@wrongstack/core 0.284.0 → 0.285.0

package/dist/utils/index.d.ts

@@ -1,921 +1,38 @@
-import { M as Message, H as CompletedWorkSource, d as Context, s as TextBlock, K as ContextEvidenceState, G as CompletedWorkEvidence, o as ToolOutputMetadata, J as JSONSchema, A as TodoItem, g as Tool } from '../tool-BNlnIJvo.js';
-export { H as HttpDispatcher, a as HttpsAgentAsDispatcher } from '../dispatcher-types.d-BBeXBQgS.js';
+export * from './assert-never.js';
+export * from './atomic-write.js';
+export * from './child-env.js';
+export * from './color.js';
+export * from './config-json.js';
+export { buildContextEvidenceDigest, COMPLETED_WORK_LEDGER_MARKER, createContextEvidenceState, formatCompletedWorkLedger, markAssistantReferencedEvidence, type RecordCompletedWorkInput, type RecordToolOutputEvidenceInput, recordCompletedWorkEvidence, buildCompletedWorkLedgerBlock, recordToolOutputEvidence, recordUserIntentEvidence, repeatedReadPressure, syncCompletedWorkLedgerBlock, } from './context-evidence.js';
+export { type DeepMergeOptions, deepMerge, FORBIDDEN_PROTO_KEYS, isPrimitiveArray, } from './deep-merge.js';
+export * from './diff.js';
+export type { HttpDispatcher, HttpsAgentAsDispatcher } from './dispatcher-types.js';
 export { toErrorMessage } from './error.js';
-export { expectDefined } from './expect-defined.js';
-import { E as CustomModelDefinition, c as ModelsDevPayload, ac as ToolDescriptionMode, ad as ToolDescriptionModeConfig, T as ToolResultRenderMode, ae as ToolResultRenderModeConfig } from '../config-MRqn1V-u.js';
-export { T as TaskItem, c as computeTaskItemProgress, f as formatTaskList, a as formatTaskProgress } from '../task-format-GX0B1mMC.js';
-export { a as WstackPathOptions, W as WstackPaths, p as projectHash, b as projectSlug, r as resolveWstackPaths, w as wstackGlobalRoot } from '../wstack-paths-C3K40Qst.js';
-export { a as TaskPriority, b as TaskStatus, T as TaskType } from '../task-graph-CH3acNQ7.js';
-import 'node:https';
-import 'undici';
-
-/**
- * Estimate tokens for a tool_use block input.
- * Caches the stringified result keyed by the stable string representation
- * to avoid repeated JSON.stringify calls during context window checks.
- */
-declare function estimateToolInputTokens(input: unknown): number;
-/**
- * Estimate tokens for a tool_result content.
- */
-declare function estimateToolResultTokens(content: string | unknown): number;
-/**
- * Estimate tokens for a text block.
- */
-declare function estimateTextTokens(text: string): number;
-/**
- * Compute and cache the token estimate for a single message. This is the
- * canonical per-message estimator — called once by ConversationState on
- * append/replace so the O(n·m) content-block walk happens at mutation time,
- * not on every context-pressure check.
- */
-declare function computeMessageTokens(msg: Message): number;
-/**
- * Estimate tokens for an array of messages (text + tool I/O), using the shared
- * 3.5 chars/token basis. This is the single canonical message-array estimator —
- * compactors, the context_manager tool, and the `/context` display all route
- * through it so the number a user sees matches the number compaction decides on.
- *
- * When a message carries a pre-computed `_estTokens` field (set by
- * ConversationState on append/replace), it is used directly instead of
- * re-walking the content blocks — turning the O(n·m) scan into an O(n)
- * sum for fully-cached arrays.
- */
-declare function estimateMessageTokens(messages: readonly Message[]): number;
-/**
- * Rough estimate of tokens in a tool definition (name + description + schema).
- * Accounts for the JSON-serialized inputSchema which is sent to the API
- * but NOT included in roughEstimate(content).
- */
-declare function estimateToolDefTokens(tool: {
-    name: string;
-    description?: string | undefined;
-    inputSchema: unknown;
-}): number;
-/**
- * Estimate the total API request token count: system prompt + tool definitions
- * + conversation messages. Use this for context-window bar calculations
- * instead of roughEstimate (which only counts messages).
- *
- * The overhead ratio (overhead / messages) varies by conversation length:
- *   - Short conversations (< 10 messages): ~30-50% overhead (large system+tools)
- *   - Medium (10-50 messages): ~15-30%
- *   - Long (> 50 messages): ~5-15%
- *
- * Returns { messages, systemPrompt, tools, total } for debugging display.
- */
-interface RequestTokenBreakdown {
-    messages: number;
-    systemPrompt: number;
-    tools: number;
-    total: number;
-}
-declare function estimateRequestTokens(messages: unknown, systemPrompt: unknown, tools: {
-    name: string;
-    description?: string | undefined;
-    inputSchema: unknown;
-}[], calibrationKey?: string): RequestTokenBreakdown;
-/**
- * Record the actual API input token count after a provider call so
- * `estimateRequestTokensCalibrated` can self-correct on subsequent calls.
- *
- * Prefer passing `estimatedInputTokens` explicitly (the calibrated pre-flight
- * estimate from the middleware) — this avoids race conditions when other code
- * also calls `estimateRequestTokens` between the pre-flight and this call
- * (e.g. audit logging in agent.ts).
- *
- * When `estimatedInputTokens` is omitted, falls back to the keyed bucket's
- * `prevEst` for backward compatibility with callers that don't have the
- * pre-flight value. `calibrationKey` selects the per-(provider,model) bucket
- * (defaults to the shared global bucket).
- */
-declare function recordActualUsage(actualInputTokens: number, estimatedInputTokens?: number, calibrationKey?: string): void;
-/**
- * Returns the current calibration state for a bucket. Exposed for debugging
- * and tests — not needed by normal callers.
- */
-declare function getCalibrationState(calibrationKey?: string): {
-    ratio: number;
-    count: number;
-    calibrated: boolean;
-};
-/**
- * Like `estimateRequestTokens` but applies the rolling calibration factor
- * so context pressure readings converge on reality within a few iterations.
- *
- * Before any `recordActualUsage` samples are collected, returns the same
- * result as `estimateRequestTokens` (ratio = 1.0, no distortion).
- * After `MIN_SAMPLES_FOR_CALIBRATION` samples, applies the calibrated
- * multiplier capped to the range [0.5, 1.5] as a sanity bound.
- */
-declare function estimateRequestTokensCalibrated(messages: unknown, systemPrompt: unknown, tools: {
-    name: string;
-    description?: string | undefined;
-    inputSchema: unknown;
-}[], calibrationKey?: string): RequestTokenBreakdown;
-/**
- * Resets calibration state. Primarily for tests that run in the same
- * process and need a clean slate between suites. With no argument it clears
- * every bucket (including the global one); pass a key to reset just that bucket.
- */
-declare function resetCalibration(calibrationKey?: string): 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;
-
-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. Two value-side guards back up the
- * name-based filter:
- *   - any value carrying an embedded URI credential (`scheme://user:pass@host`,
- *     e.g. `DATABASE_URL`/`REDIS_URL`/`*_DSN`) is dropped (WS-01);
- *   - `NODE_OPTIONS` is forwarded but with module-preload directives
- *     (`--require`/`--import`/`--loader`) stripped so a parent-set value can't
- *     inject code into node children (WS-02).
- *
- * Override with `WRONGSTACK_CHILD_ENV_PASSTHROUGH=1` to forward the full
- * parent environment unchanged (opt-in for advanced users who understand
- * the risk).
- */
-/**
- * Strip module-preload directives from a `NODE_OPTIONS` value while preserving
- * benign flags (`--no-warnings`, `--max-old-space-size=…`, etc.). Handles both
- * the `--require=./x.js` and space-separated `--require ./x.js` forms. Returns
- * the sanitized string (possibly empty).
- */
-declare function sanitizeNodeOptions(value: string): string;
-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;
-
-type JsonObject = Record<string, unknown>;
-type JsonPathSegment = string | number;
-type JsonPath = readonly JsonPathSegment[];
-declare function readJsonObjectFile(filePath: string): Promise<JsonObject>;
-declare function jsonObjectFileExists(filePath: string): Promise<boolean>;
-declare function writeJsonObjectFile(filePath: string, value: JsonObject): Promise<void>;
-declare function updateJsonObjectFile(filePath: string, mutator: (config: JsonObject) => void | JsonObject | Promise<void | JsonObject>): Promise<JsonObject>;
-declare function getJsonPath(root: unknown, path: JsonPath): unknown;
-declare function setJsonPath(root: JsonObject, path: JsonPath, value: unknown): JsonObject;
-declare function removeJsonPath(root: JsonObject, path: JsonPath): boolean;
-declare function setJsonPathInFile(filePath: string, path: JsonPath, value: unknown): Promise<JsonObject>;
-declare function removeJsonPathInFile(filePath: string, path: JsonPath): Promise<JsonObject>;
-declare function isJsonObject(value: unknown): value is JsonObject;
-
-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;
-/** Marker prefixing the ledger's system-prompt block (also used to find/replace it). */
-declare const COMPLETED_WORK_LEDGER_MARKER = "[completed_work_ledger]";
-interface RecordCompletedWorkInput {
-    /** Stable dedupe key, e.g. `task:<id>` — re-completion updates in place. */
-    key: string;
-    source: CompletedWorkSource;
-    summary: string;
-    /** Optional pointer to proof (test run, commit hash, file path). */
-    evidence?: string | undefined;
-    /** Epoch ms; defaults to now. */
-    completedAt?: number | undefined;
-}
-/**
- * Append one finished unit of work to the session ledger. The provider request
- * composer renders this state as a volatile tail block; the stable system-prompt
- * prefix is never mutated here.
- */
-declare function recordCompletedWorkEvidence(ctx: Context, input: RecordCompletedWorkInput): CompletedWorkEvidence;
-/** Render the ledger's system-prompt block text (marker + newest entries). */
-declare function formatCompletedWorkLedger(items: readonly CompletedWorkEvidence[]): string;
-/** Build the current volatile completed-work block without mutating the prompt. */
-declare function buildCompletedWorkLedgerBlock(ctx: Context): TextBlock | undefined;
-/**
- * @deprecated Volatile state must be composed at request time. Kept as a
- * compatibility no-op for embedders importing the old helper.
- */
-declare function syncCompletedWorkLedgerBlock(_ctx: Context): void;
-
-/**
- * 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;
-interface CoercionResult {
-    value: unknown;
-    /** True when at least one leaf was rewritten. */
-    changed: boolean;
-}
-/**
- * Best-effort, lossless coercion of a value toward a JSON Schema. Models —
- * especially through OpenAI-compatible proxies — frequently deliver
- * arguments with the right *content* in the wrong *type*: numbers and
- * booleans encoded as strings ("5", "true"), scalars where a string is
- * expected, or a whole nested object serialized into a JSON string.
- *
- * Only conversions that cannot lose information are applied:
- *   - string → number/integer when the whole trimmed string parses cleanly
- *   - string "true"/"false" → boolean
- *   - number/boolean → string when a string is expected
- *   - JSON-serialized string → object/array when the parse yields that shape
- * Recurses into `properties`/`items`. Returns the (possibly new) value and
- * whether anything changed — callers should re-validate before trusting it.
- */
-declare function coerceAgainstSchema(value: unknown, schema: JSONSchema): CoercionResult;
-
-/**
- * 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 CompileFail {
-    ok: false;
-    reason: string;
-}
-declare function compileUserRegex(pattern: string, flags: string): CompileResult | CompileFail;
-
-interface SafeParseResult<T> {
-    ok: boolean;
-    value?: T | undefined;
-    error?: string | undefined;
-}
-declare function safeParse<T = unknown>(input: string, maxBytes?: number): SafeParseResult<T>;
-declare function safeStringify(value: unknown, pretty?: boolean): string;
-/**
- * Attempt to parse JSON5-style input and return a valid JSON string.
- * Handles trailing commas, single-line comments, and unquoted keys
- * that are common in provider output.
- *
- * Returns the sanitized string if it parses successfully as JSON,
- * or `null` if the input cannot be made valid. Callers use this to
- * decide whether to proceed with the parsed result or fall back to
- * raw handling.
- */
-declare function sanitizeJsonString(s: string): string | null;
-/**
- * Strip a Markdown code-fence wrapper from a payload.
- *
- * Models occasionally return tool-call arguments wrapped in ```json fences
- * (or embedded in prose around one) instead of bare JSON. Returns the inner
- * content when the input starts with a fence (closing fence optional, so a
- * truncated stream still unwraps) or contains one complete fenced block;
- * returns null when no fence is present. Callers should only invoke this
- * after a direct parse failed, so fences inside legitimate string values are
- * never touched.
- */
-declare function stripCodeFences(s: string): string | null;
-
-/**
- * Resolve `<dir>/<sessionId><suffix>` for per-session sidecar files
- * (annotations, audit chain, replay log, the session JSONL itself).
- *
- * Modern session ids are date-sharded ("2026-06-11/sess_<ULID>"),
- * so a forward slash is a legitimate shard separator — NOT traversal.
- * Escape attempts are blocked two ways: an explicit ban on `..` and
- * backslashes, plus a resolved-path containment check that rejects any
- * id whose resolved target leaves `dir`. Character bans alone are how
- * several stores ended up throwing on every modern session id.
- */
-declare function sessionScopedPath(dir: string, sessionId: string, suffix: string): string;
-
-/**
- * Turn an arbitrary string into a filesystem- and URL-safe lowercase slug.
- *
- * Collapses every run of non-alphanumeric characters into a single hyphen,
- * trims leading/trailing hyphens, and caps the length. Returns `fallback`
- * when the input slugifies to the empty string.
- *
- * Used as the stable dedup + registry key for prompts. (Distinct from the
- * project-folder slug in `wstack-paths.ts`, which has its own `'project'`
- * fallback and shorter cap.)
- */
-declare function slugify(name: string, fallback?: string, maxLen?: number): string;
-
-/**
- * Generate a ULID — a 26-char Crockford-base32 identifier whose first 10 chars
- * encode the millisecond timestamp (so IDs sort lexicographically by creation
- * time) followed by 16 chars of randomness. Zero runtime dependencies.
- *
- * The codebase convention is "IDs are ULIDs"; use this for any new store key.
- */
-declare function ulid(seedTime?: number): string;
-/** True for a well-formed 26-char Crockford-base32 ULID. */
-declare function isUlid(value: string): boolean;
-
-/** 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>;
-
-/**
- * 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
- * running against a real terminal?". Replaces ad-hoc `process.stdin.isTTY`
- * / `process.stdout.isTTY` checks scattered across the codebase so that:
- *
- *   1. test code can mock a single module instead of stubbing `isTTY` on
- *      every ReadStream/WriteStream the test happens to touch;
- *   2. a future TTY-detection source (an env var override, a Windows
- *      ConPTY workaround, …) lands in one place;
- *   3. `isInteractive()` encodes the rule the project already used inline
- *      ("both streams are TTYs AND we're not running under CI") in one
- *      testable helper instead of the same 3-condition check in two
- *      different files.
- *
- * Scope: detection only. Raw-mode control (`setRawMode`), resize
- * subscriptions, and write-injection belong to a future, larger TTY
- * abstraction; this module is the smallest pull that gives us a
- * testable seam and dedups 20+ call sites.
- */
-/** True when `process.stdout` is attached to a terminal (not a pipe/file). */
-declare function isStdoutTTY(): boolean;
-/** True when `process.stdin` is attached to a terminal (not a pipe/file). */
-declare function isStdinTTY(): boolean;
-/**
- * True when the current process is an interactive session: both stdin and
- * stdout are TTYs. Callers that also need a "not a single-shot invocation"
- * or "not under CI" check should layer that on top — keeping this helper
- * minimal preserves the original inline checks it replaces.
- */
-declare function isInteractive(): boolean;
-/** Current terminal size in characters, with a 24×80 fallback for non-TTYs. */
-declare function getTermSize(): {
-    rows: number;
-    cols: number;
-};
-/**
- * Subscribe to terminal resize events. `cb` is called with the new size each
- * time the underlying stream emits `resize`. Returns a cleanup function the
- * caller MUST call on dispose to remove the listener — leaving a stale
- * `resize` listener on a disposed component leaks the closure (and the
- * component itself, transitively) until the process exits.
- *
- * The stream argument defaults to `process.stdout`. Pass an explicit
- * `NodeJS.WriteStream` when the caller already owns one (e.g. a status line
- * that targets an injected `out` for testability). For non-TTY streams no
- * listener is registered and the returned cleanup is a no-op.
- */
-declare function onResize(cb: (size: {
-    rows: number;
-    cols: number;
-}) => void, stream?: NodeJS.WriteStream): () => void;
-/**
- * Toggle raw mode on a TTY stdin stream. Returns `true` when the toggle was
- * applied, `false` when the stream is null, not a TTY, or doesn't expose
- * `setRawMode` (pipes, file descriptors, Windows ConPTY edge cases). Callers
- * that need to restore the previous mode should snapshot `input.isRaw`
- * BEFORE the call and pass the value to a second call to flip back.
- *
- * Use this helper to drop the now-redundant
- * `if (input.isTTY) input.setRawMode(...)` ceremony at every call site.
- */
-declare function setRawMode(input: NodeJS.ReadStream, mode: boolean): boolean;
-/**
- * Bracket installed by the interactive input reader while a `readline`
- * prompt is on screen. Out-of-band terminal writes — logger WARN/INFO
- * lines, async activity from the Telegram bridge, etc. — go to the same
- * physical terminal as the half-typed prompt but readline has no idea they
- * happened, so it never repaints. The result is the classic corruption the
- * user sees: every async line strands the in-progress draft as a fresh
- * scrollback row (sometimes with its cursor underline).
- *
- * The guard closes that gap. `suspend()` wipes the draft row so the message
- * prints clean; `resume()` repaints the prompt + draft (cursor preserved).
- * 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;
-/**
- * True when the todos list still has at least one unfinished item — either
- * `pending` (not started) or `in_progress` (underway). The REPL and other
- * post-turn handlers call this to decide whether to surface `<nextsteps>`
- * suggestions to the user: as long as the agent has open todos, finishing
- * them takes priority over offering new prompt options. Surfacing
- * `<nextsteps>` mid-task is what causes YOLO+auto mode and the autonomy
- * 'auto' loop to prematurely pivot away from the in-flight todo list.
- *
- * Returns false for an empty / undefined list (nothing pending, nothing to
- * block on) and false for an all-completed list. Treats any non-array input
- * (legacy contexts, mocks) as "no todos" rather than throwing.
- */
-declare function hasOpenTodos(todos: readonly TodoItem[] | undefined | null): boolean;
-
-declare function escapeGlobSubject(value: string): string;
-declare function normalizePathSubject(value: string): string;
-declare function isPathSubjectKey(subjectKey: string): boolean;
-declare function subjectForToolInput(toolName: string, input: unknown, subjectKey?: string): string | undefined;
-
-/**
- * Tool output serialization utilities.
- * Extracted from Agent.executeTools to allow reuse and consistent output handling.
- */
-interface ToolOutputSerializerOptions {
-    perIterationOutputCapBytes?: number | undefined;
-    estimator?: ((text: string) => number) | undefined;
-}
-interface ToolOutputSerializeContext {
-    toolName?: string | undefined;
-    input?: unknown;
-    /**
-     * Optional reference to the Tool object. When present and the tool defines
-     * a `serialize()` method, the serializer delegates to it instead of the
-     * central `renderToolObject()` switch (P3 #21).
-     */
-    tool?: {
-        serialize?: (output: unknown, input: unknown) => string;
-    } | undefined;
-}
-declare function createToolOutputSerializer(opts?: ToolOutputSerializerOptions): {
-    serialize: (value: unknown, context?: ToolOutputSerializeContext) => string;
-    enforceCap: (text: string, remainingBudget: number) => {
-        text: string;
-        newBudget: number;
-    };
-    capBytes: number;
-};
-
-declare const DEFAULT_TOOL_DESCRIPTION_MODE: ToolDescriptionMode;
-interface ToolDescriptionRegistryLike {
-    get(name: string): Tool | undefined;
-    list(): Tool[];
-    wrap?(name: string, wrapper: (tool: Tool) => Tool, owner?: string): void;
-    setDescriptionMode?(name: string, mode: ToolDescriptionMode): boolean;
-    applyDescriptionModes?(modes?: ToolDescriptionModeConfig): {
-        applied: number;
-        missing: string[];
-    };
-    getDescriptionMode?(name: string): ToolDescriptionMode;
-}
-declare function normalizeToolDescriptionMode(value: unknown): ToolDescriptionMode | undefined;
-declare function resolveToolDescriptionMode(modes: ToolDescriptionModeConfig | undefined, toolName: string): ToolDescriptionMode;
-declare function simplifyToolDescription(text: string, opts?: {
-    maxSentences?: number | undefined;
-    maxChars?: number | undefined;
-}): string;
-declare function applyToolDescriptionModeToTool(tool: Tool, mode: ToolDescriptionMode): Tool;
-declare function setToolDescriptionMode(registry: ToolDescriptionRegistryLike, name: string, mode: ToolDescriptionMode): boolean;
-declare function getToolDescriptionMode(registry: ToolDescriptionRegistryLike, name: string): ToolDescriptionMode;
-declare function applyToolDescriptionModes(registry: ToolDescriptionRegistryLike, modes?: ToolDescriptionModeConfig): {
-    applied: number;
-    missing: string[];
-};
-
-declare const DEFAULT_TOOL_RESULT_RENDER_MODE: ToolResultRenderMode;
-/**
- * Normalize a raw value to a {@link ToolResultRenderMode}. Accepts the
- * canonical strings (`'extend' | 'simple'`) plus a few synonyms so the
- * slash command feels forgiving (`extended`/`full` → `extend`,
- * `short`/`brief` → `simple`). Returns `undefined` for anything else so
- * the caller can reject unknown input without throwing.
- */
-declare function normalizeToolResultRenderMode(value: unknown): ToolResultRenderMode | undefined;
-/**
- * Look up the result-render mode for `toolName` from a config map. Falls
- * back to the default `'extend'` when the map is missing the entry.
- */
-declare function resolveToolResultRenderMode(modes: ToolResultRenderModeConfig | undefined, toolName: string): ToolResultRenderMode;
-/**
- * Subset of {@link import('../registry/tool-registry.js').ToolRegistry}
- * the result-render-mode setters need. Decouples this module from the
- * concrete registry class so it can be reused by tests and by tools
- * that wrap their own registry.
- */
-interface ToolResultRenderModeRegistryLike {
-    get(name: string): Tool | undefined;
-    setResultRenderMode?(name: string, mode: ToolResultRenderMode): boolean;
-    applyResultRenderModes?(modes?: ToolResultRenderModeConfig): {
-        applied: number;
-        missing: string[];
-    };
-    getResultRenderMode?(name: string): ToolResultRenderMode;
-}
-/**
- * Set a single tool's result-render mode on a registry. Prefers the
- * registry's native accessor (so it can update any internal state, e.g.
- * usage caches); falls back to a no-op so callers stay decoupled from
- * the registry implementation.
- */
-declare function setToolResultRenderMode(registry: ToolResultRenderModeRegistryLike, name: string, mode: ToolResultRenderMode): boolean;
-/**
- * Look up the current result-render mode for a single tool. Returns the
- * registry's view if it has one, otherwise the default. This is what the
- * tool-executor calls on each tool invocation to decide whether the next
- * `writeToolResult` should be `simple` or `extend`.
- */
-declare function getToolResultRenderMode(registry: ToolResultRenderModeRegistryLike, name: string): ToolResultRenderMode;
-/**
- * Bulk-apply a config map (`tools.resultRenderMode`) to a registry.
- * Mirrors {@link import('./tool-description-mode.js').applyToolDescriptionModes}
- * for symmetry with the LLM-side description mode.
- */
-declare function applyToolResultRenderModes(registry: ToolResultRenderModeRegistryLike, modes?: ToolResultRenderModeConfig): {
-    applied: number;
-    missing: string[];
-};
-
-interface ToolWireDefinitionLike {
-    name: string;
-    description?: string | undefined;
-    inputSchema: unknown;
-}
-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>;
-}
-/**
- * Return the provider-wire version of a tool definition.
- *
- * 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 compactToolDefinitionForWire(tool: ToolWireDefinitionLike, opts?: CompactToolDefinitionForWireOptions): CompactWireToolDefinition;
-declare function compactSchemaDescriptions(schema: unknown, maxDescriptionChars?: number): Record<string, unknown>;
-
-export { type AtomicWriteOptions, type BuildChildEnvOptions, COMPLETED_WORK_LEDGER_MARKER, type CoercionResult, type CompactToolDefinitionForWireOptions, type CompactWireToolDefinition, type CompileFail, type CompileResult, DEFAULT_TOOL_DESCRIPTION_MODE, DEFAULT_TOOL_RESULT_RENDER_MODE, type DeepMergeOptions, FORBIDDEN_PROTO_KEYS, type FileLockOptions, type JsonObject, type JsonPath, type JsonPathSegment, type MessageRepairReport, type MessageRepairResult, type NewlineStyle, type OutputLineGuard, type RecordCompletedWorkInput, type RecordToolOutputEvidenceInput, type RequestTokenBreakdown, type SafeParseResult, type ToolDescriptionRegistryLike, type ToolOutputSerializerOptions, type ToolResultRenderModeRegistryLike, type ToolWireDefinitionLike, type UnifiedDiffOptions, type ValidationError, type ValidationResult, applyToolDescriptionModeToTool, applyToolDescriptionModes, applyToolResultRenderModes, assertNever, assertNotPrivateHost, atomicWrite, buildChildEnv, buildCompletedWorkLedgerBlock, buildContextEvidenceDigest, coerceAgainstSchema, color, compactSchemaDescriptions, compactToolDefinitionForWire, compileGlob, compileUserRegex, completePartialObject, computeMessageTokens, createContextEvidenceState, createToolOutputSerializer, deepMerge, detectNewlineStyle, ensureDir, escapeGlobSubject, estimateMessageTokens, estimateRequestTokens, estimateRequestTokensCalibrated, estimateTextTokens, estimateToolDefTokens, estimateToolInputTokens, estimateToolResultTokens, expandGlob, expandIPv6, formatCompletedWorkLedger, formatTodosList, getCalibrationState, getJsonPath, getTermSize, getToolDescriptionMode, getToolResultRenderMode, hasOpenTodos, isInteractive, isJsonObject, isPathSubjectKey, isPrimitiveArray, isPrivateIPv4, isPrivateIPv6, isStdinTTY, isStdoutTTY, isUlid, jsonObjectFileExists, markAssistantReferencedEvidence, matchAny, matchGlob, mergeCustomModelDefs, mergeModelsPayload, normalizePathSubject, normalizeToLf, normalizeToolDescriptionMode, normalizeToolResultRenderMode, onResize, readJsonObjectFile, recordActualUsage, recordCompletedWorkEvidence, recordToolOutputEvidence, recordUserIntentEvidence, removeJsonPath, removeJsonPathInFile, repairToolUseAdjacency, repeatedReadPressure, resetCalibration, resolveToolDescriptionMode, resolveToolResultRenderMode, safeParse, safeStringify, sanitizeJsonString, sanitizeNodeOptions, sessionScopedPath, setJsonPath, setJsonPathInFile, setOutputLineGuard, setRawMode, setToolDescriptionMode, setToolResultRenderMode, simplifyToolDescription, sleep, slugify, stripAnsi, stripCodeFences, subjectForToolInput, syncCompletedWorkLedgerBlock, toStyle, truncate, ulid, unifiedDiff, updateJsonObjectFile, validateAgainstSchema, withFileLock, writeErr, writeJsonObjectFile, writeOut };
+export * from './expect-defined.js';
+export { expandGlob } from './glob-expand.js';
+export * from './glob-match.js';
+export { assertNotPrivateHost, expandIPv6, isPrivateIPv4, isPrivateIPv6 } from './ip-guard.js';
+export { completePartialObject } from './json-repair.js';
+export { type CoercionResult, type ValidationError, type ValidationResult, coerceAgainstSchema, validateAgainstSchema, } from './json-schema-validate.js';
+export { mergeCustomModelDefs } from './merge-custom-models.js';
+export { mergeModelsPayload } from './merge-models-payload.js';
+export { type MessageRepairReport, type MessageRepairResult, repairToolUseAdjacency, } from './message-invariants.js';
+export * from './newline-normalize.js';
+export { type CompileFail, type CompileResult, compileUserRegex } from './regex-guard.js';
+export * from './safe-json.js';
+export { sessionScopedPath } from './session-scoped-path.js';
+export { slugify } from './slug.js';
+export { ulid, isUlid } from './ulid.js';
+export * from './sleep.js';
+export * from './string.js';
+export * from './task-format.js';
+export * from './term.js';
+export * from './todos-format.js';
+export * from './tool-subject.js';
+export { computeMessageTokens, estimateMessageTokens, estimateRequestTokens, estimateRequestTokensCalibrated, estimateTextTokens, estimateToolDefTokens, estimateToolInputTokens, estimateToolResultTokens, getCalibrationState, type RequestTokenBreakdown, recordActualUsage, resetCalibration, } from './token-estimate.js';
+export { createToolOutputSerializer, type ToolOutputSerializerOptions, } from './tool-output-serializer.js';
+export { DEFAULT_TOOL_DESCRIPTION_MODE, applyToolDescriptionModeToTool, applyToolDescriptionModes, getToolDescriptionMode, normalizeToolDescriptionMode, resolveToolDescriptionMode, setToolDescriptionMode, simplifyToolDescription, type ToolDescriptionRegistryLike, } from './tool-description-mode.js';
+export { DEFAULT_TOOL_RESULT_RENDER_MODE, applyToolResultRenderModes, getToolResultRenderMode, normalizeToolResultRenderMode, resolveToolResultRenderMode, setToolResultRenderMode, type ToolResultRenderModeRegistryLike, } from './tool-result-render-mode.js';
+export { type CompactToolDefinitionForWireOptions, type CompactWireToolDefinition, compactSchemaDescriptions, compactToolDefinitionForWire, type ToolWireDefinitionLike, } from './tool-wire-compact.js';
+export * from './wstack-paths.js';
+//# sourceMappingURL=index.d.ts.map