@sema-agent/core 5.20.0 → 5.21.0

package/dist/tools/fs/search.d.ts

@@ -1,46 +1,153 @@
 import type { ExecutionEnv } from "../../internal/harness-types.js";
+/** Directories never worth crawling (design/64 §10.3) — dependency/build/cache trees, PLUS the VCS
+ *  metadata directories CC names explicitly (RB-200 F1, 220 @368402: `Ok_ = [".git",".svn",".hg",
+ *  ".bzr",".jj",".sl"]` — git/svn/mercurial/bazaar/jujutsu/sapling). `.bzr`/`.jj`/`.sl` are additive here
+ *  (the other three VCS dirs already lived in this list for the build/cache reason above; they're
+ *  identical either way). See {@link buildIgnore}'s own comment for why this list is now the ENTIRE
+ *  directory-skip story — the blanket "any dot-prefixed name is invisible" rule this list used to sit
+ *  beside is gone. */
 export declare const DEFAULT_IGNORE_DIRS: ReadonlySet<string>;
 export interface GrepParams {
+    /** Regular expression (ripgrep semantics) — CC 2.1.209 parity: the pattern is ALWAYS a regex; the
+     *  old `regex?: boolean` literal-by-default switch is retired (a legacy `regex` argument sent by an
+     *  old caller is tolerated and ignored at the tool layer, never a failure). */
     pattern: string;
+    /** Restrict the search to this sub-path (relative to root, or absolute within root). */
     path?: string;
+    /** Only search files matching this glob (e.g. `*.ts`, `*.{ts,tsx}`). 批④ #6 (CC parity): a
+     *  comma/whitespace-separated list (`"*.ts,*.tsx"`) is split into multiple globs (brace globs kept whole). */
     glob?: string;
+    /** 批④ #5 (CC 2.1.201 `-o`): print only the matched (non-empty) parts of each matching line, one match
+     *  per output line (rg -o / --only-matching). content mode only; ignored otherwise (CC parity).
+     *  1.253: with `multiline` the JS fallback emits the matched SEGMENT's lines (rg -U -o shape). */
     only_matching?: boolean;
+    /** content: `path:line:text`. files_with_matches (default, CC 2.1.209): `path`. count: `path:count`. */
     output_mode?: "content" | "files_with_matches" | "count";
+    /** Lines of context around a match (content mode only) — CC's `-C`. */
     context?: number;
+    /** Lines of context BEFORE each match (content mode) — CC's `-B`. Wins over `context` for the before-window. */
     context_before?: number;
+    /** Lines of context AFTER each match (content mode) — CC's `-A`. Wins over `context` for the after-window. */
     context_after?: number;
+    /** File type filter — CC's `type` (rg `--type`): "js", "py", "rust", "go", "ts", … The rg path uses rg's
+     *  built-in type table; the JS fallback maps common types to globs (unknown types are ignored with a note). */
     type?: string;
+    /** Case-insensitive match — CC's `-i`. */
     ignore_case?: boolean;
+    /** Match across line boundaries — CC's multiline `-U`. JS fallback approximates per-file. */
     multiline?: boolean;
+    /** Cap the number of output items (default 250) — CC's `head_limit`. */
     head_limit?: number;
+    /** Skip the first N output lines — CC's `offset` (pagination partner of head_limit). */
     offset?: number;
 }
+/** 批④ #6 (CC 2.1.198 Grep call, bundle :333383-333390): split the `glob` param into individual glob
+ *  tokens — whitespace-separated first; a token WITHOUT braces is further split on commas
+ *  (`"*.ts,*.tsx"` → two globs), while a brace token (`*.{ts,tsx}`) is kept whole (its commas are
+ *  alternation syntax, not separators). CC-verbatim splitting rules. */
 export declare function splitGlobParam(glob: string): string[];
+/** 批④ #8 (CC 2.1.198 RWp, bundle :332987): decompose an ABSOLUTE glob pattern into a base directory +
+ *  relative pattern — cut at the last separator before the first glob metachar (`* ? [ {`); a pattern
+ *  with no metachar splits dirname/basename. Returns undefined for a relative pattern (caller keeps it
+ *  as-is) or when no usable base can be derived. */
 export declare function splitAbsoluteGlobPattern(pattern: string): {
     baseDir: string;
     relativePattern: string;
 } | undefined;
+/**
+ * POSIX-safe single-quote so an arbitrary model-supplied string can't break out of the shell command that
+ * runs ripgrep. Wraps in single quotes (inside which the shell expands nothing — no `$()`, backtick, `;`, or
+ * glob) and escapes any embedded single quote via the `'\''` idiom (close, escaped-quote, reopen). Exported
+ * for direct injection testing (council [R145]). Renamed from `shq` for legibility.
+ */
 export declare function shellQuote(s: string): string;
+/**
+ * RB-284 ③ (成批, CC 220 `xGg`/`MCu` @240961-240967 亲核) — the tokens of a `glob` argument that this
+ * engine CANNOT compile as glob syntax, i.e. the ones whose metacharacter would silently degrade to a
+ * literal match.
+ *
+ * The harm this closes is specific and asymmetric. An unknown `type` degrades to searching EVERY file —
+ * a SUPERSET of what was asked, wrong but self-evidently over-broad, and sema already discloses it with
+ * a `[note: unknown type …]` line. An unparseable `glob` degrades the other way: `src/[ab.ts` stops
+ * being a character class and becomes a request for a file literally NAMED `src/[ab.ts`, so the filter
+ * silently narrows to (almost always) nothing and the search answers a clean "No matches." — a
+ * false negative wearing the exact shape of a successful exhaustive search. That is the RB-264 G2
+ * failure class, and this repo's standing verdict on it is: no real data ⇒ isError, never a degraded
+ * answer.
+ *
+ * CC hard-errors on the same input class rather than searching at all — its ripgrep stderr matcher
+ * `xGg` covers `error parsing glob` (alongside regex-parse / unrecognized-file-type / flag-parse
+ * errors) and raises `Search failed — ripgrep rejected the pattern, glob, or file type without
+ * searching`. sema rejects at the INPUT level instead of waiting for a stderr string, because sema has
+ * two search engines (rg + the JS fallback) and only the rg one would ever produce that stderr: a
+ * rejection that fires only when ripgrep happens to be installed is not a contract. The `type` leg
+ * deliberately does NOT get this treatment (see the `typeNote` site) — over-broad-with-a-note is an
+ * honest answer, silently-narrowed is not.
+ */
 export declare function invalidGlobTokens(glob: string): string[];
+/** Lightweight `.gitignore` matcher (handles comments, negation, dir-only `/`, anchoring, `*`/`?`). */
 export declare function gitignoreMatcher(content: string): (rel: string, isDir: boolean) => boolean;
+/** Build the combined ignore predicate (ignore-set ∪ .gitignore) for a JS-fallback walk.
+ *  Exported so repo-map (design/72 §1) walks with the SAME ignore semantics as grep/glob.
+ *
+ * RB-200 F1(形态一,CC 220 语料证实,@368590-368592 Grep `T=["--hidden"]; for(N of Ok_) T.push("--glob",
+ * "!"+N)`,@367957/367959-367965 Glob `CLAUDE_CODE_GLOB_HIDDEN` 默认 true 同样带 `--hidden`): CC's own
+ * "keep it quiet" posture is NOT "every dot-prefixed name is invisible" — it's `--hidden` (show
+ * everything dot-prefixed) plus an explicit VCS-directory exclusion list ({@link DEFAULT_IGNORE_DIRS}).
+ * The blanket rule this function used to apply here (`base.startsWith(".")`) instead made EVERY hidden
+ * file/dir invisible with no caveat — `.github/`, `.claude/`, `.env.example` never existed as far as
+ * Grep/Glob/repo-map were concerned, not even as an honest "search skipped this" note (A-8 posture: an
+ * unflagged gap reads as exhaustive). Removed; {@link DEFAULT_IGNORE_DIRS} (dependency/build/cache trees
+ * + the 6 VCS metadata dirs) and `.gitignore` are now the entire directory-skip story, matching CC. */
 export declare function buildIgnore(env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<(rel: string, isDir: boolean) => boolean>;
+/** What a bounded walk actually saw — so consumers can be HONEST about incompleteness (A-4 class sweep:
+ *  silently bounded results must never read as exhaustive). */
 export interface WalkResult {
+    /** Greppable text files (binary-extension and oversize files excluded). */
     files: string[];
+    /** Name-only entries: binary-extension + over-{@link FILE_MAX_BYTES} files. Content search skips them
+     *  (grep semantics / memory bound), but globbing matches NAMES — these must still be visible to it
+     *  (previously `glob *.png` could never match anything). */
     nameOnly: string[];
+    /** True when the walk hit its file-count or depth ceiling — results MAY be missing files. (Ceiling
+     *  ONLY; unreadable-dir and abort incompleteness live on their own fields below — use
+     *  {@link walkIsPartial} for the any-cause check.) */
     incomplete: boolean;
+    /** Non-binary files skipped by content search for being over {@link FILE_MAX_BYTES} (also in
+     *  `nameOnly`). Surfaced by grep so "No matches." can't silently mean "didn't look". */
     skippedLarge: number;
+    /** fidelity-sweep F2: directories whose listing FAILED (EACCES, transient I/O) — whole subtrees the
+     *  walk never saw. */
     skippedUnreadable: number;
+    /** F2: the walk was cut short by an abort — the result is a prefix, not a survey. */
     aborted: boolean;
+    /** CC 2.1.209 Glob parity (batch A2): modification time (ms epoch) per walked path (files AND
+     *  name-only entries), captured from the listing that discovered them — so glob can sort by mtime
+     *  without a second stat pass. An env whose listings carry no numeric `mtimeMs` simply leaves
+     *  entries out of this map (consumers fall back to name order). */
     mtimes: Map<string, number>;
 }
+/** F2: any-cause incompleteness — a result built on this walk must not present itself as exhaustive. */
 export declare function walkIsPartial(w: WalkResult): boolean;
+/** Bounded, ignore-aware recursive walk. Returns absolute file paths under `start`. Exported for
+ *  repo-map (design/72 §1) — same bounded/ignore-aware traversal as grep/glob, one source of truth. */
 export declare function walk(env: ExecutionEnv, root: string, start: string, ignore: (rel: string, isDir: boolean) => boolean, signal?: AbortSignal): Promise<WalkResult>;
+/** Injectable execution boundaries for the JS-fallback scan (tests shrink them; callers use defaults). */
 export interface JsGrepGuards {
+    /** Wall-clock budget (ms) for matching a SINGLE file before the scan stops with a diagnosable error. */
     budgetMs?: number;
+    /** Longest line/content (chars) a gray-zone pattern may be matched against. */
     longLineLimit?: number;
 }
+/** JS-fallback grep: ignore-aware walk + per-line scan, honoring output_mode / context / head_limit. */
 export declare function jsGrep(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal, guards?: JsGrepGuards): Promise<string>;
+/** Detect ripgrep once per env (cached). */
 export declare function detectRipgrep(env: ExecutionEnv): Promise<boolean>;
+/** How a grep result was produced when the ripgrep leg could not complete normally. Either the
+ *  delivered text IS ripgrep's own partial output (`partial: true`), or ripgrep produced nothing
+ *  usable and the results came from the JS fallback scanner (`fallback: "js-scan"`). Absent on a
+ *  clean run (and on rg-less envs, where the JS scanner is the designed primary path, not a
+ *  degradation). */
 export type GrepDegradation = {
     partial: true;
     reason: string;
@@ -48,17 +155,41 @@ export type GrepDegradation = {
     fallback: "js-scan";
     reason: string;
 };
+/** Structured grep result: the model-facing text plus the degradation facts, so the tool layer can
+ *  ship them on the structured frame instead of leaving them prose-only. */
 export interface GrepRunResult {
     text: string;
     degraded?: GrepDegradation;
 }
+/** ripgrep grep: build flags from params, run, normalize to the same output as {@link jsGrep}.
+ *  Result-fidelity contract: output ripgrep DID produce is never silently replaced by a fallback
+ *  rescan — partial results ship with a caveat; only a zero-output failure degrades to
+ *  {@link jsGrep}, and that degradation is declared in both text and structure. An external abort
+ *  propagates as the interruption it is (no fallback rerun). */
 export declare function rgGrepDetailed(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal): Promise<GrepRunResult>;
+/** grep dispatch: ripgrep when the env has it, else the hardened JS fallback (design/64 §10.3).
+ *  Returns the degradation facts alongside the text so the tool layer can surface them structurally. */
 export declare function runGrepDetailed(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal): Promise<GrepRunResult>;
+/** Text-only wrapper of {@link runGrepDetailed}. */
 export declare function runGrep(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal): Promise<string>;
+/** glob: find files by name pattern, with optional sub-path scoping; returns RELATIVE paths (design/64 §10.4). */
 export declare function runGlob(env: ExecutionEnv, root: string, pattern: string, opts?: {
     path?: string;
     max?: number;
 }, signal?: AbortSignal): Promise<string>;
+/** Structured sibling of {@link runGlob} (design/116 W3): same walk/match, plus the CC-shaped facts a
+ *  shell renders (`filenames`/`numFiles`/`truncated`/`durationMs`/`totalMatches`/`countIsComplete`)
+ *  without re-parsing the text.
+ *
+ *  CC207 backlog P2-2 (CC 2.1.206:397761-398004 = 2.1.207:342454-342633, node-sliced verbatim):
+ *   · `totalMatches` — "Total number of matching files before truncation. A lower bound when
+ *     countIsComplete is false." (CC: `totalMatches: g.length`)
+ *   · `countIsComplete` — "Whether totalMatches is the exact total (true) or a floor because the
+ *     underlying search truncated its own output (false)." (CC: `countIsComplete: !m`, m = the rg
+ *     enumeration cut its own output; sema equivalent = the bounded walk hit its file/depth ceiling)
+ *   · `numFiles` — "Number of file paths returned (after any truncation)" (CC: `numFiles: u.length`
+ *     post-slice; was matchedAll.length here — pre-truncation total — fixed to the CC contract)
+ *   · `truncated` — CC: `y = m || g.length > n + r` (underlying-incomplete OR over the result cap). */
 export declare function runGlobDetailed(env: ExecutionEnv, root: string, pattern: string, opts?: {
     path?: string;
     max?: number;

package/dist/tools/loop-tick.d.ts

@@ -1,8 +1,32 @@
 export interface AutonomousLoopPromptOptions {
+    /**
+     * True on the FIRST resolved tick of a session: the tick instructions are preceded by the
+     * `# Autonomous loop check` preamble (separated by `\n\n---\n\n`, CC P6c shape). The caller
+     * owns the latch (CC keeps it in process state; core is stateless). Default false.
+     */
     firstTick?: boolean;
+    /**
+     * Selects CC's `tengu_kairos_loop_persistent` variant (default false = the steward-framed
+     * preamble + "third straight tick" convergence wording — CC's gate default): true = the
+     * persistence-framed preamble ("Persistence is the point of autonomous mode") and the
+     * ending-the-loop wording without the third-tick clause.
+     */
     persistentVariant?: boolean;
+    /**
+     * Appends the PushNotification ping guidance (CC `FFr`, gated by `tengu_kairos_push_notifications`
+     * — default false). core ships no PushNotification tool; only a deployment that mounts one under
+     * that name should set this, or the appendix becomes a hallucination source.
+     */
     pushNotification?: boolean;
 }
+/** CC `FFi` (:205310) — first-tick preamble, DEFAULT variant (steward framing). Verbatim. */
 export declare const AUTONOMOUS_LOOP_PREAMBLE = "# Autonomous loop check\n\nYou're being invoked on a timer while the user is away or occupied. The point is to keep work moving forward without the user driving every step \u2014 finishing things they started, maintaining PRs they're building, catching problems before they come back to find them. You're a steward, not an initiator. The user set you loose on their work, and the value you provide comes from reliably advancing things they've already set in motion, not from finding new things to do.\n\nThe key tension to navigate: the user trusts you enough to run autonomously, but that trust is easily lost. Acting on what the conversation already established is safe and valuable. Inventing new work or making irreversible changes without clear authorization erodes trust fast. When you're unsure whether something falls into \"continuing established work\" or \"inventing new work,\" lean toward the former only when the transcript provides clear evidence the user wanted it done. If you find yourself reaching for justifications about why a push is probably fine, that's a signal to wait.\n\n## What to act on\n\nThe current conversation is your highest-signal source \u2014 re-read the transcript above, since everything there is something the user was actively engaged with. The strongest signal is an in-progress PR you've been building together: review comments to address and resolve, failing CI checks to diagnose (and re-enqueue if they're flakes), merge conflicts to fix. The goal is to get the PR into a state where it's ready to merge pending only human review \u2014 the user shouldn't come back to find a PR blocked on things you could have handled. After that, look for unfinished implementation where the last exchange left something half-done, and explicit \"I'll also...\" or \"next I'll...\" commitments the conversation made and didn't honor. Weaker but still real: dangling questions you could now answer, verification steps that were skipped, edge cases that were mentioned but not handled, and natural continuations that don't require new decisions.\n\nIf you find anything in this category, act on it \u2014 actually do the work, don't describe what could be done. Run the tests, don't say \"you could run the tests.\" The whole point of autonomous operation is that work gets done while the user is away.\n\nWhen the conversation transcript has nothing left, the current branch's pull/merge request on the user's SCM is the next-best place to look. This is maintenance work \u2014 valuable, but lower priority than continuing the user's active work. Find the PR/MR for the current branch via the SCM's CLI, then check three things: CI status, unresolved review threads, and whether the branch has fallen behind the base. For failing CI, pull the failing job's logs and diagnose before acting \u2014 flaky-shaped failures (timeout, runner died, transient network) can be re-enqueued; real failures need a reproduction and a minimal fix. For unresolved review threads, fetch the comment, address the feedback, push, and resolve the thread via, for example, the GitHub GraphQL `resolveReviewThread` mutation (or the equivalent for whichever SCM the project uses). Before pushing anything, check whether someone else has pushed to the branch while you were working \u2014 if so, rebase (don't merge) to keep history clean.\n\nWhen CI is green, threads are clear, and there's idle time, sweeping the branch for issues is a good use of that time \u2014 bug-hunt or simplification passes catch problems before reviewers do, saving everyone a round-trip.\n\nIf everything is genuinely quiet \u2014 no conversation work, no PR maintenance \u2014 say so in one sentence and stop. No summary of what you checked, no list of what you might do later. The user will see your message in the transcript when they come back; three consecutive \"nothing to do\" results means you should scale back to a quick CI check and stop, not narrate.\n\n## Repeated invocations\n\nIf you see earlier autonomous checks in this conversation, adjust your scope accordingly. If a previous check left a question the user hasn't answered, the cost of acting depends on reversibility: for reversible actions (local edits, running tests), make your best call and proceed; for irreversible ones (pushing, deleting, sending), keep waiting \u2014 the cost of acting wrongly on something irreversible is much higher than the cost of waiting one more cycle. If three or more consecutive checks have found nothing actionable, things are quiet \u2014 do one quick CI/threads check and stop in a single line. Repeated \"nothing to do\" messages clutter the transcript and waste the user's attention when they come back to review.\n\nRead and analyze freely \u2014 understanding the state of things has no blast radius. Make edits and run tests when you're confident they continue established work. Commit and push only when you're clearly continuing something the user authorized, or when the work pattern makes the intent obvious \u2014 like fixing CI on a PR you've been building together.\n";
+/** CC `w6c` (:205335) — first-tick preamble, PERSISTENT variant. Verbatim. */
 export declare const AUTONOMOUS_LOOP_PREAMBLE_PERSISTENT = "# Autonomous loop check\n\nYou're being invoked on a timer while the user is away or occupied. The point is to keep work moving forward without the user driving every step \u2014 finishing things they started, maintaining PRs they're building, catching problems before they come back to find them, and following through on the *spirit* of the task they gave you, not just its literal scope. The user set you loose on their work, and the value you provide comes from reliably advancing things they've already set in motion.\n\nThe key tension to navigate: the user trusts you enough to run autonomously, but that trust is easily lost. Acting on what the conversation already established is safe and valuable. For irreversible actions (push, delete, send), require clear authorization in the transcript or use a reversible alternative (a draft, a local commit, a queued message). For reversible actions (edits, tests, drafts, exploration), bias toward acting \u2014 the cost of an unneeded local edit is near zero, and the cost of a stalled loop is high. When you're unsure whether something falls into \"continuing established work\" or \"inventing new work,\" lean toward continuing whenever the transcript gives you any reasonable thread to pull on.\n\n## What to act on\n\nThe current conversation is your highest-signal source \u2014 re-read the transcript above, since everything there is something the user was actively engaged with. The strongest signal is an in-progress PR you've been building together: review comments to address and resolve, failing CI checks to diagnose (and re-enqueue if they're flakes), merge conflicts to fix. The goal is to get the PR into a state where it's ready to merge pending only human review \u2014 the user shouldn't come back to find a PR blocked on things you could have handled. After that, look for unfinished implementation where the last exchange left something half-done, and explicit \"I'll also...\" or \"next I'll...\" commitments the conversation made and didn't honor. Weaker but still real: dangling questions you could now answer, verification steps that were skipped, edge cases that were mentioned but not handled, and natural continuations that don't require new decisions.\n\nIf you find anything in this category, act on it \u2014 actually do the work, don't describe what could be done. Run the tests, don't say \"you could run the tests.\" The whole point of autonomous operation is that work gets done while the user is away.\n\nWhen the conversation transcript has nothing left, the current branch's pull/merge request on the user's SCM is the next-best place to look. This is maintenance work \u2014 valuable, but lower priority than continuing the user's active work. Find the PR/MR for the current branch via the SCM's CLI, then check three things: CI status, unresolved review threads, and whether the branch has fallen behind the base. For failing CI, pull the failing job's logs and diagnose before acting \u2014 flaky-shaped failures (timeout, runner died, transient network) can be re-enqueued; real failures need a reproduction and a minimal fix. For unresolved review threads, fetch the comment, address the feedback, push, and resolve the thread via, for example, the GitHub GraphQL `resolveReviewThread` mutation (or the equivalent for whichever SCM the project uses). Before pushing anything, check whether someone else has pushed to the branch while you were working \u2014 if so, rebase (don't merge) to keep history clean.\n\nWhen CI is green, threads are clear, and there's idle time, sweeping the branch for issues is a good use of that time \u2014 bug-hunt or simplification passes catch problems before reviewers do, saving everyone a round-trip.\n\nIf everything is genuinely quiet \u2014 no conversation work, no PR maintenance \u2014 say so in one sentence and keep the loop alive. Before stopping, broaden once: re-read the original task framing, check whether earlier ticks deferred anything (\"I'll wait for X\"), and look at sibling PRs/branches the user owns. Persistence is the point of autonomous mode. Only stop if the original task is provably complete or the user said to stop. (Pacing \u2014 how long to wait before the next tick \u2014 is handled by the per-mode reminder appended to this preamble; don't try to manage delay from here.)\n\n## Repeated invocations\n\nIf you see earlier autonomous checks in this conversation, adjust your scope accordingly. If a previous check left a question the user hasn't answered, the cost of acting depends on reversibility: for reversible actions (local edits, running tests), make your best call and proceed; for irreversible ones (pushing, deleting, sending), keep waiting \u2014 the cost of acting wrongly on something irreversible is much higher than the cost of waiting one more cycle. If three or more consecutive checks have found nothing actionable, broaden scope once before considering stopping \u2014 re-read the original task, check sibling work, look for verification or polish steps that were skipped. A loop that quits the moment work goes quiet is less useful than one that waits.\n\nRead and analyze freely \u2014 understanding the state of things has no blast radius. Make edits and run tests when you're confident they continue established work. Commit and push only when you're clearly continuing something the user authorized, or when the work pattern makes the intent obvious \u2014 like fixing CI on a PR you've been building together.\n";
+/**
+ * Resolve a fire-time prompt: if it is one of the two autonomous-loop sentinels, return the tick
+ * instructions the model should actually receive (CC `P6c`); otherwise return `null` — the caller
+ * enqueues the prompt verbatim. Stateless: the first-tick preamble latch and the decision to
+ * resolve at all belong to the calling scheduler runtime.
+ */
 export declare function resolveAutonomousLoopPrompt(prompt: string, opts?: AutonomousLoopPromptOptions): string | null;

package/dist/tools/monitor.d.ts

@@ -1,22 +1,77 @@
+/**
+ * design/135 G2 (审计 [485]① 🔴) — the `Monitor` tool: run a shell command in the background and watch its
+ * stdout as a stream of NOTIFICATION EVENTS (the自主循环 core piece: "watch this and tell me when something
+ * happens" without burning poll turns).
+ *
+ * CC-parity semantics (live-harness schema, the archived ground truth):
+ *  ① every stdout LINE becomes one event; ② lines within the 200ms batch window coalesce into ONE
+ *  notification; ③ process exit ends the watch (exit code reported); ④ non-persistent watches are killed at
+ *  `timeout_ms` (default 5min, max 60min); ⑤ stderr never notifies but is spooled (TaskOutput-readable);
+ *  ⑥ an event storm is SUPPRESSED first and auto-stops the monitor only if it persists (RB-334, CC `PCo`
+ *     220:403278-403321 two-level control — the suppressed count and the overload duration are disclosed
+ *     on both the suppression frame and the stop notification).
+ *
+ * Wiring: the process runs through the SAME ExecutionEnv background seam as Bash(run_in_background)
+ * (`spawnBackground` — remote envs included); the watcher/batching/timeout machinery lives in
+ * {@link TaskRegistry.registerMonitor} (background_bash G2b watcher's near kin); events ride the
+ * TaskNotificationPayload lane at "later" priority (delivered at the next turn boundary like every
+ * notification — ruled 2026-08-05; consecutive frames drain as one boundary batch, and a backlog past
+ * the engine-note cap parks per session, so a chatty watcher cannot monopolize the run's boundaries).
+ * 飞轮 [492]② (1.257): events born BETWEEN turns (run torn down / harness idle — the long-watch main case)
+ * are no longer lost: the Runner parks them per session (bounded, drop-disclosing) and the session's next
+ * run redelivers them through the same notification lane at its first turn boundary.
+ * 飞轮 [511]③ (CC parity): a monitor's lifetime = min(timeout_ms, process exit, TaskStop); a `persistent`
+ * one is SESSION-anchored (reaped at session release). NEITHER is run-anchored: the run teardown leaves an
+ * in-window non-persistent watch alive (process on the dispose except-list, watcher ticking, row kept), so
+ * cross-turn watching — CC's main Monitor use case — works with the default persistent:false too; its
+ * between-turns events AND its timeout/exit terminal ride the same pending lane.
+ * The handle is a first-class m* registry task: TaskOutput serves the re-readable spool, TaskStop stops the
+ * watch (design/134 stoppedBy attribution applies automatically).
+ *
+ * Security posture: `command` is an arbitrary shell script ⇒ effect:"write", same as Bash, and prepare-task
+ * folds Monitor into the SAME shellGate tighten (irreversibility tier + reversibility probe on the same
+ * `command` arg) — Monitor is never a policy side-door around a gated Bash.
+ *
+ * 深对比残差 M17 CLOSED (2026-07-09 live-CC probe, docs/cc-probe-198/live-schema-monitor-worktree-2026-07-09.json):
+ * the deep-dive bundle showed a `command? + ws?:{url,protocols}` dual-mode schema; the LIVE current-CC schema is
+ * shell-single-mode ({command, description, persistent, timeout_ms} — no ws branch anywhere in desc or schema).
+ * sema's shell-single-mode Monitor is therefore aligned with current CC — do NOT port a WebSocket event-source
+ * branch off the stale bundle. (Full-desc density diff vs the live guidance card remains P1, a separate item.)
+ */
 import type { AgentTool, ExecutionEnv } from "../internal/harness-types.js";
 import { type MonitorTimers, type TaskRegistry } from "../core/task-registry.js";
 import type { TaskNotificationPayload } from "../core/task-notification.js";
 import type { ToolResultStore } from "../core/tool-result-store.js";
 export interface MonitorToolOptions {
     registry: TaskRegistry;
+    /** Fallbacks when the runtime ctx carries no identity (direct mounts) — same posture as createBashTool. */
     owner?: string;
     scope?: string;
+    /** design/129: the session id — a `persistent` monitor registers session-scoped under it (outlives the
+     *  turn; reaped by the deployment's session release via `reapSessionBackground`). */
     sessionId?: string;
+    /** The notification sink (the run-local task-notification lane). Without it the monitor still runs and
+     *  spools — readable via TaskOutput — but no events reach the model (the tool reply says so honestly). */
     onTaskNotification?: (n: TaskNotificationPayload, opts?: {
         priority?: "now" | "next" | "later";
     }) => void;
+    /** The tracked logical cwd (shared with the hands band) — the monitor spawns there, like Bash. */
     cwdRef?: {
         current: string;
     };
+    /** design/87: injectable timers/clock for the watcher (tests drive ticks manually; default real timers). */
     timers?: MonitorTimers;
+    /** Test/deployment knobs (defaults: 200ms window, 50 batches/min). */
     batchWindowMs?: number;
     maxBatchesPerMinute?: number;
+    /** design/158 S2 (RB-364 半): the offload store a rolled-off spool middle spills to (see
+     *  task-registry-monitor.ts's spill helper). Absent ⇒ legal degrade, byte-identical rolling (no spill,
+     *  same loss shape as before this design). */
     toolResultStore?: ToolResultStore;
+    /** RB-465-b (HRD-PTL-3 残件): spec-level retain (`TaskSpec.retainBackgroundProcesses`) — the SECOND
+     *  retain lane, OR-composed with the env capability at the teardown sweep. Without this bit the mount
+     *  could only see the env lane, so a deployment retaining per spec still got the "session ends it"
+     *  wording in the persistent-watch receipt. Purely a RECEIPT input — enforcement stays at the sweep. */
     retainBackgroundProcesses?: boolean;
 }
 export declare function createMonitorTool(env: ExecutionEnv, opts: MonitorToolOptions): AgentTool;

package/dist/tools/scheduler-tools.d.ts

@@ -1,14 +1,65 @@
+/**
+ * design/105 — Scheduler 工具壳（CronCreate / CronDelete / CronList + ScheduleWakeup）。模型可调，把未来意图交给注入的
+ * daemon backend（`env` 实现 {@link SchedulerCapability}）。**core 薄壳**：工具只做 ① cron expr 白名单校验
+ * ② 组装 `intent`(模型面) + `SchedulerContext`(Runner-held，闭包捕获 principal/scope/sessionId) ③ 调
+ * `env.schedule/cancel/list`。持久化/触发/起新 task 全在 daemon。
+ * design/136 §2.2（BREAKING 去超集批）：`Sleep` 工具已撤除（CC 无此工具；等待抽象=Monitor/后台通知，定时再醒
+ * =CronCreate delay/at——纯语法糖零缺口）。旧名调用=通用响亮 roster miss（RB-476-A 墓碑已清）；daemon 已排的 `label:"sleep"`
+ * delayed intent 照常触发（daemon 只存 prompt+when，零迁移）。
+ *
+ * [c209-D2] 同名工具消歧（durable 分层激活批 2026-07-16，防后人混淆）：**我方 CronCreate = 持久 daemon 形**
+ * （对标上游产品 /schedule 的云端持久语义）；**上游同名工具是会话级易失体**（{cron: 5字段串, prompt,
+ * recurring: bool, durable: 死字段}——会话结束即消失）；壳仓 vendored 的 ScheduleCronTool 是上游原生实现，
+ * 与本工具无关。两形调用在此汇流：上游生态 skill 平移过来的 CC 形调用（`cron` 字符串，`durable` 缺省 false）
+ * 落 **session 生存期**（会话终结随会话 reap，绝不落成永生任务）；我方 `schedule` 对象形保持持久语义零回归，
+ * `durable: true` 显式亦持久。session 生存期需要 backend 能力位（supportsSessionLifetime），缺失时诚实拒绝
+ * 引导 `durable: true`——绝不静默升级语义。
+ *
+ * 挂载：prepare-task 在 `hasScheduler(executionEnv)` 时调 {@link createSchedulerTools}（需 Runner-held 上下文，故不在
+ * `createHandsToolkit` —— 与 present_plan/AskUserQuestion 同：这些工具都在 prepare-task 单独挂，那里有 spec.principal）。
+ */
 import type { AgentTool, ExecutionEnv } from "../internal/harness-types.js";
 export declare const SCHEDULE_WAKEUP_TOOL_NAME = "ScheduleWakeup";
+/** CronCreate-based autonomous-loop 哨兵(CC `Ldt`)。loop runtime(部署侧)在 fire 时解析回 autonomous-loop 指令。 */
 export declare const AUTONOMOUS_LOOP_SENTINEL = "<<autonomous-loop>>";
+/** ScheduleWakeup(dynamic-pacing)哨兵(CC `ePe`)——ScheduleWakeup 一律用 `-dynamic` 变体。 */
 export declare const AUTONOMOUS_LOOP_DYNAMIC_SENTINEL = "<<autonomous-loop-dynamic>>";
+/** Runner-held 上下文 + run-stop 出口，工具工厂闭包捕获（模型触不到）。 */
 export interface SchedulerToolContext {
+    /**
+     * **会话腿**的越权隔离键（Runner 填 sessionId ?? principal ?? taskId）。durable 腿不用这条链——它的键由
+     * {@link durableScopeOf} 从 principal 独立铸（ruled 2026-08-03，见该函数注释）。
+     */
     scope: string;
     principal?: string;
     sessionId?: string;
     taskConfig?: unknown;
+    /** `ctx.requestStopAfterTurn`（干净结束本 run 的 runner 原语出口）。design/136 §2.2：Sleep 撤除后本槽位
+     *  保留（human-suspend saga 等共用同一 runner 原语；prepare-task 仍注入）——当前 scheduler 三件不消费。 */
     requestStopAfterTurn?: () => void;
 }
+/**
+ * cron 深校验(CC CronCreateTool.validateInput parity):arity(RB-438 D4)+ 数值域(如 `61 * * * *` 分钟越域)
+ * + 永不触发(如 `31 2 30 2 *` 二月 30 日)。返回给模型自纠的错误句;合法返回 null。
+ *
+ * RB-438 D4 — **只收 5 字段**。带秒的 6 段此前收单成功并回执「Scheduled.」,而兑现腿(常驻 daemon)按标准
+ * 5 字段解析:6 段记录算不出 next-run,首次 tick 即被当作坏记录丢弃 ⇒ 任务永不触发,且没有任何回执说过它
+ * 没排上。收单 arity 必须等于开火 arity,差额只能用响亮拒绝补,不能用静默丢弃补。seam 上没有「秒粒度」
+ * 能力位可判({@link SchedulerCapability} 只有 supported / 上下限 / 两个 session 位),故取保守形:一律拒。
+ * 将来若真出现支持秒的 backend,加一个 additive 能力位在此开口(缺省仍拒),不要悄悄放行。
+ *
+ * 永不触发判定:标准 cron OR 语义(CC utils/cron.ts:150-158)—— dom 与 dow **都**受限时任一匹配即触发,而任何受限
+ * dow 每周都出现 → 必触发。所以唯一永不触发形态 = dom 受限 + dow 通配 + dom 值全部超出所有排程月份的天数上限。
+ */
 export declare function cronScheduleError(expr: string): string | null;
+/**
+ * cron → 人话(CC utils/cron.ts cronToHuman:218-308 类比,收窄到常见形态):"star/N * * * *"→"every N minutes"、
+ * "M star/N * * *"→"every N hours"、`M H * * *`→"daily at H:MM"、`M H * * D`→"weekly on <day> at H:MM"、
+ * `M H * * 1-5`→"weekdays at H:MM";其余原样返回(调用方以 `human !== expr` 判断是否可译)。
+ * 收 backend 的 `cron <expr>` 显示串(见 {@link cronExprFromSummary});6 段带秒不译(D4 已在收单面拒收)。
+ */
 export declare function cronToHuman(expr: string): string;
+/**
+ * 构建三个 scheduler 工具（仅当 `env` 暴露 {@link SchedulerCapability} 且 `supported:true`）。否则返回 `[]`（INERT）。
+ */
 export declare function createSchedulerTools(env: ExecutionEnv, ctx: SchedulerToolContext): AgentTool[];

package/dist/tools/sql-adapters.d.ts

@@ -1,11 +1,29 @@
+/**
+ * Dependency-free `query` adapters for common DB drivers, to plug into createSqlTool.
+ *
+ * These are structurally typed: you pass an already-created (ideally READ-ONLY) client/pool.
+ * No driver is a dependency of this package — install whichever you use in your app.
+ *
+ * Usage:
+ *   import pg from "pg";
+ *   const pool = new pg.Pool({ connectionString: READONLY_URL });
+ *   const tool = createSqlTool({ query: pgQuery(pool), allowTables: ["orders"] });
+ */
+/** node-postgres (`pg`) Pool/Client. */
 export declare function pgQuery(pool: {
     query: (text: string) => Promise<{
         rows: unknown[];
     }>;
 }): (sql: string) => Promise<unknown[]>;
+/**
+ * `mysql2/promise` connection or pool.
+ * Also use this for **TiDB** (MySQL wire-compatible): create a read-only `mysql2` pool
+ * pointed at your TiDB endpoint and pass it here.
+ */
 export declare function mysqlQuery(conn: {
     query: (sql: string) => Promise<[unknown, unknown]>;
 }): (sql: string) => Promise<unknown[]>;
+/** `better-sqlite3` database (synchronous). */
 export declare function sqliteQuery(db: {
     prepare: (sql: string) => {
         all: () => unknown[];

package/dist/tools/sql.d.ts

@@ -1,10 +1,35 @@
 import type { ToolSpec } from "../core/types.js";
 export interface SqlToolOptions {
+    /**
+     * Execute a query that has already passed read-only validation, returning rows.
+     * IMPORTANT: back this with **read-only database credentials** — the validation here is
+     * defense-in-depth, not the primary guarantee.
+     */
     query: (sql: string) => Promise<unknown[]>;
+    /**
+     * If set, the query may only reference these tables (case-insensitive). **Best-effort, NOT a hard
+     * isolation boundary.** Table extraction is regex-based; to stay sound it FAILS CLOSED — comma-joins
+     * (`FROM a, b`), sub-queries in FROM/JOIN, and set operations (UNION/INTERSECT/EXCEPT) are REJECTED
+     * (their full table set can't be reliably enumerated). Even so, do **NOT** rely on this alone for
+     * multi-tenant / cross-tenant isolation: back it with **read-only DB credentials scoped to the tenant +
+     * DB-level GRANTs**. The allowlist is a usability guardrail and defense-in-depth, not the security
+     * boundary. (Full AST-parser coverage is deferred to preserve the zero-extra-dependency posture.)
+     */
     allowTables?: string[];
+    /** Maximum rows returned to the model. Default 100. */
     maxRows?: number;
+    /** Tool name exposed to the model. Default "query_sql". */
     name?: string;
+    /** Description override. */
     description?: string;
 }
+/** Validate that `sql` is a single, read-only SELECT/CTE query within the allowlist. */
 export declare function validateReadOnlySql(sql: string, allowTables?: string[]): void;
+/**
+ * Build a safe, read-only `query_sql` tool.
+ *
+ * Layers of defense: (1) read-only DB credentials supplied by the caller's `query`,
+ * (2) static validation (single SELECT/WITH only, no DML/DDL, no comments/multi-statement),
+ * (3) optional table allowlist, (4) a row cap on what is returned to the model.
+ */
 export declare function createSqlTool(opts: SqlToolOptions): ToolSpec;

package/dist/tools/task-list.d.ts

@@ -1,4 +1,25 @@
 import type { ToolSpec } from "../core/types.js";
+/**
+ * design/119 (CC 2.1.198 parity) — the structured task-list tool family: `TaskCreate` / `TaskGet` /
+ * `TaskUpdate` / `TaskList`. CC 198's upgrade path over TodoWrite: individual tasks with stable ids,
+ * status transitions, dependencies (blocks/blockedBy), an optional owner, and free metadata — instead
+ * of TodoWrite's replace-the-whole-list. CC209 对齐批B B3: the two families are MUTUALLY EXCLUSIVE and
+ * this one is the DEFAULT — TodoWrite mounts only when the task list is explicitly off (the CC 209
+ * shape: TodoWrite isEnabled = !taskList; see `scenarios/full-body.ts`).
+ *
+ * State default: like TodoWrite, the default store lives in this factory's closure — FRESH per task
+ * and torn down with it; nothing durable, no deps, no egress (the model's own scratch, projected to
+ * observers only through each call's tool result / `details`). Descriptions follow CC 2.1.198
+ * (product-specific lines — teammate assignment, spinner/UI wording — trimmed or generalized).
+ *
+ * design/147 §6 D2 (CC 2.1.216 shared team task list): pass a {@link TaskListStore} to share ONE
+ * task list across several agents — CC 216's team coordination artifact ("Check the task list
+ * periodically. Create new tasks when work should be divided. Mark tasks resolved when complete.")
+ * is a task-list file under the team directory; the sema equivalent is this storage seam. A
+ * deployment mounts the SAME store instance into each teammate's tool bundle (same session = same
+ * trust domain — the list is model scratch either way, sharing adds no egress). The `owner` field's
+ * teammate-assignment semantics (trimmed in the 198 port) come back through this seam.
+ */
 export interface TaskListItem {
     id: string;
     subject: string;
@@ -10,16 +31,72 @@ export interface TaskListItem {
     blockedBy: string[];
     metadata?: Record<string, unknown>;
 }
+/**
+ * design/147 §6 D2 — the task-list persistence seam (storage-tier abstraction, same family as
+ * `RosterStore`/checkpoint store: core bundles a memory implementation; a deployment plugs pg/file
+ * behind the same interface and hands ONE instance to every teammate's tool bundle).
+ *
+ * Contract:
+ * - Methods MAY be async (a pg-backed store is); the bundled memory store is synchronous.
+ * - Each single method call must be atomic in the store. Multi-step read-modify-write sequences
+ *   (update, delete-with-pruning) are serialized PER STORE by the tools themselves within this
+ *   process ({@link createTaskListTools} keeps a per-store promise chain) — a store shared across
+ *   PROCESSES additionally needs its own transactional guarantees for those sequences, which is the
+ *   deployment's half (documented, not solved here; CC's file-backed team list has the same window).
+ * - `allocateId` is store-owned so concurrent teammates never mint colliding ids.
+ * - Value semantics: `get`/`list` return detached copies; `set` stores a detached copy. Callers
+ *   mutate their copy and write it back — a live-reference store would alias already-emitted events.
+ * - RB-274: `list` is ordered by ID (numeric ascending), not by write order. The tool lane always
+ *   allocates before it sets, so the two coincide there — but a store shared with an OUTSIDE writer
+ *   (a real CC instance on the same directory) can set an id out of order, and then the backends
+ *   disagreed: memory replayed its Map's insertion order while file/cc read the id order back off
+ *   disk. Ordering is part of the contract, not each backend's incidental iteration order.
+ */
 export interface TaskListStore {
     get(id: string): TaskListItem | undefined | Promise<TaskListItem | undefined>;
     set(id: string, item: TaskListItem): void | Promise<void>;
     delete(id: string): boolean | Promise<boolean>;
     list(): TaskListItem[] | Promise<TaskListItem[]>;
     allocateId(): string | Promise<string>;
+    /** codex S4 F2 — the transaction boundary for adapters whose backend outlives one wrapper
+     *  instance (pg, shared files): when present, the tools run EVERY read-modify-write sequence
+     *  inside `mutate` and the adapter supplies sequence-level atomicity (a DB transaction, an
+     *  advisory lock keyed on the backend — not on this object). Absent ⇒ the tools fall back to the
+     *  in-process per-store promise chain, which is exactly right for the bundled memory store (its
+     *  backend IS this object) and wrong for anything shared wider — implement `mutate` there. */
     mutate?<T>(fn: (tx: TaskListStore) => Promise<T>): Promise<T>;
 }
+/** codex S4 r2-F3 — the clone policy behind the detached-copy contract: metadata must be JSON-shaped
+ *  (structuredClone would accept — and SHARE — SharedArrayBuffer backing memory, and throws opaquely
+ *  on functions/proxies; the tool lane is always JSON, so this guards DIRECT store users). */
+/**
+ * RB-168 — the dependency arrays are STRUCTURAL, and a store must refuse a row that lacks them.
+ *
+ * The in-memory store rejected such a row incidentally: its snapshot helper spreads `t.blocks`, so a
+ * missing array threw "blocks is not iterable" at write. The file store had no such accident and wrote the
+ * row to disk, where it survived until `TaskUpdate` reached `t.blocks.includes(...)` — a poisoned row that
+ * passes the write and detonates at an unrelated later call, in a different session, with no trace of where
+ * it came from. Two backends disagreeing about what a valid row is means a test written against one has
+ * different semantics on the other.
+ *
+ * NORMALIZE rather than reject: the harm is a stored row that EXPLODES AT READ, not an incomplete one.
+ * Defaulting the arrays removes the harm without inventing a new failure mode for callers that legitimately
+ * write a partial row (a task with no dependencies has empty arrays — that is what the absence meant).
+ * Rejecting instead would have been a behaviour change dressed as a fix: the first attempt did exactly that
+ * and broke an in-tree test whose subject was id allocation, not row shape.
+ */
 export declare function normalizeTaskShape<T>(item: T): T;
 export declare function assertJsonMetadata(value: unknown, path?: string): void;
+/**
+ * RB-274 — the contract's `list` order, mirroring the CC-compat backend's `orderIds`
+ * (`stores/cc/task-list-store.ts`): numeric ids ascending (CC's own task order), any non-numeric id
+ * after them, lexicographically. Ties broken lexicographically so the comparator is total (and the
+ * order therefore stable across repeated calls, which the contract also requires).
+ */
 export declare function compareTaskIds(a: string, b: string): number;
+/** The bundled in-memory {@link TaskListStore} — detached copies both ways (see interface contract). */
 export declare function createMemoryTaskListStore(): TaskListStore;
+/** Build the four task-list tools sharing one task list. Mount all four together.
+ *  No `store` ⇒ a fresh private in-memory list (the design/119 per-run scratch shape, unchanged).
+ *  With `store` ⇒ the shared team task list (design/147 §6 D2) — mount the same instance everywhere. */
 export declare function createTaskListTools(store?: TaskListStore): ToolSpec[];

package/dist/tools/todo.d.ts

@@ -1,2 +1,10 @@
 import type { ToolSpec } from "../core/types.js";
+/**
+ * design/102 (K-8 CC full-body) — TodoWrite parity (CONTEXT leg). A private, in-task plan the model rewrites to
+ * track multi-step work. State lives in this factory's closure — FRESH per task (each `assembleCodeTools` call
+ * makes its own) and torn down with the task; nothing durable, no deps, no egress. `effect:"idempotent"` because
+ * re-sending the whole list is repeat-safe. Distinct from `present_plan` (that SUSPENDS for human review); this is
+ * the model's own scratch. Returns a RAW {@link ToolSpec} pushed via `spec.tools` (prepare-task defines it) — NOT
+ * mounted default-on, so it stays INERT for non-full-body runs. (A later slice may project the list to the wire.)
+ */
 export declare function createTodoWriteTool(): ToolSpec;