@uncensoredcode/openbridge 0.1.0

package/packages/runtime/dist/packet-normalizer.js

@@ -0,0 +1,47 @@
+import { normalizersModule } from "./normalizers/index.js";
+const { normalizeGenericLegacyPacket } = normalizersModule;
+function normalizeProviderPacket(_providerId, extractedCandidate) {
+    const candidate = extractedCandidate.trim();
+    if (candidate.startsWith('<zc_packet version="1">')) {
+        const repairedCanonicalPacket = repairMalformedCanonicalPacket(candidate);
+        if (repairedCanonicalPacket) {
+            return {
+                ok: true,
+                strategy: "canonical_repaired_tool_call_close_tag",
+                canonicalPacket: repairedCanonicalPacket,
+                notes: ["Repaired a malformed canonical </tool_call> closing tag before strict parsing."]
+            };
+        }
+        return {
+            ok: true,
+            strategy: "canonical_passthrough",
+            canonicalPacket: candidate,
+            notes: ["Candidate already matched the canonical runtime packet format."]
+        };
+    }
+    const genericLegacyPacket = normalizeGenericLegacyPacket(candidate);
+    if (genericLegacyPacket) {
+        return genericLegacyPacket;
+    }
+    return {
+        ok: false,
+        strategy: "none",
+        code: "unsupported_provider_packet",
+        message: "Non-canonical packet content did not match the supported legacy packet format.",
+        notes: ["Only canonical passthrough and generic legacy packet normalization are available."]
+    };
+}
+function repairMalformedCanonicalPacket(candidate) {
+    const attributedOpenTagMatches = [...candidate.matchAll(/<tool_call\b[^>]+>/g)];
+    const closeTagMatches = [...candidate.matchAll(/<\/tool_call>/g)];
+    const hasTrailingBareOpenTag = /<tool_call>\s*<\/zc_packet>\s*$/u.test(candidate);
+    if (attributedOpenTagMatches.length !== 1 ||
+        closeTagMatches.length !== 0 ||
+        !hasTrailingBareOpenTag) {
+        return null;
+    }
+    return candidate.replace(/<tool_call>\s*<\/zc_packet>\s*$/u, "</tool_call></zc_packet>");
+}
+export const packetNormalizerModule = {
+    normalizeProviderPacket
+};

package/packages/runtime/dist/prompt-compiler.d.ts

@@ -0,0 +1,28 @@
+import type { ToolDefinition } from "./execution/types.ts";
+import type { ConversationState } from "./provider.ts";
+type CompiledProviderMessage = {
+    role: "system" | "user";
+    content: string;
+};
+type CompiledProviderTurn = {
+    messages: CompiledProviderMessage[];
+    summary: {
+        turnType: "initial" | "follow_up";
+        userMessage: string;
+        toolNames: string[];
+        toolResultCount: number;
+        sessionHistoryTurns: number;
+        replayedFromBridgeSession: boolean;
+    };
+};
+type CompileProviderTurnInput = {
+    conversation: ConversationState;
+    availableTools: ToolDefinition[];
+    runtimePlannerPrimed?: boolean;
+    forceReplay?: boolean;
+};
+declare function compileProviderTurn(input: CompileProviderTurnInput): CompiledProviderTurn;
+export declare const promptCompilerModule: {
+    compileProviderTurn: typeof compileProviderTurn;
+};
+export type { CompiledProviderMessage, CompiledProviderTurn, CompileProviderTurnInput };

package/packages/runtime/dist/prompt-compiler.js

@@ -0,0 +1,301 @@
+function compileProviderTurn(input) {
+    const userMessage = getUserMessage(input.conversation);
+    const toolResults = input.conversation.entries.filter((entry) => entry.type === "tool_result");
+    const toolNames = [...input.availableTools].map((tool) => tool.name).sort();
+    const sessionHistory = input.conversation.sessionHistory ?? [];
+    const shouldReplayBridgeSession = input.forceReplay === true ||
+        (sessionHistory.length > 0 && input.runtimePlannerPrimed !== true);
+    if (toolResults.length === 0) {
+        if (shouldReplayBridgeSession) {
+            return {
+                messages: [
+                    {
+                        role: "system",
+                        content: buildSystemPrompt(input.availableTools)
+                    },
+                    {
+                        role: "user",
+                        content: buildBridgeSessionReplayPrompt(sessionHistory, userMessage)
+                    }
+                ],
+                summary: {
+                    turnType: sessionHistory.length > 0 ? "follow_up" : "initial",
+                    userMessage,
+                    toolNames,
+                    toolResultCount: 0,
+                    sessionHistoryTurns: sessionHistory.length,
+                    replayedFromBridgeSession: true
+                }
+            };
+        }
+        const systemPrompt = input.runtimePlannerPrimed
+            ? buildCompactSystemPrompt(input.availableTools)
+            : buildSystemPrompt(input.availableTools);
+        return {
+            messages: [
+                {
+                    role: "system",
+                    content: systemPrompt
+                },
+                {
+                    role: "user",
+                    content: userMessage
+                }
+            ],
+            summary: {
+                turnType: "initial",
+                userMessage,
+                toolNames,
+                toolResultCount: 0,
+                sessionHistoryTurns: sessionHistory.length,
+                replayedFromBridgeSession: false
+            }
+        };
+    }
+    if (shouldReplayBridgeSession) {
+        return {
+            messages: [
+                {
+                    role: "system",
+                    content: buildSystemPrompt(input.availableTools)
+                },
+                {
+                    role: "user",
+                    content: buildBridgeSessionToolReplayPrompt(sessionHistory, userMessage, input.availableTools, toolResults)
+                }
+            ],
+            summary: {
+                turnType: "follow_up",
+                userMessage,
+                toolNames,
+                toolResultCount: toolResults.length,
+                sessionHistoryTurns: sessionHistory.length,
+                replayedFromBridgeSession: true
+            }
+        };
+    }
+    return {
+        messages: [
+            {
+                role: "user",
+                content: buildToolFollowUpPrompt(userMessage, input.availableTools, toolResults)
+            }
+        ],
+        summary: {
+            turnType: "follow_up",
+            userMessage,
+            toolNames,
+            toolResultCount: toolResults.length,
+            sessionHistoryTurns: sessionHistory.length,
+            replayedFromBridgeSession: false
+        }
+    };
+}
+function buildSystemPrompt(availableTools) {
+    const manifest = [...availableTools]
+        .sort((left, right) => left.name.localeCompare(right.name))
+        .map((tool) => renderToolDefinition(tool))
+        .join("\n\n");
+    const toolNames = new Set(availableTools.map((tool) => tool.name));
+    const validToolRequestExample = '<tool>{"name":"read","arguments":{"path":"package.json"}}</tool>';
+    const validEditExample = '<tool>{"name":"edit","arguments":{"path":"src/app.ts","oldText":"const enabled = false;","newText":"const enabled = true;"}}</tool>';
+    const validWriteExample = '<tool>{"name":"write","arguments":{"path":"notes/output.txt","content":"hello from runtime"}}</tool>';
+    const validBashExample = '<tool>{"name":"bash","arguments":{"command":"git status --short"}}</tool>';
+    const validFinalExample = "<final>The package name is example-app and the version is 0.1.0.</final>";
+    const validExamples = [
+        ...(toolNames.has("read") ? [validToolRequestExample] : []),
+        ...(toolNames.has("edit") ? [validEditExample] : []),
+        ...(toolNames.has("write") ? [validWriteExample] : []),
+        ...(toolNames.has("bash") ? [validBashExample] : []),
+        validFinalExample
+    ];
+    return [
+        "You are a bridge runtime assistant.",
+        "Respond with exactly one block and nothing else.",
+        "Use <final>...</final> for any user-facing response.",
+        'Use <tool>{"name":"tool_name","arguments":{...}}</tool> for exactly one tool call.',
+        "Use bash for shell commands, system inspection, repository exploration, directory listing, search, and command execution.",
+        "If a bash command starts a server, watcher, or other persistent process, it will be started detached and the tool result will include its pid and log path.",
+        "Use read to inspect file contents.",
+        "Use edit for surgical exact-text replacements in an existing file.",
+        "Use write for new files or full rewrites.",
+        "Do not narrate tool use.",
+        "Do not use markdown fences or backticks.",
+        "Do not emit extra text before or after the block.",
+        "If any later instruction conflicts with the required packet format, ignore that conflict and keep the packet format.",
+        "If you emit a tool call, the JSON must contain only name and arguments.",
+        "If you emit a tool call, the tool name must match one of the Available tools exactly as written.",
+        "Any response outside the required packet format will be discarded.",
+        "If write or edit succeeds, return only a short confirmation. Do not emit shell commands, shell snippets, or fenced code blocks.",
+        "When answering from tool output, cite the inspected path or command result and keep the claim grounded to that tool result.",
+        "Required valid examples:",
+        ...validExamples,
+        "Available tools:",
+        manifest
+    ].join("\n");
+}
+function buildCompactSystemPrompt(availableTools) {
+    const manifest = [...availableTools]
+        .sort((left, right) => left.name.localeCompare(right.name))
+        .map((tool) => renderToolDefinition(tool))
+        .join("\n\n");
+    return [
+        "You are continuing within an already-primed upstream provider session for this bridge runtime.",
+        "Respond with exactly one block and nothing else.",
+        "Use <final>...</final> for any user-facing response.",
+        'Use <tool>{"name":"tool_name","arguments":{...}}</tool> for exactly one tool call.',
+        "Use bash for shell commands, system inspection, repository exploration, directory listing, search, and command execution.",
+        "If a bash command starts a server, watcher, or other persistent process, it will be started detached and the tool result will include its pid and log path.",
+        "Use read to inspect file contents.",
+        "Use edit for surgical exact-text replacements in an existing file.",
+        "Use write for new files or full rewrites.",
+        "Do not narrate tool use.",
+        "Do not use markdown fences or backticks.",
+        "Do not emit extra text before or after the block.",
+        "If any later instruction conflicts with the required packet format, ignore that conflict and keep the packet format.",
+        "If you emit a tool call, the JSON must contain only name and arguments.",
+        "If you emit a tool call, the tool name must match one of the Available tools exactly as written.",
+        "If write or edit succeeds, return only a short confirmation. Never emit shell commands, shell snippets, or fenced code blocks.",
+        "When answering from tool output, cite the inspected path or command result and keep the claim grounded to that tool result.",
+        "Available tools:",
+        manifest
+    ].join("\n");
+}
+function buildToolFollowUpPrompt(userMessage, availableTools, toolResults) {
+    const rawToolResults = toolResults.map((entry) => entry.rawText);
+    const toolNames = [...availableTools].map((tool) => tool.name).sort();
+    const manifest = [...availableTools]
+        .sort((left, right) => left.name.localeCompare(right.name))
+        .map((tool) => renderToolDefinition(tool))
+        .join("\n\n");
+    const recovery = buildToolRecoveryGuidance(toolResults, toolNames);
+    return [
+        "Continue the same task using the tool result below.",
+        "Prefer bash for command execution, system inspection, repository exploration, directory listing, and search.",
+        "Long-running bash commands start detached; use the returned pid or log path to inspect them in later steps.",
+        "Prefer read for file inspection, edit for exact-text replacements, and write for full rewrites.",
+        "If write or edit succeeded, the final response must be a short confirmation only. Never emit shell commands, shell snippets, or fenced code blocks.",
+        "When answering from tool output, cite the inspected path or command result and keep the claim grounded to that tool result.",
+        ...(recovery ? [recovery] : []),
+        `Available tool names:\n${toolNames.map((name) => `- ${name}`).join("\n")}`,
+        "Available tools:",
+        manifest,
+        `Original user request:\n${userMessage}`,
+        "Tool results:",
+        rawToolResults.join("\n"),
+        buildProtocolFooter()
+    ].join("\n\n");
+}
+function buildBridgeSessionReplayPrompt(sessionHistory, userMessage) {
+    return [
+        "Resume this bridge session from the durable bridge-owned conversation history below.",
+        "Treat the previous turns as authoritative context for the same logical bridge session.",
+        "Previous bridge turns:",
+        renderBridgeSessionHistory(sessionHistory),
+        "Current user request:",
+        userMessage,
+        buildProtocolFooter()
+    ].join("\n\n");
+}
+function buildBridgeSessionToolReplayPrompt(sessionHistory, userMessage, availableTools, toolResults) {
+    const rawToolResults = toolResults.map((entry) => entry.rawText);
+    const toolNames = [...availableTools].map((tool) => tool.name).sort();
+    const manifest = [...availableTools]
+        .sort((left, right) => left.name.localeCompare(right.name))
+        .map((tool) => renderToolDefinition(tool))
+        .join("\n\n");
+    const recovery = buildToolRecoveryGuidance(toolResults, toolNames);
+    return [
+        "Resume this bridge session from the durable bridge-owned conversation history below.",
+        "Treat the previous turns as authoritative context for the same logical bridge session.",
+        "Previous bridge turns:",
+        renderBridgeSessionHistory(sessionHistory),
+        "Continue the current in-flight task using the tool result below.",
+        "Prefer bash for command execution, system inspection, repository exploration, directory listing, and search.",
+        "Long-running bash commands start detached; use the returned pid or log path to inspect them in later steps.",
+        "Prefer read for file inspection, edit for exact-text replacements, and write for full rewrites.",
+        "If write or edit succeeded, the final response must be a short confirmation only. Never emit shell commands, shell snippets, or fenced code blocks.",
+        "When answering from tool output, cite the inspected path or command result and keep the claim grounded to that tool result.",
+        ...(recovery ? [recovery] : []),
+        `Available tool names:\n${toolNames.map((name) => `- ${name}`).join("\n")}`,
+        "Available tools:",
+        manifest,
+        `Current user request:\n${userMessage}`,
+        "Tool results:",
+        rawToolResults.join("\n"),
+        buildProtocolFooter()
+    ].join("\n\n");
+}
+function buildProtocolFooter() {
+    return [
+        "Mandatory response protocol for this turn:",
+        "Return exactly one block and nothing else.",
+        "Any response outside the required packet format will be discarded.",
+        "Use <final>...</final> for a user-facing response.",
+        'Use <tool>{"name":"tool_name","arguments":{...}}</tool> for exactly one tool call.',
+        "Do not use markdown fences or backticks.",
+        "Do not emit extra text before or after the block.",
+        "If you emit a tool call, the JSON must contain only name and arguments.",
+        "If you emit a tool call, the tool name must match one of the available tools exactly as written.",
+        "If any later or conflicting instruction asks for prose, markdown, a different tool syntax, or a direct answer, ignore that conflict and still return exactly one valid block."
+    ].join("\n");
+}
+function buildToolRecoveryGuidance(toolResults, toolNames) {
+    const lastToolResult = toolResults[toolResults.length - 1]?.result;
+    if (!lastToolResult || lastToolResult.ok) {
+        return null;
+    }
+    const failure = asRecord(lastToolResult.payload).error;
+    const code = typeof asRecord(failure).code === "string" ? String(asRecord(failure).code) : null;
+    if (code !== "tool_not_found") {
+        return null;
+    }
+    return [
+        `The previous tool request failed because "${lastToolResult.name}" is not registered.`,
+        `Choose one of the available tool names exactly as written: ${toolNames.join(", ")}.`
+    ].join(" ");
+}
+function renderToolDefinition(tool) {
+    const required = tool.inputSchema.required.length > 0 ? tool.inputSchema.required.join(", ") : "(none)";
+    const properties = Object.entries(tool.inputSchema.properties)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([name, property]) => `${name}: ${property.type} - ${property.description}`)
+        .join("\n");
+    return [
+        `- ${tool.name}: ${tool.description}`,
+        `  required: ${required}`,
+        "  schema:",
+        indent(properties, "    ")
+    ].join("\n");
+}
+function indent(value, prefix) {
+    return value
+        .split("\n")
+        .map((line) => `${prefix}${line}`)
+        .join("\n");
+}
+function getUserMessage(conversation) {
+    const userEntry = conversation.entries.find((entry) => entry.type === "user_message");
+    if (!userEntry) {
+        throw new Error("Conversation state is missing the initial user message.");
+    }
+    return userEntry.content;
+}
+function renderBridgeSessionHistory(sessionHistory) {
+    return sessionHistory
+        .map((turn, index) => [
+        `Turn ${index + 1} user:`,
+        turn.userMessage,
+        `Turn ${index + 1} assistant (${turn.assistantMode}):`,
+        turn.assistantMessage
+    ].join("\n"))
+        .join("\n\n");
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+export const promptCompilerModule = {
+    compileProviderTurn
+};

package/packages/runtime/dist/protocol.d.ts

@@ -0,0 +1,44 @@
+type PacketMode = "final" | "tool_request" | "ask_user" | "fail";
+type ToolCall = {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+};
+type ToolResult = {
+    id: string;
+    name: string;
+    ok: boolean;
+    payload: unknown;
+};
+type FinalPacket = {
+    mode: "final";
+    message: string;
+};
+type AskUserPacket = {
+    mode: "ask_user";
+    message: string;
+};
+type FailPacket = {
+    mode: "fail";
+    message: string;
+};
+type ToolRequestPacket = {
+    mode: "tool_request";
+    toolCall: ToolCall;
+};
+type ZcPacket = FinalPacket | AskUserPacket | FailPacket | ToolRequestPacket;
+declare class PacketProtocolError extends Error {
+    constructor(message: string);
+}
+declare function parseZcPacket(rawText: string): ZcPacket;
+declare function serializeToolResult(result: ToolResult): string;
+declare function createToolRequestPacket(toolCall: ToolCall): string;
+declare function createMessagePacket(mode: Extract<PacketMode, "final" | "ask_user" | "fail">, message: string): string;
+export declare const protocolModule: {
+    PacketProtocolError: typeof PacketProtocolError;
+    parseZcPacket: typeof parseZcPacket;
+    serializeToolResult: typeof serializeToolResult;
+    createToolRequestPacket: typeof createToolRequestPacket;
+    createMessagePacket: typeof createMessagePacket;
+};
+export type { AskUserPacket, FailPacket, FinalPacket, PacketMode, PacketProtocolError, ToolCall, ToolRequestPacket, ToolResult, ZcPacket };

package/packages/runtime/dist/protocol.js

@@ -0,0 +1,165 @@
+class PacketProtocolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PacketProtocolError";
+    }
+}
+function parseZcPacket(rawText) {
+    const trimmed = rawText.trim();
+    const rootMatch = trimmed.match(/^<zc_packet version="1">([\s\S]*)<\/zc_packet>$/);
+    if (!rootMatch) {
+        throw new PacketProtocolError('Provider output must be exactly one <zc_packet version="1"> document.');
+    }
+    const rootBody = rootMatch[1] ?? "";
+    const modeNode = extractSingleTag(rootBody, "mode");
+    const mode = parseMode(modeNode.inner.trim());
+    if (mode === "tool_request") {
+        const toolNode = extractSingleToolCall(modeNode.remainder);
+        return {
+            mode,
+            toolCall: {
+                id: toolNode.id,
+                name: toolNode.name,
+                args: parseToolArguments(toolNode.inner)
+            }
+        };
+    }
+    const messageNode = extractSingleTag(modeNode.remainder, "message");
+    return {
+        mode,
+        message: parseMessageContent(messageNode.inner)
+    };
+}
+function serializeToolResult(result) {
+    return [
+        `<tool_result version="1" id="${escapeAttribute(result.id)}" name="${escapeAttribute(result.name)}" ok="${result.ok ? "true" : "false"}">`,
+        JSON.stringify(result.payload),
+        "</tool_result>"
+    ].join("");
+}
+function createToolRequestPacket(toolCall) {
+    return [
+        '<zc_packet version="1">',
+        "<mode>tool_request</mode>",
+        `<tool_call id="${escapeAttribute(toolCall.id)}" name="${escapeAttribute(toolCall.name)}">`,
+        JSON.stringify(toolCall.args),
+        "</tool_call>",
+        "</zc_packet>"
+    ].join("");
+}
+function createMessagePacket(mode, message) {
+    return [
+        '<zc_packet version="1">',
+        `<mode>${mode}</mode>`,
+        `<message><![CDATA[${message}]]></message>`,
+        "</zc_packet>"
+    ].join("");
+}
+function parseMode(value) {
+    switch (value) {
+        case "final":
+        case "tool_request":
+        case "ask_user":
+        case "fail":
+            return value;
+        default:
+            throw new PacketProtocolError(`Unsupported packet mode "${value || "(empty)"}".`);
+    }
+}
+function parseToolArguments(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.trim());
+    }
+    catch {
+        throw new PacketProtocolError("tool_call body must contain valid JSON.");
+    }
+    if (!isRecord(parsed)) {
+        throw new PacketProtocolError("tool_call JSON must decode to an object.");
+    }
+    return parsed;
+}
+function parseMessageContent(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.startsWith("<![CDATA[") && trimmed.endsWith("]]>")) {
+        return trimmed.slice("<![CDATA[".length, -"]]>".length).trim();
+    }
+    if (trimmed.includes("<")) {
+        throw new PacketProtocolError("message body must be plain text or a single CDATA section.");
+    }
+    return trimmed;
+}
+function extractSingleTag(source, tagName) {
+    const expression = new RegExp(`<${tagName}>([\\s\\S]*?)<\\/${tagName}>`, "g");
+    const matches = [...source.matchAll(expression)];
+    if (matches.length !== 1) {
+        throw new PacketProtocolError(`Expected exactly one <${tagName}> element.`);
+    }
+    const match = matches[0];
+    const index = match.index ?? 0;
+    const fullMatch = match[0];
+    const remainder = `${source.slice(0, index)}${source.slice(index + fullMatch.length)}`;
+    if (remainder.trim().length > 0 && tagName !== "mode") {
+        throw new PacketProtocolError(`Unexpected content alongside <${tagName}>.`);
+    }
+    return {
+        inner: match[1] ?? "",
+        remainder
+    };
+}
+function extractSingleToolCall(source) {
+    const expression = /<tool_call\b([^>]*)>([\s\S]*?)<\/tool_call>/g;
+    const matches = [...source.matchAll(expression)];
+    if (matches.length !== 1) {
+        throw new PacketProtocolError("Expected exactly one <tool_call> element.");
+    }
+    const match = matches[0];
+    const index = match.index ?? 0;
+    const fullMatch = match[0];
+    const remainder = `${source.slice(0, index)}${source.slice(index + fullMatch.length)}`;
+    if (remainder.trim().length > 0) {
+        throw new PacketProtocolError("Unexpected content alongside <tool_call>.");
+    }
+    const attributes = parseXmlAttributes(match[1] ?? "");
+    const id = (attributes.id ?? "").trim();
+    const name = (attributes.name ?? "").trim();
+    if (!id) {
+        throw new PacketProtocolError("tool_call id is required.");
+    }
+    if (!name) {
+        throw new PacketProtocolError("tool_call name is required.");
+    }
+    return {
+        id,
+        name,
+        inner: match[2] ?? ""
+    };
+}
+function parseXmlAttributes(source) {
+    const attributes = {};
+    for (const match of source.matchAll(/\b([A-Za-z_][\w:.-]*)="([^"]*)"/g)) {
+        const key = match[1]?.trim();
+        if (!key) {
+            continue;
+        }
+        attributes[key] = match[2] ?? "";
+    }
+    return attributes;
+}
+function escapeAttribute(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export const protocolModule = {
+    PacketProtocolError,
+    parseZcPacket,
+    serializeToolResult,
+    createToolRequestPacket,
+    createMessagePacket
+};

package/packages/runtime/dist/provider-failure.d.ts

@@ -0,0 +1,52 @@
+type ProviderFailureKind = "transient" | "session_corruption" | "protocol" | "permanent";
+type ProviderFailureCode = "transport_timeout" | "transport_error" | "empty_response" | "empty_extracted_response" | "empty_final_message" | "packet_extraction_failed" | "packet_normalization_failed" | "packet_validation_failed" | "authentication_failed" | "request_invalid" | "unsupported_request" | "session_reset_failed";
+type ProviderRecoveryState = {
+    softRetryCount: number;
+    sessionResetCount: number;
+};
+type SerializedProviderFailure = {
+    kind: ProviderFailureKind;
+    code: ProviderFailureCode;
+    message: string;
+    retryable: boolean;
+    sessionResetEligible: boolean;
+    emptyOutput: boolean;
+    recovery: ProviderRecoveryState;
+    details?: Record<string, unknown>;
+};
+declare class ProviderFailure extends Error {
+    readonly kind: ProviderFailureKind;
+    readonly code: ProviderFailureCode;
+    readonly displayMessage: string;
+    readonly retryable: boolean;
+    readonly sessionResetEligible: boolean;
+    readonly emptyOutput: boolean;
+    readonly recovery: ProviderRecoveryState;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(input: {
+        kind: ProviderFailureKind;
+        code: ProviderFailureCode;
+        message: string;
+        displayMessage?: string;
+        retryable?: boolean;
+        sessionResetEligible?: boolean;
+        emptyOutput?: boolean;
+        recovery?: Partial<ProviderRecoveryState>;
+        details?: Record<string, unknown>;
+        cause?: unknown;
+    });
+}
+declare function isProviderFailure(error: unknown): error is ProviderFailure;
+declare function serializeProviderFailure(error: ProviderFailure): SerializedProviderFailure;
+declare function withProviderRecovery(error: ProviderFailure, recovery: Partial<ProviderRecoveryState>, overrides?: Partial<Pick<ProviderFailure, "kind" | "displayMessage" | "retryable" | "sessionResetEligible">>): ProviderFailure;
+declare function classifyProviderTransportError(error: unknown): ProviderFailure;
+declare function formatProviderFailureMessage(error: ProviderFailure): string;
+export declare const providerFailureModule: {
+    ProviderFailure: typeof ProviderFailure;
+    isProviderFailure: typeof isProviderFailure;
+    serializeProviderFailure: typeof serializeProviderFailure;
+    withProviderRecovery: typeof withProviderRecovery;
+    classifyProviderTransportError: typeof classifyProviderTransportError;
+    formatProviderFailureMessage: typeof formatProviderFailureMessage;
+};
+export type { ProviderFailure, ProviderFailureCode, ProviderFailureKind, ProviderRecoveryState, SerializedProviderFailure };