@sema-agent/server 6.7.0 → 7.0.0

package/dist/org-memory-admission.js

@@ -0,0 +1,224 @@
+import { PrincipalOrgMemoryWire } from "@sema-agent/registry-core";
+import { assertPrincipalShape } from "./security.js";
+const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const ORG_SCOPE_RE = /^org:\S+$/;
+/**
+ * 单机腿:装载 `MEMORY_ORG_DIRECTORY_JSON`(`Record<principal, Record<orgScope, {write?}>>`)。启动期调用,
+ * **fail-loud**——任何非法直接 throw 且消息点名坏在哪个键(响亮拒是正确方向:一张半坏的授权表比拒绝
+ * 启动更危险)。principal 键复用 {@link assertPrincipalShape}(拒保留哨兵/超长租户名,与所有其它
+ * principal 入口同一道闸);scope 键必须是 `org:` 前缀、值必须是仅含可选 `write: boolean` 的 plain object。
+ */
+export function parseOrgDirectoryStatic(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (e) {
+        throw new Error(`MEMORY_ORG_DIRECTORY_JSON is not valid JSON: ${e.message}`);
+    }
+    if (!isPlainObject(parsed)) {
+        throw new Error("MEMORY_ORG_DIRECTORY_JSON must be a JSON object: Record<principal, Record<orgScope, {write?: boolean}>>");
+    }
+    const table = new Map();
+    for (const [principal, scopesRaw] of Object.entries(parsed)) {
+        assertPrincipalShape(principal); // reserved sentinel / oversized tenant name → throws (same gate as every other principal entry point)
+        if (!isPlainObject(scopesRaw)) {
+            throw new Error(`MEMORY_ORG_DIRECTORY_JSON[${JSON.stringify(principal)}] must be an object of org scopes`);
+        }
+        const scopes = {};
+        for (const [scope, entryRaw] of Object.entries(scopesRaw)) {
+            if (!ORG_SCOPE_RE.test(scope)) {
+                throw new Error(`MEMORY_ORG_DIRECTORY_JSON[${JSON.stringify(principal)}] has an invalid org scope key ${JSON.stringify(scope)} (must match /^org:\\S+$/)`);
+            }
+            if (!isPlainObject(entryRaw)) {
+                throw new Error(`MEMORY_ORG_DIRECTORY_JSON[${JSON.stringify(principal)}][${JSON.stringify(scope)}] must be an object`);
+            }
+            for (const key of Object.keys(entryRaw)) {
+                if (key !== "write") {
+                    throw new Error(`MEMORY_ORG_DIRECTORY_JSON[${JSON.stringify(principal)}][${JSON.stringify(scope)}] has an unexpected key ${JSON.stringify(key)} (only "write" is allowed)`);
+                }
+            }
+            if (entryRaw.write !== undefined && typeof entryRaw.write !== "boolean") {
+                throw new Error(`MEMORY_ORG_DIRECTORY_JSON[${JSON.stringify(principal)}][${JSON.stringify(scope)}].write must be a boolean`);
+            }
+            scopes[scope] = entryRaw.write !== undefined ? { write: entryRaw.write } : {};
+        }
+        table.set(principal, scopes);
+    }
+    return table;
+}
+/**
+ * 建目录:远程腿(fetchSection,per-principal TTL 缓存 + in-flight 去重 + 退避窗 + gen 高水位)或单机腿
+ * (staticTable,恒同步成功、无 TTL/退避语义——operator 自证配置面)。两腿互斥,装配点必须恰好给一个。
+ */
+export function createOrgMemoryDirectory(opts) {
+    if ((opts.fetchSection !== undefined) === (opts.staticTable !== undefined)) {
+        throw new Error("createOrgMemoryDirectory requires exactly one of fetchSection or staticTable (both given or both missing)");
+    }
+    if (opts.staticTable !== undefined) {
+        const table = opts.staticTable;
+        return {
+            async lookup(principal) {
+                return { kind: "granted", scopes: table.get(principal) ?? {} };
+            },
+        };
+    }
+    if (opts.fetchSection === undefined) {
+        // Unreachable given the xor guard above (staticTable was undefined, so fetchSection must not be) — this
+        // check exists ONLY so the type checker narrows fetchSection to a function without a cast.
+        throw new Error("createOrgMemoryDirectory: fetchSection missing (invariant violated)");
+    }
+    const fetchSection = opts.fetchSection;
+    const grantTtlMs = opts.grantTtlMs;
+    const backoffMs = opts.unavailableBackoffMs;
+    const now = opts.now ?? (() => Date.now());
+    const states = new Map();
+    const inflight = new Map();
+    function markUnavailable(state, reason) {
+        state.unavailable = { until: now() + backoffMs, reason };
+        // C6: retryAfterMs never 0/negative — the window just opened, so its remaining time IS backoffMs.
+        return { kind: "unavailable", reason, retryAfterMs: Math.max(backoffMs, 1000) };
+    }
+    async function doFetch(principal, state) {
+        let raw;
+        try {
+            raw = await fetchSection(principal);
+        }
+        catch {
+            return markUnavailable(state, "fetch_failed");
+        }
+        if (raw === undefined)
+            return markUnavailable(state, "section_absent");
+        const parsed = PrincipalOrgMemoryWire.safeParse(raw);
+        if (!parsed.success) {
+            // malformed: does NOT touch state.grant — a bad shape must not refresh (or clear) an existing granted entry's
+            // timestamp; a still-fresh old grant keeps serving from cache on the NEXT lookup (checked before we ever get here).
+            return markUnavailable(state, "malformed");
+        }
+        if (state.highWaterGen !== undefined && parsed.data.gen < state.highWaterGen) {
+            // LB stale-replica defense: an older generation than one we've already seen is NEVER adopted.
+            return markUnavailable(state, "stale_generation");
+        }
+        state.highWaterGen = parsed.data.gen;
+        state.grant = { scopes: parsed.data.scopes, at: now() };
+        delete state.unavailable; // a real success clears any prior backoff window
+        return { kind: "granted", scopes: parsed.data.scopes };
+    }
+    return {
+        async lookup(principal) {
+            let state = states.get(principal);
+            if (!state) {
+                state = {};
+                states.set(principal, state);
+            }
+            const t = now();
+            // 1. Fresh grant (positive OR negative/empty result) always wins — no fetch, no backoff check.
+            if (state.grant && state.grant.at + grantTtlMs > t) {
+                return { kind: "granted", scopes: state.grant.scopes };
+            }
+            // 2. Inside an open backoff window → answer from the window WITHOUT re-fetching.
+            if (state.unavailable && state.unavailable.until > t) {
+                return { kind: "unavailable", reason: state.unavailable.reason, retryAfterMs: Math.max(state.unavailable.until - t, 1000) };
+            }
+            // 3. Grant expired (or never existed) and no active backoff → fetch, deduping concurrent callers.
+            const dup = inflight.get(principal);
+            if (dup)
+                return dup;
+            const p = doFetch(principal, state).finally(() => inflight.delete(principal));
+            inflight.set(principal, p);
+            return p;
+        },
+    };
+}
+/** core 侧「瞬时不可用，重试」契约的载体：一个带 `retryAfterMs`（ms）属性的真 Error 子类，core 据此铸
+ *  memory.admission_required 终局码并透传该值。子类而非事后挂属性——避免任何宽松断言就能拿到正确类型。 */
+export class OrgMemoryAdmissionRetryError extends Error {
+    retryAfterMs;
+    constructor(message, retryAfterMs) {
+        super(message);
+        this.retryAfterMs = retryAfterMs;
+        this.name = "OrgMemoryAdmissionRetryError";
+    }
+}
+/**
+ * `RunnerDeps.memoryScopeAdmission` 的 server 实装。deployment-origin 的 requested 项一律放行（operator
+ * 自证——v1 不做中央收窄部署声明）；request-origin 项查 `directory.lookup(principal)`：granted 时逐项核
+ * 对是否在授权集里（任何一项缺席 = 整体终局拒绝，不做部分放行——reason 只点名调用方自己请求过的 scope
+ * 串，不逐 scope 展开「为什么」，避免变成成员探针）；unavailable 时 throw 一个带 `retryAfterMs` 的
+ * {@link OrgMemoryAdmissionRetryError}。write 面独立收窄：deployment-origin 恒授，request-origin 仅当目录
+ * 条目 `write === true` 才授，否则收窄为 null（即使读侧整体放行）。
+ */
+export function createMemoryScopeAdmission(directory, opts) {
+    const emit = (outcome, details) => {
+        try {
+            opts.onOutcome?.(outcome, details);
+        }
+        catch {
+            /* an observability hook must never break admission */
+        }
+    };
+    return async ({ principal, requested, requestedWriteScope }) => {
+        const requestOriginRequested = requested.filter((r) => r.origin === "request");
+        const writeIsRequestOrigin = requestedWriteScope?.origin === "request";
+        const hasRequestOrigin = requestOriginRequested.length > 0 || writeIsRequestOrigin;
+        const fullScopes = requested.map((r) => r.scope);
+        const fullWriteScope = requestedWriteScope?.scope ?? null;
+        const admitFull = () => ({ ok: true, scopes: fullScopes, writeScope: fullWriteScope });
+        async function decide() {
+            // deployment-only requests (no request-origin item anywhere, including the write slot): nothing to
+            // look up — v1 does not centrally narrow operator-declared deployment scopes.
+            if (!hasRequestOrigin)
+                return { kind: "admit", verdict: admitFull() };
+            if (principal === undefined) {
+                // Defensive arm: core already refuses this shape itself when a request-origin org scope is present
+                // with no principal, but the resolver must not assume that guard always ran first.
+                return { kind: "deny", reason: "principal absent", outcome: "principal_missing" };
+            }
+            const lookup = await directory.lookup(principal);
+            if (lookup.kind === "unavailable") {
+                const outcome = lookup.reason === "stale_generation" ? "directory_stale" : lookup.reason === "malformed" ? "directory_malformed" : "directory_absent"; // fetch_failed | section_absent
+                return { kind: "unavailable", retryAfterMs: lookup.retryAfterMs, outcome, lookupReason: lookup.reason, details: { reason: lookup.reason } };
+            }
+            const deniedScopes = requestOriginRequested.filter((r) => !(r.scope in lookup.scopes)).map((r) => r.scope);
+            if (deniedScopes.length > 0) {
+                return {
+                    kind: "deny",
+                    reason: `org scope(s) not admitted for this principal: ${deniedScopes.join(", ")}`,
+                    outcome: "denied",
+                    details: { deniedScopes },
+                };
+            }
+            const writeScope = requestedWriteScope === null
+                ? null
+                : requestedWriteScope.origin === "deployment"
+                    ? requestedWriteScope.scope
+                    : lookup.scopes[requestedWriteScope.scope]?.write === true
+                        ? requestedWriteScope.scope
+                        : null;
+            return { kind: "admit", verdict: { ok: true, scopes: fullScopes, writeScope } };
+        }
+        const decision = await decide();
+        if (decision.kind === "admit") {
+            // C10(audit=纯观察**零**行为变化):write 收窄也是行为变化(enforce 下 harvest 静默零提交)——
+            // audit 模式对「读面通过但 write 未显式授」的判决只记 would-narrow,返回未收窄的全额;
+            // enforce 照常收窄。ok:true 分支的 writeScope 恒为 fullWriteScope 或 null(decide 只做这两值)。
+            if (opts.mode === "audit" && decision.verdict.ok && decision.verdict.writeScope !== fullWriteScope) {
+                emit("ok", { audited: true, wouldNarrowWriteScope: true });
+                return admitFull();
+            }
+            emit("ok");
+            return decision.verdict;
+        }
+        if (opts.mode === "audit") {
+            // Zero behavior change: a would-deny (terminal or transient) is overridden to a full, UNNARROWED admit —
+            // the real decision is only ever recorded via onOutcome, never enforced.
+            emit(decision.outcome, { ...decision.details, audited: true, wouldDeny: true, ...(decision.kind === "unavailable" ? { retryAfterMs: decision.retryAfterMs } : { reason: decision.reason }) });
+            return admitFull();
+        }
+        emit(decision.outcome, decision.details);
+        if (decision.kind === "deny")
+            return { ok: false, reason: decision.reason };
+        throw new OrgMemoryAdmissionRetryError(`org memory directory unavailable (${decision.lookupReason})`, decision.retryAfterMs);
+    };
+}
+//# sourceMappingURL=org-memory-admission.js.map

package/dist/question.d.ts

@@ -67,6 +67,11 @@ export declare class QuestionCoordinator {
     };
     /** Test/observability hook: number of currently-parked questions. */
     pendingCount(): number;
+    /** #152 ([2703] 案二):durable 部署上的 AskUserQuestion 判决探针——本调用点是否处在某条活流腿的
+     *  per-run 上下文里(runWithContext 包裹的 bg/SSE 腿=true;sync /v1/tasks、verify/cascade=false)。
+     *  resolve-spec 的 durable question policy 用它在**判决时**分腿:有活流 ⇒ allow(问活人),无 ⇒
+     *  ask(durable park)。ALS 让这个判断天然 per-leg,policy 组装期不必预知腿别。 */
+    hasLiveContext(): boolean;
     private countersFor;
 }
 //# sourceMappingURL=question.d.ts.map

package/dist/question.js

@@ -192,6 +192,13 @@ export class QuestionCoordinator {
     pendingCount() {
         return this.pending.size;
     }
+    /** #152 ([2703] 案二):durable 部署上的 AskUserQuestion 判决探针——本调用点是否处在某条活流腿的
+     *  per-run 上下文里(runWithContext 包裹的 bg/SSE 腿=true;sync /v1/tasks、verify/cascade=false)。
+     *  resolve-spec 的 durable question policy 用它在**判决时**分腿:有活流 ⇒ allow(问活人),无 ⇒
+     *  ask(durable park)。ALS 让这个判断天然 per-leg,policy 组装期不必预知腿别。 */
+    hasLiveContext() {
+        return this.als.getStore() !== undefined;
+    }
     countersFor(taskId) {
         let rc = this.counters.get(taskId);
         if (!rc) {

package/dist/runs.d.ts

@@ -106,6 +106,13 @@ export declare function isSessionConflictResult(result: {
  * UNCHANGED for the shell). `rewind_snapshot.unresolvable` (rewindFiles + "before": no snapshot at/above the branch
  * point) is core's third rejection with a DIFFERENT prefix — same caller-mistake shape (prepare-throw, nothing
  * billed), map it to 422 explicitly so it doesn't fall through to a 200-with-failed body.
+ *
+ * design/170 件A(#148 件4): core 5.13.0's org-memory admission rides the SAME prepare-throw pipe
+ * (GOVERNANCE_CODES). `memory.admission_denied` is TERMINAL — the principal has no grant on that tenant
+ * plane → 403 (a retry cannot change the verdict). `memory.admission_required` is TRANSIENT fail-closed —
+ * the directory is unreachable / no resolver is wired → 503 (retry later; the sync leg forwards the
+ * result's `retryAfterMs` as body `retryAfterSec`, same family shape as usage.window_exhausted). Exact
+ * codes only, no memory.* family grab — an unknown sibling stays a 200-with-failed-body until cataloged.
  */
 export declare function resumeAtHttpStatus(result: {
     status: string;

package/dist/runs.js

@@ -3,7 +3,7 @@ import { withPrincipal } from "./observability/principal-context.js";
 import { redactSecrets } from "./trace/redact.js";
 import { taskNotificationEventData, appendModelUsageDelta, appendPromptManifest, attachModelUsage } from "./trace/project.js";
 import { createLedgerSink } from "./trace/ledger-sink.js";
-import { fleetRunResiduals } from "./fleet/fleet-bus.js";
+import { fleetRunResiduals, isFleetAgentTerminalNotification } from "./fleet/fleet-bus.js";
 import { defaultSubagentTailBus, projectTailFrame } from "./fleet/subagent-tail-bus.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKey, NotifiedKeys } from "./orchestration/workflow-completion-inbox.js";
 /**
@@ -148,6 +148,13 @@ export function isSessionConflictResult(result) {
  * UNCHANGED for the shell). `rewind_snapshot.unresolvable` (rewindFiles + "before": no snapshot at/above the branch
  * point) is core's third rejection with a DIFFERENT prefix — same caller-mistake shape (prepare-throw, nothing
  * billed), map it to 422 explicitly so it doesn't fall through to a 200-with-failed body.
+ *
+ * design/170 件A(#148 件4): core 5.13.0's org-memory admission rides the SAME prepare-throw pipe
+ * (GOVERNANCE_CODES). `memory.admission_denied` is TERMINAL — the principal has no grant on that tenant
+ * plane → 403 (a retry cannot change the verdict). `memory.admission_required` is TRANSIENT fail-closed —
+ * the directory is unreachable / no resolver is wired → 503 (retry later; the sync leg forwards the
+ * result's `retryAfterMs` as body `retryAfterSec`, same family shape as usage.window_exhausted). Exact
+ * codes only, no memory.* family grab — an unknown sibling stays a 200-with-failed-body until cataloged.
  */
 export function resumeAtHttpStatus(result) {
     if (result.status !== "failed")
@@ -156,6 +163,10 @@ export function resumeAtHttpStatus(result) {
         return 404;
     if (result.errorCode === "rewind_snapshot.unresolvable")
         return 422;
+    if (result.errorCode === "memory.admission_denied")
+        return 403;
+    if (result.errorCode === "memory.admission_required")
+        return 503;
     if (!(result.errorCode?.startsWith("resume_at.") ?? false))
         return undefined;
     return result.errorCode === "resume_at.not_found" ? 404 : 422;
@@ -362,7 +373,9 @@ promptManifests) {
     // run-store mutation/poll below (the run row was created with owner = principal ?? null).
     const owner = principal ?? null;
     const heartbeat = setInterval(() => {
-        void runStore.heartbeat(taskId, owner).catch(() => undefined);
+        // 鲁棒性批5 A5(2026-08-05):与下面 cancel/preempt 两条兄弟同族——此前裸吞错,store 持续故障期间本 run
+        // 的心跳每拍静默落空、运维零信号,直到某个副本的 reapStale 把它误判死亡(心跳失败正是那个误判的前兆)。
+        void runStore.heartbeat(taskId, owner).catch(() => { metrics?.inc("run_signal_poll_errors_total", { kind: "heartbeat" }); });
         // Cross-replica cancel: the cancel may have landed on another instance, which only set the durable flag.
         // Poll it here so the OWNING instance aborts its in-flight run (bounded by HEARTBEAT_MS).
         // 鲁棒性批3 A5(2026-08-04,§M 感知链路):poll 失败本身有界(下一拍重试),但此前**零披露**——
@@ -573,8 +586,11 @@ promptManifests) {
                     }
                     // id-domain alias (core): fleet child rows key by the TICK's taskId = the child's sessionId
                     // (uuid domain); the notification's task_id is the a* domain — payload.sessionId IS the tick-domain
-                    // alias, so flip by it (fallback task_id for pre-1.238 payloads / bash lane).
-                    const hadRow = fleetPublisher?.onChildTerminal(n.sessionId ?? n.task_id, n.status, n.task_id, n.toolUseId) ?? false;
+                    // alias, so flip by it (fallback task_id for pre-1.238 payloads).
+                    // [2687-cli] 幽灵行案:onChildTerminal 只对 **agent 族终态**调用(isFleetAgentTerminalNotification
+                    // 单源判别,理由与病灶链见其 doc 注)。通知帧/park 面照走,只掐 fleet 铸行。三消费点孪生同形
+                    // (http/server.ts resume 腿、routes/tasks.ts sync 腿)。
+                    const hadRow = isFleetAgentTerminalNotification(n) ? (fleetPublisher?.onChildTerminal(n.sessionId ?? n.task_id, n.status, n.task_id, n.toolUseId) ?? false) : false;
                     const parked = !legLive && Boolean(workflowCompletionInbox && spec.sessionId);
                     // diagnosability: one line per observed bg completion. hadFleetRow=false = the terminal frame was
                     // FLIP-THROUGH synthesized (the row was gone — parent settle removed it, or a bg BASH never ticked).

package/dist/spec-fields.js

@@ -69,9 +69,10 @@ export function normalizeAttachments(v) {
         ...(o.todoReminder === true ? { todoReminder: true } : {}),
         ...(changedFiles !== undefined ? { changedFiles } : {}),
         ...(o.planModeReminder === true ? { planModeReminder: true } : {}),
-        // core 1.253 G1: post-compaction background-task recap + deferred-tools boundary notice —
-        // same literal-true contract as the rest of the family (both are one-shot/opt-in on the core side).
-        ...(o.backgroundTasks === true ? { backgroundTasks: true } : {}),
+        // core 1.253 G1 → 5.12.0 BREAKING-3:压缩后 bg 任务重述从 opt-in 翻 **DEFAULT-ON**(显式 false
+        // 恒关/缺席走默认)。literal-true 形在此翻转后就是轴B #1 的原案复刻(agentListing/skillsListing
+        // 当年同病):丢 false = 客户端显式关断被静默压成默认 ON,wire 上无法表达关闭 ⇒ 迁 boolean 透传。
+        ...(typeof o.backgroundTasks === "boolean" ? { backgroundTasks: o.backgroundTasks } : {}),
         ...(o.toolsDelta === true ? { toolsDelta: true } : {}),
         ...(o.todoReminderMode === "baseline" || o.todoReminderMode === "off" ? { todoReminderMode: o.todoReminderMode } : {}),
         ...(o.budgetUsd === true ? { budgetUsd: true } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "6.7.0",
+  "version": "7.0.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -54,8 +54,8 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "^5.11.0",
-    "@sema-agent/registry-core": "^0.14.0",
+    "@sema-agent/core": "^5.13.0",
+    "@sema-agent/registry-core": "^0.16.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",
     "mysql2": "^3.22.4",