@threadplane/ag-uiInterfacev0.3.7

Session

What createSession returns: the core AgentSession contract over an AG-UI backend, with the snapshot, the commands and the protocol's own evidence.

import type { Session } from '@threadplane/ag-ui';

Declaration

export interface Session<TState = unknown>  {
  readonly agentId?: string;
  checkStatus?(): Promise<void>;
  readonly clientTools?: AgentClientTools;
  dispose(): Promise<void>;
  getSnapshot(): SessionSnapshot<TState>;
  isDevelopmentRuntimeEnabled(): boolean;
  readonly lifecycle?: SessionLifecycleSource;
  load?(options?: {
        readonly signal?: AbortSignal;
    }): Promise<void>;
  onCustomEvent?(listener: (event: AgentSessionCustomEvent) => void): () => void;
  onRawEvent?(listener: (event: AGUIEvent) => void): () => void;
  readonly ready?: Promise<void>;
  reconcileInterrupt?(): Promise<void>;
  regenerate?(messageId: string, options?: {
        readonly signal?: AbortSignal;
    }): Promise<CompleteOutcome>;
  resume(responses: readonly InterruptResponse[], options?: ResumeOptions<TState>): Promise<CompleteOutcome>;
  retry?(): Promise<CompleteOutcome>;
  runWithoutMessage?(input?: {
        readonly state?: SubmitState<TState>;
    }, options?: {
        readonly signal?: AbortSignal;
    }): Promise<CompleteOutcome>;
  readonly stateType?: StateDeclaration<TState>;
  stop(): Promise<void>;
  submit(input: SubmitInput<TState>, options?: {
        readonly signal?: AbortSignal;
    }): Promise<CompleteOutcome>;
  subscribe(notify: () => void): () => void;
  readonly threadId?: string;
}

Type parameters

TState
Default: unknown

Members

agentId

The agent's name, when the session was given one.

readonly agentId?: string;

checkStatus · overload 1

Present with a persistence.reconcile. The control to offer when error.recovery is 'check': asks the reconciler what became of an answer that was sent and not proven taken, and settles the session only on a conclusive report (the answer's run ended, or the pause still waits). Anything less, and any failure to ask, leaves the error in place so the check can be offered again. Never sends the answer again. Rejects after disposal and while a run is going.

checkStatus?(): Promise<void>;

Returns

Promise<void>

clientTools

The core client-tool capability, on a session created without a handler map: setCatalog declares the tools each later request sends, the calls that wait are in the snapshot's pendingClientTools once a catalog was set, settle records a result as a tool record without running, flush saves the thread when the session has persistence, and resolve records a result and continues the run. A session created with a handler map runs its tools itself and leaves this undefined.

readonly clientTools?: AgentClientTools;

dispose · overload 1

dispose(): Promise<void>;

Returns

Promise<void>

getSnapshot · overload 1

getSnapshot(): SessionSnapshot<TState>;

Returns

SessionSnapshot<TState>

isDevelopmentRuntimeEnabled · overload 1

Whether a host may run development-install collection for this session: true unless the session was created with a telemetry option, false included. The session itself collects nothing.

isDevelopmentRuntimeEnabled(): boolean;

Returns

boolean

lifecycle

When the session first saw each milestone, in the shape the LangGraph session's lifecycle has. The factory always supplies it.

readonly lifecycle?: SessionLifecycleSource;

load · overload 1

Present with replay or persistence. Reads the thread again, as the session did when it was created: replay first, then storage. The snapshot's inputBlocked.reason is hydrating meanwhile, which is what a thread-loading indicator reads, and commands are refused until it settles. Rejects after disposal, while a run or a status check is going, and when storage could not be read; a failed replay does not reject it. The first load starts by itself at creation: ready resolves with it.

load?(options?: {
        readonly signal?: AbortSignal;
    }): Promise<void>;

Parameters

options · optional
{ readonly signal?: AbortSignal; }

Returns

Promise<void>

onCustomEvent · overload 1

Listens for CUSTOM events other than on_interrupt while runs stream. The factory always supplies it; it is optional so hand-written sessions need not. Returns an idempotent release. Nothing is replayed to a later listener, a throwing listener cannot fail the run, and nothing is delivered after disposal.

onCustomEvent?(listener: (event: AgentSessionCustomEvent) => void): () => void;

Parameters

listener · required
(event: AgentSessionCustomEvent) => void

Returns

() => void

onRawEvent · overload 1

Listens for every AG-UI protocol event the session applied to its snapshot, in arrival order, for a host that folds the full stream into a view of its own. The factory always supplies it. Each event is delivered after the snapshot shows it. Events the session ignores are not delivered: those of a superseded or stopped run, and those after a run's terminal event. A thread restored from replay delivers every replayed event, in order, once the snapshot shows the whole replay; a thread restored from persistence delivers none. With a reportOperationFailure a RUN_ERROR carries only the fixed message. Nothing is retained for a later listener, a throwing listener cannot fail the run, and nothing is delivered after disposal. Returns an idempotent release.

onRawEvent?(listener: (event: AGUIEvent) => void): () => void;

Parameters

listener · required
(event: AGUIEvent) => void

Returns

() => void

ready

Resolves once the thread is restored from replay or persistence, and at once for a session with neither. Commands issued before then wait for it. Rejects when the stored thread could not be read; a failed replay does not reject it. The factory always supplies it.

readonly ready?: Promise<void>;

reconcileInterrupt · overload 1

Present with persistence. Asks the configured reconciler what became of the saved thread and adopts whatever it reports, including an answer that only proves a resume started. Rejects after disposal, while a run or another check is going, without a reconciler, and when the backend does not know. Prefer checkStatus for the control a person is offered.

reconcileInterrupt?(): Promise<void>;

Returns

Promise<void>

regenerate · overload 1

Answers the prompt behind one assistant message again, as the Angular adapter's regenerate does. Takes the id of a root assistant record (or of the reasoning record a reasoning-only answer is shown under), drops every record after the user message that precedes it, and sends a run with that history and the current state. The prompt is not added again. Rejects without sending while a run is active, while a decision is waiting, after disposal, for an id that is not an assistant record, and when no user message precedes it. retry can send a failed regenerate again. With a client-tool catalog it also forgets the client-tool calls of the dropped records, and rejects while a blocker is installed.

regenerate?(messageId: string, options?: {
        readonly signal?: AbortSignal;
    }): Promise<CompleteOutcome>;

Parameters

messageId · required
string
options · optional
{ readonly signal?: AbortSignal; }

Returns

Promise<CompleteOutcome>

resume · overload 1

Answers the pending interrupts, as the core contract's resume: one response for each interrupt in the snapshot's interrupts, naming it by id. A response may also carry the protocol's metadata.

Rejects without sending when no interrupt is waiting, a run is active, an interrupt has expired, a response names an interrupt that is not pending or names one twice, or an interrupt is left unanswered. Resolves aborted without sending after disposal or when the signal is already aborted.

resume(responses: readonly InterruptResponse[], options?: ResumeOptions<TState>): Promise<CompleteOutcome>;

Parameters

responses · required
readonly InterruptResponse[]
options · optional
ResumeOptions<TState>

Returns

Promise<CompleteOutcome>

retry · overload 1

Sends the last submission again after its run failed with a backend RUN_ERROR. The request carries the history and state that submission sent, so no second user message is added and the failed run's output is dropped. Resolves aborted without sending while a run is active, when nothing failed or when the last run was not a failed submission. Rejects without sending when the error's recovery is not 'retry': the failure leaves the backend outcome open. With a client-tool catalog it sends the failed request again, whichever request of the command that was, and runs no handler a second time.

It also sends a failed resume again, unchanged, when that request provably reached no run: it was never made, or the backend refused it with its own RUN_ERROR before any RUN_STARTED. The pause is then pending again and the error's recovery is 'retry'. An answer that may have arrived is never sent twice, and a transport's own claim that a request did not leave is not taken as proof.

retry?(): Promise<CompleteOutcome>;

Returns

Promise<CompleteOutcome>

runWithoutMessage · overload 1

Runs the agent on the conversation as it stands, appending no user message, after merging input.state when given: the core contract's runWithoutMessage. Refused, like submit, while a decision is waiting. The factory always supplies it.

runWithoutMessage?(input?: {
        readonly state?: SubmitState<TState>;
    }, options?: {
        readonly signal?: AbortSignal;
    }): Promise<CompleteOutcome>;

Parameters

input · optional
{ readonly state?: SubmitState<TState>; }
options · optional
{ readonly signal?: AbortSignal; }

Returns

Promise<CompleteOutcome>

stateType

The state declaration this session was created with, when it has one.

readonly stateType?: StateDeclaration<TState>;

stop · overload 1

stop(): Promise<void>;

Returns

Promise<void>

submit · overload 1

submit(input: SubmitInput<TState>, options?: {
        readonly signal?: AbortSignal;
    }): Promise<CompleteOutcome>;

Parameters

input · required
SubmitInput<TState>
options · optional
{ readonly signal?: AbortSignal; }

Returns

Promise<CompleteOutcome>

subscribe · overload 1

subscribe(notify: () => void): () => void;

Parameters

notify · required
() => void

Returns

() => void

threadId

The thread this session owns. The factory always supplies it.

readonly threadId?: string;