eve/dist/src/subagents/remote-dispatch.d.ts

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

import { type ResetResponse } from "#protocol/reset-session.js";
import type { ActivityObserverConfig, CancelTurnResult, SessionAuthContext } from "#channel/types.js";
import type { ChannelAudience } from "#shared/channel-audience.js";
import { type SubagentParentContext } from "#subagents/invocation.js";
import type { HarnessSession } from "#harness/types.js";
import type { RuntimeRemoteAgentDispatchRequest } from "#shared/action-types.js";
import type { RuntimeSubagentRegistry } from "#runtime/subagents/registry.js";
import type { DynamicRemoteAgentConfig } from "#runtime/subagents/dynamic-remote-agent-config.js";
import type { CompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-cache.js";
import type { ResolvedRuntimeRemoteAgentNode } from "#runtime/types.js";
import type { JsonObject } from "#shared/json.js";
type RemoteAgentSessionCoordinates = {
    readonly sessionId: string;
};
export declare function startRemoteAgentSession(input: {
    readonly action: RuntimeRemoteAgentDispatchRequest;
    /** The dispatching turn's session principal, forwarded when `remote.forwardPrincipal` is set. */
    readonly auth?: SessionAuthContext | null;
    readonly callbackBaseUrl: string | undefined;
    readonly originAudience?: ChannelAudience;
    readonly activityObserver?: ActivityObserverConfig;
    /** The root initiator's principal, forwarded alongside {@link auth}. */
    readonly initiatorAuth?: SessionAuthContext | null;
    /**
     * Replay-stable identity of this create attempt. A retried dispatch step
     * re-sends the same value, letting the receiver return the child it already
     * created instead of starting a second one.
     */
    readonly operationId?: string;
    readonly parent?: Omit<SubagentParentContext, "lineage"> & {
        readonly lineage?: SubagentParentContext["lineage"];
    };
    readonly remote: ResolvedRuntimeRemoteAgentNode;
    readonly session: HarnessSession;
    readonly taskId?: string;
}): Promise<RemoteAgentSessionCoordinates>;
/** Continues one remote-agent session by its immutable session ID. */
export declare function continueRemoteAgentSession(input: {
    readonly activityObserver?: ActivityObserverConfig;
    /** The dispatching turn's session principal, forwarded when `remote.forwardPrincipal` is set. */
    readonly auth: SessionAuthContext | null;
    readonly callback?: {
        readonly callId: string;
        readonly subagentName: string;
        readonly taskId?: string;
        readonly token: string;
        readonly url: string;
    };
    readonly message: string;
    readonly outputSchema?: JsonObject;
    readonly remote: ResolvedRuntimeRemoteAgentNode;
    readonly sessionId: string;
}): Promise<void>;
/**
 * Failure of a continue-session request, classified at the HTTP boundary.
 * Exported so tests can exercise {@link isRetryableRemoteAgentContinueError}
 * with real instances instead of re-encoding the classification.
 */
export declare class RemoteAgentContinueRequestError extends Error {
    readonly deliveryAmbiguous: boolean;
    readonly retryable: boolean;
    constructor(message: string, options: {
        readonly deliveryAmbiguous: boolean;
        readonly retryable: boolean;
    });
}
/**
 * Returns true when a failed continue request may be retried. Only a
 * session that no longer exists (404 / SESSION_NOT_RESUMABLE) is permanent;
 * transient HTTP and network failures stay retryable so the dispatch step
 * keeps the agent handle and surfaces a retryable error instead of
 * discarding it — the model decides whether to try the same agentId again
 * (the step itself never re-sends: the callee may have accepted a delivery
 * whose response was lost).
 */
export declare function isRetryableRemoteAgentContinueError(error: unknown): boolean;
/** Whether the callee may have accepted the continuation before delivery failed. */
export declare function isAmbiguousRemoteAgentContinueError(error: unknown): boolean;
export declare function cancelRemoteAgentTurn(input: {
    readonly headers?: Record<string, string>;
    readonly remote: Pick<ResolvedRuntimeRemoteAgentNode, "auth" | "headers" | "name" | "url">;
    readonly sessionId: string;
    readonly taskId?: string;
    readonly turnId?: string;
}): Promise<CancelTurnResult>;
/** Retires one exact remote child session through eve's authenticated reset route. */
export declare function resetRemoteAgentSession(input: {
    readonly headers?: Record<string, string>;
    readonly remote: Pick<ResolvedRuntimeRemoteAgentNode, "auth" | "headers" | "name" | "url">;
    readonly sessionId: string;
}): Promise<ResetResponse>;
export declare function isRetryableRemoteAgentCancelError(error: unknown): boolean;
export declare function resolveRemoteAgentForAction(input: {
    readonly dynamicRemoteAgent?: DynamicRemoteAgentConfig;
    readonly nodeId: string;
    readonly registry: RuntimeSubagentRegistry["subagentsByNodeId"];
    readonly remoteAgentName: string;
}): ResolvedRuntimeRemoteAgentNode;
/**
 * Resolves authored outbound headers for a server-authored remote child event.
 *
 * `resolverId` is the key persisted on the `subagent.called` event (see
 * `SubagentCalledStreamEvent`): it identifies the authored credential
 * functions, never their resolved values. Lookup order mirrors how dispatch
 * chose the key — first as a subagent node id (static remote definition),
 * then as a `credentialsStepId` in the step registry (dynamic remote
 * definition). The matched static definition must still agree with the
 * event's `name`/`url`, so a stale or mismatched key fails closed rather
 * than minting headers for the wrong upstream.
 */
export declare function resolveRemoteAgentStreamHeaders(input: {
    readonly bundle: CompiledRuntimeAgentBundle;
    readonly name: string;
    readonly resolverId?: string;
    readonly url: string;
}): Promise<Record<string, string>>;
export {};