@sema-agent/server 7.132.0 → 7.134.0

package/dist/orchestration/workflow-completion-inbox.d.ts

@@ -228,26 +228,26 @@ diag?: {
     connection: string;
     log(msg: string, meta?: Record<string, unknown>): void;
 }): Promise<void>;
-/**
- * The durable half is the deployment's job: map a core `TaskNotificationPayload`
- * (background subagent / background bash completion) onto an inbox entry, for the IDLE gap — core's in-process
- * injection covers a LIVE harness; a completion that lands after the leg ended had NO durable path (idle no-show,
- * lost across restart). Bounded + redacted HERE (the store carries only egress-safe bytes; summary/result are
- * UNTRUSTED free text). `status` collapses onto the inbox's completed|failed column; the ORIGINAL status rides
- * the payload extras and overrides on drain (killed/cancelled reach the shell verbatim). Workflow-type
- * notifications are the CALLER's job to filter (they have their own durable chain — double-enqueueing here would
- * re-open the poll-served double-push).
- */
-export declare function taskNotificationInboxEntry(sessionId: string, owner: string | null, n: {
+/** 停驻收件条目的**共享字段** —— 引擎递来的完成与本服务铸的 external 通知都有的那几位。三只入参型都写成类型字面量(不是 interface):
+ *  调用方手里的是一只记录形的 payload,字面量型才与它可比(interface 没有隐式索引签名)。 */
+type ParkedNotificationFields = {
     task_id: string;
-    task_type: string;
-    toolUseId?: string;
     status: string;
     summary: string;
     result?: string;
+    seq?: number;
+    /** 通知的来源标签(external 通知的入站体键,core 载荷同名键;live 投影过 `redactSecrets`,这里同读法)。 */
+    source?: string;
+};
+/**
+ * **引擎递来的一次完成**(`onTaskNotification` 的 payload,执行腿父腿已收尾时入箱)—— 停驻收件的入参型。四处调用(bg 腿 `runs.ts`、sync 腿
+ * `routes/tasks.ts`、两条续跑腿 `resume-legs.ts`)原样交 core 的那只 payload。
+ */
+export type EngineNotificationParkInput = ParkedNotificationFields & {
+    task_type: string;
+    toolUseId?: string;
     output_file?: string;
     sessionId?: string;
-    seq?: number;
     lines?: string[];
     stoppedBy?: string;
     recentSteps?: Array<{
@@ -281,7 +281,33 @@ export declare function taskNotificationInboxEntry(sessionId: string, owner: str
     };
     resupplied?: boolean;
     attempt?: number;
-}, enqueuedAt: number, 
+    /**
+     * 引擎的**一次完成**的相关 id(fill-once,`SemaTaskHandle.completionId`)—— live 投影(`trace/project.ts`)逐字透传的同一个值,
+     * 停驻收件条目照带 ⇒ 同一次完成在 live 帧与下一次开流的补投帧上同一个 id。引擎铸的不透明标识:逐字、不脱敏、不进折叠键;本仓零自铸。
+     */
+    completionId?: string;
+};
+/**
+ * **本服务自己铸的 external 通知**(`POST /v1/sessions/:id/notify` 的 idle 半场)—— 停驻收件的入参型。类型上**不许**带 `completionId`:
+ * 那一位是引擎的一次完成的相关 id,本服务铸的通知没有它(编一个 = 凭空造一次「完成」)。
+ */
+export type ExternalNotificationParkInput = ParkedNotificationFields & {
+    task_type: "external";
+    completionId?: never;
+};
+/** external 通知 → 停驻收件条目(逐键取共享字段:运行期硬塞进来的别的键 —— 包括 `completionId` —— 一个都不过)。 */
+export declare function externalNotificationInboxEntry(sessionId: string, owner: string | null, n: ExternalNotificationParkInput, enqueuedAt: number): WorkflowCompletionInboxEntry;
+/**
+ * The durable half is the deployment's job: map a core `TaskNotificationPayload`
+ * (background subagent / background bash completion) onto an inbox entry, for the IDLE gap — core's in-process
+ * injection covers a LIVE harness; a completion that lands after the leg ended had NO durable path (idle no-show,
+ * lost across restart). Bounded + redacted HERE (the store carries only egress-safe bytes; summary/result are
+ * UNTRUSTED free text). `status` collapses onto the inbox's completed|failed column; the ORIGINAL status rides
+ * the payload extras and overrides on drain (killed/cancelled reach the shell verbatim). Workflow-type
+ * notifications are the CALLER's job to filter (they have their own durable chain — double-enqueueing here would
+ * re-open the poll-served double-push). External notifications enter through {@link externalNotificationInboxEntry}.
+ */
+export declare function taskNotificationInboxEntry(sessionId: string, owner: string | null, n: EngineNotificationParkInput, enqueuedAt: number, 
 /** lead-b (dual-ID audit): the PARENT run's durable taskId (the uuid the shell's footer rows
  *  key on) — rides the drained frame so a consumer can bind the a*-keyed child notification to its uuid-keyed
  *  parent row without a side lookup. */
@@ -341,4 +367,5 @@ export declare function resolveServedSession(p: {
 }, getRun?: (taskId: string) => Promise<{
     sessionId?: string | null;
 } | undefined | null>): Promise<string | undefined>;
+export {};
 //# sourceMappingURL=workflow-completion-inbox.d.ts.map

package/dist/orchestration/workflow-completion-inbox.js

@@ -315,6 +315,17 @@ export async function emitPendingWorkflowCompletions(inbox, sessionId, callerPri
         }
     }
 }
+export function externalNotificationInboxEntry(sessionId, owner, n, enqueuedAt) {
+    return taskNotificationInboxEntry(sessionId, owner, {
+        task_id: n.task_id,
+        task_type: "external",
+        status: n.status,
+        summary: n.summary,
+        ...(n.result !== undefined ? { result: n.result } : {}),
+        ...(n.seq !== undefined ? { seq: n.seq } : {}),
+        ...(n.source !== undefined ? { source: n.source } : {}),
+    }, enqueuedAt);
+}
 export function taskNotificationInboxEntry(sessionId, owner, n, enqueuedAt, parentTaskId, priority) {
     const cap = (s, max) => (s.length > max ? `${s.slice(0, max)}…[+${s.length - max} chars]` : s);
     const extras = {
@@ -328,6 +339,8 @@ export function taskNotificationInboxEntry(sessionId, owner, n, enqueuedAt, pare
         ...(n.toolUseId ? { toolUseId: n.toolUseId } : {}),
         ...(n.status !== "completed" && n.status !== "failed" ? { status: n.status } : {}),
         ...(n.seq !== undefined ? { seq: n.seq } : {}),
+        ...(n.completionId !== undefined ? { completionId: n.completionId } : {}),
+        ...(n.source !== undefined ? { source: redactSecrets(n.source) } : {}),
         ...(n.lines !== undefined ? { lines: n.lines.map((l) => cap(redactSecrets(l), 1024)) } : {}),
         ...(n.stoppedBy !== undefined ? { stoppedBy: n.stoppedBy } : {}),
         ...(n.diagnostics !== undefined ? { diagnostics: cap(n.diagnostics, 4_000) } : {}),

package/dist/orchestration/workflow-notify-journal.d.ts

@@ -291,39 +291,20 @@ export declare class JournalingWorkflowRunStore implements WorkflowRunStore {
      *  的派生投影,写点必须与 fleet 行投影/notify journal 同一个(见 index 模块的文件头「单写者」段)。
      *  可选:缺席 ⇒ 一位不维护(与 fleet 半场同姿势,行为逐字不变)。 */
     agentSessionIndex?: WorkflowAgentSessionIndex | undefined);
-    /** 上一次**本进程**为某条 run 写进索引的行集 —— 变更检测,不是缓存。
+    /** 本进程**亲眼看着落进索引**的指针:run → 它点名过的子会话。只用来跳过重复的 upsert,不是缓存(指针只增不删,记着的必在索引里)。
      *
-     *  为什么需要:workflow 的进度写是每只 agent 状态变化一次,而 park 是罕见事件 ⇒ 无条件同步会给
-     *  「一条 park 都没有」的绝大多数 run 每次写多打一发删除(SQL)或多追加一行账本(file,无界增长)。
-     *  判据是**行集是否变化**,与后端无关 ⇒ 规则只有一条、两个后端同享。
-     *  跨副本安全性:一条 run 的写者按 core 契约唯一(`store` 的 owner),而同步只发生在一次**成功 CAS 之后**;
-     *  失败切换后新 owner 的表是空的 ⇒ 它的第一次写必落盘,收敛。
-     *
-     *  🔴 **空集也记**(7.69.0 合并重扫 c0):此前成功臂写作「空集 delete、非空集 set」,于是「一条 park
-     *  都没有」的那条 run —— 也就是上面这段头注**点名要短路的绝大多数形** —— memo 恒回 `undefined`、短路
-     *  判据恒假,每一次 put/update 都重跑一遍 `syncRun(id, [])`(file 车道每次多一行账本 + 一次 fsync,而
-     *  这本账本按设计没有压缩腿;SQL 车道每次多一发 `DELETE`)。代码与自己成文的判据相反。
-     *  当时那条 delete 臂承担的是**有界性**:memo 若无条件记,表会随本进程见过的每一条 run 单调增长。
-     *  现在有界性由下面那条**终态驱逐**独立承担(run 终态 ⇒ 它不会再被写 ⇒ 摘表),两件事各归各位:
-     *  记不记 = 变更检测的正确性;摘不摘 = 表的有界性。**不**加「首次空集跳过」这类依赖进程内历史的特判。 */
-    private readonly indexedRows;
-    /**
-     * 写腿的**不变式守卫**(codex r1 [medium],验真后修):`indexedRows` 只保留一次**我们亲眼看着落地**
-     * 的写。持久化抛错时这条 run 的盘上状态未知(而 core 会吞掉这次失败、这条 run 往往再也不被写),
-     * 若把 memo 留着,那一条 `{runId → rows}` 就永久留在表里 —— 终态驱逐等不到它的终态写。
-     *
-     * ⚠️ 如实登记的残余:一条**最后一次写成功、随后被放弃**的 run(进程崩前没跑到终态)仍会在本进程的
-     * memo 里留一条空集。它与 fleet 活行登记簿同一量级(都随本世进程消亡),刻意**不**为它加清扫腿:
-     * 那是给一个不产生错误答案的形加机制。
-     */
-    private forgetIndexMemoIfWriteOutcomeUnknown;
-    /** 索引的一次收敛(put/update 成功后调用)。
-     *
-     *  **自吞错**:索引是观察面的派生物,它的故障绝不能把一次已成功的 run 持久化变成失败 —— 与
-     *  `publishFleet` 的姿态同源。但自吞 ≠ 静默([ref]):留痕走**登记过的** fail-open tag
-     *  `server.workflow-park-index.sync-failed`(P-DEBT;射程、后果与欠账的唯一属主 = 那条词表项的
-     *  `note`,census 里有对应行);记录的 `parks[]` 读不出而不同步的那一臂另走 `server.workflow-park-index.parks-unreadable`(F 类,见下)。 */
-    private syncAgentSessionIndex;
+     *  为什么需要:workflow 的进度写是每只 agent 状态变化一次,而 park 是罕见事件 ⇒ 无条件 upsert 会给每一次写多打几发语句(SQL)
+     *  或多追加一行账本(file,无界增长)。判据只有一条:**这次记录点名的子会话,有没有还没亲眼看着落盘的** —— 没有就不写。
+     *  有界性:这条 run 不会再被本进程写的那一刻就摘表 —— 写到终态、CAS 输掉(owner 已不是本副本)、或这次写抛了(盘上状态未知)。 */
+    private readonly pointedSessions;
+    /** **指针先于记录**(索引模块头注的那条律):这次记录点名的子会话,指针在记录落盘之前 upsert。写不进 ⇒ 抛 —— 调用方的记录写
+     *  因此不发生,错误交给引擎 persist 的失败臂(与库写失败同一条路),不吞、不计 fail-open。
+     *  记录的 `parks[]` 读不出(在场却不是列表 / 条目形坏)⇒ 派生不出 ⇒ 不写指针,记录照写(读口据记录响亮拒);留痕走
+     *  `server.workflow-park-index.parks-unreadable`(F 类)。`parks` 缺席不在这一臂:那是没有条目(读者答 `[]`),没有要写的指针。 */
+    private ensurePointersFor;
+    /** 一次记录写的整形:先指针、再记录;记录没落(`landed` 答否 / 写抛)或写到终态 ⇒ 摘表(见 {@link pointedSessions} 的有界性)。
+     *  终态判据走 fleet 半场那张**同一张**终态闭集表,不在这里手写第二份「哪些词算终态」。 */
+    private writeWithPointers;
     /** Derive + publish the MF-Fleet workflow row from a WorkflowRun (doneCount/totalCount from agents, tokens from
      *  stats); a terminal workflow LEAVES the fleet (publish terminal then remove), a running one stays/updates. */
     private publishFleet;

package/dist/orchestration/workflow-notify-journal.js

@@ -2,7 +2,7 @@ import { join } from "node:path";
 import { AppendLog, ensureDir } from "@sema-agent/core";
 import { buildFleetWorkflowRow } from "../fleet/fleet-bus.js";
 import { isTerminalWorkflowRowStatus, seedTerminalWorkflowRow } from "../fleet/fleet-terminal-window.js";
-import { buildParkSessionRows, sameAgentSessionRows } from "./workflow-agent-session-index.js";
+import { buildParkSessionRows } from "./workflow-agent-session-index.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { replayJsonlSkipping } from "../observability/corrupt-read-seat.js";
 const SUMMARY_MAX = 500;
@@ -264,41 +264,39 @@ export class JournalingWorkflowRunStore {
         this.fleetBus = fleetBus;
         this.agentSessionIndex = agentSessionIndex;
     }
-    indexedRows = new Map();
-    async forgetIndexMemoIfWriteOutcomeUnknown(id, write) {
-        try {
-            return await write();
-        }
-        catch (e) {
-            this.indexedRows.delete(id);
-            throw e;
-        }
-    }
-    async syncAgentSessionIndex(id, run) {
+    pointedSessions = new Map();
+    async ensurePointersFor(id, run) {
         const index = this.agentSessionIndex;
         if (index === undefined)
             return;
         const rows = buildParkSessionRows(id, run);
         if (rows === undefined) {
-            this.indexedRows.delete(id);
             recordFailOpen("server.workflow-park-index.parks-unreadable", `runId=${id}`);
             return;
         }
-        const prior = this.indexedRows.get(id);
-        if (prior === undefined || !sameAgentSessionRows(prior, rows)) {
-            try {
-                await index.syncRun(id, rows);
-            }
-            catch (err) {
-                this.indexedRows.delete(id);
-                recordFailOpen("server.workflow-park-index.sync-failed", `runId=${id} rows=${rows.length} err=${err instanceof Error ? err.message : String(err)}`);
-                return;
-            }
+        const known = this.pointedSessions.get(id);
+        const fresh = rows.filter((r) => known?.has(r.sessionId) !== true);
+        if (fresh.length === 0)
+            return;
+        await index.ensurePointers(id, fresh);
+        const landed = known ?? new Set();
+        for (const r of fresh)
+            landed.add(r.sessionId);
+        this.pointedSessions.set(id, landed);
+    }
+    async writeWithPointers(id, run, write, landed) {
+        await this.ensurePointersFor(id, run);
+        let result;
+        try {
+            result = await write();
         }
-        if (isTerminalWorkflowRowStatus(run.status))
-            this.indexedRows.delete(id);
-        else
-            this.indexedRows.set(id, rows);
+        catch (e) {
+            this.pointedSessions.delete(id);
+            throw e;
+        }
+        if (!landed(result) || isTerminalWorkflowRowStatus(run.status))
+            this.pointedSessions.delete(id);
+        return result;
     }
     publishFleet(id, run) {
         if (!this.fleetBus)
@@ -322,16 +320,11 @@ export class JournalingWorkflowRunStore {
             runId: id,
             scope: run.scope,
         });
-        await this.forgetIndexMemoIfWriteOutcomeUnknown(id, () => this.inner.put(id, run));
-        await this.syncAgentSessionIndex(id, run);
+        await this.writeWithPointers(id, run, () => this.inner.put(id, run), () => true);
         this.publishFleet(id, run);
     }
     async update(id, scope, run, expect) {
-        const ok = await this.forgetIndexMemoIfWriteOutcomeUnknown(id, () => this.inner.update(id, scope, run, expect));
-        if (!ok)
-            this.indexedRows.delete(id);
-        if (ok)
-            await this.syncAgentSessionIndex(id, run);
+        const ok = await this.writeWithPointers(id, run, () => this.inner.update(id, scope, run, expect), (won) => won);
         if (ok)
             this.publishFleet(id, run);
         return ok;

package/dist/orchestration/workflow-park-decision.d.ts

@@ -0,0 +1,89 @@
+import { type CheckpointToken, type ResumeOutcome } from "@sema-agent/core";
+import { type JsonColumnReader } from "../plugins/sql-json-column.js";
+import { type InProcessClaimFence } from "../plugins/store-contracts.js";
+/** 一条人对审批卡的决定(引擎 `ResumeOutcome` 的 `policy_ask` 臂 —— 子代停驻只会是这一门)。 */
+export type WorkflowParkOutcome = Extract<ResumeOutcome, {
+    gate: "policy_ask";
+}>;
+/** 决定行(内域形)。 */
+export interface WorkflowParkDecision {
+    /** 子代 checkpoint 的 token —— 键。 */
+    readonly token: CheckpointToken;
+    /** 留存锚:受理那一刻的持有者 run(收割它时同批删本行)。**不是**投递目标 —— 投递目标在读时由路由判官定。 */
+    readonly runId: string;
+    /** 带着它的会话 = 受理那一刻那条 run 的发起会话(宿主)。 */
+    readonly hostSessionId: string;
+    readonly outcome: WorkflowParkOutcome;
+    /** {@link parkDecisionFingerprint}:同一决定的判据(回执幂等用)。 */
+    readonly fingerprint: string;
+    /** 受理它的那一次投递跑(回执上的 `taskId`)。 */
+    readonly deliveredTaskId: string;
+    /** 受理时刻(受理那台副本的墙钟,记录值;不当任何条件 —— 序由认领栅栏的提交序定,见文件头律二)。 */
+    readonly acceptedAtMs: number;
+}
+/**
+ * 决定行的店契约(SQL 两方言 / local 文件 / 内存三形同律)。写者只有 `/decide` 的 workflow 车道(开跑之前那一笔);读者是起跑读者与
+ * `/decide` 自己的回执幂等判;删除只有 SQL 收割的级联。
+ */
+export interface WorkflowParkDecisionStore {
+    /** 这只店每一笔写所在的认领栅栏 = 构造时绑定的那只 run 店。起服判官要它**就是**部署的 run 店({@link parkDecisionStoreRefusal})。 */
+    readonly claims: object;
+    /**
+     * 认领栅栏的原子段里整行写(律二,文件头):投递那一跑此刻持有宿主会话的认领且在跑 ⇒ 写(没有行插入、有行整行取代)并答 `true`;
+     * 否则什么都不写、答 `false`。
+     */
+    record(decision: WorkflowParkDecision): Promise<boolean>;
+    get(token: CheckpointToken): Promise<WorkflowParkDecision | null>;
+    /** 带着这个会话的全部决定行(顺序不承重)。 */
+    listByHostSession(hostSessionId: string): Promise<WorkflowParkDecision[]>;
+}
+/** 起服判官读的那几座(`ServiceDeps` 的子集)。 */
+export interface ParkDecisionLaneSeats {
+    readonly runStore?: object | undefined;
+    readonly workflowAgentSessionIndex?: unknown;
+    readonly workflowParkDecisions?: WorkflowParkDecisionStore | undefined;
+}
+/**
+ * 🔴 **「决定店绑对了 run 店吗」的唯一判官**(`createHttpServer` 起服时调;拒 ⇒ 拒启)。判的是**递进来的对象**(按身份比),不是配置组合 ——
+ * 本服务自己那一形(SQL 后端配 `WORKFLOW_RUN_STORE=file|memory` 且开自编排)由配置不变量 `workflow-park-decision-domain` 在第 1 段、一次性迁移之前拒,走不到这里;
+ * 走到这里的不相等只来自嵌入方递错了座。
+ * 期望的绑定:workflow 子代停驻车道装了(park 索引在场)且部署有 run 店 ⇒ 决定店在场、绑的**就是**那只 run 店;否则不该有决定店。不相等的三形各一句:
+ * ①车道与 run 店都在而决定店缺席;②决定店绑的是别的 run 店(两只店各取各的:决定写进一只库、认领与读在另一只);③有决定店,而车道没装或部署没有 run 店。
+ */
+export declare function parkDecisionStoreRefusal(seats: ParkDecisionLaneSeats): string | undefined;
+/**
+ * 决定的同一性判据:判词 + 绑定两位 + 出处词(`decidedBy`)+ 载荷指纹(`updatedInput` / `answer` / `reason` / `feedback`,与 live 腿幂等回放的门⑦
+ * 同一只 {@link approvalPayloadFingerprint})。通道自报的 `approver` 不进 —— 它是归属标签,不改引擎铸的结算词。
+ * 载荷序列化不了 ⇒ 抛(两侧都源自 JSON,走到这里是结构异常;那只函数自己已经响亮 warn)。
+ */
+export declare function parkDecisionFingerprint(outcome: WorkflowParkOutcome): string;
+/**
+ * 存下的决定体 → 内域形的**唯一读者**(SQL 列与 local 账本行共用)。判到本仓自己读的那几格为止(门、判词、绑定两位、出处对象);
+ * 其余键的属主是引擎,它在续跑入口 pre-CAS 再判一遍(与 checkpoint 店读 `outcome` 列同一条分工,见 `checkpoint-store-sql.ts` 的形读者注)。
+ */
+export declare const readWorkflowParkOutcome: JsonColumnReader<WorkflowParkOutcome>;
+/**
+ * 单机车道的决定店(`LocalWorkflowAgentSessionIndex` 的同室孪生),绑在进程内的 run 店上({@link InProcessClaimFence}:Memory / File run 店)。
+ * `root` 在场 ⇒ 追加式 JSONL 账本(0o700 目录 + 0o600 账本,一行 = 一条决定行的整份快照,每一笔写都追加);重放按行序、**末行胜**
+ * (写序就是认领栅栏的序:每一笔都在栅栏的同步段里追加,同一宿主会话上的受理由认领串行);缺席 ⇒ 纯内存(`WORKFLOW_RUN_STORE=memory` 的易失车道)。
+ *
+ * 🔴 **坏行 fail-closed**(登记座 `workflow-park-decisions`):读不出的一行可能正是**取代**了一条旧决定的那一笔 —— 跳过它重放其余行,
+ * 会把被取代的旧决定复活成当下的决定,在下一次起跑时交给引擎。闸合上之后三个动词都响亮拒,直到有人处理那只文件;
+ * 起跑读者(`parked-decide.ts`)把这一拒读成「本店没有可供的行」(F tag `server.workflow-park-decision.store-unreadable`)—— 起跑不连带拒,写与按 token 读照旧拒。
+ * SQL 孪生同律:某一行 `outcome` 坏体 ⇒ 读口拒,起跑读者同一臂。
+ */
+export declare class LocalWorkflowParkDecisionStore implements WorkflowParkDecisionStore {
+    readonly claims: InProcessClaimFence;
+    private readonly fsyncEnabled;
+    private readonly ledgerPath;
+    private readonly gate;
+    private readonly rows;
+    private log;
+    constructor(claims: InProcessClaimFence, root?: string, fsyncEnabled?: boolean);
+    record(decision: WorkflowParkDecision): Promise<boolean>;
+    /** 整行写(同步):落盘**先于**内存翻转(调用方观察到的状态背后一定有耐久记录)。交回栅栏的落定记号(同步交回,型上不许让出)。 */
+    private landNow;
+    get(token: CheckpointToken): Promise<WorkflowParkDecision | null>;
+    listByHostSession(hostSessionId: string): Promise<WorkflowParkDecision[]>;
+}
+//# sourceMappingURL=workflow-park-decision.d.ts.map

package/dist/orchestration/workflow-park-decision.js

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { AppendLog, ensureDir } from "@sema-agent/core";
+import { approvalPayloadFingerprint } from "../plugins/approval-payload-fingerprint.js";
+import { createObjectColumnReader, isJsonObject } from "../plugins/sql-json-column.js";
+import { replayJsonlGuarded } from "../observability/corrupt-read-seat.js";
+import { FENCE_LANDED } from "../plugins/store-contracts.js";
+function seatName(v) {
+    if (v === undefined)
+        return "none";
+    const ctor = Reflect.get(v, "constructor");
+    return typeof ctor === "function" && ctor.name !== "" ? ctor.name : "an object";
+}
+export function parkDecisionStoreRefusal(seats) {
+    const wanted = seats.workflowAgentSessionIndex !== undefined ? seats.runStore : undefined;
+    const decisions = seats.workflowParkDecisions;
+    if (decisions?.claims === wanted)
+        return undefined;
+    const pair = `run store: ${seatName(seats.runStore)}; workflow park decision store: ${decisions === undefined ? "none" : `${seatName(decisions)} bound to ${seatName(decisions.claims)}`}`;
+    if (decisions === undefined) {
+        return (`the workflow park lane is wired (park index and run store) but no workflow park decision store is bound to that run store (${pair}) — ` +
+            "a decision row is written in the same atomic step that checks the delivering run still holds the host session, so it must live where the session claims live; " +
+            "pass the store backend's workflowParkDecisions() next to its run(); refusing to start rather than answer every workflow approval decision with a 500");
+    }
+    if (wanted === undefined) {
+        return (`a workflow park decision store is wired but the workflow park lane is not (${pair}; park index: ${seats.workflowAgentSessionIndex === undefined ? "none" : "present"}) — ` +
+            "a decision store is only read and written by that lane, which needs both the park index and the run store the decisions are fenced by; " +
+            "wire the lane (park index and run store) or drop the decision store; refusing to start rather than keep a store no lane fences");
+    }
+    return (`the workflow park decision store is not bound to this server's run store (${pair}) — ` +
+        "its writes are fenced by the run store it was built on, so a different run store means decisions recorded where the session claims are not checked; " +
+        "take runStore and workflowParkDecisions from the same store backend (run() and workflowParkDecisions()); refusing to start rather than record decisions the session claim cannot fence");
+}
+export function parkDecisionFingerprint(outcome) {
+    const payload = approvalPayloadFingerprint({
+        ...(outcome.updatedInput !== undefined ? { updatedInput: outcome.updatedInput } : {}),
+        ...(outcome.answer !== undefined ? { answer: outcome.answer } : {}),
+        ...(outcome.reason !== undefined ? { reason: outcome.reason } : {}),
+        ...(outcome.feedback !== undefined ? { feedback: outcome.feedback } : {}),
+    });
+    if (payload === null)
+        throw new Error("workflow park decision: the decision payload cannot be serialized — refusing to record a decision whose identity cannot be stated");
+    const identity = JSON.stringify([outcome.decision, outcome.boundCallId, outcome.boundInputHash, outcome.hostDecision.decidedBy, payload]);
+    return createHash("sha256").update(identity).digest("hex");
+}
+const readOutcomeObject = createObjectColumnReader();
+export const readWorkflowParkOutcome = (body) => {
+    if (!isJsonObject(body))
+        return { problem: "expected a JSON object" };
+    if (body.gate !== "policy_ask")
+        return { problem: "expected a policy_ask decision" };
+    if (body.decision !== "allow" && body.decision !== "deny")
+        return { problem: "decision is neither allow nor deny" };
+    if (typeof body.boundCallId !== "string" || typeof body.boundInputHash !== "string")
+        return { problem: "the binding pair is not two strings" };
+    if (!isJsonObject(body.hostDecision))
+        return { problem: "hostDecision is not an object" };
+    return readOutcomeObject(body);
+};
+const nonEmpty = (v) => typeof v === "string" && v !== "";
+function readRow(raw) {
+    if (!isJsonObject(raw))
+        return undefined;
+    const { token, runId, hostSessionId, outcome, fingerprint, deliveredTaskId, acceptedAtMs } = raw;
+    if (!nonEmpty(token) || !nonEmpty(runId) || !nonEmpty(hostSessionId) || !nonEmpty(fingerprint) || !nonEmpty(deliveredTaskId))
+        return undefined;
+    if (typeof acceptedAtMs !== "number" || !Number.isSafeInteger(acceptedAtMs))
+        return undefined;
+    const o = readWorkflowParkOutcome(outcome);
+    if (o.problem !== undefined)
+        return undefined;
+    return { token: token, runId, hostSessionId, outcome: o.value, fingerprint, deliveredTaskId, acceptedAtMs };
+}
+const LEDGER_LINE_SHAPE = { what: "a workflow park decision row", read: readRow };
+export class LocalWorkflowParkDecisionStore {
+    claims;
+    fsyncEnabled;
+    ledgerPath;
+    gate;
+    rows = new Map();
+    log;
+    constructor(claims, root, fsyncEnabled = true) {
+        this.claims = claims;
+        this.fsyncEnabled = fsyncEnabled;
+        if (root === undefined) {
+            this.ledgerPath = undefined;
+            this.gate = undefined;
+            return;
+        }
+        const dir = join(root, "workflow-park-decisions");
+        ensureDir(dir);
+        this.ledgerPath = join(dir, "decisions.jsonl");
+        const { records, gate } = replayJsonlGuarded(this.ledgerPath, "workflow-park-decisions", LEDGER_LINE_SHAPE);
+        this.gate = gate;
+        for (const d of records)
+            this.rows.set(d.token, d);
+    }
+    async record(decision) {
+        this.gate?.assertUsable();
+        return this.claims.whileHoldingClaim(decision.hostSessionId, decision.deliveredTaskId, () => this.landNow(decision));
+    }
+    landNow(decision) {
+        if (this.ledgerPath !== undefined) {
+            this.log ??= new AppendLog(this.ledgerPath);
+            this.log.append(decision, this.fsyncEnabled);
+        }
+        this.rows.set(decision.token, decision);
+        return FENCE_LANDED;
+    }
+    async get(token) {
+        this.gate?.assertUsable();
+        return this.rows.get(token) ?? null;
+    }
+    async listByHostSession(hostSessionId) {
+        this.gate?.assertUsable();
+        return [...this.rows.values()].filter((d) => d.hostSessionId === hostSessionId);
+    }
+}
+//# sourceMappingURL=workflow-park-decision.js.map

package/dist/org-delivery-gate.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 跨主体投递门 —— core `OrgDeliveryGate` 契约的 server 实现([ref] §10.2;core 7.53.0 的 core 半场)。
+ *
+ * ## 规则(一条)
+ * **一封跨主体的信只因这只门把它追加进收件人的 `principal.inbox` 而存在。** 门是唯一的跨 scope 追加持有者:成员判 →
+ * 铸信 → 收件箱上界 → 配额 → 追加,全在 {@link createOrgDeliveryGate} 交出的 `deliverCrossPrincipal` 里一体完成;
+ * 它只有两种答案 —— 一张回执,或 core 闭集 `ORG_DELIVERY_REFUSAL_CODES` 里的一个词。本仓不铸第二只拒绝词。
+ *
+ * 规则因此少了几条(而不是多了几条):
+ *  · **成员判不另立名册**:「谁属于 org:acme」在一个进程里只有一个答案 —— 记忆准入 seam、memory-policy 面、共享记忆读面
+ *    读的那**同一个**目录实例(`boot/org-memory.ts` 装配的 `OrgMemoryDirectory`)。两位主体同属一个 org ⟺ 两人
+ *    `lookup` 的 `org:` 键集合有交集。目录答不上来(`unavailable`)= 「部署说不出他们同 org」⇒ `not_member`
+ *    (core 对这只词的定义逐字含这一臂)。
+ *  · **记录只有一个铸点**:core 的纯函数 `mintCrossPrincipalRecord`(只写 `peerMeta.kind / fromScope / gateReceiptId`
+ *    + 可选 `urgent` 与显示名;不写 `fromSession / fromMode / hopChain`)。本仓不另铸任何记录形。
+ *  · **限流是配额店的两个原子动作,各管一件事**:`admitAttempt` 记发件人的每一次尝试(碰目录之前;界住刷目录的速率),
+ *    `take` 在同一把锁下判并记 (from→to) 对偶界与收件人聚合界(投递额度)。SQL 两方言各是一个事务,见
+ *    `plugins/org-delivery-quota-store.ts` 头注;File / Memory = 单进程。
+ *  · **收件人的 scope 就是收件人主体串本身**:本服务的引擎 scope = `spec.principal`(`resolve-spec.ts` 落
+ *    `auth.principal`;同一事实的推导见 `peer-directory.ts` 的「scope 轴」段)。门不另造编解码。
+ *
+ * ## 次序与理由
+ *  0. **发件人的尝试界**(配额店 `admitAttempt`,成没成都记一笔):满 ⇒ `rate_limited`。它必须在成员判之前 —— 成员判把调用方给的
+ *     收件人串交给组织目录去查,而目录的每主体状态按属主裁定不淘汰、它的量级只在「查的都是验过的主体」时有界(`org-memory-admission.ts`
+ *     的 `PrincipalState` 注);这一界让「一个成员拿任意串去刷目录」的速率与总量随时间线性有界(设计稿收件人查询面第四条:查询限流)。
+ *     与收件人无关 ⇒ 它的 `rate_limited` 不泄露收件人存不存在。
+ *  1. **成员判**(纯读):不同 org / 查无此人 / 目录不可用 / 收件人串过不了主体形判 / 收件人当不了收件箱的身份键(良构 Unicode ∧ 无控制字符 ∧
+ *     UTF-8 字节不超过键列宽 —— 两方言收件箱写面与读面同读的唯一判官 `mailbox-store-sql.ts` 的 `mailboxKeyProblem`)⇒ 同一句 `not_member`,逐字节同 ——
+ *     门永远不是一只存在性探针(core 契约原句),也不说「是长度」。收件人那一判必须在配额之前:第 5 步的追加按同一只判官拒,拒在扣了投递额度之后就是「吃了额度没投到」。
+ *  2. **铸信**(纯函数):放在任何有副作用的步骤之前。发件人的 scope 拼不进信封的发件人位(引擎按百分号编码后 1..190 字节判,抛闭集码
+ *     `cross_session.invalid_from_scope`,`CrossSessionCodecError` 由引擎包根导出)⇒ 同一句 `not_member`、一个配额名额都没吃 —— 发件人这一侧的判官只有引擎这一只,
+ *     本仓不另抄宽度公式。部署没声明收件箱消费方(`no_consumer`)或别的铸信失败 ⇒ 门抛(core:「the gate maps that to its own failure」),HTTP 面答 500,同样没吃额度。
+ *  3. **收件箱上界**(`peekCount` 读):满 ⇒ `inbox_full`,在吃配额之前判,满箱不烧发件人的额度。与引擎同主体车道的
+ *     `maxQueuedPeerMessages` 同一形(入口处读一次占用);两封并发信最多越界并发数那么多,上界由配额再界一次。
+ *  4. **配额**(原子判并记):任一界满 ⇒ `rate_limited`,与第 0 步同一句(不让发件人从拒句里分辨出「收件人这一小时收了多少」)。
+ *  5. **追加**:`append(收件人 scope, PRINCIPAL_INBOX_HANDLE, 记录)`。店的预删除态拒码(`mailbox.recipient_tombstoned`)
+ *     原样转成 `recipient_tombstoned`(core 对这只词的定义:「the store's own pre-delete code, relayed」);其余错误抛。
+ * 被拒的投递在任何地方都不追加任何东西(core 契约原句);投递额度(第 4 步)在之后只有追加失败这一种「吃了额度没投到」—— 方向是收紧;
+ * 尝试界(第 0 步)按定义每次都记。
+ *
+ * ## 不是本门的威胁面(如实,[ref] §10.2-1 原句)
+ * 库内直接持有 `MailboxStore` 的宿主恒能写任何 scope —— 那是同一信任域内的事。本门保证的是**本服务的 wire 面**上没有第二条
+ * 跨 scope 写径:受理口(`POST /v1/principal-inbox/messages`)只调门,本仓源码里拼得出 `principal.inbox` 这只箱址的只有本文件
+ * (`test/org-delivery-gate-single-path.test.ts` 按源码钉)。
+ */
+import { type MailboxStore, type OrgDeliveryGate, type OrgDeliveryRefusalCode, type PrincipalInboxConsumer } from "@sema-agent/core";
+import type { OrgMemoryDirectory } from "./org-memory-admission.js";
+import type { OrgDeliveryQuotaPolicy, OrgDeliveryQuotaStore } from "./plugins/org-delivery-quota-store.js";
+/**
+ * 跨主体配额(**唯一**的数字源;店只按它数)。默认显著紧于同主体车道(引擎 `PEER_LANE_DEFAULTS`:每发件人突发 30、
+ * 每秒回填 0.5):同一对主体每小时 10 封,一位收件人每小时合计 30 封 —— org 里一个吵闹的主体淹不了别人的箱;
+ * 一个发件人每小时 60 次尝试(成没成都算)—— 拿收件人串去问组织目录的速率有界(头注「次序」第 0 步)。
+ */
+export declare const ORG_DELIVERY_QUOTA: OrgDeliveryQuotaPolicy;
+/** 收件箱上界(在箱、未被消费方确认的信封数)。与引擎同主体车道的箱上界缺省(`maxQueuedPeerMessages`)同值。 */
+export declare const PRINCIPAL_INBOX_BOUND = 50;
+/**
+ * 四只拒绝词各自的那**一句**(wire 上的 `error` 就是它,`routes/principal-inbox.ts` 原样中继、不手抄)。
+ * 键集 = core 闭集:core 加词 ⇒ 这张表编译红。
+ * `not_member` 一句同时服务「不同 org / 查无此人 / 目录答不上来 / 收件人串不成形 / 收件人当不了收件箱的键 / 发件人主体拼不进信封的发件人位」—— 改它要保持各臂同字节。
+ */
+export declare const ORG_DELIVERY_REFUSAL_MESSAGES: Readonly<Record<OrgDeliveryRefusalCode, string>>;
+export interface OrgDeliveryGateDeps {
+    /** org 成员目录 —— **必须**与记忆准入 seam / memory-policy / 共享记忆读面同一个实例(头注)。 */
+    readonly directory: OrgMemoryDirectory;
+    /** 收件人箱所在的店(与引擎 `RunnerDeps.mailboxStore` 同一只)。 */
+    readonly mailbox: Pick<MailboxStore, "append" | "peekCount">;
+    /** 配额店(`StoreBackend.orgDeliveryQuota()`)。 */
+    readonly quota: OrgDeliveryQuotaStore;
+    /** 部署声明的收件箱消费方 —— `principalInboxConsumerOf` 读**同一份** `RunnerDeps` 的结果(core 契约:铸信要它)。 */
+    readonly consumer: PrincipalInboxConsumer;
+    /** 信的 `sentAt` 钟(缺省本进程墙钟)。配额窗不读它 —— 窗由配额店自己的钟定。 */
+    readonly nowMs?: () => number;
+    /** 回执 id 铸点(缺省 uuidv7)。 */
+    readonly mintReceiptId?: () => string;
+}
+/**
+ * 活对象(闭包持有目录 / 两只店 / 消费方)⇒ `create*`(CLAUDE.md 工厂命名律)。
+ */
+export declare function createOrgDeliveryGate(deps: OrgDeliveryGateDeps): OrgDeliveryGate;
+//# sourceMappingURL=org-delivery-gate.d.ts.map

package/dist/org-delivery-gate.js

@@ -0,0 +1,59 @@
+import { CrossSessionCodecError, MAILBOX_TOMBSTONED_RECIPIENT_CODE, PRINCIPAL_INBOX_HANDLE, mintCrossPrincipalRecord, uuidv7, } from "@sema-agent/core";
+import { principalShapeProblem } from "./security.js";
+import { mailboxKeyProblem } from "./plugins/mailbox-store-sql.js";
+export const ORG_DELIVERY_QUOTA = Object.freeze({ windowMs: 3_600_000, attemptsPerSender: 60, perPair: 10, perRecipient: 30 });
+export const PRINCIPAL_INBOX_BOUND = 50;
+export const ORG_DELIVERY_REFUSAL_MESSAGES = Object.freeze({
+    "org_delivery.not_member": "the recipient cannot be reached through the organization delivery gate",
+    "org_delivery.rate_limited": "the cross-principal delivery quota is spent for now — try again later",
+    "org_delivery.inbox_full": "the recipient's principal inbox is full — try again after the recipient has read some of it",
+    "org_delivery.recipient_tombstoned": "the recipient is being deleted — nothing was delivered",
+});
+const refuse = (code) => ({ ok: false, code, message: ORG_DELIVERY_REFUSAL_MESSAGES[code] });
+async function shareAnOrg(directory, a, b) {
+    const [la, lb] = await Promise.all([directory.lookup(a), directory.lookup(b)]);
+    if (la.kind !== "granted" || lb.kind !== "granted")
+        return false;
+    return Object.keys(la.scopes).some((org) => Object.hasOwn(lb.scopes, org));
+}
+const principalShaped = (s) => s !== "" && principalShapeProblem(s) === undefined;
+const fitsInboxKey = (recipient) => mailboxKeyProblem("scope", recipient) === undefined;
+export function createOrgDeliveryGate(deps) {
+    const nowMs = deps.nowMs ?? Date.now;
+    const mintReceiptId = deps.mintReceiptId ?? uuidv7;
+    return {
+        async deliverCrossPrincipal(authedFrom, toPrincipal, body) {
+            if (!(await deps.quota.admitAttempt(authedFrom.scope, ORG_DELIVERY_QUOTA)))
+                return refuse("org_delivery.rate_limited");
+            if (!principalShaped(toPrincipal) || !fitsInboxKey(toPrincipal) || !(await shareAnOrg(deps.directory, authedFrom.scope, toPrincipal))) {
+                return refuse("org_delivery.not_member");
+            }
+            const toScope = toPrincipal;
+            const receiptId = mintReceiptId();
+            let record;
+            try {
+                record = mintCrossPrincipalRecord({ from: authedFrom, body, receiptId, sentAt: nowMs(), consumer: deps.consumer });
+            }
+            catch (err) {
+                if (err instanceof CrossSessionCodecError && err.code === "cross_session.invalid_from_scope")
+                    return refuse("org_delivery.not_member");
+                throw err;
+            }
+            if ((await deps.mailbox.peekCount(toScope, PRINCIPAL_INBOX_HANDLE)) >= PRINCIPAL_INBOX_BOUND)
+                return refuse("org_delivery.inbox_full");
+            if (!(await deps.quota.take(authedFrom.scope, toScope, ORG_DELIVERY_QUOTA)))
+                return refuse("org_delivery.rate_limited");
+            let seq;
+            try {
+                seq = await deps.mailbox.append(toScope, PRINCIPAL_INBOX_HANDLE, record);
+            }
+            catch (err) {
+                if (err?.code === MAILBOX_TOMBSTONED_RECIPIENT_CODE)
+                    return refuse("org_delivery.recipient_tombstoned");
+                throw err;
+            }
+            return { ok: true, receipt: { receiptId, seq } };
+        },
+    };
+}
+//# sourceMappingURL=org-delivery-gate.js.map

package/dist/panel-tool-names.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 读面上「一台服务器 / 一个对端挂了哪些工具」的**名单截表律** —— 全仓唯一属主。
+ *
+ * 为什么必须是一处:名单的条数是远端可控且无界的(A2A 卡里的技能条数、MCP 服务器列出的工具条数,core 只限单个名字的
+ * 长度,不限条数),而这些读面都是**只读 GET / 可被反复触发的探测**,多身份可放大。所以读面发的是
+ * **有界表 + 真计数 + 显式旗**,而不是静默截断:一个会撒谎的读面比一个大的读面更贵。
+ * 同一个事实(「名单被截了」)在每一张读面上必须是同一个数、同一个旗键、同一个说法 —— 两处各写一遍,
+ * 下一个人只会改到其中一处。
+ *
+ * ## 契约(所有用到它的读面逐字成立)
+ *  · 名单最多 {@link PANEL_MAX_TOOL_NAMES} 条,**读数序**取前缀;
+ *  · 超出时另发 `toolNamesTruncated: true`;**恰好**在上限上不算截断,旗键缺席(不编 `false`);
+ *  · **真数不在这里**:`toolCount` 是各读面自己的铸点(A2A 面板 = 名单长度;MCP 状态面 = §G.7 的那一只投影),本函数一个字都不碰它 ——
+ *    消费端读数用 `toolCount`,别用 `toolNames.length`。
+ */
+/** 每一台服务器 / 每一个对端最多回多少条工具名。 */
+export declare const PANEL_MAX_TOOL_NAMES = 200;
+/** 一份工具名单的有界出口形(纯数据,`build*`)。入参不被改写。 */
+export declare function buildBoundedToolNames(names: readonly string[]): {
+    toolNames: string[];
+    toolNamesTruncated?: true;
+};
+//# sourceMappingURL=panel-tool-names.d.ts.map