@sema-agent/core 5.20.0 → 5.21.1

package/dist/core/skills-directory.d.ts

@@ -1,13 +1,112 @@
+/**
+ * RB-410 件1 — the Agent Skills (`SKILL.md`) directory loader.
+ *
+ * The open skills format (published at agentskills.io, reference implementation `anthropics/skills`) is
+ * a directory per skill: `skill-name/SKILL.md` holding a `---` frontmatter block plus a Markdown body,
+ * with optional `scripts/` / `references/` / `assets/` resource directories beside it. sema's
+ * {@link SkillSpec} is already the same shape — frontmatter → `name`/`description`, body → `content`,
+ * sibling resources → `files[]` — so the only missing piece was this reader. No engine mechanism
+ * changes: the output is an ordinary `SkillSpec[]` a deployment hands to `TaskSpec.skills`.
+ *
+ * **Deployment-half helper, called BEFORE a task starts.** It reads the filesystem synchronously and is
+ * NOT reachable from the run loop — the engine still never resolves a skill path at tool time, and never
+ * writes. An embedder serving skills from a remote/sandboxed filesystem should read through its own
+ * `ExecutionEnv` instead and construct `SkillSpec` objects directly; this helper is the local-disk case.
+ *
+ * **Trust contract is unchanged and is the caller's:** a skill IS instructions, so everything read here
+ * (body and attachments alike) enters the model's context as CALLER-TRUSTED material. Pointing this at a
+ * directory third parties can write to is the same as pasting their text into the system prompt. The
+ * loader validates SHAPE (spec conformance), never intent.
+ *
+ * **`allowed-tools` is mapped TIGHTEN-ONLY** — see {@link SkillsDirectoryOptions.deployedTools}.
+ *
+ * Frontmatter is parsed by a deliberately closed subset reader (no YAML dependency — the runtime
+ * dependency budget is a standing constraint): top-level `key: value` scalars, optional surrounding
+ * quotes, `#` comment lines, block scalars (`|` / `>` with their indentation + chomping indicators),
+ * flow sequences (`[a, b]`, including the multi-line form), and indented mapping bodies skipped
+ * wholesale. That covers every field the spec defines, and the same posture the memory-engine
+ * frontmatter reader already takes.
+ */
 import type { SkillSpec } from "./types.js";
-export type SkillsDirectoryWarningCode = "no_skill_file" | "no_frontmatter" | "missing_name" | "invalid_name" | "name_mismatch" | "missing_description" | "allowed_tool_pattern_unsupported" | "description_too_long" | "allowed_tool_not_mounted" | "disallowed_tools_unenforced" | "attachment_skipped" | "read_failed";
+/** Why one skill directory (or one of its parts) was not taken as-declared. */
+export type SkillsDirectoryWarningCode = 
+/** The directory holds no `SKILL.md`. */
+"no_skill_file"
+/** `SKILL.md` has no well-formed `---` fenced frontmatter block. */
+ | "no_frontmatter"
+/** Required `name` absent. */
+ | "missing_name"
+/** `name` breaks the charset/length rule. */
+ | "invalid_name"
+/** `name` disagrees with the directory name (the spec requires they match). */
+ | "name_mismatch"
+/** Required `description` absent. */
+ | "missing_description"
+/** RB-428-A: an `allowed-tools` entry carries a pattern specifier (`Bash(git:*)`) — the scope policy
+ *  matches names, not patterns, so the entry cannot match and the tool is DISABLED in this skill
+ *  frame. Disclosed loudly until pattern enforcement lands (the entry is deliberately NOT widened to
+ *  its base name: that would turn "only git" into "all of Bash"). */
+ | "allowed_tool_pattern_unsupported"
+/** `description` exceeds the spec cap. */
+ | "description_too_long"
+/** An `allowed-tools` entry the deployment does not mount — dropped (tighten-only). */
+ | "allowed_tool_not_mounted"
+/** A `disallowed-tools` declaration this mapping cannot carry — see {@link SkillsDirectoryOptions.deployedTools}. */
+ | "disallowed_tools_unenforced"
+/** An attachment was left out (non-text bytes, over budget, unreadable, or resolving outside the skill). */
+ | "attachment_skipped"
+/** A file or directory entry existed but could not be read/resolved. */
+ | "read_failed";
+/** One non-fatal diagnostic from a load. Safe to log: no file contents, only names/reasons. */
 export interface SkillsDirectoryWarning {
     code: SkillsDirectoryWarningCode;
+    /** Directory name of the skill this concerns, relative to the scanned root. */
     skill: string;
+    /** Human-readable detail (names the offending field/file and what was done about it). */
     detail: string;
 }
 export interface SkillsDirectoryOptions {
+    /**
+     * The tool names this deployment actually mounts. When given, a skill's `allowed-tools` declaration is
+     * INTERSECTED with it and every name outside is dropped with an `allowed_tool_not_mounted` warning.
+     *
+     * 🔴 **Tighten-only, by ruling.** `allowed-tools` is a skill-authored capability claim and the format
+     * marks it experimental; sema's permission discipline is tighten-only, so it is mapped exclusively onto
+     * {@link SkillManifest} — a structure that can only SUBTRACT capability (the scope policy returns
+     * `allow`/`deny` and composes ahead of the task policy under a deny-short-circuit fold, so it can never
+     * re-grant what the task withheld). Consequences worth stating plainly:
+     * - a name outside `deployedTools` is dropped, NOT honored — a skill cannot pull in a tool the
+     *   deployment never mounted;
+     * - when the intersection comes out EMPTY the manifest is still emitted with an empty `allowTools`
+     *   (narrow to nothing while the skill's frame is active). Dropping the manifest instead would widen
+     *   the run relative to what the skill asked for, which is the one direction this mapping may not take;
+     * - omitting `deployedTools` skips the filter. Still safe — an unmounted name simply never matches a
+     *   call — but the warning is then unavailable, so a deployment that wants the audit trail should pass it.
+     *
+     * Names are compared in CANONICAL form on both sides (the same normalization the enforcing policy
+     * applies), so passing this option can never produce a stricter result than omitting it: a declared
+     * legacy alias and the mounted current name are one tool here exactly as they are at call time.
+     * A wildcard declaration (`allowed-tools: "*"`) claims the whole roster and therefore narrows by
+     * nothing — no manifest is emitted, leaving the task policy untouched.
+     */
     deployedTools?: readonly string[];
+    /** Sink for non-fatal diagnostics. Absent ⇒ warnings are dropped and the load still proceeds. */
     onWarning?: (warning: SkillsDirectoryWarning) => void;
+    /**
+     * Total decoded-text budget for ONE skill's attachments, in bytes (default 256 KiB). Files are taken in
+     * path order until the budget is spent; the rest are skipped with a disclosed warning. Attachments also
+     * ride a separate delivery cap at invoke time, so a generous value here does not enlarge the prompt.
+     */
     maxAttachmentBytes?: number;
 }
+/**
+ * Load every `SKILL.md`-bearing subdirectory of `dir` into a {@link SkillSpec}, ready for
+ * `TaskSpec.skills`. Results are ordered by directory name (deterministic across filesystems).
+ *
+ * Per-skill problems are NON-FATAL: a directory whose frontmatter breaks the spec (missing/invalid
+ * `name`, missing/over-long `description`, no fenced block, no `SKILL.md`) is SKIPPED and reported
+ * through {@link SkillsDirectoryOptions.onWarning}, so one malformed skill cannot take down a whole
+ * library. The root itself is different — an unreadable/non-directory root THROWS, because silently
+ * returning `[]` for a mistyped path would look exactly like "this deployment has no skills".
+ */
 export declare function createSkillsFromDirectory(dir: string, options?: SkillsDirectoryOptions): SkillSpec[];

package/dist/core/spec-contract.d.ts

@@ -1,57 +1,146 @@
+/**
+ * design/125 — **SpecContract**:spec→Verifier 闭环的机器可读任务契约(make-real 两周实战纪律的
+ * 一等原语化)。本模块 = 纯 core 零件:契约类型 + 三值 oracle 执行器 + frozenPaths 校验/快照/恢复。
+ * 装配(policy 组合、stop 把关、outcome 发射)在 `orchestration/run-spec.ts`。
+ *
+ * 🔴 **信任声明(fable-M3)**:SpecContract 是 **CODE-tier** 输入 —— `oracle[].cmd` 会被亲跑(execFile,
+ * 任意命令)。它只能来自部署作者/可信代码路径;LLM 生成的 contract 直接喂 runSpec = 不受信输入获得
+ * 命令执行权(越红线),禁止。contract 里的 `spec` **文本**才是 DATA-tier(runSpec 恒围栏置入 objective)。
+ *
+ * 🔴 **oracle 三值(fable-M6)**:每门结果 ∈ {green, red, error} —— 判据不满足 = red;基础设施故障
+ * (ENOENT/timeout/maxBuffer/parse 解析不出)= **error 非 red**。假红防线:error 绝不冒充"曾经红过"
+ * (design/73 红线② 的机器化 —— `oracleHadRedRun` 只由真 red 观察置位)。
+ */
+/** Declarative green criteria for one oracle gate. Absent ⇒ `exitCode === 0`. All declared criteria AND. */
 export interface OracleGreenSpec {
+    /** Expected exit code. Default 0 when no `parse` is declared; with `parse`, exit code is only
+     *  checked when explicitly set here (test runners exit non-zero on failures the counts already judge). */
     exitCode?: number;
+    /** Regex (source string) that MUST match the combined stdout+stderr. */
     mustMatch?: string;
+    /** Regex (source string) that MUST NOT match the combined stdout+stderr. */
     mustNotMatch?: string;
+    /**
+     * Parsing criteria (fable-M5/B1 一体解): extract pass/fail counts from the output. Each regex's FIRST
+     * capture group is the integer count (e.g. `"ℹ pass (\\d+)"`). Either regex failing to match = the gate
+     * is **error** (解析不出 ≠ red — a runner that printed nothing proves nothing).
+     */
     parse?: {
         passRe: string;
         failRe: string;
     };
+    /**
+     * Lower bound on the parsed pass count (requires `parse`). `"baseline"` = the pass+fail TOTAL this gate
+     * observed at preflight — the anti-「测试消失式走捷径」 gate (the model leaves tests untouched but makes
+     * them undiscovered; harness :114 实战门, fable-B1). Numeric default when absent: 1 (a zero-test green
+     * is vacuous).
+     */
     minPass?: number | "baseline";
 }
+/** One mechanical adjudicator: a command run via execFile (NO shell) + declarative green criteria. */
 export interface OracleGateSpec {
+    /** Stable gate name (baseline capture and per-gate reporting key on it). */
     name: string;
+    /** argv — `cmd[0]` is the executable, the rest are arguments. execFile, never a shell. */
     cmd: string[];
+    /** Working directory, containment-checked against the runSpec root (same rule as frozenPaths). */
     cwd?: string;
+    /** Per-gate timeout. Default 60s. */
     timeoutMs?: number;
     green?: OracleGreenSpec;
 }
+/** design/125 D1 — the machine-readable task contract (CODE-tier input; see module doc). */
 export interface SpecContract {
+    /** Task spec text (or a file reference resolved against the runSpec root). runSpec owns the objective
+     *  framing; the spec text itself is DATA-tier and is ALWAYS fenced before injection. */
     spec: string | {
         path: string;
     };
+    /**
+     * Read-only specification surface. **Validation (fable-M2)**: absolute paths and `..` segments are
+     * rejected; paths resolve against the runSpec root with a containment check; policy matching uses the
+     * RESOLVED path. Exact paths, no globs (v1 收窄).
+     */
     frozenPaths: string[];
+    /** Mechanical adjudicators (serializable, checkpointable, service-boundary-safe, feed-recordable). */
     oracle: OracleGateSpec[];
+    /**
+     * 双向验证: preflight runs the full oracle and REQUIRES red (proves the spec has substance), capturing
+     * baseline counts for `minPass:"baseline"` (fable-B1: the red gate and the baseline are two faces of the
+     * same preflight). Default **true** (the discipline is the default; opting out must be explicit).
+     * `{ exempt }` documents WHY this contract legitimately starts green (e.g. pure-refactor spec).
+     */
     requireRedStart?: boolean | {
         exempt: string;
     };
+    /** design/73 aggregation key. Default: `spec:<sha256(specText) first 16 hex>`. */
     taskSignature?: string;
 }
+/** Three-value gate verdict — `error` = the adjudicator itself failed to run/parse (NEVER counts as red). */
 export type OracleVerdict = "green" | "red" | "error";
 export interface OracleGateResult {
     name: string;
     verdict: OracleVerdict;
+    /** Process exit code (null when the process did not run/complete — spawn error or timeout kill). */
     exitCode: number | null;
+    /** Parsed counts when `green.parse` was declared and both regexes matched. */
     pass?: number;
     fail?: number;
+    /** Which criterion failed / what the infrastructure error was (first-party classification string). */
     reason?: string;
+    /** Tail of the combined stdout+stderr (UNTRUSTED — the model can influence it via the code under test;
+     *  fence with `delimitUntrusted` before any model-facing use). */
     outputTail: string;
 }
+/** Per-gate preflight counts backing `minPass:"baseline"` (keyed by gate name). */
 export type OracleBaseline = Record<string, {
     pass: number;
     fail: number;
 }>;
 export interface OracleRunReport {
+    /** Worst-across-gates: any `error` ⇒ error (fail-loud dominates); else any `red` ⇒ red; else green. */
     verdict: OracleVerdict;
     gates: OracleGateResult[];
 }
+/**
+ * Run every gate of the contract's oracle (sequentially — gates commonly share a working tree) and fold
+ * the three-value verdicts: any `error` ⇒ `error` (fail-loud dominates; an unfalsifiable adjudication must
+ * never pass silently), else any `red` ⇒ `red`, else `green`.
+ *
+ * `cwdRoot` is the runSpec root: each gate's `cwd` resolves against it with the same containment rule as
+ * frozenPaths (a contract cannot point its adjudicator outside the workcopy).
+ */
 export declare function runOracle(gates: OracleGateSpec[], cwdRoot: string, opts?: {
     baseline?: OracleBaseline;
     signal?: AbortSignal;
 }): Promise<OracleRunReport>;
+/** Extract the per-gate baseline counts from a (preflight) report — only gates whose parse succeeded. */
 export declare function captureBaseline(report: OracleRunReport): OracleBaseline;
+/** A coded error (`config.*` / `spec.*` convention — same shape as goal.ts's reserved-name fail-fast). */
 export declare function specError(code: string, message: string): Error & {
     code: string;
 };
+/**
+ * Validate and resolve `frozenPaths` against the runSpec root (fable-M2): absolute paths and `..`
+ * segments are rejected outright (`spec.frozen_path_invalid`); the resolved path must stay inside the
+ * root. Returns resolved absolute paths (the ONLY form policy matching and snapshots use).
+ */
 export declare function resolveFrozenPaths(rootDir: string, frozenPaths: string[]): string[];
+/**
+ * Byte-level snapshot of the frozen surface (fable-M1: a hash can only DETECT tampering — restoring needs
+ * the CONTENT, and the snapshot is the restore source; no external seed directory dependency). Missing
+ * file ⇒ `spec.frozen_missing` (a frozen path that doesn't exist can't be a specification).
+ */
 export declare function snapshotFrozenPaths(resolvedPaths: string[]): Map<string, Buffer>;
+/**
+ * Restore any frozen file whose on-disk bytes differ from the snapshot (belt for `echo > test/x`-style
+ * bash writes the Write/Edit deny policy cannot see — fable-MIN2). Returns the number of files restored.
+ *
+ * Symlink-safe (codex 实现审 B2): a tampered entry that is no longer a regular file (the model swapped
+ * it for a symlink pointing outside the root) is REMOVED first — the snapshot bytes are then written to
+ * a fresh regular file, never THROUGH a link. When `rootDir` is given, the parent directory's physical
+ * path is containment-checked too (a symlinked PARENT dir would also carry the write outside); an entry
+ * whose parent escapes is skipped (counted) — the terminal oracle then adjudicates the missing spec
+ * files honestly (fail-safe direction) instead of runSpec writing outside its root.
+ */
 export declare function restoreFrozenPaths(snapshot: Map<string, Buffer>, rootDir?: string): number;

package/dist/core/store-contracts/background-agent-store-contract.d.ts

@@ -1,5 +1,36 @@
 import { type BackgroundAgentStore } from "../background-agent-store.js";
 import { type ContractAssertionRunner } from "./contract-harness.js";
+/**
+ * design/159 — the cross-backend {@link BackgroundAgentStore} contract kit (vitest-free; see
+ * `contract-harness.ts` for the runner seam and `contract-kit-version.ts` for version lockstep).
+ * `make()` must return a FRESH, empty store each call; a store a case creates is closed (`close?.()`)
+ * when the case ends, so a backend holding a file descriptor does not leak one per case.
+ *
+ * 为什么这个家族需要一份共跑资产:这个 store 的两个捆绑后端是逐方法手写的孪生实现,而本仓在它上面
+ * 已经连续吃过四次「一份修了、另一份没修」——RB-60 / RB-74 / RB-87 / RB-111,其中 RB-87 与 RB-111
+ * 是同一个 reap 重复计数缺陷在两个后端里分别被发现、相隔一个版本。REF-A3/REF-D18 之后共享形状收敛
+ * 到了单一构造点,但**语义**仍然只由每个后端各自的测试看住;第三方后端更是完全在射程之外。这份
+ * 试剂盒把语义变成全后端共跑的验收底线:任何后端在这里变红 = 该后端违约,**不许通过放宽契约让它
+ * 变绿**。
+ *
+ * 断言只描述已落地的行为(权威文本 = `src/core/background-agent-store.ts` 的接口契约段),不引入
+ * 任何新义务。
+ *
+ * 分层:
+ * - 核心层 {@link backgroundAgentStoreContract}:每个后端都必须过。
+ * - 可选能力层 {@link backgroundAgentStoreScopesContract}:只挂实现了可选方法 `listScopes` 的后端
+ *   (接口把它标为可选——把它折进核心层就会变成「没实现的后端静默跳过」,而静默跳过正是假绿的
+ *   来源)。两个捆绑后端都实现了它,都挂。
+ */
+/** 契约统一用的租户 scope(核心层的多租户用例会另外显式构造第二个)。 */
 export declare const BACKGROUND_AGENT_CONTRACT_SCOPE = "tenant-A";
+/**
+ * 核心不变量层 —— 每个 {@link BackgroundAgentStore} 后端都必须过。
+ */
 export declare function backgroundAgentStoreContract(mk: () => BackgroundAgentStore, runAssertion?: ContractAssertionRunner): Promise<void>;
+/**
+ * 可选能力层 —— 只挂实现了 {@link BackgroundAgentStore.listScopes} 的后端。接口把该方法标为可选
+ * (一个把租户清单记在别处的部署可以省略它),所以它不能进核心层:核心层里的「没实现就跳过」等于
+ * 给不合规后端发一张假绿通行证。两个捆绑后端都实现了它。
+ */
 export declare function backgroundAgentStoreScopesContract(mk: () => BackgroundAgentStore, runAssertion?: ContractAssertionRunner): Promise<void>;

package/dist/core/store-contracts/checkpoint-store-contract.d.ts

@@ -1,11 +1,37 @@
 import { type Checkpoint, type CheckpointStore, type ResumeOutcome } from "../checkpoint-store.js";
 import { type ContractAssertionRunner } from "./contract-harness.js";
+/**
+ * design/159 S1 — the cross-backend {@link CheckpointStore} contract, extracted VERBATIM from
+ * `test/cross-backend-shared.ts` (design/87 §3 gap [cross-backend-enforce], the anti-drift guard
+ * born in design/80 §6.3) into a vitest-free kit a third-party backend implementor can import and
+ * run under any harness (or none — see {@link ContractAssertionRunner}).
+ *
+ * `make()` must return a FRESH, empty store each call. Core binds this to InMemory + File
+ * (`test/cross-backend-inmem-file.test.ts`) and Pg via pg-mem (`test/pg-cross-backend.test.ts`);
+ * a third-party durable backend passes its own factory.
+ *
+ * Version lockstep: see `contract-kit-version.ts` (`CONTRACT_KIT_ENGINE_VERSION`).
+ */
+/** Build a {@link Checkpoint} fixture. `createdAt` is FIXED (not wall-clock) so summary projections
+ *  are deterministic and cross-backend byte-comparable; override via `over` for ordering tests. */
 export declare function createCheckpointFixture(over?: Partial<Checkpoint>): Checkpoint;
+/** The canonical `policy_ask allow` outcome the contract resolves with. Declared as the NARROW
+ *  `policy_ask` arm — not the whole union — so field access and spread call sites need no
+ *  re-assertion (RB-396-d: the wide declaration forced an `as Extract<…>` + a same-value
+ *  `boundCallId` overwrite at one site — verbatim 移植残渣, both gone with this declaration). */
 export declare const ALLOW: Extract<ResumeOutcome, {
     gate: "policy_ask";
 }>;
+/**
+ * The full cross-backend contract for {@link CheckpointStore} — the SAME assertions for every
+ * backend. Entries are a 1:1 port of the vitest originals (assertion semantics unchanged).
+ */
 export declare function checkpointStoreContract(make: () => CheckpointStore, runAssertion?: ContractAssertionRunner): Promise<void>;
+/** Seed the canonical listByScope fixture into `store` and return the sorted summaries. Compare the
+ *  result against {@link EXPECTED_LISTBYSCOPE_SUMMARIES} (deep equality) to prove the backend's
+ *  summary projection matches the reference — the caller owns the comparison (harness-specific). */
 export declare function checkpointListByScopeSummaries(store: CheckpointStore): Promise<import("../checkpoint-store.js").CheckpointSummary[]>;
+/** The canonical expected summary projection (what `summarizeCheckpoint` must yield for the fixture above). */
 export declare const EXPECTED_LISTBYSCOPE_SUMMARIES: ({
     token: string;
     sessionId: string;

package/dist/core/store-contracts/contract-harness.d.ts

@@ -1,5 +1,25 @@
+/**
+ * design/159 S1 — the shared runner seam every store-contract kit in this directory uses, extracted
+ * verbatim from the proven shape in `src/core/workflow-run-store-contract.ts` (the kit service
+ * already consumes in production). vitest-free BY CONTRACT: the kits run under any harness — a
+ * vitest binding passes `(name, fn) => { it(name, fn); }`, a bare script passes nothing and gets
+ * the sequential default — so a third-party store implementor needs NO test framework to verify
+ * their backend (cli [2081]: shell/client-core run self-written runners).
+ */
+/**
+ * Labels + schedules one contract case. May return a promise (collected and awaited by the kit's
+ * final `Promise.all`) or register the case with a harness and return void (vitest `it`).
+ *
+ * ⚠️ Binding note (service [390], inherited from workflowRunStoreContract): cases are REGISTERED
+ * eagerly — an async runner that starts work immediately will interleave cases. Every case builds
+ * its own fresh store via `make()`, so interleaving is safe UNLESS your binding's stores share
+ * state (e.g. SQL twins on one table); such bindings must serialize inside `runAssertion`.
+ */
 export type ContractAssertionRunner = (name: string, fn: () => Promise<void>) => void | Promise<void>;
+/** The no-harness default: run each case immediately in order, surfacing the first failure. */
 export declare function defaultSequentialRunner(_name: string, fn: () => Promise<void>): Promise<void>;
+/** The eager-register + collect-promises loop shared by every kit (same semantics as the inline
+ *  original in workflow-run-store-contract.ts). Call `run` per case, then `await settle()`. */
 export declare function beginContract(runAssertion?: ContractAssertionRunner): {
     run: (name: string, fn: () => Promise<void>) => void;
     settle: () => Promise<void>;

package/dist/core/store-contracts/contract-kit-version.d.ts

@@ -1 +1,28 @@
+/**
+ * design/159 S1 — the contract kit's version-lockstep constant (server [2058] requirement ①).
+ *
+ * The store-contract kit ships INSIDE `@sema-agent/core` and evolves in lockstep with the engine —
+ * an assertion added because an engine release changed a store's semantics is only meaningful
+ * against THAT engine generation. Because kit and engine are one package, lockstep holds by
+ * construction and no entry point asserts a host version; this constant exists so an EXTERNAL
+ * consumer can make the pairing loud instead of silent:
+ *
+ * ```ts
+ * import { CONTRACT_KIT_ENGINE_VERSION } from "@sema-agent/core/…";
+ * if (CONTRACT_KIT_ENGINE_VERSION !== myPinnedEngineVersion) {
+ *   throw new Error(`contract kit ${CONTRACT_KIT_ENGINE_VERSION} != engine ${myPinnedEngineVersion}`);
+ * }
+ * ```
+ *
+ * A third party running an old kit against a new engine (or the reverse) would otherwise get a
+ * silent false-green ([2021] A1 form) — e.g. a pre-2.2.0 kit has no idempotent-reopen entry, so a
+ * wiping SessionRepo passes it. Compare this constant against the `@sema-agent/core` version you
+ * actually resolved (read the installed package.json — the lock file can pin something older than
+ * what your manifest says).
+ *
+ * Same source as `package.json` `version`: resolved at runtime via {@link engineVersion} (the
+ * package's own package.json, memoized, "unknown" only under an exotic bundler that severed the
+ * module from its package root). A test pins it equal to the repo's package.json so the relative
+ * walk can never drift from the published value.
+ */
 export declare const CONTRACT_KIT_ENGINE_VERSION: string;

package/dist/core/store-contracts/file-snapshot-store-contract.d.ts

@@ -1,5 +1,13 @@
 import type { FileSnapshotStore } from "../file-snapshot-store.js";
 import { type ContractAssertionRunner } from "./contract-harness.js";
 export declare function fileSnapshotStoreContract(make: () => FileSnapshotStore, runAssertion?: ContractAssertionRunner, options?: {
+    /**
+     * How quickly unreferenced BLOB BYTES become unreadable after a reap. The MANIFEST key is a hard
+     * contract either way (invisible immediately). `"immediate"` (default — the in-memory and file
+     * reference backends): `getBlob` of a just-unreferenced hash is `undefined` right after `reap`
+     * returns. `"eventual"`: a durable/object-storage backend that hands byte GC to an asynchronous
+     * sweeper (so a reap on the request path is never held hostage by external-storage latency) —
+     * the immediate-unreadability assertion is skipped; the backend owns proving its sweeper.
+     */
     blobGc?: "immediate" | "eventual";
 }): Promise<void>;

package/dist/core/store-contracts/mailbox-store-contract.d.ts

@@ -1,6 +1,48 @@
 import type { MailboxStore } from "../mailbox-store.js";
 import { type ContractAssertionRunner } from "./contract-harness.js";
+/**
+ * design/159 S1 — the cross-backend {@link MailboxStore} contract, extracted VERBATIM from
+ * `test/mailbox-contract.ts` (design/157 A11's two-layer form) into a vitest-free kit (see
+ * `contract-harness.ts` for the runner seam and `contract-kit-version.ts` for version lockstep).
+ *
+ * 为什么这个家族有契约(结构性复发机制,两次实证):契约 harness 此前只喂 InMemory + File 两个
+ * 后端,于是没进 harness 的那个后端反复独立漂移 ——
+ *   - RB-86:`stores/cc/mailbox-store.ts` 注释自陈 "the contract both bundled backends already
+ *     honor, missing only here"(空箱 claimLease 不返回 null,还装上幽灵租约);
+ *   - MB1(黑板 [1937]):CC 后端的 `ack` 根本不查 lease 表,注释自陈 "worse than the other two
+ *     backends' pre-fix bug"。
+ * 两次漏的都是同一个后端。修法不是再补一次点,而是把契约本身变成全后端共跑的资产 —— design/159
+ * 再进一步:第三方后端也拿得到同一份资产。
+ *
+ * 分层(与 test/mailbox-contract.ts 的挂载对应):
+ * - T1 核心不变量层 = {@link mailboxStoreContract} + {@link mailboxAckOwnershipContract}:每个后端
+ *   都必须过。任何后端在这一层变红 = 该后端违约,**不许通过放宽契约让它变绿**。核心层一律用
+ *   `scope: "default"`({@link MAILBOX_CONTRACT_SCOPE}),这样租户轴受限的后端(CC inbox 文件)
+ *   也跑同一段代码。
+ * - T2 可选能力层 = {@link mailboxBundledOnlyContract}:多租户隔离 + 键注入性,只挂具备租户轴/
+ *   自有键空间的后端(core 的两个捆绑后端;CC 按 D-3 边界豁免,豁免明细在
+ *   `src/stores/cc/mailbox-store.ts` 模块头)。
+ *
+ * `make()` must return a FRESH, empty store each call. Stores a contract case creates are closed
+ * (`close?.()`) when the case ends — the file backend's append fd is refcounted, so a harness that
+ * runs many cases would otherwise hold descriptors until process exit.
+ */
+/** 核心层统一用的 scope —— 每个后端都必须服务它(租户轴受限的后端只服务它)。 */
 export declare const MAILBOX_CONTRACT_SCOPE = "default";
+/**
+ * T1 核心不变量层 —— 每个后端都跑。用例出处见每条内联注释(`src/core/mailbox-store.ts` 的接口
+ * 契约段是权威文本)。
+ */
 export declare function mailboxStoreContract(mk: () => MailboxStore, runAssertion?: ContractAssertionRunner): Promise<void>;
+/**
+ * T1 核心不变量层(MB1 分册)—— ack 的 owner 围栏,与 {@link mailboxStoreContract} 同层同权重,
+ * 单独成函数只是为了让 MB1 的出处叙述留在它自己的挂载文件里
+ * (`test/mb1-mailbox-ack-ownership.test.ts`)。
+ */
 export declare function mailboxAckOwnershipContract(mk: () => MailboxStore, runAssertion?: ContractAssertionRunner): Promise<void>;
+/**
+ * T2 可选能力层 —— 只挂具备租户轴 + 自有键空间的后端(core 的两个捆绑后端)。CC 后端按其形态
+ * 明文豁免(豁免明细在 `src/stores/cc/mailbox-store.ts` 模块头,D-3 裁定),不是「没做到所以
+ * 放宽」:核心层没有一条为了任何后端而弱化。第三方后端若有租户轴,应当也挂这一层。
+ */
 export declare function mailboxBundledOnlyContract(mk: () => MailboxStore, runAssertion?: ContractAssertionRunner): Promise<void>;

package/dist/core/store-contracts/tool-result-store-contract.d.ts

@@ -1,3 +1,16 @@
 import type { ToolResultStore } from "../tool-result-store.js";
 import { type ContractAssertionRunner } from "./contract-harness.js";
+/**
+ * design/159 S1 — the cross-backend {@link ToolResultStore} contract, extracted VERBATIM from
+ * `test/cross-backend-shared.ts` into a vitest-free kit (see `contract-harness.ts` for the runner
+ * seam and `contract-kit-version.ts` for version lockstep). `make()` must return a FRESH, empty
+ * store each call.
+ *
+ * Semantics since @sema-agent/core 2.1.0 (RB-266 + RB-273): ref safety is UNIFORM across backends —
+ * the write face rejects the intersection-unsafe ref set on EVERY backend (`assertSafeToolResultRef`
+ * is the shared floor) and a ref the contract accepts must round-trip on EVERY backend (a backend
+ * with a narrower native key space owns an injective encoding, not a rejection). Before 2.1.0 the
+ * bundled backends genuinely diverged on both halves (dev-green / deployment-red), so running this
+ * kit against a pre-2.1.0-modeled backend is expected to go red on those two entries.
+ */
 export declare function toolResultStoreContract(make: () => ToolResultStore, runAssertion?: ContractAssertionRunner): Promise<void>;

package/dist/core/strategy-store.d.ts

@@ -1,18 +1,54 @@
+/**
+ * Teacher-mode strategy repository (design/14). Stores the *generalized* strategies a teacher gave
+ * that actually worked, so a later similar problem can be solved without re-consulting the teacher
+ * (Inter-Cascade cross-session reuse). Retrieval is deliberately **high-precision / low-recall**: a
+ * wrong strategy injected into a student costs wasted turns + a likely escalation (net negative),
+ * while a missed strategy just falls back to asking the teacher (baseline). `scope` is a **mandatory
+ * isolation boundary** (multi-tenant: one user's strategies must never leak to another).
+ */
 export interface StoredStrategy {
+    /** Stable id. */
     id: string;
+    /** The raw task objective that triggered the teacher's help — matched against future objectives. */
     problem: string;
+    /** The teacher's generalized approach (1-2 sentences). */
     strategy: string;
+    /** The teacher's confidence (0-3) when it gave this. */
     confidence: number;
+    /** Tenant/isolation scope (e.g. "user:42"). Strategies are only ever retrieved within their scope. */
     scope: string;
+    /** ISO timestamp stored. */
     ts: string;
+    /** Teacher model id, for future staleness handling. */
     teacherModel?: string;
+    /** Reserved for a future generalized signature (v3 semantic matching). */
     signature?: string;
 }
 export interface StrategyStore {
+    /** Persist a strategy (implementations may merge an exact near-duplicate and cap per-scope size). */
     save(s: StoredStrategy): Promise<void> | void;
+    /**
+     * The most relevant strategies for `query`, within `scope`, at most `limit`.
+     *
+     * `limit` must be a non-negative integer, or `Infinity` for the explicit "no cap" (return every
+     * match). Any other value — NaN, `-Infinity`, negative, fractional — is refused rather than folded
+     * into some nearby number (ruled 2026-08-04): a retrieval cap that silently becomes 0 turns "give me
+     * everything" into "give me nothing", and the caller sees only an empty result it cannot distinguish
+     * from "no strategies stored".
+     */
     find(scope: string, query: string, limit: number): Promise<StoredStrategy[]> | StoredStrategy[];
+    /**
+     * Optional: trim a scope to `maxSize` (evicting the least useful). `maxSize` must be a non-negative
+     * integer; 0 is a legal "empty the scope". Unlike {@link find}'s `limit`, `Infinity` is REFUSED here
+     * (ruled 2026-08-04): this is a capacity cap, and a capacity cap can be widened but never turned off.
+     */
     prune?(scope: string, maxSize: number): Promise<void> | void;
 }
+/**
+ * Default in-memory store. Retrieval: a stored problem must contain **every significant** query token
+ * (and there must be ≥1) — near-exact on the meaningful words, ignoring stopword noise. High precision
+ * by design. Ranked by `confidence × recency`. Per-scope capacity cap with eviction on save.
+ */
 export declare class InMemoryStrategyStore implements StrategyStore {
     private byScope;
     private readonly maxPerScope;
@@ -20,5 +56,6 @@ export declare class InMemoryStrategyStore implements StrategyStore {
     save(s: StoredStrategy): void;
     find(scope: string, query: string, limit: number): StoredStrategy[];
     prune(scope: string, maxSize: number): void;
+    /** Total stored strategies (across scopes); for tests/observability. */
     get size(): number;
 }

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

@@ -1,4 +1,11 @@
 import { type ExecResult, type ExecutionEnv, ExecutionError, FileError, type FileInfo, type Result } from "../internal/harness.js";
+/**
+ * A no-op ExecutionEnv for tool/MCP-only deployments (no shell, no filesystem).
+ *
+ * AgentHarness requires an `env`, but the normal tools+MCP code path never touches it.
+ * Every filesystem op returns a `not_supported` FileError; `exec` returns `shell_unavailable`.
+ * If a task genuinely needs shell/fs, supply a real ExecutionEnv instead (e.g. a Node or SSH one).
+ */
 export declare class StubExecutionEnv implements ExecutionEnv {
     cwd: string;
     constructor(cwd?: string);

package/dist/core/surrogate-safe-slice.d.ts

@@ -1,4 +1,39 @@
+/**
+ * Code-point-boundary-safe head/tail slicing — the one arithmetic every head+tail-with-marker truncator in
+ * this repo needs (`truncateError`, `clipWithFilePointer`, `truncateMcpErrorText`, `boundedString`,
+ * `truncateForSummary`).
+ *
+ * Why this exists as its own module: cutting a string at a UTF-16 code-unit index can land BETWEEN the two
+ * halves of an astral code point, and the result is a lone surrogate — a string that still satisfies the
+ * length bound but can no longer round-trip through UTF-8 (JSON frames, log files, prompt assembly). The
+ * same defect has been found and fixed one site at a time (RB-122 in `clipWithFilePointer`, then
+ * `truncateError`, then the three siblings above), which is exactly the shape a shared primitive prevents.
+ *
+ * Anchored on CC 2.1.220 `A7e`'s helpers `ma` (head) / `_W` (tail): drop the straddling code point WHOLE
+ * rather than emit half of it. Zero imports, so any module in the repo may depend on it without risking an
+ * import cycle.
+ *
+ * NOTE for whoever next touches `src/core/tool-errors.ts`: that file still declares a byte-identical private
+ * pair (`sliceHeadSafe`/`sliceTailSafe`, added by the earlier car in this class). Collapsing it onto this
+ * module — delete the two private copies plus `isHighSurrogate`/`isLowSurrogate` and import from here — is
+ * the remaining step to "one construction point"; it is outside this car's edit surface and is reported
+ * rather than done here.
+ */
+/** High half of a surrogate pair (U+D800–U+DBFF): valid only when immediately FOLLOWED by a low half. */
 export declare const isHighSurrogate: (c: number) => boolean;
+/** Low half of a surrogate pair (U+DC00–U+DFFF): valid only when immediately PRECEDED by a high half. */
 export declare const isLowSurrogate: (c: number) => boolean;
+/**
+ * Head-keep of at most `keep` code UNITS that never ends on a lone high surrogate — a code point straddling
+ * the cut is dropped whole (CC 2.1.220 `ma`).
+ *
+ * Callers must derive any "how much was dropped" count from the RETURNED length, never from `keep`: when
+ * the rollback fires the result is one unit SHORTER than the budget, and a count computed from `keep`
+ * under-reports by that unit.
+ */
 export declare function sliceHeadSafe(s: string, keep: number): string;
+/**
+ * Tail-keep counterpart: at most `keep` code units, never STARTING on a lone low surrogate (CC 2.1.220
+ * `_W`). Same rule for the caller's dropped-count arithmetic — read it off the returned length.
+ */
 export declare function sliceTailSafe(s: string, keep: number): string;