@sema-agent/server 2.0.0 → 3.0.0

package/dist/model-select.d.ts

@@ -10,7 +10,7 @@
  * untrusted body/text can pick WHICH configured model but can never inject a baseUrl/apiKey (parseModelMention
  * only ever returns an allow-listed catalog name).
  *
- * [865]②(clay 生产实锤:onboard 选 kimi 实跑 Qwen):
+ * [865]②(生产实锤:面板上选了 A 模型,实际跑的是目录里的另一个):
  *  - explicit ref 走 name+id 双键索引({@link matchCatalogModel})——壳 boot 回读的 mainLoopModel 是 **id 形**,
  *    目录键是 **name 形**,单键索引把 id 形请求当「未知」静默落 default = session 中途静默换模型(最恶性的
  *    上下文污染路径)。

package/dist/model-select.js

@@ -11,7 +11,7 @@ import { parseModelMention } from "@sema-agent/core";
  * untrusted body/text can pick WHICH configured model but can never inject a baseUrl/apiKey (parseModelMention
  * only ever returns an allow-listed catalog name).
  *
- * [865]②(clay 生产实锤:onboard 选 kimi 实跑 Qwen):
+ * [865]②(生产实锤:面板上选了 A 模型,实际跑的是目录里的另一个):
  *  - explicit ref 走 name+id 双键索引({@link matchCatalogModel})——壳 boot 回读的 mainLoopModel 是 **id 形**,
  *    目录键是 **name 形**,单键索引把 id 形请求当「未知」静默落 default = session 中途静默换模型(最恶性的
  *    上下文污染路径)。

package/dist/plugins/checkpoint-store-sql.d.ts

@@ -1,6 +1,6 @@
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import { type Checkpoint, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type ResumeOutcome, type ResolveExpectation, type ReopenReason, type RiskDescriptor } from "@sema-agent/core";
+import { type Checkpoint, type CheckpointGate, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type ResumeOutcome, type ResolveExpectation, type ReopenReason, type RiskDescriptor } from "@sema-agent/core";
 import { type SqlDriver } from "./sql-driver.js";
 /**
  * design/80 D-1 (§3 invariant #3 — crash-safe reaper backstop): an ABSOLUTE upper bound on a pending
@@ -38,10 +38,18 @@ export interface PendingCheckpoint {
      *  resume binds to the EXACT action they saw (a stale view is then rejected fail-closed PRE-CAS). `boundCallId`
      *  === `toolCallId` (the pending tool call); `boundInputHash` is the server-minted opaque hash of the shown
      *  input (NEVER recomputed by the portal — echoed verbatim). Surfacing them here is what makes the D-1 TOCTOU
-     *  guard REACHABLE by the portal (without it the portal can only do the unbound legacy fallback). `null` on a
-     *  pre-D-1 / legacy-deserialized checkpoint ⇒ the consumer falls back to the unbound resolve. */
-    boundCallId: string | null;
-    boundInputHash: string | null;
+     *  guard REACHABLE by the portal (without it the portal can only do the unbound legacy fallback).
+     *  🔴 [1995]②: ABSENT (key omitted, never `null`) on a park with no tool action (plan_review /
+     *  resource_limit / task_done) or a pre-D-1 legacy row ⇒ the consumer falls back to the unbound resolve.
+     *  The wire contract (§1) is "an absent nullable field is OMITTED, not null" — a `null` here invited a
+     *  consumer to treat the key's PRESENCE as "there is a binding" and echo `null` back into /decide. */
+    boundCallId?: string;
+    boundInputHash?: string;
+    /** 🔴 [1995]③ (additive): the checkpoint's gate kind — the operator queue mixes tool approvals with
+     *  plan_review / resource_limit / task_done parks (all of which carry `toolName: null`), so a durable-recovery
+     *  consumer needs this to ROUTE a row to the right wire (`/decide` vs `/plan_review` vs `/resume`). Absent
+     *  only for a legacy SQL row suspended before the `gate_kind` column existed. */
+    gateKind?: CheckpointGate["kind"];
     /** The suspended run's taskId (task_active join) — the key to the run/trace ("view task context"). */
     taskId: string | null;
     /** The pending tool call's args (post-hook), redacted + bounded — for tool_approval the write payload, for a

package/dist/plugins/checkpoint-store-sql.js

@@ -305,13 +305,15 @@ export class SqlCheckpointStore {
      *  joined from task_active (the JOIN KEY to the run/trace — a suspended run KEEPS its
      *  session claim, so the join is live for every pending row; null only in pathological windows). */
     async listPending(scope) {
-        const base = "SELECT c.session_id, c.scope, c.tool_name, c.tool_call_id, c.tool_input, c.bound_input_hash, c.risk_descriptor, c.created_at, c.deadline, ta.task_id " +
+        const base = "SELECT c.session_id, c.scope, c.tool_name, c.tool_call_id, c.tool_input, c.bound_input_hash, c.risk_descriptor, c.created_at, c.deadline, c.gate_kind, ta.task_id " +
             "FROM checkpoint c LEFT JOIN task_active ta ON ta.session_id = c.session_id WHERE c.status='pending'";
         const { rows } = scope
             ? await this.db.query(`${base}${this.q(" AND c.scope=?", " AND c.scope=$1")} ORDER BY c.created_at ASC`, [scope])
             : await this.db.query(`${base} ORDER BY c.created_at ASC`);
         const out = rows.map((r) => {
             const toolCallId = r.tool_call_id ?? null;
+            const boundInputHash = r.bound_input_hash ?? null;
+            const gateKind = r.gate_kind ?? null;
             return {
                 sessionId: String(r.session_id),
                 scope: String(r.scope),
@@ -319,8 +321,13 @@ export class SqlCheckpointStore {
                 toolCallId,
                 // D-1: boundCallId === the pending tool call id; boundInputHash is the server-minted opaque hash. The
                 // portal echoes BOTH on /decide so the resume binds to the exact action shown (TOCTOU guard reachable).
-                boundCallId: toolCallId,
-                boundInputHash: r.bound_input_hash ?? null,
+                // [1995]②: a park with no tool action (plan_review / resource_limit / task_done — both columns NULL)
+                // OMITS the keys entirely; the wire contract says absent, never `null` (LOCAL twin does the same).
+                ...(toolCallId !== null ? { boundCallId: toolCallId } : {}),
+                ...(boundInputHash !== null ? { boundInputHash } : {}),
+                // [1995]③ additive: the gate kind the row is parked on (NULL only on a pre-`gate_kind` legacy row) —
+                // lets a durable-recovery consumer route plan / tool / resource off this ONE queue.
+                ...(gateKind !== null ? { gateKind } : {}),
                 taskId: r.task_id ?? null,
                 // Both drivers return the JSON column already parsed; null for pre-migration rows. PG 库内恒干净
                 // (拒绝式)——直读即审阅面=执行面。

package/dist/plugins/local-checkpoint-store.js

@@ -192,8 +192,14 @@ export class LocalCheckpointStore {
                 scope: cp.scope,
                 toolName: pa?.toolName ?? null,
                 toolCallId,
-                boundCallId: toolCallId,
-                boundInputHash: pa?.boundInputHash ?? null,
+                // [1995]②: the D-1 binding fields are OMITTED when the park has no tool action (plan_review /
+                // resource_limit / task_done) — the wire contract says an absent nullable field is ABSENT, not `null`
+                // (a consumer branching on "key present ⇒ there is a binding" would echo `null` back into /decide).
+                ...(toolCallId !== null ? { boundCallId: toolCallId } : {}),
+                ...(pa?.boundInputHash !== undefined ? { boundInputHash: pa.boundInputHash } : {}),
+                // [1995]③ additive: which gate this row is parked on, so a durable-recovery consumer can route
+                // plan / tool / resource off the SAME queue (toolName is null for every non-tool gate).
+                ...(gate?.kind !== undefined ? { gateKind: gate.kind } : {}),
                 taskId: (await this.opts.getActiveTaskId?.(cp.sessionId)) ?? null,
                 input: boundedToolInput(pa?.args),
                 createdAt: cp.createdAt,

package/dist/plugins/remote-env-host.d.ts

@@ -43,7 +43,8 @@ export interface HostEnvConfig {
      *  reports `supported:false` → INERT (no scheduler tools). Injected at boot only on the single-user host lane. */
     scheduler?: SchedulerCapability;
     /** design/103 background shell: `false` → INERT (multi-tenant host lane gate). Default (undefined) = on for the
-     *  single-user TOC host lane. `HOST_BG_ENABLED=false` is an additional global kill switch(旧名 HOST_BG_DISABLED=true 兼容期内仍认)。 */
+     *  single-user TOC host lane. `HOST_BG_ENABLED=false` is an additional global kill switch(🪦 旧名
+     *  `HOST_BG_DISABLED` 自 server 3.0.0 起是 fail-loud 墓碑:设了即拒启并指路新名,不再被读取)。 */
     backgroundShell?: boolean;
 }
 export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, SchedulerCapability, BackgroundShellCapability {

package/dist/run-local.js

@@ -291,7 +291,8 @@ export async function runLocal(argv, deps = {}) {
     // TOC local LSP (core 1.190): run-local IS the pure-local host lane, so mount core's `NodeLspManager` (local
     // child_process language servers over stdio, CC `services/lsp` parity) on the host lane. Default ON (degrades
     // gracefully to grep/read if a server binary is absent); `LSP_HOST_ENABLED=false` opts out (design/158 B4 split
-    // this lane off `LSP_ENABLED`, which still works as a back-compat opt-out). `requirePrincipal !== true`
+    // this lane off `LSP_ENABLED`; 🪦 server 3.0.0 起 `LSP_ENABLED=false` 是 fail-loud 墓碑,拒启指路新名,
+    // 不再是可用的 opt-out)。`requirePrincipal !== true`
     // keeps it uniform with main.ts (a no-op here — run-local is single-user — but never relies on that). Both runners.
     const lspManager = hostRx && config.lspHostEnabled && config.requirePrincipal !== true ? new NodeLspManager({ log: (event, fields) => logger.info(event, fields) }) : undefined;
     // Long-term memory (design/138 S1): run-local IS the single-user lane, so the file-based memory ENGINE is

package/dist/session-titler.d.ts

@@ -29,6 +29,7 @@ export interface SessionTitlerDeps {
     llm(opts: {
         prompt: string;
         timeoutMs: number;
+        model?: string;
     }): Promise<{
         ok: true;
         text: string;
@@ -47,7 +48,8 @@ export interface SessionTitlerDeps {
 }
 export interface SessionTitler {
     /** Fire-and-forget: maybe generate + persist a title for this session. Never throws, never blocks the caller. */
-    maybeTitle(sessionId: string, objective: string): void;
+    /** `model`([1992]②)= 本 turn 真实驱动的模型——带上则标题 hook 同链路,不再裸落 env 缺省。 */
+    maybeTitle(sessionId: string, objective: string, model?: string): void;
 }
 export declare const TITLE_MAX_CHARS = 80;
 /** Single line, control chars stripped, hard cap; surrounding quotes (a common LLM tic) trimmed. */

package/dist/session-titler.js

@@ -65,7 +65,7 @@ export function createSessionTitler(deps) {
         deps.logger?.warn?.("session_title_failed", { ...meta, note: "同 cause 后续降为 debug 级" });
     };
     return {
-        maybeTitle(sessionId, objective) {
+        maybeTitle(sessionId, objective, model) {
             if (!sessionId || !objective.trim())
                 return;
             if (seen.has(sessionId))
@@ -93,7 +93,7 @@ export function createSessionTitler(deps) {
                     deps.metrics?.inc("session_title_total", { outcome: "already_titled" });
                     return;
                 }
-                const r = await deps.llm({ prompt: buildTitlePrompt(objective), timeoutMs: LLM_TIMEOUT_MS });
+                const r = await deps.llm({ prompt: buildTitlePrompt(objective), timeoutMs: LLM_TIMEOUT_MS, model });
                 if (!r.ok) {
                     deps.metrics?.inc("session_title_total", { outcome: "llm_failed" });
                     logFailure(sessionId, r.error);

package/dist/trace/project.js

@@ -510,7 +510,10 @@ export function mapTraceEvent(type, seq, data) {
         case "failed":
             // BL-13: redact at the read boundary too (defense-in-depth) — covers any errorMessage that reached the
             // log un-redacted via another write path; idempotent on the BL-12-redacted catch-path message.
-            return { event: "error", data: { code: "WORKER_DOWN", message: redactSecrets(String(data.errorMessage ?? "run failed")) } };
+            // A1/A6/B(复审 2026-07-29):error 帧统一为 `{ type:"error", errorCode, message }` —— 与 sse-log /
+            // approvals 的帧同形。这一处是 3.0.0 摘 legacy `code` 键时的漏网:帧在 src/trace/ 铸,而当时的门只扫
+            // src/http/,于是"SSE error 帧机器键统一为 errorCode"的公开声明与 wire 上跑的东西不一致(门是绿的)。
+            return { event: "error", data: { type: "error", errorCode: "WORKER_DOWN", message: redactSecrets(String(data.errorMessage ?? "run failed")) } };
         default:
             return null; // compacted etc. — not a client trace event
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "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",
@@ -23,7 +23,9 @@
     "!dist/run-local-linux-x64",
     "!dist/run-local-darwin-arm64",
     "skills",
-    "deploy/sema-up"
+    "deploy/sema-up",
+    "USAGE.md",
+    "MIGRATION.md"
   ],
   "bin": {
     "run-local": "dist/run-local.js",
@@ -51,7 +53,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": "^2.0.0",
+    "@sema-agent/core": "^2.1.0",
     "@sema-agent/registry-core": "^0.10.21",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",