@sema-agent/server 7.130.0 → 7.132.0

package/dist/observability/prompt-manifest.d.ts

@@ -1,85 +1,49 @@
-/** The whitelisted projection of core's `prompt.assembled` trace event ([ref]② web observability slice A:
- *  the manifest reaches the durable run event log + turns/stream). Built FIELD-BY-FIELD at record time
- *  (never a spread — the 1.72 task_progress lesson: a future core field must not ride the durable wire raw).
- *  Carries ONLY ids/digests/counts by core's manifest contract (no prompt bodies; hashes are core-salted) —
- *  so the projection legs have zero redact burden. */
-export interface PromptManifestRecord {
-    constitution: string;
-    blocks: Array<{
-        id: string;
-        chars: number;
-        hash: string;
-    }>;
-    /** `contentHash`(core 1.315 [ref]①):operator 声明 section 的**非盐化**对账锚(core 已对 text 校验
-     *  后透传)——盐化 `hash` 恒在旁;端到端对账链(center 发布→manifest)经本投影,必须透传不可吞。 */
-    sections?: Array<{
-        id: string;
-        slot: string;
-        carrier: string;
-        cadence: string;
-        cacheClass: string;
-        chars: number;
-        hash: string;
-        contentHash?: string;
-    }>;
-    tools?: Array<{
-        wireName: string;
-        aliases: string[];
-        contractId: string;
-        implementationRevision: string;
-        cardId: string;
-        shapeDigest: string;
-        wireSchemaDigest: string;
-    }>;
-    /** core 5.15.0([ref]):deferred 披露策略自证三键(诊断值,零内容)。缺席=core <5.15 或无 deferred。 */
-    toolDisclosure?: {
-        deferredTools: number;
-        strategy: string;
-        source: string;
-    };
-    totalChars: number;
-}
-/** Whitelist one `prompt.assembled` trace event into a {@link PromptManifestRecord} (v1 face required,
- *  v2 `sections`/`tools` additive — absent stays absent). */
-export declare function promptManifestRecordOf(e: {
-    constitution: string;
-    blocks: Array<{
-        id: string;
-        chars: number;
-        hash: string;
-    }>;
-    sections?: Array<{
-        id: string;
-        slot: string;
-        carrier: string;
-        cadence: string;
-        cacheClass: string;
-        chars: number;
-        hash: string;
-        contentHash?: string;
-    }>;
-    tools?: Array<{
-        wireName: string;
-        aliases: string[];
-        contractId: string;
-        implementationRevision: string;
-        cardId: string;
-        shapeDigest: string;
-        wireSchemaDigest: string;
-    }>;
-    /** core 5.15.0([ref],[ref] 提货②):deferred 工具的披露策略自证——{deferredTools(数), strategy
-     *  ("static"|"swap"), source(四值:`spec` / `env` / `default` / `degraded_no_direct_lane`)}。
-     *  诊断三键(数 + 两闭集词,零内容)。词表属主是 core(`core/trace.d.ts` 的 `source` 联合),本仓宽收
-     *  ⇒ 词错不会红,所以照抄时务必对表:`degraded_no_direct_lane` = 直呼车道联锁把 `static` 请求收窄成
-     *  `swap` 的那一格,正是运维最需要认出来的一格(本注上一版把它写成了不存在的 `api-default`,下游看板
-     *  照抄就会把真实的 degraded 读成未知词)。 */
-    toolDisclosure?: {
-        deferredTools: number;
-        strategy: string;
-        source: string;
-    };
-    totalChars: number;
-}): PromptManifestRecord;
+import type { TraceEvent } from "@sema-agent/core";
+/**
+ * 引擎的清单帧 `prompt.assembled`(引擎 7.52.0 起 `version: 3`):这条腿的提示**是哪一份**(`identity` + 它的选择器值 `selectors`)、
+ * 由哪些块与段组成、每一段的文本从哪里来(`chain`,被取代的 overlay 另在 `superseded`)。只有 id / 尺寸 / 摘要,没有提示正文。
+ */
+export type PromptAssembledEvent = Extract<TraceEvent, {
+    kind: "prompt.assembled";
+}>;
+/** 帧上**不上行**的键。唯一一簿在 `trace/wire-projection-faces.ts` 的 `prompt_manifest` 行(逐键理由在那里);这里只做类型查询。 */
+type NotOnTheRow = (typeof import("../trace/wire-projection-faces.js").WIRE_PROJECTION_FACES)["prompt_manifest"]["excluded"][number];
+/** 引擎的型,**词读成开集串**:投影判形,不判词表(档名、激活方式、来源类、渲染器……每一张词表的属主都是引擎,新词原样过境)。 */
+type OpenWords<T> = T extends string ? string : T extends readonly (infer U)[] ? OpenWords<U>[] : T extends object ? {
+    [K in keyof T]: OpenWords<T[K]>;
+} : T;
+/**
+ * 耐久 `prompt_assembled` 行(turns 的 `prompt-assembled` 块与 trace SSE 的同名帧按它原样交出)= **引擎帧减不上行的键**,
+ * 由引擎的型派生,本仓不另写成员表。每个成员都可能缺席:引擎型里可选的成员缺席即缺席;在场却读不出的成员被丢并计数。
+ */
+export type PromptManifestRecord = {
+    [K in Exclude<keyof PromptAssembledEvent, NotOnTheRow>]?: OpenWords<PromptAssembledEvent[K]>;
+};
+/** 投影器的入参:引擎帧的键,值一律当未知读 —— 逐层判形在投影器里做,第三方 producer / 坏世代的帧走同一道门。 */
+export type PromptManifestInput = {
+    readonly [K in keyof PromptAssembledEvent]?: unknown;
+};
+/** 读一个值:读得出 ⇒ 值;读不出 ⇒ `undefined`;可选成员缺席 ⇒ {@link ABSENT}(不铸、不计)。 */
+type Read<V> = (v: unknown) => V | undefined;
+declare const ABSENT: unique symbol;
+/** 可选格的记号:只有 {@link optional} 铸得出带它的读器 —— 一只裸读器的回值型是可选格回值型的子型,单靠回值型拦不住它。 */
+declare const OPTIONAL_CELL: unique symbol;
+type OptionalRead<V> = Read<V | typeof ABSENT> & {
+    readonly [OPTIONAL_CELL]: true;
+};
+/**
+ * 每张读表按引擎型的**每一个键**写一格(`-?`:可选键也必须有格,引擎给哪一层加成员 ⇒ 这里编译红);可选键的格必须经 {@link optional} —— 格型要求
+ * {@link OPTIONAL_CELL} 记号,裸读器写进可选键 ⇒ 编译红(否则缺席的成员被裸读器读成「读不出」,整句被丢)。
+ */
+export type ReadTable<T> = {
+    [K in keyof T]-?: undefined extends T[K] ? OptionalRead<Exclude<T[K], undefined>> : Read<T[K]>;
+};
+/**
+ * 把一帧 `prompt.assembled` 读成耐久行(记录时白名单:tracer 同步、无 IO,未来的引擎键不随帧上行)。
+ * 规则一句:**只挑引擎型里有的键,逐层判形;在场却读不出 ⇒ 计一次 `server.trace.projection-input-malformed` 并丢;缺席从不计数**。
+ * 词原样过境(不判词表);`identity` 是这条腿的提示身份的唯一读法 —— 本仓不另铸第二种(v2 的 `constitution` 随引擎退役)。
+ */
+export declare function promptManifestRecordOf(e: PromptManifestInput): PromptManifestRecord;
 /**
  * [ref]② per-task prompt-manifest accumulator — the `ModelUsageTracker`(budget.ts)pattern: the
  * `prompt.assembled` tracer hook is SYNC/no-IO, so it cannot persist; it RECORDS here (registered
@@ -126,4 +90,5 @@ export declare class PromptManifestTracker {
      *  a stale leg's teardown after a fast re-register is a no-op (the new leg owns it now). */
     clear(taskId: string, lease: number): void;
 }
+export {};
 //# sourceMappingURL=prompt-manifest.d.ts.map

package/dist/observability/prompt-manifest.js

@@ -1,22 +1,124 @@
-export function promptManifestRecordOf(e) {
-    return {
-        constitution: String(e.constitution),
-        blocks: (Array.isArray(e.blocks) ? e.blocks : []).map((b) => ({ id: String(b.id), chars: b.chars, hash: String(b.hash) })),
-        ...(Array.isArray(e.sections)
-            ? { sections: e.sections.map((s) => ({ id: String(s.id), slot: String(s.slot), carrier: String(s.carrier), cadence: String(s.cadence), cacheClass: String(s.cacheClass), chars: s.chars, hash: String(s.hash), ...(typeof s.contentHash === "string" ? { contentHash: s.contentHash } : {}) })) }
-            : {}),
-        ...(Array.isArray(e.tools)
-            ? { tools: e.tools.map((t) => ({ wireName: String(t.wireName), aliases: (Array.isArray(t.aliases) ? t.aliases : []).map(String), contractId: String(t.contractId), implementationRevision: String(t.implementationRevision), cardId: String(t.cardId), shapeDigest: String(t.shapeDigest), wireSchemaDigest: String(t.wireSchemaDigest) })) }
-            : {}),
-        ...(typeof e.toolDisclosure === "object" && e.toolDisclosure !== null &&
-            typeof e.toolDisclosure.deferredTools === "number" && Number.isFinite(e.toolDisclosure.deferredTools) &&
-            typeof e.toolDisclosure.strategy === "string" && e.toolDisclosure.strategy.length > 0 &&
-            typeof e.toolDisclosure.source === "string" && e.toolDisclosure.source.length > 0
-            ? { toolDisclosure: { deferredTools: e.toolDisclosure.deferredTools, strategy: e.toolDisclosure.strategy, source: e.toolDisclosure.source } }
-            : {}),
-        totalChars: e.totalChars,
+import { dropProjectedFace } from "../trace/projection-drop.js";
+const ABSENT = Symbol("absent");
+const OPTIONAL_CELL = Symbol("optional-cell");
+const text = (v) => (typeof v === "string" ? v : undefined);
+const finite = (v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+const flag = (v) => (typeof v === "boolean" ? v : undefined);
+const onlyTrue = (v) => (v === true ? true : undefined);
+const plainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v) ? v : undefined;
+function optional(read) {
+    return Object.assign((v) => (v === undefined ? ABSENT : read(v)), { [OPTIONAL_CELL]: true });
+}
+function objectOf(table) {
+    return (v) => {
+        const o = plainObject(v);
+        if (o === undefined)
+            return undefined;
+        const out = {};
+        for (const [key, read] of Object.entries(table)) {
+            const r = read(o[key]);
+            if (r === undefined)
+                return undefined;
+            if (r !== ABSENT)
+                out[key] = r;
+        }
+        return out;
+    };
+}
+function listOf(read) {
+    return (v) => {
+        if (!Array.isArray(v))
+            return undefined;
+        const out = [];
+        for (const x of v) {
+            const r = read(x);
+            if (r === undefined)
+                return undefined;
+            out.push(r);
+        }
+        return out;
+    };
+}
+function entriesOf(read) {
+    return (v) => {
+        const o = plainObject(v);
+        if (o === undefined)
+            return undefined;
+        const out = [];
+        for (const [k, x] of Object.entries(o)) {
+            const r = read(x);
+            if (r === undefined)
+                return undefined;
+            out.push([k, r]);
+        }
+        return Object.fromEntries(out);
+    };
+}
+function drop(member, why) {
+    return dropProjectedFace("prompt_assembled." + member + " " + why);
+}
+function rowsOf(member, read) {
+    return (v) => {
+        if (!Array.isArray(v))
+            return undefined;
+        const out = [];
+        for (const x of v) {
+            const r = read(x);
+            if (r === undefined)
+                drop(`${member}[]`, "element does not read as the engine's type");
+            else
+                out.push(r);
+        }
+        return v.length > 0 && out.length === 0 ? ABSENT : out;
     };
 }
+const readIdentity = objectOf({
+    artifact: text,
+    layers: objectOf({ catalog: text, renderers: entriesOf(finite), center: optional(text), deploy: optional(text), task: optional(text), binding: text }),
+    epoch: finite,
+    activatedBy: text,
+});
+const readSelectors = objectOf({
+    binding: optional(text),
+    traits: listOf(text),
+    host: objectOf({ role: text, form: text }),
+    facts: entriesOf(flag),
+});
+const readSection = objectOf({
+    id: text,
+    band: text,
+    rank: finite,
+    variant: optional(text),
+    renderer: optional(objectOf({ id: text, version: finite })),
+    chars: finite,
+    locale: text,
+    contentHash: text,
+    chain: listOf(objectOf({ source: text, overlay: optional(text), op: optional(text), superseded: optional(onlyTrue) })),
+});
+const ROW = {
+    identity: readIdentity,
+    selectors: readSelectors,
+    blocks: rowsOf("blocks", objectOf({ id: text, chars: finite, hash: text })),
+    sections: rowsOf("sections", readSection),
+    superseded: rowsOf("superseded", objectOf({ id: text, source: text, by: text, target: text, supersededBy: text })),
+    tools: rowsOf("tools", objectOf({ wireName: text, aliases: listOf(text), contractId: text, implementationRevision: text, cardId: text, shapeDigest: text, wireSchemaDigest: text })),
+    toolDisclosure: objectOf({ deferredTools: finite, strategy: text, source: text }),
+    totalChars: finite,
+};
+export function promptManifestRecordOf(e) {
+    const out = {};
+    for (const [member, read] of Object.entries(ROW)) {
+        const v = e[member];
+        if (v === undefined)
+            continue;
+        const r = read(v);
+        if (r === undefined)
+            drop(member, "does not read as the engine's type");
+        else if (r !== ABSENT)
+            out[member] = r;
+    }
+    return out;
+}
 export function configAssembledRecordOf(e) {
     const rec = {
         catalogVersion: e.catalogVersion,

package/dist/observability/run-terminal.js

@@ -206,19 +206,20 @@ function redactStringLeaves(node, depth = 0) {
     }
     return out ?? node;
 }
+const OFF_ARM_MEMBER_TREATMENT = "free-text-tree";
+const redactDetailMember = (v) => redactStringLeaves(v, 1);
 function shapeTerminalFailureDetail(detail) {
     if (detail === null || typeof detail !== "object" || Array.isArray(detail))
         return detail;
     const d = detail;
     const kind = d.kind;
-    const table = typeof kind === "string" && Object.hasOwn(TERMINAL_FAILURE_DETAIL_TREATMENT, kind) ? TERMINAL_FAILURE_DETAIL_TREATMENT[kind] : undefined;
-    if (table === undefined)
-        return redactStringLeaves(d);
+    const arm = typeof kind === "string" && Object.hasOwn(TERMINAL_FAILURE_DETAIL_TREATMENT, kind) ? TERMINAL_FAILURE_DETAIL_TREATMENT[kind] : {};
     let out;
-    for (const [key, treatment] of Object.entries(table)) {
+    for (const key of Object.keys(d)) {
         const v = d[key];
         if (v === undefined)
             continue;
+        const treatment = Object.hasOwn(arm, key) ? arm[key] : OFF_ARM_MEMBER_TREATMENT;
         switch (treatment) {
             case "verbatim":
             case "provider-join-key":
@@ -228,7 +229,7 @@ function shapeTerminalFailureDetail(detail) {
                     delete (out ??= { ...d })[key];
                 break;
             case "free-text-tree": {
-                const nv = redactStringLeaves(v);
+                const nv = redactDetailMember(v);
                 if (nv !== v)
                     (out ??= { ...d })[key] = nv;
                 break;
@@ -251,10 +252,11 @@ function shapeTerminalBlockedDetail(detail) {
         return detail;
     const d = detail;
     let out;
-    for (const [key, treatment] of Object.entries(TERMINAL_BLOCKED_DETAIL_TREATMENT)) {
+    for (const key of Object.keys(d)) {
         const v = d[key];
         if (v === undefined)
             continue;
+        const treatment = Object.hasOwn(TERMINAL_BLOCKED_DETAIL_TREATMENT, key) ? TERMINAL_BLOCKED_DETAIL_TREATMENT[key] : OFF_ARM_MEMBER_TREATMENT;
         switch (treatment) {
             case "verbatim":
                 break;
@@ -265,6 +267,12 @@ function shapeTerminalBlockedDetail(detail) {
                         (out ??= { ...d })[key] = next;
                 }
                 break;
+            case "free-text-tree": {
+                const nv = redactDetailMember(v);
+                if (nv !== v)
+                    (out ??= { ...d })[key] = nv;
+                break;
+            }
             default: {
                 const unhandled = treatment;
                 throw new Error(`unhandled blocked-detail treatment: ${String(unhandled)}`);

package/dist/observability/secret-env-scrub.d.ts

@@ -49,10 +49,22 @@ export interface SecretEnvScrubSiteSpec {
 }
 /** 登记过的剥除现场。闭集:未登记的 site 传不进 {@link recordSecretEnvScrub}(编译期拒,同 FAIL_OPEN_TAGS 纪律)。 */
 export declare const SECRET_ENV_SCRUB_SITES: {
-    readonly "server.remote-env-host.inherit-scrub": {
+    readonly "server.remote-env-host.spawn-env": {
         readonly note: "模型可驱动的 host shell 继承 env(`inheritEnv` 三词任一,缺省 `\"scrub\"`;`\"all\"` 词下扣的只有本服务自己的凭据名)——这条腿上的一次泄漏等于把编排器的脑钥/仓库令牌交给模型选的命令";
         readonly remedy: null;
     };
+    readonly "server.remote-env-local-docker.spawn-env": {
+        readonly note: "local-docker 车道交给宿主 `docker` CLI 的 env(它拉起的凭据助手 / CLI 插件同读)—— 继承词 `\"all\"`,扣的只有本服务自己的凭据;一次泄漏等于把本服务凭据交给宿主上的第三方助手";
+        readonly remedy: null;
+    };
+    readonly "server.remote-env-adb.spawn-env": {
+        readonly note: "adb 车道交给宿主 `adb` CLI 的 env(首次调用起的常驻 adb server 继承同一份并一直活着)—— 继承词 `\"all\"`,扣的只有本服务自己的凭据;一次泄漏等于把本服务凭据留在一只常驻进程的环境里";
+        readonly remedy: null;
+    };
+    readonly "server.hooks.spawn-env": {
+        readonly note: "settings hooks 的命令腿(请求带来的命令跑在宿主上)的 env —— 严格名单(`PATH` / `HOME` / 终端 / locale 等十二名)经引擎组合,名单外一律不交;请求显式给的 `settings.env` 另叠在上面";
+        readonly remedy: null;
+    };
     readonly "server.project-memory.git-subprocess": {
         readonly note: "project-memory 读仓叙事时的 git 子进程 env —— 仓内的钩子/凭证助手会以本进程身份运行";
         readonly remedy: null;

package/dist/observability/secret-env-scrub.js

@@ -1,10 +1,22 @@
 import { summarizeRedactions } from "@sema-agent/core";
 import { describeAllowlistPostures } from "../env-name-allowlist-knobs.js";
 export const SECRET_ENV_SCRUB_SITES = {
-    "server.remote-env-host.inherit-scrub": {
+    "server.remote-env-host.spawn-env": {
         note: "模型可驱动的 host shell 继承 env(`inheritEnv` 三词任一,缺省 `\"scrub\"`;`\"all\"` 词下扣的只有本服务自己的凭据名)——这条腿上的一次泄漏等于把编排器的脑钥/仓库令牌交给模型选的命令",
         remedy: null,
     },
+    "server.remote-env-local-docker.spawn-env": {
+        note: "local-docker 车道交给宿主 `docker` CLI 的 env(它拉起的凭据助手 / CLI 插件同读)—— 继承词 `\"all\"`,扣的只有本服务自己的凭据;一次泄漏等于把本服务凭据交给宿主上的第三方助手",
+        remedy: null,
+    },
+    "server.remote-env-adb.spawn-env": {
+        note: "adb 车道交给宿主 `adb` CLI 的 env(首次调用起的常驻 adb server 继承同一份并一直活着)—— 继承词 `\"all\"`,扣的只有本服务自己的凭据;一次泄漏等于把本服务凭据留在一只常驻进程的环境里",
+        remedy: null,
+    },
+    "server.hooks.spawn-env": {
+        note: "settings hooks 的命令腿(请求带来的命令跑在宿主上)的 env —— 严格名单(`PATH` / `HOME` / 终端 / locale 等十二名)经引擎组合,名单外一律不交;请求显式给的 `settings.env` 另叠在上面",
+        remedy: null,
+    },
     "server.project-memory.git-subprocess": {
         note: "project-memory 读仓叙事时的 git 子进程 env —— 仓内的钩子/凭证助手会以本进程身份运行",
         remedy: null,

package/dist/observability/tool-trace.d.ts

@@ -1,15 +1,18 @@
-import { type Hooks } from "@sema-agent/core";
+import { type EngineDollar, type ModRegistration } from "@sema-agent/core";
 import type { Logger } from "./logger.js";
 import type { Metrics } from "./metrics.js";
+/** 两张部署注册的名字 —— wire 可见(`wiring_manifest.mods[].name`);名字中性、稳定、不含部署信息。 */
+export declare const PERMISSION_DENIED_METER_REGISTRATION = "server.permission-denied-meter";
+export declare const TOOL_TRACE_REGISTRATION = "server.tool-trace";
 /**
  * ALWAYS-ON gate-deny meter (goal B4, 2026-07-08): `permission_denied_total{deniedBy}` — how often the
  * adjudicate chain DENIES a tool call, by the LAYER whose verdict is the deny. Deliberately SEPARATE from
  * {@link createToolTracer}: the tracer is a default-OFF diagnostic (TOOL_TRACE=true), but deny frequency is an
  * operational/security signal that must reach /metrics on every deployment — a spike in `deniedBy="policy"`
  * means a task keeps asking for something the operator forbids; `deniedBy="org"` is the organization layer
- * refusing, the one class an operator most wants to see on its own. main.ts composes this UNDER the tracer via
- * composeHooks (both are void observers on the permissionDenied slot, which composeHooks double-runs
- * deployment-first).
+ * refusing, the one class an operator most wants to see on its own. It is the deployment seat's first registration
+ * (`createDeploymentMods`, `boot/deployment-mods.ts`): an observer on `classic.PermissionDenied`, run before the tracer's observer on the same
+ * event (the engine runs observers by tier, then deployment before task, then each seat's own order).
  *
  * 🔴 BREAKING(server 7.64.0,core 7.6.0 提货):标签名 `source` → `deniedBy`,词表从七词
  * (`policy/hook/safety/shellGate/planMode/classifier/org`)换成八词
@@ -46,7 +49,7 @@ import type { Metrics } from "./metrics.js";
  *  · **计数总量方向**:新座只在「分类器那一轮没有裁决」时在场(`<block>yes` 的真裁决恒缺席),与旧座的
  *    「分类器停摆」同向;多出来的那一格是 `parse_error`,它也确实是「分类器没正常工作」的一种。
  */
-export declare function createPermissionDeniedMeter(metrics: Pick<Metrics, "inc">): Hooks;
+export declare function createPermissionDeniedMeter(metrics: Pick<Metrics, "inc">): ModRegistration<EngineDollar>;
 /**
  * prove-before-scale stopgap ([ref]): a no-op observer hook that logs every tool call (pre + post)
  * to the worker log — INCLUDING resumed legs that `GET /v1/runs/:id/events` does NOT surface (the
@@ -59,21 +62,13 @@ export declare function createPermissionDeniedMeter(metrics: Pick<Metrics, "inc"
  * the full sequence: a repeated `write_file path=X contentLen=Y` across resumes ⇒ restart-loop;
  * write X → write Y → bash ⇒ iteration.
  *
- * Pure observation: every hook returns `undefined`, so it never rewrites args, never gates, never alters
- * the result (and per core's hooks invariant a hook's `allow` can't bypass the policy gate anyway).
- *
- * 🔴 core 5.20.0 起这条「纯观察」性质必须**声明**出来(`preToolUseObservational`),不能只写在注释里:
- * core 5.19.0 的委派折叠按「PreToolUse 席位在不在」把父的 screening 面折进子代的祖先约束链——它分不出
- * 诊断 tracer 与真裁决者。后果是**这个默认关的诊断旋钮**一开,该部署所有 hook-wired 父的 parked 子代
- * checkpoint 就记 `parentConstraintCount=2`,而跨副本赎回腿(`boot/parked-revive-gate.ts`)恒供 1 ⇒
- * core pre-CAS 响亮拒、行永久 pending(层数 park 时写死,事后关旋钮/重批/回滚都不改)。
- * 声明之后该面不铸链条目,count 回到 1,病路消灭。
- * ⛔ 打这个标的前提是**真的一条裁决都不出**:core 对声明了却返回判词的面是「拒绝采纳 + onError 告警」
- * (classification `observational-hook-verdict-ignored`),即判词被静默丢弃——把标打到会裁决的面上比原
- * 缺陷更坏。本文件三个 pre/post 回调恒返 `undefined`,`permissionDenied` 本就是 void 观察槽。
- * 📎 连带的**可观测**变化(不是回归):core 的「可写工具面无 effect-aware 门」启动告警此前把本 tracer
- * 算作一道门而被抑制;声明之后它不再算,于是「没配任何 policy 层 + 开着 TOOL_TRACE」的部署升级后会
- * 多出那行告警。方向正确——tracer 从来没有门住任何东西,原先的抑制本身就是一次静默 fail-open。
+ * Pure observation: every handler is an observer (`{ observe: true }`, via {@link observeClassic}) — a detached copy of
+ * the event, outside the chain, its answer never adopted — so it never rewrites args, never gates, never alters the result.
+ * Being an observer is also what keeps it out of a delegated child's inherited constraint: the engine mints a screening
+ * entry only from a chain that JUDGES, so turning this diagnostic switch on adds no `parentConstraintCount` to a parked
+ * child of a hook-wired parent (the cross-replica revive leg, `boot/parked-revive-gate.ts`, supplies the caller policy only).
+ * 📎 Not a gate either for the engine's "writable tool face without an effect-aware gate" startup warning: a deployment with
+ * no policy layer and `TOOL_TRACE` on still gets that warning — the tracer never gated anything.
  */
-export declare function createToolTracer(logger: Logger): Hooks;
+export declare function createToolTracer(logger: Logger): ModRegistration<EngineDollar>;
 //# sourceMappingURL=tool-trace.d.ts.map

package/dist/observability/tool-trace.js

@@ -1,60 +1,69 @@
 import { isClassifierDenyCause, isDeniedBy } from "@sema-agent/core";
+import { observeClassic } from "../hooks/classic-stations.js";
 import { redactSecrets } from "../trace/redact.js";
+export const PERMISSION_DENIED_METER_REGISTRATION = "server.permission-denied-meter";
+export const TOOL_TRACE_REGISTRATION = "server.tool-trace";
 function deniedByLabel(gate) {
     const d = gate.disposition;
     return d.kind === "denied" && isDeniedBy(d.deniedBy) ? d.deniedBy : "other";
 }
 export function createPermissionDeniedMeter(metrics) {
     return {
-        permissionDenied(payload) {
-            metrics.inc("permission_denied_total", { deniedBy: deniedByLabel(payload.gate) });
-            const disposition = payload.gate?.disposition;
-            const cause = disposition?.kind === "denied" ? disposition.cause : undefined;
-            if (cause !== undefined) {
-                metrics.inc("auto_mode_classifier_deny_cause_total", { cause: isClassifierDenyCause(cause) ? cause : "other" });
-            }
+        name: PERMISSION_DENIED_METER_REGISTRATION,
+        tier: "prepend",
+        uses: { events: ["classic.PermissionDenied"], calls: [] },
+        register(on) {
+            observeClassic(on, "classic.PermissionDenied", (payload) => {
+                metrics.inc("permission_denied_total", { deniedBy: deniedByLabel(payload.gate) });
+                const disposition = payload.gate?.disposition;
+                const cause = disposition?.kind === "denied" ? disposition.cause : undefined;
+                if (cause !== undefined) {
+                    metrics.inc("auto_mode_classifier_deny_cause_total", { cause: isClassifierDenyCause(cause) ? cause : "other" });
+                }
+            });
         },
     };
 }
 export function createToolTracer(logger) {
     return {
-        preToolUseObservational: true,
-        preToolUse(toolName, input, ctx) {
-            logger.info("tool_trace", { phase: "pre", id: ctx.toolCallId, tool: toolName, arg: summarize(input) });
-            return undefined;
-        },
-        postToolUse(toolName, _input, output, ctx) {
-            logger.info("tool_trace", {
-                phase: "post",
-                id: ctx.toolCallId,
-                tool: toolName,
-                isError: output.isError,
-                out: textOf(output.content),
+        name: TOOL_TRACE_REGISTRATION,
+        tier: "prepend",
+        uses: { events: ["classic.PreToolUse", "classic.PostToolUse", "classic.PostToolUseFailure", "classic.PermissionDenied"], calls: [] },
+        register(on) {
+            observeClassic(on, "classic.PreToolUse", (e) => {
+                logger.info("tool_trace", { phase: "pre", id: e.tool_use_id, tool: e.tool, arg: summarize(e.input) });
             });
-            return undefined;
-        },
-        postToolUseFailure(toolName, _input, failure, ctx) {
-            logger.info("tool_trace", {
-                phase: "post",
-                id: ctx.toolCallId,
-                tool: toolName,
-                isError: true,
-                isInterrupt: failure.isInterrupt,
-                ...(failure.durationMs !== undefined ? { durationMs: failure.durationMs } : {}),
-                out: clip(redactSecrets(failure.error), 200),
+            observeClassic(on, "classic.PostToolUse", (e) => {
+                logger.info("tool_trace", {
+                    phase: "post",
+                    id: e.tool_use_id,
+                    tool: e.tool,
+                    isError: e.output.isError,
+                    out: textOf(e.output.content),
+                });
             });
-            return undefined;
-        },
-        permissionDenied(payload) {
-            logger.info("tool_trace", {
-                phase: "denied",
-                id: payload.toolCallId,
-                tool: payload.toolName,
-                deniedBy: deniedByLabel(payload.gate),
-                ...(payload.gate.origin === undefined ? {} : { origin: payload.gate.origin }),
-                ...(payload.gate.settlement === undefined ? {} : { settlement: payload.gate.settlement.kind }),
-                reason: clip(redactSecrets(payload.reason), 200),
-                arg: summarize(payload.input),
+            observeClassic(on, "classic.PostToolUseFailure", (e) => {
+                logger.info("tool_trace", {
+                    phase: "post",
+                    id: e.tool_use_id,
+                    tool: e.tool,
+                    isError: true,
+                    isInterrupt: e.failure.isInterrupt,
+                    ...(e.failure.durationMs !== undefined ? { durationMs: e.failure.durationMs } : {}),
+                    out: clip(redactSecrets(e.failure.error), 200),
+                });
+            });
+            observeClassic(on, "classic.PermissionDenied", (payload) => {
+                logger.info("tool_trace", {
+                    phase: "denied",
+                    id: payload.toolCallId,
+                    tool: payload.toolName,
+                    deniedBy: deniedByLabel(payload.gate),
+                    ...(payload.gate.origin === undefined ? {} : { origin: payload.gate.origin }),
+                    ...(payload.gate.settlement === undefined ? {} : { settlement: payload.gate.settlement.kind }),
+                    reason: clip(redactSecrets(payload.reason), 200),
+                    arg: summarize(payload.input),
+                });
             });
         },
     };

package/dist/per-task-image.d.ts

@@ -4,13 +4,19 @@ import type { ImageViewer, ImageIndexEntry } from "./plugins/store-contracts.js"
 export interface SandboxImageResolver {
     latestPublished(profile: string, viewer: ImageViewer): Promise<Pick<ImageIndexEntry, "repo" | "digest" | "capabilities"> | null>;
 }
+/**
+ * 解析失败的机读码(闭集):`not_found.image` = 按调用方的约束(档案 · 本主体可见 · 已发布 · 所需能力)找不到镜像 —— 与 `POST /v1/images/select`
+ * 「没有可见的已发布镜像」同一个码(同一个事实);`request.field_invalid` = `capabilitiesNeeded` 里有不认识的能力词。状态随码,一码一状态。
+ */
+export type SandboxImageRefusalCode = "not_found.image" | "request.field_invalid";
 export type SandboxImageResolution = {
     ok: true;
     ref: string;
     capabilities?: import("./plugins/store-contracts.js").ImageCapabilities;
 } | {
     ok: false;
-    status: number;
+    status: 404 | 400;
+    errorCode: SandboxImageRefusalCode;
     message: string;
 };
 /**

package/dist/per-task-image.js

@@ -3,15 +3,15 @@ const REQUESTABLE_CAPS = new Set(["browser", "db", "nestedBuild"]);
 export async function resolveSandboxImageRef(opts) {
     const entry = await opts.index.latestPublished(opts.profile, opts.viewer);
     if (!entry) {
-        return { ok: false, status: 404, message: `no published sandbox image for profile "${opts.profile}" visible to this principal` };
+        return { ok: false, status: 404, errorCode: "not_found.image", message: `no published sandbox image for profile "${opts.profile}" visible to this principal` };
     }
     const caps = entry.capabilities;
     for (const cap of opts.capabilitiesNeeded ?? []) {
         if (!REQUESTABLE_CAPS.has(cap)) {
-            return { ok: false, status: 400, message: `unknown sandbox capability "${cap}" (allowed: ${[...REQUESTABLE_CAPS].join(", ")})` };
+            return { ok: false, status: 400, errorCode: "request.field_invalid", message: `unknown sandbox capability "${cap}" (allowed: ${[...REQUESTABLE_CAPS].join(", ")})` };
         }
         if (caps[cap] !== true) {
-            return { ok: false, status: 404, message: `sandbox image for profile "${opts.profile}" does not provide capability "${cap}"` };
+            return { ok: false, status: 404, errorCode: "not_found.image", message: `sandbox image for profile "${opts.profile}" does not provide capability "${cap}"` };
         }
     }
     return { ok: true, ref: `${entry.repo}@${entry.digest}`, capabilities: entry.capabilities };