@sema-agent/server 7.9.0 → 7.11.0

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

package/dist/http/server.js

@@ -30,7 +30,10 @@ import { clampVerifyRounds, verifyRoundsFromBody } from "./verify-rounds.js"; //
 import { handleCapabilities } from "./routes/capabilities.js";
 import { handleObservability } from "./routes/observability.js";
 import { handleDiagnostics } from "./routes/diagnostics.js";
+import { handleAdoption } from "./routes/adoption.js";
 import { handleMemoryPolicy } from "./routes/memory-policy.js";
+import { handleSharedMemory } from "./routes/shared-memory.js";
+import { handleRules } from "./routes/rules.js";
 import { handleSessionsList } from "./routes/sessions-list.js";
 import { handleSessions, createSessionsLocal } from "./routes/sessions.js";
 import { handleSessionSync, createSessionSyncLocal } from "./routes/session-sync.js";
@@ -147,7 +150,10 @@ const ROUTE_DOMAINS = [
     handleImages,
     handleApprovalsAssistant,
     handleObservability,
+    handleAdoption,
     handleMemoryPolicy,
+    handleSharedMemory,
+    handleRules,
     handleSessionsList,
     handleSessions,
     handleSessionSync,
@@ -598,9 +604,20 @@ export function createHttpServer(rawDeps) {
         // #154 件三:装配自证只读面(routes/diagnostics.ts):GET /v1/diagnostics/wiring(operator-only)。
         if (await handleDiagnostics(req, res, url, ctx))
             return;
+        // design/183 §4.3:收编面(routes/adoption.ts,operator lane;POST /v1/adoption + GET /v1/adoption/:id)。
+        if (await handleAdoption(req, res, url, ctx))
+            return;
         // design/158 A9:memory 导出/同步 + /v1/policy 只读面(routes/memory-policy.ts)。
         if (await handleMemoryPolicy(req, res, url, ctx))
             return;
+        // #154 车二:CC settings 导入两口(lane=principal,billable=false)。
+        if (await handleRules(req, res, url, ctx))
+            return;
+        // design/177 共享记忆库只读面(routes/shared-memory.ts)。🔴 域头的合取式**就是**挂载条件:供给面
+        // 与 org 折叠面双在场才有这个域,缺一个则请求落到本函数尾的全局 404(诚实缺席,不是 501)。
+        // `capabilities.sharedMemory` 读同一个合取式 ——「说 yes ⟺ 面真能用」因此是结构性的,不靠人盯。
+        if (deps.sharedMemoryStore && deps.orgMemoryDirectory && (await handleSharedMemory(req, res, url, ctx)))
+            return;
         // design/158 A9:会话/发件链接列表面(routes/sessions-list.ts)。
         if (await handleSessionsList(req, res, url, ctx))
             return;
@@ -1406,8 +1423,8 @@ export function createHttpServer(rawDeps) {
         // escaping HttpError here was (a) attributed to the OPERATOR's /decide request as a bare 400/403 — undiagnosable
         // from that contract — and (b) swallowed by the D-D SLA deny-sweep's catch, silently failing EVERY tick. Fold it
         // into a typed 409 result instead: the operator sees "this parked task is blocked by a policy change" (retry
-        // after the policy is restored, or let terminal_at abort it); the sweep skips the row this tick (retried next
-        // tick, terminal_at backstop — its documented per-call-failure semantics).
+        // after the policy is restored, or let terminal_at_ms abort it); the sweep skips the row this tick (retried next
+        // tick, terminal_at_ms backstop — its documented per-call-failure semantics).
         let spec;
         try {
             spec = await deps.resolveSpec({ ...ctx.body, resumeAt: undefined }, req, auth);
@@ -2110,6 +2127,13 @@ export function createHttpServer(rawDeps) {
                     e.code === "checkpoint.reopened_concurrently" ||
                     e.code === "resume.parent_constraint_missing" || // 历史复审轴A #4(1.254):core 新增两码同为
                     e.code === "resume.parent_constraint_mismatch" || // PRE-CAS(checkpoint 保持 pending)——按本块 doctrine 归 retriable;当前 /decide 面只 resume 顶层 checkpoint 应不可达,前瞻补齐防嵌套 resume 面开放时踩中
+                    // core 5.22.0(BREAKING「编辑复裁前移 pre-CAS」)闭集加员:审批人**改写**入参时,继承祖先链
+                    // 的冻结投影先静态复裁 —— 判 deny ⇒ constraint_rejected;链上有 opaque 层/声明 live remainder
+                    // ⇒ constraint_unprojectable。两者与上面两码同族:PRE-CAS、checkpoint 留 pending 且**同 token
+                    // 仍可再决**(core 明写 fresh-redecision 语义:照原样批 / deny / 改别的都还点得动)。归 terminal
+                    // 会释放 task_active 并孤儿化那条仍 pending 的卡 —— 一张还能点的卡当场变死件。
+                    e.code === "resume.constraint_rejected" ||
+                    e.code === "resume.constraint_unprojectable" ||
                     e.code.startsWith("wake."); // design/144:wake 拒绝(gate_pending/nothing_to_deliver)全是 PRE-CAS,checkpoint 保持 pending——驱 terminal 会孤儿化仍在等的 park
                 if (claimedRow && taskId && deps.runStore) {
                     // Re-park on the SAME gate family the outcome targeted: a plan_review retry must re-park `needs_review`
@@ -2651,7 +2675,7 @@ export function createHttpServer(rawDeps) {
      * (graceful; vs the abort the reaper's expire() gives resource_limit/needs_review). Reuses resumeCheckpoint,
      * so the markResuming CAS makes it idempotent across replicas (one replica wins each resume) and the parked
      * run row is driven correctly. A per-call failure (e.g. a redeployed scenario) is swallowed → the row stays
-     * pending and is retried next tick, with the terminal_at backstop as the eventual abort if the deny never
+     * pending and is retried next tick, with the terminal_at_ms backstop as the eventual abort if the deny never
      * succeeds. Bounded per tick by the store query's LIMIT. Wired into main.ts's reaper.
      */
     async function denyExpiredApprovals(now) {
@@ -2659,7 +2683,7 @@ export function createHttpServer(rawDeps) {
         if (!cs)
             return;
         const expired = await cs.listExpiredApprovalGates(now).catch(() => []);
-        // [1591] 候裁③ 静默臂:parked 后台子代的过期 cp 不走 sweep 的重活赎回(deadline→terminal_at 窗内
+        // [1591] 候裁③ 静默臂:parked 后台子代的过期 cp 不走 sweep 的重活赎回(deadline→terminal_at_ms 窗内
         // 每行每 tick 一条 warn 的噪声源)——其收割属 reaper 的 expire+reconcileParkedAgents 车道。判别在
         // resume 尝试之前做(省掉注定 409 的整条 ctx/resolveSpec 重建尝试;代价=每过期行两次店读,过期集
         // 本就被店查询 LIMIT 界住);命中聚合为单条 info 留痕。判别自身故障 ⇒ 按非 parked 处理(保留 warn,
@@ -2684,7 +2708,7 @@ export function createHttpServer(rawDeps) {
         for (const { sessionId } of expired) {
             // 对抗评审 2026-07-11: log the swallow — a per-tick failure retried forever (e.g. a policy change now folded
             // into a 409 by resumeCheckpoint, or a redeployed scenario) was fully silent; the row sat pending to its
-            // terminal_at with zero operator-visible signal. Behavior unchanged (skip + retry next tick), now diagnosable.
+            // terminal_at_ms with zero operator-visible signal. Behavior unchanged (skip + retry next tick), now diagnosable.
             if (await isParkedOwned(sessionId)) {
                 parkedSkipped += 1;
                 continue;
@@ -2770,12 +2794,19 @@ const ROUTE_LABEL_PATTERNS = [
     // #151 车4:durable 回决口。必须排在 `/v1/tasks/:id/$sub` **之前**?—— 不必(那条只认三个字面动词),
     // 但仍按「具体先于泛化」的表序纪律放在它前面,免得日后 $sub 放宽成 `[^/]+` 时静默吞掉本条。
     [/^\/v1\/tasks\/[^/]+\/asks\/[^/]+\/decision$/, "/v1/tasks/:id/asks/:askId/decision"],
+    // [3321] tool-results 读面:同样排在 `/v1/tasks/:id/$sub` 之前(具体先于泛化的表序纪律;$sub 那条
+    // 只认三个字面动词,今日不冲突,但它日放宽成 `[^/]+` 时本条不会被静默吞掉)。
+    [/^\/v1\/tasks\/[^/]+\/tool-results\/[^/]+$/, "/v1/tasks/:id/tool-results/:ref"],
     [/^\/v1\/tasks\/[^/]+\/(turns|stream|artifacts)$/, "/v1/tasks/:id/$sub"],
     [/^\/v1\/leader\/[^/]+$/, "/v1/leader/:id"],
     [/^\/v1\/attachments\/[^/]+$/, "/v1/attachments/:id"],
     [/^\/v1\/capabilities\/scenarios\/[^/]+$/, "/v1/capabilities/scenarios/:name"],
+    [/^\/v1\/adoption\/[^/]+$/, "/v1/adoption/:id"],
     [/^\/v1\/memory\/sync\/[^/]+$/, "/v1/memory/sync/:scope"],
     [/^\/v1\/usage\/(summary|series|breakdown)$/, "/v1/usage/$sub"],
+    // design/177 共享记忆库只读面。两条各自成桶(列举是窗口读、正文是单文档读,延迟分布不同族)。
+    [/^\/v1\/shared-memory\/stores\/[^/]+\/documents$/, "/v1/shared-memory/stores/:store/documents"],
+    [/^\/v1\/shared-memory\/stores\/[^/]+\/document$/, "/v1/shared-memory/stores/:store/document"],
 ];
 const ROUTE_LABEL_LITERALS = new Set([
     "/health", "/metrics", "/metrics/summary", "/metrics/plan-cache",
@@ -2789,8 +2820,19 @@ const ROUTE_LABEL_LITERALS = new Set([
     // 名册门的枚举器当时只认 `url === …`,整条路由对门隐形(枚举器已一并补上)。
     "/v1/fleet/stream",
     "/v1/memory/export", "/v1/sendfile-links",
+    // design/177:共享记忆库清单面(具名两条走上面的模式表)。
+    "/v1/shared-memory/stores",
     // #154:装配自证读面(operator-only)。低频但**每次都在排障现场被打**,落进 `other` 桶等于排障时看不见。
     "/v1/diagnostics/wiring",
+    // design/183:收编发起口(operator-only,一次性部署级动作)。低频、但它的 duration 与失败率是
+    // 迁移现场唯一的机器信号,落进 `other` 桶就看不见了。
+    "/v1/adoption",
+    // #154 车二:CC settings 导入两口。字面量(无 id 段)⇒ 进 LITERALS 表而不是模式表。
+    // 🔴 写**字面量**而不是引 `RULES_CC_IMPORT_*_PATH` 常量:名册门与 billable 申明门都是**扫源码文本**
+    // 的(它们正则抓本表里的双引号词),引常量会让两条新路由对两道门隐形 —— 那不是「过了门」,是绕过门。
+    // ⚠️ 本段注释里也不许出现方括号后紧跟右圆括号的字符对:billable 门的表捕获正则是**非贪婪**的,
+    //    那两个字符会让它在这里提前收尾,后面的字面量整段落在门的视野外(写这条注时真的踩到过)。
+    "/v1/rules/cc-import/prepare", "/v1/rules/cc-import/redeem",
 ]);
 /** Stable, low-cardinality route label for metrics/logs (ids collapsed to `:id`).
  *  [#104] 字面量**先于**模式:此前模式先查,五条精确路由被形状桶吞掉(`/v1/approvals/stream`

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export { buildSessionAudit, type SessionAudit } from "./audit.js";
 export { createLogger, type Logger, type LogLevel } from "./observability/logger.js";
 export { Metrics, createMetrics, type Labels } from "./observability/metrics.js";
 export { RateLimiter, type RateDecision } from "./observability/rate-limit.js";
-export { GiteaClient, repoToolsFor, parseRepo, type RepoCoords } from "./capabilities/repo-tools.js";
+export { GiteaClient, GitHubClient, createRepoClient, GIT_API_KINDS, isGitApiKind, repoToolsFor, parseRepo, type GitApiKind, type RepoCoords, type RepoReadClient } from "./capabilities/repo-tools.js";
 export { nowTool } from "./capabilities/builtin-tools.js";
 export { createCouncilTool } from "./capabilities/code-review-council.js";
 export { loadSkills, skillsForScenario, type LoadedSkill } from "./capabilities/skills.js";

package/dist/index.js

@@ -17,7 +17,7 @@ export { buildSessionAudit } from "./audit.js";
 export { createLogger } from "./observability/logger.js";
 export { Metrics, createMetrics } from "./observability/metrics.js";
 export { RateLimiter } from "./observability/rate-limit.js";
-export { GiteaClient, repoToolsFor, parseRepo } from "./capabilities/repo-tools.js";
+export { GiteaClient, GitHubClient, createRepoClient, GIT_API_KINDS, isGitApiKind, repoToolsFor, parseRepo } from "./capabilities/repo-tools.js";
 export { nowTool } from "./capabilities/builtin-tools.js";
 export { createCouncilTool } from "./capabilities/code-review-council.js";
 export { loadSkills, skillsForScenario } from "./capabilities/skills.js";