@alpacakit/agents 0.1.0-beta.39 → 0.2.0-beta.3

package/dist/agents/claude/host.js

@@ -0,0 +1,319 @@
+/**
+ * The claude host plane: auth materials and sign-in, installed skills
+ * (`~/.claude/skills`, project `.claude/skills`, plugins), and MCP
+ * registration through the CLI. Outside a run and a session; every path
+ * comes from `HostContext.location`, never `os.homedir()`.
+ */
+import { cp, mkdir, readdir, readFile, rm, stat } from "node:fs/promises";
+import path from "node:path";
+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 { NO_FAILURE_EVIDENCE } from "../../core/cli-child.js";
+import { AGENT_ERROR_CODE, AgentError } from "../../core/error.js";
+import { isErrnoCode } from "../../core/fs.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 { cliLoginCommand } from "../../kernel/cli-login.js";
+import { CLAUDE, CLAUDE_API_KEY_ENV_VAR, CLAUDE_CONFIG_DIR_ENV_VAR, } from "./cli.js";
+const COMPETING_TOKEN_VARS = [
+    CLAUDE_API_KEY_ENV_VAR,
+    "ANTHROPIC_AUTH_TOKEN",
+    "CLAUDE_CODE_OAUTH_TOKEN",
+];
+const COMPETING_CONFIG_VARS = [
+    CLAUDE_CONFIG_DIR_ENV_VAR,
+    "ANTHROPIC_AUTH_TOKEN",
+    "CLAUDE_CODE_OAUTH_TOKEN",
+];
+const CLAUDE_PROJECT_SKILL_ROOT = CLAUDE.files.root;
+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",
+};
+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,
+    }),
+});
+/**
+ * `claude auth login --claudeai` writes its credential into
+ * `CLAUDE_CONFIG_DIR`, so pointing that at the requested home is the whole
+ * isolation mechanism — the competing token variables are unset for the same
+ * reason `homeDirHandler` unsets them: an inherited token would authenticate
+ * the CLI without ever populating the home we are creating.
+ *
+ * Only `oauth` is offered. The CLI has no device-code flow (`--console` /
+ * `--sso` are still browser flows), and declaring an unimplemented method
+ * would make `agent.login.supports("device")` lie.
+ */
+function claudeLoginCommand(args) {
+    return (request, ctx) => cliLoginCommand({
+        command: CLAUDE.command,
+        args,
+        envPatch: {
+            set: { [CLAUDE_CONFIG_DIR_ENV_VAR]: request.homeDir },
+            unset: COMPETING_TOKEN_VARS,
+        },
+        request,
+        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,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.failed),
+        message: `Could not read installed claude skills: ${target}`,
+        data: NO_FAILURE_EVIDENCE,
+        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,
+        classification: AgentError.agentFailure(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,
+            classification: AgentError.agentFailure(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 const claudeAuth = {
+    [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,
+    }),
+};
+export const claudeLogin = {
+    methods: {
+        [LOGIN_METHOD.oauth]: claudeLoginCommand(CLAUDE.auth.loginArgs),
+    },
+};
+export const claudeSkills = {
+    list: listClaudeSkills,
+    install: {
+        [SKILL_SOURCE_KIND.localDir]: installLocalClaudeSkill,
+        [SKILL_SOURCE_KIND.githubDir]: installGithubClaudeSkill,
+        [SKILL_SOURCE_KIND.plugin]: installClaudePlugin,
+    },
+};
+export const claudeMcp = {
+    list: listClaudeMcp,
+    add: {
+        [MCP_TRANSPORT.stdio]: addClaudeStdioMcp,
+    },
+    remove: removeClaudeMcp,
+};

package/dist/agents/{claude.d.ts → claude/index.d.ts}

@@ -1,14 +1,14 @@
 /**
- * Built-in claude CLI contract:
- * `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 ""`.
+ * The built-in claude agent: the one-shot run contract
+ * (`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, no grants means `--tools ""`) 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";
-export declare const CLAUDE_CONFIG_DIR_ENV_VAR = "CLAUDE_CONFIG_DIR";
-export declare const CLAUDE_API_KEY_ENV_VAR = "ANTHROPIC_API_KEY";
+import { type FailureMatcher } from "../../kernel/classify.js";
+import type { AgentDefinition } from "../../kernel/definition.js";
+import { type ClaudeSessionPermissions } from "./cli.js";
 /**
  * Structured quota signals in Claude CLI NDJSON output (v1 F2), scanned
  * per line: rate_limit_event rejected (with resetsAt), api_error_status
@@ -23,5 +23,5 @@ export type ClaudeOptions = {
      */
     readonly customizations?: "inherit" | "disabled";
 };
-export declare function claude(options?: ClaudeOptions): AgentDefinition<"claude">;
-//# sourceMappingURL=claude.d.ts.map
+export declare function claude(options?: ClaudeOptions): AgentDefinition<"claude", ClaudeSessionPermissions>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agents/claude/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,OAAO,EACL,KAAK,cAAc,EAEpB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE,OAAO,EAGL,KAAK,wBAAwB,EAI9B,MAAM,UAAU,CAAC;AA8BlB;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,cAAc,CA0CvD;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;CAClD,CAAC;AAEF,wBAAgB,MAAM,CACpB,OAAO,GAAE,aAAkB,GAC1B,eAAe,CAAC,QAAQ,EAAE,wBAAwB,CAAC,CAmDrD"}

package/dist/agents/claude/index.js

@@ -0,0 +1,134 @@
+/**
+ * The built-in claude agent: the one-shot run contract
+ * (`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, no grants means `--tools ""`) composed with the session adapter
+ * and the host plane. Vocabulary lives in `cli.ts`.
+ */
+import { AGENT_ERROR_CODE } from "../../core/error.js";
+import { readBoolean, readJsonRecord, readNumber, readRecord, readString, } from "../../core/json.js";
+import { cliAvailability } from "../../host/availability.js";
+import { parseEpochTimestamp, } from "../../kernel/classify.js";
+import { defineCliAgent } from "../../kernel/cli-agent.js";
+import { GRANT_KIND, SANDBOX_MODE } from "../../kernel/options.js";
+import { CLAUDE, CLAUDE_PERMISSION_MODE, parseClaudeLine, parseClaudeResult, permissionModeArgs, } from "./cli.js";
+import { claudeAuth, claudeLogin, claudeMcp, claudeSkills } from "./host.js";
+import { claudeSessions } from "./session.js";
+function grantToToolArg(grant) {
+    return grant.kind === GRANT_KIND.shell
+        ? `Bash(${grant.command}:*)`
+        : grant.name;
+}
+function sharedArgs(ctx, customizations) {
+    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,
+        ...(customizations === "disabled"
+            ? [
+                CLAUDE.cli.safeMode,
+                CLAUDE.cli.strictMcpConfig,
+                CLAUDE.cli.noSessionPersistence,
+            ]
+            : []),
+    ];
+}
+/**
+ * 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;
+    };
+}
+export function claude(options = {}) {
+    const customizations = options.customizations ?? "inherit";
+    const definition = defineCliAgent({
+        id: CLAUDE.id,
+        command: CLAUDE.command,
+        args: {
+            [SANDBOX_MODE.full]: (_sandbox, ctx) => [
+                ...sharedArgs(ctx, customizations),
+                ...permissionModeArgs(CLAUDE_PERMISSION_MODE.bypassPermissions),
+                CLAUDE.cli.verbose,
+            ],
+            [SANDBOX_MODE.readOnly]: (sandbox, ctx) => [
+                ...sharedArgs(ctx, customizations),
+                ...permissionModeArgs(CLAUDE_PERMISSION_MODE.default),
+                ...(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()],
+        availability: cliAvailability({
+            command: CLAUDE.command,
+            commandMissingRemediation: {
+                detail: "Install Claude Code and ensure `claude` is on PATH.",
+                command: null,
+            },
+            authentication: {
+                args: CLAUDE.auth.statusArgs,
+                remediation: {
+                    detail: "Sign in to Claude Code.",
+                    command: {
+                        executable: CLAUDE.command,
+                        args: CLAUDE.auth.loginArgs,
+                    },
+                },
+            },
+        }),
+        auth: claudeAuth,
+        login: claudeLogin,
+        skills: claudeSkills,
+        mcp: claudeMcp,
+    });
+    return { ...definition, session: claudeSessions({ customizations }) };
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Claude session adapter: one `claude -p --input-format stream-json
+ * --output-format stream-json` process held open across turns.
+ *
+ * Protocol facts (claude 2.1.270, T52 / T61 lab runs):
+ * - a turn is one user line `{"type":"user","message":{"role":"user","content":…}}`
+ *   and ends with the `result` line; a user line written mid-turn is absorbed
+ *   into the running turn at its next tool boundary (`steer`);
+ * - `{"type":"control_request","request_id":…,"request":{"subtype":"interrupt"}}`
+ *   is answered by a `control_response`, and the turn then ends with
+ *   `is_error: true` / `terminal_reason: "aborted_tools"`;
+ * - approval prompts reach stdout only with `--permission-prompt-tool stdio`, as
+ *   `control_request` / `can_use_tool`, and are answered with a
+ *   `control_response` whose `behavior` is `allow` (+ `updatedInput`) or `deny`;
+ * - `--session-id <uuid>` fixes the id before the first turn (no `init` line
+ *   is emitted until then), `--resume <id>` continues a recorded one;
+ * - the child needs `USER` in its env: without it the CLI reports "Not logged in".
+ */
+import { type SessionCapability } from "../../kernel/session.js";
+import { type ClaudeSessionPermissions } from "./cli.js";
+export type ClaudeSessionOptions = {
+    readonly customizations: "inherit" | "disabled";
+};
+export declare function claudeSessions(options: ClaudeSessionOptions): SessionCapability<ClaudeSessionPermissions>;
+//# sourceMappingURL=session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/agents/claude/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAoCH,OAAO,EAGL,KAAK,iBAAiB,EAOvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAIL,KAAK,wBAAwB,EAG9B,MAAM,UAAU,CAAC;AAqBlB,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,cAAc,EAAE,SAAS,GAAG,UAAU,CAAC;CACjD,CAAC;AAuWF,wBAAgB,cAAc,CAC5B,OAAO,EAAE,oBAAoB,GAC5B,iBAAiB,CAAC,wBAAwB,CAAC,CAoB7C"}