@alpacakit/agents 0.1.0-beta.19

package/dist/agents/claude.js

@@ -0,0 +1,480 @@
+/**
+ * Built-in claude adapter (v1 E1/E2 argv kept verbatim):
+ * `claude -p [--model m] [--effort e] --output-format stream-json
+ *  --permission-mode <mode> [tool args] --verbose`, prompt on stdin.
+ * Read-only grants map to `--allowedTools` (`Bash(cmd:*)` for shell
+ * grants, the bare tool name otherwise); no grants means `--tools ""`.
+ */
+import { cp, mkdir, readdir, readFile, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { cliLoginProbe } from "../auth/login-probe.js";
+import { AUTH_MATERIAL_KIND, envVarAuthMaterial } from "../auth/material.js";
+import { requireSecret } from "../auth/secrets.js";
+import { AGENT_ERROR_CODE, AgentError } from "../core/error.js";
+import { isErrnoCode } from "../core/fs.js";
+import { readBoolean, readJsonRecord, readNumber, readRecord, readString, readUnknownRecord, } from "../core/json.js";
+import { AGENT_EVENT_TYPE } from "../core/run.js";
+import { TEXT_ENCODING } from "../core/values.js";
+import { INSTALL_STATUS, MCP_TRANSPORT, SKILL_SOURCE_KIND, } from "../host/capabilities.js";
+import { withStagedGithubDirectory, } from "../host/github-dir.js";
+import { listMcpServersViaCli } from "../host/mcp-list.js";
+import { hostCommandFailedError, runHostCommand, runHostCommandResult, } from "../host/run-command.js";
+import { parseEpochTimestamp, } from "../kernel/classify.js";
+import { defineCliAgent, } from "../kernel/cli-agent.js";
+import { GRANT_KIND, SANDBOX_MODE } from "../kernel/options.js";
+export const CLAUDE_CONFIG_DIR_ENV_VAR = "CLAUDE_CONFIG_DIR";
+export const CLAUDE_API_KEY_ENV_VAR = "ANTHROPIC_API_KEY";
+const CLAUDE = {
+    id: "claude",
+    command: "claude",
+    cli: {
+        prompt: "-p",
+        model: "--model",
+        effort: "--effort",
+        outputFormat: "--output-format",
+        streamJson: "stream-json",
+        permissionMode: "--permission-mode",
+        bypassPermissions: "bypassPermissions",
+        defaultPermissionMode: "default",
+        verbose: "--verbose",
+        tools: "--tools",
+        allowedTools: "--allowedTools",
+    },
+    auth: {
+        statusArgs: ["auth", "status", "--json"],
+    },
+    mcp: {
+        addJson: "add-json",
+        mcp: "mcp",
+        remove: "remove",
+        scope: "--scope",
+    },
+    plugin: {
+        plugin: "plugin",
+        install: "install",
+    },
+    json: {
+        field: {
+            type: "type",
+            message: "message",
+            content: "content",
+            text: "text",
+            name: "name",
+            usage: "usage",
+            result: "result",
+            inputTokens: "input_tokens",
+            outputTokens: "output_tokens",
+            totalCost: "total_cost_usd",
+        },
+        type: {
+            assistant: "assistant",
+            result: "result",
+            text: "text",
+            toolUse: "tool_use",
+        },
+    },
+};
+const COMPETING_TOKEN_VARS = [
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "CLAUDE_CODE_OAUTH_TOKEN",
+];
+const COMPETING_CONFIG_VARS = [
+    "CLAUDE_CONFIG_DIR",
+    "ANTHROPIC_AUTH_TOKEN",
+    "CLAUDE_CODE_OAUTH_TOKEN",
+];
+const CLAUDE_PROJECT_SKILL_ROOT = ".claude";
+const SKILLS_DIRECTORY = "skills";
+const SKILL_MARKDOWN = "SKILL.md";
+const PLUGIN_ALREADY_INSTALLED = /already installed/i;
+const CLAUDE_SKILL_SOURCE = {
+    project: "claude:project",
+    user: "claude:user",
+};
+function grantToToolArg(grant) {
+    return grant.kind === GRANT_KIND.shell
+        ? `Bash(${grant.command}:*)`
+        : grant.name;
+}
+function sharedArgs(ctx) {
+    return [
+        CLAUDE.cli.prompt,
+        ...(ctx.model === null ? [] : [CLAUDE.cli.model, ctx.model]),
+        ...(ctx.effort === null ? [] : [CLAUDE.cli.effort, ctx.effort]),
+        CLAUDE.cli.outputFormat,
+        CLAUDE.cli.streamJson,
+    ];
+}
+function parseClaudeLine(line) {
+    const record = readJsonRecord(line);
+    if (record === null ||
+        readString(record, CLAUDE.json.field.type) !== CLAUDE.json.type.assistant) {
+        return [];
+    }
+    const message = readRecord(record, CLAUDE.json.field.message);
+    const content = message?.[CLAUDE.json.field.content];
+    if (!Array.isArray(content)) {
+        return [{ type: AGENT_EVENT_TYPE.turn }];
+    }
+    const events = [{ type: AGENT_EVENT_TYPE.turn }];
+    for (const block of content) {
+        const blockRecord = readUnknownRecord(block);
+        if (blockRecord === null) {
+            continue;
+        }
+        const blockType = readString(blockRecord, CLAUDE.json.field.type);
+        if (blockType === CLAUDE.json.type.text) {
+            const text = readString(blockRecord, CLAUDE.json.field.text);
+            if (text !== null) {
+                events.push({ type: AGENT_EVENT_TYPE.message, text });
+            }
+        }
+        if (blockType === CLAUDE.json.type.toolUse) {
+            const name = readString(blockRecord, CLAUDE.json.field.name);
+            if (name !== null) {
+                events.push({ type: AGENT_EVENT_TYPE.tool, name });
+            }
+        }
+    }
+    return events;
+}
+function parseClaudeResult(line) {
+    const record = readJsonRecord(line);
+    if (record === null ||
+        readString(record, CLAUDE.json.field.type) !== CLAUDE.json.type.result) {
+        return null;
+    }
+    const usageRecord = readRecord(record, CLAUDE.json.field.usage);
+    const usage = usageRecord === null
+        ? null
+        : {
+            inputTokens: readNumber(usageRecord, CLAUDE.json.field.inputTokens),
+            outputTokens: readNumber(usageRecord, CLAUDE.json.field.outputTokens),
+            costUsd: readNumber(record, CLAUDE.json.field.totalCost),
+        };
+    return { text: readString(record, CLAUDE.json.field.result), usage };
+}
+/**
+ * Structured quota signals in Claude CLI NDJSON output (v1 F2), scanned
+ * per line: rate_limit_event rejected (with resetsAt), api_error_status
+ * 429, and error === "rate_limit". Exported for custom agents that speak
+ * the same stream format.
+ */
+export function structuredQuotaMatcher() {
+    return (evidence) => {
+        let fallbackCooldownUntil = null;
+        for (const line of evidence.stdout.split(/\r?\n/)) {
+            const record = readJsonRecord(line.trim());
+            if (record === null) {
+                continue;
+            }
+            const rateLimitInfo = readRecord(record, "rate_limit_info");
+            const resetsAt = rateLimitInfo === null ? null : readNumber(rateLimitInfo, "resetsAt");
+            const cooldownUntil = resetsAt === null ? null : parseEpochTimestamp(resetsAt);
+            const rejected = rateLimitInfo !== null &&
+                readString(rateLimitInfo, "status") === "rejected";
+            if (readString(record, "type") === "rate_limit_event" && rejected) {
+                return {
+                    code: AGENT_ERROR_CODE.quota,
+                    message: "Provider rejected the request for rate limiting",
+                    data: { cooldownUntil },
+                };
+            }
+            if (cooldownUntil !== null) {
+                fallbackCooldownUntil = cooldownUntil;
+            }
+            const apiError = readBoolean(record, "is_error") === true &&
+                readNumber(record, "api_error_status") === 429;
+            const rateLimitError = readString(record, "error") === "rate_limit" &&
+                readString(record, "type") !== null;
+            if (apiError || rateLimitError) {
+                return {
+                    code: AGENT_ERROR_CODE.quota,
+                    message: "Provider reported a rate-limit error",
+                    data: { cooldownUntil: fallbackCooldownUntil },
+                };
+            }
+        }
+        return null;
+    };
+}
+const homeDirHandler = envVarAuthMaterial({
+    set: (material) => ({ [CLAUDE_CONFIG_DIR_ENV_VAR]: material.path }),
+    unset: COMPETING_TOKEN_VARS,
+    check: (material, ctx) => cliLoginProbe({
+        command: CLAUDE.command,
+        args: CLAUDE.auth.statusArgs,
+        envPatch: {
+            set: { [CLAUDE_CONFIG_DIR_ENV_VAR]: material.path },
+            unset: COMPETING_TOKEN_VARS,
+        },
+        ctx,
+    }),
+});
+/** Install/list roots in priority order; the first is the install target. */
+function claudeSkillRoots(ctx) {
+    const userRoot = {
+        root: path.join(ctx.location.homeDir, CLAUDE_PROJECT_SKILL_ROOT, SKILLS_DIRECTORY),
+        source: CLAUDE_SKILL_SOURCE.user,
+    };
+    if (ctx.location.projectDir === null) {
+        return [userRoot];
+    }
+    return [
+        {
+            root: path.join(ctx.location.projectDir, CLAUDE_PROJECT_SKILL_ROOT, SKILLS_DIRECTORY),
+            source: CLAUDE_SKILL_SOURCE.project,
+        },
+        userRoot,
+    ];
+}
+function parseSkillMetadata(markdown) {
+    const frontmatter = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---/u);
+    if (frontmatter?.[1] === undefined) {
+        return { name: null, description: null };
+    }
+    let name = null;
+    let description = null;
+    for (const line of frontmatter[1].split(/\r?\n/u)) {
+        const separator = line.indexOf(":");
+        if (separator < 0) {
+            continue;
+        }
+        const key = line.slice(0, separator).trim();
+        const value = line
+            .slice(separator + 1)
+            .trim()
+            .replace(/^["']|["']$/gu, "");
+        if (key === "name") {
+            name = value;
+        }
+        if (key === "description") {
+            description = value;
+        }
+    }
+    return { name, description };
+}
+function skillListReadError(target, cause) {
+    return new AgentError({
+        code: AGENT_ERROR_CODE.failed,
+        message: `Could not read installed claude skills: ${target}`,
+        data: { exitCode: null, stdoutTail: null, stderrTail: null },
+        cause,
+    });
+}
+async function readSkillRootEntries(root) {
+    try {
+        return await readdir(root, { withFileTypes: true });
+    }
+    catch (error) {
+        // D5 discipline: only "the root does not exist" reads as empty.
+        if (isErrnoCode(error, "ENOENT") || isErrnoCode(error, "ENOTDIR")) {
+            return [];
+        }
+        throw skillListReadError(root, error);
+    }
+}
+async function readSkillMarkdown(location) {
+    try {
+        return await readFile(path.join(location, SKILL_MARKDOWN), TEXT_ENCODING);
+    }
+    catch (error) {
+        // A directory without SKILL.md is simply not a skill; anything else
+        // (permissions, I/O) must surface instead of hiding installed skills.
+        if (isErrnoCode(error, "ENOENT")) {
+            return null;
+        }
+        throw skillListReadError(location, error);
+    }
+}
+async function listClaudeSkills(ctx) {
+    const byId = new Map();
+    for (const { root, source } of claudeSkillRoots(ctx)) {
+        for (const entry of await readSkillRootEntries(root)) {
+            if (!entry.isDirectory() || byId.has(entry.name)) {
+                continue;
+            }
+            const location = path.join(root, entry.name);
+            const markdown = await readSkillMarkdown(location);
+            if (markdown === null) {
+                continue;
+            }
+            const metadata = parseSkillMetadata(markdown);
+            byId.set(entry.name, {
+                id: entry.name,
+                name: metadata.name ?? entry.name,
+                description: metadata.description ?? "",
+                location,
+                source,
+            });
+        }
+    }
+    return [...byId.values()];
+}
+async function installLocalClaudeSkill(ctx, source, options) {
+    await assertSkillDirectory(source.path);
+    const skillId = path.basename(path.resolve(source.path));
+    const location = path.join(claudeSkillRoot(ctx), skillId);
+    if ((await pathExists(location)) && options.overwrite !== true) {
+        return { status: INSTALL_STATUS.alreadyInstalled, location };
+    }
+    if (options.overwrite === true) {
+        await rm(location, { recursive: true, force: true });
+    }
+    await mkdir(path.dirname(location), { recursive: true });
+    await cp(source.path, location, { recursive: true });
+    return { status: INSTALL_STATUS.installed, location };
+}
+function claudeSkillRoot(ctx) {
+    return claudeSkillRoots(ctx)[0].root;
+}
+async function assertSkillDirectory(directory) {
+    try {
+        const skill = await stat(path.join(directory, SKILL_MARKDOWN));
+        if (skill.isFile()) {
+            return;
+        }
+    }
+    catch {
+        // Convert below to the library's typed boundary error.
+    }
+    throw new AgentError({
+        code: AGENT_ERROR_CODE.invalidInput,
+        message: `Skill source does not contain ${SKILL_MARKDOWN}: ${directory}`,
+        data: { reason: `missing ${SKILL_MARKDOWN}` },
+    });
+}
+async function pathExists(target) {
+    try {
+        await stat(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function installGithubClaudeSkill(ctx, source, options) {
+    return withStagedGithubDirectory(ctx, source, (stagedSkill) => installLocalClaudeSkill(ctx, { kind: SKILL_SOURCE_KIND.localDir, path: stagedSkill }, options));
+}
+async function installClaudePlugin(ctx, source, options) {
+    if (options.overwrite === true) {
+        // `claude plugin install` has no overwrite semantics; refusing is
+        // honest, silently ignoring the request is not.
+        throw new AgentError({
+            code: AGENT_ERROR_CODE.invalidInput,
+            message: "Claude plugin installation cannot overwrite an installed plugin",
+            data: { reason: "plugin install does not support overwrite" },
+        });
+    }
+    const result = await runHostCommandResult(ctx, {
+        command: CLAUDE.command,
+        args: [CLAUDE.plugin.plugin, CLAUDE.plugin.install, source.name],
+    });
+    const output = `${result.stdout}\n${result.stderr}`;
+    if (result.exit.code === 0) {
+        return {
+            status: INSTALL_STATUS.installed,
+            location: `claude:plugin:${source.name}`,
+        };
+    }
+    if (PLUGIN_ALREADY_INSTALLED.test(output)) {
+        return {
+            status: INSTALL_STATUS.alreadyInstalled,
+            location: `claude:plugin:${source.name}`,
+        };
+    }
+    throw hostCommandFailedError(CLAUDE.command, result);
+}
+async function addClaudeStdioMcp(ctx, name, spec, options) {
+    await runHostCommand(ctx, {
+        command: CLAUDE.command,
+        args: [
+            CLAUDE.mcp.mcp,
+            CLAUDE.mcp.addJson,
+            name,
+            JSON.stringify({
+                command: spec.command,
+                args: spec.args,
+                env: spec.env,
+                ...(spec.cwd === null ? {} : { cwd: spec.cwd }),
+            }),
+            CLAUDE.mcp.scope,
+            options.scope,
+        ],
+    });
+    return {
+        status: INSTALL_STATUS.installed,
+        location: `claude:${options.scope}:${name}`,
+    };
+}
+async function removeClaudeMcp(ctx, name, options) {
+    await runHostCommand(ctx, {
+        command: CLAUDE.command,
+        args: [
+            CLAUDE.mcp.mcp,
+            CLAUDE.mcp.remove,
+            name,
+            CLAUDE.mcp.scope,
+            options.scope,
+        ],
+    });
+}
+async function listClaudeMcp(ctx) {
+    return listMcpServersViaCli(ctx, { command: CLAUDE.command });
+}
+export function claude() {
+    return defineCliAgent({
+        id: CLAUDE.id,
+        command: CLAUDE.command,
+        args: {
+            [SANDBOX_MODE.full]: (_sandbox, ctx) => [
+                ...sharedArgs(ctx),
+                CLAUDE.cli.permissionMode,
+                CLAUDE.cli.bypassPermissions,
+                CLAUDE.cli.verbose,
+            ],
+            [SANDBOX_MODE.readOnly]: (sandbox, ctx) => [
+                ...sharedArgs(ctx),
+                CLAUDE.cli.permissionMode,
+                CLAUDE.cli.defaultPermissionMode,
+                ...(sandbox.grants.length === 0
+                    ? [CLAUDE.cli.tools, ""]
+                    : [
+                        CLAUDE.cli.allowedTools,
+                        sandbox.grants.map(grantToToolArg).join(","),
+                    ]),
+                CLAUDE.cli.verbose,
+            ],
+        },
+        parseLine: parseClaudeLine,
+        parseResult: parseClaudeResult,
+        classify: [structuredQuotaMatcher()],
+        // F6: Claude CLI can report a structured quota rejection on exit 0.
+        classifyOnSuccess: [structuredQuotaMatcher()],
+        auth: {
+            [AUTH_MATERIAL_KIND.homeDir]: homeDirHandler,
+            [AUTH_MATERIAL_KIND.apiKey]: envVarAuthMaterial({
+                set: async (material, secrets) => ({
+                    [CLAUDE_API_KEY_ENV_VAR]: await requireSecret(secrets, material.secret),
+                }),
+                unset: COMPETING_CONFIG_VARS,
+            }),
+        },
+        skills: {
+            list: listClaudeSkills,
+            install: {
+                [SKILL_SOURCE_KIND.localDir]: installLocalClaudeSkill,
+                [SKILL_SOURCE_KIND.githubDir]: installGithubClaudeSkill,
+                [SKILL_SOURCE_KIND.plugin]: installClaudePlugin,
+            },
+        },
+        mcp: {
+            list: listClaudeMcp,
+            add: {
+                [MCP_TRANSPORT.stdio]: addClaudeStdioMcp,
+            },
+            remove: removeClaudeMcp,
+        },
+    });
+}

package/dist/agents/codex.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Built-in codex adapter (v1 E1/E2 argv kept verbatim):
+ * `codex exec [--model m] [-c model_reasoning_effort="e"] --json
+ *  --skip-git-repo-check --sandbox <mode> -C <workspace>`, prompt on
+ * stdin. Codex sandboxing is filesystem-level, so read-only grants have
+ * no argv mapping and are ignored here.
+ */
+import { type FailureMatcher } from "../kernel/classify.js";
+import type { AgentDefinition } from "../kernel/definition.js";
+export declare const CODEX_HOME_ENV_VAR = "CODEX_HOME";
+export declare const CODEX_API_KEY_ENV_VAR = "OPENAI_API_KEY";
+/**
+ * Codex "selected model is at capacity" phrasing, plus the looser
+ * "model ... at capacity" combination. Exported for custom agents that
+ * surface the same provider text.
+ */
+export declare function capacityTextMatcher(): FailureMatcher;
+export declare function codex(): AgentDefinition<"codex">;
+//# sourceMappingURL=codex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/agents/codex.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAwCH,OAAO,EAAE,KAAK,cAAc,EAAqB,MAAM,uBAAuB,CAAC;AAG/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG/D,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAC/C,eAAO,MAAM,qBAAqB,mBAAmB,CAAC;AA6GtD;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAepD;AAyMD,wBAAgB,KAAK,IAAI,eAAe,CAAC,OAAO,CAAC,CAoEhD"}