@sema-agent/server 7.92.1 → 7.92.2

package/dist/runs.js

@@ -1,5 +1,5 @@
-import { runWithVerification, runCascade, defaultTaskRegistry, terminalProjection, DURABLE_AGENT_HANDLE_RE } from "@sema-agent/core";
-import { failureCodeOf, stripResumeToken } from "./terminal.js";
+import { runWithVerification, runCascade, defaultTaskRegistry, DURABLE_AGENT_HANDLE_RE } from "@sema-agent/core";
+import { failureCodeOf, sealResultForExit, outwardPlane } from "./terminal.js";
 import { GOVERNANCE_HTTP_STATUS } from "./governance-http-status.js";
 import { redactErrorMessage } from "./observability/run-terminal.js";
 import { withPrincipal } from "./observability/principal-context.js";
@@ -311,10 +311,10 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 await flush();
                 evictIfConflict(runner, spec.sessionId, result);
                 await flushPromptManifest();
-                const safe = await withModelUsage(stripResumeToken(result));
+                const safe = await withModelUsage(sealResultForExit(result));
                 await append("done", { result: safe });
                 reached = { kind: "done", result: safe };
-                const plane = terminalProjection(safe.terminal);
+                const plane = outwardPlane(safe.terminal);
                 await runStore.setTerminal(taskId, plane.status, safe, plane.errorMessage ?? null);
                 recordDone(safe, plane.status);
                 return;
@@ -324,10 +324,10 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 await flush();
                 evictIfConflict(runner, spec.sessionId, result);
                 await flushPromptManifest();
-                const safe = await withModelUsage(stripResumeToken(result));
+                const safe = await withModelUsage(sealResultForExit(result));
                 await append("done", { result: safe });
                 reached = { kind: "done", result: safe };
-                const plane = terminalProjection(safe.terminal);
+                const plane = outwardPlane(safe.terminal);
                 await runStore.setTerminal(taskId, plane.status, safe, plane.errorMessage ?? null);
                 recordDone(safe, plane.status);
                 return;
@@ -358,7 +358,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 }
                 if (ev.type === "done") {
                     await flush();
-                    const parkStatus = ev.result.terminal.kind === "paused" ? terminalProjection(ev.result.terminal).status : undefined;
+                    const parkStatus = ev.result.terminal.kind === "paused" ? outwardPlane(ev.result.terminal).status : undefined;
                     if (parkStatus === "suspended") {
                         await sink.appendParked("suspended", await graftParkToolCallId(ev.result, parkCheckpointReader));
                         await flushModelUsage();
@@ -376,10 +376,10 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                     {
                         const settled = cancelledAtDone ? cancelledResult(ev.result) : ev.result;
                         settledAsCancel = failureCodeOf(settled.terminal) === CANCELLED_CODE;
-                        const safe = await withModelUsage(stripResumeToken(settled));
+                        const safe = await withModelUsage(sealResultForExit(settled));
                         await sink.appendDone(safe);
                         reached = { kind: "done", result: safe };
-                        const plane = terminalProjection(safe.terminal);
+                        const plane = outwardPlane(safe.terminal);
                         await runStore.setTerminal(taskId, plane.status, safe, plane.errorMessage ?? null);
                         recordDone(safe, failureCodeOf(safe.terminal) === CANCELLED_CODE ? CANCELLED_CODE : plane.status);
                     }
@@ -436,7 +436,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 recordFailOpen("server.runs.terminal-ledger-write-failed", `arm=append-clean-cancel ${errText(e)}`);
             }
             reached = { kind: "done", result: c };
-            await runStore.setTerminal(taskId, "failed", c, terminalProjection(c.terminal).errorMessage ?? null);
+            await runStore.setTerminal(taskId, "failed", c, outwardPlane(c.terminal).errorMessage ?? null);
             recordDone(c, CANCELLED_CODE);
         }
     }
@@ -450,7 +450,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 recordFailOpen("server.runs.terminal-ledger-write-failed", `arm=flush-catch ${errText(e)}`);
             }
             if (reached?.kind === "done") {
-                const plane = terminalProjection(reached.result.terminal);
+                const plane = outwardPlane(reached.result.terminal);
                 settledAsCancel = failureCodeOf(reached.result.terminal) === CANCELLED_CODE;
                 await runStore.setTerminal(taskId, plane.status, reached.result, plane.errorMessage ?? null);
             }
@@ -469,7 +469,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 catch (e) {
                     recordFailOpen("server.runs.terminal-ledger-write-failed", `arm=append-thrown-cancel ${errText(e)}`);
                 }
-                await runStore.setTerminal(taskId, "failed", c, terminalProjection(c.terminal).errorMessage ?? null);
+                await runStore.setTerminal(taskId, "failed", c, outwardPlane(c.terminal).errorMessage ?? null);
             }
             else {
                 settledAsCancel = false;
@@ -486,7 +486,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         catch {
         }
         if (reached?.kind === "done")
-            recordDone(reached.result, failureCodeOf(reached.result.terminal) === CANCELLED_CODE ? CANCELLED_CODE : terminalProjection(reached.result.terminal).status);
+            recordDone(reached.result, failureCodeOf(reached.result.terminal) === CANCELLED_CODE ? CANCELLED_CODE : outwardPlane(reached.result.terminal).status);
         else if (reached?.kind === "suspended") {
             metrics?.addGauge("runs_active", -1);
             metrics?.inc("tasks_total", { status: "suspended" });
@@ -503,7 +503,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         unregisterEngineNotice();
         if (fleetPublisher) {
             if (reached?.kind === "done")
-                fleetPublisher.onTerminal(failureCodeOf(reached.result.terminal) === CANCELLED_CODE ? CANCELLED_CODE : terminalProjection(reached.result.terminal).status, fleetRunResiduals(reached.result));
+                fleetPublisher.onTerminal(failureCodeOf(reached.result.terminal) === CANCELLED_CODE ? CANCELLED_CODE : outwardPlane(reached.result.terminal).status, fleetRunResiduals(reached.result));
             else if (reached?.kind === "suspended")
                 fleetPublisher.onTerminal("suspended");
             else if (reached?.kind === "needs_review")

package/dist/terminal.d.ts

@@ -16,9 +16,9 @@
  *    (run 行的 `status` / `error` 列、`tasks_total{status}` 计量标签、fleet 行的终态词)。出口之外不拼。
  *
  * wire 面(HTTP 任务体、SSE `done.result`)**就是结果本身**,所以它跟着 core 一起丢八键、带 `terminal`
- * —— 那里没有投影,只有转发(见 {@link stripResumeToken} 的例外)。
+ * —— 那里没有投影,只有转发(见 {@link sealResultForExit} 的例外)。
  */
-import { type PausedCause, type TaskStatus, type TerminalCause } from "@sema-agent/core";
+import { terminalProjection, type PausedCause, type TaskStatus, type TerminalCause } from "@sema-agent/core";
 /**
  * 这次失败带的**机器码**(`terminal.failed.code`);非失败终局 ⇒ `undefined`。
  *
@@ -31,7 +31,46 @@ import { type PausedCause, type TaskStatus, type TerminalCause } from "@sema-age
  */
 export declare function failureCodeOf(terminal: TerminalCause): string | undefined;
 /**
- * 把**耐久恢复能力凭据**(`CheckpointToken`)从一条结果里摘掉,再让它进可重放账本 / run 行 / wire。
+ * 本仓**对外机器码**的词法(S-548)。附录 A 那张表、core 的点名族(`limits.*` / `config.*` /
+ * `resume_at.*` / `output.*` / brain 扁平码)、工具层自注册码 —— 全体成员都是这一形:**小写**的
+ * `a-z0-9_`,用 `.` 分族。门 {@link OUTWARD_CODE_SHAPE} 在 `test/terminal-store-error-fold.test.ts`
+ * 里对**目录里真有的每一个码**断言这条词法(判据由 catalog 机器派生,不是手抄的一张清单)。
+ */
+export declare const OUTWARD_CODE_SHAPE: RegExp;
+/** 域外失败码的**唯一**落点(附录外的新码;原码进日志与 message,不丢)。 */
+export declare const STORE_ERROR_CODE = "internal.store_error";
+/**
+ * 一个失败码要上 wire 之前的**归一**(S-548)。在词法内 ⇒ 原样;词法外 ⇒ {@link STORE_ERROR_CODE}。
+ *
+ * ── 病(test T-47,三库一致)────────────────────────────────────────────────────────────────────
+ * 本仓的 SQL 店把**驱动原生错误**原样抛回引擎,而 core 的 `errorCodeOf` 沿 `err.code`/`cause` 链取
+ * **第一个非空字符串**当这次失败的机器码 —— 于是 mysql2 的 `ER_BAD_FIELD_ERROR` / node-pg 的 SQLSTATE
+ * `42703` **逐字**成了 `POST /v1/tasks` 回给消费端的 `terminal.failed.code`。消费端拿到的是一个它的码表里
+ * 根本没有、而且随数据库厂商/版本变化的串。
+ *
+ * ── 为什么判据是**词法**而不是「在不在附录 A 那张表里」────────────────────────────────────────
+ * 亲读实现证伪了白名单形:`output.invalid` / `suspend.loop` / `resume_at.*` 这些**合法的引擎终局码**
+ * 今天**不在**附录 A(那张表的辖域是 4xx/5xx 错误体,不是 run 终局),白名单会把它们一起折掉 ——
+ * 那不仅丢诊断,还会当场打死 `resumeAtHttpStatus` 的 404/422 分诊腿。词法判据则是一条**正面**规则:
+ * 「本仓与引擎的码全是小写点分」,而驱动码全是 SCREAMING_SNAKE(`ER_*` / `PROTOCOL_*` / `ECONNRESET`)
+ * 或五位 SQLSTATE(`42703`)—— 两个字符集不相交,一条规则覆盖整类,**零逐码特判**。
+ *
+ * ⚠️ **辖域如实**:本臂触发条件是「码出了本仓的词法」,所以任何依赖铸出的域外码都落这里,不只 SQL 驱动。
+ * 今天可观察的产出方**只有**耐久店那一层(引擎自己的传输/brain 错误在 core 侧已被分类成小写码),故码名
+ * 取 `internal.store_error`;原码逐字进 message 与 warn 行,归因从不丢失。
+ */
+export declare function outwardFailureCode(code: string): string;
+/**
+ * **一条结果离开引擎、进入本仓(可重放账本 / run 行 / wire)的唯一封口** —— 两件事,一个出口:
+ *  ①摘掉**耐久恢复能力凭据**(`CheckpointToken`);②把**域外的失败码**折成本仓的 `internal.store_error`
+ *  ({@link outwardFailureCode},S-548)。
+ *
+ * 🔴 为什么两件事合在一只函数里而不是并列两只(7.92.2 改名 `stripResumeToken` → `sealResultForExit`):
+ * 它们是**同一个出口上的同一件事** —— 「这条结果可以见人了吗」。并列两只 = 六个结算点各自要记得调两次,
+ * 而漏调的那一次不会红、只会在某天的 wire 上露出一个不该露的东西(凭据或驱动码)。名字跟着职责改:
+ * 旧名只说了摘凭据那一半,一个只做一半的名字会让下一个人在另一半上另开出口。
+ *
+ * ── ① 摘凭据 ──
  * token 就是 resume 凭据(token-as-auth,search [18] Q1b),**永不离开本服务**;非密的 `gate` /
  * `checkpointId` / `restoreMode` 有意保留(对账位)。
  *
@@ -49,9 +88,24 @@ export declare function failureCodeOf(terminal: TerminalCause): string | undefin
  *
  * 对任何输入安全(非普通对象 / 无 `terminal` / 因由不带 token ⇒ **同一引用**原样返回,不重塑)。
  */
-export declare function stripResumeToken<T extends {
+export declare function sealResultForExit<T extends {
     terminal: TerminalCause;
 }>(result: T): T;
+/**
+ * **投影出口的唯一属主**(S-548)—— core 的 `terminalProjection` + 对外码归一,一次。
+ *
+ * `docs/ASSISTANT-WIRE-CONTRACT.md` §5.0 说清了终局有**两张脸**:①结果**本身**(`done.result` / 200 体 /
+ * `GET /v1/runs/:id → result`,零投影)与②**五词投影**(run 行的 `status` / `error_code` 列、fleet 终态词、
+ * 决策腿 200 体的三格平面词)。两张脸各有一个属主:①是 {@link sealResultForExit},②就是本函数。
+ * **两个属主都折码**,否则同一次失败在两张脸上说两个不同的码 —— 而缺的那一张正是 S-548 修前仍在泄漏的
+ * 那条路(codex 对抗复审本轮 [medium],亲读证实:决策腿的 200 体从**未封口的** result 投影 `errorCode`,
+ * 于是驱动原生码照旧上 wire,尽管同一段代码落库那份已经折过)。
+ *
+ * ⇒ 纪律:**`src/` 里除本文件外不许再直接调 core 的 `terminalProjection`**(门在
+ * `test/terminal-store-error-fold.test.ts` ④)。折叠**幂等**(折过的码再折还是它自己),所以对一个已经封口的
+ * 结果调本函数是安全的 no-op —— 调用方不需要记得"这个 result 封过了没有"。
+ */
+export declare function outwardPlane(terminal: TerminalCause): ReturnType<typeof terminalProjection>;
 /**
  * 这条腿的结果里**藏着的那次耐久暂停** —— 嵌套边界(verify / cascade)遇到自己驱动不了的耐久 park 时,
  * 在**它的**边界上如实报 `failed`(码是 `unexpected.suspended` / `unexpected.needs_review`),而把那次

package/dist/terminal.js

@@ -3,15 +3,37 @@ import { recordFailOpen } from "./observability/fail-open.js";
 export function failureCodeOf(terminal) {
     return terminal.kind === "failed" ? terminal.code : undefined;
 }
-export function stripResumeToken(result) {
+export const OUTWARD_CODE_SHAPE = /^[a-z][a-z0-9_]*(?:\.[a-z0-9_]+)*$/;
+export const STORE_ERROR_CODE = "internal.store_error";
+export function outwardFailureCode(code) {
+    return OUTWARD_CODE_SHAPE.test(code) ? code : STORE_ERROR_CODE;
+}
+export function sealResultForExit(result) {
     const t = result?.terminal;
     if (t === null || typeof t !== "object")
         return result;
     if (t.kind === "paused")
         return { ...result, terminal: stripPausedToken(t) };
-    if (t.kind === "failed" && t.nestedPause !== undefined)
-        return { ...result, terminal: { ...t, nestedPause: stripPausedToken(t.nestedPause) } };
-    return result;
+    if (t.kind !== "failed")
+        return result;
+    let terminal = t;
+    if (t.nestedPause !== undefined)
+        terminal = { ...terminal, nestedPause: stripPausedToken(t.nestedPause) };
+    if (t.code !== undefined) {
+        const outward = outwardFailureCode(t.code);
+        if (outward !== t.code) {
+            console.warn(`[terminal] outward_failure_code_folded original=${t.code} outward=${outward}`, { message: t.message });
+            terminal = { ...terminal, code: outward, message: `${t.message ?? "the durable store failed"} [original code: ${t.code}]` };
+        }
+    }
+    return terminal === t ? result : { ...result, terminal };
+}
+export function outwardPlane(terminal) {
+    const plane = terminalProjection(terminal);
+    if (plane.errorCode === undefined)
+        return plane;
+    const outward = outwardFailureCode(plane.errorCode);
+    return outward === plane.errorCode ? plane : { ...plane, errorCode: outward };
 }
 function stripPausedToken(paused) {
     const { token: _drop, ...rest } = paused;
@@ -30,7 +52,7 @@ export function persistedPlaneOf(result) {
     if (r.terminal !== null && typeof r.terminal === "object") {
         let projected;
         try {
-            projected = terminalProjection(r.terminal);
+            projected = outwardPlane(r.terminal);
         }
         catch (e) {
             recordFailOpen("server.terminal.persisted-plane-malformed", e instanceof Error ? e.message : String(e));
@@ -47,7 +69,7 @@ export function persistedPlaneOf(result) {
     }
     return {
         ...(typeof r.status === "string" ? { status: r.status } : {}),
-        ...(typeof r.errorCode === "string" ? { errorCode: r.errorCode } : {}),
+        ...(typeof r.errorCode === "string" ? { errorCode: outwardFailureCode(r.errorCode) } : {}),
         ...(typeof r.errorMessage === "string" ? { errorMessage: r.errorMessage } : {}),
         ...(typeof r.blockedReason === "string" ? { blockedReason: r.blockedReason } : {}),
     };

package/dist/trace/ledger-sink.js

@@ -1,4 +1,5 @@
-import { terminalProjection } from "@sema-agent/core";
+import {} from "@sema-agent/core";
+import { outwardPlane } from "../terminal.js";
 import { modelTextEventData, toolStartEventData, toolEndEventData, taskProgressEventData, taskNotificationEventData, compactedEventData, diagnosticsEventData, brainStatusEventData, steeringInjectedEventData, compactionOutcomeEventData, workspaceChangedEventData, wiringManifestEventData, toolRosterDeltaEventData, toolDisclosureEventData, humanInputEventData, turnEndEventData, contextUsageEventData } from "./project.js";
 import { NotifiedKeys, taskNotificationStreamKey } from "../orchestration/workflow-completion-inbox.js";
 import { isParkLedgerEventType } from "./ledger-events.js";
@@ -164,7 +165,7 @@ export function createLedgerSink(opts) {
     const onDone = async (result) => {
         await flush();
         if (result.terminal.kind === "paused") {
-            const parkKind = terminalProjection(result.terminal).status;
+            const parkKind = outwardPlane(result.terminal).status;
             if (isParkLedgerEventType(parkKind)) {
                 await appendParked(parkKind, result);
                 return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.92.1",
+  "version": "7.92.2",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -59,7 +59,7 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "7.25.0",
+    "@sema-agent/core": "7.25.1",
     "@sema-agent/settings-schema": "3.0.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",
@@ -74,7 +74,7 @@
     "sharp": "^0.35.3"
   },
   "devDependencies": {
-    "@sema-agent/sdk": "10.0.0",
+    "@sema-agent/sdk": "11.0.1",
     "@types/libsodium-wrappers": "^0.7.14",
     "@types/node": "22.10.2",
     "@types/pg": "^8.20.0",