@intx/workflow-host 0.2.2

package/dist/ipc/event-channel.d.ts

@@ -0,0 +1,677 @@
+import { decodeEnvelope } from "./envelope.js";
+/**
+ * The event channel additionally carries the two bracket events the
+ * reactor emits per message run. They are part of the InferenceEvent
+ * union upstream; re-exporting the union directly keeps this channel
+ * structurally identical to what the hub's `agent.event` frame
+ * carries today.
+ */
+export declare const EventPayload: import("arktype/internal/variants/object.ts").ObjectType<{
+    type: "inference.start";
+    seq: number;
+    data: {
+        model: string;
+    };
+} | {
+    type: "inference.thinking.delta";
+    seq: number;
+    data: {
+        token: string;
+        partial: {
+            text: string;
+            thinking?: string;
+            toolCalls?: {
+                id: string;
+                name: string;
+                partialArguments: string;
+            }[];
+        };
+        index?: number;
+    };
+} | {
+    type: "inference.thinking.signature";
+    seq: number;
+    data: {
+        signature: string;
+        index?: number;
+    };
+} | {
+    type: "inference.thinking.redacted";
+    seq: number;
+    data: {
+        redactedThinking: {
+            type: "redacted_thinking";
+            data: string;
+        };
+        index?: number;
+    };
+} | {
+    type: "inference.text.delta";
+    seq: number;
+    data: {
+        token: string;
+        partial: {
+            text: string;
+            thinking?: string;
+            toolCalls?: {
+                id: string;
+                name: string;
+                partialArguments: string;
+            }[];
+        };
+        index?: number;
+    };
+} | {
+    type: "inference.refusal.delta";
+    seq: number;
+    data: {
+        token: string;
+        partial: {
+            text: string;
+            thinking?: string;
+            toolCalls?: {
+                id: string;
+                name: string;
+                partialArguments: string;
+            }[];
+        };
+        index?: number;
+    };
+} | {
+    type: "inference.tool_call.start";
+    seq: number;
+    data: {
+        callId: string;
+        name: string;
+        partial: {
+            text: string;
+            thinking?: string;
+            toolCalls?: {
+                id: string;
+                name: string;
+                partialArguments: string;
+            }[];
+        };
+        index?: number;
+    };
+} | {
+    type: "inference.tool_call.delta";
+    seq: number;
+    data: {
+        callId: string;
+        argumentFragment: string;
+        partial: {
+            text: string;
+            thinking?: string;
+            toolCalls?: {
+                id: string;
+                name: string;
+                partialArguments: string;
+            }[];
+        };
+        index?: number;
+    };
+} | {
+    type: "inference.tool_call.end";
+    seq: number;
+    data: {
+        callId: string;
+        name: string;
+        arguments: Record<string, unknown>;
+        partial: {
+            text: string;
+            thinking?: string;
+            toolCalls?: {
+                id: string;
+                name: string;
+                partialArguments: string;
+            }[];
+        };
+        index?: number;
+    };
+} | {
+    type: "inference.usage";
+    seq: number;
+    data: {
+        usage: {
+            input: number;
+            output: number;
+            cacheRead: number;
+            cacheWrite: number;
+            thinking: number;
+        };
+        source: {
+            sourceId: string;
+            provider: string;
+            model: string;
+        };
+    };
+} | {
+    type: "inference.done";
+    seq: number;
+    data: {
+        turn: {
+            role: "assistant";
+            content: ({
+                type: "text";
+                text: string;
+            } | {
+                type: "image";
+                source: {
+                    kind: "base64";
+                    mimeType: string;
+                    data: string;
+                } | {
+                    kind: "file-reference";
+                    mimeType: string;
+                    reference: string;
+                } | {
+                    kind: "url";
+                    mimeType: string;
+                    url: string;
+                };
+            } | {
+                type: "audio";
+                source: {
+                    kind: "base64";
+                    mimeType: string;
+                    data: string;
+                } | {
+                    kind: "file-reference";
+                    mimeType: string;
+                    reference: string;
+                } | {
+                    kind: "url";
+                    mimeType: string;
+                    url: string;
+                };
+            } | {
+                type: "video";
+                source: {
+                    kind: "base64";
+                    mimeType: string;
+                    data: string;
+                } | {
+                    kind: "file-reference";
+                    mimeType: string;
+                    reference: string;
+                } | {
+                    kind: "url";
+                    mimeType: string;
+                    url: string;
+                };
+            } | {
+                type: "document";
+                source: {
+                    kind: "base64";
+                    mimeType: string;
+                    data: string;
+                } | {
+                    kind: "file-reference";
+                    mimeType: string;
+                    reference: string;
+                } | {
+                    kind: "url";
+                    mimeType: string;
+                    url: string;
+                };
+            } | {
+                type: "thinking";
+                thinking: string;
+                signature?: string;
+            } | {
+                type: "redacted_thinking";
+                data: string;
+            } | {
+                type: "refusal";
+                reason: string;
+            } | {
+                type: "tool_call";
+                id: string;
+                name: string;
+                arguments: Record<string, unknown>;
+            } | {
+                type: "citation";
+                citedText: string;
+                source: {
+                    title?: string;
+                    uri?: string;
+                    documentRef?: {
+                        index: number;
+                    };
+                };
+                location?: {
+                    kind: "page" | "char" | "content-block";
+                    start: number;
+                    end: number;
+                };
+                textOffset?: {
+                    start: number;
+                    end: number;
+                };
+            } | {
+                type: "code_execution_request";
+                id: string;
+                code: string;
+                language?: string;
+            } | {
+                type: "code_execution_result";
+                requestId: string;
+                status: "error" | "ok" | "aborted" | "timeout";
+                stdout?: string;
+                stderr?: string;
+                returnCode?: number;
+                providerOutcome?: string;
+                abortReason?: string;
+            } | {
+                type: "tool_result";
+                callId: string;
+                content: ({
+                    type: "text";
+                    text: string;
+                } | {
+                    type: "image";
+                    source: {
+                        kind: "base64";
+                        mimeType: string;
+                        data: string;
+                    } | {
+                        kind: "file-reference";
+                        mimeType: string;
+                        reference: string;
+                    } | {
+                        kind: "url";
+                        mimeType: string;
+                        url: string;
+                    };
+                } | {
+                    type: "audio";
+                    source: {
+                        kind: "base64";
+                        mimeType: string;
+                        data: string;
+                    } | {
+                        kind: "file-reference";
+                        mimeType: string;
+                        reference: string;
+                    } | {
+                        kind: "url";
+                        mimeType: string;
+                        url: string;
+                    };
+                } | {
+                    type: "video";
+                    source: {
+                        kind: "base64";
+                        mimeType: string;
+                        data: string;
+                    } | {
+                        kind: "file-reference";
+                        mimeType: string;
+                        reference: string;
+                    } | {
+                        kind: "url";
+                        mimeType: string;
+                        url: string;
+                    };
+                } | {
+                    type: "document";
+                    source: {
+                        kind: "base64";
+                        mimeType: string;
+                        data: string;
+                    } | {
+                        kind: "file-reference";
+                        mimeType: string;
+                        reference: string;
+                    } | {
+                        kind: "url";
+                        mimeType: string;
+                        url: string;
+                    };
+                })[];
+                detail?: unknown;
+                isError?: boolean;
+            })[];
+            model: string;
+            timestamp: number;
+        };
+        usage: {
+            input: number;
+            output: number;
+            cacheRead: number;
+            cacheWrite: number;
+            thinking: number;
+        };
+        source: {
+            sourceId: string;
+            provider: string;
+            model: string;
+        };
+        pacingDelayMs?: number;
+    };
+} | {
+    type: "inference.error";
+    seq: number;
+    data: {
+        error: {
+            category: "fatal" | "aborted" | "timeout" | "retryable" | "context_overflow" | "credential_failure" | "quota_exhausted" | "protocol_mismatch";
+            message: string;
+            statusCode?: number;
+            retryAfterMs?: number;
+            raw?: unknown;
+        };
+        partial: {
+            text: string;
+            thinking?: string;
+            toolCalls?: {
+                id: string;
+                name: string;
+                partialArguments: string;
+            }[];
+        };
+    };
+} | {
+    type: "inference.retry";
+    seq: number;
+    data: {
+        attempt: number;
+        delayMs: number;
+        previousError: {
+            category: "fatal" | "aborted" | "timeout" | "retryable" | "context_overflow" | "credential_failure" | "quota_exhausted" | "protocol_mismatch";
+            message: string;
+            statusCode?: number;
+            retryAfterMs?: number;
+            raw?: unknown;
+        };
+    };
+} | {
+    type: "inference.citation";
+    seq: number;
+    data: {
+        citation: {
+            type: "citation";
+            citedText: string;
+            source: {
+                title?: string;
+                uri?: string;
+                documentRef?: {
+                    index: number;
+                };
+            };
+            location?: {
+                kind: "page" | "char" | "content-block";
+                start: number;
+                end: number;
+            };
+            textOffset?: {
+                start: number;
+                end: number;
+            };
+        };
+        index?: number;
+    };
+} | {
+    type: "inference.code_execution.start";
+    seq: number;
+    data: {
+        request: {
+            type: "code_execution_request";
+            id: string;
+            code: string;
+            language?: string;
+        };
+        index?: number;
+    };
+} | {
+    type: "inference.code_execution.delta";
+    seq: number;
+    data: {
+        requestId: string;
+        codeFragment: string;
+        index?: number;
+    };
+} | {
+    type: "inference.code_execution.result";
+    seq: number;
+    data: {
+        result: {
+            type: "code_execution_result";
+            requestId: string;
+            status: "error" | "ok" | "aborted" | "timeout";
+            stdout?: string;
+            stderr?: string;
+            returnCode?: number;
+            providerOutcome?: string;
+            abortReason?: string;
+        };
+        index?: number;
+    };
+} | {
+    type: "inference.image_output";
+    seq: number;
+    data: {
+        image: {
+            type: "image";
+            source: {
+                kind: "base64";
+                mimeType: string;
+                data: string;
+            } | {
+                kind: "file-reference";
+                mimeType: string;
+                reference: string;
+            } | {
+                kind: "url";
+                mimeType: string;
+                url: string;
+            };
+        };
+        index?: number;
+    };
+} | {
+    type: "tool.start";
+    seq: number;
+    data: {
+        call: {
+            id: string;
+            name: string;
+            arguments: Record<string, unknown>;
+        };
+    };
+} | {
+    type: "tool.update";
+    seq: number;
+    data: {
+        callId: string;
+        partial: string;
+    };
+} | {
+    type: "tool.done";
+    seq: number;
+    data: {
+        result: {
+            callId: string;
+            content: string | Record<string, unknown>;
+            detail?: unknown;
+            isError?: boolean;
+            pendingMarker?: {
+                status: "pending";
+                correlationId: string;
+                expectedFrom?: string;
+            };
+        };
+    };
+} | {
+    type: "message.queued";
+    seq: number;
+    data: {
+        message: {
+            ref: {
+                uid: number;
+                mailbox: string;
+            };
+            headers: Record<string, unknown>;
+            flags: string[];
+            signatureStatus: "unknown" | "valid" | "invalid" | "missing";
+            content?: string;
+            payload?: object;
+            attachments?: unknown[];
+        };
+    };
+} | {
+    type: "message.run.started";
+    seq: number;
+    data: {
+        messageId: string;
+        messageRunId: string;
+        receivedAt: number;
+    };
+} | {
+    type: "message.run.ended";
+    seq: number;
+    data: {
+        messageRunId: string;
+        messageId: string;
+        status: "completed" | "failed";
+        error?: {
+            message: string;
+            kind?: string;
+        };
+    };
+} | {
+    type: "message.correlated";
+    seq: number;
+    data: {
+        message: {
+            ref: {
+                uid: number;
+                mailbox: string;
+            };
+            headers: Record<string, unknown>;
+            flags: string[];
+            signatureStatus: "unknown" | "valid" | "invalid" | "missing";
+            content?: string;
+            payload?: object;
+            attachments?: unknown[];
+        };
+        correlationId: string;
+    };
+} | {
+    type: "connector.reply";
+    seq: number;
+    data: {
+        content: string;
+        checkpointHash?: string;
+    };
+} | {
+    type: "reactor.start";
+    seq: number;
+    data: object;
+} | {
+    type: "reactor.gate.blocked";
+    seq: number;
+    data: {
+        reason: "approval" | "payment" | "credential" | "budget" | "child_completion" | "message_response";
+        gateId: string;
+    };
+} | {
+    type: "reactor.gate.cleared";
+    seq: number;
+    data: {
+        gateId: string;
+        reason: "timeout" | "resolved" | "shutdown";
+    };
+} | {
+    type: "reactor.done";
+    seq: number;
+    data: object;
+} | {
+    type: "reactor.error";
+    seq: number;
+    data: {
+        error: string;
+        fatal: boolean;
+    };
+} | {
+    type: "fork.created";
+    seq: number;
+    data: {
+        forkId: string;
+        parentId: string;
+        mode: "child" | "independent";
+    };
+} | {
+    type: "fork.done";
+    seq: number;
+    data: {
+        forkId: string;
+        result?: unknown;
+    };
+} | {
+    type: "fork.error";
+    seq: number;
+    data: {
+        forkId: string;
+        error: string;
+    };
+} | {
+    type: "fork.aborted";
+    seq: number;
+    data: {
+        forkId: string;
+    };
+} | {
+    type: string;
+    seq: number;
+    data: Record<string, unknown>;
+}, {}>;
+export type EventPayload = typeof EventPayload.infer;
+export interface FrameWriter {
+    write(bytes: Uint8Array): Promise<void> | void;
+}
+export interface FrameReader {
+    read(): AsyncIterableIterator<Uint8Array>;
+}
+export interface EventChannelSenderOpts {
+    hmacKey: Uint8Array;
+    channelId: string;
+    writer: FrameWriter;
+}
+export interface EventChannelSender {
+    send(payload: EventPayload): Promise<void>;
+    readonly seq: number;
+}
+/**
+ * Construct the child-side event-channel sender. The shared HMAC
+ * key lives in closure. The child mints monotonic seq values per
+ * channelId; the receiver enforces strict monotonicity.
+ */
+export declare function createEventChannelSender(opts: EventChannelSenderOpts): EventChannelSender;
+export interface EventChannelReceiverOpts {
+    hmacKey: Uint8Array;
+    channelId: string;
+    reader: FrameReader;
+    /**
+     * Userspace bound on the in-flight buffer between substrate read
+     * and caller consume. Overrun calls `onCrash` and stops the
+     * iterator. Default 1024 matches the discipline documented in
+     * the IPC threat model.
+     */
+    bufferLimit?: number;
+    onCrash: (reason: string) => void;
+}
+/**
+ * Construct the supervisor-side event-channel receiver. Yields one
+ * verified, in-order `EventPayload` per call. Any frame that fails
+ * HMAC verification, carries a non-current channelId, arrives out
+ * of order, or arrives faster than the consumer drains -- triggers
+ * `onCrash` and ends the iterator.
+ */
+export declare function receiveEventChannel(opts: EventChannelReceiverOpts): AsyncGenerator<EventPayload, void, void>;
+export declare const DEFAULT_EVENT_BUFFER_LIMIT = 1024;
+/**
+ * Re-export the envelope decoder for callers that need raw access
+ * to a frame's envelope outside the receiver iterator.
+ */
+export { decodeEnvelope };