eve/dist/src/execution/session-inbox/inbox.d.ts

Filesystem-first framework for durable backend AI agents that run anywhere.

import type { DeliverPayload, HookPayload, SessionCommand } from "#channel/types.js";
import type { WorkflowToolRunMessage } from "#execution/tools/workflow/messages.js";
/** All session addresses accept the same protocol. Callback routes construct
 * their own message kind; they never accept arbitrary session commands. */
export interface AuthorizationCallbackPayload {
    readonly kind: "authorization-callback";
    readonly payloads: DeliverPayload[];
}
export type SessionInboxPayload = HookPayload | SessionCommand | WorkflowToolRunMessage | AuthorizationCallbackPayload;
export interface SessionInboxReader {
    /**
     * Waits for and removes the next accepted payload in arrival order, or
     * `undefined` once every hook is released. Only one consumer waits at a
     * time; the owner program is strictly sequential.
     */
    next(): Promise<SessionInboxPayload | undefined>;
    /** Removes every payload accepted so far, in arrival order. */
    drain(): SessionInboxPayload[];
    hasPending(): boolean;
    /**
     * Called from the pump the moment an interrupt (`cancel`, `reset`,
     * `session-timeout`) is accepted, ahead of any consumer read. Handlers must
     * be synchronous and idempotent. The payload stays in the queue so the
     * consumer still processes it in order.
     */
    onInterrupt(handler: (payload: SessionInboxPayload) => void): () => void;
    /** Observes deliveries without consuming them; replays unread deliveries on subscription. */
    onDelivery(handler: (payload: SessionInboxPayload) => void): () => void;
    restore(payloads: readonly SessionInboxPayload[]): void;
}
export interface SessionInboxOwnership {
    /** Logical tokens currently claimed, in claim order. */
    readonly claimedTokens: readonly string[];
    claimSessionHook(token: string): Promise<void>;
    /** Registers every token as one batch; all claims settle before the first failure propagates. */
    claimSessionHooks(tokens: readonly string[]): Promise<void>;
}
export interface SessionInbox extends SessionInboxReader, SessionInboxOwnership {
}
export interface SessionInboxHandle extends SessionInbox {
    dispose(): Promise<void>;
    /** Disposes every hook and returns each payload the hooks accepted but the owner never read. */
    release(): Promise<SessionInboxPayload[]>;
}
export declare function isInterrupt(value: SessionInboxPayload): boolean;
/**
 * One FIFO queue for the session lifetime, fed by a continuous reader per
 * claimed hook. The pump never waits on queue depth: interrupts share each
 * hook's ordered stream, so any backpressure on ordinary payloads would also
 * hold back the cancel behind them. Accepted payloads are already durable on
 * the hook, so the queue is a mirror rather than the source of truth.
 */
export declare function createSessionInbox(sessionId: string): SessionInboxHandle;
export declare function isWorkflowMessage(value: SessionInboxPayload): value is WorkflowToolRunMessage;