@sema-agent/server 7.10.0 → 7.12.0

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

@@ -0,0 +1,31 @@
+/**
+ * design/177 —— 共享记忆库(org 盘)的**只读 HTTP 面**。
+ *
+ * 路由:`GET /v1/shared-memory/stores`、`GET /v1/shared-memory/stores/:store/documents`、
+ * `GET /v1/shared-memory/stores/:store/document?path=`。本域零可变状态。
+ *
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * 挂载条件 = store ∧ org 折叠面,**双在场**才有这个域(v2/F4 硬化)
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * 供给面在场但授权面缺席时,这个域整体**不挂载** —— 请求落到全局 404 `not_found.route`。刻意不是 501:
+ *  · 501 的自述是「这个面存在,只是本部署没开」,它对一个连身份都无法被判定的调用方泄露了「这套部署
+ *    有共享记忆库」,并暗示补个配置就能读;
+ *  · 「store 好了先挂载、授权后补」是这条纪律真正要堵的中间态 —— 一个没有成员性判据的读面,唯一能做的
+ *    要么是全放(跨租户读)要么是全拒(伪装成故障),两个都比「这个面不存在」差。
+ * 能力广告(`capabilities.sharedMemory`)读的是**同一个合取式**,所以「说 yes ⟺ 面真能用」结构上成立。
+ *
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * 授权:一次 snapshot,零第二真源
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * 每个请求取**一次** `provider.snapshot({ principal })` —— 与模型面(core 的 memory_list/memory_read)
+ * 走的是同一个供给口、同一次绑定。可见的 store 集合因此按定义等于模型看到的那一份,HTTP 面不可能比
+ * 模型面多看见一个库。越界一律 404 且**与「这个库根本不存在」字节同形**:状态码、errorCode、message
+ * 全同,差一个字就是一次成员性探针(某人能用 404 的差异枚举出别的 org 有哪些库)。
+ *
+ * 文档**不存在**则另说(`not_found.shared_memory_document`):调用方已经证明了自己是这个库的成员,
+ * 「库里没有这份文件」对他不是秘密,把它和「你不是成员」合并反而会让成员无法区分打错路径和权限问题。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteCtx } from "../route-ctx.js";
+export declare function handleSharedMemory(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+//# sourceMappingURL=shared-memory.d.ts.map

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

@@ -0,0 +1,181 @@
+import { SHARED_MEMORY_READ_CAP_BYTES, SharedMemoryStoreError } from "@sema-agent/core";
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal } from "../principal-gate.js";
+const PREFIX = "/v1/shared-memory/";
+/** `unavailable` 时给客户端的重试间隔。目录退避窗与库导入都在秒级,10s 是"别打穿"与"别显得死了"之间。 */
+const RETRY_AFTER_SEC = 10;
+/** 一次 documents 列举的窗口。core 的模型面用 50;HTTP 面给同一个数量级,靠 cursor 续窗。 */
+const HTTP_LIST_LIMIT = 100;
+/** core 的文档路径规则,HTTP 参数面复述:绝对、无控制字符/反斜杠、段非空且不以 `.` 开头、文件名带后缀。 */
+const FORBIDDEN_PATH_CHARS = /[\p{Cc}\p{Cf}\p{Co}\p{Cn}\p{Default_Ignorable_Code_Point}\u2028\u2029\\]/u;
+const DOCUMENT_SUFFIXES = [".md", ".txt", ".json", ".jsonl"];
+function isDocumentPath(path) {
+    if (!path.startsWith("/") || FORBIDDEN_PATH_CHARS.test(path))
+        return false;
+    const segments = path.slice(1).split("/");
+    const last = segments.at(-1);
+    if (last === undefined || !segments.every((s) => s !== "" && !s.startsWith(".")))
+        return false;
+    return DOCUMENT_SUFFIXES.some((s) => last.endsWith(s));
+}
+/** 零存在性 oracle 的那**一句**拒绝。三种成因(库不存在 / 不是成员 / 是别的 org 的库)共用它,因此
+ *  调用方无法用响应差异枚举别人的库。改这里的字面量时三条腿一起改——它们同形是**被测断言**。 */
+function refuseStore(res) {
+    sendError(res, 404, "not_found.shared_memory_store", "not found");
+}
+/** 供给面自述不可用 ⇒ 503 + Retry-After。**绝不**塌成「200 空库」:后者对调用方是终局的
+ *  「你们团队没有共享库」,而真相是「暂时读不到,一会儿再来」——两句话是相反的指令。 */
+function refuseUnavailable(res, message) {
+    res.setHeader("retry-after", String(RETRY_AFTER_SEC));
+    sendError(res, 503, "memory.shared_unavailable", "shared memory stores are unavailable", {
+        retryAfterSec: RETRY_AFTER_SEC,
+        ...(message !== undefined ? { detail: message } : {}),
+    });
+}
+/** 取本次请求的绑定快照。返回 `undefined` = 已经应答(401/503),调用方直接 return。 */
+async function bindSnapshot(req, res, ctx) {
+    const { deps } = ctx;
+    // 身份先于可用性(memory-policy 同款次序):后端姿态不该对一个本来什么都读不到的调用方 oracle。
+    const principal = gatedPrincipal(req, deps.config); // direct-door safe: verified identity, never the spoofable header
+    if (!principal && deps.config.requirePrincipal === true) {
+        sendError(res, 401, "auth.unauthorized", "unauthorized");
+        return undefined;
+    }
+    const provider = deps.sharedMemoryStore;
+    if (!provider) {
+        // 到不了:域头的合取式已经保证它在场。写出来是为了让类型收窄不靠断言。
+        refuseStore(res);
+        return undefined;
+    }
+    const snapshot = await provider.snapshot({ sessionId: `http:${principal ?? "anonymous"}`, taskId: "http-read", ...(principal ? { principal } : {}) }, {});
+    if (snapshot.state === "unavailable") {
+        refuseUnavailable(res, snapshot.message);
+        return undefined;
+    }
+    return snapshot;
+}
+/**
+ * reader 抛出的 **typed** 失败 → HTTP 的逐格映射。返回 `true` = 已应答。
+ *
+ * 🔴 codex 复审轮2 F2(真缺陷):不折叠的话这些全落进外层兜底的 500 `internal.error`。而它们**不是**
+ * 服务器缺陷:`store_not_found` 是治理面在绑定之后回收了库(正常竞态),`refused/document_too_large`
+ * 是一行旧数据(可恢复状况)。更要命的是——真 SQL 供给面对超帽行是**抛**而不是返回内容,所以本文件
+ * 那条 413 分支对它根本不可达,除非在这里折。
+ *
+ * `kind` 是 core 的闭集,用穷举 `switch` 消费:core 加员时这里当场编译红,而不是悄悄落进某个 default。
+ */
+function foldReaderError(res, err) {
+    if (!(err instanceof SharedMemoryStoreError))
+        return false;
+    switch (err.kind) {
+        case "store_not_found":
+            refuseStore(res); // 与"你不是成员"同形——绑定之后库没了,对调用方就是"它不存在"
+            return true;
+        case "refused":
+            if (err.reason === "document_too_large") {
+                // 与模型面同一条规则:拒绝,不截断(一份被截断的共享文档读起来和完整的一模一样)。
+                sendError(res, 413, "request.payload_too_large", `document exceeds the ${SHARED_MEMORY_READ_CAP_BYTES}-byte shared-store read cap`, { capBytes: SHARED_MEMORY_READ_CAP_BYTES });
+                return true;
+            }
+            // host 自述的其它拒绝(配额等):按"现在读不到,带着机器原因重试"回,原因原样进 detail。
+            refuseUnavailable(res, err.reason);
+            return true;
+        case "transient":
+            refuseUnavailable(res, err.reason);
+            return true;
+    }
+}
+/** 快照里解析一个 store,越界返回 `undefined` 并已应答 404(同形拒)。 */
+function resolveStore(res, snapshot, storeId) {
+    if (snapshot.state !== "connected") {
+        refuseStore(res); // connecting 状态下没有绑定,任何具名库对这次请求都还不存在
+        return undefined;
+    }
+    const found = snapshot.stores.find((s) => s.info.id === storeId);
+    if (!found) {
+        refuseStore(res);
+        return undefined;
+    }
+    return found.reader;
+}
+export async function handleSharedMemory(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleSharedMemoryBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleSharedMemoryBody(req, res, url, ctx, miss) {
+    // GET /v1/shared-memory/stores —— 本会话可见的库清单(= 模型面 memory_list 无参形的同一份)。
+    if (url === "/v1/shared-memory/stores" && req.method === "GET") {
+        const snapshot = await bindSnapshot(req, res, ctx);
+        if (!snapshot)
+            return;
+        if (snapshot.state !== "connected") {
+            // 诚实的「还没好」:既不是错误(没坏)也不是空(不是终局)。与 core 模型面的 CONNECTING 同义。
+            // (`unavailable` 已在 bindSnapshot 里 503 掉,走不到这里;判 `!== "connected"` 是为了让类型
+            //  收窄不靠断言 —— 联合加员时这里当场编译红,而不是悄悄落进某个 else。)
+            sendJson(res, 200, { state: "connecting", stores: [] });
+            return;
+        }
+        sendJson(res, 200, { state: "connected", stores: snapshot.stores.map((s) => ({ id: s.info.id, description: s.info.description, writable: s.info.writable })) });
+        return;
+    }
+    const rest = url.startsWith(PREFIX) ? url.slice(PREFIX.length) : undefined;
+    const segments = rest === undefined ? [] : rest.split("/");
+    // stores/:store/documents  |  stores/:store/document
+    if (segments.length === 3 && segments[0] === "stores" && req.method === "GET" && (segments[2] === "documents" || segments[2] === "document")) {
+        const storeId = decodeURIComponent(segments[1]);
+        const query = new URL(req.url ?? "", "http://x").searchParams; // route-level `url` is query-stripped
+        const snapshot = await bindSnapshot(req, res, ctx);
+        if (!snapshot)
+            return;
+        const reader = resolveStore(res, snapshot, storeId);
+        if (!reader)
+            return;
+        if (segments[2] === "documents") {
+            const prefix = query.get("path_prefix") ?? undefined;
+            const cursor = query.get("cursor") ?? undefined;
+            const page = await reader.list(prefix, { ...(cursor !== undefined ? { cursor } : {}), limit: HTTP_LIST_LIMIT }).catch((err) => {
+                if (foldReaderError(res, err))
+                    return undefined;
+                throw err; // 非 typed 的失败仍归外层兜底(那才真是服务器缺陷)
+            });
+            if (page === undefined)
+                return;
+            const entries = Array.isArray(page) ? page : page.entries;
+            const nextCursor = Array.isArray(page) ? undefined : page.nextCursor;
+            sendJson(res, 200, { store: storeId, entries, ...(nextCursor !== undefined ? { nextCursor } : {}) });
+            return;
+        }
+        const path = query.get("path");
+        if (path === null || path === "" || !isDocumentPath(path)) {
+            sendError(res, 400, "request.query_invalid", "missing or malformed ?path= (absolute, .md/.txt/.json/.jsonl)");
+            return;
+        }
+        let folded = false;
+        const doc = await reader.read(path, {}).catch((err) => {
+            if (foldReaderError(res, err)) {
+                folded = true;
+                return null;
+            }
+            throw err;
+        });
+        if (folded)
+            return;
+        if (doc === null) {
+            // 成员本人有权区分「打错了路径」与「无权」——见文件头注。
+            sendError(res, 404, "not_found.shared_memory_document", "not found");
+            return;
+        }
+        const bytes = Buffer.byteLength(doc.content, "utf8");
+        if (bytes > SHARED_MEMORY_READ_CAP_BYTES) {
+            // core 的模型面对超帽文档是**拒绝并报出真实大小**,从不截断(一份被截断的共享文档读起来和完整的
+            // 一模一样,而那正是这个帽存在的理由)。HTTP 面用同一条规则,两个面因此对「什么读得到」永不分歧。
+            sendError(res, 413, "request.payload_too_large", `document is ${bytes} bytes, over the ${SHARED_MEMORY_READ_CAP_BYTES}-byte shared-store read cap`, { bytes, capBytes: SHARED_MEMORY_READ_CAP_BYTES });
+            return;
+        }
+        sendJson(res, 200, { store: storeId, path, content: doc.content, bytes, ...(doc.updatedAt !== undefined ? { updatedAt: doc.updatedAt } : {}) });
+        return;
+    }
+    miss.fell = true;
+}
+//# sourceMappingURL=shared-memory.js.map

package/dist/http/routes/trace-usage.js

@@ -1,10 +1,26 @@
+import { buildToolResultRef } from "@sema-agent/core";
 import { projectEvents, taskSummary, mapTraceEvent } from "../../trace/project.js";
 import { projectArtifacts } from "../../trace/artifacts.js";
 import { usageSummary, usageSeries, usageBreakdown } from "../../usage-analytics.js";
 import { sleep } from "../sse-log.js";
 import { sendJson, sendError, sseHeaders, SSE_MAX_STREAM_MS, SSE_HEARTBEAT_IDLE_MS } from "../send.js";
 import { gatedPrincipal } from "../principal-gate.js";
-const TRACE_RE = /^\/v1\/tasks(?:\/([^/]+)(\/turns|\/stream|\/artifacts))?$/;
+// [3321] tool-results 读面**共用这一段守卫**([3318] 的字面承诺):新 sub 进的是同一个 `sub` 捕获组,
+// 于是下方 fleetWide / gateOwner / per-id owner-404 三道门原样罩住它,不存在第二套门可以漂。
+// ⚠️ 「both-or-neither」结构不可破:`:id` 与 `sub` 同在一个可选组里,所以 TRACE_RE 从不匹配裸
+// `/v1/tasks/<seg>` —— 那正是 `POST /v1/tasks/stream` 不被本读面遮蔽的原因(见下方 source-summary 注)。
+// 新臂写成 `sub` 的一个 alternation 分支(而不是新开捕获组),组号与既有两个捕获保持逐字不变。
+const TRACE_RE = /^\/v1\/tasks(?:\/([^/]+)(\/turns|\/stream|\/artifacts|\/tool-results\/[^/]+))?$/;
+/** tool-results 读面的 sub 前缀(路由判别 + 段切分单源)。 */
+const TOOL_RESULTS_SUB = "/tool-results/";
+/** `limit` 的 server 权威上限(chars)。缺席 = 不传给 store,用 store 自己的默认;超上限 = 400(不静默夹取:
+ *  夹取会让「我要 1M」与「我要 256K」返回同一段内容,调用方无从知道自己被截了)。 */
+const TOOL_RESULT_LIMIT_CAP = 262_144;
+/** `offset` 的上限 = **最窄后端**能表达的值(codex 复审 R1 medium,已核真)。PG 那半边发的是
+ *  `SUBSTRING(content FROM $1::int …)` 且绑的是 `offset + 1`(`plugins/tool-result-store-sql.ts`),
+ *  于是 `offset = 2147483647` 过得了「非负整数」这一关,却在库里变成 `2147483648::int` ⇒ 范围错 ⇒ 500。
+ *  「坏输入回 400」是本面的承诺,承诺不能挑后端兑现,所以上限按 int32 - 1 收(留出 +1 的余量)。 */
+const TOOL_RESULT_OFFSET_CAP = 2_147_483_646;
 export async function handleTraceUsage(req, res, url, ctx) {
     const miss = { fell: false };
     await handleTraceUsageBody(req, res, url, ctx, miss);
@@ -14,7 +30,7 @@ export async function handleTraceUsage(req, res, url, ctx) {
  *  = 「本域已应答」;走到函数尾才是「没匹配上」。跨域的东西一律在首行解构出来。 */
 async function handleTraceUsageBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
-    const { isFleetWide } = ctx.helpers;
+    const { isFleetWide, safeDecode } = ctx.helpers;
     // Task Trace API (S1, read-only): GET /v1/tasks[/:id/turns|/stream]. Authorized by EITHER the full authToken
     // OR a read-only traceToken (sema-registry pulls traces fleet-wide with one read-only token). Handled BEFORE
     // the global gate (like /metrics) so a traceToken-only caller isn't 401'd.
@@ -61,14 +77,19 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
         }
         const query = new URL(req.url ?? "", "http://x").searchParams;
         const taskId = traceMatch[1];
-        const sub = traceMatch[2]; // undefined (list) | "/turns" | "/stream" | "/artifacts"
+        const sub = traceMatch[2]; // undefined (list) | "/turns" | "/stream" | "/artifacts" | "/tool-results/<ref>"
         // per-id owner gate for the principal path (404 for a non-owner — no existence oracle, parity with runOwnerOk).
+        // 🔴 该行**只在 principal 路径**被取(fleet 路径按设计不做 per-id 归属判定)——tool-results 面还要用
+        // `run.sessionId` 算 ref 前缀,所以这里把取到的行留住(`ownedRun`),fleet 路径由该面自己补一次取行:
+        // 少了那次取行,fleet caller 就能拿任意 taskId 配任意 ref 读走**别的 session** 的产物。
+        let ownedRun;
         if (taskId && gateOwner !== null) {
             const run = await deps.runStore.getRun(taskId);
             if (!run || (run.owner !== null && run.owner !== gateOwner)) {
                 sendError(res, 404, "not_found.run", "task not found");
                 return;
             }
+            ownedRun = run;
         }
         if (!taskId)
             await handleTaskList(res, deps.runStore, query, gateOwner); // gateOwner (when set) forces the owner filter
@@ -78,6 +99,9 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
             await streamTaskTrace(req, res, deps.runStore, taskId, deps.config.runStaleSec * 1000);
         else if (sub === "/artifacts")
             await handleTaskArtifacts(res, deps.runStore, taskId);
+        else if (sub?.startsWith(TOOL_RESULTS_SUB)) {
+            await handleToolResult(res, deps.toolResultStore, deps.runStore, taskId, ownedRun, safeDecode(sub.slice(TOOL_RESULTS_SUB.length)), query);
+        }
         else
             sendError(res, 404, "not_found.route", "not found");
         return;
@@ -202,6 +226,118 @@ async function handleTaskArtifacts(res, runStore, taskId) {
     const events = await runStore.getEvents(taskId, 0);
     sendJson(res, 200, { artifacts: projectArtifacts(events, { taskId, jobId: run.jobId }) });
 }
+/**
+ * GET /v1/tasks/:id/tool-results/:ref?offset&limit —— core `ToolResultStore.get` 的 wire 镜像([3321])。
+ *
+ * 三件事,顺序本身就是契约:
+ *
+ * ① **query 先判**。坏 offset/limit ⇒ 400,且这一判**先于**任何 ref/归属/store 在场性判定 —— 否则
+ *    「坏 query + 已知 ref = 400」而「坏 query + 未知 ref = 404」,状态码之差立刻成了存在性 oracle。
+ *    query 的合法性只取决于 query 自身,与调用方看不看得见这个 ref 无关,所以先判是安全的。
+ *
+ * ② **归属绑定 = 对本 task 的耐久日志做精确成员判定**,不解析 ref、不复制段转义规则。
+ *
+ *    先说为什么**不是**前缀判定([3321]② 的字面形、[3322] 的指定形):core 的 ref 形是
+ *    `tr_<seg(session)>_<seg(toolCallId)>`,而 `_` 在两段里都合法 ⇒ session `team` 的前缀 `tr_team_`
+ *    同样命中 session `team_blue` 的 ref(`tr_team_blue_toolu_x`)。本仓的 sessionId 是**调用方自选的
+ *    任意 ≤64 字符串**(`http/server.ts` 的 submit 面只查长度,刻意宽松),所以租户 A 可以把自己的
+ *    sessionId 取成租户 B 的前缀,拿自己的 taskId 配 B 的 ref 读走 B 的产物(codex 复审 R1 high,已核真)。
+ *    这在字符串层面**无解**:把余段当 toolCallId 重铸一遍会逐字相等(拼接本身有歧义),而按「更长的
+ *    session 是否存在」去探,既堵不住折成 base+sha 的 sessionId(候选串 ≠ 真 id),又反手造出一个新的
+ *    跨租户**拒绝**面(别人注册一个 `<你的 session>_toolu` 就能让你自己的 ref 永远 404)——R2 复审两条
+ *    中标,已撤回该启发式。
+ *
+ *    改判据:ref **必须由本 task 自己的耐久事件日志作证**。日志里每条 tool_start/tool_end 都带
+ *    `toolCallId`(`trace/project.ts` 的 toolStartEventData / toolEndEventData 是唯一铸造点),用 core
+ *    的**同一个** `buildToolResultRef` 把它们铸成 ref 集合,再要求 `ref` 是其中一员 —— 精确相等,
+ *    零解析、零转义规则复制,歧义面结构上不存在(A 的 taskId 只作证 A 自己的 toolCallId)。
+ *    辖域(诚实写明,也正是本路由的语义):本面服务的是**这条 task 的 trace 里看得见的那些产物** ——
+ *    trace 的 tool-result 块与本判据读的是同一份日志,所以「trace 上看得见 ⇒ 这里读得到」成立;
+ *    同 session 里**别的 task** 的 ref(或日志已过保留窗被逐出的)按 404 同形拒,请到那条 task 上读。
+ *
+ *    ⚠️ 两处**已知残余**,都要 core 侧动刀才能消,写在明处而不是让下一个人自己撞(codex 复审 R3):
+ *
+ *    (a) **覆盖面**:core 除了「按工具调用 id 卸载」这条主路,还从**合成 id** 铸 ref ——
+ *        `task-registry-monitor` 的 `<handle>_<stream>_seg<n>`、`task-registry-agent` 的 `<handle>_c<n>`、
+ *        `runner/compaction-call-options` 的 `<toolCallId>_s<sha>`、budget 的 `idx<k>`。这些 id **不进**
+ *        耐久事件日志(日志记的是外层调用 id),所以那几类 ref 在本面一律 404 同形拒。
+ *        方向明确:**不**在本仓照抄那几条命名规则去反推(复制上游规则 = 两处各自漂,宪法禁),
+ *        真解是 core 在写入时带上 (session/task) 出处、或给出 core 属主的精确成员判定。
+ *
+ *    (b) **注入性**:`buildToolResultRef` 对 `(session, toolCallId)` **不是单射**(`_` 两段都合法):
+ *        `("team","blue_toolu_1")` 与 `("team_blue","toolu_1")` 铸出同一枚 ref。所以「本 task 日志作证过
+ *        一个恰好长成 `<受害 session 尾巴>_<受害 toolCallId>` 的 toolCallId」时,判据仍会放行。
+ *        与被撤掉的前缀形的差别是**门槛**:前缀形只要知道 ref 就能读,本形还要求攻击者能让**模型网关**
+ *        铸出那一枚精确的 toolCallId(provider 铸,本服务不控也不产)。同样只有 core 换成单射编码才真消。
+ *        这里**不留特征化测试**去钉这条通路 —— 把缺陷钉成契约是另一种病。
+ *
+ * ③ **同形 404**(unknown ref / 未获本 task 日志作证 / 本部署没有 durable store)。任何可区分的响应都是
+ *    缺陷:前两者之差会告诉调用方「这枚 ref 存在,只是不是你的」;第三者若回 501 则会把部署形告诉一个
+ *    连自己的 ref 都读不到的 caller。文案恒定且**不回显 ref**(回显=把输入原样反射进错误面)。
+ *    残余面(诚实写明):响应字节同形,**时序**并不同形 —— 三条臂到达的后端调用数不同。要抹平时序得让
+ *    每条臂都跑满全部后端调用,那是另一档代价/收益裁定,不在本批;本批的判据是响应本身不给 oracle。
+ */
+async function handleToolResult(res, store, runStore, taskId, ownedRun, 
+/** 已过 `safeDecode` 的 ref;`null` = %-序列坏(客户端错,但同形 404 —— 它同样不该成为一条可区分的信道)。
+ *  解码用调用点传下来的 helper 而不是本地 try/catch:那条规则(坏序列 ⇒ null,绝不 500)在本仓只有
+ *  `safeDecode` 一个属主,复制一份等于把它变成两个。 */
+ref, query) {
+    // ① query 校验(先于一切存在性判定 —— 见头注)。非负十进制整数,`Number()` 的宽松形(空串/前后空白/
+    //    "1e3"/"0x10"/"1.5")一律不认:宽松解析会让两个不同的请求串静默映射到同一段内容。
+    const intParam = (name, cap) => {
+        const raw = query.get(name);
+        if (raw === null)
+            return undefined; // 缺席 = 用 store 默认
+        if (!/^\d+$/.test(raw))
+            return "bad";
+        const n = Number(raw);
+        if (!Number.isSafeInteger(n))
+            return "bad";
+        if (cap !== undefined && n > cap)
+            return "bad";
+        return n;
+    };
+    const offset = intParam("offset", TOOL_RESULT_OFFSET_CAP);
+    if (offset === "bad") {
+        sendError(res, 400, "request.query_invalid", "offset must be a non-negative integer of at most 2147483646");
+        return;
+    }
+    const limit = intParam("limit", TOOL_RESULT_LIMIT_CAP);
+    if (limit === "bad") {
+        sendError(res, 400, "request.query_invalid", "limit must be a non-negative integer of at most 262144");
+        return;
+    }
+    // ③ 同形 404 的**唯一**下发点:每条臂都必须走这里,不许任何一条自己写一句(文案分家=oracle 复活)。
+    const notFound = () => sendError(res, 404, "not_found.tool_result", "tool result not found");
+    if (ref === null)
+        return notFound(); // 坏 %-序列(见参数注)
+    // fleet 路径没做 per-id 取行(见调用点注),这里补齐 —— 归属绑定要 run.sessionId,没有行就没有绑定面。
+    const run = ownedRun ?? (await runStore.getRun(taskId));
+    if (!run)
+        return notFound();
+    // ② 精确成员判定(见头注):本 task 耐久日志作证过的 toolCallId,经 core 同一个铸造点变成 ref 集合。
+    // 成本口径:整份日志一读一扫,与同域的 `/turns`、`/artifacts` 同款(不是本面引入的新量级);分页读会
+    // 逐页重扫 —— 真消要一张 (task, ref) 出处索引,与上面 (a) 是同一件 core/store 侧的活。
+    const events = await runStore.getEvents(taskId, 0);
+    let attested = false;
+    for (const ev of events) {
+        // 取键姿势与同域的 `trace/artifacts.ts` 逐字同款(同一份日志、同一个字段,读法不该有第二种)。
+        const { toolCallId: id } = (ev.data ?? {});
+        // 逐条比对而不是先建全集:命中即停,长日志上不必把整份集合物化。
+        if (typeof id === "string" && id.length > 0 && buildToolResultRef(run.sessionId, id) === ref) {
+            attested = true;
+            break;
+        }
+    }
+    if (!attested)
+        return notFound();
+    if (!store)
+        return notFound(); // durable store 缺席:404 同形,不 501(不泄露部署形)
+    const slice = await store.get(ref, { ...(offset !== undefined ? { offset } : {}), ...(limit !== undefined ? { limit } : {}) });
+    if (!slice)
+        return notFound();
+    sendJson(res, 200, { content: slice.content, offset: slice.offset, totalChars: slice.totalChars });
+}
 async function handleTaskTurns(res, runStore, taskId, query) {
     const run = await runStore.getRun(taskId);
     if (!run) {

package/dist/http/server.d.ts

@@ -5,7 +5,8 @@ import type { TaskRequestBody } from "./wire-types.js";
 import type { ServiceConfig } from "../config-types.js";
 import { type RestartSignal, type SessionMirrorRuling } from "../config-center/facade.js";
 import { type OwnerAwareSessionStore } from "../security.js";
-import type { RunStore, ImageIndex, ImageBake, CheckpointStoreFull, ResumeAnchorStore, ApprovalExemptionStore, ServiceSessionPolicyStore, ServiceFileSnapshotStore, StoreBackend } from "../plugins/store-backend.js";
+import type { RunStore, ImageIndex, ImageBake, CheckpointStoreFull, ResumeAnchorStore, ApprovalExemptionStore, ServiceSessionPolicyStore, ServiceFileSnapshotStore, ToolResultStoreFull, StoreBackend } from "../plugins/store-backend.js";
+import type { RuleConsentLane } from "../rules-consent.js";
 import { type MemorySyncRequest, type MemorySyncResponse } from "../memory-sync.js";
 import type { TaskAttachmentStore } from "../plugins/task-attachment-store.js";
 import type { LeaderEndpoint } from "../leader/endpoint.js";
@@ -101,6 +102,13 @@ export interface ServiceStoreDeps {
     /** E6 durable SessionPolicyStore (operator-tightened per-session tool rules). Enables PUT/GET /v1/sessions/:id/policy
      *  when present; core reads the rules at prepare-time (subtract-only) via RunnerDeps.sessionPolicyStore (wired separately). */
     sessionPolicyStore?: ServiceSessionPolicyStore;
+    /** [3321] tool-results 读面([3315] 请求,core [3322] `buildToolResultRef` 到货):`GET /v1/tasks/:id/
+     *  tool-results/:ref` 的数据源 —— 与 RunnerDeps 侧的 offload 店**同实例**(main.ts 的 `toolResultStore`,
+     *  即「durable 后端在场」那一只;无 backend 部署里 Runner 用的内存兜底 `runnerOffloadStore` **不接**这里)。
+     *  🔴 缺席 ⇒ 路由回 404 而不是 501:501 会向一个无权 caller 泄露「这台机器配没配 durable 店」的部署形,
+     *  与 unknown-ref / 归属不符两臂**同形** 404 才是防 oracle 的收口([3321] 的「另定」项按防 oracle 收紧)。
+     *  这是本组「absent ⇒ 501 诚实缺席」通例的**唯一具名例外**,例外理由即上一句。 */
+    toolResultStore?: ToolResultStoreFull;
     /** E19 rewind-files snapshot store. Present ⇒ the `rewindFiles` capability is advertised; core uses it via
      *  RunnerDeps.fileSnapshotStore (snapshot per turn + restore on resumeAt, ANY env since gate-split 1.134.0). Also the 2c artifact store. */
     fileSnapshotStore?: ServiceFileSnapshotStore;
@@ -156,6 +164,11 @@ export interface ServiceStoreDeps {
      *  `backend.session()`/`fileSnapshot()`/`sessionPolicy()`/`resumeAnchor()` must come from ONE backend). Present
      *  whenever a durable backend (tidb/pg/local) is; absent on the env-only/no-backend worker (the routes 501). */
     backend?: StoreBackend;
+    /** #154 车二:**持久化权限规则的同意车道**(core design/179 三步协议的宿主半场)。
+     *  在场 ⇔ 规则店真装配(`backend.permissionRule()` 有值)⇒ `POST /v1/rules/cc-import/{prepare,redeem}`
+     *  可用、ask 帧才投 `ruleSuggestions`;缺席 ⇒ 两口 501、帧上零候选(发一格无处可兑的「不再询问」
+     *  = wire 谎言,比缺席更坏)。 */
+    ruleConsent?: RuleConsentLane;
 }
 /** **进程内活体协调面**(本副本 only,重启即空):HITL 协调器、可 steer 句柄注册表、事件总线、
  *  收件箱。跨副本一律不可见——每个消费点都按「不在本副本 ⇒ 409/降级」写,不假装全局。 */
@@ -281,6 +294,11 @@ export interface ServiceSeamDeps {
      *  读面要该 scope 在授权表里、写面另要条目 `write === true`。缺席=本部署没有目录源 ⇒ `org:` 键
      *  逐字保持 operator-only(收编前行为),绝不因目录不接线而放宽。 */
     orgMemoryDirectory?: import("../org-memory-admission.js").OrgMemoryDirectory;
+    /** design/177 —— org 共享记忆库的供给面(与 core `RunnerDeps.sharedMemoryStores` **同一个实例**:
+     *  HTTP 只读面看到的库集合按定义等于模型面看到的那一份,两面不可能分歧)。
+     *  🔴 缺席 ⇒ `/v1/shared-memory/*` 整域不挂载(诚实缺席);挂载还另要 {@link orgMemoryDirectory}
+     *  在场 —— 没有成员性判据的读面只能全放或全拒,两个都比「这个面不存在」差。 */
+    sharedMemoryStore?: import("@sema-agent/core").SharedMemoryStoreProvider;
     /** WEB-SETUP-RECON 附B — org sessionMirror 治理态的 SERVICE 半场 = **观测面(audit),非执法面**。
      *  裁定 (c):「该镜像而未镜像」发生在数据产生端(壳)——本 server 是镜像**目标**,只看得见到达的 push;
      *  没到达的会话对 server 不存在(无客户端会话清单、无心跳契约),required 锁的真执法只能在壳(CC
@@ -316,8 +334,10 @@ export interface ServiceSeamDeps {
     parkedKnownAgentTypes?: ReadonlySet<string>;
     /** [1596]/[1597] 跨进程父约束重供:decide 腿按部署配置重建 host 任务的同语义父策略链(exempt 锚=
      *  row.rootSessionId),经 core 1.396 的 `parkedResume.inheritedGate` 席位透传——缺席时重启后带
-     *  requiresParentConstraint 的 parked checkpoint 恒被 core pre-CAS 门诚实拒(不可赎回)。 */
-    parkedReviveInheritedGate?: (row: import("@sema-agent/core").BackgroundAgentRecord) => unknown;
+     *  requiresParentConstraint 的 parked checkpoint 恒被 core pre-CAS 门诚实拒(不可赎回)。
+     *  ⚠️ **async**(A-010.1):重建要按本行 principal 现解 entitlement——理由在 parked-decide.ts 的
+     *  `rebuildInheritedGate` 头注。 */
+    parkedReviveInheritedGate?: (row: import("@sema-agent/core").BackgroundAgentRecord) => Promise<unknown>;
 }
 /** **可观测面**:日志/指标/累加器。全体 fail-open——观测失败绝不改变业务面行为。 */
 export interface ServiceObservabilityDeps {