@mono-agent/agent-runtime 0.4.0 → 0.5.0

package/types/agent/tools/pi-bridge.d.ts

@@ -0,0 +1,144 @@
+/**
+ * @param {any} _serverName
+ * @param {any} toolName
+ * @param {any} params
+ * @param {{qaOutputDir?: any, ctx?: any}} [options]
+ */
+export function normalizeMcpToolParams(_serverName: any, toolName: any, params: any, { qaOutputDir, ctx }?: {
+    qaOutputDir?: any;
+    ctx?: any;
+}): any;
+/**
+ * @param {any} name
+ * @param {any} params
+ * @param {{cwd?: any, toolLimits?: any, ctx?: any}} [options]
+ */
+export function normalizePiBuiltinToolParams(name: any, params: any, { cwd, toolLimits, ctx }?: {
+    cwd?: any;
+    toolLimits?: any;
+    ctx?: any;
+}): any;
+export function createStructuredOutputTool(outputSchema: any, onStructuredOutput: any): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Type.TUnsafe<unknown>;
+    executionMode: string;
+    execute(_toolCallId: any, params: any): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        details: any;
+        terminate: boolean;
+    }>;
+};
+/**
+ * @param {any} allowedTools
+ * @param {{skillNames?: any[], skills?: any[], skillsRoot?: any, dataDir?: any, cwd?: any, onEvent?: (event: any) => void, toolLimits?: any, persistArtifact?: any, onTruncate?: any, toolPayloadMaxBytes?: number, imageInlineMaxBytes?: any, toolPolicy?: any, sandboxPolicy?: any, sandboxEngine?: any, approvalManager?: any, approvalModel?: any, ctx?: any}} [options]
+ */
+export function getPiBuiltinTools(allowedTools: any, { skillNames, skills, skillsRoot, dataDir, cwd, onEvent, toolLimits, persistArtifact, onTruncate, toolPayloadMaxBytes, imageInlineMaxBytes, toolPolicy, sandboxPolicy, sandboxEngine, approvalManager, approvalModel, ctx, }?: {
+    skillNames?: any[];
+    skills?: any[];
+    skillsRoot?: any;
+    dataDir?: any;
+    cwd?: any;
+    onEvent?: (event: any) => void;
+    toolLimits?: any;
+    persistArtifact?: any;
+    onTruncate?: any;
+    toolPayloadMaxBytes?: number;
+    imageInlineMaxBytes?: any;
+    toolPolicy?: any;
+    sandboxPolicy?: any;
+    sandboxEngine?: any;
+    approvalManager?: any;
+    approvalModel?: any;
+    ctx?: any;
+}): any[];
+export function resolveMcpStdioCwd(cfg?: {}, cwd?: any): any;
+export function prepareMcpStdioCommand(cfg?: {}, { cwd, sandboxPolicy, sandboxEngine, ctx }?: {
+    cwd?: any;
+    sandboxPolicy?: any;
+    sandboxEngine?: any;
+    ctx?: any;
+}): Promise<any>;
+export function coerceMcpContent(out: any, { textLimit, imageInlineMaxBytes, persistArtifact, toolName, toolUseId, onTruncate, }?: {
+    textLimit?: number;
+    imageInlineMaxBytes?: number;
+    persistArtifact?: any;
+    toolName?: string;
+    toolUseId?: any;
+    onTruncate?: any;
+}): any;
+/**
+ * @param {any} mcpConfig
+ * @param {Set<any>} [reservedNames]
+ * @param {{limits?: any, cwd?: any, persistArtifact?: any, qaOutputDir?: any, onTruncate?: any, toolPayloadMaxBytes?: number, sandboxPolicy?: any, sandboxEngine?: any, onToolProgress?: any, ctx?: any}} [options]
+ */
+export function initPiMcpTools(mcpConfig: any, reservedNames?: Set<any>, { limits, cwd, persistArtifact, qaOutputDir, onTruncate, toolPayloadMaxBytes, sandboxPolicy, sandboxEngine, onToolProgress, ctx, }?: {
+    limits?: any;
+    cwd?: any;
+    persistArtifact?: any;
+    qaOutputDir?: any;
+    onTruncate?: any;
+    toolPayloadMaxBytes?: number;
+    sandboxPolicy?: any;
+    sandboxEngine?: any;
+    onToolProgress?: any;
+    ctx?: any;
+}): Promise<{
+    clients: {
+        name: any;
+        client: McpClient<{
+            method: string;
+            params?: {
+                [x: string]: unknown;
+                _meta?: {
+                    [x: string]: unknown;
+                    progressToken?: string | number;
+                    "io.modelcontextprotocol/related-task"?: {
+                        taskId: string;
+                    };
+                };
+            };
+        }, {
+            method: string;
+            params?: {
+                [x: string]: unknown;
+                _meta?: {
+                    [x: string]: unknown;
+                    progressToken?: string | number;
+                    "io.modelcontextprotocol/related-task"?: {
+                        taskId: string;
+                    };
+                };
+            };
+        }, {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                };
+            };
+        }>;
+        transport: StreamableHTTPClientTransport | SSEClientTransport | StdioClientTransport;
+    }[];
+    tools: any[];
+    warnings: {
+        type: string;
+        warning_kind: string;
+        server: string;
+        message: any;
+    }[];
+}>;
+export function closePiMcpClients(clients: any, { timeoutMs }?: {
+    timeoutMs?: number;
+}): Promise<void>;
+import { Type } from "@earendil-works/pi-ai";
+import { Client as McpClient } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

package/types/agent/tools/read.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @param {{file_path: string, offset?: number, start_line?: number, limit?: number, max_output_chars?: number, workdir?: string}} params
+ * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ */
+export function readToolImpl({ file_path, offset, start_line, limit, max_output_chars, workdir }: {
+    file_path: string;
+    offset?: number;
+    start_line?: number;
+    limit?: number;
+    max_output_chars?: number;
+    workdir?: string;
+}, { sandboxPolicy, ctx }?: {
+    sandboxPolicy?: any;
+    ctx?: any;
+}): Promise<string | {
+    kind: string;
+    data: string;
+    mimeType: any;
+}>;

package/types/agent/tools/shared/constants.d.ts

@@ -0,0 +1,13 @@
+export const DEFAULT_READ_LINES: 240;
+export const MAX_READ_LINES: 500;
+export const MAX_READ_LINE_CHARS: 2000;
+export const DEFAULT_MAX_READ_CHARS: 16000;
+export const DEFAULT_MAX_TOOL_OUTPUT_CHARS: 16000;
+export const DEFAULT_MAX_BASH_OUTPUT_CHARS: 20000;
+export const MAX_WRITE_BYTES: number;
+export const DEFAULT_EXCLUDED_DIRS: string[];
+export const DEFAULT_EXCLUDED_FILES: string[];
+export const DEFAULT_MAX_SEARCH_LINES: 100;
+export const DEFAULT_MAX_SEARCH_CHARS: 16000;
+export const SEARCH_MAX_BUFFER: number;
+export const READ_HISTORY_LIMIT: 200;

package/types/agent/tools/shared/dedup.d.ts

@@ -0,0 +1,8 @@
+export function boundedInt(value: any, fallback: any, { min, max }?: {
+    min?: number;
+    max?: number;
+}): any;
+export function safeStat(path: any): import("fs").Stats;
+export function rememberRead(target: any, start: any, count: any): boolean;
+export function trimLine(line: any): string;
+export const readHistory: Map<any, any>;

package/types/agent/tools/shared/output-truncation.d.ts

@@ -0,0 +1,22 @@
+export function writeToolArtifact(label: any, text: any, ctx: any): {
+    path: string;
+    bytes: number;
+};
+export function truncationSuffix({ label, shown, total, artifact, hint }: {
+    label: any;
+    shown: any;
+    total: any;
+    artifact: any;
+    hint: any;
+}): string;
+/**
+ * @param {string} text
+ * @param {{label?: string, maxChars?: number, strategy?: string, hint?: string, ctx?: any}} [options]
+ */
+export function capChars(text: string, { label, maxChars, strategy, hint, ctx, }?: {
+    label?: string;
+    maxChars?: number;
+    strategy?: string;
+    hint?: string;
+    ctx?: any;
+}): string;

package/types/agent/tools/shared/path-resolver.d.ts

@@ -0,0 +1,6 @@
+export function workspaceRoot(workdir: any, ctx: any): string;
+export function resolveToolPath(path: any, workdir: any, ctx: any): any;
+export function isPathAllowed(path: any, workdir: any, options?: {}): boolean;
+export function isWritablePathAllowed(path: any, workdir: any, options?: {}): boolean;
+export function isWorkdirAllowed(workdir: any, options?: {}): boolean;
+export function isInsidePath(root: any, target: any): boolean;

package/types/agent/tools/shared/ripgrep.d.ts

@@ -0,0 +1,38 @@
+export function ripgrepMissingMessage(ctx: any): string;
+/**
+ * @param {{refresh?: boolean, ctx?: any}} [options]
+ */
+export function resolveRgPath({ refresh, ctx }?: {
+    refresh?: boolean;
+    ctx?: any;
+}): any;
+export function excludedGlobArgs(): string[];
+export function normalizeGlobPattern(pattern: any): string;
+/**
+ * @param {any} rawLines
+ * @param {{label?: string, noMatches?: string, maxLines?: number, maxChars?: number, offset?: number, ctx?: any}} [options]
+ */
+export function formatSearchLines(rawLines: any, { label, noMatches, maxLines, maxChars, offset, ctx, }?: {
+    label?: string;
+    noMatches?: string;
+    maxLines?: number;
+    maxChars?: number;
+    offset?: number;
+    ctx?: any;
+}): string;
+/**
+ * @param {string} text
+ * @param {{label?: string, noMatches?: string, maxLines?: number, maxChars?: number, offset?: number, ctx?: any}} [options]
+ */
+export function capLines(text: string, { label, noMatches, maxLines, maxChars, offset, ctx, }?: {
+    label?: string;
+    noMatches?: string;
+    maxLines?: number;
+    maxChars?: number;
+    offset?: number;
+    ctx?: any;
+}): string;
+export function excludedPathSummary(): string;
+export namespace cachedRgPath {
+    let value: any;
+}

package/types/agent/tools/shared/runtime-context.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @param {Partial<ToolContext>} [next]
+ * @returns {void}
+ */
+export function configureToolRuntime(next?: Partial<ToolContext>): void;
+/**
+ * @returns {ToolContext}
+ */
+export function readToolRuntime(): ToolContext;
+/**
+ * @param {import('../../sandbox-seam.js').SandboxPolicy} [requestPolicy]
+ * @returns {import('../../sandbox-seam.js').SandboxPolicy|undefined}
+ */
+export function resolveSandboxPolicy(requestPolicy?: import("../../sandbox-seam.js").SandboxPolicy): import("../../sandbox-seam.js").SandboxPolicy | undefined;
+/**
+ * @returns {import('../../../runtime-brand.js').RuntimeBrand}
+ */
+export function readRuntimeBrand(): import("../../../runtime-brand.js").RuntimeBrand;
+/**
+ * @returns {void}
+ */
+export function resetToolRuntime(): void;
+export type ToolContext = import("./tool-context.js").ToolContext;
+/**
+ * Back-compat alias for the historical name.
+ */
+export type ToolRuntimeContext = ToolContext;

package/types/agent/tools/shared/tool-context.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Build a fresh ToolContext from a partial input. `runtimeBrand` is always
+ * resolved (to the defaults when absent); the remaining keys default to
+ * undefined and are copied from `input` when present.
+ * @param {Partial<ToolContext>} [input]
+ * @returns {ToolContext}
+ */
+export function createToolContext(input?: Partial<ToolContext>): ToolContext;
+/**
+ * Mutate an existing ToolContext in place with the keys present on `next`,
+ * leaving untouched keys as-is. Mutating in place (rather than returning a
+ * copy) is deliberate: `createRuntime` threads a single context object to its
+ * bridges and `configureTools` updates that same reference so subsequent runs
+ * observe the change — the instance-scoped equivalent of the old global
+ * configureToolRuntime.
+ * @param {ToolContext} ctx
+ * @param {Partial<ToolContext>} [next]
+ * @returns {ToolContext}
+ */
+export function updateToolContext(ctx: ToolContext, next?: Partial<ToolContext>): ToolContext;
+/**
+ * Reset every data key to undefined and the brand back to the defaults.
+ * @param {ToolContext} ctx
+ * @returns {ToolContext}
+ */
+export function resetToolContext(ctx: ToolContext): ToolContext;
+/**
+ * @param {ToolContext|undefined} ctx
+ * @param {SandboxPolicy} [requestPolicy]
+ * @returns {SandboxPolicy|undefined}
+ */
+export function resolveSandboxPolicy(ctx: ToolContext | undefined, requestPolicy?: SandboxPolicy): SandboxPolicy | undefined;
+export type RuntimeBrand = import("../../../runtime-brand.js").RuntimeBrand;
+export type SandboxPolicy = import("../../sandbox-seam.js").SandboxPolicy;
+export type RuntimeSandboxEngine = import("../../sandbox-seam.js").RuntimeSandboxEngine;
+export type RuntimeSandbox = import("../../sandbox-seam.js").RuntimeSandbox;
+export type ToolContext = {
+    workspace?: string;
+    repoRoot?: string;
+    runId?: string;
+    toolArtifactDir?: string;
+    ripgrepPath?: string;
+    qaOutputDir?: string;
+    sandboxPolicy?: SandboxPolicy;
+    sandboxEngine?: RuntimeSandboxEngine;
+    sandbox: RuntimeSandbox;
+    runtimeBrand: RuntimeBrand;
+};

package/types/agent/tools/web-fetch.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @param {{url: string, headers?: Record<string, string>, max_output_chars?: number}} params
+ * @param {{sandboxPolicy?: any, ctx?: any, retryDelaysMs?: number[]}} [options]
+ */
+export function webFetchToolImpl({ url, headers, max_output_chars }: {
+    url: string;
+    headers?: Record<string, string>;
+    max_output_chars?: number;
+}, { sandboxPolicy, ctx, retryDelaysMs }?: {
+    sandboxPolicy?: any;
+    ctx?: any;
+    retryDelaysMs?: number[];
+}): Promise<string>;

package/types/agent/tools/web-search.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @param {{query: string, limit?: number}} params
+ * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ */
+export function webSearchToolImpl({ query, limit }: {
+    query: string;
+    limit?: number;
+}, { sandboxPolicy, ctx }?: {
+    sandboxPolicy?: any;
+    ctx?: any;
+}): Promise<string>;

package/types/agent/tools/write.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @param {{file_path: string, content?: string, workdir?: string}} params
+ * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ */
+export function writeToolImpl({ file_path, content, workdir }: {
+    file_path: string;
+    content?: string;
+    workdir?: string;
+}, { sandboxPolicy, ctx }?: {
+    sandboxPolicy?: any;
+    ctx?: any;
+}): Promise<string>;

package/types/agent/transcript.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @param {Array<*>} events
+ * @param {Object} [options]
+ * @param {number} [options.maxTurns]
+ * @param {number} [options.verbatimTurns]
+ * @param {number} [options.maxChars]
+ * @param {number} [options.toolResultChars]
+ * @param {number} [options.assistantTextChars]
+ * @param {number} [options.turnSummaryChars]
+ * @param {import('../runtime-brand.js').RuntimeBrand} [options.runtimeBrand]
+ */
+export function buildTranscriptTailSnapshot(events: Array<any>, { maxTurns, verbatimTurns, maxChars, toolResultChars, assistantTextChars, turnSummaryChars, runtimeBrand, }?: {
+    maxTurns?: number;
+    verbatimTurns?: number;
+    maxChars?: number;
+    toolResultChars?: number;
+    assistantTextChars?: number;
+    turnSummaryChars?: number;
+    runtimeBrand?: import("../runtime-brand.js").RuntimeBrand;
+}): {
+    schema: string;
+    captured_at: number;
+    turn_count: number;
+    earlier_turn_summaries: {
+        turn_index: number;
+        summary: string;
+    }[];
+    turns: any[];
+};
+export function renderResumeSnapshot(snapshot: any): string;
+export namespace RESUME_SNAPSHOT_DEFAULTS {
+    export { DEFAULT_MAX_TURNS as maxTurns };
+    export { DEFAULT_VERBATIM_TURNS as verbatimTurns };
+    export { DEFAULT_MAX_CHARS as maxChars };
+    export { DEFAULT_TOOL_RESULT_CHARS as toolResultChars };
+    export { DEFAULT_ASSISTANT_TEXT_CHARS as assistantTextChars };
+    export { DEFAULT_TURN_SUMMARY_CHARS as turnSummaryChars };
+}
+declare const DEFAULT_MAX_TURNS: 12;
+declare const DEFAULT_VERBATIM_TURNS: 3;
+declare const DEFAULT_MAX_CHARS: 24000;
+declare const DEFAULT_TOOL_RESULT_CHARS: 2400;
+declare const DEFAULT_ASSISTANT_TEXT_CHARS: 4000;
+declare const DEFAULT_TURN_SUMMARY_CHARS: 320;
+export {};

package/types/ai/backend.d.ts

@@ -0,0 +1,41 @@
+export function backendCapabilities(sdkOrModel: any): any;
+export function backendUsesExecenvConfig(sdk: any): boolean;
+export function backendSupportsSessionResume(sdk: any): boolean;
+export const BACKEND_CAPABILITIES: {
+    claude: {
+        supports_session_resume: boolean;
+        streaming: boolean;
+        structured_output: boolean;
+        native_runtime_config: any;
+        supports_mcp: boolean;
+        supports_skills: boolean;
+        supports_builtin_tools: boolean;
+        supports_live_input: boolean;
+        supports_native_subagents: boolean;
+        runtime: string;
+    };
+    pi: {
+        supports_session_resume: boolean;
+        supports_native_subagents: boolean;
+        streaming: boolean;
+        structured_output: boolean;
+        native_runtime_config: any;
+        supports_mcp: boolean;
+        supports_skills: boolean;
+        supports_builtin_tools: boolean;
+        supports_live_input: boolean;
+        runtime: string;
+    };
+    codex: {
+        supports_session_resume: boolean;
+        streaming: boolean;
+        structured_output: boolean;
+        native_runtime_config: any;
+        supports_mcp: boolean;
+        supports_skills: boolean;
+        supports_builtin_tools: boolean;
+        supports_live_input: boolean;
+        supports_native_subagents: boolean;
+        runtime: string;
+    };
+};

package/types/ai/cost.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @param {Object} [options]
+ * @param {(parsed: ParsedModelReference) => (NormalizedPricing|null)} [options.resolveCustomPricing]
+ * @param {string} [options.model]
+ * @returns {NormalizedPricing}
+ */
+export function resolvePricing({ resolveCustomPricing, model }?: {
+    resolveCustomPricing?: (parsed: ParsedModelReference) => (NormalizedPricing | null);
+    model?: string;
+}): NormalizedPricing;
+/**
+ * @param {Object} [options]
+ * @param {(parsed: ParsedModelReference) => (NormalizedPricing|null)} [options.resolveCustomPricing]
+ * @param {string} [options.model]
+ * @param {number} [options.inputTokens]
+ * @param {number} [options.outputTokens]
+ * @param {number} [options.cachedTokens]
+ * @param {number} [options.cacheWriteTokens]
+ * @param {number} [options.cacheCreationTokens]
+ * @returns {number|null}
+ */
+export function estimateCost({ resolveCustomPricing, model, inputTokens, outputTokens, cachedTokens, cacheWriteTokens, cacheCreationTokens, }?: {
+    resolveCustomPricing?: (parsed: ParsedModelReference) => (NormalizedPricing | null);
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedTokens?: number;
+    cacheWriteTokens?: number;
+    cacheCreationTokens?: number;
+}): number | null;
+export type ParsedModelReference = {
+    sdk: string | null;
+    provider?: string;
+    model: string;
+};
+export type NormalizedPricing = {
+    input: number | null;
+    cacheRead: number | null;
+    cacheWrite: number | null;
+    output: number | null;
+    source: string;
+    priced: boolean;
+};
+/**
+ * Duck-typed pricing row a host (or the pi catalog) supplies: either
+ * camelCase or the provider's `*_per_million` snake_case spelling.
+ */
+export type PricingInputRow = {
+    input?: number | string;
+    input_per_million?: number | string;
+    cacheRead?: number | string;
+    cachedInput?: number | string;
+    cached_input_per_million?: number | string;
+    cacheWrite?: number | string;
+    cache_write_per_million?: number | string;
+    cache_creation_per_million?: number | string;
+    output?: number | string;
+    output_per_million?: number | string;
+};
+/**
+ * @param {PricingInputRow|null|undefined} pricing
+ * @param {Object} [options]
+ * @param {string} [options.source]
+ * @param {boolean} [options.priced]
+ * @param {number} [options.missing]
+ * @returns {NormalizedPricing|null}
+ */
+export function normalizePricing(pricing: PricingInputRow | null | undefined, { source, priced, missing }?: {
+    source?: string;
+    priced?: boolean;
+    missing?: number;
+}): NormalizedPricing | null;
+/**
+ * @param {string} source
+ * @returns {NormalizedPricing}
+ */
+export function zeroPricing(source: string): NormalizedPricing;
+/**
+ * @returns {NormalizedPricing}
+ */
+export function unknownPricing(): NormalizedPricing;
+/**
+ * @param {PricingInputRow} [pricing]
+ * @returns {boolean}
+ */
+export function pricingHasRates(pricing?: PricingInputRow): boolean;
+/**
+ * @param {string} baseUrl
+ * @returns {boolean}
+ */
+export function isPrivateHost(baseUrl: string): boolean;
+/**
+ * @param {string} reference
+ * @returns {ParsedModelReference|null}
+ */
+export function parseReference(reference: string): ParsedModelReference | null;

package/types/ai/failure.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function isProviderAuthFailureText(text?: string): boolean;
+/**
+ * @param {Object} [options]
+ * @param {string} [options.errorText]
+ * @param {string} [options.stderrTail]
+ * @param {string|null} [options.failureKind]
+ * @returns {RetryableProviderFailureInfo}
+ */
+export function retryableProviderFailureInfo({ errorText, stderrTail, failureKind, }?: {
+    errorText?: string;
+    stderrTail?: string;
+    failureKind?: string | null;
+}): RetryableProviderFailureInfo;
+/**
+ * @param {Object} [options]
+ * @param {number|null} [options.exitCode]
+ * @param {string|null} [options.signal]
+ * @param {string} [options.errorText]
+ * @param {string} [options.stderrTail]
+ * @param {boolean} [options.timedOut]
+ * @param {boolean} [options.cancelRequested]
+ * @param {string|null} [options.cancelInitiator]
+ * @param {boolean} [options.resultParseError]
+ * @param {boolean} [options.mcpInitFailed]
+ * @param {boolean} [options.budgetExceeded]
+ * @param {boolean} [options.childFailed]
+ * @param {string|null} [options.hint]
+ * @returns {FailureKind|null} One of FAILURE_KINDS, or null for a clean exit.
+ */
+export function classifyFailure({ exitCode, signal, errorText, stderrTail, timedOut, cancelRequested, cancelInitiator, resultParseError, mcpInitFailed, budgetExceeded, childFailed, hint, }?: {
+    exitCode?: number | null;
+    signal?: string | null;
+    errorText?: string;
+    stderrTail?: string;
+    timedOut?: boolean;
+    cancelRequested?: boolean;
+    cancelInitiator?: string | null;
+    resultParseError?: boolean;
+    mcpInitFailed?: boolean;
+    budgetExceeded?: boolean;
+    childFailed?: boolean;
+    hint?: string | null;
+}): FailureKind | null;
+/**
+ * @param {Object} [options]
+ * @param {number} [options.limit]
+ * @returns {{push: (chunk: (string|Buffer|null|undefined)) => void, toString: () => string, readonly bytesDropped: number}}
+ */
+export function createStderrTail({ limit }?: {
+    limit?: number;
+}): {
+    push: (chunk: (string | Buffer | null | undefined)) => void;
+    toString: () => string;
+    readonly bytesDropped: number;
+};
+/**
+ * @typedef {Object} RetryableProviderFailureInfo
+ * @property {boolean} retryable
+ * @property {string|null} subkind
+ * @property {string|null} requestId
+ */
+/**
+ * @typedef {"spawn" | "timeout" | "stall" | "usage_limit" | "invalid_result"
+ *   | "invalid_delegation" | "tool_failure" | "provider_unavailable"
+ *   | "provider_unavailable_exhausted" | "provider_auth"
+ *   | "skipped_capability_mismatch" | "cancelled" | "cancelled_user"
+ *   | "cancelled_shutdown" | "cancelled_signal" | "abandoned"
+ *   | "session_not_found" | "session_busy" | (string & {})} FailureKind
+ * OPEN string union. The literals above are the CORE taxonomy the kernel itself
+ * derives from provider/runtime signals in `classifyFailure` /
+ * `retryableProviderFailureInfo` (and `provider_unavailable_exhausted`, produced
+ * by the router on chain exhaustion). The union is intentionally open
+ * (`string & {}`) because `FAILURE_KINDS` also transports HOST-TAXONOMY kinds
+ * the kernel never originates on its own:
+ *   - `child_failed`, `budget_exceeded` — `classifyFailure` only returns these
+ *     when the HOST passes the matching `childFailed` / `budgetExceeded` (or a
+ *     `cancelInitiator: "budget"`) input; the kernel never infers them from a
+ *     provider signal.
+ *   - `delegation_agent_not_in_team`, `delegation_team_roster_empty`,
+ *     `invalid_delegation`, `cancelled_stale` (`stale_reconcile`) — set by a
+ *     host coordinator (planner/roster/reconcile logic) and merely carried
+ *     through `FAILURE_KINDS` / the `hint` passthrough; the kernel transports
+ *     them in the result contract but never emits them from its own paths.
+ * Hosts (e.g. worklab's coordinator) validate against `FAILURE_KINDS` and may
+ * define additional kinds — accepting them at the type level is deliberate.
+ */
+export const FAILURE_KINDS: string[];
+export const PROVIDER_ABORT_RE: RegExp;
+export type RetryableProviderFailureInfo = {
+    retryable: boolean;
+    subkind: string | null;
+    requestId: string | null;
+};
+/**
+ * OPEN string union. The literals above are the CORE taxonomy the kernel itself
+ * derives from provider/runtime signals in `classifyFailure` /
+ * `retryableProviderFailureInfo` (and `provider_unavailable_exhausted`, produced
+ * by the router on chain exhaustion). The union is intentionally open
+ * (`string & {}`) because `FAILURE_KINDS` also transports HOST-TAXONOMY kinds
+ * the kernel never originates on its own:
+ * - `child_failed`, `budget_exceeded` — `classifyFailure` only returns these
+ *   when the HOST passes the matching `childFailed` / `budgetExceeded` (or a
+ *   `cancelInitiator: "budget"`) input; the kernel never infers them from a
+ *   provider signal.
+ * - `delegation_agent_not_in_team`, `delegation_team_roster_empty`,
+ *   `invalid_delegation`, `cancelled_stale` (`stale_reconcile`) — set by a
+ *   host coordinator (planner/roster/reconcile logic) and merely carried
+ *   through `FAILURE_KINDS` / the `hint` passthrough; the kernel transports
+ *   them in the result contract but never emits them from its own paths.
+ * Hosts (e.g. worklab's coordinator) validate against `FAILURE_KINDS` and may
+ * define additional kinds — accepting them at the type level is deliberate.
+ */
+export type FailureKind = "spawn" | "timeout" | "stall" | "usage_limit" | "invalid_result" | "invalid_delegation" | "tool_failure" | "provider_unavailable" | "provider_unavailable_exhausted" | "provider_auth" | "skipped_capability_mismatch" | "cancelled" | "cancelled_user" | "cancelled_shutdown" | "cancelled_signal" | "abandoned" | "session_not_found" | "session_busy" | (string & {});