eve/dist/src/tools/durable-callbacks.d.ts

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

import type { Approval } from "#approval/definition.js";
import type { JsonObject, JsonPrimitive } from "#shared/json.js";
export type DurableDynamicCallbackPhase = "labelComplete" | "labelDelta" | "labelStart" | "approvalKey" | "approvalRequest" | "approvalResponse" | "execute" | "toModelOutput";
export type DurableDynamicCallbackFn = (closure: JsonObject, ...args: never[]) => unknown;
/**
 * Persisted binding for one callback phase. Identity is
 * session, lifecycle scope, resolver, entry, tool name, and phase — carried
 * by the surrounding context and metadata — so only the
 * snapshotted closure values persist.
 */
export interface DurableDynamicCallbackReference {
    readonly closure: JsonObject;
    readonly stepId?: never;
}
export interface DurableDynamicToolCallbacks {
    readonly execute: DurableDynamicCallbackReference;
    readonly label?: {
        readonly complete?: DurableDynamicCallbackReference;
        readonly delta?: DurableDynamicCallbackReference;
        readonly start?: DurableDynamicCallbackReference;
    };
    readonly approvalKey?: DurableDynamicCallbackReference;
    readonly approvalRequest?: DurableDynamicCallbackReference;
    readonly approvalResponse?: DurableDynamicCallbackReference;
    readonly toModelOutput?: DurableDynamicCallbackReference;
}
/** Live descriptor stamped on authored callbacks; `callback` never persists. */
export interface StampedDurableDynamicCallback {
    readonly callback: DurableDynamicCallbackFn;
    readonly closure: JsonObject;
}
export type LiveDurableDynamicToolCallbacks = Partial<{
    execute: StampedDurableDynamicCallback;
    label: {
        readonly complete?: StampedDurableDynamicCallback;
        readonly delta?: StampedDurableDynamicCallback;
        readonly start?: StampedDurableDynamicCallback;
    };
    approvalKey: StampedDurableDynamicCallback;
    approvalRequest: StampedDurableDynamicCallback;
    approvalResponse: StampedDurableDynamicCallback;
    toModelOutput: StampedDurableDynamicCallback;
}>;
export declare const DURABLE_DYNAMIC_TOOL_CALLBACKS: unique symbol;
export type DynamicToolCallbackScope = "session" | "turn" | "step";
export interface DynamicToolCallbackOwner {
    readonly sessionId: string;
    readonly scope: DynamicToolCallbackScope;
    readonly resolverSlug: string;
    readonly entryKey: string;
    readonly name: string;
}
/** Re-resolution updates only the same session's resolver and lifecycle scope. */
export declare function registerDurableDynamicCallback(input: {
    readonly callback: DurableDynamicCallbackFn;
    readonly phase: DurableDynamicCallbackPhase;
    readonly owner: DynamicToolCallbackOwner;
}): void;
export declare function lookupDurableDynamicCallback(owner: DynamicToolCallbackOwner, phase: DurableDynamicCallbackPhase): DurableDynamicCallbackFn | undefined;
/** Discards completed sessions or a resolver's previous result before replacement. */
export declare function clearDurableDynamicCallbacks(sessionId: string, resolver?: {
    readonly scope: DynamicToolCallbackScope;
    readonly resolverSlug: string;
}): void;
/** Invokes a registered callback with its snapshotted closure and live arguments. */
export declare function callDurableDynamicCallback(callback: DurableDynamicCallbackFn, closure: JsonObject, ...args: unknown[]): unknown;
/** True when any persisted callback of these tools has no registered binding. */
export declare function hasUnregisteredDurableDynamicCallbacks(metadata: readonly {
    callbacks: DurableDynamicToolCallbacks;
    name: string;
    resolverSlug: string;
    entryKey: string;
}[], scope: Pick<DynamicToolCallbackOwner, "sessionId" | "scope">): boolean;
type DurableCallbackJsonValue<T> = T extends (...args: never[]) => unknown ? never : T extends JsonPrimitive ? T : T extends readonly (infer TItem)[] ? readonly DurableCallbackJsonValue<TItem>[] : T extends object ? DurableCallbackJsonObject<T> : never;
type DurableCallbackJsonObject<T extends object> = Extract<keyof T, symbol> extends never ? {
    readonly [TKey in keyof T]: DurableCallbackJsonValue<Exclude<T[TKey], undefined>> | Extract<T[TKey], undefined>;
} : never;
/**
 * Defines a replayable callback for tools created outside eve's authored-source
 * transform, such as tools returned by a provider package.
 *
 * Put every per-tool value in `closure`. eve snapshots that JSON-serializable
 * object when the dynamic tool resolves and passes it as the first argument to
 * the current callback implementation during both live execution and replay.
 */
export declare function defineDurableCallback<TClosure extends object, TArgs extends unknown[], TResult>(input: {
    readonly callback: (closure: TClosure, ...args: TArgs) => TResult;
    readonly closure: TClosure & DurableCallbackJsonObject<TClosure>;
}): (...args: TArgs) => TResult;
/** Marks a live callback with the descriptor needed to register it at resolve time. */
export declare function stampDurableDynamicCallback<TCallback extends (...args: never[]) => unknown>(callback: TCallback, descriptor: StampedDurableDynamicCallback): TCallback;
export declare function readDurableDynamicCallback(callback: unknown): StampedDurableDynamicCallback | undefined;
/** Copies phase-specific callback descriptors onto a branded tool definition. */
export declare function stampDurableDynamicToolCallbacks(definition: object, callbacks: LiveDurableDynamicToolCallbacks): void;
export declare function collectDurableDynamicToolCallbacks(input: {
    readonly label?: {
        readonly complete?: (...args: never[]) => unknown;
        readonly delta?: (...args: never[]) => unknown;
        readonly start?: (...args: never[]) => unknown;
    };
    readonly approval?: Approval<never>;
    readonly approvalKey?: (...args: never[]) => unknown;
    readonly execute: (...args: never[]) => unknown;
    readonly toModelOutput?: (...args: never[]) => unknown;
}): LiveDurableDynamicToolCallbacks;
export declare function readDurableDynamicToolCallbacks(definition: object): LiveDurableDynamicToolCallbacks | undefined;
export {};