@sema-agent/server 7.51.0 → 7.52.1

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

@@ -1,6 +1,7 @@
 import { formatUserScope } from "@sema-agent/core";
 import { parseMemorySyncRequest } from "../../memory-sync.js";
 import { sendJson, sendError } from "../send.js";
+import { buildOriginFence, readOriginAware } from "../../memory-origin-fence.js";
 import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
 const ORG_PREFIX = "org:";
 export const MEMORY_EXPORT_MAX_LIMIT = 500;
@@ -101,9 +102,11 @@ async function handleMemoryPolicyBody(req, res, url, ctx, miss) {
             return;
         }
         try {
-            const entries = await deps.memoryExport(scope);
+            const fence = buildOriginFence(await deps.memoryExport(scope), readOriginAware(new URL(req.url ?? "", "http://x").searchParams));
+            const entries = fence.entries;
+            const withheld = fence.withheldOriginTagged !== undefined ? { withheldOriginTagged: fence.withheldOriginTagged } : {};
             if (limitRaw === null) {
-                sendJson(res, 200, { scope, exportedAt: new Date().toISOString(), entries });
+                sendJson(res, 200, { scope, exportedAt: new Date().toISOString(), entries, ...withheld });
                 return;
             }
             const sorted = [...entries].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
@@ -116,6 +119,7 @@ async function handleMemoryPolicyBody(req, res, url, ctx, miss) {
                 exportedAt: new Date().toISOString(),
                 entries: page,
                 ...(hasMore ? { truncated: true, nextBefore: encodeExportCursor({ id: last.id }) } : {}),
+                ...withheld,
             });
         }
         catch (err) {

package/dist/http/routes/retention-ops.d.ts

@@ -24,7 +24,7 @@
  *    `checkAdoptionWidths` 同一条判据):一次静默截断会让 hold 落在一个**别的**域上。
  *
  * ── 审计行为什么放置/解除都要写 ────────────────────────────────────────────────────────────
- * hold 本身就是一次留存治理动作,不留痕的 hold 是审计漏洞(设计稿 §5 逐字)。行**每次成功调用都写**,
+ * hold 本身就是一次留存治理动作,不留痕的 hold 是审计缺陷(设计稿 §5 逐字)。行**每次成功调用都写**,
  * 而不是"只在状态真的翻转时写":审计表记的是**发生过的动作**(operator 在某时刻按了这个按钮),不是
  * 状态机的边。一次对已冻结域的重复 PUT 同样是一次需要留痕的操作。
  *

package/dist/http/routes/rules.d.ts

@@ -11,11 +11,11 @@
  * 因此**导入两口**只认已验明的 principal,连 `explicitOperatorOk` 的旁路都不给:一个 operator 想给
  * 自己导规则,用他自己的 principal 走同一条路即可(那时他就是租户)。
  *
- * 🔴 **撤销面两口多一条 operator 越权域,而这不是上面那句话的例外,是它的对偶**(design/203 §2 设计题
+ * 🔴 **撤销面两口多一条 operator 超范围域,而这不是上面那句话的例外,是它的对偶**(design/203 §2 设计题
  * 一裁定):`?principal=` / body 里的 `principal` 让 operator 读**或收回**任一租户的规则。方向决定授权:
  * 收回是**收紧**(core 的 `removePersistedRule` 头注逐字:「a host may narrow on a user's behalf, it may
  * not widen」),而多租户管理员能回收权限正是撤销面的本义。读那一半同样只开给 operator ——
- * 规则文本里含命令样式,跨 principal 读是信息面泄露,所以**不开第三方 principal 相互读**。
+ * 规则文本里含命令样式,跨 principal 读是信息面外泄,所以**不开第三方 principal 相互读**。
  * 判据用 `explicitOperatorOk`(空名单 = 全拒),**绝不**从 service token 推断身份:一个共享的部署凭证
  * 不是一个人。
  *
@@ -29,6 +29,9 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx } from "../route-ctx.js";
 export declare const RULES_CC_IMPORT_PREPARE_PATH = "/v1/rules/cc-import/prepare";
 export declare const RULES_CC_IMPORT_REDEEM_PATH = "/v1/rules/cc-import/redeem";
+/** #265 A7:File 规则直通票口两条(与 cc-import 两口并列,票语义分家见 `rules-consent.ts` 的 A7 段)。 */
+export declare const RULES_LOCAL_IMPORT_PREPARE_PATH = "/v1/rules/local-import/prepare";
+export declare const RULES_LOCAL_IMPORT_REDEEM_PATH = "/v1/rules/local-import/redeem";
 /** 撤销面两口共用的字面路径(GET 列举 / DELETE 撤销)。 */
 export declare const RULES_PATH = "/v1/rules";
 export declare function handleRules(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;

package/dist/http/routes/rules.js

@@ -1,11 +1,16 @@
 import { z } from "zod";
-import { sendJson, sendError } from "../send.js";
+import { sendJson, sendError, httpErrorCode } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
 import { createLogger } from "../../observability/logger.js";
 import { RULE_IMPORT_RETRY_AFTER_SEC, MAX_RULE_SCOPE_CHARS, parseRuleScope, serializeRuleScope } from "../../rules-consent.js";
+import { CONTROL_AND_BIDI_CHARS } from "../../text-bidi.js";
+import { HttpError } from "../../security.js";
+import { MAX_RULE_TEXT_CHARS } from "@sema-agent/core";
 const logger = createLogger();
 export const RULES_CC_IMPORT_PREPARE_PATH = "/v1/rules/cc-import/prepare";
 export const RULES_CC_IMPORT_REDEEM_PATH = "/v1/rules/cc-import/redeem";
+export const RULES_LOCAL_IMPORT_PREPARE_PATH = "/v1/rules/local-import/prepare";
+export const RULES_LOCAL_IMPORT_REDEEM_PATH = "/v1/rules/local-import/redeem";
 export const RULES_PATH = "/v1/rules";
 const RULES_PAGE_DEFAULT = 50;
 const RULES_PAGE_MAX = 200;
@@ -26,7 +31,30 @@ const CcImportPrepareBodySchema = z
         .max(MAX_LAYERS),
 })
     .strict();
-const CcImportRedeemBodySchema = z.object({ ticket: z.string().min(1).max(190) }).strict();
+const TICKET_CONTROL_CHARS_RE = new RegExp(`[${CONTROL_AND_BIDI_CHARS}]`);
+const TicketStringSchema = z.string().min(1).max(190).refine((t) => !TICKET_CONTROL_CHARS_RE.test(t));
+const CcImportRedeemBodySchema = z.object({ ticket: TicketStringSchema }).strict();
+const LocalImportAddSchema = z
+    .object({
+    dot: z.object({ actor: z.string().min(1).max(190), counter: z.number().int().nonnegative().safe() }).strict(),
+    origin: z.enum(["user", "imported-cc", "starter"]),
+    createdAt: z.string().min(1).max(64),
+})
+    .strict();
+const LocalImportRowSchema = z
+    .object({
+    rule: z.string().min(1).max(MAX_RULE_TEXT_CHARS),
+    scope: z.string().min(1).max(MAX_RULE_SCOPE_CHARS),
+    tool: z.literal("Bash"),
+    match: z.enum(["exact", "prefix"]),
+    command: z.string().min(1).max(MAX_RULE_TEXT_CHARS),
+    adds: z.array(LocalImportAddSchema).max(64),
+})
+    .strict();
+const LOCAL_IMPORT_ROW_SHAPE_PIN = true;
+void LOCAL_IMPORT_ROW_SHAPE_PIN;
+const LocalImportPrepareBodySchema = z.object({ rows: z.array(LocalImportRowSchema).min(1) }).strict();
+const LocalImportRedeemBodySchema = z.object({ ticket: TicketStringSchema }).strict();
 const RuleRevokeBodySchema = z
     .object({
     rule: z.string().min(1).max(1024),
@@ -60,9 +88,11 @@ async function handleRulesBody(req, res, url, ctx, miss) {
     const { readJson, rateLimited } = ctx.helpers;
     const isPrepare = req.method === "POST" && url === RULES_CC_IMPORT_PREPARE_PATH;
     const isRedeem = req.method === "POST" && url === RULES_CC_IMPORT_REDEEM_PATH;
+    const isLocalPrepare = req.method === "POST" && url === "/v1/rules/local-import/prepare";
+    const isLocalRedeem = req.method === "POST" && url === "/v1/rules/local-import/redeem";
     const isList = req.method === "GET" && url === "/v1/rules";
     const isRevoke = req.method === "DELETE" && url === "/v1/rules";
-    if (!isPrepare && !isRedeem && !isList && !isRevoke) {
+    if (!isPrepare && !isRedeem && !isList && !isRevoke && !isLocalPrepare && !isLocalRedeem) {
         miss.fell = true;
         return;
     }
@@ -86,7 +116,11 @@ async function handleRulesBody(req, res, url, ctx, miss) {
     try {
         rawBody = await readJson(req);
     }
-    catch {
+    catch (err) {
+        if (err instanceof HttpError && err.status !== 400) {
+            sendError(res, err.status, httpErrorCode(err.status, err.code), err.message);
+            return;
+        }
         sendError(res, 400, "request.body_shape", "body must be valid JSON");
         return;
     }
@@ -94,6 +128,46 @@ async function handleRulesBody(req, res, url, ctx, miss) {
         await handleRuleRevoke(res, rawBody, principal, lane, deps.config.operatorPrincipals);
         return;
     }
+    if (isLocalPrepare) {
+        const parsed = LocalImportPrepareBodySchema.safeParse(rawBody);
+        if (!parsed.success) {
+            sendError(res, 400, "request.body_shape", "body must be {rows:[{rule,scope,tool,match,command,adds}]}");
+            return;
+        }
+        const prepared = await lane.prepareLocalImport(principal, parsed.data.rows);
+        if (!prepared.ok) {
+            logger.info("local rule import batch refused", prepared.reason === "too-many-rows" ? { reason: prepared.reason, rows: prepared.rows } : { reason: prepared.reason, bytes: prepared.bytes });
+            sendError(res, 413, "request.payload_too_large", "too many rule rows in this batch — split it and import again");
+            return;
+        }
+        sendJson(res, 200, { preview: prepared.preview, ...(prepared.ticket !== undefined ? { ticket: prepared.ticket, expiresAtMs: prepared.expiresAtMs } : {}) });
+        return;
+    }
+    if (isLocalRedeem) {
+        const parsed = LocalImportRedeemBodySchema.safeParse(rawBody);
+        if (!parsed.success) {
+            sendError(res, 400, "request.body_shape", "body must be {ticket}");
+            return;
+        }
+        const redeemed = await lane.redeemLocalImport(principal, parsed.data.ticket);
+        if (redeemed.ok) {
+            sendJson(res, 200, { members: redeemed.outcome.members, rev: redeemed.outcome.rev });
+            return;
+        }
+        logger.info("local rule import ticket refused", { reason: redeemed.reason, detail: redeemed.detail, retryable: redeemed.reason !== "ticket-unusable" && redeemed.reason !== "in-flight" && redeemed.retryable === true });
+        if (redeemed.reason === "in-flight") {
+            res.setHeader("retry-after", String(RULE_IMPORT_RETRY_AFTER_SEC));
+            sendError(res, 409, "conflict.rule_import_in_flight", "another redemption of this import ticket is still in flight — retry with the same ticket", { retryAfterSec: RULE_IMPORT_RETRY_AFTER_SEC });
+            return;
+        }
+        if (redeemed.reason !== "ticket-unusable" && redeemed.retryable === true) {
+            res.setHeader("retry-after", String(RULE_IMPORT_RETRY_AFTER_SEC));
+            sendError(res, 503, "state.rule_import_retry", "the rule import could not be completed right now; the ticket is still usable — retry", { retryAfterSec: RULE_IMPORT_RETRY_AFTER_SEC });
+            return;
+        }
+        sendError(res, 404, "not_found.rule_ticket", "no such import ticket");
+        return;
+    }
     if (isPrepare) {
         const parsed = CcImportPrepareBodySchema.safeParse(rawBody);
         if (!parsed.success) {
@@ -115,7 +189,12 @@ async function handleRulesBody(req, res, url, ctx, miss) {
     }
     const redeemed = await lane.redeemImport(principal, parsed.data.ticket);
     if (!redeemed.ok) {
-        logger.info("rule import ticket refused", { reason: redeemed.reason, detail: redeemed.detail, retryable: redeemed.retryable === true });
+        logger.info("rule import ticket refused", { reason: redeemed.reason, detail: redeemed.detail, retryable: redeemed.reason !== "state-unreadable" && redeemed.retryable === true });
+        if (redeemed.reason === "state-unreadable") {
+            res.setHeader("retry-after", String(RULE_IMPORT_RETRY_AFTER_SEC));
+            sendError(res, 503, "state.rule_ticket_unreadable", "the import ticket's state could not be read right now — retry with the same ticket, and re-run the import if it then reports not found", { retryAfterSec: RULE_IMPORT_RETRY_AFTER_SEC });
+            return;
+        }
         if (redeemed.retryable === true) {
             res.setHeader("retry-after", String(RULE_IMPORT_RETRY_AFTER_SEC));
             sendError(res, 503, "state.rule_import_retry", "the rule import could not be completed right now; the ticket is still usable — retry", { retryAfterSec: RULE_IMPORT_RETRY_AFTER_SEC });

package/dist/http/routes/run-memory-capture.d.ts

@@ -0,0 +1,34 @@
+/**
+ * design/383 §2.1 / §3.4 S-8①(server S-49;[5596] 认领)—— **中途翻转 verb** 的 wire 面:
+ *
+ *   `POST /v1/runs/:id/memory/capture-optout`  body `{ reason?: string }`
+ *     → 200 `{ taskId, sessionId, outcome: "created" | "existed" }`
+ *
+ * 语义 = core `TaskStream.optOutMemoryCapture()`(「聊着聊着发现不该记」):从这一刻起本会话**零提交**长期记忆、
+ * 已提交贡献退出整理候选(回溯 A2 臂)、写根残留边界隔离清扫。**单向**(无反向动词;重复调用幂等 `existed`),
+ * 回到采集只能开新会话。
+ *
+ * ── 权限法条(steer 车道逐字)────────────────────────────────────────────────────────────────────
+ * core 不认证:持有活流句柄即能力。**本面拥有 verified-principal / 会话所有权判定**:裸 sessionId 中继会让任何人
+ * 关掉任何人的记忆(可用性攻击)。所以:身份来自 `gatedPrincipal`(验证过的身份,不是可自造的头),run 属主不符
+ * ⇒ 404 `not_found.run` **同串反枚举**(与 steer/interrupt 同判)。core 在翻转时刻**重新裁决** per-principal
+ * entitlement(`RuntimeCaps.allowMemoryOptOut` under `memoryCapturePolicy`,fresh resolve)—— 被拒 ⇒ typed
+ * `memory.capture_optout_denied` + 零记录残留;server 不复刻那条裁决。
+ *
+ * ── 四臂(steer 车道同形,但**没有 park 腿**)──────────────────────────────────────────────────────
+ *  (a) 本副本活流在场 ⇒ 调 verb,200 `{outcome}`;core 的 typed 拒闭集逐码转发(见 switch);
+ *  (b) 非 live(parked / 他副本 / 无活流 / 终态)⇒ 409 `steering.not_running` + 指路**声明形**:opt-out 的持久
+ *      形是 `TaskSpec.memory.capture:"off"`(wire `memoryCapture:"off"`),下一次 resume/新会话提交时带上即可 ——
+ *      core 明写声明与 verb 是同一条记录的两个 ingress,**不存在**「park 一个翻转等 resume 再翻」的形(记录是
+ *      一次性单向的,resume 时带声明就是幂等重写),所以本面刻意不铸 park 腿。
+ *
+ * ── 计费/门 ─────────────────────────────────────────────────────────────────────────────────────
+ * 零模型工作(不进 billable;不吃 drain / roster-pending);mutating ⇒ `rateLimited`。**不进** `isCredentialGatedRewrite`:
+ * 有属主门兜底(run.owner),爆炸半径 = 本人会话。能力位 `runMemoryCaptureOptOut`(= 持久 run 账面在场,与
+ * `sessionBackgroundable` 同谓词):老 worker 键缺席 ⇒ 壳不渲入口(假 affordance 纪律)。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type RouteCtx } from "../route-ctx.js";
+export declare const RUN_MEMORY_CAPTURE_OPTOUT_RE: RegExp;
+export declare function handleRunMemoryCapture(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+//# sourceMappingURL=run-memory-capture.d.ts.map

package/dist/http/routes/run-memory-capture.js

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import { isParkedRunStatus, isTerminalRunStatus } from "../../plugins/store-contracts.js";
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal } from "../principal-gate.js";
+import { RUN_NOT_FOUND_MESSAGE, runNotFoundMessage } from "../route-ctx.js";
+export const RUN_MEMORY_CAPTURE_OPTOUT_RE = /^\/v1\/runs\/([^/]+)\/memory\/capture-optout$/;
+const BodySchema = z.object({ reason: z.string().min(1).max(500).optional() }).strict();
+export async function handleRunMemoryCapture(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const m = req.method === "POST" ? RUN_MEMORY_CAPTURE_OPTOUT_RE.exec(url) : null;
+    if (m === null) {
+        miss.fell = true;
+        return;
+    }
+    if (ctx.helpers.rateLimited(req, res))
+        return;
+    if (!deps.runStore) {
+        sendError(res, 501, "capability.run_store_required", "async runs require a durable run store (DB_BACKEND=mysql|pg|local)");
+        return;
+    }
+    const principal = gatedPrincipal(req, deps.config);
+    if (deps.config.requirePrincipal && principal === undefined) {
+        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        return;
+    }
+    const taskId = m[1];
+    const parsed = BodySchema.safeParse((await ctx.helpers.readJson(req)) ?? {});
+    if (!parsed.success) {
+        sendError(res, 400, "request.body_shape", "body must be {} or { reason: string (non-empty, at most 500 chars) } — the session memory-capture opt-out verb takes no other keys");
+        return;
+    }
+    const run = await deps.runStore.getRun(taskId);
+    if (!run) {
+        sendError(res, 404, "not_found.run", runNotFoundMessage(taskId));
+        return;
+    }
+    if (run.owner !== null && run.owner !== principal) {
+        sendError(res, 404, "not_found.run", RUN_NOT_FOUND_MESSAGE);
+        return;
+    }
+    const live = ctx.registry.steerableRuns.get(taskId);
+    if (live) {
+        try {
+            const { outcome } = await live.optOutMemoryCapture(parsed.data.reason !== undefined ? { reason: parsed.data.reason } : {});
+            sendJson(res, 200, { taskId, sessionId: run.sessionId, outcome });
+            return;
+        }
+        catch (e) {
+            const code = e.code;
+            const msg = e instanceof Error ? e.message : String(e);
+            switch (code) {
+                case "memory.capture_optout_denied":
+                    sendError(res, 403, "memory.capture_optout_denied", msg);
+                    return;
+                case "memory.capture_optout_unpersisted":
+                    sendError(res, 503, "memory.capture_optout_unpersisted", msg);
+                    return;
+                case "memory.capture_optout_unavailable":
+                    sendError(res, 409, "memory.capture_optout_unavailable", msg);
+                    return;
+                case "memory.capture_optout_sweep_failed":
+                    sendError(res, 409, "memory.capture_optout_sweep_failed", msg);
+                    return;
+                case "config.memory_capture_unsupported":
+                    sendError(res, 409, "config.memory_capture_unsupported", msg);
+                    return;
+                case "steering.invalid_content":
+                    sendError(res, 422, "steering.invalid_content", msg);
+                    return;
+                case "steering.not_running":
+                    sendError(res, 409, "steering.not_running", "run just finished — the memory-capture opt-out verb needs a live run; declare it on the next submit instead (memoryCapture: 'off')");
+                    return;
+                default: throw e;
+            }
+        }
+    }
+    if (isParkedRunStatus(run.status)) {
+        sendError(res, 409, "steering.not_running", "run is parked on a pending decision — the memory-capture opt-out verb needs a live turn, and a resumed continuation rebuilds its spec from the persisted body (it cannot take a new declaration); the opt-out becomes effective on this session's next NEW submit (POST /v1/tasks with this sessionId and memoryCapture: 'off') — content captured until then stays captured");
+        return;
+    }
+    if (isTerminalRunStatus(run.status)) {
+        sendError(res, 409, "steering.not_running", "run already ended — the memory-capture opt-out verb needs a live run; submit the next turn of this session with memoryCapture: 'off' (the declaration writes the same one-way session record)");
+        return;
+    }
+    const provenElsewhere = typeof run.instanceId === "string" && run.instanceId.length > 0 && deps.instanceId !== undefined && run.instanceId !== deps.instanceId;
+    if (provenElsewhere) {
+        sendError(res, 409, "steering.not_running", "run is live on another replica — the memory-capture opt-out verb must reach the replica holding the stream; resend it there, or declare memoryCapture: 'off' on the next submit");
+        return;
+    }
+    sendError(res, 409, "steering.not_running", "no live steerable face for this run on this replica — verify/cascade execution lanes expose none; declare memoryCapture: 'off' on the next submit of this session instead");
+}
+//# sourceMappingURL=run-memory-capture.js.map

package/dist/http/routes/runs.d.ts

@@ -20,6 +20,7 @@ export declare const RUN_CANCEL_RE: RegExp;
 export declare const RUN_STEER_RE: RegExp;
 export declare const RUN_DETACH_RE: RegExp;
 export declare const RUN_COMPACT_RE: RegExp;
+export declare const RUN_INTERRUPT_RE: RegExp;
 /** PAIR-REVIEW F-10:runs 面 404 文案统一富形——a\* 形 id(background-agent registry 句柄,`a`+hex 短形)
  *  是「结构性不在 run 店」的常客([1347]⑤ 记档裁量:不改路由,只给引导)。识别句法形即补引导;
  *  非 a\* 形保通用富文案(cancel 腿 [888]① 同款)。 */