@sema-agent/core 5.2.0 → 5.3.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 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/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>;