@cjhyy/code-shell-core 0.7.1 → 0.8.0

package/dist/panel-apps/registry.js

@@ -0,0 +1,99 @@
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { z } from "zod";
+import { panelAppsRegistryPath } from "./paths.js";
+import { lock } from "../utils/lockfile.js";
+const GitSource = z
+    .object({
+    kind: z.literal("git"),
+    url: z.string().url().max(4_096),
+    ref: z.string().min(1).max(255).optional(),
+    subdir: z.string().min(1).max(1_024).optional(),
+})
+    .strict();
+const RegistryEntry = z
+    .object({
+    id: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/),
+    version: z.string().min(1).max(80),
+    source: z.union([z.string().min(1).max(4_096), GitSource]),
+    installedAt: z.string().min(1).max(128),
+    lastUpdated: z.string().min(1).max(128),
+})
+    .strict();
+const Registry = z
+    .object({
+    version: z.literal(1),
+    apps: z.array(RegistryEntry).max(1_024),
+})
+    .strict();
+async function readRegistryUnlocked() {
+    const path = panelAppsRegistryPath();
+    if (!existsSync(path))
+        return [];
+    try {
+        return Registry.parse(JSON.parse(await readFile(path, "utf-8"))).apps;
+    }
+    catch {
+        return [];
+    }
+}
+async function writeRegistryUnlocked(apps) {
+    const path = panelAppsRegistryPath();
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        const registry = Registry.parse({
+            version: 1,
+            apps: [...apps].sort((left, right) => left.id.localeCompare(right.id)),
+        });
+        await writeFile(tmp, `${JSON.stringify(registry, null, 2)}\n`, {
+            encoding: "utf-8",
+            flag: "wx",
+            mode: 0o600,
+        });
+        await rename(tmp, path);
+    }
+    finally {
+        await rm(tmp, { force: true });
+    }
+}
+async function mutateRegistry(mutation) {
+    const directory = dirname(panelAppsRegistryPath());
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const release = await lock(directory, {
+        realpath: true,
+        stale: 10_000,
+        retries: { retries: 8, minTimeout: 10, maxTimeout: 120, factor: 1.5 },
+    });
+    try {
+        const next = mutation(await readRegistryUnlocked());
+        await writeRegistryUnlocked(next.apps);
+        return next.result;
+    }
+    finally {
+        await release();
+    }
+}
+export async function readInstalledPanelAppsRegistry() {
+    return readRegistryUnlocked();
+}
+export async function writeInstalledPanelAppsRegistry(apps) {
+    await mutateRegistry(() => ({ apps, result: undefined }));
+}
+export async function upsertInstalledPanelAppRecord(record) {
+    await mutateRegistry((current) => ({
+        apps: [
+            ...current.filter((candidate) => candidate.id !== record.id),
+            RegistryEntry.parse(record),
+        ],
+        result: undefined,
+    }));
+}
+export async function removeInstalledPanelAppRecord(id) {
+    await mutateRegistry((current) => ({
+        apps: current.filter((candidate) => candidate.id !== id),
+        result: undefined,
+    }));
+}

package/dist/panel-apps/runtime.d.ts

@@ -0,0 +1,80 @@
+/**
+ * UI-agnostic lifecycle runtime for trusted, code-backed Panel App modules.
+ *
+ * A host supplies its own service object and panel context. Core owns ordering,
+ * instance identity, and error isolation; it does not import React/Electron or
+ * decide how an untrusted installed Panel App is sandboxed.
+ */
+export type PanelAppLifecycleEventName = "activate" | "panel_mount" | "panel_context_changed" | "panel_visibility_changed" | "panel_unmount" | "deactivate";
+export interface PanelAppInstance<TContext extends object = Record<string, unknown>> {
+    panelId: string;
+    instanceId: string;
+    context: TContext;
+    visible: boolean;
+}
+export type PanelAppLifecycleEvent<TContext extends object = Record<string, unknown>> = {
+    type: "activate";
+} | {
+    type: "panel_mount";
+    panel: PanelAppInstance<TContext>;
+} | {
+    type: "panel_context_changed";
+    panel: PanelAppInstance<TContext>;
+} | {
+    type: "panel_visibility_changed";
+    panel: PanelAppInstance<TContext>;
+} | {
+    type: "panel_unmount";
+    panel: PanelAppInstance<TContext>;
+} | {
+    type: "deactivate";
+};
+export interface PanelAppLifecycleHookContext<THost, TContext extends object = Record<string, unknown>> {
+    appId: string;
+    host: THost;
+    event: PanelAppLifecycleEvent<TContext>;
+}
+export type PanelAppLifecycleHook<THost, TContext extends object = Record<string, unknown>> = (context: PanelAppLifecycleHookContext<THost, TContext>) => void | Promise<void>;
+export type PanelAppLifecycleHooks<THost, TContext extends object = Record<string, unknown>> = Partial<Record<PanelAppLifecycleEventName, PanelAppLifecycleHook<THost, TContext> | readonly PanelAppLifecycleHook<THost, TContext>[]>>;
+/** Trusted code module. Installed web content must not be imported through this boundary. */
+export interface PanelAppLifecycleModule<THost, TContext extends object = Record<string, unknown>> {
+    id: string;
+    hooks?: PanelAppLifecycleHooks<THost, TContext>;
+}
+export interface PanelAppLifecycleError<THost, TContext extends object = Record<string, unknown>> {
+    appId: string;
+    event: PanelAppLifecycleEvent<TContext>;
+    host: THost;
+    error: unknown;
+}
+export interface PanelAppLifecycleRuntimeOptions<THost, TContext extends object = Record<string, unknown>> {
+    onError?(error: PanelAppLifecycleError<THost, TContext>): void;
+}
+/**
+ * Stateful lifecycle coordinator shared by headless and UI hosts.
+ *
+ * Mounting the first panel activates its module automatically. State changes
+ * are recorded before hooks run, so re-entrant/StrictMode calls remain
+ * idempotent even when a hook is asynchronous.
+ */
+export declare class PanelAppLifecycleRuntime<THost, TContext extends object = Record<string, unknown>> {
+    private readonly options;
+    private readonly modules;
+    private readonly active;
+    private readonly panels;
+    constructor(options?: PanelAppLifecycleRuntimeOptions<THost, TContext>);
+    register(module: PanelAppLifecycleModule<THost, TContext>): () => void;
+    has(appId: string): boolean;
+    isActive(appId: string): boolean;
+    mountedPanels(appId?: string): PanelAppInstance<TContext>[];
+    activate(appId: string, host: THost): Promise<void>;
+    mountPanel(appId: string, panel: PanelAppInstance<TContext>, host: THost): Promise<void>;
+    updatePanelContext(appId: string, instanceId: string, context: TContext, host: THost): Promise<void>;
+    setPanelVisibility(appId: string, instanceId: string, visible: boolean, host: THost): Promise<void>;
+    unmountPanel(appId: string, instanceId: string, host: THost): Promise<void>;
+    deactivate(appId: string, host: THost): Promise<void>;
+    private hasMountedPanels;
+    private requireModule;
+    private requirePanel;
+    private emit;
+}

package/dist/panel-apps/runtime.js

@@ -0,0 +1,154 @@
+/**
+ * UI-agnostic lifecycle runtime for trusted, code-backed Panel App modules.
+ *
+ * A host supplies its own service object and panel context. Core owns ordering,
+ * instance identity, and error isolation; it does not import React/Electron or
+ * decide how an untrusted installed Panel App is sandboxed.
+ */
+function panelKey(appId, instanceId) {
+    return `${appId}\0${instanceId}`;
+}
+function clonePanel(panel) {
+    return { ...panel, context: { ...panel.context } };
+}
+/**
+ * Stateful lifecycle coordinator shared by headless and UI hosts.
+ *
+ * Mounting the first panel activates its module automatically. State changes
+ * are recorded before hooks run, so re-entrant/StrictMode calls remain
+ * idempotent even when a hook is asynchronous.
+ */
+export class PanelAppLifecycleRuntime {
+    options;
+    modules = new Map();
+    active = new Set();
+    panels = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    register(module) {
+        if (!module.id)
+            throw new Error("Panel App lifecycle module id is required");
+        if (this.modules.has(module.id)) {
+            throw new Error(`Panel App lifecycle module '${module.id}' is already registered`);
+        }
+        this.modules.set(module.id, module);
+        let disposed = false;
+        return () => {
+            if (disposed)
+                return;
+            if (this.active.has(module.id) || this.hasMountedPanels(module.id)) {
+                throw new Error(`Panel App lifecycle module '${module.id}' must be deactivated first`);
+            }
+            disposed = true;
+            if (this.modules.get(module.id) === module)
+                this.modules.delete(module.id);
+        };
+    }
+    has(appId) {
+        return this.modules.has(appId);
+    }
+    isActive(appId) {
+        return this.active.has(appId);
+    }
+    mountedPanels(appId) {
+        const prefix = appId === undefined ? null : `${appId}\0`;
+        return [...this.panels.entries()]
+            .filter(([key]) => prefix === null || key.startsWith(prefix))
+            .map(([, panel]) => clonePanel(panel));
+    }
+    async activate(appId, host) {
+        this.requireModule(appId);
+        if (this.active.has(appId))
+            return;
+        this.active.add(appId);
+        await this.emit(appId, host, { type: "activate" });
+    }
+    async mountPanel(appId, panel, host) {
+        this.requireModule(appId);
+        const key = panelKey(appId, panel.instanceId);
+        if (this.panels.has(key))
+            return;
+        const snapshot = clonePanel(panel);
+        this.panels.set(key, snapshot);
+        await this.activate(appId, host);
+        // A host can unmount/remount while an async activate hook is pending. Only
+        // the generation that installed this snapshot may publish its mount event.
+        if (this.panels.get(key) !== snapshot)
+            return;
+        await this.emit(appId, host, { type: "panel_mount", panel: clonePanel(snapshot) });
+    }
+    async updatePanelContext(appId, instanceId, context, host) {
+        const current = this.requirePanel(appId, instanceId);
+        const next = { ...current, context: { ...context } };
+        this.panels.set(panelKey(appId, instanceId), next);
+        await this.emit(appId, host, {
+            type: "panel_context_changed",
+            panel: clonePanel(next),
+        });
+    }
+    async setPanelVisibility(appId, instanceId, visible, host) {
+        const current = this.requirePanel(appId, instanceId);
+        if (current.visible === visible)
+            return;
+        const next = { ...current, visible };
+        this.panels.set(panelKey(appId, instanceId), next);
+        await this.emit(appId, host, {
+            type: "panel_visibility_changed",
+            panel: clonePanel(next),
+        });
+    }
+    async unmountPanel(appId, instanceId, host) {
+        const key = panelKey(appId, instanceId);
+        const current = this.panels.get(key);
+        if (!current)
+            return;
+        this.panels.delete(key);
+        await this.emit(appId, host, {
+            type: "panel_unmount",
+            panel: clonePanel(current),
+        });
+    }
+    async deactivate(appId, host) {
+        this.requireModule(appId);
+        for (const panel of this.mountedPanels(appId)) {
+            await this.unmountPanel(appId, panel.instanceId, host);
+        }
+        if (!this.active.delete(appId))
+            return;
+        await this.emit(appId, host, { type: "deactivate" });
+    }
+    hasMountedPanels(appId) {
+        const prefix = `${appId}\0`;
+        for (const key of this.panels.keys()) {
+            if (key.startsWith(prefix))
+                return true;
+        }
+        return false;
+    }
+    requireModule(appId) {
+        const module = this.modules.get(appId);
+        if (!module)
+            throw new Error(`unknown Panel App lifecycle module '${appId}'`);
+        return module;
+    }
+    requirePanel(appId, instanceId) {
+        const panel = this.panels.get(panelKey(appId, instanceId));
+        if (!panel) {
+            throw new Error(`Panel App instance '${appId}:${instanceId}' is not mounted`);
+        }
+        return panel;
+    }
+    async emit(appId, host, event) {
+        const configured = this.requireModule(appId).hooks?.[event.type];
+        const hooks = configured ? (Array.isArray(configured) ? configured : [configured]) : [];
+        for (const hook of hooks) {
+            try {
+                await hook({ appId, host, event });
+            }
+            catch (error) {
+                this.options.onError?.({ appId, event, host, error });
+            }
+        }
+    }
+}

package/dist/plugins/gitOps.js

@@ -63,6 +63,10 @@ async function runGit(args, cwd, timeoutMs = 60_000) {
         cwd: cwd ?? process.cwd(),
         env: nonInteractiveGitEnv(process.env),
         timeoutMs,
+        // A stalled git clone/fetch owns helpers such as git-remote-https. Keep
+        // them in a dedicated group so the timeout cannot leave network workers
+        // running after the UI operation has failed.
+        processGroup: process.platform !== "win32",
     });
     if (r.spawnFailed) {
         return { ok: false, error: `git ${args.join(" ")} failed: ${r.error ?? "spawn failed"}` };
@@ -164,7 +168,10 @@ export async function gitLsRemote(url, ref) {
         return r;
     const sha = r.stdout.split(/\s+/)[0] ?? "";
     if (!/^[0-9a-f]{7,40}$/i.test(sha)) {
-        return { ok: false, error: `ls-remote: no sha for ${ref ?? "HEAD"} in: ${r.stdout.slice(0, 120)}` };
+        return {
+            ok: false,
+            error: `ls-remote: no sha for ${ref ?? "HEAD"} in: ${r.stdout.slice(0, 120)}`,
+        };
     }
     return { ok: true, stdout: sha };
 }

package/dist/plugins/installedPlugins.d.ts

@@ -1,6 +1,7 @@
 /**
  * Read/write ~/.code-shell/plugins/installed_plugins.json (V2 format).
- * Byte-compatible with Claude Code's analogous file.
+ * Reads the Claude Code-compatible V2 shape plus optional CodeShell integrity
+ * fields on each install entry.
  */
 import type { InstalledPluginsV2, PluginInstallEntry } from "./types.js";
 export declare function installedPluginsPath(): string;

package/dist/plugins/installedPlugins.js

@@ -1,26 +1,153 @@
 /**
  * Read/write ~/.code-shell/plugins/installed_plugins.json (V2 format).
- * Byte-compatible with Claude Code's analogous file.
+ * Reads the Claude Code-compatible V2 shape plus optional CodeShell integrity
+ * fields on each install entry.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
+const MAX_PLUGIN_KEYS = 2_048;
+const MAX_INSTALLS_PER_KEY = 16;
+const MAX_KEY_LENGTH = 256;
+const MAX_PATH_LENGTH = 4_096;
+const MAX_METADATA_LENGTH = 512;
+const DIGEST_RE = /^[a-f0-9]{64}$/;
+const MAX_HOOK_REVIEW_ITEMS = 256;
+const MAX_HOOK_REVIEW_COMMAND_LENGTH = 4_096;
+const MAX_HOOK_REVIEW_MATCHER_LENGTH = 4_096;
 function userHome() {
     return process.env.HOME ?? homedir();
 }
 export function installedPluginsPath() {
     return join(userHome(), ".code-shell", "plugins", "installed_plugins.json");
 }
-const EMPTY = { version: 2, plugins: {} };
+function recordOf(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function boundedString(value, maxLength) {
+    return typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= maxLength &&
+        !value.includes("\0")
+        ? value
+        : undefined;
+}
+function hookReviewItemOf(value) {
+    const raw = recordOf(value);
+    if (!raw)
+        return undefined;
+    const rawEvent = boundedString(raw.rawEvent, 128);
+    const command = boundedString(raw.command, MAX_HOOK_REVIEW_COMMAND_LENGTH);
+    const commandDigest = typeof raw.commandDigest === "string" && DIGEST_RE.test(raw.commandDigest)
+        ? raw.commandDigest
+        : undefined;
+    if (!rawEvent || !command || !commandDigest)
+        return undefined;
+    const matcher = raw.matcher === undefined
+        ? undefined
+        : boundedString(raw.matcher, MAX_HOOK_REVIEW_MATCHER_LENGTH);
+    if (raw.matcher !== undefined && matcher === undefined)
+        return undefined;
+    if (raw.commandTruncated !== undefined && typeof raw.commandTruncated !== "boolean") {
+        return undefined;
+    }
+    if (raw.async !== undefined && typeof raw.async !== "boolean")
+        return undefined;
+    const timeoutMs = raw.timeoutMs === undefined ||
+        (typeof raw.timeoutMs === "number" &&
+            Number.isSafeInteger(raw.timeoutMs) &&
+            raw.timeoutMs >= 1 &&
+            raw.timeoutMs <= 600_000)
+        ? raw.timeoutMs
+        : null;
+    if (timeoutMs === null)
+        return undefined;
+    return {
+        rawEvent,
+        ...(matcher === undefined ? {} : { matcher }),
+        command,
+        commandDigest,
+        ...(raw.commandTruncated === true ? { commandTruncated: true } : {}),
+        ...(raw.async === undefined ? {} : { async: raw.async }),
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+    };
+}
+function installEntryOf(value) {
+    const raw = recordOf(value);
+    if (!raw || raw.scope !== "user")
+        return undefined;
+    const installPath = boundedString(raw.installPath, MAX_PATH_LENGTH);
+    const version = boundedString(raw.version, MAX_METADATA_LENGTH);
+    const installedAt = boundedString(raw.installedAt, MAX_METADATA_LENGTH);
+    const lastUpdated = boundedString(raw.lastUpdated, MAX_METADATA_LENGTH);
+    if (!installPath || !version || !installedAt || !lastUpdated)
+        return undefined;
+    const entry = {
+        scope: "user",
+        installPath,
+        version,
+        installedAt,
+        lastUpdated,
+    };
+    const gitCommitSha = boundedString(raw.gitCommitSha, MAX_METADATA_LENGTH);
+    if (gitCommitSha)
+        entry.gitCommitSha = gitCommitSha;
+    for (const field of [
+        "hookDigest",
+        "approvedHookDigest",
+        "mcpDigest",
+        "approvedMcpDigest",
+    ]) {
+        const digest = raw[field];
+        if (typeof digest === "string" && DIGEST_RE.test(digest))
+            entry[field] = digest;
+    }
+    if (Array.isArray(raw.approvedHookSnapshot) &&
+        raw.approvedHookSnapshot.length <= MAX_HOOK_REVIEW_ITEMS) {
+        const snapshot = raw.approvedHookSnapshot
+            .map((item) => hookReviewItemOf(item))
+            .filter((item) => item !== undefined);
+        if (snapshot.length === raw.approvedHookSnapshot.length)
+            entry.approvedHookSnapshot = snapshot;
+    }
+    return entry;
+}
+function registryOf(value) {
+    const raw = recordOf(value);
+    const plugins = recordOf(raw?.plugins);
+    if (raw?.version !== 2 || !plugins)
+        return undefined;
+    const entries = Object.entries(plugins);
+    if (entries.length > MAX_PLUGIN_KEYS)
+        return undefined;
+    const normalized = { version: 2, plugins: {} };
+    for (const [key, value] of entries) {
+        if (key.length === 0 ||
+            key.length > MAX_KEY_LENGTH ||
+            key.includes("\0") ||
+            !Array.isArray(value) ||
+            value.length > MAX_INSTALLS_PER_KEY) {
+            continue;
+        }
+        const installs = value
+            .map((entry) => installEntryOf(entry))
+            .filter((entry) => entry !== undefined);
+        if (installs.length > 0)
+            normalized.plugins[key] = installs;
+    }
+    return normalized;
+}
 export function readInstalledPlugins() {
     const path = installedPluginsPath();
     if (!existsSync(path))
         return { version: 2, plugins: {} };
     try {
-        const raw = JSON.parse(readFileSync(path, "utf-8"));
-        if (raw && typeof raw === "object" && raw.version === 2 && raw.plugins && typeof raw.plugins === "object") {
-            return raw;
-        }
+        const parsed = registryOf(JSON.parse(readFileSync(path, "utf-8")));
+        if (parsed)
+            return parsed;
     }
     catch {
         // Corrupt — treat as empty so the user can re-install.
@@ -30,7 +157,18 @@ export function readInstalledPlugins() {
 export function writeInstalledPlugins(data) {
     const path = installedPluginsPath();
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+    const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", {
+            encoding: "utf-8",
+            flag: "wx",
+            mode: 0o600,
+        });
+        renameSync(tmp, path);
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
 }
 /**
  * Append an install entry for `<plugin>@<marketplace>`. Multiple entries

package/dist/plugins/installer/codex/convertAgents.d.ts

@@ -1,7 +1,10 @@
 /**
  * Convert one Codex agent TOML into a CC agent Markdown string.
- * Real CC fields: name, description, model, body(=developer_instructions).
+ * Real CodeShell fields: name, description, model, MCP allowlist and
+ * body(=developer_instructions).
  * Every other field is preserved with a `codex_` prefix (v1 inert; see spec §7.1).
  * `mcp_servers` values are rewritten to `<plugin>:<server>` to match the MCP merge key.
  */
 export declare function convertCodexAgentToml(toml: string, sourceName: string, pluginName: string): string;
+/** Walk <sourceDir>/agents/**.toml → <destDir>/agents/**.md. */
+export declare function convertCodexAgentsDirectory(sourceDir: string, destDir: string, pluginName: string): Promise<void>;

package/dist/plugins/installer/codex/convertAgents.js

@@ -1,11 +1,15 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, readdir, realpath, stat, writeFile } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
 import { parse as parseToml } from "smol-toml";
 import { stringify as stringifyYaml } from "yaml";
 import { serializeAgentDefinition } from "../../../agent/agent-definition.js";
 import { PluginInstallError } from "../types.js";
-const MAPPED = new Set(["name", "description", "model", "developer_instructions"]);
+const MAPPED = new Set(["name", "description", "model", "developer_instructions", "mcp_servers"]);
 /**
  * Convert one Codex agent TOML into a CC agent Markdown string.
- * Real CC fields: name, description, model, body(=developer_instructions).
+ * Real CodeShell fields: name, description, model, MCP allowlist and
+ * body(=developer_instructions).
  * Every other field is preserved with a `codex_` prefix (v1 inert; see spec §7.1).
  * `mcp_servers` values are rewritten to `<plugin>:<server>` to match the MCP merge key.
  */
@@ -24,11 +28,24 @@ export function convertCodexAgentToml(toml, sourceName, pluginName) {
         throw new PluginInstallError(`${sourceName}: missing required 'description'`);
     }
     const body = typeof raw.developer_instructions === "string" ? raw.developer_instructions.trim() : "";
+    let mcp;
+    if (raw.mcp_servers !== undefined) {
+        if (!Array.isArray(raw.mcp_servers) ||
+            raw.mcp_servers.length > 256 ||
+            raw.mcp_servers.some((server) => typeof server !== "string" ||
+                server.length === 0 ||
+                server.length > 256 ||
+                !/^[A-Za-z0-9._-]+$/u.test(server))) {
+            throw new PluginInstallError(`${sourceName}: 'mcp_servers' must be an array of at most 256 safe server names`);
+        }
+        mcp = [...new Set(raw.mcp_servers.map((server) => `${pluginName}:${server}`))];
+    }
     const base = serializeAgentDefinition({
         name: raw.name.trim(),
         description: raw.description.trim(),
         systemPrompt: body,
         ...(typeof raw.model === "string" && raw.model.trim() ? { model: raw.model.trim() } : {}),
+        ...(mcp !== undefined ? { mcp } : {}),
     });
     // Collect codex_-prefixed extras.
     const extras = {};
@@ -36,12 +53,7 @@ export function convertCodexAgentToml(toml, sourceName, pluginName) {
         if (MAPPED.has(key))
             continue;
         const outKey = `codex_${key}`;
-        if (key === "mcp_servers" && Array.isArray(value)) {
-            extras[outKey] = value.map((s) => (typeof s === "string" ? `${pluginName}:${s}` : s));
-        }
-        else {
-            extras[outKey] = value;
-        }
+        extras[outKey] = value;
     }
     if (Object.keys(extras).length === 0)
         return base;
@@ -53,3 +65,45 @@ export function convertCodexAgentToml(toml, sourceName, pluginName) {
     const [, fm, rest] = match;
     return `---\n${fm}\n${extraYaml}\n---\n${rest}`;
 }
+/** Walk <sourceDir>/agents/**.toml → <destDir>/agents/**.md. */
+export async function convertCodexAgentsDirectory(sourceDir, destDir, pluginName) {
+    const agentsSrc = join(sourceDir, "agents");
+    if (!existsSync(agentsSrc))
+        return;
+    const sourceRoot = await realpath(sourceDir);
+    const resolvedAgentsRoot = await resolveContainedAgentSource(sourceRoot, agentsSrc, "agents");
+    const walk = async (dir) => {
+        for (const dirent of await readdir(dir, { withFileTypes: true })) {
+            const abs = join(dir, dirent.name);
+            if (dirent.isDirectory()) {
+                await walk(abs);
+                continue;
+            }
+            if (!dirent.name.endsWith(".toml"))
+                continue;
+            const source = await resolveContainedAgentSource(resolvedAgentsRoot, abs, relative(resolvedAgentsRoot, abs));
+            if (!(await stat(source)).isFile())
+                continue;
+            const rel = relative(resolvedAgentsRoot, abs).replace(/\.toml$/, ".md");
+            const outPath = join(destDir, "agents", rel);
+            await mkdir(join(outPath, ".."), { recursive: true });
+            const markdown = convertCodexAgentToml(await readFile(source, "utf-8"), rel, pluginName);
+            await writeFile(outPath, markdown);
+        }
+    };
+    await walk(resolvedAgentsRoot);
+}
+async function resolveContainedAgentSource(sourceRoot, candidate, label) {
+    let target;
+    try {
+        target = await realpath(candidate);
+    }
+    catch {
+        throw new PluginInstallError(`agent source not found: ${label}`);
+    }
+    const rel = relative(sourceRoot, target);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new PluginInstallError(`agent source escapes plugin dir: ${label}`);
+    }
+    return target;
+}

package/dist/plugins/installer/codex/convertCommands.d.ts

@@ -7,11 +7,11 @@
  * already scans `commands/*.md`. So the conversion is a flat copy of every
  * `.md` from `prompts/` (and any explicit `commands/`) into `dest/commands/`.
  *
- * Placeholder syntax differs (Codex `$1`/`$FILE` vs CC `$ARGUMENTS`) but the
- * body is copied verbatim — v1 inert, the same stance taken for `codex_`
- * agent fields (see convertAgents.ts). Non-`.md` files are ignored, matching
- * Codex's own behaviour. On a filename collision an explicit `commands/`
- * entry wins over `prompts/` (the more specific source).
+ * Placeholder syntax differs (Codex `$1`/`$FILE` vs CC `$ARGUMENTS`), so the
+ * body is copied verbatim and expanded at invocation time by
+ * `expandPluginCommandBody`. Non-`.md` files are ignored, matching Codex's
+ * own behaviour. On a filename collision an explicit `commands/` entry wins
+ * over `prompts/` (the more specific source).
  *
  * Async fs throughout: this runs in the Electron main process during install;
  * sync copies block the event loop and freeze the UI (see convertSkills.ts).