@smartmemory/stratum 0.3.4 → 0.4.0

package/dist/learn/smartmemory_egress.js

@@ -0,0 +1,330 @@
+const MIN_BACKOFF_MS = 1_000;
+const MAX_BACKOFF_MS = 5 * 60_000;
+const REQUEST_TIMEOUT_MS = 5_000;
+const DEAD_STATUSES = new Set([400, 401, 403, 404, 422]);
+const MEMORY_TYPES = [
+    "stratum_usage_debit",
+    "stratum_step_reset",
+    "stratum_checkpoint_reverted",
+];
+export class LearnEgress {
+    url;
+    apiKey;
+    workspaceId;
+    optedIn;
+    fetchImpl;
+    now;
+    random;
+    warn;
+    setTimeoutImpl;
+    clearTimeoutImpl;
+    store;
+    withReceiptUpdate;
+    drains = new Map();
+    backoffs = new Map();
+    workspaceWarningIssued = false;
+    constructor(options) {
+        const env = options.env ?? process.env;
+        const url = env.SMARTMEMORY_API_URL?.replace(/\/+$/, "");
+        this.url = url ? url : undefined;
+        this.apiKey = env.SMARTMEMORY_API_KEY || undefined;
+        this.workspaceId = env.SMARTMEMORY_WORKSPACE_ID || undefined;
+        this.optedIn = env.STRATUM_LEARN_EGRESS === "1";
+        this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+        this.now = options.now ?? Date.now;
+        this.random = options.random ?? Math.random;
+        this.warn = options.warn ?? ((warning) => console.warn(warning));
+        this.setTimeoutImpl = options.setTimeoutImpl ?? setTimeout;
+        this.clearTimeoutImpl = options.clearTimeoutImpl ?? clearTimeout;
+        this.store = options.store;
+        this.withReceiptUpdate = options.withReceiptUpdate;
+    }
+    enabled() {
+        if (!this.optedIn || this.url === undefined || this.apiKey === undefined)
+            return false;
+        if (this.workspaceId !== undefined)
+            return true;
+        if (!this.workspaceWarningIssued) {
+            this.workspaceWarningIssued = true;
+            this.warn("SmartMemory receipt egress is disabled: SMARTMEMORY_WORKSPACE_ID is required");
+        }
+        return false;
+    }
+    async drainRun(runId) {
+        if (!this.enabled())
+            return;
+        let state = this.drains.get(runId);
+        if (state === undefined) {
+            state = { dirty: false, inFlight: undefined };
+            this.drains.set(runId, state);
+        }
+        state.dirty = true;
+        if (state.inFlight === undefined)
+            this.startDrain(runId, state);
+        await state.inFlight;
+    }
+    async drainAll() {
+        if (!this.enabled())
+            return;
+        try {
+            await Promise.all((await this.store.list()).map((runId) => this.drainRun(runId)));
+        }
+        catch (error) {
+            this.warn(`SmartMemory egress reconciliation failed: ${message(error)}`);
+        }
+    }
+    async close() {
+        for (;;) {
+            const inFlight = [...this.drains.values()].flatMap((state) => state.inFlight ? [state.inFlight] : []);
+            if (inFlight.length === 0)
+                return;
+            await Promise.all(inFlight);
+        }
+    }
+    async verifyRun(runId) {
+        if (!this.enabled()) {
+            throw new Error("SmartMemory egress is disabled: STRATUM_LEARN_EGRESS=1 and SMARTMEMORY_API_URL/API_KEY/WORKSPACE_ID are required");
+        }
+        const run = await this.store.load(runId);
+        const local = run.receipts ?? [];
+        let missingCount = 0;
+        let duplicateCount = 0;
+        let wrongTypeCount = 0;
+        for (const receipt of local) {
+            const receiptId = `${runId}:${receipt.seq}`;
+            const expectedType = memoryTypeFor(receipt);
+            const expectedHits = await this.exactHits(receiptId, expectedType);
+            if (expectedHits.length > 0) {
+                duplicateCount += expectedHits.length - 1;
+                continue;
+            }
+            missingCount += 1;
+            for (const otherType of MEMORY_TYPES) {
+                if (otherType === expectedType)
+                    continue;
+                wrongTypeCount += (await this.exactHits(receiptId, otherType)).length;
+            }
+        }
+        return {
+            runId,
+            receiptCount: local.length,
+            missingCount,
+            duplicateCount,
+            wrongTypeCount,
+            deadCount: local.filter((receipt) => receipt.egress === "dead").length,
+        };
+    }
+    async retryDead(runId) {
+        let retried = 0;
+        try {
+            retried = await this.withReceiptUpdate(runId, (run) => {
+                let changed = 0;
+                for (const receipt of run.receipts ?? []) {
+                    if (receipt.egress !== "dead")
+                        continue;
+                    receipt.egress = "pending";
+                    delete receipt.egressStatus;
+                    changed += 1;
+                }
+                return changed;
+            });
+            await this.drainRun(runId);
+        }
+        catch (error) {
+            this.warn(`SmartMemory egress could not retry dead receipts for run ${runId}: ${message(error)}`);
+        }
+        return retried;
+    }
+    startDrain(runId, state) {
+        const inFlight = this.drainLoop(runId, state)
+            .catch((error) => {
+            this.warn(`SmartMemory egress could not drain run ${runId}: ${message(error)}`);
+        })
+            .finally(() => {
+            state.inFlight = undefined;
+            if (state.dirty)
+                this.startDrain(runId, state);
+            else if (this.drains.get(runId) === state)
+                this.drains.delete(runId);
+        });
+        state.inFlight = inFlight;
+    }
+    async drainLoop(runId, state) {
+        while (state.dirty) {
+            state.dirty = false;
+            await this.drainOnce(runId);
+        }
+    }
+    async drainOnce(runId) {
+        const backoff = this.backoffs.get(runId);
+        if (backoff !== undefined && this.now() < backoff.nextAttemptAt)
+            return;
+        const snapshot = await this.withReceiptUpdate(runId, (run) => ({
+            id: run.id,
+            flowName: run.flowName,
+            ...(run.workspaceRoot !== undefined ? { workspaceRoot: run.workspaceRoot } : {}),
+            ...(run.revisionDigest !== undefined ? { revisionDigest: run.revisionDigest } : {}),
+            pending: (run.receipts ?? [])
+                .filter((receipt) => receipt.egress === "pending")
+                .sort((left, right) => left.seq - right.seq)
+                .map((receipt) => structuredClone(receipt)),
+        }));
+        if (snapshot.pending.length === 0)
+            return;
+        const transitions = [];
+        for (const receipt of snapshot.pending) {
+            let response;
+            let failure;
+            try {
+                response = await this.add(snapshot, receipt);
+            }
+            catch (error) {
+                failure = error;
+            }
+            if (response?.ok) {
+                transitions.push({ seq: receipt.seq, egress: "sent" });
+                this.resetBackoff(runId);
+                continue;
+            }
+            if (response !== undefined && DEAD_STATUSES.has(response.status)) {
+                transitions.push({ seq: receipt.seq, egress: "dead", status: response.status });
+                this.warn(`SmartMemory egress dead-lettered ${snapshot.id}:${receipt.seq}: HTTP ${response.status}`);
+                continue;
+            }
+            this.recordFailure(runId);
+            const detail = response === undefined ? message(failure) : `HTTP ${response.status}`;
+            this.warn(`SmartMemory egress stopped at ${snapshot.id}:${receipt.seq}: ${detail}`);
+            break;
+        }
+        if (transitions.length === 0)
+            return;
+        await this.withReceiptUpdate(runId, (run) => {
+            const bySequence = new Map((run.receipts ?? []).map((receipt) => [receipt.seq, receipt]));
+            for (const transition of transitions) {
+                const receipt = bySequence.get(transition.seq);
+                if (receipt === undefined || receipt.egress !== "pending")
+                    continue;
+                receipt.egress = transition.egress;
+                if (transition.status === undefined)
+                    delete receipt.egressStatus;
+                else
+                    receipt.egressStatus = transition.status;
+            }
+        });
+    }
+    async add(run, receipt) {
+        return this.request(`${this.url}/memory/add`, {
+            content: summary(run, receipt),
+            memory_type: memoryTypeFor(receipt),
+            metadata: {
+                ...receipt,
+                ...(receipt.detail !== undefined ? { detail: receipt.detail } : {}),
+                run_id: run.id,
+                workspace_root: run.workspaceRoot ?? null,
+                flow_name: run.flowName,
+                spec_digest: run.revisionDigest ?? null,
+                event_ordinal: receipt.seq,
+                receipt_id: `${run.id}:${receipt.seq}`,
+                origin: "cli:stratum",
+            },
+            use_pipeline: false,
+        });
+    }
+    async exactHits(receiptId, memoryType) {
+        const response = await this.request(`${this.url}/memory/search`, {
+            query: receiptId,
+            memory_type: memoryType,
+            top_k: 20,
+        });
+        if (!response.ok)
+            throw new Error(`SmartMemory verify failed for ${memoryType}: HTTP ${response.status}`);
+        const payload = await response.json();
+        if (!Array.isArray(payload.results))
+            throw new Error(`SmartMemory verify returned no results array for ${memoryType}`);
+        return payload.results.filter((result) => resultReceiptId(result) === receiptId && resultMemoryType(result) === memoryType);
+    }
+    async request(url, body) {
+        const controller = new AbortController();
+        const timeout = this.setTimeoutImpl(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        try {
+            return await this.fetchImpl(url, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "X-Workspace-Id": this.workspaceId,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        finally {
+            this.clearTimeoutImpl(timeout);
+        }
+    }
+    recordFailure(runId) {
+        const current = this.backoffs.get(runId) ?? { consecutiveFailures: 0, nextAttemptAt: 0 };
+        current.consecutiveFailures += 1;
+        const exponent = Math.min(current.consecutiveFailures - 1, 20);
+        const base = Math.min(MAX_BACKOFF_MS, MIN_BACKOFF_MS * (2 ** exponent));
+        const jittered = Math.min(MAX_BACKOFF_MS, base + (base * 0.2 * this.random()));
+        current.nextAttemptAt = this.now() + jittered;
+        this.backoffs.set(runId, current);
+    }
+    resetBackoff(runId) {
+        this.backoffs.delete(runId);
+    }
+}
+function memoryTypeFor(receipt) {
+    if (receipt.source === "engine" && receipt.dispatchId.startsWith("engine:step_reset:"))
+        return "stratum_step_reset";
+    if (receipt.source === "engine" && receipt.dispatchId.startsWith("engine:checkpoint_reverted:"))
+        return "stratum_checkpoint_reverted";
+    return "stratum_usage_debit";
+}
+function summary(run, receipt) {
+    const tokens = receipt.amount.tokens ?? 0;
+    const milliseconds = receipt.amount.ms ?? receipt.telemetry.durationMs;
+    return `${run.flowName}/${receipt.stepId ?? "run"} ${receipt.source} (${receipt.telemetry.model}): ${tokens} tokens, ${milliseconds} ms`;
+}
+function resultReceiptId(result) {
+    return resultField(result, (value) => {
+        if (typeof value.receipt_id === "string")
+            return value.receipt_id;
+        if (typeof value.metadata !== "object" || value.metadata === null || Array.isArray(value.metadata))
+            return undefined;
+        const receiptId = value.metadata.receipt_id;
+        return typeof receiptId === "string" ? receiptId : undefined;
+    });
+}
+function resultMemoryType(result) {
+    return resultField(result, (value) => {
+        if (typeof value.memory_type === "string")
+            return value.memory_type;
+        if (typeof value.metadata !== "object" || value.metadata === null || Array.isArray(value.metadata))
+            return undefined;
+        const memoryType = value.metadata.memory_type;
+        return typeof memoryType === "string" ? memoryType : undefined;
+    });
+}
+function resultField(result, read) {
+    if (typeof result !== "object" || result === null || Array.isArray(result))
+        return undefined;
+    const row = result;
+    const direct = read(row);
+    if (direct !== undefined)
+        return direct;
+    for (const key of ["item", "context"]) {
+        const nested = row[key];
+        if (typeof nested !== "object" || nested === null || Array.isArray(nested))
+            continue;
+        const found = read(nested);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=smartmemory_egress.js.map

package/dist/learn/smartmemory_egress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smartmemory_egress.js","sourceRoot":"","sources":["../../src/learn/smartmemory_egress.ts"],"names":[],"mappings":"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"}

package/dist/mcp/server.js

@@ -1,11 +1,11 @@
+import { linkAbort, teardownDeadline } from "../connectors/cancellation.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
-import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { stat } from "node:fs/promises";
 import { cancelBackgroundRun, pollBackgroundRun, runAgent } from "../connectors/index.js";
-import { CheckpointOperationError, SpecValidationError, StratumEngine } from "../engine/engine.js";
+import { CheckpointOperationError, InputValidationError, SpecValidationError, StratumEngine } from "../engine/engine.js";
 import { createEvaluator } from "../eval/expr.js";
 import { createEvaluateRunner } from "../engine/evaluate.js";
 import { validateSpec } from "../ir/validate.js";
@@ -53,14 +53,65 @@ function defaultEngine() {
         evaluateRunner: createEvaluateRunner(),
     });
 }
+/** Every structured MCP error goes through the registry: an envelope the
+ * contract does not declare (or whose payload drifts from the declaration)
+ * fails here rather than reaching a client as an undeclared shape. */
+async function registryError(envelope, errorCode, message, data) {
+    const declaration = (await mcpSurface()).errors[envelope];
+    if (!declaration)
+        throw new Error(`MCP error registry is missing ${envelope}`);
+    assertShape(data, declaration.data, `errors.${envelope}.data`);
+    return new McpError(errorCode, message, data);
+}
+/** Rejects a request field before the contract check can run — the cancellation
+ * bookkeeping below must be in place before any awaited contract I/O, so these
+ * few fields are validated by hand and reported in the declared shape. */
+function inputValidationError(path, message) {
+    return registryError("input_validation_failed", ErrorCode.InvalidParams, message, {
+        code: "input_validation_failed",
+        errors: [{ code: "input_validation_failed", path, message }],
+    });
+}
 export function createToolDispatcher(dependencies = {}) {
     const engine = dependencies.engine ?? defaultEngine();
     const agentRun = dependencies.runAgent ?? runAgent;
     const agentPoll = dependencies.pollBackgroundRun ?? pollBackgroundRun;
     const agentCancel = dependencies.cancelBackgroundRun ?? cancelBackgroundRun;
+    // Register before contract I/O: an immediate cancellation cannot overtake startup.
+    // UUIDs cannot collide with durable background IDs.
+    const foreground = new Map();
+    const completed = new Map();
     return {
         async call(tool, request, context = {}) {
+            // This request has one required string field. Check that exact shape before
+            // acting synchronously, otherwise contract loading can let startup overtake
+            // an already-received cancellation. Full contract validation still follows.
+            if (tool === "stratum_cancel_agent_run" && typeof request.runId === "string"
+                && Object.keys(request).length === 1) {
+                foreground.get(request.runId)?.controller.abort(new Error("Foreground agent run cancelled"));
+            }
+            let cancellationId;
+            let controller;
+            let settle;
+            let unlink;
+            let succeeded = false;
+            let teardownFailure;
             try {
+                if (tool === "stratum_agent_run" && request.cancellationId !== undefined) {
+                    if (typeof request.cancellationId !== "string"
+                        || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(request.cancellationId)) {
+                        throw await inputValidationError("cancellationId", "cancellationId must be a UUID");
+                    }
+                    cancellationId = request.cancellationId;
+                    if (request.background === true)
+                        throw await inputValidationError("background", "cancellationId is only supported for foreground runs");
+                    if (foreground.has(cancellationId) || completed.has(cancellationId))
+                        throw await inputValidationError("cancellationId", "cancellationId has already been used");
+                    controller = new AbortController();
+                    const settled = new Promise((resolve) => { settle = resolve; });
+                    foreground.set(cancellationId, { controller, settled });
+                    unlink = linkAbort(context.signal, controller);
+                }
                 await assertToolRequest(tool, request);
                 let response;
                 switch (tool) {
@@ -91,12 +142,21 @@ export function createToolDispatcher(dependencies = {}) {
                         response = validation.ok ? { status: "valid" } : { status: "invalid", errors: validation.errors };
                         break;
                     }
-                    case "stratum_plan":
-                        response = await engine.plan(request.spec, request.input, option(request, "workspaceRoot"));
+                    case "stratum_plan": {
+                        const policyStepSelector = optionalString(request, "policy_step_selector");
+                        response = await engine.plan(request.spec, request.input, {
+                            ...option(request, "workspaceRoot"),
+                            ...(request.policy_bundle !== undefined ? { policyBundle: record(request, "policy_bundle") } : {}),
+                            ...(policyStepSelector !== undefined ? { policyStepSelector } : {}),
+                        });
                         break;
+                    }
                     case "stratum_step_done":
                         response = await engine.stepDone(string(request, "runId"), string(request, "stepId"), record(request, "result"), string(request, "dispatchToken"));
                         break;
+                    case "stratum_usage_report":
+                        response = await engine.usageReport(string(request, "runId"), record(request, "receipt"));
+                        break;
                     case "stratum_commit":
                         response = { ...await engine.commit(string(request, "flow_id"), string(request, "label")) };
                         break;
@@ -110,7 +170,7 @@ export function createToolDispatcher(dependencies = {}) {
                         response = auditResponse(await engine.audit(string(request, "runId")));
                         break;
                     case "stratum_gate_resolve":
-                        response = await engine.gateResolve(string(request, "runId"), string(request, "stepId"), string(request, "decision"), string(request, "gateToken"));
+                        response = await engine.gateResolve(string(request, "runId"), string(request, "stepId"), string(request, "decision"), string(request, "gateToken"), optionalString(request, "user_id"));
                         break;
                     case "stratum_flow_poll":
                         response = flowPollResponse(await engine.flowPoll(string(request, "runId"), optionalNumber(request, "cursor")));
@@ -138,6 +198,7 @@ export function createToolDispatcher(dependencies = {}) {
                             : undefined;
                         const executed = await agentRun({
                             agent: string(request, "agent"),
+                            ...(cancellationId !== undefined ? { ownProcessGroup: true } : {}),
                             prompt: string(request, "prompt"),
                             cwd: string(request, "cwd"),
                             // Presence-based forwarding, NOT truthiness: sandboxMode:"" must reach
@@ -150,37 +211,73 @@ export function createToolDispatcher(dependencies = {}) {
                             ...(allowedTools !== undefined ? { allowedTools } : {}),
                             ...(disallowedTools !== undefined ? { disallowedTools } : {}),
                             ...(context.onAgentEvent !== undefined ? { onEvent: context.onAgentEvent } : {}),
+                            ...((controller?.signal ?? context.signal) !== undefined ? { signal: (controller?.signal ?? context.signal) } : {}),
+                            ...(request.thinking !== undefined ? { thinking: record(request, "thinking") } : {}),
+                            ...(request.effort !== undefined ? { effort: string(request, "effort") } : {}),
                         });
+                        unlink?.(); // Provider finished; a late disconnect cannot cancel a completed run.
+                        succeeded = true;
                         response = "status" in executed ? { ...executed } : { status: "complete", ...executed };
                         break;
                     }
                     case "stratum_agent_poll":
                         response = await agentPoll(string(request, "runId"));
                         break;
-                    case "stratum_cancel_agent_run":
-                        response = await agentCancel(string(request, "runId"));
+                    case "stratum_cancel_agent_run": {
+                        const runId = string(request, "runId");
+                        const running = foreground.get(runId);
+                        if (running) {
+                            running.controller.abort(new Error("Foreground agent run cancelled"));
+                            // Acknowledge only after the connector has finished teardown.
+                            await teardownDeadline(running.settled, dependencies.cancellationTimeoutMs ?? Number(process.env.STRATUM_CANCEL_TIMEOUT_MS ?? 15000), "Foreground connector teardown did not settle");
+                            const outcome = completed.get(runId);
+                            if (outcome instanceof Error)
+                                throw outcome;
+                            response = { status: "cancelled", runId };
+                        }
+                        else if (completed.has(runId)) {
+                            const outcome = completed.get(runId);
+                            if (outcome instanceof Error)
+                                throw outcome;
+                            response = { status: outcome, runId };
+                        }
+                        else
+                            response = await agentCancel(runId);
                         break;
+                    }
                     case "stratum_guard_register": {
                         const { registerGuard } = await import("../guard/transition.js");
-                        response = await registerGuard(string(request, "resource_id"), record(request, "graph"), record(request, "edge_predicates"), string(request, "initial"), optionalArray(request, "terminal"), optionalRecord(request, "stakes"), optionalString(request, "workspace_root") ?? null);
+                        response = await registerGuard(string(request, "resource_id"), record(request, "graph"), record(request, "edge_predicates"), string(request, "initial"), optionalArray(request, "terminal"), optionalRecord(request, "stakes"), optionalString(request, "workspace_root") ?? null, request.policy_bundle !== undefined ? record(request, "policy_bundle") : undefined);
                         break;
                     }
                     case "stratum_guard_transition": {
                         const { guardTransition } = await import("../guard/transition.js");
+                        const runId = optionalString(request, "run_id");
                         response = await guardTransition(string(request, "resource_id"), string(request, "from_state"), string(request, "to_state"), {
                             artifacts: record(request, "artifacts"), modifiedFiles: optionalArray(request, "modified_files"), idempotencyKey: optionalString(request, "idempotency_key") ?? null, resolvedBy: optionalString(request, "resolved_by") ?? "agent",
+                            ...(runId !== undefined ? { runId } : {}),
                             ...(dependencies.guardJudge !== undefined ? { judge: dependencies.guardJudge } : {}),
                         });
                         break;
                     }
                     case "stratum_guard_override": {
                         const { guardOverride } = await import("../guard/transition.js");
-                        response = await guardOverride(string(request, "resource_id"), string(request, "from_state"), string(request, "to_state"), string(request, "override_token"), string(request, "rationale"), optionalString(request, "resolved_by") ?? "human");
+                        response = await guardOverride(string(request, "resource_id"), string(request, "from_state"), string(request, "to_state"), string(request, "authorization"), string(request, "rationale"), optionalString(request, "resolved_by") ?? "human", optionalString(request, "user_id"), optionalString(request, "run_id"));
                         break;
                     }
                     case "stratum_guard_migrate": {
                         const { guardMigrate } = await import("../guard/transition.js");
-                        response = await guardMigrate(string(request, "resource_id"), record(request, "new_graph"), record(request, "new_edge_predicates"), string(request, "override_token"), string(request, "rationale"), optionalArray(request, "new_terminal"), optionalRecord(request, "new_stakes"));
+                        response = await guardMigrate(string(request, "resource_id"), record(request, "new_graph"), record(request, "new_edge_predicates"), string(request, "authorization"), string(request, "rationale"), optionalArray(request, "new_terminal"), optionalRecord(request, "new_stakes"));
+                        break;
+                    }
+                    case "stratum_guard_upgrade": {
+                        const { guardUpgrade } = await import("../guard/transition.js");
+                        response = await guardUpgrade(string(request, "resource_id"), record(request, "new_graph"), record(request, "new_edge_predicates"), string(request, "rationale"), optionalArray(request, "new_terminal"), optionalRecord(request, "new_stakes"));
+                        break;
+                    }
+                    case "stratum_guard_apply_upgrade": {
+                        const { guardApplyUpgrade } = await import("../guard/transition.js");
+                        response = await guardApplyUpgrade(string(request, "resource_id"), string(request, "descriptor_id"));
                         break;
                     }
                     case "stratum_guard_history": {
@@ -194,31 +291,53 @@ export function createToolDispatcher(dependencies = {}) {
                         await assertEvent(event);
                 }
                 await assertToolResponse(tool, response);
+                succeeded = true;
                 return response;
             }
             catch (error) {
+                if (error instanceof Error && "code" in error
+                    && ["CANCELLATION_TEARDOWN_TIMEOUT", "CANCELLATION_UNCONFIRMED"].includes(String(error.code))) {
+                    teardownFailure = error;
+                }
                 if (error instanceof SpecValidationError) {
                     const code = tool === "stratum_flow_run_bg"
                         && error.errors.some((entry) => entry.code === "consumer_dispatch_bg_unsupported")
-                        ? "consumer_dispatch_bg_unsupported" : "spec_validation_failed";
-                    const data = { code, errors: error.errors };
-                    const declaration = (await mcpSurface()).errors[code];
-                    if (!declaration)
-                        throw new Error(`MCP error registry is missing ${code}`);
-                    assertShape(data, declaration.data, `errors.${code}.data`);
-                    throw new McpError(ErrorCode.InvalidParams, error.message, data);
+                        ? "consumer_dispatch_bg_unsupported" : error instanceof InputValidationError ? "input_validation_failed" : "spec_validation_failed";
+                    throw await registryError(code, ErrorCode.InvalidParams, error.message, { code, errors: error.errors });
                 }
                 if ((tool === "stratum_commit" || tool === "stratum_revert") && error instanceof CheckpointOperationError) {
                     const response = checkpointErrorEnvelope(error);
                     await assertToolResponse(tool, response);
                     return response;
                 }
+                if (tool === "stratum_agent_run" || tool === "stratum_cancel_agent_run") {
+                    // An McpError already carries a declared code and payload — rewrapping it
+                    // as agent_run_failed would replace a precise contract error (a rejected
+                    // request field, an undeclared response) with a generic provider failure.
+                    if (error instanceof McpError)
+                        throw error;
+                    const failure = error;
+                    // The envelope is always agent_run_failed; `code` names the specific
+                    // connector failure (CANCELLATION_TEARDOWN_TIMEOUT and friends) when it has one.
+                    const data = { code: failure.code ?? "agent_run_failed", ...Object.fromEntries(["usage", "split", "usdSource", "stderr", "telemetry"].filter(key => key in Object(failure)).map(key => [key, failure[key]])) };
+                    throw await registryError("agent_run_failed", ErrorCode.InternalError, failure.message ?? String(error), data);
+                }
                 if (!tool.startsWith("stratum_guard_"))
                     throw error;
                 const response = guardErrorEnvelope(error);
                 await assertToolResponse(tool, response);
                 return response;
             }
+            finally {
+                unlink?.();
+                if (cancellationId !== undefined && controller) {
+                    completed.set(cancellationId, teardownFailure ?? (succeeded ? "already_complete" : controller.signal.aborted ? "cancelled" : "already_error"));
+                    foreground.delete(cancellationId);
+                    if (completed.size > 1024)
+                        completed.delete(completed.keys().next().value);
+                    settle?.();
+                }
+            }
         },
     };
 }
@@ -257,20 +376,29 @@ export async function createMcpServer(dependencies = {}) {
             heartbeat.unref?.();
         }
         try {
-            let context;
+            let context = { signal: extra.signal };
             if (request.params.name === "stratum_agent_run" && progressToken !== undefined) {
-                const flowId = randomUUID();
+                // No flow_id: an agent run has no flow, and a server-invented UUID cannot
+                // match any consumer's correlation id — compose dropped EVERY agent event
+                // as "misrouted" while it was stamped (2026-08-30 census). Progress
+                // notifications are already scoped to this call by progressToken; the
+                // consumer stamps its own correlation id on an absent flow_id.
                 let eventSeq = 0;
                 context = {
+                    signal: extra.signal,
                     onAgentEvent: async (event) => {
                         const message = JSON.stringify({
-                            schema_version: "0.2.7",
-                            flow_id: flowId,
+                            // 0.2.8: flow_id is OPTIONAL on `_agent_run` envelopes (call-local).
+                            schema_version: "0.2.8",
                             step_id: "_agent_run",
                             seq: eventSeq,
                             ts: new Date().toISOString(),
                             kind: event.kind,
-                            metadata: event.metadata,
+                            // Agent connector events are call-local; stamp the same step
+                            // identity in usage metadata required by the BuildStreamEvent contract.
+                            metadata: event.kind === "step_usage"
+                                ? { ...event.metadata, stepId: "_agent_run" }
+                                : event.metadata,
                             reply_required: false,
                         });
                         eventSeq += 1;