@sema-agent/server 7.31.0 → 7.32.0

package/dist/boot/lexical-path-env.d.ts

@@ -0,0 +1,10 @@
+import { FileError, StubExecutionEnv, type Result } from "@sema-agent/core";
+/**
+ * 无文件系统的路径裁决 env(见文件头)。只覆写 `absolutePath` 一面,其余全部继承 `StubExecutionEnv`
+ * 的 `not_supported` ——**继承而非逐一手写**是刻意的:core 日后给 `ExecutionEnv` 加必填面时,新面会
+ * 随 `StubExecutionEnv` 一起到位并保持同一个诚实答案,不会在这里留下一个悄悄编出来的假答案。
+ */
+export declare class LexicalPathExecutionEnv extends StubExecutionEnv {
+    absolutePath(path: string): Promise<Result<string, FileError>>;
+}
+//# sourceMappingURL=lexical-path-env.d.ts.map

package/dist/boot/lexical-path-env.js

@@ -0,0 +1,88 @@
+/**
+ * #156 —— 非 host lane(e2b/k8s/ssh/adb/local-docker)写门的**纯路径规则**过渡形所用的裁决 env。
+ *
+ * ## 它解决的缺口
+ *
+ * core 的 `createFsWriteGatePolicy` / `createSensitivePathPolicy` 都把写目标交给
+ * `canonicalizeTarget(env, …)` 去「问 fs 要真身」。host lane 上那个 env 就是 hand 工具真正写的那块盘,
+ * 答案可信。沙箱 lane 不是:per-task 的沙箱 env 由 core 的 `executionEnvFactory` 在 spec **之后**才铸,
+ * spec 期手边只有 worker 本机的 fs——拿它去裁沙箱里的路径会答错(exists/symlink 全是别人机器上的事实),
+ * 而**错误的 allow 比没有门更糟**。所以 [816]/[820] 当年在沙箱 lane 诚实不挂门(wiring=undefined ⇒
+ * 三个模式臂全回落 base 规则,写门整条缺席)。#153 的 ③ 号注把这笔记成了余款,#156 是它的过渡还款。
+ *
+ * ## 这个 env 是什么
+ *
+ * 一个**没有文件系统**的 env:除 `absolutePath` 外的每一个 fs 面(exists / canonicalPath / fileInfo /
+ * read* / write* / listDir / createDir / …)与 shell 面都继承 core 的 `StubExecutionEnv`,
+ * 恒返回 `not_supported` 错误(`readLink` 是可选面,Stub 干脆没有——core 把缺席当「symlink 不可解」,
+ * 且该分支在本 env 恒不可达:exists 先错就进了 canonicalizeNewPath)——这不是伪装,这就是本 env 的诚实回答:**spec 期我们确实不知道沙箱里
+ * 那块盘上有什么**。`absolutePath` 是唯一被赋予真实语义的一面,而它本来就是纯路径运算(不碰盘):
+ * POSIX 绝对路径做词法归一后原样奉还,其余一律「不知道」。
+ *
+ * ## 由此得到的裁决语义(core dist 亲读推出,`tools/fs/safety.js` canonicalizeTarget)
+ *
+ *  · 绝对路径(`/…`):`absolutePath` ok ⇒ core 进 exists 探测 ⇒ 我们返回错误 ⇒ core 按「该路径尚不存在」
+ *    走 `canonicalizeNewPath`,那里逐级 exists 也全错 ⇒ 原样返回我们给的词法绝对路径。于是 canonical key
+ *    = **词法归一后的路径**,`canonicalPath` / `fileInfo` / `readLink` 三面在这条路上根本不可达。
+ *  · 相对路径 / `~/…` / Windows 盘符形:`absolutePath` 返回错误 ⇒ `canon.ok=false` ⇒ 写门直接
+ *    `ask`(fail-closed)。沙箱的 cwd 在 spec 期不可知,这正是我们要的偏置——**不猜沙箱工作目录**。
+ *  · 反斜杠 UNC 形(`\\host\share\…`)是唯一**不经过**本 env 的形:core 的 `canonicalizeTarget` 在入口
+ *    就把它短路成 `ok:true, key=原样`(复审 2026-08-05 dist 亲读+实测)。结果不变——写门无放行域可越,
+ *    落 defaultWrite 的 `ask`;sensitive 段匹配按 `[\\/]` 双分隔符切段,`\\host\share\.env` 照样 deny。
+ *  · sensitivePatterns 的 deny 腿照常施加:它按 canonical key 的**路径段**做 glob 匹配,词法 key 足够,
+ *    且在 `combinePolicies` 折叠里 deny 恒胜(session 豁免 / accept 域越不过)。
+ *  · `isExempt`(会话「本会话不再询问」探针)是 name-keyed 的,不做 fs 裁决,任何 lane 都安全,照接。
+ *
+ * ## 已知残余面(过渡形的边界,不是疏漏)
+ *
+ *  · **symlink 形**:词法裁决看不见符号链接。沙箱里一个名字普通的软链可以指向守卫段(`.ssh` 等),
+ *    我们只会给 `ask` 而不是 `deny`;host lane 上 core 会 canonicalize 出真身并 deny。相应地,core 的
+ *    `unresolvedSymlink ⇒ deny` 那条腿在本 env 下永不触发。注意豁免会话下的口径(codex 复审 E):
+ *    name-keyed 豁免不看路径,这类词法无害的软链目标在豁免会话里是 **allow** 而非 ask——这是本残余面
+ *    在「操作员已授 don't-ask-again」情形下的完整代价,host lane 同情形仍会 deny。
+ *  · **exempt/accept 域**:沙箱 lane 既无可信 cwd 也无 scratchpad 对应物,故本过渡形**一个自动放行域都
+ *    不铸**(见 resolve-spec 的 wiring)。代价是 acceptEdits 在沙箱 lane 退化成与 default 同形(全 ask);
+ *    这是 fail-safe 方向,与 host lane「accept 域解析不出 ⇒ 该域不生效」的哨兵先例同口径。
+ *  · **`cwd` 字段**:继承 `StubExecutionEnv` 的 `"/"` 占位。本 env 只活在 policy 折叠里,core 的两个
+ *    policy 都不读 `env.cwd`(相对路径基准走 `rootPath` 形参,而我们不给)——它不代表沙箱的工作目录。
+ *
+ * ## 终局 seam
+ *
+ * 正解是让写门在**工具执行时刻**拿到真沙箱 env:core [2751] 已排期给 `HookToolContext` 加一个只读的
+ * env 能力窄面(174/#22 窗)。那一面到货后,本过渡形整体退役换正解——届时沙箱 lane 与 host lane 走同
+ * 一条真 fs 裁决,上面三条残余面一并消失。
+ */
+import { posix } from "node:path";
+import { FileError, StubExecutionEnv, err, ok } from "@sema-agent/core";
+/** 词法归一:纯字符串运算,折 `.` / `..` / 重复分隔符,不碰 fs。
+ *  `posix.normalize` 把 `..` 在根部截断(`/../x` → `/x`),与「沙箱根之上没有东西」的语义一致。
+ *  尾部分隔符统一剥掉(根 `/` 除外),让同一目标只有一个 key ——前缀判域靠的就是 key 的唯一性。
+ *  (core 内部有同形的 `normalizeAbsPathLexically`,但未从包根导出;此处是 Node 标准库的等价运算,
+ *   不是它的抄本——若日后 core 导出,这里应改为直接复用。) */
+function normalizeAbsolutePathLexically(path) {
+    const collapsed = posix.normalize(path.replace(/^\/+/, "/"));
+    return collapsed.length > 1 ? collapsed.replace(/\/+$/, "") : collapsed;
+}
+/**
+ * 无文件系统的路径裁决 env(见文件头)。只覆写 `absolutePath` 一面,其余全部继承 `StubExecutionEnv`
+ * 的 `not_supported` ——**继承而非逐一手写**是刻意的:core 日后给 `ExecutionEnv` 加必填面时,新面会
+ * 随 `StubExecutionEnv` 一起到位并保持同一个诚实答案,不会在这里留下一个悄悄编出来的假答案。
+ */
+export class LexicalPathExecutionEnv extends StubExecutionEnv {
+    absolutePath(path) {
+        // POSIX 绝对形是沙箱 lane(全 Linux)上 hand 工具的书面契约形。其余一切——相对路径、`~`、
+        // `C:\…`——在 spec 期都无法诚实解析成一个沙箱内的绝对路径,返回错误让 core 落 ask。
+        // (反斜杠 UNC 形根本到不了这里:core 在 canonicalizeTarget 入口短路,见文件头「由此得到的裁决语义」。)
+        // codex 复审 A(2026-08-05):含 NUL 的字符串不是合法 POSIX 路径(任何 fs 面都写不进去),但词法归一
+        // 会照样给它铸出 canonical key——`\0` 尾巴让守卫段 glob 失配,豁免会话下还能拿 allow。拒收让 canon
+        // 在豁免咨询**之前**就失败 ⇒ 恒 ask。
+        if (path.includes("\u0000")) {
+            return Promise.resolve(err(new FileError("not_supported", "this environment adjudicates paths lexically and rejects a path containing a NUL byte (not a representable POSIX path)", path)));
+        }
+        if (!path.startsWith("/")) {
+            return Promise.resolve(err(new FileError("not_supported", "this environment adjudicates paths lexically and cannot resolve a non-absolute path (the sandbox working directory is unknown at spec time)", path)));
+        }
+        return Promise.resolve(ok(normalizeAbsolutePathLexically(path)));
+    }
+}
+//# sourceMappingURL=lexical-path-env.js.map

package/dist/capabilities/oa-tools.d.ts

@@ -0,0 +1,15 @@
+import type { ToolSpec } from "@sema-agent/core";
+/**
+ * OA scenario — tools are thin HTTP clients to the OA backend's existing APIs (read = /api/v1/*,
+ * write = /api/assets/*). The shared service token + the request's principal are forwarded so OA
+ * enforces THAT end-user's RBAC + audit (the service never holds per-user creds). Decoupled: the
+ * service knows no OA schema/DB — OA stays the source of truth (its /api/v1/meta is self-describing).
+ */
+export interface OaCtx {
+    baseUrl: string;
+    token: string;
+    principal?: string;
+}
+export declare function oaTools(ctx: OaCtx): ToolSpec[];
+export declare const oaPrompt: import("@sema-agent/core").PromptProvider;
+//# sourceMappingURL=oa-tools.d.ts.map

package/dist/capabilities/oa-tools.js

@@ -0,0 +1,54 @@
+import { Type } from "typebox";
+import { stablePrompt } from "./prompt.js";
+async function oaFetch(ctx, path, init) {
+    if (!ctx.baseUrl || !ctx.token)
+        return "OA 后端未配置(OA_API_BASEURL / OA_SERVICE_TOKEN)";
+    try {
+        const res = await fetch(ctx.baseUrl + path, {
+            method: init?.method ?? "GET",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${ctx.token}`,
+                ...(ctx.principal ? { "x-agent-principal": ctx.principal } : {}),
+            },
+            body: init?.body !== undefined ? JSON.stringify(init.body) : undefined,
+        });
+        const text = await res.text();
+        if (!res.ok)
+            return `OA ${res.status}: ${text.slice(0, 600)}`;
+        return text.slice(0, 60_000);
+    }
+    catch (e) {
+        return `调用 OA 失败：${e.message}`;
+    }
+}
+const needWrite = (ctx) => (!ctx.principal ? "缺少身份(principal)，无法代表用户写库；请让调用方带上 x-agent-principal。" : null);
+export function oaTools(ctx) {
+    const obj = Type.Object({}, { additionalProperties: true });
+    return [
+        { name: "oa_schema", effect: "read", description: "取 OA 数据结构(每类资产的字段/必填/条件必填 requiredWhen/联动 showWhen/枚举、生命周期、表名)。建/改前先调它，别凭记忆。", parameters: Type.Object({}), execute: () => oaFetch(ctx, "/api/v1/meta") },
+        { name: "oa_alerts", effect: "read", description: "派生告警：GP 闲置(已注册未变现) / APP 未上架(已接广告未 LIVE)。", parameters: Type.Object({}), execute: () => oaFetch(ctx, "/api/v1/alerts") },
+        { name: "oa_list", effect: "read", description: "列出某类资产。type∈gp/package/ad-platform/ad-unit/email/environment/proxy。可选 q 关键字。", parameters: Type.Object({ type: Type.String(), q: Type.Optional(Type.String()) }), execute: (a) => { const x = a; return oaFetch(ctx, `/api/v1/entities/${encodeURIComponent(x.type)}${x.q ? `?q=${encodeURIComponent(x.q)}` : ""}`); } },
+        { name: "oa_get", effect: "read", description: "取某资产详情(敏感字段为掩码)。", parameters: Type.Object({ type: Type.String(), id: Type.String() }), execute: (a) => { const x = a; return oaFetch(ctx, `/api/v1/entities/${encodeURIComponent(x.type)}/${encodeURIComponent(x.id)}`); } },
+        { name: "oa_lookup", effect: "read", description: "约定字段值反查(同手机/证件=同一实物)。field: phone|idCardNo|bizLicenseNo。", parameters: Type.Object({ field: Type.String(), value: Type.String() }), execute: (a) => { const x = a; return oaFetch(ctx, `/api/v1/lookup?field=${encodeURIComponent(x.field)}&value=${encodeURIComponent(x.value)}`); } },
+        { name: "oa_create", effect: "write", description: "创建实体(走 OA 校验+当前用户 RBAC+审计)。type + data(字段对象，参照 oa_schema)。失败会返回缺失/非法字段。", parameters: Type.Object({ type: Type.String(), data: obj }), execute: (a) => { const e = needWrite(ctx); if (e)
+                return e; const x = a; return oaFetch(ctx, `/api/assets/${encodeURIComponent(x.type)}`, { method: "POST", body: x.data ?? {} }); } },
+        { name: "oa_update", effect: "write", description: "改字段(敏感留空=保持原值；状态字段改不动，用 oa_transition)。", parameters: Type.Object({ type: Type.String(), id: Type.String(), data: obj }), execute: (a) => { const e = needWrite(ctx); if (e)
+                return e; const x = a; return oaFetch(ctx, `/api/assets/${encodeURIComponent(x.type)}/${encodeURIComponent(x.id)}`, { method: "PATCH", body: x.data ?? {} }); } },
+        { name: "oa_transition", effect: "write", description: "受控状态流转(先 oa_schema 看可用迁移；风险/弃用等需 note)。", parameters: Type.Object({ type: Type.String(), id: Type.String(), to: Type.String(), note: Type.Optional(Type.String()) }), execute: (a) => { const e = needWrite(ctx); if (e)
+                return e; const x = a; return oaFetch(ctx, `/api/assets/${encodeURIComponent(x.type)}/${encodeURIComponent(x.id)}/transition`, { method: "POST", body: { to: x.to, note: x.note ?? null } }); } },
+    ];
+}
+// OA business prompt MOVED OUT — migration complete (design/29, 2026-06-05). Persona / 工作准则 / UI
+// markers (::FORM:: / ::GOTO:: / ::SUGGEST:: / ::ISSUE_FORM::) / 分级确认 / 报bug流程 are OA's business,
+// and OA now injects the WHOLE thing per request via `request.systemPrompt` (it holds the service token,
+// content is stable per OA version → cacheable prefix; page context still rides `objective`). Keeping
+// any of it here would just DUPLICATE OA's prompt, so the base is EMPTY — single source of truth = OA.
+// The service stays business-agnostic: it provides the oa_* tools (referenced by NAME from OA's prompt;
+// they carry their own descriptions) and nothing else. `stablePrompt` keeps STABLE→VARIABLE order —
+// OA's systemPrompt is appended after this (empty) base, before core's <user_memory>.
+// (::ISSUE_FORM:: is parsed/rendered + submitted entirely by OA's frontend via OA /api/ai/issue — the
+//  service never touches it; `open_gitea_issue` remains only as the unattended/automated fallback.)
+const OA_SYSTEM = "";
+export const oaPrompt = stablePrompt(OA_SYSTEM);
+//# sourceMappingURL=oa-tools.js.map

package/dist/capabilities/tool-defer.d.ts

@@ -5,10 +5,20 @@
  *  - candidates for deferral are ONLY `spec.tools` (scenario/user tools) + MCP tools — core's first-party
  *    roster (Bash/Read/Edit/Grep/Glob/Write/…) is structurally NEVER deferred, so the CC "12 core tools
  *    inline" posture holds without any server action;
+ *    ⚠️ **这句在中间那些世代上一度不成立**(#277 件⑤ 对表):`deferMode:"auto"` 的压力阀曾把内建 fs 族
+ *    也卷进候选,小窗模型上首用即激活错;core 5.40.0(#308 a 案,判据帖 [4315] 翻面清单 #3)把阀候选
+ *    收回 caller specs,**内建恒 inline**,于是这句话重新为真。**对本仓零行为影响**——理由是下一条:
+ *    我们从不开 auto。这一段留着是因为它是那次漂移的出处(数字对了而理由没对,是最难查的一类)。
  *  - MCP tool names are ALWAYS deferred (unconditional in `classifyDeferred`) — no server knob needed;
  *  - `RunnerDeps.deferMode:"auto"` is ALL-OR-NOTHING over the candidates (defers every spec tool once their
  *    combined inline chars exceed 10% of the window) — on our default scenario that would defer Agent and the
  *    Task quartet too, the OPPOSITE of the CC posture, so we deliberately do NOT enable it;
+ *    🔴 该判断在 core 5.40.0 上**逐字仍成立**(#277 件⑤ 亲验):5.40 收窄的是「内建卷不卷进来」,而
+ *    Agent / Task 四件是 **caller spec 工具**,收窄后照样在候选池里 —— 所以「开了 auto 就会 defer 掉
+ *    CC 姿势工具」这条不开 auto 的理由没有被这次收窄消解。
+ *    我方**从不接线**这个座:全树零 `RunnerDeps.deferMode` 赋值(`deferModelPlane` 是 config-center 的
+ *    同形近名,与本轴无关)。机器钉见 test/tool-defer.test.ts 的 #277 件⑤ 格 —— 这条「零接线」正是本仓
+ *    在两个 core 世代之间行为逐字不变的**全部**依据,所以它值一根钉而不只是一句注。
  *  - per-tool `ToolSpec.defer:true` is the precise instrument — that is what this helper applies.
  *
  * Measured inline surface (chars = description + JSON schema; ÷4 ≈ tokens), default scenario @ core 1.289:

package/dist/finance/cost-taxonomy.d.ts

@@ -0,0 +1,34 @@
+export interface InfraCostRates {
+    toolCallMicroUsd: number;
+    sandboxSecMicroUsd: number;
+    egressGbMicroUsd: number;
+}
+export interface InfraUsage {
+    toolCalls: number;
+    sandboxWalltimeMs: number;
+    egressBytes: number;
+}
+export interface InfraCostBreakdown {
+    toolCallMicroUsd: number;
+    sandboxWalltimeMicroUsd: number;
+    egressMicroUsd: number;
+    totalMicroUsd: number;
+}
+export interface LlmCostBreakdown {
+    llmRootMicroUsd: number;
+    nestedSubagentMicroUsd: number;
+    memoryConsolidationMicroUsd: number;
+    compactionMicroUsd: number;
+}
+export interface SupervisorCostBreakdown {
+    llm: LlmCostBreakdown | null;
+    infra: InfraCostBreakdown;
+    totalMicroUsd: number;
+}
+export declare function infraCost(usage: InfraUsage, rates: InfraCostRates): InfraCostBreakdown;
+export declare function composeSupervisorCost(llm: LlmCostBreakdown | null, llmTotalMicroUsd: number, infra: InfraCostBreakdown): SupervisorCostBreakdown;
+export declare function hasInfraPricing(r: InfraCostRates): boolean;
+export declare function infraUsageFromEvents(events: ReadonlyArray<{
+    type?: string;
+}>, runDurationMs: number): InfraUsage;
+//# sourceMappingURL=cost-taxonomy.d.ts.map

package/dist/finance/cost-taxonomy.js

@@ -0,0 +1,26 @@
+const nonNeg = (n) => (Number.isFinite(n) && n > 0 ? n : 0);
+export function infraCost(usage, rates) {
+    const toolCallMicroUsd = nonNeg(usage.toolCalls) * nonNeg(rates.toolCallMicroUsd);
+    const sandboxWalltimeMicroUsd = (nonNeg(usage.sandboxWalltimeMs) / 1000) * nonNeg(rates.sandboxSecMicroUsd);
+    const egressMicroUsd = (nonNeg(usage.egressBytes) / 1_000_000_000) * nonNeg(rates.egressGbMicroUsd);
+    return {
+        toolCallMicroUsd,
+        sandboxWalltimeMicroUsd,
+        egressMicroUsd,
+        totalMicroUsd: toolCallMicroUsd + sandboxWalltimeMicroUsd + egressMicroUsd,
+    };
+}
+export function composeSupervisorCost(llm, llmTotalMicroUsd, infra) {
+    return { llm, infra, totalMicroUsd: nonNeg(llmTotalMicroUsd) + infra.totalMicroUsd };
+}
+export function hasInfraPricing(r) {
+    return r.toolCallMicroUsd > 0 || r.sandboxSecMicroUsd > 0 || r.egressGbMicroUsd > 0;
+}
+export function infraUsageFromEvents(events, runDurationMs) {
+    return {
+        toolCalls: events.reduce((n, e) => (e.type === "tool_start" ? n + 1 : n), 0),
+        sandboxWalltimeMs: nonNeg(runDurationMs),
+        egressBytes: 0,
+    };
+}
+//# sourceMappingURL=cost-taxonomy.js.map

package/dist/http/routes/capabilities.js

@@ -149,6 +149,17 @@ async function handleCapabilitiesBody(req, res, url, ctx, miss) {
             // 空名单在这条轴上**刻意**不走 `isOperator` 的「人人都是 operator」旧义(那是一道世界可写的门,
             // 见 principal-gate.ts 的 `explicitOperatorOk` 头注),所以补的是能力位、不是放宽授权。
             adoption: Boolean(deps.backend?.adoptionLog) && deps.config.operatorPrincipals.length > 0,
+            // #264 v2-c:治理携出 bundle 两口(`POST /v1/memory/{export,import}`,operator lane)。谓词**逐项**
+            // 对着 routes/memory-bundle.ts 的拒绝臂写,与 adoption 同族两项合取:
+            //  ①引擎两面都接线(`memoryBundle{Export,Import}`;记忆引擎没接线的部署 ⇒ 501);
+            //  ②operator 名单**非空** —— 否则 `explicitOperatorOk` 对任何身份恒假,两口**恒 403**
+            //    ([3397]-4 逮到的那条真缺口,adoption 同病,这里从第一天就带上)。
+            // ⚠️ 位为真**只**保证「门能过 + 引擎在场」,不保证这台部署的记忆后端真有 bundle 复合面:本仓两只
+            // SQL 记忆孪生没实现 `exportSnapshotOf`/`importBundleCommit`,那时 core 自己响亮拒
+            // (`memory.export_incomplete`)。刻意不把「后端有没有复合面」编进本位:那是一次**运行期**能力探测
+            // (要真打一次店面才知道),把它做成部署级布尔就会变成一个会撒谎的位 —— 诚实的边界写在这里,
+            // 而不是让位去猜。消费方按码分支(附录 A 已收录该码),不是 trial-by-501。
+            memoryBundle: Boolean(deps.memoryBundleExport && deps.memoryBundleImport) && deps.config.operatorPrincipals.length > 0,
             // [3397]-5:`GET /v1/outcomes`(design/73 §7.2 机械信号只读聚合)。此前**有 501 拒而无能力位** ——
             // 消费端只能 trial-by-501,与本仓「gate-don't-trial-by-501」的姿势相反。谓词逐项对着该路由的
             // 拒绝臂:①可查询的账面在场(`outcomeSink.summary`;File sink 只写 JSONL,没有查询面 ⇒ 501);

package/dist/http/routes/memory-bundle.d.ts

@@ -0,0 +1,109 @@
+/**
+ * #264 v2-c —— **治理携出 bundle 的 operator 面**(core 5.40.0 `MemoryEngine.exportMemoryScopes` /
+ * `importMemoryBundle`,design/178 v2-c;判据帖 [4315] G1/G2/G3)。
+ *
+ *   · `POST /v1/memory/export` —— 请求 `{scopes: string[]}`,回**治理完备包**(bundle 原样);
+ *   · `POST /v1/memory/import` —— 请求 `{bundle}`,回 `MemoryImportReport` 的白名单投影。
+ *
+ * ── 为什么是 operator-only(而不是属主自助)────────────────────────────────────────────────────
+ * 同路径上的 `GET /v1/memory/export?scope=`(routes/memory-policy.ts,142-S5)是**属主自助的条目读**:
+ * 一个 principal 导出自己那张盘。本面不是它的 POST 版本,是**另一件东西**:
+ *  · import 是**治理写面** —— 它往本部署的记忆平面里落别处铸的条目、挑战、污染标记与托管链。写错=
+ *    把一份外来治理史当成本店的账。fail-closed 是唯一可接受的缺省,门=`explicitOperatorOk`(与
+ *    approvals RBAC / adoption / retention-ops 同一条门,不是第二套判据);
+ *  · export 出的包**跨 scope 携带治理行**(custody 链、跨会话污染标记、lineage),按定义超出任何单个
+ *    principal 的自助边界 —— 与 import 同级授权,不给「读半场松一格」的斜坡。
+ * 缺 principal 的形照 sibling mutating 端点(retention-ops / adoption)401 `auth.principal_required`。
+ *
+ * ── 门序(逐字同 routes/adoption.ts / retention-ops.ts)────────────────────────────────────────
+ * 身份(401)→ 授权(403)→ 能力(501)→ 验型(400)。**授权在能力之前**:一个够不着任何东西的调用方
+ * 不该从「这个部署有没有记忆引擎」上读出部署形态。
+ *
+ * ── 能力面的诚实形(与 GET 面**方向相反**,这不是笔误)──────────────────────────────────────
+ * `GET /v1/memory/export` 要的是 **DB 记忆平面**(pg|tidb),file 形态 501。本面要的是 core 的
+ * **bundle 复合面**(`exportSnapshotOf` / `importBundleCommit`),而它今天只在 core 自带的 **File**
+ * 后端上实装:本仓的两只 SQL 记忆孪生(plugins/memory-engine-{pg,tidb}.ts)没有实现这两个可选面。
+ * 因此**两个成因同落 501** `capability.memory_engine_required`(都是「换部署形态才行」,消费端分支相同):
+ *  · 记忆引擎整个没接线(`MEMORY_ENGINE=off` / 多租 file 底座等暗态);
+ *  · 引擎接了但后端没有 bundle 复合面(pg/tidb 孪生)—— 这一支在**挂载期**就判掉了
+ *    (`createMemoryBundleFaces` 返回 undefined ⇒ 两口整个不挂),能力位 `memoryBundle` 因此与「路由真能用」
+ *    严格同真。🔴 首版把它当运行期事实(照常挂载、让 core 每次抛 409/422),被 codex 对抗复审驳倒并改此形:
+ *    面在不在是一次**属性检查**、boot 期判得出、且是**永久**缺席 ⇒ 照常挂着就是一个恒假的 yes,
+ *    壳会据此给用户开出一条走不通的迁移流程。
+ * ⚠️ 与**运行期**拒别混:后端**有**复合面但托管链 chain-degraded 时,core 照样抛
+ *    `memory.export_incomplete`(409)—— 那是诚实的运行期拒,附录 A 单列。
+ * ⚠️ 绝不在本层为 SQL 孪生现造一个「够用的」导出:那正是 core 明写要拒绝的
+ *    「a governance-less export is the laundering shape this API refuses by design」。
+ *    SQL 孪生补齐两面是上游/本仓 store 层的独立工单(消费台账 debt 行)。
+ *
+ * ── 验型的分权:server 验**形**,core 验**义** ─────────────────────────────────────────────────
+ * 本层只用 zod 校 JSON **结构**(宪法 [2704]:边界必 schema、禁裸 as-cast)。scopes 的「非空/去重/
+ * 元素非空」与 bundle 的整包判决(section hash 键集、逐条目 rev 重算、批内唯一性、scope 授权信封)
+ * **全部**归 core —— 在本层抄一遍等于第二真源:core 收紧一格我方不会跟着动,而两边都"绿"。
+ * 于是 `{scopes:["a","a"]}` 这种**形对义错**的请求会走到引擎并带回 `config.memory_export_request`。
+ *
+ * ── 披露的传导([4352] 权威句;打分帖 [4351] 扣点① 的 server 半场)────────────────────────────
+ * bundle 体里的 `doc: string[]` 是**铸包方的治理披露**(自由串字面的租户隔离界限等),core 铸包时恒
+ * 写入。本面把它**原样透传**:不剥离、不复述、不另铸 `disclosure` 键。理由是单一属主 —— 复述会随
+ * core 版本漂移,而转发即真话。端点文档(openapi 段 + docs/ASSISTANT-WIRE-CONTRACT.md)负责告诉消费方
+ * 「`bundle.doc` 要呈现给最终用户」。
+ *
+ * ── 幂等 ────────────────────────────────────────────────────────────────────────────────────
+ * 同 bundle 重放的收敛是 **core 的**契约(崩溃后重导同一包收敛;已完成的导入幂等答同一份记录报告)。
+ * 本端点**不加**第二层去重:两个写者压同一条语义面,其重叠通常比原缺陷更坏且静默。
+ *
+ * 计费/lane:两口都是**部署级治理动作**,零模型工作 ⇒ `billable=false`(与 adoption / retention-ops
+ * 同族,申明在 test/billable-route-declaration.test.ts)。
+ *
+ * 分层:本模块不值 import `server.ts`(那条边闭合运行时装载环),只 `import type`。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { MemoryImportReport } from "@sema-agent/core";
+import type { RouteCtx } from "../route-ctx.js";
+export declare const MEMORY_BUNDLE_EXPORT_PATH = "/v1/memory/export";
+export declare const MEMORY_BUNDLE_IMPORT_PATH = "/v1/memory/import";
+/**
+ * `MemoryImportReport` → wire 的**显式白名单**投影。
+ *
+ * 🔴 为什么是显式白名单而不是整行透传:报告是**治理处置**的清单,core 日后加一个新的处置座(例如又一
+ * 类"被扣下的行"),整行透传会让它**静默**上 wire 而没人给它写过契约;白名单让它变成**编译错误**
+ * (`test/memory-bundle-http.test.ts` 的差集断言 = `wire-whitelist-exhaustiveness` 同款门形)。
+ * 今天**每一个**键都在场:每一条都是 operator 判「这次导入到底发生了什么」必须看到的东西,一个都
+ * 不该省 —— 「每个否定处置都被报告,绝不静默」是 core 对这份报告的原话。
+ */
+export declare function buildImportReportWire(r: MemoryImportReport): {
+    v: 1;
+    bundleHash: string;
+    sourceStoreId: string;
+    landed: {
+        id: string;
+        scope: string;
+        slug: string;
+    }[];
+    alreadyPresent: string[];
+    refusedErased: string[];
+    refusedUntrusted: string[];
+    conflicts: {
+        id: string;
+        reason: string;
+    }[];
+    governanceWithheld: string[];
+    erasedAtSource: string[];
+    pollutionDivergence: {
+        sessionId: string;
+        kept: "destination";
+    }[];
+    referentialOrphans: string[];
+    lineageDivergence: {
+        entryId: string;
+        sessionId: string;
+        kept: "destination";
+    }[];
+    custodyWithheld: {
+        srcEv: string;
+        channel: string;
+    }[];
+    custodyAppended: number;
+};
+export declare function handleMemoryBundle(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+//# sourceMappingURL=memory-bundle.d.ts.map

package/dist/http/routes/memory-bundle.js

@@ -0,0 +1,178 @@
+import { z } from "zod";
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+export const MEMORY_BUNDLE_EXPORT_PATH = "/v1/memory/export";
+export const MEMORY_BUNDLE_IMPORT_PATH = "/v1/memory/import";
+/** export 请求体 —— **形**验(义归 core;见文件头「验型的分权」)。 */
+const ExportRequestSchema = z.object({ scopes: z.array(z.string().min(1)).min(1) });
+/** import 请求体 —— 只断言 `bundle` 是个**对象**;整包判决是 core 的单一属主面。
+ *  `z.record(z.string(), z.unknown())` 而不是 `z.object({...})`:在本层写出 bundle 的字段表就是复制
+ *  core 的 schema(第二真源),而 `z.unknown()` 的 record 恰好表达「结构由下游判」。 */
+const ImportRequestSchema = z.object({ bundle: z.record(z.string(), z.unknown()) });
+/**
+ * core 抛出的**已分类**错误 → HTTP 状态。闭集穷举 `switch`:core 新增一个码 ⇒ 这里落 `undefined`
+ * ⇒ 走 500 fail-loud(而不是被某个默认臂静默塞进 4xx)。安全轴上的静默默认值正是本仓禁止的东西。
+ *
+ *  · `config.memory_{export,import}_request` = **调用方**给的请求参数不合法(非空/去重/可序列化)⇒ 400;
+ *  · `memory.export_incomplete` = 店**声明自己说不清**(chain-degraded / 无导出复合面)⇒ 409:不是请求
+ *    的错、也不是服务器故障,是**当前状态**下这个包铸不出来(去修 chain 或换后端后重试即改判);
+ *  · `memory.import_rejected` = 请求**形**合法但**内容**不可接受(整包拒批,零落地)⇒ 422 —— 与 400
+ *    分家是承重的:400 说"你的 HTTP 请求写错了",422 说"包本身被判不合格",两句话的运维动作不同。
+ *
+ * 🔴 每一支都把码**再写一遍字面量**(而不是 `sendError(res, status, code, …)` 把变量透下去):错误码
+ * 目录门(test/error-code-catalog-live.test.ts)是**扫源码字面量**的,变量态的码整条对它隐形 ⇒ 这四个
+ * 码会「wire 上发得出来、附录 A 里查不到」。同门另有一张中继登记表可走,但那张表是**有上限的棘轮**
+ * (「码不写字面量」不许变成默认写法),而这里本来就该是一张闭集词表 —— 写字面量既过门又把闭集写实。
+ */
+// ⚠️ 形参叫 `coreCode` 而不是 `code`:错误体自 core 3.0.0 起**只有** `errorCode`,而 test/error-code-key-gate
+// 扫的是「还在发 legacy `code` 键」的站点(文本判据)——一个叫 `code` 的形参会被它当成那种站点收走。
+function sentCoreCode(res, coreCode, message) {
+    switch (coreCode) {
+        case "config.memory_export_request":
+            sendError(res, 400, "config.memory_export_request", message);
+            return true;
+        case "config.memory_import_request":
+            sendError(res, 400, "config.memory_import_request", message);
+            return true;
+        case "memory.export_incomplete":
+            sendError(res, 409, "memory.export_incomplete", message);
+            return true;
+        case "memory.import_rejected":
+            sendError(res, 422, "memory.import_rejected", message);
+            return true;
+        default:
+            return false;
+    }
+}
+/** core 的抛出形 = `Error` + `.code`(engine.js 逐字)。裸 as-cast 禁令下的判别式读法。 */
+function codeOf(err) {
+    if (!(err instanceof Error))
+        return undefined;
+    const { code } = err;
+    return typeof code === "string" ? code : undefined;
+}
+/**
+ * 引擎调用的统一收尾:已分类的码**原样**上 wire(码与 core 的诊断文案都不改写 —— 那句文案是运维排障
+ * 的第一手材料,判据帖 G3 就断言它含 "chain-degraded");未分类的一律 500 且**不回显**内部文本。
+ * 返回 true = 已应答。
+ */
+function sentClassifiedFailure(res, ctx, face, err) {
+    const code = codeOf(err);
+    if (code !== undefined && sentCoreCode(res, code, err instanceof Error ? err.message : String(err)))
+        return true;
+    ctx.deps.logger?.warn?.(`memory_bundle_${face}_failed`, { err: String(err) });
+    return false; // 未分类 ⇒ 调用方发它自己那句 500(见下面两处的**内联字面量**)
+}
+/**
+ * `MemoryImportReport` → wire 的**显式白名单**投影。
+ *
+ * 🔴 为什么是显式白名单而不是整行透传:报告是**治理处置**的清单,core 日后加一个新的处置座(例如又一
+ * 类"被扣下的行"),整行透传会让它**静默**上 wire 而没人给它写过契约;白名单让它变成**编译错误**
+ * (`test/memory-bundle-http.test.ts` 的差集断言 = `wire-whitelist-exhaustiveness` 同款门形)。
+ * 今天**每一个**键都在场:每一条都是 operator 判「这次导入到底发生了什么」必须看到的东西,一个都
+ * 不该省 —— 「每个否定处置都被报告,绝不静默」是 core 对这份报告的原话。
+ */
+// 🔴 **不要**给这个函数标 `: Record<string, unknown>` 返回型:那会让 `keyof ReturnType<…>` 塌成 `string`,
+// 上面那道编译期差集门当场变成**恒真**(vacuous)—— 写这条钉时正踩到过。返回型交给推断,键集才是字面的。
+export function buildImportReportWire(r) {
+    return {
+        v: r.v,
+        bundleHash: r.bundleHash,
+        sourceStoreId: r.sourceStoreId,
+        landed: r.landed,
+        alreadyPresent: r.alreadyPresent,
+        refusedErased: r.refusedErased,
+        refusedUntrusted: r.refusedUntrusted,
+        conflicts: r.conflicts,
+        governanceWithheld: r.governanceWithheld,
+        erasedAtSource: r.erasedAtSource,
+        pollutionDivergence: r.pollutionDivergence,
+        referentialOrphans: r.referentialOrphans,
+        lineageDivergence: r.lineageDivergence,
+        custodyWithheld: r.custodyWithheld,
+        custodyAppended: r.custodyAppended,
+    };
+}
+export async function handleMemoryBundle(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleMemoryBundleBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleMemoryBundleBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const path = url.split("?")[0] ?? url;
+    const isExport = req.method === "POST" && path === MEMORY_BUNDLE_EXPORT_PATH;
+    const isImport = req.method === "POST" && path === MEMORY_BUNDLE_IMPORT_PATH;
+    if (!isExport && !isImport) {
+        miss.fell = true;
+        return;
+    }
+    // ── 身份(401)── direct-door safe:验证过的身份,不是可伪造的头。
+    const principal = gatedPrincipal(req, deps.config);
+    if (deps.config.requirePrincipal && !principal) {
+        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        return;
+    }
+    // ── 授权(403)── 治理面 fail-closed,与 adoption / retention-ops 同一条门。
+    // ⚠️ 文案写**内联字面量**而不是抽个模块常量:文案冻结门(test/api-error-text-freeze.test.ts)是**扫源码
+    //    文本**的,把 message 换成一个常量名的写法它结构性够不到 ⇒ 这句 wire 文案就没有被冻住。
+    //    ⚠️ 本段注释里也不许照抄一个带状态码与引号码名的调用样例 —— 那道门的提取器会把**注释里**的样例
+    //    当成一条真站点收走(写这条注时真的踩到过:凭空多出一个 `403:code` 对)。
+    //    两口同受众同理由,所以两处逐字同一句(族断言按去重集合比,同串出现两次不改判)。
+    if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {
+        sendError(res, 403, "auth.operator_only", "memory governance bundles are an operator-only deployment action");
+        return;
+    }
+    // ── 能力(501)── 在授权之后:部署形态不对越权者泄漏。
+    // ⚠️ 与 `capability.memory_store_required`(GET 导出面要 DB 平面)**刻意不合并**:两码的运维动作相反
+    //    (那条要 pg|tidb,本条要引擎在场且后端带 bundle 复合面),消费端真会分支——附录 A 判据②。
+    // 🔴 缺席有**两个**成因,文案两个都点名(codex [medium] 后修:此前只说「引擎没接线」,而 pg/tidb 部署
+    //    是引擎接了、后端没那两个可选面 —— 只说一半会让运维去查一个根本没问题的旋钮)。两因同码:消费端
+    //    的分支一样(本部署做不了 bundle,换部署形态),分成两码只会让码表长一倍而判据不变(判据②)。
+    const engineExport = deps.memoryBundleExport;
+    const engineImport = deps.memoryBundleImport;
+    if (engineExport === undefined || engineImport === undefined) {
+        sendError(res, 501, "capability.memory_engine_required", "memory governance bundles are not available on this deployment — they require a wired memory engine (MEMORY_ENGINE=on) whose backend implements the v2-c bundle composite (exportSnapshotOf / importBundleCommit); the file memory backend does, the pg/tidb memory backends do not");
+        return;
+    }
+    // ── 验型(400)── 体读的 413/400(超长 / 坏 JSON)由顶层 typed catch 统一处理(鉴权已完成)。
+    const raw = await ctx.helpers.readJson(req);
+    if (isExport) {
+        const parsed = ExportRequestSchema.safeParse(raw);
+        if (!parsed.success) {
+            sendError(res, 400, "request.body_shape", "invalid memory export request — expected an object with a non-empty `scopes` array of non-empty strings");
+            return;
+        }
+        try {
+            // 🔴 bundle **原样**下发(含 `doc` 披露段)—— 投影它就是替铸包方复述披露,见文件头。
+            const bundle = await engineExport(parsed.data.scopes);
+            sendJson(res, 200, bundle);
+        }
+        catch (err) {
+            // 未分类 ⇒ 500,文案是**内联整串**(不是 `memory bundle ${face} failed` 模板):冻结门的模板臂只
+            // 钉到第一个 `${` 为止,"memory bundle " 这个前缀会把「哪一半炸了」留在门外,而那正是消费端能从
+            // 500 上读到的全部信息。同族先例:"memory export failed" / "memory sync failed"(memory-policy.ts)。
+            if (!sentClassifiedFailure(res, ctx, "export", err))
+                sendError(res, 500, "internal.error", "memory bundle export failed");
+        }
+        return;
+    }
+    const parsed = ImportRequestSchema.safeParse(raw);
+    if (!parsed.success) {
+        sendError(res, 400, "request.body_shape", "invalid memory import request — expected an object with a `bundle` object");
+        return;
+    }
+    try {
+        // 整包判决(结构/完整性/授权信封)全在 core:本层递交的就是调用方给的那个对象。
+        // 递交的是**未校验**的对象:整包判决(结构/完整性/授权信封)是 core 的单一属主面,所以 seam 的
+        // 入参类型就写 `unknown` —— 在本层把它断言成 MemoryExportBundle 是**说谎**(我们并不知道它是),
+        // 而说谎的那一下正好把类型检查关灯(type-hygiene 门抓的就是这个)。
+        const report = await engineImport(parsed.data.bundle);
+        sendJson(res, 200, buildImportReportWire(report));
+    }
+    catch (err) {
+        if (!sentClassifiedFailure(res, ctx, "import", err))
+            sendError(res, 500, "internal.error", "memory bundle import failed");
+    }
+}
+//# sourceMappingURL=memory-bundle.js.map

package/dist/http/server.d.ts

@@ -1,6 +1,6 @@
 import http from "node:http";
 import type { IncomingMessage } from "node:http";
-import { type Runner, type TaskSpec, type TaskResult, type WorkflowRunStore, type MemoryEntry } from "@sema-agent/core";
+import { type Runner, type TaskSpec, type TaskResult, type WorkflowRunStore, type MemoryEntry, type MemoryExportBundle, type MemoryImportReport } from "@sema-agent/core";
 import type { TaskRequestBody } from "./wire-types.js";
 import type { ServiceConfig } from "../config-types.js";
 import { type RestartSignal, type SessionMirrorRuling } from "../config-center/facade.js";
@@ -290,6 +290,20 @@ export interface ServiceSeamDeps {
      *  (MEMORY_ENGINE_BACKEND=pg|tidb); absent / file posture ⇒ 501 honestly (a single-user file plane
      *  IS the TOC side of a sync — it has no central-authority half to serve). */
     memorySync?: (scope: string, syncReq: MemorySyncRequest) => Promise<MemorySyncResponse>;
+    /** #264 v2-c(core 5.40.0 `MemoryEngine.exportMemoryScopes`):治理完备包的**携出**面。main.ts 把它接到
+     *  装配好的 memory engine 上。启用 `POST /v1/memory/export`(operator-only)。
+     *  🔴 缺席 = 这个部署**没有记忆引擎**(`MEMORY_ENGINE=off` / 多租 file 底座等暗态)⇒ 501
+     *  `capability.memory_engine_required`。注意与 {@link memoryExport} 的**方向相反**:那条要 DB 记忆
+     *  平面,本条只要引擎在场 —— 而 bundle 复合面(`exportSnapshotOf`)今天只有 core 自带的 File 后端
+     *  实装,SQL 孪生上引擎会自己响亮拒(`memory.export_incomplete` 原样上 wire)。理由全文见
+     *  routes/memory-bundle.ts 的「能力面的诚实形」。 */
+    memoryBundleExport?: (scopes: readonly string[]) => Promise<MemoryExportBundle>;
+    /** #264 v2-c(core 5.40.0 `MemoryEngine.importMemoryBundle`):治理完备包的**导入**面(治理写面)。
+     *  启用 `POST /v1/memory/import`(operator-only)。缺席语义与 {@link memoryBundleExport} 逐字相同 ——
+     *  两口共用一个能力判据,因为它们是同一个引擎面的两半(一个部署不可能只有其中一半)。 */
+    memoryBundleImport?: (bundle: unknown, opts?: {
+        expectedScopes?: readonly string[];
+    }) => Promise<MemoryImportReport>;
     /** design/170 件A §7 —— org 记忆授权目录,`boot/org-memory.ts` 装配的**同一个实例**(准入 seam 与
      *  本面共享它的 TTL 缓存/退避窗/gen 高水位)。memory-policy 面的 `org:` 属主门用它回答成员性:
      *  读面要该 scope 在授权表里、写面另要条目 `write === true`。缺席=本部署没有目录源 ⇒ `org:` 键
@@ -574,8 +588,20 @@ export declare function isBillableSubmitPath(url: string): boolean;
  * 🔴 **方法感知**(codex 对抗复审 R2-[high],验真后修):撤销走的是 `DELETE`,而本门最初只挂在 `POST` 的
  * 合取里 —— 于是一个自称「持久改写」的谓词把爆炸半径最大的那条动词漏在门外,正是 `isDestructiveSessionWrite`
  * 当年被抓到的同一形。签名因此收方法,与那只谓词逐字同形。
- * 🔴 读面不进本表:`GET /v1/adoption/:id` 与 `GET /v1/rules` 各有自己的属主/operator 门,本门只拦写。
- * 行为面钉:`test/rewrite-door-service-token-gate.test.ts`(四扇门各一正一反 + 逃生口格 + 读面负控)。
+ * 🔴 读面**原则上**不进本表:`GET /v1/adoption/:id` 与 `GET /v1/rules` 各有自己的**属主门**兜底,本门只拦写。
+ *
+ * 🔴 **第二个合取项的加宽**(codex 对抗复审 [high],#277 提货批,验真后修)——判据现在是
+ * 「持久改写 **或** 授权唯一输入是 principal 头的**跨租户治理读**」。加宽是为了收进 #264 v2-c 的两口:
+ *  · `POST /v1/memory/import` —— 直接落在**原**判据上,而且是本仓最深的那一种持久改写:它把别处铸的
+ *    条目 / 挑战 / 污染标记 / 托管链落进本部署的记忆平面。伪造一个在册 operator 头 ⇒ 一份**攻击者自制的
+ *    治理史**成为本店的账;而记忆是模型**每次挂载都读**的面,比种一条常驻 allow 规则更深(那条只影响
+ *    ask 会不会问,这条影响模型相信什么)。
+ *  · `POST /v1/memory/export` —— 是**读**,按原措辞本不该进。但被点名豁免的那两条读各有属主门兜底,
+ *    而本条**没有**:它的授权判据就是 `explicitOperatorOk`,过了就是**全库**——一次调用取走每个 scope 的
+ *    条目正文 + 托管链 + 跨会话污染标记 + lineage。把一次全租户记忆外泄留在门外、只为守住「本门只拦写」
+ *    这句措辞,是把措辞看得比它要保护的东西更重。加宽后的判据仍然是**闭**的(不是「写门以外都进」):
+ *    它要求「授权的唯一输入是那个头」∧「一次调用的爆炸半径跨租户」,`GET /v1/rules` 那种属主门读不满足。
+ * 行为面钉:`test/rewrite-door-service-token-gate.test.ts`(六扇门各一正一反 + 逃生口格 + 读面负控)。
  */
 export declare function isCredentialGatedRewrite(method: string, url: string): boolean;
 /** Stable, low-cardinality route label for metrics/logs (ids collapsed to `:id`).