@dynamicagents/plugins 0.14.0 → 0.15.0

package/dist/claude-code/egress.js

@@ -1,327 +1,71 @@
-import { credentialPool, readRefusal } from "./credentials.js";
-import { GITHUB_HOSTS, githubAuthorization, githubError, presentsPlaceholder } from "./github.js";
+import { ANTHROPIC_PLACEHOLDER_HOST } from "./harness-wire.js";
+import { readRefusal, sharedPool } from "./credentials.js";
 /**
- * `@dynamicagents/plugins/claude-code` — the container's only way out.
+ * The Anthropic credential, swapped in on the Worker side of a sandbox.
  *
- * `egress: { mode: "http-gateway", gateway }` makes `computerd` intercept every
- * outbound request in the container and tunnel it back to the workspace Durable
- * Object, which reconstructs it against its original absolute URL and hands it
- * here. So this function sits on the **Worker side of the trust boundary** and
- * sees the whole of what the container tries to reach.
+ * The CLI holds a placeholder OAuth token, this sets the pool's lead as the
+ * Bearer, and a refusal that spends or rejects the credential moves the lead
+ * and tells the CLI to retry on the next one — `./credentials.ts` reads the
+ * refusal. A sandbox's egress entrypoint is stateless, so the pool lives in the
+ * sandbox the request came from, reached through `call.sandbox()` as a
+ * {@link CredentialLease}.
  *
- * Intercepting HTTPS means terminating it, which has a cost this file does not
- * pay and the container does: the runtime presents its own certificate, so an
- * image that has not installed the interception CA has no working HTTPS client
- * at all — not even `npm`. Nothing here can fix that from the Worker side; the
- * image's entrypoint has to, and the README's "Your image must trust the
- * interception CA" section is the whole of what that takes.
- *
- * That position is what makes three otherwise-hard things easy, and they are the
- * reason this file exists rather than a plain allowlist:
- *
- * 1. **The real credential never enters the container.** Claude Code is launched
- *    with a placeholder; the swap happens here. A `postinstall` script in a
- *    cloned repository can read every environment variable the container has and
- *    still learn nothing — which is the repository's standing rule ("hand it the
- *    action, not the credential") applied to a process nobody can constrain. A
- *    GitHub token, when configured, is held the same way — see `./github.ts`.
- * 2. **Any restriction that is applied is total.** Not a policy the container
- *    cooperates with; the only route out. Restriction is **off by default** —
- *    see {@link EgressConfig.restrictToHosts} for why.
- * 3. **Exhaustion is seen, so it can be routed around.** This is the only place
- *    Anthropic's actual response is visible, and therefore the only place that
- *    can learn a subscription bucket is empty. See {@link EgressConfig.store}
- *    and `credentials.ts`.
- *
- * ## What this deliberately does not do
- *
- * It does not meter, and a budget gate must not come back: an estimate of spend
- * is a guess about a bucket nobody can read, moves only once per run, and the
- * bucket announces the answer exactly — see the docblock in `credentials.ts`.
- *
- * And it does not, by default, **bound exfiltration**. The container holds the
- * checkout, and with no restriction configured it can send it anywhere. That is
- * a deliberate default rather than an oversight — the reasoning is on
- * {@link EgressConfig.restrictToHosts} — and what it means for a reader is that
- * the containment here is "the container holds no credential", full stop. Do not
- * read a host restriction that is switched off as a boundary that exists.
+ * The CLI reaches this over plain HTTP to a placeholder host the harness
+ * intercepts, so nothing in the container terminates TLS. The daemon points
+ * the CLI at it (`./daemon/index.ts`), after the deployment's own environment,
+ * so the rule sets no `env`.
  */
 /** Anthropic's API host — the one destination that gets a credential. */
 export const ANTHROPIC_HOST = "api.anthropic.com";
-/**
- * Hosts that name **this** side of the boundary, refused whatever the policy.
- *
- * The reason is a difference between the two egress modes that is easy to miss.
- * Under `mode: "direct"` the container's traffic leaves from the container's own
- * network position. Under `http-gateway` **the Worker makes the request**, so an
- * unrestricted policy hands the container the Worker's reach rather than its
- * own — and `computer.internal` is the loopback the intercept itself rides on.
- * Bouncing a request back into it is never a legitimate fetch, so it is refused
- * before any policy is consulted.
- *
- * A workspace that overrides `egressHost` on its `ContainerBackend` should add
- * that name here; the default is what the backend uses when nothing says
- * otherwise.
- */
-const NEVER_ALLOWED = new Set([
-    "computer.internal",
-    "localhost",
-    "127.0.0.1",
-    "::1",
-    "0.0.0.0"
-]);
-/**
- * The hostname a rule should be matched against, not the one the URL reports.
- *
- * `URL.hostname` is not canonical for this purpose in two ways that both defeat
- * an exact-match set:
- *
- * - **IPv6 keeps its brackets.** `new URL("http://[::1]/").hostname` is
- *   `"[::1]"`, so a set holding `"::1"` never matches.
- * - **A trailing dot survives.** `computer.internal.` and `api.anthropic.com.`
- *   are the same destinations as their undotted forms and compare unequal.
- *
- * The second one cuts both ways and is the more dangerous: an undotted
- * comparison against {@link ANTHROPIC_HOST} would send `api.anthropic.com.` down
- * the *non-Anthropic* branch, which strips the credential — fail-safe, but it
- * also means a spent bucket is never noticed on that spelling.
- */
-function canonicalHost(url) {
-    let host = url.hostname.toLowerCase();
-    if (host.startsWith("[") && host.endsWith("]"))
-        host = host.slice(1, -1);
-    if (host.endsWith("."))
-        host = host.slice(0, -1);
-    return host;
-}
-/** Headers that carry a credential, stripped from anything not Anthropic. */
-const CREDENTIAL_HEADERS = [
-    "authorization",
-    "x-api-key",
-    "proxy-authorization"
-];
-/**
- * What a rotated request is told to wait.
- *
- * One second, not zero: the point is to get the client retrying promptly onto
- * the credential that just became the lead, not to remove its backoff. Claude
- * Code honours `retry-after`, so leaving the upstream value in place — four
- * hours, on a spent 5-hour bucket — would stall the session rather than rotate
- * it. This rewrite is what turns the client's own retry into the rotation, and
- * it is why nothing here has to buffer a request body.
- */
+/** The one-second retry that lands a rotated request on the next credential. */
 const ROTATED_RETRY_AFTER = "1";
-/** How much of an unrecognised body to keep in the log. */
+/** How much of a refusal's body the log keeps. */
 const CAPTURE_BYTES = 2048;
-/** The Anthropic error shape, so the client recognises what it is being told. */
-function apiError(type, message, status, headers = {}) {
-    return new Response(JSON.stringify({ type: "error", error: { type, message } }), {
-        status,
-        headers: { "content-type": "application/json", ...headers }
-    });
-}
-/** Every header on a response, for the capture log. */
-function headerMap(headers) {
-    const out = {};
-    headers.forEach((value, key) => {
-        out[key] = value;
-    });
-    return out;
-}
-/**
- * Build the `Fetcher` a `WorkspaceEgressPolicy` takes.
- *
- * A real object rather than a cast: `Fetcher` requires `connect` as well as
- * `fetch`, and container egress is HTTP only, so `connect` throws a sentence
- * naming why instead of being absent. If a future `computerd` ever opens a raw
- * socket through this policy, the failure says so rather than arriving as
- * `undefined is not a function` several frames away.
- */
-export function claudeCodeEgress(config) {
-    // Resolved once. `undefined` is unrestricted; a list — including an empty one
-    // — is a restriction that always admits Anthropic.
-    const allowed = config.restrictToHosts === undefined
-        ? undefined
-        : new Set([ANTHROPIC_HOST, ...config.restrictToHosts]);
-    const tag = config.label
-        ? `claude-code-egress:${config.label}`
-        : "claude-code-egress";
-    const now = config.now ?? Date.now;
-    const pool = credentialPool({
-        credentials: config.credentials,
-        store: config.store,
-        ...(config.now ? { now: config.now } : {})
-    });
-    /**
-     * What the client is told when no credential in the pool is usable.
-     *
-     * Two different answers, because they are two different situations and the
-     * client's correct reaction differs. A pool with a `retryAt` **will** recover
-     * on its own, so it is an honest `429` carrying the real wait — the client
-     * backs off, and if the wait outlives the session the run ends cleanly having
-     * said why. A pool with none will not: every entry was rejected as invalid, or
-     * none is configured. That needs an operator, and a `429` there would put the
-     * client in a retry loop against a wall for the rest of the session.
-     */
+/** The egress rule of a sandbox that runs Claude Code. */
+export function claudeCodeEgress(options = {}) {
+    const tag = options.label ?? "claude-code-egress";
+    const now = options.now ?? Date.now;
+    const poolOf = options.pool ??
+        ((call) => call.sandbox());
     const spent = (lead) => {
         if (lead.retryAt === undefined) {
             console.error(`[${tag}] no usable credential, and none will recover on its own`);
-            return apiError("authentication_error", "no Anthropic credential in this deployment's pool is usable and none " +
-                "will recover on its own — every entry was rejected as invalid, or " +
-                "none is configured", 500);
+            return apiError("authentication_error", "no Anthropic credential in this deployment's pool is usable and none will recover " +
+                "on its own — every entry was rejected as invalid, or none is configured", 500);
         }
         const waitMs = lead.retryAt - now();
         console.error(`[${tag}] every credential in the pool is rate limited`, {
             retryAt: new Date(lead.retryAt).toISOString()
         });
         return apiError("rate_limit_error", "every Anthropic credential in this deployment's pool is rate limited; " +
-            `the earliest resets at ${new Date(lead.retryAt).toISOString()}`, 429, 
-        // The **real** wait, not the rotation's one second. There is nothing to
-        // rotate to, so shortening it here would only spin the client.
-        { "retry-after": String(Math.max(1, Math.ceil(waitMs / 1000))) });
+            `the earliest resets at ${new Date(lead.retryAt).toISOString()}`, 429, { "retry-after": String(Math.max(1, Math.ceil(waitMs / 1000))) });
     };
-    const handle = async (request) => {
-        let url;
-        try {
-            url = new URL(request.url);
-        }
-        catch {
-            return apiError("invalid_request_error", "unparseable egress URL", 400);
-        }
-        const host = canonicalHost(url);
-        // Before any policy: this side of the boundary is never a destination.
-        if (NEVER_ALLOWED.has(host)) {
-            console.warn(`[${tag}] refused a request aimed back at the gateway`, {
-                host,
-                method: request.method
-            });
-            return apiError("permission_error", `${url.hostname} names the egress gateway itself and is never ` +
-                "reachable from inside the workspace", 403);
-        }
-        if (allowed && !allowed.has(host)) {
-            // Logged, because this is the line that makes a failing install
-            // intelligible. A container that cannot reach its registry produces a
-            // hundred lines of npm output and no mention of egress.
-            console.warn(`[${tag}] refused a request outside the host restriction`, {
-                host,
-                method: request.method
-            });
-            return apiError("permission_error", `${host} is outside this workspace's egress host restriction`, 403);
-        }
-        if (config.githubToken && GITHUB_HOSTS.has(host)) {
-            return await toGitHub(request, url, config.githubToken);
-        }
-        const headers = new Headers(request.headers);
-        if (host !== ANTHROPIC_HOST) {
-            // The placeholder must not leave the boundary either. It is worthless to
-            // whoever receives it, but a credential-shaped header sent to a third
-            // party is a credential leak in every log it lands in.
-            for (const name of CREDENTIAL_HEADERS)
-                headers.delete(name);
-            return await fetch(new Request(url, new Request(request, { headers })));
-        }
-        /**
-         * Anthropic over TLS, and only that, from here down.
-         *
-         * Checked **before** a credential is read, let alone attached. Nothing stops
-         * a process in the container asking for `http://api.anthropic.com/…`, and
-         * this function would otherwise fetch it — putting a real subscription token
-         * on the wire in plaintext, from the Worker, at the request of code the
-         * workspace does not trust. The host matched; the scheme is the rest of the
-         * question.
-         */
-        if (url.protocol !== "https:") {
-            console.warn(`[${tag}] refused a plaintext request to Anthropic`, {
-                protocol: url.protocol,
-                method: request.method
-            });
-            return apiError("permission_error", `${ANTHROPIC_HOST} is reachable over https only; a credential is never ` +
-                "attached to a plaintext request", 403);
-        }
+    const handle = async (call) => {
+        const pool = poolOf(call);
         const lead = await pool.lead();
         if (!lead.ok)
             return spent(lead);
-        /**
-         * The swap, and it is the whole point of the file.
-         *
-         * `authorization` is set and `x-api-key` removed because that is the shape
-         * the sanctioned client sends: `authorization: Bearer …` with no
-         * `x-api-key` at all. Everything else is forwarded
-         * untouched: the `anthropic-beta` list (which carries
-         * `claude-code-20250219` and `oauth-2025-04-20`, almost certainly part of
-         * what marks the request as coming from the client) and the `user-agent`
-         * are not ours to normalise or reorder.
-         *
-         * Claude Code also sends an unauthenticated `HEAD /api/hello` preflight.
-         * It gets a credential too, harmlessly, and nothing keys on the path: a
-         * bucket that is empty is empty for every endpoint.
-         */
-        headers.set("authorization", `Bearer ${lead.token}`);
+        // `authorization` set and `x-api-key` removed: the shape the sanctioned
+        // client sends. Everything else — the `anthropic-beta` list, the user agent
+        // — is forwarded untouched; it is not ours to normalise.
+        const headers = new Headers(call.request.headers);
+        headers.delete("host");
+        headers.delete("proxy-authorization");
         headers.delete("x-api-key");
-        const response = await fetch(new Request(url, new Request(request, { headers })));
-        // The overwhelming majority: a normal answer, streamed straight back with
-        // its body untouched. Nothing below this line runs on the hot path.
+        headers.set("authorization", `Bearer ${lead.token}`);
+        const hasBody = call.request.method !== "GET" && call.request.method !== "HEAD";
+        const response = await fetch(call.target, {
+            method: call.request.method,
+            headers,
+            ...(hasBody ? { body: call.request.body } : {}),
+            redirect: "manual"
+        });
         if (response.status !== 429 &&
             response.status !== 401 &&
             response.status !== 403) {
             return response;
         }
-        return await rotate(request, response, lead.id, lead.index);
-    };
-    /**
-     * A request to GitHub: anonymous unless it presents the placeholder,
-     * which is swapped for the real token over https only.
-     *
-     * `redirect: "manual"`, so the token rides only the request it was swapped
-     * into: a redirect goes back to the client, whose next request crosses this
-     * gateway again and is judged on its own host.
-     */
-    const toGitHub = async (request, url, githubToken) => {
-        const headers = new Headers(request.headers);
-        const presented = presentsPlaceholder(headers.get("authorization"));
-        for (const name of CREDENTIAL_HEADERS)
-            headers.delete(name);
-        if (!presented) {
-            return await fetch(new Request(url, new Request(request, { headers })));
-        }
-        if (url.protocol !== "https:") {
-            console.warn(`[${tag}] refused a plaintext request to GitHub`, {
-                host: url.hostname,
-                method: request.method
-            });
-            return githubError(`${url.hostname} is reachable over https only; a credential is never ` +
-                "attached to a plaintext request", 403);
-        }
-        const token = githubToken();
-        if (!token) {
-            console.error(`[${tag}] a session asked for GitHub with no token set`);
-            return githubError("no GitHub token is configured for this deployment, so nothing can " +
-                "be done as its account", 401);
-        }
-        headers.set("authorization", githubAuthorization(presented, token));
-        return await fetch(new Request(url, new Request(request, { headers, redirect: "manual" })));
-    };
-    /**
-     * Read a refusal, move the lead if it earned one, and shape what the client
-     * sees so its own retry lands on the new credential.
-     */
-    const rotate = async (request, response, 
-    /** Which credential sent this — see `CredentialPool.spend`. */
-    id, 
-    /** Its slot, for the log line only. An operator reads "1", not a hash. */
-    index) => {
-        const at = now();
-        const verdict = readRefusal(response, at);
-        /**
-         * Capture the whole thing, every time.
-         *
-         * **No genuine subscription-exhaustion `429` has been observed through this
-         * path** — a raw-API refusal is a different response — so the rules in
-         * `readRefusal` are inferences from the documented API rate limits. This log
-         * is the instrument that replaces
-         * them with a fact, and it costs nothing: these statuses are rare, and the
-         * body of one is a few hundred bytes.
-         */
+        const verdict = readRefusal(response, now());
         const body = await response
             .clone()
             .text()
@@ -329,49 +73,60 @@ export function claudeCodeEgress(config) {
             .catch(() => "<unreadable>");
         console.warn(`[${tag}] Anthropic refused a request`, {
             status: response.status,
-            method: request.method,
-            credential: index,
+            method: call.request.method,
+            credential: lead.index,
             verdict: verdict?.kind ?? "unrecognised",
-            headers: headerMap(response.headers),
+            headers: Object.fromEntries(response.headers),
             body
         });
-        // Unrecognised, or an ordinary slow-down: not this credential's fault, so
-        // forward it exactly as it came. Rotating on a speed bump would retire a
-        // working credential for whatever window the header happened to name.
+        // Unrecognised, or an ordinary slow-down: not this credential's fault.
         if (!verdict || verdict.kind === "transient")
             return response;
         const next = verdict.kind === "invalid"
-            ? await pool.reject(id)
-            : await pool.spend(id, verdict.resetAt);
+            ? await pool.reject(lead.id)
+            : await pool.spend(lead.id, verdict.resetAt);
         if (!next.ok)
             return spent(next);
         console.warn(`[${tag}] rotated to the next credential`, {
-            from: index,
+            from: lead.index,
             to: next.index,
             reason: verdict.kind
         });
-        /**
-         * A `429` with a one-second `retry-after`, whatever the upstream status was.
-         *
-         * The status is rewritten for the `invalid` case and that is deliberate: a
-         * client does not retry a `401`, so passing one through would fail the run
-         * on a credential we have already stopped using. From the client's point of
-         * view "this did not work, try again shortly" is exactly true — the next
-         * attempt carries a different credential — and the operator-facing detail is
-         * in the log line above, which names the rejection explicitly.
-         */
+        // A 429 whatever the upstream said: a client does not retry a 401, and the
+        // next attempt carries a different credential.
         return apiError("rate_limit_error", verdict.kind === "invalid"
-            ? "that Anthropic credential was rejected; the gateway has moved to " +
-                "the next one in the pool — retry"
-            : "that Anthropic credential's limit is reached; the gateway has moved " +
-                "to the next one in the pool — retry", 429, { "retry-after": ROTATED_RETRY_AFTER });
+            ? "that Anthropic credential was rejected; the egress has moved to the next one in the pool — retry"
+            : "that Anthropic credential's limit is reached; the egress has moved to the next one in the pool — retry", 429, { "retry-after": ROTATED_RETRY_AFTER });
     };
     return {
-        fetch: (input, init) => handle(new Request(input, init)),
-        connect() {
-            throw new Error("the claude-code egress gateway is HTTP only; a raw socket cannot be " +
-                "credential-swapped or rotated, so it is refused rather than " +
-                "silently passed through");
+        name: "claude-code",
+        http: { [ANTHROPIC_PLACEHOLDER_HOST]: `https://${ANTHROPIC_HOST}` },
+        handle
+    };
+}
+function apiError(type, message, status, headers = {}) {
+    return new Response(JSON.stringify({ type: "error", error: { type, message } }), {
+        status,
+        headers: { "content-type": "application/json", ...headers }
+    });
+}
+/**
+ * The pool a sandbox object holds, for its RPCs to answer {@link CredentialLease}
+ * with — and `admit`, which a session start calls: a mark lasts one session.
+ */
+export function credentialHost(options) {
+    const key = options.key ?? "claude-credentials";
+    const store = {
+        read: async () => (await options.storage.get(key)) ?? [],
+        write: async (states) => {
+            await options.storage.put(key, states);
         }
     };
+    const pool = sharedPool({ credentials: options.credentials, store });
+    return {
+        lead: () => pool.lead(),
+        spend: (id, resetAt) => pool.spend(id, resetAt),
+        reject: (id) => pool.reject(id),
+        admit: () => pool.reopen()
+    };
 }

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

@@ -53,20 +53,16 @@ export interface ClaudeCodeUsage {
  * What the client knows about the subscription bucket it is drawing on.
  *
  * The one thing on this stream that is about the *deployment* rather than the
- * run. This plugin's entry point describes the 5-hour and weekly limits as
- * routed around rather than predicted, because the gateway only learns a bucket
- * is empty when Anthropic refuses a request — this is the client saying so in
- * advance, on every session.
+ * run. It is read from the headers of Anthropic's own responses, so it says
+ * nothing the egress gateway has not already seen — it is what lets the parent
+ * hear it.
  *
  * `resetsAt` is **seconds**, not milliseconds, which is the one field here it is
  * possible to get silently wrong: a value handed to `Date` unconverted lands in
- * January 1970, and a credential marked spent until then reads as usable.
+ * January 1970.
  */
 export interface RateLimitInfo {
-    /**
-     * {@link RATE_LIMIT_OK} on a healthy bucket. Any other value is
-     * **unclassified** — no consumer should read one as exhaustion.
-     */
+    /** One of {@link RATE_LIMIT_STATUSES}, or a value nobody has named yet. */
     status: string;
     /** Unix **seconds** at which this bucket refills. */
     resetsAt?: number;
@@ -236,17 +232,18 @@ export declare const LIVE_SLACK_MS = 5000;
  * block is timed.
  */
 export declare function parseStream(buffer: string, clock?: ParseClock): ParsedStream;
+/** The status a healthy bucket reports. */
+export declare const RATE_LIMIT_OK = "allowed";
 /**
- * The status a healthy bucket reports, and the only one ever observed.
+ * Every status the client has reported: {@link RATE_LIMIT_OK},
+ * `allowed_warning` once the bucket is nearly spent, and `rejected` once
+ * Anthropic has refused a request.
  *
- * **Every other value is unclassified, not a refusal.** Nothing here knows what
- * a non-`allowed` status means, and the one place that decides whether a
- * credential is spent — `readRateLimitEvent` in this package's `credentials.ts`
- * — recognises none of them, deliberately: retiring a working credential on a
- * guess is the expensive half of that trade. What an unrecognised status earns
- * is a note and a log, so somebody can name it.
+ * **None of them retires a credential.** `rejected` follows a refusal the
+ * egress gateway has already read off the response itself — see `readRefusal`
+ * in `./credentials.ts` — so acting on it again would add nothing.
  */
-export declare const RATE_LIMIT_OK = "allowed";
+export declare const RATE_LIMIT_STATUSES: ReadonlySet<string>;
 /**
  * Turn events into progress notes for the parent's transcript.
  *

package/dist/claude-code/events.js

@@ -366,17 +366,22 @@ function readTime(value) {
 function isRealDate(ms) {
     return Number.isFinite(ms) && !Number.isNaN(new Date(ms).getTime());
 }
+/** The status a healthy bucket reports. */
+export const RATE_LIMIT_OK = "allowed";
 /**
- * The status a healthy bucket reports, and the only one ever observed.
+ * Every status the client has reported: {@link RATE_LIMIT_OK},
+ * `allowed_warning` once the bucket is nearly spent, and `rejected` once
+ * Anthropic has refused a request.
  *
- * **Every other value is unclassified, not a refusal.** Nothing here knows what
- * a non-`allowed` status means, and the one place that decides whether a
- * credential is spent — `readRateLimitEvent` in this package's `credentials.ts`
- * — recognises none of them, deliberately: retiring a working credential on a
- * guess is the expensive half of that trade. What an unrecognised status earns
- * is a note and a log, so somebody can name it.
+ * **None of them retires a credential.** `rejected` follows a refusal the
+ * egress gateway has already read off the response itself — see `readRefusal`
+ * in `./credentials.ts` — so acting on it again would add nothing.
  */
-export const RATE_LIMIT_OK = "allowed";
+export const RATE_LIMIT_STATUSES = new Set([
+    RATE_LIMIT_OK,
+    "allowed_warning",
+    "rejected"
+]);
 /** Read a `result` line. Total by construction — a missing field reads as zero. */
 function readResult(event) {
     const apiErrorStatus = event.api_error_status;
@@ -504,10 +509,9 @@ function describe(event) {
              * session — one note per `rate_limit_event` would be the noisiest thing on
              * the stream and would say "allowed" each time.
              *
-             * The test is inverted deliberately: an unrecognised status produces a
-             * note rather than silence. The statuses are a vendor's and only
-             * {@link RATE_LIMIT_OK} has been seen, so a new one meaning "nearly out"
-             * should surface as prose somebody reads, not be assumed benign.
+             * The test is inverted deliberately: anything but {@link RATE_LIMIT_OK}
+             * is a note — a bucket nearly spent or refused, and a status nobody has
+             * named yet, which should surface as prose rather than be assumed benign.
              */
             return event.info.status === RATE_LIMIT_OK
                 ? undefined
@@ -517,9 +521,9 @@ function describe(event) {
                             ? ""
                             : ` until ${new Date(event.info.resetsAt * 1000).toISOString()}`)
                 };
-        // `init`'s session id is a handle as well as news: it reaches the host on
-        // the drain's cursor — see `DrainCursor.sessionId` in ./run.ts — where
-        // something can record it and resume with it.
+        // `init`'s session id is a handle as well as news: the daemon's parser
+        // hands it to the host — see `./daemon/index.ts` — where something can
+        // record it and resume with it.
         case "init":
             return initCard(event);
         case "result":

package/dist/claude-code/harness-wire.d.ts

@@ -0,0 +1,45 @@
+import type { NoteData } from "@dynamicagents/core/subagent";
+import type { ClaudeCodeResult, RateLimitInfo } from "./events.js";
+/**
+ * What the daemon in a sandbox image and the host model must spell
+ * identically, in one module both import. The harness stores a turn's messages
+ * and its outcome, and nothing else the daemon reports, so everything the host
+ * reads travels as one of those.
+ */
+/**
+ * How one turn of a session ended. The harness keeps an operation's outcome as
+ * one string — the text of a turn that was answered, or the reason one was not
+ * — so the whole end travels in it: the CLI's own `result` line, the
+ * subscription bucket it last reported, its session id, and for a process that
+ * died with no result, its exit code and the end of its stderr.
+ */
+export interface RunEnd {
+    result?: ClaudeCodeResult;
+    rateLimit?: RateLimitInfo;
+    sessionId?: string;
+    /** Only when there is no `result`: the process ended without one. */
+    exitCode?: number | null;
+    stderr?: string;
+}
+/** The host the CLI is pointed at by `ANTHROPIC_BASE_URL`, which the sandbox intercepts. */
+export declare const ANTHROPIC_PLACEHOLDER_HOST = "anthropic.harness.internal";
+export declare function encodeRunEnd(end: RunEnd): string;
+/** The end in `text`, or `undefined` for a string the daemon did not write — the harness's own `container_lost`, say. */
+export declare function decodeRunEnd(text: string | undefined): RunEnd | undefined;
+/**
+ * One transcript note, as one message's only text part.
+ *
+ * The daemon makes the note (`./events.ts` `toProgress`) rather than sending
+ * the event, because a card clips its sections and an event does not: a tool's
+ * output is whatever the tool printed, and the harness stores every message in
+ * a row of the object's SQLite.
+ */
+export declare function encodeNote(note: NoteData): string;
+export declare function decodeNote(text: string): NoteData | undefined;
+/**
+ * The CLI's session id, as its own message: the handle a host records the
+ * moment the `init` line names it, since a session that dies before its end
+ * reports no other.
+ */
+export declare function encodeSessionId(sessionId: string): string;
+export declare function decodeSessionId(text: string): string | undefined;