@sema-agent/core 5.2.0 → 5.4.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 5.4.0 (2026-08-03)
+
+_The external-audit dunning batch closes end-to-end (small cases + all three cleared A-group debts), and the engine grows its outer brain-call guardrail. All additive or louder; major stays locked at 5._
+
+### Fixed
+
+- webfetch: the tool card follows the wired capability (a mount without a summarizer no longer advertises `prompt` in prose or schema), and an error response stops silently eating the caller's `prompt` (the error leg now carries the same "was NOT applied" disclosure family, naming the HTTP status). Error bodies are deliberately NOT fed to the summarizer (a 404 page dressed up as "the requested analysis" would be worse than the raw dump) — pinned as a negative control.
+- Background-agent poll projection: stop-attribution rides whenever the ROW carries it — the stale-running reaper settles rows as `failed` with `stoppedBy:"system"`, and the previous killed-only gate dropped that fact, making a reaped row indistinguishable from a natural failure. A row without the field still projects nothing.
+- Brains: an ERROR tool result now discloses the media it had to drop (`[N images omitted — …]`, both wire formats) instead of silently presenting an attachment-free error; the vision-degrade predicates and placeholder wording collapse into one construction point (`media-degrade.ts`).
+- Image read cap: the refusal for an oversized image without a downsampler now names `sharp` (declared in `optionalDependencies`) and the 64MB ceiling it unlocks — the cap itself is unchanged.
+
+- Background-command spool (RB-235 close-out): a LIVE writer's spool file is append-only — the reclaim truncate now waits for the writer to be terminal, closing the stat→truncate race window that silently destroyed whole buffered write blocks (external audit reproduced 8192-multiple losses on 5.3.0; the fix's own red-first run recorded 65536/720896/294912-byte ledger gaps). Cost, stated honestly: a live writer past the hard cap no longer has physical space reclaimed until it dies (the reader stays bounded and byte-accounted as before); the file is reclaimed wholesale at writer terminal. The live-rotation disclosure marker is retired with the race (structurally impossible now).
+
+### Added
+
+- `STALE_RUNNING_REAP_ATTRIBUTION` (exported): the reaper's settle wording reaches the package root, so an out-of-repo store twin can import the attribution instead of value-copying it against the contract kit (downstream pickup request).
+- `TaskSpec.limits.brainCallGuardrailMs` + `RunnerDeps.brainCallGuardrailMs` (RB-458): an OUTER per-call guardrail on how long the engine waits for one brain call — default 1 hour, `false`/`0` switches it off, invalid values refuse loudly at prepare. Independent of brain cooperation: expiry aborts the brain's signal AND stops the engine's own waiting at every await point, so a custom Brain that ignores `options.signal` can no longer wedge a run forever (previously the de-facto bound was an accidental property of the bundled fetch stack). A run stopped this way terminates loud with `TaskResult.errorCode = "brain.call_guardrail_timeout"`; walltime-budgeted runs keep their own (usually tighter) clocks — the two race and the earlier one wins.
+
+## 5.3.0 (2026-08-03)
+
+_The A2A arc: client+server legs land end-to-end (all additive), the workflow-size notice lane closes its channel, and three naming/containment defects fix. Major stays locked at 5._
+
+### Fixed
+
+- Protocol naming (ticket #10): a minted peer segment can no longer parse back as a DIFFERENT peer — adjacent out-of-charset characters used to normalize into the `__` separator (`"prod. db"` → `prod__db`, read back as peer `prod`), and a clamp could splice one in at the digest join. The peer leg folds `_` runs after the clamp (an all-separator peer degrades to a readable digest), the digest joins with `-`; only names for peers over the assembly budget change spelling. The tool segment is untouched (`repo__delete` round-trips as before).
+- MCP tool `description` is neutralized (`sanitizeUntrustedText`) before it reaches the model-facing tool card (ticket #11) — it was the one remote text with no neutralization at all (instructions are sanitized+fenced, drop reasons inlined, error bodies fenced); the text is otherwise verbatim (no fence: that would poison every tool table for the honest majority).
+- MCP refresh receipt `prefix` (ticket #9): the refresh leg recomputed the server prefix without the assembly budget, so a server name surviving normalization but not the 64-char budget produced a prefix matching none of the registered names — the splice domain then removed nothing and the fresh tools mounted alongside the stale ones under the same names. Minting (normalize + budget + clamp) is now single-sourced in `protocol-naming.ts`; the intake and the receipt call the same arithmetic.
+
+### Added
+
+- `workflow_size_guideline_change` turn-boundary frame: a mid-run retune of `RunnerDeps.workflowLimits.sizeGuideline` now reaches the model at the next tool-calling boundary (the Workflow tool card is a per-mount snapshot and never re-renders). Same discipline as the `date_change`/`instructions_change` lanes: continuation-gated (a retune landing on a text-final turn never revives a finished run), fixed one-sentence frame above the bundle byte cap, comparison on the RESOLVED guideline (writing down the value already in force is not a change), armed only when the Workflow tool is mounted. `TaskEvent.steering_injected.source` gains the member (additive).
+- Internal cleanup: the todo projection's dead `statusCounts` field is gone (computed on every TodoWrite, never consumed by any model-facing renderer).
+- `toA2ATaskState` / `fromA2ATaskState` / `A2A_TASK_STATES` (exported): the pure projection between the durable background-agent row status and the A2A TaskState vocabulary. Forward is total (`killed` splits on `stoppedBy`: user/parent → `canceled`, anything else → `failed`); reverse is 9→5 and returns a discriminated `{lossy, status, note?}` — `lossy: false` holds exactly for the states that survive the round trip (pinned as a property test). Serving layers must still gate every row through `canAccessAgentRecord`.
+- `queryBackgroundAgents` / `serveDurableAgentRowLane` / `buildAgentPollDetails` (+ their named input/result types) reach the package root — the row-serving primitives an A2A-style host endpoint composes, previously module-internal.
+- `backgroundAgentStoreContract` + `backgroundAgentStoreScopesContract`: the contract kit the store family was missing — third-party `BackgroundAgentStore` backends can now run the same assertion set the bundled InMemory/File backends pass (rev-CAS, guarded updateIf, filter semantics, stale-running reap attribution; the optional `listScopes` layer is opt-in so an unimplemented method cannot skip silently).
+- `TaskSpec.a2a` + `A2aServerSpec` + `materializeA2aTools` / `MaterializedA2a` (exported) + `onError` phase `"a2a"`: the A2A client leg — declared peers' agent cards are discovered (`agent-card.json` with legacy fallback, explicit `cardUrl` override), their skills mount as task-scoped tools (`a2a__<peer>__<skill>`; the protocol gives skills no input schema, so the engine synthesizes `{message, taskId?, contextId?}` and folds tags/examples into the sanitized, bounded description), calls ride JSON-RPC `message/send` with terminal-state polling under dual clocks, and every request declares `A2A-Version: 1.0`. Both legal reply shapes are honored (a direct Message and a polled Task); `input-required`/`auth-required` return immediately with the continuation keys instead of burning the ceiling. Default axes are `egress` + `write` (a remote agent is an external write; the caller's `toolAxes` is the only lowering channel), success bodies come back fenced as untrusted data (a deliberate divergence from the MCP success path — the sender is an agent, not a data source), and a `FilePart` uri is shown as text, never fetched. One unreachable peer never bricks its healthy sibling.
+- `A2A_NAMESPACE` (exported): the protocol table's second entry — the `a2a__<peer>__<skill>` name shape, parse/makeName/displayGroupKey under the same destructuring-safe contract as MCP (both entries now built by one factory). The reserved-name and policy-audit messages now enumerate every table prefix instead of spelling `mcp__` by hand.
+- `CheckpointError.detail` (additive, optional): structured discrimination where the code alone is ambiguous — `detail.field` names WHICH decision-action binding failed on `checkpoint.invalid_outcome` (`"boundCallId"`: the action you decided on was replaced, re-fetch the pending list; `"boundInputHash"`: the input you reviewed changed under the same action, re-review). `code` remains the only required discriminant.
+
 ## 5.2.0 (2026-08-03)
 
 _The v5.0.1..v5.1.0 full-window dual-lens review's repair batch (67 findings, all dispositioned; see docs/REVIEW-BACKLOG.md). Theme: the 5.1.0 retirements now refuse loudly EVERYWHERE they promised to, and the new disclosure seats reach the deployments they were built for._

package/dist/brain/anthropic.js

@@ -5,6 +5,7 @@ import { createRepetitionPoll, createWalltimeGate, parseStreamedToolArgs } from
 import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { WALLTIME_CUTOFF_MESSAGE } from "./walltime.js";
 import { emitBrainTelemetry } from "./status-sink.js";
+import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, modelSupportsVision, sendableImages } from "./media-degrade.js";
 import { ANTHROPIC_RESERVED, applyExtraBody, stripAuthHeaders } from "./request-params.js";
 import { isThinkingLevel, reasoningBudgetShare, resolveEffort } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
@@ -37,7 +38,7 @@ function toUserBlocks(content, supportsVision = true) {
                 blocks.push({ type: "image", source: { type: "base64", media_type: c.mimeType, data: c.data } });
             else {
                 omitted++;
-                blocks.push({ type: "text", text: "[image omitted: the serving model does not support image input]" });
+                blocks.push({ type: "text", text: IMAGE_OMITTED_NO_VISION });
             }
         }
     }
@@ -46,7 +47,7 @@ function toUserBlocks(content, supportsVision = true) {
     return blocks;
 }
 function toAnthropicMessages(ctx, model) {
-    const supportsVision = model?.input === undefined ? true : model.input.includes("image");
+    const supportsVision = modelSupportsVision(model);
     const raw = [];
     let pendingDocs = [];
     const flushDocs = () => {
@@ -112,6 +113,15 @@ function toAnthropicMessages(ctx, model) {
                         inner.push({ type: "text", text: note });
                 }
             }
+            if (m.isError) {
+                const note = errorResultMediaNote({ images: sendableImages(Array.isArray(rest) ? rest : []).length, documents: docs.length });
+                if (note !== undefined) {
+                    if (typeof inner === "string")
+                        inner = inner ? `${inner}\n${note}` : note;
+                    else
+                        inner.push({ type: "text", text: note });
+                }
+            }
             if (typeof inner === "string" ? inner.length === 0 : inner.length === 0)
                 inner = NO_CONTENT;
             raw.push({

package/dist/brain/media-degrade.d.ts

@@ -0,0 +1,14 @@
+import type { Model } from "../internal/llm.js";
+export declare function modelSupportsVision(model?: Model): boolean;
+export declare const IMAGE_OMITTED_NO_VISION = "[image omitted: the serving model does not support image input]";
+export declare function imagesOmittedNoVisionNote(count: number): string;
+export interface SendableImage {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+export declare function sendableImages(blocks: readonly unknown[]): SendableImage[];
+export declare function errorResultMediaNote(counts: {
+    images: number;
+    documents: number;
+}): string | undefined;

package/dist/brain/media-degrade.js

@@ -0,0 +1,30 @@
+export function modelSupportsVision(model) {
+    return model?.input === undefined ? true : model.input.includes("image");
+}
+export const IMAGE_OMITTED_NO_VISION = "[image omitted: the serving model does not support image input]";
+export function imagesOmittedNoVisionNote(count) {
+    return count > 1 ? `[${count} images omitted: the serving model does not support image input]` : IMAGE_OMITTED_NO_VISION;
+}
+export function sendableImages(blocks) {
+    const out = [];
+    for (const b of blocks) {
+        const c = b;
+        if (c.type === "image" && typeof c.data === "string" && typeof c.mimeType === "string") {
+            out.push({ type: "image", data: c.data, mimeType: c.mimeType });
+        }
+    }
+    return out;
+}
+function plural(count, noun) {
+    return `${count} ${noun}${count > 1 ? "s" : ""}`;
+}
+export function errorResultMediaNote(counts) {
+    const dropped = [];
+    if (counts.images > 0)
+        dropped.push(plural(counts.images, "image"));
+    if (counts.documents > 0)
+        dropped.push(plural(counts.documents, "document"));
+    if (dropped.length === 0)
+        return undefined;
+    return `[${dropped.join(" and ")} omitted — an error tool result must be text-only; re-run the tool successfully if you need the attachment]`;
+}

package/dist/brain/openai.js

@@ -5,6 +5,7 @@ import { createRepetitionPoll, createWalltimeGate, parseStreamedToolArgs } from
 import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { WALLTIME_CUTOFF_MESSAGE } from "./walltime.js";
 import { emitBrainTelemetry } from "./status-sink.js";
+import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
 import { OPENAI_RESERVED, applyExtraBody, stripAuthHeaders } from "./request-params.js";
 import { DEFAULT_EFFORT_LEVELS, isThinkingLevel, resolveEffort } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
@@ -30,10 +31,6 @@ function textOf(content) {
         .map((c) => c.text)
         .join("");
 }
-function visionOf(model) {
-    return model?.input === undefined ? true : model.input.includes("image");
-}
-const IMAGE_OMITTED = "[image omitted: the serving model does not support image input]";
 const NO_CONTENT = "(no content)";
 const DOCUMENT_OMITTED = "[PDF document omitted: PDF direct read requires an Anthropic-family model; re-Read the file (the engine will extract text/render pages when possible) or extract the text via Bash instead (e.g. `pdftotext`).]";
 function toUserContent(content, supportsVision = true) {
@@ -54,7 +51,7 @@ function toUserContent(content, supportsVision = true) {
         const n = content.filter((c) => c.type === "image").length;
         emitBrainTelemetry({ kind: "vision_placeholder", count: n });
         const base = textOf(content);
-        const note = n > 1 ? `[${n} images omitted: the serving model does not support image input]` : IMAGE_OMITTED;
+        const note = imagesOmittedNoVisionNote(n);
         const withNote = base ? `${base}\n${note}` : note;
         return nDocs > 0 ? `${withNote}\n${DOCUMENT_OMITTED}` : withNote;
     }
@@ -139,7 +136,7 @@ function applyThinking(body, model, reasoning) {
     }
 }
 function toOpenAIMessages(ctx, replayThinking = true, model) {
-    const supportsVision = visionOf(model);
+    const supportsVision = modelSupportsVision(model);
     const out = [];
     const needsEmptyReasoningField = !!model?.reasoning && thinkingCompat(model).requiresReasoningContentOnAssistantMessages === true;
     if (ctx.systemPrompt) {
@@ -194,9 +191,8 @@ function toOpenAIMessages(ctx, replayThinking = true, model) {
             out.push(msg);
         }
         else if (m.role === "toolResult") {
-            const rawImages = !m.isError && Array.isArray(m.content)
-                ? m.content.filter((c) => c.type === "image" && typeof c.data === "string" && typeof c.mimeType === "string")
-                : [];
+            const mediaImages = sendableImages(Array.isArray(m.content) ? m.content : []);
+            const rawImages = m.isError ? [] : mediaImages;
             const images = supportsVision ? rawImages : [];
             if (!supportsVision && rawImages.length > 0)
                 emitBrainTelemetry({ kind: "vision_placeholder", count: rawImages.length });
@@ -205,11 +201,13 @@ function toOpenAIMessages(ctx, replayThinking = true, model) {
                 emitBrainTelemetry({ kind: "document_placeholder", count: nDocs });
             const baseText0 = textOf(m.content);
             const baseText = nDocs > 0 ? (baseText0 ? `${baseText0}\n${DOCUMENT_OMITTED}` : DOCUMENT_OMITTED) : baseText0;
-            const text = !supportsVision && rawImages.length > 0 ? (baseText ? `${baseText}\n${IMAGE_OMITTED}` : IMAGE_OMITTED) : baseText;
+            const text = !supportsVision && rawImages.length > 0 ? (baseText ? `${baseText}\n${IMAGE_OMITTED_NO_VISION}` : IMAGE_OMITTED_NO_VISION) : baseText;
+            const errorNote = m.isError ? errorResultMediaNote({ images: mediaImages.length, documents: 0 }) : undefined;
+            const finalText = errorNote === undefined ? text : text ? `${text}\n${errorNote}` : errorNote;
             out.push({
                 role: "tool",
                 tool_call_id: m.toolCallId,
-                content: toolResultText(text, images.length > 0, m.content),
+                content: toolResultText(finalText, images.length > 0, m.content),
             });
             for (const img of images)
                 pendingImages.push({ toolCallId: m.toolCallId, data: img.data, mimeType: img.mimeType });

package/dist/brain/timeout.d.ts

@@ -1,3 +1,4 @@
+import type { StreamFn } from "../internal/llm.js";
 export interface BrainTimeoutConfig {
     connectTimeoutMs?: number;
     firstTokenTimeoutMs?: number;
@@ -10,3 +11,16 @@ export declare function createConnectController(connectTimeoutMs: number | undef
     clearTimer: () => void;
     dispose: () => void;
 };
+export declare const BRAIN_CALL_GUARDRAIL_DEFAULT_MS = 3600000;
+export declare const BRAIN_CALL_GUARDRAIL_ERROR_CODE = "brain.call_guardrail_timeout";
+export declare class BrainCallGuardrailTimeoutError extends Error {
+    readonly code = "brain.call_guardrail_timeout";
+    readonly limitMs: number;
+    constructor(limitMs: number);
+}
+export type BrainCallGuardrailKnob = number | false;
+export declare function resolveBrainCallGuardrailMs(knob: BrainCallGuardrailKnob | undefined): number | undefined;
+export interface BrainCallGuardrailRef {
+    timedOut?: BrainCallGuardrailTimeoutError;
+}
+export declare function withBrainCallGuardrail(streamFn: StreamFn, limitMs: number, ref: BrainCallGuardrailRef): StreamFn;

package/dist/brain/timeout.js

@@ -44,3 +44,117 @@ export function createConnectController(connectTimeoutMs, outerSignal, deadlineA
         },
     };
 }
+export const BRAIN_CALL_GUARDRAIL_DEFAULT_MS = 3_600_000;
+export const BRAIN_CALL_GUARDRAIL_ERROR_CODE = "brain.call_guardrail_timeout";
+export class BrainCallGuardrailTimeoutError extends Error {
+    code = BRAIN_CALL_GUARDRAIL_ERROR_CODE;
+    limitMs;
+    constructor(limitMs) {
+        super(`the engine stopped waiting for a brain call that ran past its ${limitMs}ms guardrail — the call was abandoned (a Brain that ignores options.signal may still be running)`);
+        this.name = "BrainCallGuardrailTimeoutError";
+        this.limitMs = limitMs;
+    }
+}
+export function resolveBrainCallGuardrailMs(knob) {
+    if (knob === undefined)
+        return BRAIN_CALL_GUARDRAIL_DEFAULT_MS;
+    if (knob === false || knob === 0)
+        return undefined;
+    if (typeof knob !== "number" || !Number.isFinite(knob) || knob < 0) {
+        const e = new Error(`brainCallGuardrailMs must be a positive number of milliseconds, 0, or false (got ${String(knob)})`);
+        e.code = "config.brain_call_guardrail_invalid";
+        throw e;
+    }
+    return knob;
+}
+function armCallGuardrail(limitMs, outerSignal, ref) {
+    const ac = new AbortController();
+    if (outerSignal !== undefined) {
+        if (outerSignal.aborted)
+            ac.abort(outerSignal.reason);
+    }
+    const forwardAbort = () => {
+        ac.abort(outerSignal === undefined ? undefined : outerSignal.reason);
+    };
+    if (outerSignal !== undefined && !outerSignal.aborted) {
+        outerSignal.addEventListener("abort", forwardAbort, { once: true });
+    }
+    let expired;
+    let rejectExpiry = () => undefined;
+    const expiry = new Promise((_resolve, reject) => {
+        rejectExpiry = reject;
+    });
+    expiry.catch(() => undefined);
+    const timer = setTimeout(() => {
+        const err = new BrainCallGuardrailTimeoutError(limitMs);
+        expired = err;
+        ref.timedOut ??= err;
+        ac.abort(err);
+        rejectExpiry(err);
+    }, limitMs);
+    return {
+        signal: ac.signal,
+        race: async (p) => {
+            if (expired !== undefined)
+                throw expired;
+            const value = await Promise.race([p, expiry]);
+            if (expired !== undefined)
+                throw expired;
+            return value;
+        },
+        disarm: () => {
+            clearTimeout(timer);
+            if (outerSignal !== undefined)
+                outerSignal.removeEventListener("abort", forwardAbort);
+        },
+    };
+}
+export function withBrainCallGuardrail(streamFn, limitMs, ref) {
+    return async (model, context, options) => {
+        const gate = armCallGuardrail(limitMs, options?.signal, ref);
+        let inner;
+        try {
+            inner = await gate.race(Promise.resolve(streamFn(model, context, { ...options, signal: gate.signal })));
+        }
+        catch (err) {
+            gate.disarm();
+            throw err;
+        }
+        return {
+            [Symbol.asyncIterator]() {
+                const it = inner[Symbol.asyncIterator]();
+                return {
+                    next: async () => {
+                        let step;
+                        try {
+                            step = await gate.race(Promise.resolve(it.next()));
+                        }
+                        catch (err) {
+                            gate.disarm();
+                            throw err;
+                        }
+                        if (step.done === true)
+                            gate.disarm();
+                        return step;
+                    },
+                    return: async () => {
+                        gate.disarm();
+                        const release = it.return;
+                        if (release !== undefined) {
+                            Promise.resolve(release.call(it)).catch(() => undefined);
+                        }
+                        return { value: undefined, done: true };
+                    },
+                };
+            },
+            result: async () => {
+                try {
+                    return await gate.race(Promise.resolve(inner.result()));
+                }
+                finally {
+                    gate.disarm();
+                }
+            },
+        };
+    };
+}

package/dist/core/a2a-task-state.d.ts

@@ -0,0 +1,15 @@
+import type { BackgroundAgentRecord } from "./background-agent-store.js";
+export declare const A2A_TASK_STATES: readonly ["submitted", "working", "input-required", "completed", "canceled", "failed", "rejected", "auth-required", "unknown"];
+export type A2ATaskState = (typeof A2A_TASK_STATES)[number];
+export declare function toA2ATaskState(record: Pick<BackgroundAgentRecord, "status" | "stoppedBy">): A2ATaskState;
+export interface A2ATaskStateReversalFaithful {
+    lossy: false;
+    status: BackgroundAgentRecord["status"];
+}
+export interface A2ATaskStateReversalLossy {
+    lossy: true;
+    status: BackgroundAgentRecord["status"];
+    note: string;
+}
+export type A2ATaskStateReversal = A2ATaskStateReversalFaithful | A2ATaskStateReversalLossy;
+export declare function fromA2ATaskState(state: A2ATaskState): A2ATaskStateReversal;

package/dist/core/a2a-task-state.js

@@ -0,0 +1,68 @@
+export const A2A_TASK_STATES = [
+    "submitted",
+    "working",
+    "input-required",
+    "completed",
+    "canceled",
+    "failed",
+    "rejected",
+    "auth-required",
+    "unknown",
+];
+const CANCELLING_STOP_SOURCES = new Set(["user", "parent"]);
+export function toA2ATaskState(record) {
+    switch (record.status) {
+        case "running":
+            return "working";
+        case "parked":
+            return "input-required";
+        case "completed":
+            return "completed";
+        case "failed":
+            return "failed";
+        case "killed":
+            return record.stoppedBy !== undefined && CANCELLING_STOP_SOURCES.has(record.stoppedBy) ? "canceled" : "failed";
+    }
+}
+export function fromA2ATaskState(state) {
+    switch (state) {
+        case "working":
+            return { lossy: false, status: "running" };
+        case "input-required":
+            return { lossy: false, status: "parked" };
+        case "completed":
+            return { lossy: false, status: "completed" };
+        case "failed":
+            return { lossy: false, status: "failed" };
+        case "submitted":
+            return {
+                lossy: true,
+                status: "running",
+                note: "the durable ledger has no accepted-but-not-yet-started state — a row exists only once its child is running, so the distinction between submitted and working is dropped.",
+            };
+        case "canceled":
+            return {
+                lossy: true,
+                status: "killed",
+                note: "the cancellation attribution lives in the row's stoppedBy field, which a state alone cannot carry: a killed row WITHOUT stoppedBy in (user, parent) projects back as failed, not canceled.",
+            };
+        case "rejected":
+            return {
+                lossy: true,
+                status: "failed",
+                note: "rejection happens before a row exists (admission-time), so it is recorded as a failed terminal — the fact that the task was never admitted at all is lost.",
+            };
+        case "auth-required":
+            return {
+                lossy: true,
+                status: "failed",
+                note: "auth-required is a resumable waiting state with no durable seat here (parked is bound to an approval-checkpoint token, which this state has none of), so it lands as a failed terminal and is NOT resumable through this mapping.",
+            };
+        case "unknown":
+            return {
+                lossy: true,
+                status: "failed",
+                note: "unknown is a read-projection state (an outcome this engine instance cannot see), not a durable outcome; writing it back asserts a terminal failure the row itself never recorded.",
+            };
+    }
+}

package/dist/core/a2a.d.ts

@@ -0,0 +1,42 @@
+import type { AgentTool } from "../internal/harness-types.js";
+import type { A2aServerSpec, ToolEffect } from "./types.js";
+export declare const A2A_SKILL_DESCRIPTION_MAX_CHARS = 2048;
+export interface A2aToolAxis {
+    name: string;
+    irreversibility?: "always";
+    egress?: true;
+    effect?: ToolEffect;
+}
+export interface A2aPeerStatus {
+    name: string;
+    status: "ready" | "failed";
+    agentName?: string;
+    agentDescription?: string;
+    endpoint?: string;
+    toolNames?: string[];
+    error?: string;
+}
+export interface A2aRefreshResult {
+    peer: string;
+    prefix: string;
+    status: "refreshed" | "failed" | "disposed";
+    toolCount: number;
+    added: string[];
+    removed: string[];
+    tools?: AgentTool[];
+    axes?: A2aToolAxis[];
+    error?: string;
+}
+export interface MaterializedA2a {
+    tools: AgentTool[];
+    toolAxes: A2aToolAxis[];
+    warnings: Error[];
+    statuses: A2aPeerStatus[];
+    refresh: (peer?: string) => Promise<A2aRefreshResult[]>;
+    dispose: () => Promise<void>;
+}
+export declare class A2aRpcError extends Error {
+    readonly code: number;
+    constructor(peer: string, method: string, code: number, message: string);
+}
+export declare function materializeA2aTools(specs: readonly A2aServerSpec[], principal?: string, signal?: AbortSignal): Promise<MaterializedA2a>;