@wrongstack/core 0.264.0 → 0.267.0

package/dist/utils/index.d.ts

@@ -1,25 +1,352 @@
-import { s as TodoItem, M as Message, J as JSONSchema } from '../context-BGSpZNSE.js';
-export { T as TaskItem, c as computeTaskItemProgress, f as formatTaskList, a as formatTaskProgress } from '../task-format-vGOIftmK.js';
-export { a as WstackPathOptions, W as WstackPaths, p as projectHash, b as projectSlug, r as resolveWstackPaths, w as wstackGlobalRoot } from '../wstack-paths-CJjEwPXn.js';
-export { expectDefined } from './expect-defined.js';
-export { toErrorMessage } from './error.js';
-import { a as ModelsDevPayload, t as CustomModelDefinition } from '../config-Dz2F3H2K.js';
+import { C as Context, w as ContextEvidenceState, k as ToolOutputMetadata, J as JSONSchema, M as Message, t as TodoItem } from '../context-dT5Ueund.js';
 export { H as HttpDispatcher, a as HttpsAgentAsDispatcher } from '../dispatcher-types.d-BBeXBQgS.js';
+export { toErrorMessage } from './error.js';
+export { expectDefined } from './expect-defined.js';
+import { v as CustomModelDefinition, a as ModelsDevPayload } from '../config-Du3pYYln.js';
+export { T as TaskItem, c as computeTaskItemProgress, f as formatTaskList, a as formatTaskProgress } from '../task-format-vGOIftmK.js';
+export { a as WstackPathOptions, W as WstackPaths, p as projectHash, b as projectSlug, r as resolveWstackPaths, w as wstackGlobalRoot } from '../wstack-paths-hOpNLmvf.js';
 export { a as TaskPriority, b as TaskStatus, T as TaskType } from '../task-graph-u1q9Jkyk.js';
 import 'node:https';
 import 'undici';
 
-interface AtomicWriteOptions {
-    mode?: number | undefined;
-    encoding?: BufferEncoding | undefined;
+/**
+ * Exhaustiveness check for discriminated union switches.
+ * Place in the `default` branch of a switch over a union type
+ * to get a compile-time error when a new variant is added.
+ *
+ * @example
+ * switch (block.type) {
+ *   case 'text': return renderText(block);
+ *   case 'tool_use': return renderToolUse(block);
+ *   default: return assertNever(block);
+ * }
+ */
+declare function assertNever(x: never, message?: string): never;
+
+interface AtomicWriteOptions {
+    mode?: number | undefined;
+    encoding?: BufferEncoding | undefined;
+}
+interface FileLockOptions {
+    timeoutMs?: number | undefined;
+    staleMs?: number | undefined;
+}
+declare function atomicWrite(targetPath: string, content: string | Uint8Array, opts?: AtomicWriteOptions): Promise<void>;
+declare function ensureDir(dir: string): Promise<void>;
+declare function withFileLock<T>(targetPath: string, fn: () => Promise<T>, opts?: FileLockOptions): Promise<T>;
+
+/**
+ * Build a sanitized child-process environment.
+ *
+ * The bash/exec tools and MCP stdio transports execute LLM-generated or
+ * configured commands. The parent process carries provider API keys
+ * (ANTHROPIC_API_KEY, OPENAI_API_KEY, ...), VCS tokens (GITHUB_TOKEN),
+ * and cloud credentials. Forwarding those to a child is an exfiltration
+ * vector even with `permission: 'confirm'` — a compromised MCP server
+ * or a cleverly composed shell pipeline can leak secrets.
+ *
+ * Strategy: copy a small, explicit allowlist of variables that real builds
+ * need, then copy anything else that does NOT look secret-bearing. This
+ * preserves user-friendly behavior (locale, terminal, npm config) while
+ * blocking the obvious leak channels.
+ *
+ * Override with `WRONGSTACK_CHILD_ENV_PASSTHROUGH=1` to forward the full
+ * parent environment unchanged (opt-in for advanced users who understand
+ * the risk).
+ */
+interface BuildChildEnvOptions {
+    /** Session ID to inject as WRONGSTACK_SESSION_ID. */
+    sessionId?: string | undefined;
+    /** Additional env vars to merge (takes priority over filtered parent env). */
+    extra?: NodeJS.ProcessEnv | undefined;
+}
+/**
+ * Build a filtered child-process environment suitable for bash, exec, and
+ * MCP server subprocesses. Strips API keys, tokens, and other credentials
+ * while preserving system/tooling variables.
+ */
+declare function buildChildEnv(optsOrSessionId?: BuildChildEnvOptions | string): NodeJS.ProcessEnv;
+
+declare const color: {
+    reset: (s: string) => string;
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    italic: (s: string) => string;
+    underline: (s: string) => string;
+    red: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    blue: (s: string) => string;
+    magenta: (s: string) => string;
+    cyan: (s: string) => string;
+    gray: (s: string) => string;
+    amber: (s: string) => string;
+    pink: (s: string) => string;
+    bgRed: (s: string) => string;
+    bgGreen: (s: string) => string;
+};
+declare function stripAnsi(s: string): string;
+
+declare function createContextEvidenceState(): ContextEvidenceState;
+interface RecordToolOutputEvidenceInput {
+    toolUseId: string;
+    toolName: string;
+    input: unknown;
+    content: string;
+    ok: boolean;
+    outputBytes?: number | undefined;
+    outputTokens?: number | undefined;
+    outputLines?: number | undefined;
+}
+declare function recordUserIntentEvidence(ctx: Context, text: string): void;
+declare function recordToolOutputEvidence(ctx: Context, input: RecordToolOutputEvidenceInput): ToolOutputMetadata;
+declare function markAssistantReferencedEvidence(ctx: Context, text: string): void;
+declare function buildContextEvidenceDigest(ctx: Context): string;
+declare function repeatedReadPressure(ctx: Context): number;
+
+/**
+ * Deep merge utility — safely merges nested objects with configurable
+ * conflict resolution, array merging, and prototype-pollution guarding.
+ *
+ * Used by:
+ * - config-loader  (config layer merging with primitive-array concatenation)
+ * - secret-vault   (config patching)
+ * - json-path       (json_merge tool with prefer-base / prefer-patch semantics)
+ *
+ * @module utils/deep-merge
+ */
+declare const FORBIDDEN_PROTO_KEYS: Set<string>;
+/** True when every element is a primitive or null (no nested objects/arrays). */
+declare function isPrimitiveArray(a: unknown[]): boolean;
+interface DeepMergeOptions {
+    /**
+     * Which side wins on collision for scalars and arrays.
+     *
+     * - `'prefer-patch'` (default): patch value replaces base value.
+     * - `'prefer-base'`:  base value is kept, patch value is ignored.
+     */
+    conflictResolution?: 'prefer-base' | 'prefer-patch';
+    /**
+     * How to handle array values.
+     *
+     * - `'replace'` (default): patch array replaces base array entirely.
+     * - `'concat-primitives'`: when both values are primitive arrays,
+     *   they are concatenated and deduped (via Set).  Non-primitive
+     *   arrays still replace the base wholesale.
+     */
+    arrayMode?: 'replace' | 'concat-primitives';
+    /**
+     * Skip prototype-pollution keys (`__proto__`, `constructor`, etc.).
+     * Enabled by default.  Only disable when you control both inputs
+     * and the keyset (e.g. when merging trusted JSON schemas).
+     */
+    protectProto?: boolean;
+    /**
+     * Optional callback fired when a non-primitive (object) array is
+     * replaced wholesale (only relevant with `arrayMode: 'concat-primitives'`).
+     * Receives the key name, existing array length, and patch array length.
+     * Used by config-loader for debug logging.
+     */
+    onNonPrimitiveArrayReplace?: (key: string, existingLen: number, patchLen: number) => void;
+}
+/**
+ * Recursively merge `patch` into `base`, returning a new object.
+ *
+ * - Nested plain objects are merged recursively.
+ * - Arrays are handled per `options.arrayMode`.
+ * - Scalar collisions are resolved per `options.conflictResolution`.
+ * - `null` and non-object values in `patch` replace the base value
+ *   (unless `conflictResolution` is `'prefer-base'`).
+ * - Keys in `base` that are absent from `patch` are preserved.
+ * - `FORBIDDEN_PROTO_KEYS` are skipped in the patch (unless
+ *   `options.protectProto` is set to `false`).
+ *
+ * The function is generic over `T extends Record<string, unknown>` for
+ * callers that pass typed config objects, but the runtime signature
+ * also accepts `unknown` inputs (used by the json-path plugin).
+ */
+declare function deepMerge<T extends Record<string, unknown>>(base: T, patch: Record<string, unknown>, options?: DeepMergeOptions): T;
+declare function deepMerge(base: unknown, patch: unknown, options?: DeepMergeOptions): unknown;
+
+/**
+ * Myers diff with unified-format output. No external dependencies.
+ * Operates on arrays of lines (newline-terminated or stripped).
+ */
+interface UnifiedDiffOptions {
+    context?: number | undefined;
+    fromFile?: string | undefined;
+    toFile?: string | undefined;
+}
+declare function unifiedDiff(oldText: string, newText: string, opts?: UnifiedDiffOptions): string;
+
+/**
+ * Resolve `pattern` to the set of concrete file paths it matches.
+ * Literal paths (no glob chars) are returned as-is.
+ *
+ * @example
+ * await expandGlob('src/**\/*.ts')  // → ['src/a.ts', 'src/b/c.ts', ...]
+ * await expandGlob('foo.txt')       // → ['foo.txt']
+ */
+declare function expandGlob(pattern: string): Promise<string[]>;
+
+declare function compileGlob(pattern: string): RegExp;
+declare function matchGlob(pattern: string, input: string): boolean;
+declare function matchAny(patterns: string[], input: string): boolean;
+
+/**
+ * Shared IP-address guards for SSRF protection.
+ *
+ * Exported so `fetch.ts` (tools), `web-search/index.ts` (plugins), and any
+ * other package that needs to validate IPs can all consume the same logic.
+ * Any future additions (e.g. extra CIDR blocks) need only be made here.
+ */
+/**
+ * True if `addr` is in a private / loopback / link-local / reserved / CGNAT /
+ * multicast range.  `net.isIP` is called by the caller first so `addr` is
+ * guaranteed to be a canonical dotted-quad at this point.
+ */
+declare function isPrivateIPv4(addr: string): boolean;
+/**
+ * True if `raw` (an IPv6 literal, already lowercased) is loopback / unique-local /
+ * link-local / unspecified / IPv4-mapped-private.
+ */
+declare function isPrivateIPv6(raw: string): boolean;
+/**
+ * Expand an IPv6 string into exactly 8 16-bit numbers.  Handles `::` compression.
+ * Returns null on malformed input — caller should treat that as "block".
+ */
+declare function expandIPv6(addr: string): number[] | null;
+/**
+ * Convenience: throw if `hostname` resolves to a private / loopback IP.
+ * Use as a pre-flight check before opening a socket.
+ *
+ * ⚠️  This is not sufficient alone — connections must also use a pinned
+ * dispatcher (so the OS re-uses the already-resolved address) or the same
+ * check must be applied after every redirect hop.  See `guardedLookup` in
+ * `fetch.ts` for the connection-level enforcement.
+ */
+declare function assertNotPrivateHost(hostname: string): Promise<void>;
+
+/**
+ * Attempt to close an incomplete JSON object string by auto-closing braces
+ * and completing any unclosed double-quoted string values.
+ *
+ * Strategy:
+ * 1. Compute origOpen from the ORIGINAL input (how many braces are unclosed).
+ * 2. Add that many closing braces. If result is now valid JSON → return it.
+ * 3. If still invalid: trim trailing whitespace, strip trailing backslash.
+ * 4. Walk backwards to detect an unclosed string value.
+ *    - Quote followed by `:` → key-name, skip
+ *    - Quote followed by `,` `}` or end-of-string → toggle in/out of string
+ * 5. If we end INSIDE a string (unclosed opening `"`), append `"` + origOpen `}`.
+ *
+ * Known limitations:
+ * - Strings whose content ends with a `"` character cannot be repaired
+ *   (algorithm can't distinguish content-`"` from string-terminator `"`).
+ * - Input ending in bare `:` (incomplete value expression) can't be meaningfully repaired.
+ * - Bare `{` returns unchanged.
+ * - If origOpen=0 (braces balanced) but string is unclosed, repair is skipped
+ *   (the input would be valid JSON per JSON.parse, so it's returned as-is).
+ */
+declare function completePartialObject(s: string): string;
+
+/**
+ * Minimal JSON Schema validator — covers the subset needed for plugin
+ * configSchema validation and tool inputSchema sanity checks. Intentionally
+ * small (~80 lines, zero deps) and tolerant: unknown keywords are ignored so
+ * authors can mix in non-standard extensions without breaking validation.
+ *
+ * NOT for full JSON Schema 2020-12 conformance. If a plugin needs $ref,
+ * conditional schemas, format validation, or anything else exotic, it should
+ * bring its own ajv-based validator and call this only for the cheap path.
+ */
+
+interface ValidationError {
+    path: string;
+    message: string;
+}
+interface ValidationResult {
+    ok: boolean;
+    errors: ValidationError[];
+}
+declare function validateAgainstSchema(value: unknown, schema: JSONSchema): ValidationResult;
+
+/**
+ * Merge per-provider `customModels` into top-level `configModels`.
+ *
+ * Keys present in `configModels` always win over `providerCustomModels`
+ * when the same model id appears in both places. This lets the user
+ * override provider-attached definitions from the top-level config.
+ *
+ * Pure: never mutates its inputs.
+ */
+declare function mergeCustomModelDefs(providerCustomModels: Record<string, CustomModelDefinition> | undefined, configModels: Record<string, CustomModelDefinition> | undefined): Record<string, CustomModelDefinition> | undefined;
+
+/**
+ * Deep-merge a curated `overlay` payload on top of a `base` payload (both in
+ * the models.dev `api.json` shape). The overlay always wins: it can add
+ * providers/models the base lacks and override fields the base gets wrong.
+ *
+ * Precedence rules:
+ *  - Provider present in both → scalar fields (`name`, `npm`, `api`, `env`,
+ *    `doc`) come from the overlay when set; `models` maps merge by model id.
+ *  - Provider only in the overlay → added wholesale.
+ *  - Model present in both → overlay model fields override base model fields
+ *    (`{ ...base, ...overlay }`), with the nested `limit` / `cost` /
+ *    `modalities` objects merged one level deeper so an overlay can fix just
+ *    `limit.context` without restating the rest of the model.
+ *  - Model only in the overlay → added.
+ *
+ * Pure: never mutates its inputs.
+ */
+declare function mergeModelsPayload(base: ModelsDevPayload, overlay: ModelsDevPayload): ModelsDevPayload;
+
+interface MessageRepairReport {
+    changed: boolean;
+    removedToolUses: string[];
+    removedToolResults: string[];
+    removedMessages: number;
+}
+interface MessageRepairResult {
+    messages: Message[];
+    report: MessageRepairReport;
+}
+/**
+ * Repair provider-level tool-call adjacency invariants.
+ *
+ * Anthropic requires every assistant `tool_use` block to have a matching
+ * `tool_result` block in the immediately following user message. Manual
+ * context surgery (summary/prune) can cut through the middle of such an
+ * exchange. This function removes only the now-orphaned protocol blocks,
+ * preserving surrounding text/images/thinking blocks where possible.
+ */
+declare function repairToolUseAdjacency(messages: Message[]): MessageRepairResult;
+
+type NewlineStyle = 'lf' | 'crlf' | 'cr';
+declare function detectNewlineStyle(text: string): NewlineStyle;
+declare function toStyle(text: string, style: NewlineStyle): string;
+declare function normalizeToLf(text: string): string;
+
+/**
+ * Compile a user-supplied regex with conservative bounds against ReDoS.
+ *
+ * Duplicated from @wrongstack/tools/_regex.ts to avoid a circular
+ * dependency (tools depends on core, not vice versa). Keep both copies
+ * in sync if the heuristics change.
+ *
+ * V8's regex engine is backtracking-based and cannot interrupt a
+ * synchronous match — a pattern like `(a+)+$` against a sufficiently
+ * long line will pin a worker for seconds.
+ */
+interface CompileResult {
+    ok: true;
+    regex: RegExp;
 }
-interface FileLockOptions {
-    timeoutMs?: number | undefined;
-    staleMs?: number | undefined;
+interface CompileFail {
+    ok: false;
+    reason: string;
 }
-declare function atomicWrite(targetPath: string, content: string | Uint8Array, opts?: AtomicWriteOptions): Promise<void>;
-declare function ensureDir(dir: string): Promise<void>;
-declare function withFileLock<T>(targetPath: string, fn: () => Promise<T>, opts?: FileLockOptions): Promise<T>;
+declare function compileUserRegex(pattern: string, flags: string): CompileResult | CompileFail;
 
 interface SafeParseResult<T> {
     ok: boolean;
@@ -40,30 +367,19 @@ declare function safeStringify(value: unknown, pretty?: boolean): string;
  */
 declare function sanitizeJsonString(s: string): string | null;
 
-type NewlineStyle = 'lf' | 'crlf' | 'cr';
-declare function detectNewlineStyle(text: string): NewlineStyle;
-declare function toStyle(text: string, style: NewlineStyle): string;
-declare function normalizeToLf(text: string): string;
+/** Resolve a promise after `ms` milliseconds. Prefer this over raw
+ *  `setTimeout` wrappers so all delay sites use a single implementation
+ *  and an abortable variant can be introduced without a codebase-wide hunt. */
+declare function sleep(ms: number): Promise<void>;
 
-declare const color: {
-    reset: (s: string) => string;
-    bold: (s: string) => string;
-    dim: (s: string) => string;
-    italic: (s: string) => string;
-    underline: (s: string) => string;
-    red: (s: string) => string;
-    green: (s: string) => string;
-    yellow: (s: string) => string;
-    blue: (s: string) => string;
-    magenta: (s: string) => string;
-    cyan: (s: string) => string;
-    gray: (s: string) => string;
-    amber: (s: string) => string;
-    pink: (s: string) => string;
-    bgRed: (s: string) => string;
-    bgGreen: (s: string) => string;
-};
-declare function stripAnsi(s: string): string;
+/**
+ * String utilities shared across the WrongStack codebase.
+ */
+/**
+ * Truncate a string to at most `max` characters, appending an ellipsis if it
+ * was longer. Returns the original string unchanged when it fits.
+ */
+declare function truncate(s: string, max: number): string;
 
 /**
  * TTY detection helpers — the single source of truth for "is this process
@@ -141,233 +457,77 @@ declare function setRawMode(input: NodeJS.ReadStream, mode: boolean): boolean;
  * When no prompt is active the guard is `null` and writes pass straight
  * through — so agent-turn output (spinner, renderer) is untouched.
  */
-interface OutputLineGuard {
-    /** Clear the current input row right before an out-of-band write. */
-    suspend(): void;
-    /** Repaint the prompt + in-progress draft right after the write. */
-    resume(): void;
-}
-/**
- * Register (or clear, with `null`) the guard that brackets out-of-band
- * writes. Installed by {@link writeOut}/{@link writeErr} consumers — in
- * practice the CLI's readline input reader — only while a prompt is live.
- * Idempotent; the most recent caller wins.
- */
-declare function setOutputLineGuard(guard: OutputLineGuard | null): void;
-/**
- * Write `s` to `stream` (defaults to `process.stdout`). Returns `false`
- * when the stream is missing or doesn't expose `write` so callers can
- * degrade silently under hostile host environments (closed pipe, mock
- * injects `null`, test replaces the stream with a stub).
- *
- * Why a helper:
- *   1. **Single seam for output capture in tests** — stub `writeOut` once
- *      and assert on what the rest of the codebase intended to print,
- *      without spying on `process.stdout.write` (which is brittle and
- *      leaks across parallel test files).
- *   2. **Stream swap without grep** — routing the CLI's output to a
- *      logger or `out.log` becomes a one-line change at process boot.
- *   3. **Defensive default** — closes the "what if `process.stdout` is
- *      `null`" gap that currently exists at ~50 call sites that just
- *      call `process.stdout.write(s)` and crash on certain Windows
- *      redirect invocations.
- *
- * Call-site migration is staged: this commit introduces the helper, a
- * follow-up commit replaces the 50+ `process.stdout.write(...)` sites
- * with `writeOut(...)`. Until that migration lands, both forms coexist
- * and `writeOut` is the preferred form for new code.
- */
-declare function writeOut(s: string, stream?: NodeJS.WriteStream): boolean;
-/**
- * Symmetric partner of `writeOut` for the standard error stream. Same shape,
- * same defensive contract, same single-seam-for-tests story — just defaults to
- * `process.stderr` instead of `process.stdout`.
- *
- * Use this in code paths that emit error/diagnostic/warning text. Keeping
- * these two helpers split (rather than a single `writeTo(s, stream)`) means
- * the call site reads as a clear intent signal: "I am writing an error" vs.
- * "I am writing a result" — which matters for callers that decide between
- * stdout/stderr routing (e.g. `--quiet` flags, log-level filtering,
- * structured-log rewriters that fork on stream).
- *
- * Stderr writes from the core logger (see `infrastructure/logger.ts`) and from
- * the TUI guard (see `tui/run-tui.ts`) used to call `process.stderr.write`
- * directly. Routing them through this helper lets tests stub the stream at
- * one boundary and lets future logging middleware (e.g. a JSON-line rewriter)
- * swap the destination for the entire process in one place.
- */
-declare function writeErr(s: string, stream?: NodeJS.WriteStream): boolean;
-
-/**
- * Canonical text rendering of the live todo list, shared by the CLI's
- * `/todos` slash command and the TUI's auto-echo (which prints the same
- * snapshot to chat history each time the `todo` tool mutates the list).
- *
- * Layout: a header line with the `done/total done` count, then one row
- * per item — `[ ]` pending, `[~]` in-progress, `[x]` completed. In-
- * progress rows prefer `activeForm` ("Building the project") over the
- * imperative `content` ("Build the project") when present.
- *
- * Returned as a single newline-joined string so callers can hand it
- * straight to a history dispatcher or stdout.
- */
-declare function formatTodosList(todos: TodoItem[]): string;
-
-/**
- * String utilities shared across the WrongStack codebase.
- */
-/**
- * Truncate a string to at most `max` characters, appending an ellipsis if it
- * was longer. Returns the original string unchanged when it fits.
- */
-declare function truncate(s: string, max: number): string;
-
-declare function compileGlob(pattern: string): RegExp;
-declare function matchGlob(pattern: string, input: string): boolean;
-declare function matchAny(patterns: string[], input: string): boolean;
-
-/**
- * Myers diff with unified-format output. No external dependencies.
- * Operates on arrays of lines (newline-terminated or stripped).
- */
-interface UnifiedDiffOptions {
-    context?: number | undefined;
-    fromFile?: string | undefined;
-    toFile?: string | undefined;
-}
-declare function unifiedDiff(oldText: string, newText: string, opts?: UnifiedDiffOptions): string;
-
-/**
- * Build a sanitized child-process environment.
- *
- * The bash/exec tools and MCP stdio transports execute LLM-generated or
- * configured commands. The parent process carries provider API keys
- * (ANTHROPIC_API_KEY, OPENAI_API_KEY, ...), VCS tokens (GITHUB_TOKEN),
- * and cloud credentials. Forwarding those to a child is an exfiltration
- * vector even with `permission: 'confirm'` — a compromised MCP server
- * or a cleverly composed shell pipeline can leak secrets.
- *
- * Strategy: copy a small, explicit allowlist of variables that real builds
- * need, then copy anything else that does NOT look secret-bearing. This
- * preserves user-friendly behavior (locale, terminal, npm config) while
- * blocking the obvious leak channels.
- *
- * Override with `WRONGSTACK_CHILD_ENV_PASSTHROUGH=1` to forward the full
- * parent environment unchanged (opt-in for advanced users who understand
- * the risk).
- */
-interface BuildChildEnvOptions {
-    /** Session ID to inject as WRONGSTACK_SESSION_ID. */
-    sessionId?: string | undefined;
-    /** Additional env vars to merge (takes priority over filtered parent env). */
-    extra?: NodeJS.ProcessEnv | undefined;
-}
-/**
- * Build a filtered child-process environment suitable for bash, exec, and
- * MCP server subprocesses. Strips API keys, tokens, and other credentials
- * while preserving system/tooling variables.
- */
-declare function buildChildEnv(optsOrSessionId?: BuildChildEnvOptions | string): NodeJS.ProcessEnv;
-
-/** Resolve a promise after `ms` milliseconds. Prefer this over raw
- *  `setTimeout` wrappers so all delay sites use a single implementation
- *  and an abortable variant can be introduced without a codebase-wide hunt. */
-declare function sleep(ms: number): Promise<void>;
-
-/**
- * Exhaustiveness check for discriminated union switches.
- * Place in the `default` branch of a switch over a union type
- * to get a compile-time error when a new variant is added.
- *
- * @example
- * switch (block.type) {
- *   case 'text': return renderText(block);
- *   case 'tool_use': return renderToolUse(block);
- *   default: return assertNever(block);
- * }
- */
-declare function assertNever(x: never, message?: string): never;
-
-/**
- * Deep merge utility — safely merges nested objects with configurable
- * conflict resolution, array merging, and prototype-pollution guarding.
- *
- * Used by:
- * - config-loader  (config layer merging with primitive-array concatenation)
- * - secret-vault   (config patching)
- * - json-path       (json_merge tool with prefer-base / prefer-patch semantics)
- *
- * @module utils/deep-merge
- */
-declare const FORBIDDEN_PROTO_KEYS: Set<string>;
-/** True when every element is a primitive or null (no nested objects/arrays). */
-declare function isPrimitiveArray(a: unknown[]): boolean;
-interface DeepMergeOptions {
-    /**
-     * Which side wins on collision for scalars and arrays.
-     *
-     * - `'prefer-patch'` (default): patch value replaces base value.
-     * - `'prefer-base'`:  base value is kept, patch value is ignored.
-     */
-    conflictResolution?: 'prefer-base' | 'prefer-patch';
-    /**
-     * How to handle array values.
-     *
-     * - `'replace'` (default): patch array replaces base array entirely.
-     * - `'concat-primitives'`: when both values are primitive arrays,
-     *   they are concatenated and deduped (via Set).  Non-primitive
-     *   arrays still replace the base wholesale.
-     */
-    arrayMode?: 'replace' | 'concat-primitives';
-    /**
-     * Skip prototype-pollution keys (`__proto__`, `constructor`, etc.).
-     * Enabled by default.  Only disable when you control both inputs
-     * and the keyset (e.g. when merging trusted JSON schemas).
-     */
-    protectProto?: boolean;
-    /**
-     * Optional callback fired when a non-primitive (object) array is
-     * replaced wholesale (only relevant with `arrayMode: 'concat-primitives'`).
-     * Receives the key name, existing array length, and patch array length.
-     * Used by config-loader for debug logging.
-     */
-    onNonPrimitiveArrayReplace?: (key: string, existingLen: number, patchLen: number) => void;
+interface OutputLineGuard {
+    /** Clear the current input row right before an out-of-band write. */
+    suspend(): void;
+    /** Repaint the prompt + in-progress draft right after the write. */
+    resume(): void;
 }
 /**
- * Recursively merge `patch` into `base`, returning a new object.
+ * Register (or clear, with `null`) the guard that brackets out-of-band
+ * writes. Installed by {@link writeOut}/{@link writeErr} consumers — in
+ * practice the CLI's readline input reader — only while a prompt is live.
+ * Idempotent; the most recent caller wins.
+ */
+declare function setOutputLineGuard(guard: OutputLineGuard | null): void;
+/**
+ * Write `s` to `stream` (defaults to `process.stdout`). Returns `false`
+ * when the stream is missing or doesn't expose `write` so callers can
+ * degrade silently under hostile host environments (closed pipe, mock
+ * injects `null`, test replaces the stream with a stub).
  *
- * - Nested plain objects are merged recursively.
- * - Arrays are handled per `options.arrayMode`.
- * - Scalar collisions are resolved per `options.conflictResolution`.
- * - `null` and non-object values in `patch` replace the base value
- *   (unless `conflictResolution` is `'prefer-base'`).
- * - Keys in `base` that are absent from `patch` are preserved.
- * - `FORBIDDEN_PROTO_KEYS` are skipped in the patch (unless
- *   `options.protectProto` is set to `false`).
+ * Why a helper:
+ *   1. **Single seam for output capture in tests** — stub `writeOut` once
+ *      and assert on what the rest of the codebase intended to print,
+ *      without spying on `process.stdout.write` (which is brittle and
+ *      leaks across parallel test files).
+ *   2. **Stream swap without grep** — routing the CLI's output to a
+ *      logger or `out.log` becomes a one-line change at process boot.
+ *   3. **Defensive default** — closes the "what if `process.stdout` is
+ *      `null`" gap that currently exists at ~50 call sites that just
+ *      call `process.stdout.write(s)` and crash on certain Windows
+ *      redirect invocations.
  *
- * The function is generic over `T extends Record<string, unknown>` for
- * callers that pass typed config objects, but the runtime signature
- * also accepts `unknown` inputs (used by the json-path plugin).
+ * Call-site migration is staged: this commit introduces the helper, a
+ * follow-up commit replaces the 50+ `process.stdout.write(...)` sites
+ * with `writeOut(...)`. Until that migration lands, both forms coexist
+ * and `writeOut` is the preferred form for new code.
  */
-declare function deepMerge<T extends Record<string, unknown>>(base: T, patch: Record<string, unknown>, options?: DeepMergeOptions): T;
-declare function deepMerge(base: unknown, patch: unknown, options?: DeepMergeOptions): unknown;
+declare function writeOut(s: string, stream?: NodeJS.WriteStream): boolean;
+/**
+ * Symmetric partner of `writeOut` for the standard error stream. Same shape,
+ * same defensive contract, same single-seam-for-tests story — just defaults to
+ * `process.stderr` instead of `process.stdout`.
+ *
+ * Use this in code paths that emit error/diagnostic/warning text. Keeping
+ * these two helpers split (rather than a single `writeTo(s, stream)`) means
+ * the call site reads as a clear intent signal: "I am writing an error" vs.
+ * "I am writing a result" — which matters for callers that decide between
+ * stdout/stderr routing (e.g. `--quiet` flags, log-level filtering,
+ * structured-log rewriters that fork on stream).
+ *
+ * Stderr writes from the core logger (see `infrastructure/logger.ts`) and from
+ * the TUI guard (see `tui/run-tui.ts`) used to call `process.stderr.write`
+ * directly. Routing them through this helper lets tests stub the stream at
+ * one boundary and lets future logging middleware (e.g. a JSON-line rewriter)
+ * swap the destination for the entire process in one place.
+ */
+declare function writeErr(s: string, stream?: NodeJS.WriteStream): boolean;
 
 /**
- * Tool output serialization utilities.
- * Extracted from Agent.executeTools to allow reuse and consistent output handling.
+ * Canonical text rendering of the live todo list, shared by the CLI's
+ * `/todos` slash command and the TUI's auto-echo (which prints the same
+ * snapshot to chat history each time the `todo` tool mutates the list).
+ *
+ * Layout: a header line with the `done/total done` count, then one row
+ * per item — `[ ]` pending, `[~]` in-progress, `[x]` completed. In-
+ * progress rows prefer `activeForm` ("Building the project") over the
+ * imperative `content` ("Build the project") when present.
+ *
+ * Returned as a single newline-joined string so callers can hand it
+ * straight to a history dispatcher or stdout.
  */
-interface ToolOutputSerializerOptions {
-    perIterationOutputCapBytes?: number | undefined;
-    estimator?: ((text: string) => number) | undefined;
-}
-declare function createToolOutputSerializer(opts?: ToolOutputSerializerOptions): {
-    serialize: (value: unknown) => string;
-    enforceCap: (text: string, remainingBudget: number) => {
-        text: string;
-        newBudget: number;
-    };
-    capBytes: number;
-};
+declare function formatTodosList(todos: TodoItem[]): string;
 
 /**
  * Estimate tokens for a tool_use block input.
@@ -480,164 +640,52 @@ declare function estimateRequestTokensCalibrated(messages: unknown, systemPrompt
  */
 declare function resetCalibration(calibrationKey?: string): void;
 
-interface MessageRepairReport {
-    changed: boolean;
-    removedToolUses: string[];
-    removedToolResults: string[];
-    removedMessages: number;
-}
-interface MessageRepairResult {
-    messages: Message[];
-    report: MessageRepairReport;
-}
-/**
- * Repair provider-level tool-call adjacency invariants.
- *
- * Anthropic requires every assistant `tool_use` block to have a matching
- * `tool_result` block in the immediately following user message. Manual
- * context surgery (summary/prune) can cut through the middle of such an
- * exchange. This function removes only the now-orphaned protocol blocks,
- * preserving surrounding text/images/thinking blocks where possible.
- */
-declare function repairToolUseAdjacency(messages: Message[]): MessageRepairResult;
-
 /**
- * Minimal JSON Schema validator — covers the subset needed for plugin
- * configSchema validation and tool inputSchema sanity checks. Intentionally
- * small (~80 lines, zero deps) and tolerant: unknown keywords are ignored so
- * authors can mix in non-standard extensions without breaking validation.
- *
- * NOT for full JSON Schema 2020-12 conformance. If a plugin needs $ref,
- * conditional schemas, format validation, or anything else exotic, it should
- * bring its own ajv-based validator and call this only for the cheap path.
+ * Tool output serialization utilities.
+ * Extracted from Agent.executeTools to allow reuse and consistent output handling.
  */
-
-interface ValidationError {
-    path: string;
-    message: string;
+interface ToolOutputSerializerOptions {
+    perIterationOutputCapBytes?: number | undefined;
+    estimator?: ((text: string) => number) | undefined;
 }
-interface ValidationResult {
-    ok: boolean;
-    errors: ValidationError[];
+interface ToolOutputSerializeContext {
+    toolName?: string | undefined;
+    input?: unknown;
 }
-declare function validateAgainstSchema(value: unknown, schema: JSONSchema): ValidationResult;
+declare function createToolOutputSerializer(opts?: ToolOutputSerializerOptions): {
+    serialize: (value: unknown, context?: ToolOutputSerializeContext) => string;
+    enforceCap: (text: string, remainingBudget: number) => {
+        text: string;
+        newBudget: number;
+    };
+    capBytes: number;
+};
 
-/**
- * Compile a user-supplied regex with conservative bounds against ReDoS.
- *
- * Duplicated from @wrongstack/tools/_regex.ts to avoid a circular
- * dependency (tools depends on core, not vice versa). Keep both copies
- * in sync if the heuristics change.
- *
- * V8's regex engine is backtracking-based and cannot interrupt a
- * synchronous match — a pattern like `(a+)+$` against a sufficiently
- * long line will pin a worker for seconds.
- */
-interface CompileResult {
-    ok: true;
-    regex: RegExp;
+interface ToolWireDefinitionLike {
+    name: string;
+    description?: string | undefined;
+    inputSchema: unknown;
 }
-interface CompileFail {
-    ok: false;
-    reason: string;
+interface CompactToolDefinitionForWireOptions {
+    /** Top-level tool description budget. */
+    descriptionMaxChars?: number | undefined;
+    /** Per-JSON-Schema `description` annotation budget. */
+    schemaDescriptionMaxChars?: number | undefined;
+}
+interface CompactWireToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
 }
-declare function compileUserRegex(pattern: string, flags: string): CompileResult | CompileFail;
-
-/**
- * Resolve `pattern` to the set of concrete file paths it matches.
- * Literal paths (no glob chars) are returned as-is.
- *
- * @example
- * await expandGlob('src/**\/*.ts')  // → ['src/a.ts', 'src/b/c.ts', ...]
- * await expandGlob('foo.txt')       // → ['foo.txt']
- */
-declare function expandGlob(pattern: string): Promise<string[]>;
-
-/**
- * Attempt to close an incomplete JSON object string by auto-closing braces
- * and completing any unclosed double-quoted string values.
- *
- * Strategy:
- * 1. Compute origOpen from the ORIGINAL input (how many braces are unclosed).
- * 2. Add that many closing braces. If result is now valid JSON → return it.
- * 3. If still invalid: trim trailing whitespace, strip trailing backslash.
- * 4. Walk backwards to detect an unclosed string value.
- *    - Quote followed by `:` → key-name, skip
- *    - Quote followed by `,` `}` or end-of-string → toggle in/out of string
- * 5. If we end INSIDE a string (unclosed opening `"`), append `"` + origOpen `}`.
- *
- * Known limitations:
- * - Strings whose content ends with a `"` character cannot be repaired
- *   (algorithm can't distinguish content-`"` from string-terminator `"`).
- * - Input ending in bare `:` (incomplete value expression) can't be meaningfully repaired.
- * - Bare `{` returns unchanged.
- * - If origOpen=0 (braces balanced) but string is unclosed, repair is skipped
- *   (the input would be valid JSON per JSON.parse, so it's returned as-is).
- */
-declare function completePartialObject(s: string): string;
-
-/**
- * Deep-merge a curated `overlay` payload on top of a `base` payload (both in
- * the models.dev `api.json` shape). The overlay always wins: it can add
- * providers/models the base lacks and override fields the base gets wrong.
- *
- * Precedence rules:
- *  - Provider present in both → scalar fields (`name`, `npm`, `api`, `env`,
- *    `doc`) come from the overlay when set; `models` maps merge by model id.
- *  - Provider only in the overlay → added wholesale.
- *  - Model present in both → overlay model fields override base model fields
- *    (`{ ...base, ...overlay }`), with the nested `limit` / `cost` /
- *    `modalities` objects merged one level deeper so an overlay can fix just
- *    `limit.context` without restating the rest of the model.
- *  - Model only in the overlay → added.
- *
- * Pure: never mutates its inputs.
- */
-declare function mergeModelsPayload(base: ModelsDevPayload, overlay: ModelsDevPayload): ModelsDevPayload;
-
-/**
- * Merge per-provider `customModels` into top-level `configModels`.
- *
- * Keys present in `configModels` always win over `providerCustomModels`
- * when the same model id appears in both places. This lets the user
- * override provider-attached definitions from the top-level config.
- *
- * Pure: never mutates its inputs.
- */
-declare function mergeCustomModelDefs(providerCustomModels: Record<string, CustomModelDefinition> | undefined, configModels: Record<string, CustomModelDefinition> | undefined): Record<string, CustomModelDefinition> | undefined;
-
-/**
- * Shared IP-address guards for SSRF protection.
- *
- * Exported so `fetch.ts` (tools), `web-search/index.ts` (plugins), and any
- * other package that needs to validate IPs can all consume the same logic.
- * Any future additions (e.g. extra CIDR blocks) need only be made here.
- */
-/**
- * True if `addr` is in a private / loopback / link-local / reserved / CGNAT /
- * multicast range.  `net.isIP` is called by the caller first so `addr` is
- * guaranteed to be a canonical dotted-quad at this point.
- */
-declare function isPrivateIPv4(addr: string): boolean;
-/**
- * True if `raw` (an IPv6 literal, already lowercased) is loopback / unique-local /
- * link-local / unspecified / IPv4-mapped-private.
- */
-declare function isPrivateIPv6(raw: string): boolean;
-/**
- * Expand an IPv6 string into exactly 8 16-bit numbers.  Handles `::` compression.
- * Returns null on malformed input — caller should treat that as "block".
- */
-declare function expandIPv6(addr: string): number[] | null;
 /**
- * Convenience: throw if `hostname` resolves to a private / loopback IP.
- * Use as a pre-flight check before opening a socket.
+ * Return the provider-wire version of a tool definition.
  *
- * ⚠️  This is not sufficient alone — connections must also use a pinned
- * dispatcher (so the OS re-uses the already-resolved address) or the same
- * check must be applied after every redirect hop.  See `guardedLookup` in
- * `fetch.ts` for the connection-level enforcement.
+ * Tool schemas remain structurally intact: validation keywords, property
+ * names, required fields, enum values, and nested shapes are preserved. The
+ * only reduction is on human prose annotations (`description`), which are the
+ * largest repeated cost in provider tool declarations.
  */
-declare function assertNotPrivateHost(hostname: string): Promise<void>;
+declare function compactToolDefinitionForWire(tool: ToolWireDefinitionLike, opts?: CompactToolDefinitionForWireOptions): CompactWireToolDefinition;
+declare function compactSchemaDescriptions(schema: unknown, maxDescriptionChars?: number): Record<string, unknown>;
 
-export { type AtomicWriteOptions, type BuildChildEnvOptions, type CompileFail, type CompileResult, type DeepMergeOptions, FORBIDDEN_PROTO_KEYS, type FileLockOptions, type MessageRepairReport, type MessageRepairResult, type NewlineStyle, type OutputLineGuard, type RequestTokenBreakdown, type SafeParseResult, type ToolOutputSerializerOptions, type UnifiedDiffOptions, type ValidationError, type ValidationResult, assertNever, assertNotPrivateHost, atomicWrite, buildChildEnv, color, compileGlob, compileUserRegex, completePartialObject, computeMessageTokens, createToolOutputSerializer, deepMerge, detectNewlineStyle, ensureDir, estimateMessageTokens, estimateRequestTokens, estimateRequestTokensCalibrated, estimateTextTokens, estimateToolDefTokens, estimateToolInputTokens, estimateToolResultTokens, expandGlob, expandIPv6, formatTodosList, getCalibrationState, getTermSize, isInteractive, isPrimitiveArray, isPrivateIPv4, isPrivateIPv6, isStdinTTY, isStdoutTTY, matchAny, matchGlob, mergeCustomModelDefs, mergeModelsPayload, normalizeToLf, onResize, recordActualUsage, repairToolUseAdjacency, resetCalibration, safeParse, safeStringify, sanitizeJsonString, setOutputLineGuard, setRawMode, sleep, stripAnsi, toStyle, truncate, unifiedDiff, validateAgainstSchema, withFileLock, writeErr, writeOut };
+export { type AtomicWriteOptions, type BuildChildEnvOptions, type CompactToolDefinitionForWireOptions, type CompactWireToolDefinition, type CompileFail, type CompileResult, type DeepMergeOptions, FORBIDDEN_PROTO_KEYS, type FileLockOptions, type MessageRepairReport, type MessageRepairResult, type NewlineStyle, type OutputLineGuard, type RecordToolOutputEvidenceInput, type RequestTokenBreakdown, type SafeParseResult, type ToolOutputSerializerOptions, type ToolWireDefinitionLike, type UnifiedDiffOptions, type ValidationError, type ValidationResult, assertNever, assertNotPrivateHost, atomicWrite, buildChildEnv, buildContextEvidenceDigest, color, compactSchemaDescriptions, compactToolDefinitionForWire, compileGlob, compileUserRegex, completePartialObject, computeMessageTokens, createContextEvidenceState, createToolOutputSerializer, deepMerge, detectNewlineStyle, ensureDir, estimateMessageTokens, estimateRequestTokens, estimateRequestTokensCalibrated, estimateTextTokens, estimateToolDefTokens, estimateToolInputTokens, estimateToolResultTokens, expandGlob, expandIPv6, formatTodosList, getCalibrationState, getTermSize, isInteractive, isPrimitiveArray, isPrivateIPv4, isPrivateIPv6, isStdinTTY, isStdoutTTY, markAssistantReferencedEvidence, matchAny, matchGlob, mergeCustomModelDefs, mergeModelsPayload, normalizeToLf, onResize, recordActualUsage, recordToolOutputEvidence, recordUserIntentEvidence, repairToolUseAdjacency, repeatedReadPressure, resetCalibration, safeParse, safeStringify, sanitizeJsonString, setOutputLineGuard, setRawMode, sleep, stripAnsi, toStyle, truncate, unifiedDiff, validateAgainstSchema, withFileLock, writeErr, writeOut };