@sema-agent/core 5.1.0 → 5.3.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # 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._
+
+### Behavior / BREAKING-leaning (all loud-by-design)
+
+- **memory**: a `TaskSpec.memory` still carrying the retired singular `scope` throws `config.memory_scope_spelling` at task start (it silently normalized to memory-OFF for the whole task).
+- **tool policy**: a caller policy decision carrying the retired `reason` field is refused fail-closed at the policy fold — `deny` keeps denying with a migration text, `allow`/`ask` are NOT honored. (The 5.1.0 claim that `{reason}` "compiles red" was false in method-position shapes; this is the runtime signal that was missing.)
+- **hooks / resume**: the same tripwire reaches the two decision faces that do not cross the fold — a PreToolUse hook result carrying `reason` is refused fail-closed at both hook entry points (its `additionalContext`/`updatedInput` do not take effect either; `allow{reason}` used to run the tool), and the durable-resume re-checks (edited-args policy re-judgment, session-rule narrowing layer) refuse the retired dialect on the same helper.
+- **openai brain**: an out-of-contract `reasoning` value is treated as absent on every wire format (it used to pass through verbatim as `reasoning_effort`, so the two brains disagreed on the same input).
+- **ToolSearch**: a `select` argument key in any shape (the retired array form included) is a loud invalid-arguments naming `query:"select:A,B"` (it used to parse as an empty query and answer "No deferred tools matched"); stored activations replay tolerantly.
+- **Grep**: the retired `regex`/`max_results` keys refuse with their living replacements (pattern IS a regex; `head_limit`) — `max_results` was silently accepted and ignored.
+- **TodoWrite**: the public raw-spec execute lane refuses a missing/empty `activeForm` (it used to synthesize the label and accept what the schema refuses); the simple-arm card teaches the required form.
+- **protocol table**: `MCP_NAMESPACE.parse` rejects an empty tool segment; `makeName` throws on empty/separator-carrying segments (round-trip symmetry); both survive destructuring (`this`-free).
+- **workflow store**: a `resolveName` implementation still returning the retired bare-string resolution gets a structured migration error naming the `{script}` form (was a TypeError quoting the whole script source).
+- **Read/Edit/Write**: `file_path` is schema-REQUIRED, so a call carrying only the retired `path` alias is loud invalid-arguments naming `file_path` — on the live lane and on durable replay alike. 5.1.0 retired the alias from the schema's declared properties but left `file_path` optional; TypeBox's object check is non-strict, so `{path}` still validated with no `file_path` present and the tool body read the target back out through the gate reader's over-read arm. The alias therefore kept working end-to-end and no caller ever learned it had to migrate — the 5.1.0 note's "re-validates loudly on resume" was not true until now. The security-gate readers keep their `path` arm unchanged: that side is fail-closed coverage across other tool vocabularies (Glob's real `path` parameter, deployment-authored tools), and the asymmetry is deliberate — the schema decides what a caller may send, the gate decides what gets judged, and the gate must never see less than the tool might act on.
+- **memory engine (semantics fix)**: `deriveControlPlaneDir` mints resolve-only again — canonicalizing a model-writable memory dir made a symlink swap a redirect handle onto a fresh empty control plane; the repo-partition face keeps the canonical key via the new paired mint (below). Adoption no longer trips over its own backend's mkdir scaffolding (the common pinned-backend deployment adopts instead of reporting a spurious `memory.partition_split` every mount); a failed adoption rename re-checks the source before reading as adopted-by-peer.
+
+### Added
+
+- `deriveRepoControlPlaneDir` (exported): the canonical-key control-plane mint paired with `deriveRepoMemoryDir` — self-assembled hosts no longer mispair the two key families on alias paths.
+- `FileStorageBackendOptions.onCorruptRead`: the packaged file backend threads the corrupt-read disclosure seat into the stores it constructs; `FileMemoryEngineBackendOptions.onIncident` + `MemoryEngineOptions.onIncident`: partition incidents are observable on the self-constructed mount paths.
+- Disclosure coverage: session-policy `listBySession` corrupt-skips disclose; cc-mailbox element-grade corruption is dropped AND disclosed (sinks run after the cross-process lock releases); roster row-drops disclose with a count.
+- `FileMailboxStoreOptions.onCorruptRead` (server pickup receipt named the gap): the dataRoot-form file mailbox store discloses a corrupt interior JSONL record dropped on replay (both the warm and cold replay arms); the torn tail stays silent by design — that is the append-log's documented crash-recovery shape, not corruption. `readJsonlRecords` grew the optional `onCorrupt` seat (additive; other consumers unchanged).
+- `MCP_PREFIX` regains its literal type (`"mcp__"`) via the generic `ProtocolNamespace<P>`.
+- `FileSessionRepoOptions.onCorruptRead` + `FileFileSnapshotStoreOptions.onCorruptRead` (additive): the two enumerating file stores stop reading "could not read it" as "there is none". The session repo discloses an unreadable sessions directory, a session log skipped from a listing, and a corrupt interior JSONL record dropped on replay; the snapshot store discloses a corrupt/wrong-shape manifest collapsed to "no snapshot", an unreadable manifest scope directory on `listKeys`/`reap`, and every blob-GC pass that aborted (blobs kept). Plain ENOENT / `not_found` never fires either, and the torn tail stays silent. `FileStorageBackendOptions.onCorruptRead` reaches both (its payload is now the named union `FileStorageCorruptReadInfo` — `path`+`reason` always, `sessionId`/`principal` only from the session-policy face), so one sink covers the packaged deployment.
+- `MemoryEngineOptions.onIncident` also carries `memory.announce_failed`: the memory announcement queue — the disclosure lane for out-of-session memory events — used to swallow its own enqueue/drain failures at four call sites, so a host with an unwritable control plane saw healthy sessions while every notice was dropped. All four arms stay fail-open; a throwing sink is swallowed at the boundary and never re-enters the queue.
+
+### Fixed
+
+- Repair-loop spend accounting across a human-decision park: an `approval`/`plan_review` park now stamps the in-flight leg's spend into the serialized bundle, so a resume no longer under-counts the money already spent (the resource-slice park was always exact and is unchanged).
+- The retired-`reason` tripwire also wraps the `changed_files` advisory probe's direct policy `check` — the screen is a property of every consumption point. All layers in that stack are core-constructed today, so the end-to-end behavior is unchanged; a retired-dialect decision would suppress that file's turn-boundary notice (never widen a permission).
+
 ## 5.1.0 (2026-08-03)
 
 _The second (and final planned) baggage sweep: every remaining compatibility arm, plus a durable memory-key fix with an automatic adoption leg and the protocol table that clears the road for a second tool protocol. Version-line policy (project ruling): the major stays at 5 — breaking changes below are declared loudly here and coordinated with all in-org consumers, but do not mint a new major._

package/dist/agents/roster-store.js

@@ -110,7 +110,12 @@ export class FileRosterStore {
             const raw = JSON.parse(text);
             if (!Array.isArray(raw.entries))
                 throw new Error("roster file: entries is not an array");
-            return raw.entries.filter((e) => typeof e === "object" && e !== null && typeof e.name === "string" && typeof e.agentId === "string" && typeof e.createdAt === "number");
+            const kept = raw.entries.filter((e) => typeof e === "object" && e !== null && typeof e.name === "string" && typeof e.agentId === "string" && typeof e.createdAt === "number");
+            const dropped = raw.entries.length - kept.length;
+            if (dropped > 0) {
+                this.discloseCorrupt(`${dropped} schema-invalid roster rows dropped (of ${raw.entries.length}); a subsequent write persists the filtered document`);
+            }
+            return kept;
         }
         catch (e) {
             if (mode === "lenient") {

package/dist/bin/sema-tb.js

@@ -7,10 +7,9 @@ import { inferMaxTokensField } from "../brain/openai.js";
 function usage(code = 2) {
     const out = code === 0 ? process.stdout : process.stderr;
     out.write("Usage: sema-tb --model <provider/model> [--objective-file <path>] [--jsonl <path>]\n" +
-        "  Instruction legs: --objective-file <path> (preferred for real task text) | stdin\n" +
-        "  | stdin (default when neither flag is given). Both flags together = usage error.\n" +
-        "  WARNING: argv is visible to every process in the sandbox (ps / pgrep -f / /proc/*/cmdline) — long\n" +
-        "  Instructions ride --objective-file or stdin; the retired --message argv leg is refused (process-list exposure).\n" +
+        "  Instruction legs: --objective-file <path> (preferred for real task text) | stdin (default when the flag is absent).\n" +
+        "  WARNING: argv is visible to every process in the sandbox (ps / pgrep -f / /proc/*/cmdline), so instructions ride\n" +
+        "  --objective-file or stdin; the retired --message argv leg is refused (process-list exposure).\n" +
         "Env: <PROVIDER>_API_KEY / <PROVIDER>_BASE_URL, TB_MAX_TURNS, TB_TIMEOUT_SEC, TB_FULLBODY, TB_TODOREMIND, TB_BGTASKS, TB_SUMMARIZE,\n" +
         "     TB_FINALVERIFY, TB_CALLCAP, TB_FINALIZE, TB_REASONING, TB_JSONL, TB_CONTEXT_WINDOW, TB_MAX_OUTPUT_TOKENS, TB_TASKLIST, TB_VISION\n" +
         '     TB_COST="input,output[,cacheRead[,cacheWrite]]" — USD per MTok; explicit pricing override (omitted\n' +

package/dist/brain/openai.js

@@ -90,15 +90,13 @@ function applyThinking(body, model, reasoning) {
         }
         return;
     }
-    if (!model.reasoning || !reasoning || reasoning === "off")
+    if (!model.reasoning || !isThinkingLevel(reasoning) || reasoning === "off")
         return;
     const compat = thinkingCompat(model);
     const supportsEffort = compat.supportsReasoningEffort ?? true;
-    const effort = isThinkingLevel(reasoning)
-        ? resolveEffort(reasoning, compat.reasoningEffortLevels ?? DEFAULT_EFFORT_LEVELS).effective
-        : reasoning;
+    const effort = resolveEffort(reasoning, compat.reasoningEffortLevels ?? DEFAULT_EFFORT_LEVELS).effective;
     let effortWire = effort;
-    if (isThinkingLevel(effort) && model.thinkingLevelMap) {
+    if (model.thinkingLevelMap) {
         const mapped = model.thinkingLevelMap[effort];
         if (mapped === null)
             effortWire = undefined;

package/dist/brain/terminal-cause.d.ts

@@ -1,4 +1,4 @@
 import type { AssistantMessage } from "../internal/llm.js";
-export type TerminalCauseCarrier = Pick<AssistantMessage, "errorKind" | "errorMessage">;
+export type TerminalCauseCarrier = Pick<AssistantMessage, "errorKind">;
 export declare function isDegenerateCutMessage(message: TerminalCauseCarrier): boolean;
 export declare function isWalltimeCutMessage(message: TerminalCauseCarrier): boolean;

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>;