@alpacakit/agents 0.2.0-beta.2 → 0.2.0-beta.3

package/dist/agents/codex/cli.js

@@ -0,0 +1,110 @@
+/**
+ * The Codex vocabulary, spelled once: the `codex exec` flags, the app-server
+ * notification and file fields the session reads, the permission words, and
+ * the host's own file names. The run adapter (`index.ts`), the session
+ * adapter (`session.ts`), and the host plane (`host.ts`) all read from here;
+ * JSON-RPC method names and sandbox words come from `codex/protocol.ts`.
+ */
+export const CODEX_HOME_ENV_VAR = "CODEX_HOME";
+export const CODEX_API_KEY_ENV_VAR = "OPENAI_API_KEY";
+export const CODEX = {
+    id: "codex",
+    command: "codex",
+    cli: {
+        exec: "exec",
+        model: "--model",
+        config: "-c",
+        reasoningEffortConfigKey: "model_reasoning_effort",
+        json: "--json",
+        skipGitRepoCheck: "--skip-git-repo-check",
+        sandbox: "--sandbox",
+        workspace: "-C",
+    },
+    auth: {
+        // Exit-code-only login probe (E12): `codex login status` exits 0 when a
+        // credential is present, nonzero otherwise. The output format is not
+        // parsed — only the exit code decides valid/invalid, like claude's.
+        statusArgs: ["login", "status"],
+        oauthLoginArgs: ["login"],
+        deviceLoginArgs: ["login", "--device-auth"],
+    },
+    json: {
+        field: {
+            type: "type",
+            text: "text",
+            item: "item",
+        },
+        event: {
+            turnCompleted: "turn.completed",
+            agentMessage: "agent_message",
+            itemCompleted: "item.completed",
+        },
+    },
+    mcp: {
+        add: "add",
+        env: "--env",
+        executableSeparator: "--",
+        mcp: "mcp",
+        remove: "remove",
+    },
+    notification: {
+        threadId: "threadId",
+        turnId: "turnId",
+        turn: "turn",
+        item: "item",
+        id: "id",
+        type: "type",
+        text: "text",
+        status: "status",
+        items: "items",
+        phase: "phase",
+        finalAnswer: "final_answer",
+        agentMessage: "agentMessage",
+        userMessage: "userMessage",
+        reasoning: "reasoning",
+        command: "command",
+        reason: "reason",
+    },
+    turnStatus: {
+        completed: "completed",
+        interrupted: "interrupted",
+        failed: "failed",
+    },
+    decision: { accept: "accept", decline: "decline" },
+    error: {
+        archived: "is archived",
+        methodNotFound: -32601,
+        unsupported: "unsupported server request",
+    },
+    files: {
+        root: ".codex",
+        sessions: "sessions",
+        archivedSessions: "archived_sessions",
+        writerLocks: "thread-writer-locks",
+        lockExtension: ".lock",
+        rolloutExtension: ".jsonl",
+        type: "type",
+        payload: "payload",
+        sessionMeta: "session_meta",
+        turnContext: "turn_context",
+        cwd: "cwd",
+        approvalPolicy: "approval_policy",
+        approvalsReviewer: "approvals_reviewer",
+        sandboxPolicy: "sandbox_policy",
+        writableRoots: "writable_roots",
+        networkAccess: "network_access",
+        excludeTmpdirEnvVar: "exclude_tmpdir_env_var",
+        excludeSlashTmp: "exclude_slash_tmp",
+    },
+};
+/** `approval_policy` words (codex 0.153.4 `AskForApproval`; the granular object form is not modeled). */
+export const CODEX_APPROVAL_POLICY = {
+    untrusted: "untrusted",
+    onRequest: "on-request",
+    never: "never",
+};
+export const CODEX_APPROVALS_REVIEWER = {
+    user: "user",
+    autoReview: "auto_review",
+    guardianSubagent: "guardian_subagent",
+};

package/dist/agents/codex/host.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The codex host plane: auth materials and sign-in, skills and plugins
+ * through a short-lived app-server client, and MCP registration through
+ * the CLI. Outside a run and a session; every path comes from
+ * `HostContext.location`, never `os.homedir()`.
+ */
+import { type LoginCapability } from "../../auth/login.js";
+import type { MaterialHandlers } from "../../auth/material.js";
+import { type McpCapability, type SkillsCapability } from "../../host/capabilities.js";
+export declare const codexAuth: MaterialHandlers;
+export declare const codexLogin: LoginCapability;
+export declare const codexSkills: SkillsCapability;
+export declare const codexMcp: McpCapability;
+//# sourceMappingURL=host.d.ts.map

package/dist/agents/codex/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../../src/agents/codex/host.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAmB/D,OAAO,EAOL,KAAK,aAAa,EAKlB,KAAK,gBAAgB,EAEtB,MAAM,4BAA4B,CAAC;AAkOpC,eAAO,MAAM,SAAS,EAAE,gBAqBvB,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,eAKxB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,gBAKzB,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,aAMtB,CAAC"}

package/dist/agents/codex/host.js

@@ -0,0 +1,221 @@
+/**
+ * The codex host plane: auth materials and sign-in, skills and plugins
+ * through a short-lived app-server client, and MCP registration through
+ * the CLI. Outside a run and a session; every path comes from
+ * `HostContext.location`, never `os.homedir()`.
+ */
+import { LOGIN_METHOD, } from "../../auth/login.js";
+import { cliLoginProbe } from "../../auth/login-probe.js";
+import { AUTH_MATERIAL_KIND, envVarAuthMaterial } from "../../auth/material.js";
+import { requireSecret } from "../../auth/secrets.js";
+import { listAllCodexMcpServerStatuses, withCodexAppServer, } from "../../codex/app-server.js";
+import { CODEX_APP_SERVER_METHOD } from "../../codex/protocol.js";
+import { AGENT_ERROR_CODE, AgentError, AUTH_FAILURE_REASON, } from "../../core/error.js";
+import { INSTALL_STATUS, MCP_SCOPE, MCP_TRANSPORT, SKILL_SOURCE_KIND, } from "../../host/capabilities.js";
+import { runHostCommand } from "../../host/run-command.js";
+import { cliLoginCommand } from "../../kernel/cli-login.js";
+import { CODEX, CODEX_API_KEY_ENV_VAR, CODEX_HOME_ENV_VAR } from "./cli.js";
+const COMPETING_API_KEY_VARS = [CODEX_API_KEY_ENV_VAR, "CODEX_API_KEY"];
+const COMPETING_HOME_VARS = [CODEX_HOME_ENV_VAR, "CODEX_API_KEY"];
+const UNSUPPORTED_CWD_REASON = "unsupported codex stdio mcp cwd";
+const UNSUPPORTED_SCOPE_REASON_PREFIX = "unsupported codex mcp scope";
+const UNSUPPORTED_PLUGIN_OVERWRITE_REASON = "plugin install does not support overwrite";
+const CODEX_PLUGIN_AUTH_REQUIRED_MESSAGE = "Codex plugin installation requires app authorization";
+const CODEX_ALREADY_INSTALLED_STATUS = /already/i;
+const CODEX_MCP_UNUSABLE_STATUS = /failed|error|invalid|missing|required/i;
+function codexAppServerCwd(ctx) {
+    return ctx.location.projectDir ?? ctx.location.homeDir;
+}
+function codexAppServerCwds(ctx) {
+    return [codexAppServerCwd(ctx)];
+}
+async function listCodexSkills(ctx) {
+    return withCodexAppServer(codexAppServerOptions(ctx), async (client) => {
+        const result = await client.request(CODEX_APP_SERVER_METHOD.skillsList, {
+            cwds: codexAppServerCwds(ctx),
+            forceReload: true,
+        });
+        return skillsFromCodexResult(result);
+    });
+}
+async function installCodexPlugin(ctx, source, options) {
+    if (options.overwrite === true) {
+        // `plugin/install` has no overwrite semantics; refusing is honest,
+        // silently ignoring the request is not (same contract as claude).
+        throw new AgentError({
+            code: AGENT_ERROR_CODE.invalidInput,
+            classification: AgentError.agentFailure(AGENT_ERROR_CODE.invalidInput),
+            message: "Codex plugin installation cannot overwrite an installed plugin",
+            data: { reason: UNSUPPORTED_PLUGIN_OVERWRITE_REASON },
+        });
+    }
+    return withCodexAppServer(codexAppServerOptions(ctx), async (client) => {
+        const result = await client.request(CODEX_APP_SERVER_METHOD.pluginInstall, {
+            pluginName: source.name,
+            marketplacePath: null,
+            remoteMarketplaceName: null,
+        });
+        return installOutcomeFromCodexPlugin(source.name, result);
+    });
+}
+async function listCodexMcp(ctx) {
+    return withCodexAppServer(codexAppServerOptions(ctx), async (client) => (await listAllCodexMcpServerStatuses(client)).map(codexMcpState));
+}
+async function addCodexStdioMcp(ctx, name, spec, options) {
+    assertCodexStdioMcpSupported(spec, options);
+    await runHostCommand(ctx, {
+        command: CODEX.command,
+        args: [
+            CODEX.mcp.mcp,
+            CODEX.mcp.add,
+            name,
+            ...Object.entries(spec.env).flatMap(([key, value]) => [
+                CODEX.mcp.env,
+                `${key}=${value}`,
+            ]),
+            CODEX.mcp.executableSeparator,
+            spec.command,
+            ...spec.args,
+        ],
+    });
+    return {
+        status: INSTALL_STATUS.installed,
+        location: `codex:${options.scope}:${name}`,
+    };
+}
+async function removeCodexMcp(ctx, name, options) {
+    assertCodexMcpScopeSupported(options.scope);
+    await runHostCommand(ctx, {
+        command: CODEX.command,
+        args: [CODEX.mcp.mcp, CODEX.mcp.remove, name],
+    });
+}
+function assertCodexStdioMcpSupported(spec, options) {
+    assertCodexMcpScopeSupported(options.scope);
+    if (spec.cwd !== null) {
+        throw new AgentError({
+            code: AGENT_ERROR_CODE.invalidInput,
+            classification: AgentError.agentFailure(AGENT_ERROR_CODE.invalidInput),
+            message: "Codex stdio MCP registration does not support server cwd",
+            data: { reason: UNSUPPORTED_CWD_REASON },
+        });
+    }
+}
+function assertCodexMcpScopeSupported(scope) {
+    if (scope === MCP_SCOPE.user) {
+        return;
+    }
+    const reason = [UNSUPPORTED_SCOPE_REASON_PREFIX, scope].join(": ");
+    throw new AgentError({
+        code: AGENT_ERROR_CODE.invalidInput,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.invalidInput),
+        message: `Codex MCP registration does not support scope "${scope}"`,
+        data: { reason },
+    });
+}
+function codexAppServerOptions(ctx) {
+    return {
+        exec: ctx.exec,
+        clock: ctx.clock,
+        env: ctx.env,
+        cwd: codexAppServerCwd(ctx),
+        command: CODEX.command,
+    };
+}
+function skillsFromCodexResult(result) {
+    return result.data.flatMap((entry) => entry.skills.map((skill) => ({
+        id: skill.name,
+        name: skill.name,
+        description: skill.description,
+        location: skill.path,
+        source: `codex:${skill.scope}`,
+    })));
+}
+function installOutcomeFromCodexPlugin(name, result) {
+    if (result.appsNeedingAuth.length > 0) {
+        throw new AgentError({
+            code: AGENT_ERROR_CODE.auth,
+            classification: AgentError.agentFailure(AGENT_ERROR_CODE.auth),
+            message: CODEX_PLUGIN_AUTH_REQUIRED_MESSAGE,
+            data: {
+                reason: AUTH_FAILURE_REASON.notLoggedIn,
+                detail: result.authPolicy,
+            },
+        });
+    }
+    const location = result.location ?? `codex:plugin:${name}`;
+    const alreadyInstalled = result.alreadyInstalled === true ||
+        (result.status !== null &&
+            CODEX_ALREADY_INSTALLED_STATUS.test(result.status));
+    return {
+        status: alreadyInstalled
+            ? INSTALL_STATUS.alreadyInstalled
+            : INSTALL_STATUS.installed,
+        location,
+    };
+}
+function codexMcpState(status) {
+    // tools === null = the app-server did not enumerate tools; McpServerState
+    // keeps that distinct from an enumerated-but-empty tool list.
+    const tools = status.tools === null
+        ? null
+        : Object.entries(status.tools).map(([key, tool]) => tool.name ?? key);
+    return {
+        name: status.name,
+        transport: MCP_TRANSPORT.stdio,
+        usable: !CODEX_MCP_UNUSABLE_STATUS.test(status.authStatus),
+        tools,
+    };
+}
+function codexLoginCommand(args) {
+    return (request, ctx) => cliLoginCommand({
+        command: CODEX.command,
+        args,
+        envPatch: {
+            set: { [CODEX_HOME_ENV_VAR]: request.homeDir },
+            unset: COMPETING_API_KEY_VARS,
+        },
+        request,
+        ctx,
+    });
+}
+export const codexAuth = {
+    [AUTH_MATERIAL_KIND.homeDir]: envVarAuthMaterial({
+        set: (material) => ({ [CODEX_HOME_ENV_VAR]: material.path }),
+        unset: COMPETING_API_KEY_VARS,
+        check: (material, ctx) => cliLoginProbe({
+            command: CODEX.command,
+            args: CODEX.auth.statusArgs,
+            envPatch: {
+                set: { [CODEX_HOME_ENV_VAR]: material.path },
+                unset: COMPETING_API_KEY_VARS,
+            },
+            ctx,
+        }),
+    }),
+    [AUTH_MATERIAL_KIND.apiKey]: envVarAuthMaterial({
+        set: async (material, secrets) => ({
+            [CODEX_API_KEY_ENV_VAR]: await requireSecret(secrets, material.secret),
+        }),
+        unset: COMPETING_HOME_VARS,
+    }),
+};
+export const codexLogin = {
+    methods: {
+        [LOGIN_METHOD.oauth]: codexLoginCommand(CODEX.auth.oauthLoginArgs),
+        [LOGIN_METHOD.device]: codexLoginCommand(CODEX.auth.deviceLoginArgs),
+    },
+};
+export const codexSkills = {
+    list: listCodexSkills,
+    install: {
+        [SKILL_SOURCE_KIND.plugin]: installCodexPlugin,
+    },
+};
+export const codexMcp = {
+    list: listCodexMcp,
+    add: {
+        [MCP_TRANSPORT.stdio]: addCodexStdioMcp,
+    },
+    remove: removeCodexMcp,
+};

package/dist/agents/codex/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The built-in codex agent: the one-shot run contract
+ * (`codex exec [--model m] [-c model_reasoning_effort="e"] --json
+ *  --skip-git-repo-check --sandbox <mode> -C <workspace>`, prompt on
+ * stdin; sandboxing is filesystem-level, so read-only grants have no argv
+ * mapping) composed with the session adapter and the host plane.
+ * Vocabulary lives in `cli.ts`.
+ */
+import { type FailureMatcher } from "../../kernel/classify.js";
+import type { AgentDefinition } from "../../kernel/definition.js";
+import { type CodexSessionPermissions } from "./cli.js";
+export declare function capacityTextMatcher(): FailureMatcher;
+export declare function codex(): AgentDefinition<"codex", CodexSessionPermissions>;
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/codex/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agents/codex/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,EACL,KAAK,cAAc,EAEpB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE,OAAO,EAAS,KAAK,uBAAuB,EAAE,MAAM,UAAU,CAAC;AA2D/D,wBAAgB,mBAAmB,IAAI,cAAc,CAepD;AAED,wBAAgB,KAAK,IAAI,eAAe,CAAC,OAAO,EAAE,uBAAuB,CAAC,CA8CzE"}

package/dist/agents/codex/index.js

@@ -0,0 +1,127 @@
+/**
+ * The built-in codex agent: the one-shot run contract
+ * (`codex exec [--model m] [-c model_reasoning_effort="e"] --json
+ *  --skip-git-repo-check --sandbox <mode> -C <workspace>`, prompt on
+ * stdin; sandboxing is filesystem-level, so read-only grants have no argv
+ * mapping) composed with the session adapter and the host plane.
+ * Vocabulary lives in `cli.ts`.
+ */
+import { CODEX_SANDBOX_MODE } from "../../codex/protocol.js";
+import { AGENT_ERROR_CODE } from "../../core/error.js";
+import { readJsonRecord, readRecord, readString } from "../../core/json.js";
+import { AGENT_EVENT_TYPE } from "../../core/run.js";
+import { cliAvailability } from "../../host/availability.js";
+import { parseCooldownHint, } from "../../kernel/classify.js";
+import { defineCliAgent } from "../../kernel/cli-agent.js";
+import { SANDBOX_MODE } from "../../kernel/options.js";
+import { CODEX } from "./cli.js";
+import { codexAuth, codexLogin, codexMcp, codexSkills } from "./host.js";
+import { codexSessions } from "./session.js";
+function sharedArgs(ctx, sandboxValue) {
+    return [
+        CODEX.cli.exec,
+        ...(ctx.model === null ? [] : [CODEX.cli.model, ctx.model]),
+        ...(ctx.effort === null
+            ? []
+            : [
+                CODEX.cli.config,
+                `${CODEX.cli.reasoningEffortConfigKey}="${ctx.effort}"`,
+            ]),
+        CODEX.cli.json,
+        CODEX.cli.skipGitRepoCheck,
+        CODEX.cli.sandbox,
+        sandboxValue,
+        CODEX.cli.workspace,
+        ctx.workspace,
+    ];
+}
+function parseCodexLine(line) {
+    const record = readJsonRecord(line);
+    if (record === null) {
+        return [];
+    }
+    const type = readString(record, CODEX.json.field.type);
+    if (type === CODEX.json.event.turnCompleted) {
+        return [{ type: AGENT_EVENT_TYPE.turn }];
+    }
+    if (type === CODEX.json.event.agentMessage) {
+        const text = readString(record, CODEX.json.field.text);
+        return text === null ? [] : [{ type: AGENT_EVENT_TYPE.message, text }];
+    }
+    if (type === CODEX.json.event.itemCompleted) {
+        const item = readRecord(record, CODEX.json.field.item);
+        if (item !== null &&
+            readString(item, CODEX.json.field.type) === CODEX.json.event.agentMessage) {
+            const text = readString(item, CODEX.json.field.text);
+            return text === null ? [] : [{ type: AGENT_EVENT_TYPE.message, text }];
+        }
+    }
+    return [];
+}
+/**
+ * Codex "selected model is at capacity" phrasing, plus the looser
+ * "model ... at capacity" combination. Exported for custom agents that
+ * surface the same provider text.
+ */
+/** Codex capacity phrasing (v1 F5 signals, kept verbatim). */
+const CAPACITY_TEXT = /selected model is at capacity|model is at capacity/i;
+const CAPACITY_COMBINED = /at capacity/i;
+const CAPACITY_MODEL = /model/i;
+export function capacityTextMatcher() {
+    return (evidence) => {
+        const text = `${evidence.stderr}\n${evidence.stdout}`;
+        const matches = CAPACITY_TEXT.test(text) ||
+            (CAPACITY_COMBINED.test(text) && CAPACITY_MODEL.test(text));
+        if (!matches) {
+            return null;
+        }
+        return {
+            code: AGENT_ERROR_CODE.capacity,
+            message: "Provider is at capacity",
+            data: { cooldownUntil: parseCooldownHint(text, evidence.now) },
+        };
+    };
+}
+export function codex() {
+    const definition = defineCliAgent({
+        id: CODEX.id,
+        command: CODEX.command,
+        args: {
+            [SANDBOX_MODE.full]: (_sandbox, ctx) => sharedArgs(ctx, CODEX_SANDBOX_MODE.dangerFullAccess),
+            [SANDBOX_MODE.readOnly]: (_sandbox, ctx) => sharedArgs(ctx, CODEX_SANDBOX_MODE.readOnly),
+        },
+        parseLine: parseCodexLine,
+        classify: [capacityTextMatcher()],
+        detectCompletion: (line, state) => {
+            if (state.messages.length === 0) {
+                return false;
+            }
+            const record = readJsonRecord(line);
+            return (record !== null &&
+                readString(record, CODEX.json.field.type) ===
+                    CODEX.json.event.turnCompleted);
+        },
+        availability: cliAvailability({
+            command: CODEX.command,
+            commandMissingRemediation: {
+                detail: "Install Codex and ensure `codex` is on PATH.",
+                command: null,
+            },
+            authentication: {
+                args: CODEX.auth.statusArgs,
+                remediation: {
+                    detail: "Sign in to Codex.",
+                    command: {
+                        executable: CODEX.command,
+                        args: CODEX.auth.oauthLoginArgs,
+                    },
+                },
+            },
+        }),
+        auth: codexAuth,
+        login: codexLogin,
+        skills: codexSkills,
+        mcp: codexMcp,
+    });
+    return { ...definition, session: codexSessions() };
+}

package/dist/agents/codex/session.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Codex session adapter: one `codex app-server` process holding one thread.
+ *
+ * Protocol facts (codex 0.153.4, T53 / T57 / T61 lab runs):
+ * - `thread/start {cwd, sandbox, approvalPolicy, approvalsReviewer}` creates
+ *   the thread and takes its writer lock; with a writable sandbox Codex also
+ *   appends a `trust_level` entry for `cwd` to `~/.codex/config.toml`;
+ * - `thread/resume` must repeat the permissions — without `sandbox` the
+ *   resumed turns ran as danger-full-access; it answers -32600 "already has
+ *   an active writer" while another process holds the thread and -32600
+ *   "… is archived" for an archived one (`thread/unarchive` first, opt-in);
+ * - `turn/start` answers the turn id at once; `turn/steer {expectedTurnId}`
+ *   appends to it; `turn/interrupt` ends it with `turn/completed`
+ *   status `interrupted` (the command's own `item/completed` may trail by ~36 s);
+ * - `item/commandExecution/requestApproval` is a server request answered by
+ *   `{"decision": "accept" | "decline"}`; closing stdin releases the lock.
+ */
+import { type SessionCapability } from "../../kernel/session.js";
+import { type CodexSessionPermissions } from "./cli.js";
+export declare function codexSessions(): SessionCapability<CodexSessionPermissions>;
+//# sourceMappingURL=session.d.ts.map

package/dist/agents/codex/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/agents/codex/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAyCH,OAAO,EAKL,KAAK,iBAAiB,EAIvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAKL,KAAK,uBAAuB,EAC7B,MAAM,UAAU,CAAC;AAielB,wBAAgB,aAAa,IAAI,iBAAiB,CAAC,uBAAuB,CAAC,CAM1E"}