@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/tools/impl/_web-fetch-net.d.ts

@@ -0,0 +1,99 @@
+export declare const WEB_FETCH_MAX_BYTES = 10485760;
+export declare const WEB_FETCH_TIMEOUT_MS = 60000;
+export declare const WEB_FETCH_MAX_REDIRECTS = 10;
+/** claude's own `I_e(code)`: a FIXED table lookup, never the wire's own (server-controlled) reason phrase -- see the module header, finding M1. */
+export declare function reasonPhrase(status: number): string;
+/** The three-value policy AFTER `web-fetch.ts`'s own fail-closed coercion -- this module trusts it verbatim. */
+export type NormalizedPrivateAddressPolicy = "allow" | "deny" | "ask";
+export interface WebFetchNetDeps {
+    fetchImpl?: (url: string, init: {
+        redirect: "manual";
+        headers: Record<string, string>;
+        signal: AbortSignal;
+        decompress: false;
+        tls: {
+            serverName: string;
+        };
+    }) => Promise<Response>;
+    resolveHost?: (hostname: string) => Promise<readonly string[]>;
+    now?: () => number;
+    timeoutMs?: number;
+}
+export interface WebFetchNetOptions {
+    blockedDomains: readonly string[];
+    privateAddressPolicy: NormalizedPrivateAddressPolicy;
+    userAgent: string;
+    signal?: AbortSignal;
+}
+export type WebFetchNetOutcome = {
+    kind: "invalid-url";
+    message: string;
+} | {
+    kind: "blocked-domain";
+    host: string;
+} | {
+    kind: "private-address";
+    host: string;
+    policy: "deny" | "ask";
+} | {
+    kind: "redirect-blocked";
+    message: string;
+} | {
+    kind: "too-many-redirects";
+    message: string;
+} | {
+    kind: "http-error";
+    status: number;
+    statusText: string;
+    retryAfter?: string;
+} | {
+    kind: "size-exceeded";
+    message: string;
+} | {
+    kind: "timeout";
+    message: string;
+} | {
+    kind: "aborted";
+} | {
+    kind: "network-error";
+    message: string;
+} | {
+    kind: "success";
+    finalUrl: string;
+    status: number;
+    statusText: string;
+    contentType: string;
+    body: Uint8Array;
+};
+/** Exported so `web-fetch.ts`'s own upfront (pre-cache) gate uses the SAME default resolver -- never a second, drifting copy. */
+export declare function defaultResolveHost(hostname: string): Promise<readonly string[]>;
+/**
+ * `validateInput`'s own parse-failure text -- WITH the `Error: ` prefix (fidelity #2).
+ *
+ * A real string in claude's binary that NO input can reach there: claude validates a call against the
+ * tool's input schema (`url: format uri`) BEFORE the tool's own validation, so an unparseable URL is
+ * refused by the schema (`InputValidationError: [...] "Invalid URL"`) and anything the schema lets
+ * through also parses here. This runtime has no schema-validation step in front of its executors, so
+ * the same text IS reachable, as the backstop for exactly the inputs claude's schema refuses. It
+ * stops being reachable the day such a step exists.
+ */
+export declare function parseFailureMessage(raw: string): string;
+export declare const WEB_FETCH_MAX_ENCODED_BYTES: number;
+export type BodyReadResult = {
+    kind: "ok";
+    body: Uint8Array;
+} | {
+    kind: "output-cap-exceeded";
+} | {
+    kind: "input-cap-exceeded";
+} | {
+    kind: "unsupported-encoding";
+    encoding: string;
+};
+/**
+ * Performs the whole fetch, including the manual redirect walk -- one HTTP request per hop, each
+ * hop re-checked against the domain floor and the private-address policy (closing the short-link
+ * bypass: a blocked/private host reached via an intermediate redirect is refused exactly like one
+ * reached directly).
+ */
+export declare function performWebFetch(inputUrl: string, prompt: string, opts: WebFetchNetOptions, deps?: WebFetchNetDeps): Promise<WebFetchNetOutcome>;

package/dist/tools/impl/_web-search-assembler.d.ts

@@ -0,0 +1,57 @@
+/** A search hit as the OUTER (main-loop) model is allowed to see it: title and url ONLY -- no highlight, no date, no encrypted content. */
+export interface WebSearchOutputHit {
+    title: string;
+    url: string;
+}
+/**
+ * The claude-shaped BLOCK STREAM: text deltas (accumulate), a search that returned hits (a
+ * `web_search_tool_result` block), or a search that failed (a result-block error, which claude
+ * renders as the STRING `Web search error: ${code}` -- NOT as an empty links item; see the research
+ * file's own "a result-block error pushes the string" line).
+ */
+export type WebSearchStreamEvent = {
+    type: "text";
+    text: string;
+} | {
+    type: "search_result";
+    hits: readonly WebSearchOutputHit[];
+} | {
+    type: "search_error";
+    code: string;
+};
+/** claude's own structured shape (research file, verbatim, `tool_use_id` dropped -- see the module header). */
+export type WebSearchResultItem = string | {
+    content: readonly WebSearchOutputHit[];
+};
+/**
+ * Stage 1: the stream walk. Text concatenates (raw block-delta accumulation, no separator -- the
+ * research file's "text blocks accumulate"); a search boundary flushes the trimmed buffer as a STRING
+ * item WHEN IT IS NON-EMPTY (see the module header), then pushes the search's own item (a links item
+ * for a result, a string for an error); the buffer flushes once more at the end for any trailing
+ * commentary, under the identical non-empty rule.
+ */
+export declare function flushWebSearchStream(events: readonly WebSearchStreamEvent[]): WebSearchResultItem[];
+/**
+ * Stage 2: the render. Verbatim from the research file: header + `"\n\n"`; each item + `"\n\n"`
+ * (a string item as-is; a links item as `Links: ` + COMPACT `JSON.stringify` of `[{title,url}]`, or
+ * `No links found.` when its `content` is empty); then `"\n"` + the reminder; the WHOLE string
+ * `.trim()`ed once at the end (which is what removes the header's own leading blank-line pair when
+ * there happen to be zero items, and any trailing blank line before the reminder).
+ */
+export declare function renderWebSearchToolResult(query: string, items: readonly WebSearchResultItem[]): string;
+/** Both stages composed -- what a caller with no use for the intermediate item list reaches for. */
+export declare function assembleWebSearchOutput(query: string, events: readonly WebSearchStreamEvent[]): string;
+/**
+ * `renderWebSearchToolResult`, but never longer than `cap` -- and the cap NEVER costs the header or
+ * the REMINDER footer (review fix: a raw `text.slice(0, cap)` on the FULL render chops from the end,
+ * which is exactly where the "you MUST include sources" trailer lives -- the one line most worth
+ * keeping when there was the most to cite). Items are dropped from the END, in stream order (the
+ * earliest results and commentary are kept), one at a time, until what remains renders under `cap`;
+ * with zero items left the render is just `header + "\n\n" + REMINDER`, which is the floor this
+ * function can promise -- a `cap` smaller than THAT floor (an unrealistic value for a 100,000-char
+ * default and an ordinary query) is the one input this cannot fully honour, and is left uncapped
+ * further than that floor rather than truncating the header or the reminder itself.
+ */
+export declare function renderWebSearchToolResultCapped(query: string, items: readonly WebSearchResultItem[], cap: number): string;
+/** Both stages composed, capped -- what `impl/web-search.ts` calls instead of slicing the finished string. */
+export declare function assembleWebSearchOutputCapped(query: string, events: readonly WebSearchStreamEvent[], cap: number): string;

package/dist/tools/impl/advisor.d.ts

@@ -0,0 +1,37 @@
+import "../descriptors/advisor.ts";
+import type { Provider } from "../../engine.js";
+import { type ToolExecutor } from "../registry.js";
+import { type TranscriptEntry, type TranscriptSource } from "@yanlinglabs/winter-agent-sdk/tools";
+/**
+ * D29: the canonical name IS the advertised name, and it is bare. Read off the one definition, so
+ * the registered name and the descriptor's can never disagree.
+ */
+export declare const ADVISOR_TOOL_NAME: string;
+export type { TranscriptEntry, TranscriptSource };
+export { assembleReviewerMessages, ADVISOR_DEFAULT_MAX_CHARS, OPAQUE_MARKERS, stripOpaqueMarkers } from "@yanlinglabs/winter-agent-sdk/tools";
+/**
+ * Resolves BOTH the provider to call and the model id the result must report, TOGETHER: WS-06 §4's
+ * result shape pins `model: string` as required, but `Provider` has no `model` field to read back --
+ * whatever backs the `winter.reviewer-model` capability must hand back the model id alongside the
+ * provider instance it resolved, in ONE seam, rather than two seams that could disagree.
+ *
+ * Typed against THIS runtime's `Provider` (not the SDK's `AdvisorReviewer`): the resolver is the
+ * provider layer's own door, and the narrowing happens at the boundary below.
+ */
+export interface ResolvedReviewer {
+    provider: Provider;
+    model: string;
+}
+export type ReviewerResolver = () => ResolvedReviewer | undefined;
+export interface AdvisorExecutorDeps {
+    transcriptSource: TranscriptSource;
+    resolveReviewer: ReviewerResolver;
+    /** Injectable so tests can pin the truncation boundary without a multi-KB fixture transcript. */
+    maxChars?: number;
+}
+/**
+ * NO CACHE (WS-06 §4's closing line: "the advisor and the auto-mode classifier are separate routes
+ * and MUST NOT share a verdict cache"). The SDK factory memoizes nothing, and neither does this
+ * wrapper -- every call re-resolves the reviewer, re-assembles the transcript and re-generates.
+ */
+export declare function createAdvisorExecutor(deps: AdvisorExecutorDeps): ToolExecutor;

package/dist/tools/impl/agent.d.ts

@@ -0,0 +1,10 @@
+import { type ToolExecutor } from "../registry.js";
+export declare const AGENT_TOOL_NAME = "Agent";
+/** R-S5 / claude's own wording (an error message, not prompt text -- R-S4). */
+export declare const FORK_INSIDE_FORK_REFUSAL = "Fork is not available inside a forked worker. Complete your task directly using your tools.";
+/**
+ * R-S5: claude's fork+remote refusal. The research file truncates claude's string after the dash; the
+ * tail is a WINTER completion (disclosed).
+ */
+export declare const FORK_REMOTE_REFUSAL = "Fork cannot use isolation: \"remote\" \u2014 a fork inherits this session's live conversation, which a remote environment cannot receive. Omit isolation, or use isolation: \"worktree\".";
+export declare const agentExecutor: ToolExecutor;

package/dist/tools/impl/ask-user-question.d.ts

@@ -0,0 +1,5 @@
+import "../descriptors/ask-user-question.ts";
+import { type ToolExecutor } from "../registry.js";
+export declare const ASK_USER_QUESTION_TOOL_NAME = "AskUserQuestion";
+export declare const ASK_USER_QUESTION_ANSWER_KEY_FIELD: "question";
+export declare const askUserQuestionExecutor: ToolExecutor;

package/dist/tools/impl/background-task-runtime.d.ts

@@ -0,0 +1,272 @@
+export type BackgroundTaskKind = "bash" | "monitor" | "monitor_ws" | "workflow" | "agent";
+import type { BackgroundTaskMessage } from "@yanlinglabs/winter-agent-sdk";
+import type { RunCommandResult } from "../../sandbox/spawn.js";
+export type BackgroundTaskStatus = "running" | "completed" | "failed" | "stopped";
+export interface TaskFrameEmitter {
+    emitFrame: (frame: BackgroundTaskMessage) => void;
+    sessionId: string;
+}
+export interface BackgroundTaskHandle {
+    taskId: string;
+    kind: BackgroundTaskKind;
+    outputPath: string;
+    /** Required -- WS-06 §3.5's own task_started frame requires `description`; callers fall back to the command text when the model didn't supply one. */
+    description: string;
+    command?: string;
+    /** The spawned child's pid. Always the process-GROUP leader (spawn.ts's `detached: true`), so killTaskProcessGroup's negative-pid signal reaps the whole group, matching WS-12 §5.2. */
+    pid?: number;
+    /**
+     * A generic stop callback for a task with no OS process to signal -- Monitor's `ws` half is a
+     * live socket, not a child process, so it has no pid at all. `stopTask` (below) tries
+     * `killTaskProcessGroup` first (bash / Monitor's `command` half) and falls back to this callback
+     * (Monitor's `ws` half) so TaskStop has exactly ONE call to make regardless of which kind of
+     * background task it is stopping.
+     */
+    stop?: () => void;
+    status: BackgroundTaskStatus;
+    startedAt: number;
+    /**
+     * Task-frames parity (contract §1/§2): only meaningful for a `local_agent`/`local_bash` row (the
+     * two wire kinds the pin's own `register()` puts the flag on at all) -- `undefined` for every other
+     * kind (workflow, monitor_ws), which never carry it on `task_started` either. `false` marks a
+     * FOREGROUND row: excluded from `listRunningTasks()`'s own `background_tasks_changed` listing
+     * (§1's `"isBackgrounded" in task && task.isBackgrounded === false` rule). A foreground BASH row
+     * terminates through a caller-built notification + `removeTask` (§3, no task_updated); a
+     * foreground AGENT row terminates through `updateTask` exactly like a background one (§4, corrected
+     * from a live run of the pin).
+     */
+    isBackgrounded?: boolean;
+    /** The model's own `tool_use` id for the call that created this task, when known -- carried onto this row's own `task_notification`/`task_updated` unless a call overrides it. */
+    toolUseId?: string;
+    endTime?: number;
+    totalPausedMs?: number;
+    error?: string;
+    emitter?: TaskFrameEmitter;
+    /**
+     * Review r1 finding 4: the row's LIVE usage counters, when the task kind has any (an agent row --
+     * `tools/impl/agent.ts` wires it to the child's own progress snapshot). `notifyTerminal` reads it
+     * as the default `task_notification.usage`, so EVERY terminal door for an agent row -- the agent's
+     * own result path AND a TaskStop that finalizes the row first -- reports the same usage, instead
+     * of the TaskStop door silently dropping it.
+     */
+    usage?: () => TaskUsage | undefined;
+    /**
+     * The spawning engine's own agent key (`ToolExecutionContext.agentId`) -- absent for a task the
+     * TOP-LEVEL session started. Read only by `stopSessionShellTasks` below (engine teardown), which is
+     * what makes a subagent's teardown stop the shells THAT subagent started and nothing else (the
+     * pin's own `killShellTasksForAgent` on agent exit).
+     */
+    ownerAgentId?: string;
+    /**
+     * Contract §1's `ambient` (a row that runs for the session rather than for a request). NOTHING sets
+     * it today -- it exists because the print-mode background WAIT excludes an ambient `monitor_ws` row
+     * (claude's own `Mtn`), and a filter written against a field nobody can set would be a filter that
+     * silently means nothing the day someone does set it.
+     */
+    ambient?: boolean;
+}
+export interface TaskUsage {
+    total_tokens: number;
+    tool_uses: number;
+    duration_ms: number;
+}
+export interface StartTrackingInput {
+    taskId: string;
+    kind: BackgroundTaskKind;
+    outputPath: string;
+    description: string;
+    command?: string;
+    pid?: number;
+    stop?: () => void;
+    isBackgrounded?: boolean;
+    toolUseId?: string;
+    emitter?: TaskFrameEmitter;
+    usage?: () => TaskUsage | undefined;
+    ownerAgentId?: string;
+    ambient?: boolean;
+}
+export declare function startTracking(input: StartTrackingInput): BackgroundTaskHandle;
+export declare function getTask(taskId: string): BackgroundTaskHandle | undefined;
+export declare function listTasks(): readonly BackgroundTaskHandle[];
+export declare function listRunningTasks(): readonly BackgroundTaskHandle[];
+export declare function killTaskProcessGroup(taskId: string): boolean;
+/**
+ * Review r2 finding 10 (whole-branch, "the option that keeps callers correct"): the counterpart to
+ * `startTracking` never re-arming a terminal row. bash.ts/monitor.ts's own `onSpawned` callback
+ * calls `startTracking` a SECOND time once the real OS process exists, to attach its pid to the
+ * registry row -- but if a TaskStop landed in the window between the pre-spawn registration and
+ * this call (the row is now terminal, and correctly stays that way per finding 10), the row NEVER
+ * learns this pid, because `startTracking` returns the terminal row untouched rather than merging
+ * it in. Without this function the OS process itself -- which really did just get spawned, is
+ * really still running, and really was supposed to die with its already-stopped task -- would leak
+ * for the rest of the daemon's process lifetime: nothing else ever learns its pid. `onSpawned`
+ * calls this directly (bypassing the registry entirely, since the registry has no pid to act on)
+ * exactly when the row it gets back from `startTracking` is not `"running"`.
+ */
+export declare function killOrphanedSpawn(pid: number): boolean;
+/**
+ * Review r2 finding 9 (whole-branch): main.ts's own SIGTERM/SIGINT handler calls this directly --
+ * unlike `stopSessionShellTasks` (the ORDINARY "session going away" door, engine.ts's teardown),
+ * this is a raw, synchronous, FRAME-FREE sweep over EVERY row in the process with a live pid,
+ * regardless of session or kind (`bash`, `monitor`'s command half, and any future pid-bearing kind
+ * alike -- `monitor_ws`'s own socket half has no pid, `agent`/`workflow` rows have no pid either and
+ * are the child engine's own responsibility, unaffected by this sweep either way).
+ *
+ * NO `updateTask`/`emitFrame` call here, deliberately: a signal handler must return fast and must
+ * never depend on the event loop still turning normally or on a frame sink that may itself be
+ * mid-teardown -- `stopSessionShellTasks`' own `task_updated`/`task_notification` bookkeeping is a
+ * normal-exit courtesy, not a safety property. The property this function alone guarantees is
+ * process cleanup: no `detached: true` process group this `winter` child process ever spawned
+ * survives the process being asked to exit. Never throws; each row is attempted independently so
+ * one failure (already exited, ESRCH) never strands the rest of the sweep.
+ */
+export declare function killAllTaskProcessGroups(): string[];
+export declare function stopTask(taskId: string): boolean;
+export declare function toBackgroundTasksChangedEntry(t: BackgroundTaskHandle): {
+    task_id: string;
+    task_type: string;
+    description: string;
+};
+export interface TaskNotificationInput {
+    summary: string;
+    /** Defaults to `task.outputPath`; a foreground task's own caller passes `""` explicitly (§3/§4: "no output file"). */
+    outputFile?: string;
+    /** Defaults to the row's own `usage()` accessor, when it has one (finding 4). */
+    usage?: TaskUsage;
+    /** Defaults to `task.toolUseId`. */
+    toolUseId?: string;
+    skipTranscript?: boolean;
+    ambient?: boolean;
+    /** Lane N: see `TaskNotificationEmission.modelNotification`. */
+    modelNotification?: string | null;
+}
+export interface TaskUpdateChanges {
+    status?: BackgroundTaskStatus;
+    description?: string;
+    endTime?: number;
+    totalPausedMs?: number;
+    error?: string;
+    isBackgrounded?: boolean;
+    /**
+     * Consulted ONLY when this call's own status change crosses non-terminal -> terminal; ignored
+     * otherwise. §1: "same synchronous call, AFTER the task_updated" -- supplying both the state
+     * change and its eventual notification content to ONE call is what makes that true structurally,
+     * rather than relying on the caller to remember to follow up with a second call in the right order.
+     */
+    notification?: TaskNotificationInput;
+}
+export interface TaskNotificationEmission {
+    status: "completed" | "failed" | "stopped";
+    outputFile: string;
+    summary: string;
+    usage?: {
+        total_tokens: number;
+        tool_uses: number;
+        duration_ms: number;
+    };
+    toolUseId?: string;
+    skipTranscript?: boolean;
+    ambient?: boolean;
+    /**
+     * SDK 0.0.16 Lane N: the MODEL-facing `<task-notification>` document for this same terminal event
+     * (`subagents/notification-queue.ts`). Three cases, and the default is the interesting one:
+     *
+     *  - ABSENT -- derived from the row: a BACKGROUND row gets the shell/monitor document, carrying the
+     *    same pinned `summary` the frame carries (claude's `AMe` uses one text on both surfaces), and a
+     *    FOREGROUND row (`isBackgrounded === false`) gets NONE, because the model is already being
+     *    handed that task's result as its own `tool_result`.
+     *  - a STRING -- this exact document (the agent/workflow/TaskStop shapes, whose XML says more than
+     *    the frame's summary does: `<result>`, `<usage>`, the actor that stopped it).
+     *  - `null` -- explicitly no model notification.
+     */
+    modelNotification?: string | null;
+}
+/**
+ * §1's `Ik`: `task_notification` is sent at most once per task id, ever -- a second attempt (the
+ * process's own natural-exit handler racing a TaskStop that already finalized the row, or a
+ * foreground caller notifying after `removeTask`) is a silent no-op. The ONE place every
+ * `task_notification` this package emits goes through, whether reached via `updateTask`'s own
+ * terminal detection below or a foreground remove-then-notify caller (bash.ts/agent.ts) that has
+ * nothing left in the registry to update.
+ */
+export declare function emitTaskNotification(task: Pick<BackgroundTaskHandle, "taskId" | "emitter" | "toolUseId"> & Partial<Pick<BackgroundTaskHandle, "kind" | "description" | "isBackgrounded" | "ownerAgentId" | "outputPath">>, notification: TaskNotificationEmission): void;
+/**
+ * §1's update(id, fn): applies `changes`, diffs OLD vs NEW on exactly the six pinned fields, and (if
+ * the patch is non-empty) emits `task_updated {task_id, patch}` -- then, if this call's own status
+ * change crossed non-terminal -> terminal, emits `task_notification` (same synchronous call, AFTER
+ * the task_updated), through `emitTaskNotification`'s own once-per-id claim.
+ *
+ * A field counts as "changed" here by the same rule for all six: `changes.<field> !== undefined`
+ * (a caller never means to explicitly unset one of these) AND it differs from the row's current
+ * value -- which already satisfies the table's extra "AND new value is defined" clause on
+ * `error`/`isBackgrounded` for free, since neither is ever applied from an `undefined` input.
+ *
+ * Returns `undefined` for an unknown taskId (never throws).
+ *
+ * Review r1 finding 6: a TERMINAL row is settled. Its `status`, `end_time`, `error` and
+ * `is_backgrounded` no longer move -- a late second terminal attempt (a foreground agent's own
+ * result path arriving after a TaskStop already finalized the row, a process exit handler racing a
+ * kill) used to leave a stray `task_updated {end_time}` on the wire AFTER the notification, and
+ * could flip a `stopped` row to `completed`. The first terminal verdict wins, permanently.
+ */
+export declare function updateTask(taskId: string, changes: TaskUpdateChanges): BackgroundTaskHandle | undefined;
+/**
+ * §1's remove(id): deletes the row, emitting NO `task_updated`. Used for a foreground BASH command
+ * that finishes in the foreground (§3) -- the caller builds and sends the `task_notification` itself,
+ * through `emitTaskNotification`, BEFORE calling this (review r1 finding 10: the engine's
+ * Notification-hook guard reads the row to tell a foreground notification from a background one, so
+ * the row must still exist when the frame is emitted). Removing also drops the id's notification
+ * claim (finding 12 -- see `notifiedTaskIds`). Returns `undefined` for an unknown taskId, never throws.
+ */
+export declare function removeTask(taskId: string): BackgroundTaskHandle | undefined;
+export declare const AGENT_STOPPED_SUMMARY = "stopped by request";
+export declare function killedTaskSummary(kind: BackgroundTaskKind, description: string): string;
+/**
+ * Review r1 finding 2: the ONE status derivation for a background shell's natural end (Bash and
+ * Monitor's command half share it -- it lives here, not in bash.ts, because an impl module must not
+ * import another executor module: impl-isolation.test.ts). `aborted` is a kill THIS runtime issued
+ * through the run's own signal -> `stopped` (the kill wording). Exit 0 with no timeout/cap ->
+ * `completed`. Everything else -> `failed`, carrying the real exit code only when one exists -- a
+ * timeout, an output cap or an outside kill has none, and none is invented.
+ */
+export declare function resolveBackgroundOutcome(result: Pick<RunCommandResult, "exitCode" | "timedOut" | "aborted" | "streamKilled">): {
+    status: "completed" | "failed" | "stopped";
+    exitCode: number | null;
+};
+/**
+ * Review r1 finding 2 (controller ruling): a BACKGROUND shell no longer dies with the turn that
+ * started it -- the pin's `ShellCommand.background()` drops its abort listeners, so only its own
+ * exit, a TaskStop, or the session going away ends it. This is the "session going away" door: the
+ * engine's teardown calls it for its own `sessionId`, and for a subagent engine its own `agentId`
+ * (the pin's `killShellTasksForAgent` on agent exit). Each still-running background shell row
+ * (`bash`, Monitor's `monitor`/`monitor_ws` halves) the caller owns is finalized through the ONE
+ * update door -- `task_updated {killed}` then the kill-worded notification -- and THEN killed, the
+ * same order TaskStop uses so the process's own exit handler finds a terminal row and stays silent.
+ * Returns the ids it stopped. Never throws.
+ */
+export declare function stopSessionShellTasks(owner: {
+    sessionId: string;
+    agentId?: string;
+}): string[];
+/**
+ * SDK 0.0.16 Lane N: every still-running BACKGROUND row of one session (foreground rows excluded, as
+ * everywhere else). This is what a closed-input session waits on before it tears down -- the pin's own
+ * `sge(appState).filter(kf && …)`. An AMBIENT `monitor_ws` row is excluded: it runs for the session,
+ * not for a request, so waiting on it would mean never exiting (claude's `Mtn`).
+ */
+export declare function listSessionRunningTasks(owner: {
+    sessionId: string;
+    agentId?: string;
+}): readonly BackgroundTaskHandle[];
+/**
+ * Lane N: the print-mode WIND-DOWN sweep (claude's `$u`), reached only after the wait ceiling and its
+ * grace have both passed. Unlike `stopSessionShellTasks` (the teardown door, shells only) this covers
+ * EVERY kind: a shell is killed, and an agent/workflow row is finalized as stopped -- which, through
+ * the one update door, both emits its `task_updated`/`task_notification` pair and enqueues the
+ * model-facing "was stopped" document the pin sends in exactly this situation. Returns the ids swept.
+ */
+export declare function sweepSessionBackgroundTasks(owner: {
+    sessionId: string;
+    agentId?: string;
+}): string[];
+export declare function resetBackgroundTaskRuntimeForTest(): void;

package/dist/tools/impl/bash.d.ts

@@ -0,0 +1,78 @@
+import "../descriptors/bash.ts";
+import { type ToolExecutor, type ToolExecutionContext } from "../registry.js";
+import { type GlobDenyEntry } from "../../permissions/file-rules.js";
+import { type ExtractedPaths } from "../paths-seam.js";
+import { type SandboxBrand } from "../../sandbox/profile.js";
+interface BashInput {
+    command: string;
+    timeout?: number;
+    description?: string;
+    run_in_background?: boolean;
+    dangerouslyDisableSandbox?: boolean;
+}
+declare function parseBashInput(input: unknown): BashInput | {
+    error: string;
+};
+declare const CEILING_TIMEOUT_MS = 600000;
+declare function resolveTimeout(requested: number | undefined): number;
+declare function computeWritableRoots(ctx: ToolExecutionContext): string[];
+declare function buildRunCommandOptions(input: BashInput, ctx: ToolExecutionContext): {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    settings: typeof ctx.sandboxSettings;
+    writableRoots: string[];
+    denyWritePaths?: string[];
+    denyReadPaths?: string[];
+    /** Fix round 11: glob-shaped denyWrite/denyRead entries, pre-converted to SBPL regex source -- see `splitDenyPathsByGlobShape`'s own header. */
+    denyWriteRegexes?: string[];
+    denyReadRegexes?: string[];
+    /** Fix round 12: each glob-shaped denyWrite/denyRead entry's own canonicalized fixed-prefix directory -- feeds the ancestor-rename-bypass fix. */
+    denyWriteGlobFixedPrefixes?: string[];
+    denyReadGlobFixedPrefixes?: string[];
+    /** Fix round 13: each glob-shaped denyRead entry, its regex PAIRED with its own fixed prefix -- feeds the read-deny-keep-in-place fix. */
+    denyReadGlobEntries?: GlobDenyEntry[];
+    home: string;
+    /** Phase 5 fix wave, I1: the resolved winter root, distinct from the OS home above. */
+    winterHome?: string;
+    /** WS-21 fix round 1, item 4: the shared store home -- see `ToolExecutionContext.storeHome`. */
+    storeHome?: string;
+    /** P7a (D19): the session's brand -- the dot-dir names the seatbelt fences. */
+    brand?: SandboxBrand;
+    /** Fix round 16, item 2: `sandbox.filesystem.allowGitConfig` -- see `SandboxFilesystemSettings.allowGitConfig`'s own header. */
+    allowGitConfigWrites?: boolean;
+    dangerouslyDisableSandbox?: boolean;
+    /**
+     * Phase 6 Task 3 (R6-6, P4 carry): the engine's per-turn abort.
+     *
+     * `runCommand` ALREADY had the machinery -- `detached: true` makes the child its own group leader
+     * and an abort triggers the negative-pid SIGKILL that reaps sandbox-exec, bash and every forked
+     * grandchild. What was missing was the CHANNEL: nothing upstream of this function had an
+     * `AbortSignal` to give it, so an interrupted turn abandoned the await and the command kept
+     * running. Threading `ctx.signal` here is the entire fix.
+     *
+     * FOREGROUND ONLY (review r1 finding 2, controller ruling): `runBackground` strips this field. The
+     * pin's `ShellCommand.background()` drops its abort listeners, so a turn interrupt never kills a
+     * backgrounded command -- it ends by its own exit, a TaskStop, or the session's teardown
+     * (`stopSessionShellTasks`, background-task-runtime.ts).
+     */
+    signal?: AbortSignal;
+};
+interface CappedOutput {
+    text: string;
+    persistedPath?: string;
+}
+declare function capOutput(ctx: ToolExecutionContext, stream: "stdout" | "stderr", raw: string, success: boolean): CappedOutput;
+declare function formatForegroundResult(parts: {
+    stdout: CappedOutput;
+    stderr: CappedOutput;
+    exitCode: number | null;
+    timedOut: boolean;
+    aborted: boolean;
+    timeoutMs: number;
+    posture: string;
+    sandboxOverrideRequested: boolean;
+    streamKilled: boolean;
+}): string;
+declare function extractBashPaths(input: unknown): ExtractedPaths;
+export declare const bashExecutor: ToolExecutor;
+export { parseBashInput, resolveTimeout, extractBashPaths, computeWritableRoots, capOutput, formatForegroundResult, buildRunCommandOptions, CEILING_TIMEOUT_MS };

package/dist/tools/impl/cron.d.ts

@@ -0,0 +1,11 @@
+import "../descriptors/index.ts";
+export interface CronJobRecord {
+    id: string;
+    cron: string;
+    prompt: string;
+    recurring: boolean;
+    durable: boolean;
+}
+export declare function validateCronExpression(cron: string): void;
+export declare function humanizeCron(cron: string): string;
+export declare function resetInMemoryCronStoreForTest(): void;

package/dist/tools/impl/edit.d.ts

@@ -0,0 +1 @@
+import "../descriptors/index.ts";

package/dist/tools/impl/enter-plan-mode.d.ts

@@ -0,0 +1,4 @@
+import "../descriptors/enter-plan-mode.ts";
+import { type ToolExecutor } from "../registry.js";
+export declare const ENTER_PLAN_MODE_TOOL_NAME = "EnterPlanMode";
+export declare const enterPlanModeExecutor: ToolExecutor;

package/dist/tools/impl/enter-worktree.d.ts

@@ -0,0 +1,25 @@
+import { type ToolExecutor } from "../registry.js";
+import "../descriptors/enter-worktree.ts";
+export declare const ENTER_WORKTREE_TOOL_NAME = "EnterWorktree";
+export interface GitRunResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+}
+export declare function runGit(args: string[], cwd: string): Promise<GitRunResult>;
+export declare function safeRealpath(path: string): string | undefined;
+export interface WorktreeInfo {
+    path: string;
+    realPath: string;
+    headSha: string;
+    branch?: string;
+    isMain: boolean;
+}
+export declare function listWorktrees(cwd: string): Promise<{
+    ok: true;
+    worktrees: WorktreeInfo[];
+} | {
+    ok: false;
+    stderr: string;
+}>;
+export declare const enterWorktreeExecutor: ToolExecutor;

package/dist/tools/impl/exit-plan-mode.d.ts

@@ -0,0 +1,4 @@
+import "../descriptors/exit-plan-mode.ts";
+import { type ToolExecutor } from "../registry.js";
+export declare const EXIT_PLAN_MODE_TOOL_NAME = "ExitPlanMode";
+export declare const exitPlanModeExecutor: ToolExecutor;

package/dist/tools/impl/exit-worktree.d.ts

@@ -0,0 +1,4 @@
+import { type ToolExecutor } from "../registry.js";
+import "../descriptors/exit-worktree.ts";
+export declare const EXIT_WORKTREE_TOOL_NAME = "ExitWorktree";
+export declare const exitWorktreeExecutor: ToolExecutor;

package/dist/tools/impl/glob.d.ts

@@ -0,0 +1 @@
+import "../descriptors/index.ts";

package/dist/tools/impl/grep.d.ts

@@ -0,0 +1,19 @@
+import "../descriptors/index.ts";
+type OutputMode = "content" | "files_with_matches" | "count";
+export interface GrepContentRow {
+    file: string;
+    line?: number;
+    text: string;
+    match?: true;
+}
+export interface GrepResult {
+    mode: OutputMode;
+    files?: string[];
+    content?: GrepContentRow[];
+    counts?: Record<string, number>;
+    truncated: boolean;
+    limit: number;
+    offset: number;
+    skippedOversized: number;
+}
+export {};