@sema-agent/core 5.19.0 → 5.21.0

package/dist/tools/fs/fs-bash.d.ts

@@ -2,31 +2,164 @@ import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
 import { type TaskRegistry } from "../../core/task-registry.js";
 import { type CwdRef } from "./fs-shared.js";
 import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
+/**
+ * design/80 D-2 (part-1): a parsed-command classifier for the `bash` tool, exposed as a
+ * `ToolSpec.reversibilityProbe`. A full shell is treated as egress+irreversible by DEFAULT; this probe is the
+ * "real parsed classifier" that lets a deployment safely auto-allow the provably-benign subset (the §4-OQ4
+ * doctrine: shell⇒always-gate UNLESS a parsed classifier is wired). design/154 upgraded it from
+ * single-command to {@link classifyCompoundReadonly}: a command is reversible ONLY if every `;`/`&&`/`||`/`|`
+ * connected segment is a bare command (no redirects/substitution/subshells/escapes/`&` anywhere — those
+ * whole-string reject, so it can't chain to `curl`/`git push`/`rm` or background past TaskStop) whose
+ * `argv[0]` is in the reversible allowlist (default
+ * {@link BASH_READONLY_DEFAULT_ALLOW} — `ls`/`cat`/`grep`/…, curated to commands with NO write/mutation mode
+ * under ANY args; the final-council MAJOR removed `date`/`hostname`/`file`, which mutate with args). EVERYTHING
+ * else (a write command, an egress command, an operator/pipe, a path-prefixed or env-assigned command, a
+ * non-string arg) is NOT reversible → the gate tightens it to an `irreversible_ask` durable suspend. Fail-closed
+ * by construction: the allowlist is the only path to `reversible: true`. It is an argv[0]-NAME filter, so the
+ * remaining residual is the OTHER axis — a listed reader with crafted args can still READ a secret (a DATA side
+ * channel, NOT irreversibility/egress); a deployment that widens `allow` owns that (and the mutation tradeoff).
+ *
+ * Wire it on the `bash` tool with `irreversibility: "maybe"` (or via `TaskSpec.shellGate: "classify"`); without
+ * a classifier a deployment should mark `bash` `irreversibility: "always"` (`shellGate: "always"`) — fail-closed.
+ *
+ * RB-412 closed the DATA-side residual named above for the read direction: pass `boundary` and a listed
+ * reader whose path arguments leave the allowed directories stops being reversible, so the gate asks
+ * instead of auto-allowing. Pass it as a FUNCTION wherever the working directory is observable (an
+ * in-task `cd` moves the base a relative operand resolves against, and the probe is called per command).
+ * Omitted ⇒ name-only classification, exactly as before.
+ *
+ * The BOUNDED READ-ONLY POLL LOOP arm: a monitoring consumer's whole idiom is `for i in $(seq 1 8);
+ * do tail -n 5 x.log; sleep 2; done`, which the compound face rejects as a class (`for` is not an
+ * allowlisted name) — making the classify gate behave like `always` for exactly the tool that polls
+ * the most. When the plain face rejects, the probe consults
+ * {@link classifyBoundedReadonlyPollLoop} — a narrow exact grammar (literal bound, `;`-separated
+ * allowlisted readers + literal `sleep`, the same read boundary, everything else banned; the full
+ * safety argument lives on that function). Additive by construction: the plain verdict is tried
+ * first and is never overridden.
+ */
 export declare function bashReversibilityProbe(allow?: readonly string[], boundary?: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => {
     reversible: boolean;
 };
+/** The CC-verbatim exit-1 interpretation for `command`, or undefined when exit 1 means a real error.
+ *  Conservative parse: last `;`/`&&`/`||`/newline statement → last `|` pipeline segment → leading
+ *  command name (env-assignments skipped, path prefix stripped); `git grep`/`git diff` special-cased
+ *  (CC cLp). Exported for the 批④ unit tests. */
 export declare function bashExitOneInterpretation(command: string): string | undefined;
 export declare function canAutoBackground(command: string, depth?: number): boolean;
+/**
+ * `bash` (effect:write) — a full shell. ⚠️ It runs with `rootCanonical` as the initial cwd but is NOT
+ * sandboxed: a command can `cd` out, read/write/delete any path the process can reach, and use the
+ * network. `rootPath` is a file-tool guard rail, NOT a bash sandbox (design/44 §5, DESIGN#6) — real
+ * isolation is the deployment's job (inject a chroot/container `ExecutionEnv`). Every call still goes
+ * through the design/37 policy gate, which a multi-tenant deployment MUST wire to constrain it. The cwd
+ * persists across calls (design/64 §8.1A): a per-task `cwdRef` starts at `rootCanonical` and is updated
+ * from the shell's final pwd after each command.
+ */
 export declare function createBashTool(env: ExecutionEnv, rootCanonical: string, coAuthor?: string | false, cwdRef?: CwdRef, taskOpts?: {
     taskRegistry?: TaskRegistry;
     taskOwner?: string;
     taskScope?: string;
+    /** (design/129, mirrors MonitorToolOptions.sessionId): when the task runs INSIDE a session,
+     *  a background command registers session-resident (owner = sessionId, sessionScoped flag) — it
+     *  survives the run teardown like CC's bg shells and is reaped at the session terminal. Absent ⇒
+     *  run-scoped registration exactly as before (killed-with-receipt at teardown). */
     sessionId?: string;
+    /** design/116 §7 G2b: completion-notification sink — a finished background command fires ONE
+     *  task-notification (priority "next": boundary interrupt, CC LocalShellTask posture). */
     onTaskNotification?: (n: import("../../core/task-notification.js").TaskNotificationPayload, opts?: {
         priority?: "now" | "next" | "later";
     }) => void;
+    /** design/116 detach: per-tool-call detach hub — a fired signal adopts the running command as background. */
     detachHub?: import("../../core/tool-detach.js").ToolDetachHub;
+    /**
+     * RB-198 F1 (CC 220 `Zry`/`WZi.#m` parity) — EXPLICIT deployment opt-in: on this command's own
+     * timeout, an eligible foreground command (see `canAutoBackground`'s own docstring — a
+     * DELIBERATELY simplified, narrower-than-CC classifier) is adopted as a background task instead
+     * of being killed. Defaults to `false` (the pre-existing, unconditional kill-on-timeout behavior)
+     * — this must NOT be inferred from `detachHub`/`taskRegistry` merely being present, because those
+     * are wired UNCONDITIONALLY for every task (the ctrl+b manual-detach capability, `defaultTaskRegistry`
+     * is a module-level singleton) — tying auto-eligibility to their mere presence would silently flip
+     * the timeout outcome for every existing caller/test with no opt-in signal at all (caught by
+     * `test/tool-cut-kill.test.ts`'s pre-existing "ordinary lane" self-timeout test: a
+     * `canAutoBackground`-eligible command it never expected to survive its timeout started surviving
+     * it). A deployment that wants the CC-parity behavior sets this explicitly; sema's own default
+     * Runner wiring currently does NOT set it, so this feature ships INERT until a caller opts in.
+     */
     autoBackgroundOnTimeout?: boolean;
+    /**
+     * RB-220 — mirrors {@link import("../../core/types.js").TaskSpec.oneShot}: this run has no later
+     * turn for an async background notification to land in (a headless `-p` process exits once the
+     * turn ends). Branches the background-launch receipt's guidance toward an active block-wait
+     * instruction instead of "you will be notified — do not poll", the same failure form
+     * `run_workflow`'s launch note was fixed for (a model that follows "end your turn" advice in a
+     * one-shot process loses the result — the process exits with nothing left alive to receive it).
+     */
     oneShot?: boolean;
+    /**
+     * RB-371 ②: the EXTRA containment roots of the structured file tools (additionalDirectories,
+     * canonical) — combined with `rootCanonical` and consulted ONLY for the post-`cd` disclosure
+     * note (a committed cwd outside every root gets one trailer line saying the structured tools'
+     * relative paths now resolve there and may be refused). Bash itself stays deliberately
+     * unconfined; passing this never gates anything.
+     */
     additionalRoots?: readonly string[];
+    /** RB-370 ② (cli [2088]): override of the `timeout` parameter's DEFAULT budget, in ms — see
+     *  {@link import("./index.js").HandsToolkitOptions.bashDefaultTimeoutMs} for the resolution
+     *  contract (options over env over constant; invalid values discarded). */
     bashDefaultTimeoutMs?: number;
+    /** RB-370 ② (cli [2088]): override of the `timeout` parameter's engine CEILING, in ms — only-widen
+     *  vs the resolved default; see {@link import("./index.js").HandsToolkitOptions.bashMaxTimeoutMs}. */
     bashMaxTimeoutMs?: number;
+    /**
+     * #181-F6 — whether the Monitor tool is on THIS run's roster (the Runner's own mount predicate is
+     * `backgroundTaskToolsActive`; it, not this tool, mounts Monitor). Read by the SR-2 gh rate-limit
+     * hint, whose closing clause teaches the Monitor tool: `false` ⇒ the clause is dropped (the sleep
+     * advice stays), absent/`true` ⇒ historic full wording (a standalone toolkit consumer may well have
+     * mounted Monitor itself — the omitted default must not silently rewrite its hint).
+     */
     monitorToolActive?: boolean;
 }): AgentTool;
+/**
+ * `bash_readonly` (effect:read) — a restricted shell for the verifier read-only boundary (design/44 M2):
+ * a single allowlisted, bare command with no shell operators. effect:read lets it survive the verifier's
+ * read-only filter, but it is NOT a policy bypass — it still goes through the design/37 gate (council #7:
+ * a read can still be a side channel, e.g. dumping a secret file). The allowlist is a coarse pre-filter;
+ * the policy gate is the authoritative control.
+ *
+ * RB-413 (安全面, adjudicated: hard refusal) — that allowlist vets argv[0] and nothing else, so until this
+ * leg carried a path boundary an allowlisted reader could name ANY file on the host and get it: `cat
+ * /etc/passwd` went straight through. RB-412 gave the full `bash` leg the same boundary as a DEMOTION —
+ * that leg's verdict feeds an approval gate, so "outside the roots" can become a prompt. This face has no
+ * such channel: `effect:"read"` is precisely what lets it run where the write shell may not (the verifier's
+ * read-only band), so an out-of-root read here is not something to escalate, it is outside what the tool
+ * is. It is refused, fail-closed, before anything executes — including the conservative direction, where
+ * the operand cannot be resolved statically (there is nothing to degrade to).
+ */
 export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical: string, allow: ReadonlySet<string>, opts?: {
+    /** RB-370 ② (cli [2088]): same timeout-cap overrides the full `bash` leg takes — see
+     *  {@link import("./index.js").HandsToolkitOptions.bashDefaultTimeoutMs} /
+     *  {@link import("./index.js").HandsToolkitOptions.bashMaxTimeoutMs} (类修完整域: both foreground
+     *  legs share runShell's clamp, so both must share the configurable resolution). */
     bashDefaultTimeoutMs?: number;
     bashMaxTimeoutMs?: number;
+    /** RB-413: the extra containment roots the structured file tools got (design/119 `--add-dir`,
+     *  canonical). A read this deployment already sanctions for Read/Grep/Glob is equally sanctioned
+     *  here — the two faces must not disagree about which directories exist for this session. */
     additionalRoots?: readonly string[];
 }): AgentTool;
+/**
+ * design/115 P0 `TaskOutput` (legacy aliases: BashOutput/AgentOutput*) — read a background shell's NEW output
+ * since the last call (cursor), by task_id. Optional legacy `filter` regex is applied BEFORE the per-poll truncation so a watched line survives even when it
+ * falls in a high-throughput middle window. Untrusted process output is fenced (delimitUntrusted) — observe-only,
+ * never re-fed as instructions.
+ */
 export declare function createEnvTaskOutputTool(env: ExecutionEnv): AgentTool;
+/** design/115 P0 `TaskStop` (RB-476-A: legacy aliases cleared) — terminate a background shell by task_id.
+ *
+ *  design/134 KNOWN-ISSUES close-out: this band kills ENV-DIRECT (it mounts precisely when the toolkit has
+ *  no registry — the createHandsToolkit ternary routes registry deployments to createTaskStopTool), so a
+ *  row for the SAME shell in the process-local {@link defaultTaskRegistry} (a Runner-mounted run sharing
+ *  this env) used to settle via the watcher's no-claimant floor as stoppedBy:"system". The tool now marks
+ *  the initiation site ("parent") on `registry` (default: the process-local {@link defaultTaskRegistry})
+ *  BEFORE the kill — attribution only; the kill path and the model-facing receipt text are unchanged. */
 export declare function createEnvTaskStopTool(env: ExecutionEnv, registry?: TaskRegistry): AgentTool;

package/dist/tools/fs/fs-pdf.d.ts

@@ -4,9 +4,37 @@ import type { ExecutionEnv } from "../../internal/harness-types.js";
 import { type PdfModelCapabilities } from "./pdf.js";
 import { type ReadImageDownsamplerOption } from "./fs-shared.js";
 export { pdfModelCapabilitiesOf, type PdfModelCapabilities } from "./pdf.js";
+/** What the Read tool's PDF pipeline returns (document block, or rendered page images, or an error string). */
 type ReadPdfReturn = string | {
     content: Array<TextContent | ImageContent | DocumentContent>;
     details: unknown;
 };
+/**
+ * PDF read pipeline (CC FileReadTool parity — mechanism取证 + limits in fs/pdf.ts):
+ * - no `pages` → whole file as a native `document` block, gated at ≤{@link PDF_TARGET_RAW_SIZE} raw and
+ *   ≤{@link PDF_INLINE_PAGE_THRESHOLD} pages (page count via `pdfinfo`, byte-scan fallback; unknown = fail-open,
+ *   CC-identical — the size gate still bounds the request);
+ * - `pages` "F-L" → poppler `pdftoppm` renders the range as JPEG page images (CC-identical mechanism; the
+ *   downsampler seam then applies the same pipeline as the Read image branch). poppler absent → HONEST
+ *   degradation with the working alternative, never a fake success.
+ * Wire discipline: the base64 payload rides `details.file` only while ≤48K chars (same OMIT rule as the
+ * image variant — a bigger card would be dropped whole by the structuredFrom 4×cap and blind the shell).
+ * structured-card audit item B (2026-08-05): that budget management assumed `"document"` was on `CC_DETAIL_TYPES`, which
+ * it was not — every `document` card, sized or not, was dropped at the gate, making the 48K rule dead
+ * code and the pages/fallback-level disclosure invisible to a host. The word is registered now.
+ *
+ * Degradation chain v2 (clay 拍: the brain-level placeholder is NOT the end state): when the SERVING model
+ * cannot take a native document block (`caps.document === false` — e.g. any openai-compatible API), the
+ * whole-PDF path degrades IN THE TOOL (the only layer holding env.exec), best first:
+ *   1. `pdftotext -layout` text extraction → the content arrives as TEXT (Read byte-cap discipline applies);
+ *   2. pdftotext absent/failed + the model has vision → render the first {@link PDF_FALLBACK_RENDER_PAGES}
+ *      pages via the existing `pdftoppm` pipeline (note directs `pages` for more);
+ *   3. honest placeholder explaining WHY levels 1–2 did not run + the Bash self-help.
+ * Every degraded return carries `details.fallback = { level, reason }` (telemetry on the structured frame).
+ * `caps` absent ⇒ fully capable (byte-compat: native document block; the brain placeholder still guards).
+ */
 export declare function readPdfFile(env: ExecutionEnv, path: string, key: string, pages: string | undefined, signal: AbortSignal | undefined, downsamplerOpt: ReadImageDownsamplerOption, cwd: string, preRead?: Uint8Array, caps?: PdfModelCapabilities): Promise<ReadPdfReturn>;
+/** E1: readPdfFile's own return type stays `ReadPdfReturn` (its INTERNAL string-means-error dispatch
+ *  contract, shared with pdfPagesToImageBlocks) — the isError flag is applied once, here, at the tool's
+ *  actual execute() boundary, not inside the helper. */
 export declare function pdfResultToToolReturn(r: ReadPdfReturn): ReturnType<typeof errorResult> | Exclude<ReadPdfReturn, string>;

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

@@ -2,4 +2,9 @@ import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
 import type { ToolEffect } from "../../core/types.js";
 export declare function createGrepTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[]): AgentTool;
 export declare function createGlobTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[]): AgentTool;
+/** Static side-effect class of every hand tool, by name (design/44 §3). Used by prepare-task to (a) feed
+ *  wake/resume reconciliation and (b) drive the verifier read-only boundary. Every mutating hand tool is
+ *  `write` (RB-264 ⑥W1 folded `Write` back in — see below); `bash` is `write` (a command can do anything);
+ *  `bash_readonly` is `read` (so it survives the verifier boundary — but still goes through the policy
+ *  gate, council #7: effect:read is a redo-safety class, never a policy bypass). */
 export declare const HAND_TOOL_EFFECTS: Readonly<Record<string, ToolEffect>>;