@sema-agent/core 5.20.0 → 5.21.0

package/dist/core/runner/usage-accounting.d.ts

@@ -1,17 +1,49 @@
 import type { Model } from "../../internal/llm.js";
 import { type ModelPricing } from "../pricing.js";
+/** How a provider counts cached tokens in its reported `input`. */
 export type CacheFamily = "input-includes-cached" | "input-excludes-cached";
+/**
+ * Resolve the prompt-cache accounting family for a model. **Auto-inferred from `model.api`** by
+ * default (Anthropic/Bedrock report `input` EXCLUDING cached tokens; OpenAI/vLLM/Google INCLUDE them),
+ * but a deployment can **override** it via `model.params.promptCacheFamily` when `model.api` doesn't
+ * match the brain that actually serves the model — e.g. a routing brain that dispatches by `provider`
+ * while `api` is left at a default. Accepts the explicit values or the aliases `"anthropic"`/`"openai"`.
+ * (design/18: a route-by-provider setup with `api` hardcoded misjudged the family → 1090% hit rate.)
+ */
 export declare function cacheFamilyOf(model: Model): CacheFamily;
+/** Total prompt tokens presented this turn, normalized so `cachedTokens` is always ⊆ the total. */
 export declare function promptTokensOf(family: CacheFamily, u: {
     input: number;
     cacheRead: number;
     cacheWrite: number;
 }): number;
+/**
+ * The prompt tokens that were NOT served from (or written to) the cache this turn — i.e. the quantity
+ * the Anthropic protocol calls `usage.input_tokens`, normalized across families. Derived from the
+ * normalized total so the identity `total = uncached + cacheRead + cacheWrite` holds by construction.
+ *
+ * RB-457-a: the wire faces named `inputTokens`/`promptTokens` carry THIS, not the total — a consumer
+ * computing `cacheRead / (input + cacheRead)` on a same-named protocol field otherwise double-counts
+ * the cache subset and reports `h/(1+h)` (a real 98% hit rate surfaces as 49.5%). The BILLING path
+ * still consumes the total (`promptTokensOf`) — `computeCostMicroUsd` subtracts the priced subsets
+ * itself, so handing it the uncached figure would drop the cache legs from the bill entirely.
+ *
+ * Clamped at 0: when a provider reports subsets LARGER than its own total the cache family is
+ * misdeclared (design/18), which the run loop already reports on its own face; here the identity
+ * degrades to `total ≤ uncached + cacheRead + cacheWrite` rather than going negative.
+ */
 export declare function uncachedInputTokensOf(family: CacheFamily, u: {
     input: number;
     cacheRead: number;
     cacheWrite: number;
 }): number;
+/**
+ * Normalize one turn's reported usage into its `{ totalInputTokens, uncachedInputTokens, costMicroUsd }`
+ * — the authoritative cost re-priced in core from injected pricing (so cached tokens aren't charged at
+ * full price). Shared by the run loop's per-turn accounting and post-task memory consolidation
+ * (design/41) so a pricing change lives in ONE place. We emit only 5-min-TTL cache writes, so
+ * `cacheWriteTokensLong` is 0.
+ */
 export declare function usageCostMicroUsd(family: CacheFamily, u: {
     input?: number;
     output?: number;

package/dist/core/runtime.d.ts

@@ -1,3 +1,12 @@
 import type { AgentCoreRuntimeDeps } from "../internal/harness-types.js";
 import type { Brain } from "./types.js";
+/**
+ * Build the agent-core runtime dependency object from a Brain.
+ * `completeSimple` (used by compaction/summarization) is derived from `stream`
+ * when the brain does not provide one explicitly.
+ *
+ * A supplied `brain.complete` is forwarded BY REFERENCE, never re-wrapped: the summary path's
+ * budget-escalation recovery keys on `errorKind`, so anything that rebuilt the message here would
+ * disable that recovery for every brain at once (pinned in `brain-complete-contract.test.ts`).
+ */
 export declare function brainToRuntime(brain: Brain): AgentCoreRuntimeDeps;

package/dist/core/safe-notify.d.ts

@@ -1,17 +1,81 @@
+/**
+ * RB-463 — host-callback isolation, one primitive.
+ *
+ * The invariant "a callback the HOST handed us must never take the engine down" was implemented by hand at
+ * ~20 sites across 10 modules (observer taps, cascade/verify observability hooks, roster eviction sinks, the
+ * retain ledger's eviction reporter, task-registry reap/quiescence/terminal notifiers, compaction observers,
+ * the workflow event sink, the tool gate's deny observers). Every one of them was a correct swallow, but the
+ * DISCLOSURE grade differed per site: the retain ledger counted its failures and offered them on a dedicated
+ * channel, while the cascade and the roster store swallowed in total silence — so a deployment whose observer
+ * is broken had no way to find out, and WHICH sites would tell it was a matter of which module it happened to
+ * touch.
+ *
+ * This module is the single implementation those sites now share. Semantics:
+ *  · SWALLOW — the callback's throw never reaches the engine's control flow (unchanged at every site);
+ *  · COUNT — every failure is counted per site, readable for diagnostics ({@link SafeNotifier.failuresAt});
+ *  · BOUNDED DISCLOSURE — the FIRST failure of each site is offered to an optional `onError`, later ones are
+ *    counted only. A hot path whose sink fails on every call therefore reports once, never floods.
+ *
+ * WIRING STATUS (RB-473, batches 1/2a/2b landed 2026-08-02): the disclosure channel is now WIRED at the
+ * owners a deployment can reach — TaskRegistry offers `notifierFailureCounts()` (read face; it is
+ * constructed before any deployment sink exists), the delegation tool routes into `opts.onObserverError`
+ * (site attached), auto-compaction / cascade / verify / roster-store take an `onNotifyError` option, the
+ * tool gate surfaces failures as `observer.notify_failed` trace events, and the workflow options + the
+ * SendMessage resume face take `onNotifyError`. Remaining unwired scopes (retain ledger `failuresAt`
+ * read-face only, observer taps, misc subagent internals) disclose via counts.
+ *
+ * State discipline: no module-level mutable state. Counters live on the notifier instance the owner created
+ * (per class instance, or per call for the run-scoped functions), so two runs — and two tests — can never see
+ * each other's counts.
+ *
+ * WHY A THUNK and not `(fn, ...args)`: almost every site reads its callback off a host-owned object
+ * (`config.onRung?.(info)`, `opts.onEvicted?.(e)`). `?.()` on a property calls it with THAT OBJECT as the
+ * receiver, so a host that passed a method using `this` works today. Handing the extracted function value to
+ * a helper would silently re-bind the receiver to `undefined` — an invisible behavior change at ~20 sites.
+ * The thunk keeps the call expression (and its `?.`) at the site, byte-for-byte what it was.
+ *
+ * Scope note (deliberate parity): a callback typed `=> void` that instead returns a REJECTING promise is not
+ * contained by {@link SafeNotifier.notify} — it is synchronous and never touches the return value, exactly
+ * like the hand-written try/catch it replaced. Sites that genuinely await their callback use
+ * {@link SafeNotifier.notifyAsync}.
+ */
+/** One contained failure, as offered to {@link SafeNotifierOptions.onError}. */
 export interface SafeNotifyFailure {
+    /** The owner-chosen site name (e.g. `"cascade.onRung"`) — a stable literal, never derived from host input. */
     readonly site: string;
+    /** The thrown value, normalized to an `Error`. */
     readonly error: Error;
+    /** This site's cumulative failure count including this one (always 1 for a disclosed failure). */
     readonly failures: number;
 }
 export interface SafeNotifierOptions {
+    /**
+     * Optional disclosure channel: called with the FIRST failure of each site (bounded — later failures of the
+     * same site are counted only). A throw from `onError` itself is swallowed: the disclosure channel is host
+     * code too, and it must not become a second fault source.
+     */
     readonly onError?: (failure: SafeNotifyFailure) => void;
 }
 export interface SafeNotifier {
+    /**
+     * Run one host-callback invocation, containing any throw. Returns `true` when it completed, `false` when it
+     * threw. The thunk normally holds the original optional call (`() => config.onRung?.(info)`), so an absent
+     * callback is a plain no-op that never touches the failure bookkeeping.
+     */
     notify(run: () => void, site: string): boolean;
+    /** {@link notify} for a site that AWAITS its callback — contains a rejection as well as a synchronous throw. */
     notifyAsync(run: () => unknown, site: string): Promise<boolean>;
+    /** Total contained failures across all sites of this notifier. */
     readonly failures: number;
+    /** Contained failures at one site (0 when that site never failed). */
     failuresAt(site: string): number;
+    /** The most recent contained error at one site, if any. */
     lastErrorAt(site: string): Error | undefined;
+    /** The sites that have failed at least once (diagnostics; empty on the healthy path). */
     failedSites(): readonly string[];
 }
+/**
+ * Create an isolation scope for host callbacks. Cheap: the failure bookkeeping is allocated lazily, so a
+ * notifier whose callbacks never throw costs one object and nothing per call beyond the `try`.
+ */
 export declare function createSafeNotifier(opts?: SafeNotifierOptions): SafeNotifier;

package/dist/core/safety-axis-vocab.d.ts

@@ -1,9 +1,32 @@
+/**
+ * `SAFETY_AXIS_VOCABULARY` — the PUBLISHED safety-axis vocabulary as a zero-logic, zero-runtime-dependency DATA
+ * artifact (pure string / number / boolean literal constants).
+ *
+ * **design/99 center control-plane seam (2026-06-27).** The sema-registry control plane's per-field
+ * safety-classification table lives in `@sema-agent/registry-core` and, for every safety-critical config field, cites a
+ * core axis VALUE (e.g. `effect: "write"`, `irreversibility: "always"`). That contract package **must not depend on
+ * `@sema-agent/core` (the engine) at runtime** — so it dev-imports THIS const (test-only) and runs a conformance test
+ * asserting every `coreAxis` string it ships is a legal value here, failing CI if core ever drops / renames one.
+ *
+ * Anti-drift discipline (mirrors {@link import("./safety-merge-corpus.js").SAFETY_MERGE_CONFORMANCE_CORPUS}, design/87):
+ * the arrays are pinned to the engine's safety-axis source unions; `test/safety-axis-vocab.test.ts` regression-tests
+ * them in lockstep with the engine version, and the `_AssertEqual` below fails `tsc` if `toolEffect` drifts from the
+ * {@link ToolEffect} union (either direction). The const carries NO logic and imports NO runtime value — the emitted
+ * JS is pure data, so a consumer can `JSON`-shaped-read it without pulling any engine code.
+ */
 export declare const SAFETY_AXIS_VOCABULARY: {
+    /** `ToolSpec.effect` — the data-flow effect class ({@link ToolEffect}, types.ts:74). */
     readonly toolEffect: readonly ["read", "write", "idempotent"];
+    /** `ToolSpec.egress` — marks an external write (push / open PR / send a message). */
     readonly egress: readonly [true, false];
+    /** `ToolSpec.irreversibility` — reversibility class (types.ts:128; the `toolAxes` record uses the {never,always} subset). */
     readonly irreversibility: readonly ["never", "maybe", "always"];
+    /** `SafetyAxis` keys — which axes a gated call trips, for the escalation inbox (checkpoint-store.ts). */
     readonly safetyAxis: readonly ["egress", "irreversible", "shell"];
+    /** `RiskDescriptor.severity` — ToolEmu-style tier (5 = most severe), the inbox triage key (checkpoint-store.ts:85). */
     readonly severity: readonly [1, 2, 3, 4, 5];
+    /** `TaskSpec.shellGate` — deployment shell-command gate rank, `off` < `classify` < `always` (types.ts:632). */
     readonly shellGate: readonly ["off", "classify", "always"];
+    /** `ToolPolicy` decision — per-tool adjudication; `deny` short-circuits the `deny > ask > allow` fold (tool-policy.ts). */
     readonly permissionDecision: readonly ["allow", "ask", "deny"];
 };

package/dist/core/safety-merge-corpus.d.ts

@@ -1,10 +1,47 @@
 import type { SessionPermissionRules } from "./session-policy-store.js";
+/**
+ * design/99 (sema-registry center control-plane seam, channel review R2): the PUBLISHED golden conformance corpus
+ * for the safety-domain MERGE predicate {@link loosenReasons}.
+ *
+ * THE SEAM. The center control-plane's ConfigBundle merger is a DISPATCHER: for any field it classifies
+ * safety-critical (the permissions / tool-policy domain), it MUST delegate the org-published-vs-workspace-override
+ * decision to core's {@link loosenReasons} (NOT re-implement "deny>allow" — a forked safety law is the exact
+ * "mixed = security incident" failure). Core owns the safety SEMANTICS; center owns the bundle merger that calls it.
+ *
+ * THIS CORPUS is the anti-drift anchor between the two codebases (the design/87 gold-corpus discipline):
+ *  - CORE runs it as a regression test (`test/safety-merge-corpus.test.ts`) — every vector's `reasons` MUST equal
+ *    `loosenReasons(prior, next)`. If core ever changes the loosen law, this test fails and the corpus updates in
+ *    lockstep with the engine version, so the published contract can never silently drift from the implementation.
+ *  - The CENTER imports this corpus from `@sema-agent/core` and runs it as a CONTRACT test in its merger CI: for each
+ *    vector, its merger's accept/reject of a non-operator workspace override on the permissions domain MUST match
+ *    `loosens` (reject iff `loosens`). That proves center's dispatcher actually routes through core's predicate.
+ *
+ * Invariant under test: a workspace override that LOOSENS an org-published safety rule (removes a deny, widens an
+ * allowlist, removes/widens a path confinement) is a tighten-only violation — `loosens === true`, and a
+ * non-operator write of it MUST be rejected. A pure tighten / no-op is `loosens === false`.
+ */
 export interface SafetyMergeVector {
+    /** Stable case id (appears in test output + the published contract). */
     name: string;
+    /** What this vector proves. */
     intent: string;
+    /** The org-published baseline (the lower, authoritative layer). */
     prior: SessionPermissionRules;
+    /** The proposed workspace-override (the upper layer being merged down). */
     next: SessionPermissionRules;
+    /** Whether `next` LOOSENS `prior` — true ⇒ a non-operator merge of this override MUST be rejected. */
     loosens: boolean;
+    /** The EXACT reasons {@link loosenReasons}(prior, next) returns (compared order-insensitively). Empty iff
+     *  `loosens` is false. Pinned so CORE's regression test catches a change in the loosen SEMANTICS, not just the
+     *  boolean. ⚠️ CENTER CONTRACT: depend ONLY on `loosens` (reject-iff-loosens) — `reasons` is core's internal
+     *  message wording, anti-drift for core; a center CI that asserts on `reasons` would break on a core reword. On
+     *  ACCEPT (`loosens === false`) the resolved safety-domain value is `next` (the tightened override applied). */
     reasons: string[];
 }
+/**
+ * The published vectors. Covers every loosen path in {@link loosenReasons} (deny removal, allowlist widen, allowlist
+ * removal = all-allowed, path-confinement removal, path widen, and a multi-axis loosen) plus the tighten / safe /
+ * no-op cases (adding a deny, narrowing an allowlist, narrowing-to-a-subdir, adding confinement from none, identical,
+ * empty). Extend it as the safety domain grows — both core and center re-run it.
+ */
 export declare const SAFETY_MERGE_CONFORMANCE_CORPUS: readonly SafetyMergeVector[];

package/dist/core/scheduler.d.ts

@@ -1,15 +1,39 @@
+/**
+ * design/105 — Scheduler seam（自唤醒/自调度）。「手」腿（`ExecutionEnv`）的**跨-task** 未来意图能力：一个 run 里的模型
+ * 把「未来要做的活」（cron 排程 / 延迟唤醒）持久化交给一个**常驻 backend**（TOC = shell daemon），由它在未来重起一个
+ * **新** task。
+ *
+ * 🔴 与 {@link import("./background-shell.js").BackgroundShellCapability} 的根本区别（design/105 §3.1 D1）：
+ * background-shell 的进程 ⊆ task（在每条退出路径 dispose，不跨 suspend）；scheduler 的意图必须 **SURVIVE task 结束**
+ * （schedule 的全部意义就是当前 task 结束后 daemon 还能重起）——镜像反转，**绝不 dispose-on-exit**。
+ *
+ * core 薄壳裁定：core 只出接口 + 工具壳 + `hasScheduler` 门控；**持久化存储 / cron 时钟 / idle 触发 / 起新 task 全在
+ * backend（daemon）**——core 是 request-driven 不常驻，绝不假装调度器。NodeExecutionEnv 不自带 daemon（不同于
+ * background-shell 自带 spawn），而是**委托一个注入的 backend**（飞轮的 shell daemon 实现本接口）。
+ */
 import type { ExecutionEnv, Result } from "../internal/harness-types.js";
+/** 一个已排未来意图的句柄。**backend-local、durable（daemon 持久化、重启存活）、对调用方不透明** —— 绝不暴露可枚举的 raw id。 */
 export type ScheduledTaskId = string & {
     readonly __brand: "ScheduledTaskId";
 };
+/**
+ * 类型化错误码（对齐 background-shell 风格）。方法 MUST NOT throw（返回 {@link Result}）。
+ */
 export type SchedulerErrorCode = "unsupported" | "not_found" | "limit_exceeded" | "invalid_schedule" | "io";
+/** scheduler 操作的类型化错误。`code` 给程序分类，`message` 给模型自纠。 */
 export declare class SchedulerError extends Error {
     readonly code: SchedulerErrorCode;
     readonly cause?: unknown | undefined;
     constructor(code: SchedulerErrorCode, message: string, cause?: unknown | undefined);
 }
+/**
+ * 🔴 **模型可控面（不可信）**：纯意图，**无任何身份字段** —— 防模型经自排 prompt 提权（design/62 同款红线：身份是
+ * Runner-held，非工具参数）。`prompt` = 未来 task 的不可信 `objective`（daemon 起 task 时经完整 prepare-task gate）。
+ */
 export interface ScheduledIntent {
+    /** 未来要跑的 prompt（agent 自排）。daemon 起新 task 时作 `objective`。 */
     prompt: string;
+    /** 何时触发。`cron`=重复（受 minCronIntervalSec 约束）；`at`=一次性绝对时刻；`delay`=相对延迟（一次性 self re-wake 用）。 */
     when: {
         kind: "cron";
         expr: string;
@@ -20,41 +44,138 @@ export interface ScheduledIntent {
         kind: "delay";
         delaySec: number;
     };
+    /** 可选短标签；与 `(scope, when)` 一起做 upsert 去重键（防工具重试产生重复 intent）。 */
     label?: string;
+    /**
+     * [c209-D2] 生存期维度（durable 分层激活批 2026-07-16；缺省 `"durable"` = 既有行为，零破坏）。
+     * - `"durable"`：daemon 持久化、重启存活、跨会话继续触发——本 seam 的历史唯一语义（intent 不带本字段
+     *   即此义，老 backend 零迁移）。
+     * - `"session"`：会话级易失体（上游同名工具的缺省语义——「会话内过会儿跑一下」，不该活成永生任务）。
+     *   🔴 消费契约（daemon 半场，shell 仓实现）：session intent MUST 随带 `sessionId` 的
+     *   {@link SchedulerContext} 排入（工具壳保证）；该会话终结（正常收束 / 超时 reap / 显式关闭）时 daemon
+     *   MUST 一并 reap 本 intent——绝不让它在会话死后继续触发。不支持本维度的 backend 不会收到 session
+     *   intent：工具壳按 {@link SchedulerCapability} 的 `supportsSessionLifetime` 能力位门控，不支持时对
+     *   session 语义调用诚实拒绝并引导 `durable: true`——**绝不静默升级为永生任务**（本案的整个意义）。
+     */
     lifetime?: "durable" | "session";
+    /**
+     * [c209-D2] `when.kind === "cron"` 专用：`false` = 命中一次即删（上游 recurring:false 语义——触发一次后
+     * 等价一次性 at）；缺省 `true` = 每次 cron 匹配都触发（既有行为，intent 不带本字段即此义）。
+     * 🔴 消费契约（daemon 半场，shell 仓实现）：recurring:false 的 cron intent 首次触发后 daemon MUST 删除
+     * 该 intent，不再排下次。core 侧只把字段进 seam；delay/at kind 与 recurring 同给在工具层 fail-closed 拒
+     * （recurring 只属 cron），故 daemon 只会在 cron intent 上见到本字段。
+     */
     recurring?: boolean;
+    /**
+     * 执行形态（CC ScheduleWakeup 对齐批 2026-07-11；缺省 `"task"` = 既有行为，全向后兼容）。
+     * - `"task"`：daemon 起一个**无上下文新 task**（`prompt` 作 objective，经完整 prepare-task gate）——CronCreate 语义。
+     * - `"session-wakeup"`：daemon **续 `ctx.sessionId` 指定的同一会话**（`prompt` 作该会话下一轮输入；同上下文、
+     *   同 prompt cache）——CC ScheduleWakeup 的 /loop dynamic 语义。🔴 契约：`mode:"session-wakeup"` 的 intent
+     *   MUST 随一个带 `sessionId` 的 {@link SchedulerContext} 排入（工具壳保证）；daemon 触发时 MUST resume 该
+     *   session 而非起新 task，且 principal 原样（不升权）。不支持续会话的 daemon MUST 拒（`invalid_schedule`），
+     *   绝不静默降级成新 task（丢上下文=静默换语义）。
+     */
     mode?: "task" | "session-wakeup";
 }
+/**
+ * 🔴 **Runner-held 可信面**（工具工厂闭包捕获，模型无法触及）。镜像 subagent 经 `ctx.principal` 继承的代码层强制
+ * （`agents/subagent.ts`）。`schedule` 的实现 MUST 把 `principal` 钉死进持久化 intent；daemon 触发时原样传
+ * `runTask({ principal })` —— **不升权、不省略**。
+ */
 export interface SchedulerContext {
+    /**
+     * 越权隔离键（cancel/list 只能操作同 scope 排的）。由 Runner 填，且**按被操作 intent 的 lifetime 分叉**
+     * （ruled 2026-08-03）：`lifetime:"session"` 的意图用会话链（sessionId ?? principal ?? taskId ?? "default"）；
+     * durable 意图用跨会话稳定身份（principal ?? "default"）——否则 durable job 会被钉死在排它的那个会话里，
+     * 后续会话 cancel/list 一律 `not_found`（任务照常触发却再也删不掉）。backend 侧无需分辨腿别：照旧只按
+     * 收到的 `scope` 隔离即可；**同一 daemon 上两类键共存**，一次 `list` 只回本 scope 的行（工具壳自己并两腿）。
+     * ⚠️ 部署面：本分叉之前写下的 durable 行仍带旧的会话键，一次性重铸键归 backend 半场，engine 不做迁移。
+     */
     scope: string;
+    /** 排程者身份；daemon 触发时原样传给 runTask（防提权）。 */
     principal?: string;
+    /** 可选：daemon 触发新 task 时复用的 session（chat-continuity；缺省=fresh-session）。⚠️ 复用需 durable sessionStore（design/105 §3.4）。 */
     sessionId?: string;
+    /**
+     * 可选 opaque 起-task 配置（model/policy 提示）。v1 daemon 可忽略、用部署默认模板起 task（intent.prompt + 继承的
+     * principal 已足）；未来精细化时由 daemon 解释。core 不定其 schema（最薄）。**不可由模型提供**（Runner-held）。
+     */
     taskConfig?: unknown;
 }
+/** {@link SchedulerCapability.list} 的条目：足够 self-discovery + 防重复排，不含完整意图。 */
 export interface ScheduledTaskSummary {
     id: ScheduledTaskId;
+    /** 渲染用：cron expr / at 时刻 / delay 秒 的人读摘要。 */
     when: string;
     label?: string;
+    /** 下次触发的 epoch ms（cron/at 可算；daemon 提供）。 */
     nextRunMs?: number;
+    /** 执行形态回显（{@link ScheduledIntent.mode}）。ScheduleWakeup 的 stop:true 靠它定位要取消的 pending
+     *  wakeup（cron/task 意图不受 stop 影响——CC 206 D9 语义）。老 backend 不回 = undefined（工具壳以
+     *  label 兜底过滤）。 */
     mode?: "task" | "session-wakeup";
+    /** [c209-D2] codex B4：生命周期层级回显（{@link ScheduledIntent.lifetime}）——缺了它，任务创建后就再无
+     *  公开面能辨认自己是会话级还是持久级（CronCreate 的即时 details 是唯一一瞥）。老 backend 不回 =
+     *  undefined（层级未知，按既有 durable 直觉读）。 */
     lifetime?: "durable" | "session";
+    /** [c209-D2] codex B4：one-shot cron 回显（{@link ScheduledIntent.recurring}）；undefined = 老 backend
+     *  或非 cron 意图。 */
     recurring?: boolean;
 }
+/**
+ * 「手」腿的跨-task 调度能力。一个具体 `ExecutionEnv` 可选附加它（交叉类型），经 {@link hasScheduler} 检测。不支持的
+ * env（无注入 daemon backend）= `schedulerCapabilities.supported=false`，四个 scheduler 工具自动不挂（INERT）。
+ */
 export interface SchedulerCapability {
+    /** 显式声明能力（像 background-shell 一样不猜）。`supported:false` → 工具不挂（design/105 §3.9 TOB / 无 daemon）。 */
     readonly schedulerCapabilities: {
         readonly supported: boolean;
+        /** 单 scope 存量 intent 上限（防自排炸弹；超限 `limit_exceeded`）。 */
         readonly maxScheduledPerScope: number;
+        /** delay/at 最小延迟秒（防 busy 自醒）。 */
         readonly minDelaySec: number;
+        /** cron 解析后实际触发间隔下限秒（`* * * * *` 占 1 slot 但无限触发 → 须有下限）。 */
         readonly minCronIntervalSec: number;
+        /** 最远排程地平线秒（fail-closed 有界，绝不无限未来）。 */
         readonly maxScheduledHorizonSec: number;
+        /**
+         * [c209-D2] backend 是否支持 {@link ScheduledIntent.lifetime} `"session"`（intent 随排入会话终结被
+         * reap）。缺省 undefined/false = 不支持：工具壳收到 session 语义调用（CC 形 `durable` 缺省 false）时
+         * 诚实拒绝并引导 `durable: true`——**绝不静默落成永生任务**。声明 `true` 的 backend MUST 实现 session
+         * intent 的 reap 消费契约（见 {@link ScheduledIntent.lifetime} 注释）。
+         * 🔴 codex B2（TOCTOU 契约条款）：本能力位 MUST 在 backend **实例生命周期内不可变**（`readonly` 快照，
+         * 不得热翻）——工具壳的门控读与 `schedule()` 是两次操作，中途翻位会让 session intent 落到不会 reap 的
+         * backend 上。防线双置：声明面不可变 + `schedule()` 实现 MUST 自行拒绝它无法履行 reap 契约的
+         * `lifetime:"session"` intent（fail-closed 兜底，不依赖工具壳的先行探测）。
+         */
         readonly supportsSessionLifetime?: boolean;
+        /**
+         * TB [991]②b / [997] 裁决 — 宿主是否有会兑现 `mode:"session-wakeup"` intent 的常驻唤醒腿。
+         * **opt-out 方向(与 supportsSessionLifetime 的 fail-closed 缺省相反,有意)**:session-wakeup
+         * 是既有工作语义(daemon 宿主已在兑现),缺省关断=误伤现网——缺省/undefined=支持;headless 单发
+         * 宿主(如 `-p` print 路径:零 daemon,进程终答即退)**显式声明 false** ⇒ 工具壳对 ScheduleWakeup
+         * 诚实拒绝(排入即失约=静默尸体,比拒绝更糟)。不可变纪律同 supportsSessionLifetime。
+         */
         readonly supportsSessionWakeup?: boolean;
     };
+    /**
+     * 持久化一个未来意图。`intent` = 模型可控（无身份）；`ctx` = Runner-held 可信上下文（principal/scope/...）。返回不透明
+     * 句柄。🔴 实现 MUST 把 `ctx.principal` 钉死进持久化 intent（daemon 触发原样传 runTask，不升权）；MUST 用 cron 库
+     * 解析 `when.expr` **禁 shell-exec**（RCE 红线）；MUST 持久化（durable，daemon 重启存活）。upsert：同
+     * `(scope, when, label, lifetime)` 覆盖（幂等）——**lifetime 是身份的一部分**（RB-12/server 1.215 F1 案：
+     * session 级与 durable 级、或不同会话的 session 级 job 撞 (when,label) 是正常用法,MUST NOT 互相覆盖;
+     * session 级的身份还含 sessionId）。
+     */
     schedule(intent: ScheduledIntent, ctx: SchedulerContext): Promise<Result<{
         id: ScheduledTaskId;
     }, SchedulerError>>;
+    /** 取消一个已排意图（幂等：取消不存在的是 ok no-op）。🔴 越权：`id` MUST 属本 scope；非本 scope 一律 `not_found`，不泄露存在性。 */
     cancel(id: ScheduledTaskId, ctx: SchedulerContext): Promise<Result<void, SchedulerError>>;
+    /** 列**本 scope** 已排意图（self-discovery + 防重复排）。范围 = `ctx.scope`，非全局。 */
     list(ctx: SchedulerContext): Promise<Result<ScheduledTaskSummary[], SchedulerError>>;
 }
+/**
+ * 结构 + 语义检测：`env` 是否暴露 scheduler 能力且声明 `supported:true`。挂载门控用此（对齐 `hasBackgroundShell`）。
+ */
 export declare function hasScheduler(env: ExecutionEnv): env is ExecutionEnv & SchedulerCapability;
 export declare function isValidCronExpr(expr: string): boolean;

package/dist/core/secret-env.d.ts

@@ -1,12 +1,44 @@
+/**
+ * Canonical "local-spawn shell secret-env protection" (sema D1) — FIRST-PARTY, vendor-independent.
+ *
+ * When the engine (or a downstream host/exec adapter) spawns a local shell whose commands the MODEL chooses (no human at the keyboard), the child's
+ * inherited env MUST be fail-closed: a model-chosen `printenv DEEPSEEK_API_KEY` via the `bash` tool would
+ * otherwise exfiltrate the orchestrator's brain key / git token / DB creds (the gate authorizes WHICH tool runs,
+ * NOT isolation). The `scrub` policy drops secret-pattern keys (keeps PATH/build/locale → low breakage).
+ *
+ * This lives in `src/core/` — NOT `src/vendor/` — on purpose. It is OUR security invariant (D1 is a first-party
+ * edit, not openclaw upstream), shared by the (currently-vendored) {@link NodeExecutionEnv} AND a downstream
+ * adapter (service host adapter, [265]). Keeping the single source of the secret PATTERN here means:
+ *   1. A consumer imports it instead of mirroring a regex that would silently DRIFT when the pattern is extended.
+ *   2. The public export points at a STABLE first-party path that SURVIVES the planned de-vendoring refactor —
+ *      when NodeExecutionEnv is naturalized out of `src/vendor/`, this module does not move and nothing rebinds.
+ *
+ * The `inheritEnv` THREE-STATE assembly (`"all"` opt-out / `"scrub"` default / `string[]` allowlist) is a
+ * per-adapter concern (each exec env owns how it composes its child env); only the secret PATTERN is shared.
+ */
 import type { RedactionConfidence, RedactionSource } from "./arg-summary.js";
+/** Which rule classified a key as secret-shaped — the env arm's `kind` vocabulary. */
 export type SecretEnvFindingKind = "suffix-rule" | "exact-name";
+/** One env entry the `scrub` policy dropped: the key (the VALUE is never carried — this record is meant
+ *  to be loggable), the rule that classified it, how strong that claim is, and the minting module. */
 export interface SecretEnvFinding {
     key: string;
     kind: SecretEnvFindingKind;
     confidence: RedactionConfidence;
     source: RedactionSource;
 }
+/** What the two exact-name lists say about a name, before any shape rule is consulted. */
 export type ExactEnvNameVerdict = "credential" | "exempt" | "unknown";
+/** The exact-name arm of the classification, taking both lists as arguments. The credential list is read
+ *  FIRST: an exemption can never take a name away from it, so a name landing on both lists resolves to the
+ *  credential reading — the fail-closed direction (a wrongly-exempted name leaks; a wrongly-dropped one
+ *  does not). Module-level export (not part of the package surface): the two real lists are disjoint, so
+ *  only a controlled collision can tell this precedence from an inverted one. */
 export declare function classifyExactEnvName(key: string, credentialNames: ReadonlySet<string>, exemptNames: ReadonlySet<string>): ExactEnvNameVerdict;
+/** Is `key` a secret-pattern env var (one the fail-closed `scrub` policy drops before spawning a shell)? */
 export declare function isSecretEnvKey(key: string): boolean;
+/** Drop every secret-pattern key (see {@link isSecretEnvKey}) from an env object — the fail-closed `scrub`
+ *  policy. `findings` is an OPTIONAL caller-owned collector: pass an array to learn which entries were
+ *  dropped and why, read it back after the call. Omitting it leaves this function byte-for-byte what it
+ *  was before the channel existed. */
 export declare function scrubSecretEnv(env: NodeJS.ProcessEnv, findings?: SecretEnvFinding[]): NodeJS.ProcessEnv;

package/dist/core/select-model.d.ts

@@ -1,10 +1,25 @@
 import type { Model } from "../internal/llm.js";
+/** Coarse price/capability tier, declared on a model via `model.params.tier`. */
 export type ModelTier = "cheap" | "standard" | "premium";
+/** Declarative "pick a model by capability/price" criteria (design/11 Layer 2). */
 export interface ModelCriteria {
+    /** Required capabilities. `vision` = accepts images; `reasoning` = supports extended thinking. */
     needs?: Array<"vision" | "reasoning">;
+    /** Minimum usable context window (`contextTokens ?? contextWindow`). */
     minContext?: number;
+    /** Require an exact tier — read from `model.params.tier` (`"cheap" | "standard" | "premium"`). */
     tier?: ModelTier;
+    /** Tiebreak among the matches by total `cost` ($/Mtok input+output). Default `"cheapest"`. */
     prefer?: "cheapest" | "premium";
 }
+/**
+ * Pick a model from a catalog by capability + price. Filters by `needs`/`minContext`/`tier`, then
+ * ranks the survivors by total list cost (`prefer: "cheapest"` default, or `"premium"` = priciest as
+ * a capability proxy). Returns `undefined` when nothing matches. The capability/price fields already
+ * live on `Model` (`input`, `reasoning`, `contextWindow`, `cost`); `tier` is opt-in via
+ * `model.params.tier`. This is the static version of cost-aware routing (RouteLLM is the dynamic,
+ * per-query north star — see design/11); compose it into `roles` via a `{ select }` RoleSpec.
+ */
 export declare function selectModel(models: Record<string, Model> | Model[], criteria?: ModelCriteria): Model | undefined;
+/** Throwing variant of {@link selectModel}. */
 export declare function selectModelOrThrow(models: Record<string, Model> | Model[], criteria?: ModelCriteria): Model;

package/dist/core/sensitive-path-policy.d.ts

@@ -1,9 +1,51 @@
 import type { ExecutionEnv } from "../internal/harness-types.js";
 import type { ToolPolicy } from "./tool-policy.js";
+/**
+ * RECOMMENDED default pattern set for {@link createSensitivePathPolicy} ([871]② — additive export).
+ * NO upstream verbatim anchor exists (cc-anchors/2.1.209 carries no sensitive/dangerous file-pattern
+ * material), so this is an ENGINEERING-CONSENSUS set — each line states its tradeoff. The factory's
+ * default behavior is unchanged (no implicit default list; wiring this set is the caller's opt-in:
+ * `createSensitivePathPolicy({ patterns: RECOMMENDED_SENSITIVE_PATTERNS, … })`).
+ *
+ * Pattern semantics (must match `compilePatterns`/`matchSensitive` below — segment globs, NOT full-path
+ * globs): each pattern is a `/`-separated run of path SEGMENTS; `*` matches any run of non-slash chars
+ * within one segment and is the ONLY metacharacter (everything else, `?` included, is literal); the run
+ * may match ANYWHERE in the canonical path (so `.ssh` covers `~/.ssh/…` and any other `.ssh` directory —
+ * home-anchoring like `~/` is NOT part of the syntax, do not prefix it). A pattern that reduces to zero
+ * segments is a wiring ERROR (it would guard nothing) and throws rather than being dropped.
+ * Remember this policy guards WRITES only; reads are out of scope by design.
+ *
+ * NOT listed, deliberately (HRD-PRM-10): sema's own data root (`$AGENT_DATA_DIR ?? ~/.ai-agent`). Its
+ * `sessions/` subtree is already owned by `createTranscriptIntegrityPolicy`, which is wired ALWAYS-ON by
+ * the runner and answers `ask` — the design's deliberate verdict, since «reading transcripts is routine»
+ * and a legitimate operator write must remain clearable by judgment. A deny here would outrank that ask
+ * under the deny > ask > allow fold and silently convert it into a hard refusal for every deployment
+ * that wires this list.
+ */
 export declare const RECOMMENDED_SENSITIVE_PATTERNS: readonly string[];
+/**
+ * Build a composable policy that DENIES writes (via the guarded fs tools) whose canonical target
+ * lands on a sensitive path. `patterns` are deployment-supplied (no default list is shipped — the
+ * set of escalation-vector paths is deployment-specific); an empty list is a no-op allow.
+ *
+ * `env` is the same ExecutionEnv the hands run against (inject the one you pass to the Runner), so
+ * canonicalization sees the task's real filesystem (a remote/E2B task resolves in its container).
+ * `rootPath` is the FALLBACK base a relative path resolves against (omit = paths resolve as given).
+ * RB-108: when the engine stamps a live cwd onto the request (`ToolCallRequest.cwd` — the tracked
+ * directory the shell's `cd` moves and the fs tools resolve with), THAT wins for the call's target, so
+ * the guard judges the file the tool will actually write. `rootPath` still serves every deployment that
+ * calls this policy outside a Runner.
+ *
+ * Fail-open by design: a tool with no string `path`, or a path that cannot be canonicalized, returns
+ * `allow` here — this guard adds a denial on top of the other gates, it is not the only line of
+ * defense, and it must not turn an unrelated tool call into a spurious deny. The verdict it owns is
+ * narrow and certain: "the real target IS a guarded path → deny".
+ */
 export declare function createSensitivePathPolicy(opts: {
     env: ExecutionEnv;
+    /** `readonly` accepted so {@link RECOMMENDED_SENSITIVE_PATTERNS} can be passed as-is (widening, non-breaking). */
     patterns: readonly string[];
     rootPath?: string;
+    /** Override the guarded tool set (default: `Write`, `Edit`, `MultiEdit`-legacy → Edit, `NotebookEdit`). */
     tools?: string[];
 }): ToolPolicy;