@dynamicagents/plugins 0.12.0 → 0.14.0

package/dist/claude-code/index.js

@@ -1,63 +1,5 @@
-var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
-    if (value !== null && value !== void 0) {
-        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
-        var dispose, inner;
-        if (async) {
-            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
-            dispose = value[Symbol.asyncDispose];
-        }
-        if (dispose === void 0) {
-            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
-            dispose = value[Symbol.dispose];
-            if (async) inner = dispose;
-        }
-        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
-        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
-        env.stack.push({ value: value, dispose: dispose, async: async });
-    }
-    else if (async) {
-        env.stack.push({ async: true });
-    }
-    return value;
-};
-var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
-    return function (env) {
-        function fail(e) {
-            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
-            env.hasError = true;
-        }
-        var r, s = 0;
-        function next() {
-            while (r = env.stack.pop()) {
-                try {
-                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
-                    if (r.dispose) {
-                        var result = r.dispose.call(r.value);
-                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
-                    }
-                    else s |= 1;
-                }
-                catch (e) {
-                    fail(e);
-                }
-            }
-            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
-            if (env.hasError) throw env.error;
-        }
-        return next();
-    };
-})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
-    var e = new Error(message);
-    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
-});
-import { definePlugin, PLUGIN_CONTRACT_VERSION } from "@dynamicagents/core";
-import { claudeCodeEgress } from "./egress.js";
-import { credentialPool } from "./credentials.js";
-import { attachRun, drainRun, execIdFor, freshCursor, isExecLost, killRun, startRun } from "./run.js";
-import { DEFAULT_TIMEOUT_MS, DEFAULT_WINDOW_MS } from "./config.js";
-import { CLAUDE_CODE_SPEC, CLAUDE_CODE_TYPE, WORKSPACE_RUNTIME_KEY } from "./recipe.js";
 /**
- * `@dynamicagents/plugins/claude-code` — subtasks that run the Claude Code CLI.
+ * `@dynamicagents/plugins/claude-code` — sub-agents that run the Claude Code CLI.
  *
  * ## Why this exists
  *
@@ -70,11 +12,12 @@ import { CLAUDE_CODE_SPEC, CLAUDE_CODE_TYPE, WORKSPACE_RUNTIME_KEY } from "./rec
  *
  * ## What it contributes, and what it does not
  *
- * It declares **one subtask type and no tool families**. That is unusual here
- * and it is the whole shape of the thing: Claude Code brings its own tools, its
- * own loop and its own context management, so there is nothing for core's
- * resumable runner to drive. The host's subagent overrides `executeChunk` and
- * calls {@link claudeCodeSession} instead.
+ * **A writer's sub-agent spec, a model, and no plugin.** Claude Code brings its own
+ * tools, its own loop and its own context management, so there is nothing for
+ * an agent loop to drive: the session *is* the sub-agent's model —
+ * {@link claudeCodeModel} — and Think's recovery drives that. A host binds
+ * {@link CLAUDE_CODE_AGENT} to a `SubAgent` class whose `getModel()` returns
+ * one, and adds the `prepare` and `settle` that claim and release a workspace.
  *
  * ## The credential never enters the container
  *
@@ -109,218 +52,13 @@ import { CLAUDE_CODE_SPEC, CLAUDE_CODE_TYPE, WORKSPACE_RUNTIME_KEY } from "./rec
  * policy is `{ mode: "http-gateway" }` and which supplies a
  * {@link CredentialStore}. See the README.
  */
-/**
- * Bind a config to a workspace runtime: start, drain, stop.
- *
- * The three calls a host's `executeChunk` needs and nothing else. State lives in
- * the {@link DrainCursor} the caller persists between chunks, so this holds none
- * and a fresh isolate picks up exactly where the last one stopped.
- */
-export function claudeCodeSession(config) {
-    const windowMs = config.windowMs ?? DEFAULT_WINDOW_MS;
-    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    const launch = (prompt, dir) => ({
-        prompt,
-        dir,
-        ...(config.model ? { model: config.model } : {}),
-        ...(config.effort ? { effort: config.effort } : {}),
-        ...(config.maxSubagentDepth === undefined
-            ? {}
-            : { maxSubagentDepth: config.maxSubagentDepth }),
-        ...(config.maxConcurrentSubagents === undefined
-            ? {}
-            : { maxConcurrentSubagents: config.maxConcurrentSubagents }),
-        // Forwarded only when set, so `buildLaunch` owns the default in one place
-        // rather than this line resolving it and the flag being written twice.
-        ...(config.permissionMode ? { permissionMode: config.permissionMode } : {}),
-        ...(config.env ? { env: config.env } : {}),
-        ...(config.author ? { author: config.author } : {})
-    });
-    return {
-        /**
-         * Spawn a session for one subtask and drain its first window.
-         *
-         * `subtaskId` namespaces the exec id. Subtasks are a concurrent fan-out, so
-         * two sessions in one workspace under one id would spawn over each other —
-         * see {@link execIdFor}.
-         */
-        async start(runtime, subtaskId, prompt, dir, sinks = {}) {
-            const env_1 = { stack: [], error: void 0, hasError: false };
-            try {
-                const execId = execIdFor(subtaskId);
-                // `using`, so the attachment is released even when the drain throws.
-                const handle = __addDisposableResource(env_1, await startRun(runtime, {
-                    ...launch(prompt, dir),
-                    execId,
-                    timeoutMs
-                }), false);
-                return await drainRun(handle, freshCursor(execId), {
-                    windowMs,
-                    ...sinks
-                });
-            }
-            catch (e_1) {
-                env_1.error = e_1;
-                env_1.hasError = true;
-            }
-            finally {
-                __disposeResources(env_1);
-            }
-        },
-        /**
-         * Re-attach to a running session and drain one more window.
-         *
-         * **A session whose container was replaced is reported, not thrown.** The
-         * attachment is the first thing to notice a replacement, and the caller is a
-         * chunk loop with a cursor it will happily keep presenting: a throw here
-         * retries the same dead id until the chunk allowance runs out, and the run
-         * ends on a stack trace that names neither the session nor the cause. A
-         * terminal outcome ends it at the first attempt instead, with the exit code
-         * the runtime uses for a killed process and an explanation on `stderr`,
-         * which is exactly the channel a session that died without a result line
-         * already reports through.
-         *
-         * **What it must not say is that starting over is safe.** A session is an
-         * agent: by the time its container went, it may have written files that
-         * reached the workspace, committed, pushed, or called something outside
-         * altogether. None of that is visible from here — only that the attachment
-         * is gone — so the honest report is what is known plus where to look, and
-         * the decision belongs to whoever can read the durable state.
-         */
-        async resume(runtime, cursor, sinks = {}) {
-            const env_2 = { stack: [], error: void 0, hasError: false };
-            try {
-                let handle;
-                try {
-                    handle = await attachRun(runtime, cursor);
-                }
-                catch (err) {
-                    if (!isExecLost(err))
-                        throw err;
-                    console.warn("[claude-code] the session's container was replaced", {
-                        execId: cursor.execId,
-                        err: String(err)
-                    });
-                    return {
-                        done: true,
-                        cursor,
-                        progress: [],
-                        exitCode: -1,
-                        stderr: "the container holding this session was replaced, so the session " +
-                            "was lost before it finished and cannot be re-attached. What it had " +
-                            "already written to the workspace is still there, and anything it " +
-                            "did outside the workspace — a commit, a push, a request — has " +
-                            "already happened. Check the workspace and the branch before " +
-                            "starting this subtask again, since a rerun repeats from the " +
-                            "beginning."
-                    };
-                }
-                const session = __addDisposableResource(env_2, handle, false);
-                return await drainRun(session, cursor, { windowMs, ...sinks });
-            }
-            catch (e_2) {
-                env_2.error = e_2;
-                env_2.hasError = true;
-            }
-            finally {
-                __disposeResources(env_2);
-            }
-        },
-        /** Stop a session — `SIGTERM`, so its own process tree goes with it. */
-        async stop(runtime, subtaskId) {
-            await killRun(runtime, execIdFor(subtaskId));
-        },
-        /**
-         * Is any credential usable right now, and if not, when?
-         *
-         * The same question {@link egress} answers per request, asked ahead of time
-         * so a host can decline to start a session it cannot pay for. That is not a
-         * micro-optimisation: an invocation carries an 18.7-27k-token cached prefix
-         * before it does anything, so starting one and letting the gateway refuse
-         * its first model call costs a container start and that prefix to learn what
-         * this returns for free — and reports it as a failed run rather than as a
-         * rate limit with a time on it.
-         *
-         * Reads only. Nothing here marks anything spent.
-         */
-        credentials: (store) => credentialPool({ credentials: config.credentials, store }).lead(),
-        /**
-         * The `Fetcher` the workspace object installs as its egress policy.
-         *
-         * `store` is an **argument rather than a config field**, and that is the
-         * point: the credential pool's state belongs to whichever object has
-         * storage, and this same config object is also held by the parent's plugin
-         * list and by the subagent facet, neither of which has any. Making it a
-         * field would force both of them to invent one.
-         */
-        egress: (store) => claudeCodeEgress({
-            credentials: config.credentials,
-            store,
-            // Forwarded only when set. Defaulting it to `[]` here would turn "the
-            // host said nothing" into "Anthropic only", which is the one reading
-            // the three-way semantics exist to keep distinct.
-            ...(config.restrictToHosts === undefined
-                ? {}
-                : { restrictToHosts: config.restrictToHosts }),
-            label: CLAUDE_CODE_TYPE
-        })
-    };
-}
-/**
- * The plugin.
- *
- * `subtaskType` and nothing else: no `toolFamilies`, because Claude Code's tools
- * are its own, and no `capability` on the plugin, because a plugin declaring a
- * subtask type puts its capability block on the **type** — declaring both makes
- * the main agent read the same advice twice per round.
- */
-export function claudeCode(config) {
-    // Read once at construction so a deployment that forgot the secret fails at DO
-    // start with a sentence naming this plugin, rather than at the first model
-    // call inside a subtask somebody is waiting on. The thunk is still what the
-    // gateway calls per request, so a rotation is picked up.
-    if (config.credentials().filter(Boolean).length === 0) {
-        throw new Error("claude-code: no credentials. Set at least one `claude setup-token` " +
-            "credential and pass it as " +
-            "`credentials: () => [env.CLAUDE_CODE_OAUTH_TOKEN_1]`.");
-    }
-    return definePlugin({
-        key: "claude-code",
-        contractVersion: PLUGIN_CONTRACT_VERSION,
-        subtaskType: CLAUDE_CODE_SPEC,
-        /**
-         * Hand each subtask the workspace its parent is working in.
-         *
-         * This runs on the **parent** — core dispatches `resolveRuntime` to the
-         * plugin that declared the subtask type, which is this one — so
-         * `workspaceName()` resolves here and would throw in the facet, where
-         * `callerKey()` is deliberately unavailable. Whatever this returns arrives
-         * at `executeChunk` as its `runtime` argument, and the host reads the name
-         * back out with {@link WORKSPACE_RUNTIME_KEY}.
-         *
-         * Without it a delegated session has no way to address the Durable Object
-         * holding the checkout it was told to work in — and it cannot be a subtask
-         * param instead, because those are rendered to the delegating model and a
-         * model-authored workspace name would let it name somebody else's.
-         */
-        // Annotated rather than inferred: without it TypeScript narrows the
-        // plugin's runtime generic to this one key, which then fails to accept a
-        // plain `SubtaskRuntime` anywhere else.
-        resolveRuntime: async () => ({
-            [WORKSPACE_RUNTIME_KEY]: config.workspaceName()
-        })
-        // **No `requires.secrets`, and it is not an omission.** It named
-        // `CLAUDE_CODE_OAUTH_TOKEN` while there was exactly one credential with a
-        // name this package could know. The pool's entries are host-named — a
-        // deployment may call them anything and may have three — so there is no
-        // name left to declare. The property `requires` bought is kept by the
-        // `credentials()` check above, which is strictly better: it fails at DO
-        // start on the *value* being absent rather than on a name being unset.
-    });
-}
+export { claudeCodeModel } from "./model.js";
+export { claudeCodeSession } from "./session.js";
+export { CLAUDE_CODE_AGENT, CLAUDE_CODE_WRITE_INPUT } from "./spec.js";
 export { ANTHROPIC_HOST, claudeCodeEgress } from "./egress.js";
+export { VERIFIED_CLAUDE_CODE_VERSION } from "./verified.js";
+export { GITHUB_HOSTS, GITHUB_TOKEN_PLACEHOLDER } from "./github.js";
 export { credentialPool, readRefusal, readRateLimitEvent } from "./credentials.js";
-export { buildLaunch, CLAUDE_EXEC_PREFIX, CREDENTIAL_PLACEHOLDER, execIdFor, freshCursor } from "./run.js";
+export { buildLaunch, CLAUDE_EXEC_PREFIX, CREDENTIAL_PLACEHOLDER, execIdFor, followUpExecIdFor, freshCursor } from "./run.js";
 export { parseStream, toProgress, RATE_LIMIT_OK } from "./events.js";
-export { CLAUDE_CODE_CAPABILITY, CLAUDE_CODE_RECIPE, CLAUDE_CODE_SPEC, CLAUDE_CODE_TYPE, WORKSPACE_RUNTIME_KEY } from "./recipe.js";
-export { DEFAULT_PERMISSION_MODE, DEFAULT_TIMEOUT_MS, DEFAULT_WINDOW_MS } from "./config.js";
+export { DEFAULT_PERMISSION_MODE, DEFAULT_TIMEOUT_MS } from "./config.js";

package/dist/claude-code/model.d.ts

@@ -0,0 +1,152 @@
+import type { LanguageModel } from "ai";
+import type { ArtifactEntryDetail } from "@dynamicagents/core/artifacts";
+import type { ClaudeCodeConfig, PermissionMode } from "./config.js";
+import type { ClaudeCodeResult, RateLimitInfo } from "./events.js";
+import { type SessionRuntime } from "./run.js";
+/**
+ * A Claude Code session as a sub-agent's **model**.
+ *
+ * Claude Code brings its own tools, its own loop and its own context, so there
+ * is nothing for Think to drive but the one call that runs it — and making that
+ * call the model is what puts the session under Think's recovery. A turn cut by
+ * an eviction or a deploy is continued; the continuation calls `doStream`
+ * again, and every step below it has already taken is stored, so it resumes
+ * where it was: the session is re-attached from its cursor, and a report
+ * already made is emitted again rather than made again.
+ *
+ * ## The report is the only text
+ *
+ * A run's result is what its assistant messages say, so narration streamed as
+ * text would become the result and bury the report. What the session says as
+ * it works goes to the parent as notes instead, through `note`. Nothing else is
+ * streamed at all: Think's stall watchdog is off, so a silent stream is not cut.
+ */
+/** The provider interface this implements, read off `ai` rather than imported. */
+type LanguageModelV3 = Extract<LanguageModel, {
+    specificationVersion: "v3";
+}>;
+/** How one exec of a session ended. */
+export interface SessionEnd {
+    exitCode: number;
+    /** Absent when the process died without ever emitting a `result` line. */
+    result?: ClaudeCodeResult;
+    /** Bounded, and only when there is no `result` to explain the exit. */
+    stderr?: string;
+    /** The subscription bucket as the client last reported it, if it did. */
+    rateLimit?: RateLimitInfo;
+    /**
+     * The Claude Code session id, from the `init` line by way of the drain's
+     * cursor — see {@link file://./run.ts DrainCursor.sessionId}.
+     *
+     * Here as well as on `result` because the sessions worth continuing are often
+     * the ones with no result: a session ended by its time limit, a cancel or a
+     * container rollout reports none, and this is then the only handle to the
+     * conversation it got half-way through.
+     */
+    sessionId?: string;
+}
+/**
+ * A session's handle, as the host is told it.
+ *
+ * Told **twice**: once with the id alone, as soon as the session's `init` line
+ * names it, and once with the session's end. The first call is what makes a
+ * session that is about to be killed resumable at all; the second says how the
+ * conversation it left stands.
+ *
+ * So a host keys its record on `sessionId` and keeps an `end` once it has one: a
+ * recovered turn can report the same id again without an end, and a record that
+ * let that erase the end would forget how the session finished.
+ */
+export interface SessionRecord {
+    sessionId: string;
+    /** Absent on the first call; the session's end on the second. */
+    end?: SessionEnd;
+}
+/** What a run amounted to, handed to `report`. */
+export interface SessionOutcome {
+    /** The session's own end. */
+    session: SessionEnd;
+    /** The follow-up's end, when `followUp` asked for one. */
+    followUp?: SessionEnd;
+}
+/** The container a session runs in, released when the call that opened it ends. */
+export interface SessionWorkspace extends Disposable {
+    readonly runtime: SessionRuntime;
+}
+export interface ClaudeCodeModelOptions {
+    config: ClaudeCodeConfig;
+    /**
+     * Opens the run's container — the workspace the run's `runtime()` names.
+     * Called again to re-attach after a cut stream, so each call should reach the
+     * object through a new stub rather than one held from the last.
+     */
+    workspace: () => Promise<SessionWorkspace>;
+    /** The sub-agent's own storage, where every step's outcome is kept. */
+    storage: DurableObjectStorage;
+    /** The sub-agent's name, which is the run's id. The exec ids derive from it. */
+    runId: string;
+    /** The checkout. */
+    dir: string;
+    /**
+     * A JSON Schema the session's answer must match. Its `result` then carries
+     * the answer as `structured`, for `report` to read.
+     */
+    jsonSchema?: Record<string, unknown>;
+    /**
+     * This run's mode, over {@link file://./config.ts ClaudeCodeConfig.permissionMode}.
+     *
+     * A planning run is a writing session under `plan` with a `jsonSchema`: it
+     * reads, edits nothing, and answers through `StructuredOutput` rather than an
+     * approval nobody is there to give. Carrying the plan out is a later run that
+     * resumes it with `fork` under the config's mode — the CLI takes a new
+     * `--permission-mode` on `--resume` — so the plan's own conversation stays
+     * whole for an edit.
+     */
+    permissionMode?: PermissionMode;
+    /**
+     * A Claude Code conversation for this run to continue instead of starting one
+     * — see {@link file://./session.ts StartSession.resume}.
+     *
+     * Resolved by the host, in `prepare`, against whatever it recorded through
+     * {@link ClaudeCodeModelOptions.onSession}: which conversations exist in a
+     * workspace, and which of them a caller may continue, are the host's
+     * questions. The run's prompt is then the next user turn — its `brief` hook
+     * is the place to say what changed and nothing the session already holds.
+     */
+    resume?: {
+        sessionId: string;
+        fork?: boolean;
+    };
+    /**
+     * Files one note on the parent's transcript: the sub-agent's `note`. A tool
+     * call, its result and the session's own start and end arrive with a card —
+     * see {@link file://./cards.ts Card}.
+     */
+    note: (key: string, text: string, detail?: ArtifactEntryDetail) => Promise<void>;
+    /**
+     * The session's handle, as soon as there is one and again when the session
+     * ends — see {@link SessionRecord}.
+     *
+     * Best-effort, like `note`: a throw is logged and the run goes on. Recording a
+     * handle is what makes a later run able to continue this conversation, and
+     * losing that is not worth losing the session over.
+     */
+    onSession?: (record: SessionRecord) => Promise<void>;
+    /**
+     * The session's prompt, from the task the parent sent. Defaults to the task.
+     *
+     * Runs once per run, before the session starts, and its answer is kept. A
+     * throw fails the run with its message — how a host refuses a run it cannot
+     * pay for, or has nothing to work in.
+     */
+    brief?: (task: string) => Promise<string>;
+    /**
+     * One more turn for a session that ended, or `undefined`. Asked once; its
+     * answer is kept, so a resumed run does not ask again.
+     */
+    followUp?: (session: SessionEnd) => Promise<string | undefined>;
+    /** The text the parent receives. Run once, and kept. */
+    report: (outcome: SessionOutcome) => Promise<string>;
+}
+export declare function claudeCodeModel(options: ClaudeCodeModelOptions): LanguageModelV3;
+export {};