Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import type {
CapabilityRouteOverride,
CapabilityRoutingPolicy,
} from '../../types/capability-routing.js';
import type { BotRuntimeMcpPolicy, BotRuntimeSkillPolicy } from '../base-agent.js';
import { canonicalSkillPath } from '../shared/skill-activation.js';
import { isBotMcpServerAllowed } from '../shared/bot-runtime-policy.js';
const CODEX_HARNESS_ID = 'codex';
interface CodexSkillState {
path: string;
enabled: boolean;
}
/** Build Codex's native per-thread Skill config for a Bot allowlist. */
export function buildCodexBotSkillConfigOverrides(
policy: BotRuntimeSkillPolicy | undefined,
refreshed?: { skills: readonly { path: string; enabled?: boolean }[]; grants: ReadonlySet<string> },
): Record<string, unknown> {
if (!policy) return {};
const byPath = new Map<string, { path: string; enabled: boolean }>();
const allowed = policy.mode === 'allowlist'
? new Set(policy.configured.map((item) => item.trim()))
: new Set<string>();
for (const item of policy.catalog) {
const skillPath = item.path?.trim();
if (!skillPath) continue;
const runtimeName = item.runtimeCommandName?.trim();
byPath.set(skillPath, {
path: skillPath,
enabled: item.enabled !== false && item.runtimeStatus !== 'failed' &&
(!refreshed || refreshed.grants.has(canonicalSkillPath(skillPath))) &&
(allowed.has(item.name.trim()) || (!!runtimeName && allowed.has(runtimeName))),
});
}
// The refreshed native catalog can contain skills absent from the Bot's
// earlier catalog. Grant by frozen physical identity, never by a new name.
for (const item of refreshed?.skills ?? []) {
byPath.set(item.path, {
path: item.path,
enabled: item.enabled !== false && refreshed!.grants.has(canonicalSkillPath(item.path)),
});
}
// Cindy-owned Bot Skills are outside the ambient allowlist. Codex has no
// plugin-root mount equivalent, so project them as explicit per-thread Skill
// paths and let them win any accidental same-path ambient entry.
for (const item of policy.ownSkills ?? []) {
const skillPath = item.filePath?.trim() || item.path?.trim();
if (!skillPath) continue;
byPath.set(skillPath, { path: skillPath, enabled: true });
}
return byPath.size > 0
? { 'skills.config': [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path)) }
: {};
}
export function mergeCodexSkillConfigOverrides(
base: Record<string, unknown>,
overlay: Record<string, unknown>,
): Record<string, unknown> {
const merged = { ...base, ...overlay };
const entries = new Map<string, { path: string; enabled: boolean }>();
for (const source of [base['skills.config'], overlay['skills.config']]) {
if (!Array.isArray(source)) continue;
for (const raw of source) {
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) continue;
const item = raw as { path?: unknown; enabled?: unknown };
if (typeof item.path !== 'string' || typeof item.enabled !== 'boolean') continue;
const previous = entries.get(item.path);
entries.set(item.path, {
path: item.path,
enabled: (previous?.enabled ?? true) && item.enabled,
});
}
}
if (entries.size > 0) {
merged['skills.config'] = [...entries.values()].sort((a, b) => a.path.localeCompare(b.path));
}
return merged;
}
/** Disable every non-essential MCP server through Codex's native thread config. */
export function buildCodexBotMcpConfigOverrides(
policy: BotRuntimeMcpPolicy | undefined,
transportServerNames: ReadonlySet<string>,
): Record<string, unknown> {
if (!policy || policy.mode !== 'allowlist') return {};
const result: Record<string, unknown> = {};
// Apps is a native server without command/url. A disabled-only MCP entry is
// invalid in Codex; use its feature switch, and never force-enable an account feature.
if (!isBotMcpServerAllowed(policy, 'codex_apps')) result['features.apps'] = false;
// Codex parses transport before enabled. Never synthesize disabled-only
// entries for absent servers: even `enabled=false` makes thread/start fail.
for (const name of transportServerNames) {
// Native Apps has no transport. A real transport with the same name must
// still obey the allowlist (including configs inherited from CODEX_HOME).
const restricted = ['cindy_group_history', 'cindy_orca'].includes(name);
if (!restricted && isBotMcpServerAllowed(policy, name)) continue;
result[`mcp_servers.${renderThreadConfigKeySegment(name)}.enabled`] = false;
}
return result;
}
interface CodexPluginCacheIdentity {
pluginName: string;
marketplace: string;
}
interface CodexSkillDisableTarget {
plugin: CodexPluginCacheIdentity;
/** Undefined means every Skill contributed by the plugin. */
skillArtifactId?: string;
}
export interface CodexCapabilityRoutingOptions {
/**
* Whether the host prepared a provenance-preserving plugin overlay for this
* Codex home.
*
* Local Cindy sessions have one. Remote Codex runs from a separate isolated
* CODEX_HOME, so until the host synchronizes the overlay there we must disable
* an explicit-only downstream plugin as a whole instead of pretending its
* renamed MCP and non-implicit Skill are available.
*/
isolatedPluginOverlays?: boolean;
}
export interface CodexSessionCapabilityRoutingOptions {
/** Whether this Codex host can invoke replacements served by Cindy itself. */
cindyHostReplacementsAvailable: boolean;
}
/**
* Codex thread config accepts flattened TOML paths. Plugin config names contain
* `@`, so they must be rendered as quoted dotted-key segments.
*/
function quoteTomlKeySegment(value: string): string {
return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
}
function renderThreadConfigKeySegment(value: string): string {
// app-server's thread config takes flattened paths, but unlike CLI `-c` it
// does not parse quotes around a bare-safe segment. Quoting `node_repl`
// therefore addresses a literal `"node_repl"` server and makes transport
// resolution fail. Keep quoting only for names that TOML cannot render bare.
return /^[A-Za-z0-9_-]+$/.test(value) ? value : quoteTomlKeySegment(value);
}
function isCodexHarnessPluginDirective(
directive: CapabilityRouteOverride,
): boolean {
return (
directive.source.kind === 'harness-plugin' &&
directive.source.harness === CODEX_HARNESS_ID
);
}
function isDisabledCodexSkillSourceDirective(
directive: CapabilityRouteOverride,
): boolean {
return (
isCodexHarnessPluginDirective(directive) &&
(directive.source.surface === 'plugin' ||
directive.source.surface === 'skill') &&
directive.invocation === 'disabled'
);
}
function parseCodexPluginCacheIdentity(
pluginId: string,
): CodexPluginCacheIdentity | null {
const separator = pluginId.lastIndexOf('@');
if (separator <= 0 || separator === pluginId.length - 1) return null;
return {
pluginName: pluginId.slice(0, separator),
marketplace: pluginId.slice(separator + 1),
};
}
function isSkillFromPluginDistribution(
skillPath: string,
target: CodexSkillDisableTarget,
): boolean {
const segments = skillPath.replace(/\\/g, '/').split('/');
for (let index = 0; index < segments.length; index += 1) {
if (
index + 6 < segments.length &&
segments[index] === 'plugins' &&
segments[index + 1] === 'cache' &&
segments[index + 2] === target.plugin.marketplace &&
segments[index + 3] === target.plugin.pluginName &&
segments[index + 4] !== '' &&
segments[index + 5] === 'skills' &&
(target.skillArtifactId === undefined ||
segments[index + 6] === target.skillArtifactId)
) {
return true;
}
const bundledMarketplace = segments[index + 1];
if (
index + 5 < segments.length &&
segments[index] === 'bundled-marketplaces' &&
(bundledMarketplace === target.plugin.marketplace ||
bundledMarketplace?.startsWith(
`${target.plugin.marketplace}.staging-`,
)) &&
segments[index + 2] === 'plugins' &&
segments[index + 3] === target.plugin.pluginName &&
segments[index + 4] === 'skills' &&
(target.skillArtifactId === undefined ||
segments[index + 5] === target.skillArtifactId)
) {
return true;
}
}
return false;
}
function hasCodexPluginIdentity(pluginId: string | undefined): boolean {
return !!pluginId && parseCodexPluginCacheIdentity(pluginId) !== null;
}
/**
* The Skill catalog target hidden by a disabled Codex plugin or Skill route.
* Throws when the route lacks the plugin identity Codex needs to find it.
*/
function codexSkillDisableTarget(
directive: CapabilityRouteOverride,
): CodexSkillDisableTarget {
const pluginId = directive.source.surface === 'plugin'
? directive.source.id
: directive.source.containerId;
if (!pluginId) {
const requiredField = directive.source.surface === 'plugin'
? 'source.id'
: 'source.containerId';
throw new Error(
`Cannot disable Codex Skill ${directive.source.id}: ${requiredField} is required`,
);
}
const plugin = parseCodexPluginCacheIdentity(pluginId);
if (!plugin) {
throw new Error(
`Cannot enforce disabled Codex Skill routing for ${directive.source.id}: expected plugin id in <name>@<marketplace> form`,
);
}
const skillArtifactId = directive.source.surface === 'skill'
? directive.source.artifactId
: undefined;
if (directive.source.surface === 'skill' && !skillArtifactId) {
throw new Error(
`Cannot disable Codex Skill ${directive.source.id}: source.artifactId is required`,
);
}
return {
plugin,
...(skillArtifactId ? { skillArtifactId } : {}),
};
}
/**
* Whether the desktop's provenance-preserving plugin overlay narrows this
* explicit-only route locally. The overlay builder selects routes through this
* same predicate.
*/
export function isCodexExplicitOnlyOverlayRoute(
directive: CapabilityRouteOverride,
): boolean {
if (
!isCodexHarnessPluginDirective(directive) ||
directive.invocation !== 'explicit-only' ||
!hasCodexPluginIdentity(directive.source.containerId)
) {
return false;
}
const { surface, id, artifactId } = directive.source;
return surface === 'skill' ||
(surface === 'mcp' && !!artifactId && artifactId !== id);
}
/**
* Whether Codex enforces a host route. Built from the same helpers the Skill
* config builder and the desktop overlay use, so the route support check
* cannot drift from what a session actually applies.
*/
export function isCodexCapabilityRouteEnforced(
directive: CapabilityRouteOverride,
): boolean {
if (isDisabledCodexSkillSourceDirective(directive)) {
try {
codexSkillDisableTarget(directive);
return true;
} catch {
return false;
}
}
if (
isCodexHarnessPluginDirective(directive) &&
directive.invocation === 'disabled'
) {
return directive.source.surface === 'mcp';
}
return isCodexExplicitOnlyOverlayRoute(directive);
}
/**
* Remove replacement-arbitration routes that the selected Codex host cannot
* satisfy. Compatibility-only restrictions without a replacement remain in
* force, so remote sessions still hide Skills that depend on unavailable APIs.
*/
export function buildCodexSessionCapabilityRoutingPolicy(
policy: CapabilityRoutingPolicy | undefined,
opts: CodexSessionCapabilityRoutingOptions,
): CapabilityRoutingPolicy | undefined {
if (opts.cindyHostReplacementsAvailable || !policy) return policy;
const overrides = policy.overrides.filter(
(directive) => directive.replacement?.kind !== 'cindy-host',
);
return overrides.length === policy.overrides.length ? policy : { overrides };
}
/** Whether a session must inspect Codex's effective Skill catalog before start. */
export function requiresCodexCapabilitySkillDiscovery(
policy: CapabilityRoutingPolicy | undefined,
): boolean {
return policy?.overrides.some(isDisabledCodexSkillSourceDirective) ?? false;
}
/**
* Hide a selected plugin Skill, or every Skill from a disabled plugin.
*
* Codex 0.145 keeps plugin Skills enabled in the model-facing catalog even
* when the plugin-wide `enabled` override is false. `skills.config` is the
* supported per-Skill control. Cindy also uses the same narrow control when a
* specific downstream Skill depends on a host interface that is unavailable.
* Derive paths from app-server's own catalog rather than guessing local or
* remote homes. Existing disabled Skills in this cwd are carried forward
* because the per-thread array may replace the base array.
*/
export function buildCodexCapabilitySkillConfigOverrides(
policy: CapabilityRoutingPolicy | undefined,
skills: readonly CodexSkillState[],
): Record<string, unknown> {
const targets: CodexSkillDisableTarget[] = [];
for (const directive of policy?.overrides ?? []) {
if (!isDisabledCodexSkillSourceDirective(directive)) continue;
targets.push(codexSkillDisableTarget(directive));
}
if (targets.length === 0) return {};
const routedSkillPaths = skills
.filter((skill) =>
targets.some((target) =>
isSkillFromPluginDistribution(skill.path, target),
),
)
.map((skill) => skill.path);
if (routedSkillPaths.length === 0) return {};
const disabledPaths = new Set([
...skills.filter((skill) => !skill.enabled).map((skill) => skill.path),
...routedSkillPaths,
]);
return {
'skills.config': [...disabledPaths]
.sort()
.map((skillPath) => ({ path: skillPath, enabled: false })),
};
}
/**
* Convert host policy into per-thread Codex config overrides.
*
* Codex 0.145 exposes plugin-wide enablement but has no host-side equivalent of
* Claude's `user-invocable-only` skill override. Local explicit-only sources
* are narrowed by the provenance-preserving plugin overlay plus the approval
* guard. When that overlay is unavailable (currently remote Codex), the whole
* targeted plugin is disabled rather than silently widened.
*/
export function buildCodexCapabilityConfigOverrides(
policy: CapabilityRoutingPolicy | undefined,
opts: CodexCapabilityRoutingOptions = {},
): Record<string, unknown> {
const config: Record<string, unknown> = Object.create(null);
if (!policy) return config;
for (const directive of policy.overrides) {
if (!isCodexHarnessPluginDirective(directive)) continue;
if (
opts.isolatedPluginOverlays === false &&
directive.invocation === 'explicit-only'
) {
const pluginId =
directive.source.surface === 'plugin'
? directive.source.id
: directive.source.containerId;
if (!pluginId) {
const requiredField =
directive.source.surface === 'plugin'
? 'source.id'
: 'source.containerId';
throw new Error(
`Cannot enforce explicit-only Codex capability ${directive.capabilityId} without an isolated plugin overlay: ${requiredField} is required for ${directive.source.surface} source ${directive.source.id}`,
);
}
config[`plugins.${quoteTomlKeySegment(pluginId)}.enabled`] = false;
continue;
}
if (
directive.source.surface === 'plugin' &&
directive.invocation === 'disabled'
) {
config[`plugins.${quoteTomlKeySegment(directive.source.id)}.enabled`] =
false;
continue;
}
if (
directive.source.surface === 'mcp' &&
directive.invocation === 'disabled'
) {
config[
`mcp_servers.${renderThreadConfigKeySegment(directive.source.id)}.enabled`
] = false;
continue;
}
if (
directive.source.surface === 'mcp' &&
directive.invocation === 'explicit-only' &&
directive.source.containerId
) {
const artifactId = directive.source.artifactId;
if (artifactId && artifactId !== directive.source.id) {
// The isolated plugin overlay renames the downstream MCP server so the
// runtime approval request cannot collide with a user-owned MCP of the
// same name. Disabling the original name also makes overlay failures
// fail closed for the MCP surface.
config[
`plugins.${quoteTomlKeySegment(directive.source.containerId)}.mcp_servers.${renderThreadConfigKeySegment(artifactId)}.enabled`
] = false;
}
config[
`plugins.${quoteTomlKeySegment(directive.source.containerId)}.mcp_servers.${renderThreadConfigKeySegment(directive.source.id)}.default_tools_approval_mode`
] = 'prompt';
}
}
return config;
}