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
TStateDefault: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
booleanlifecycle
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
() => voidonRawEvent · 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
() => voidready
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· requiredstringoptions· 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· requiredreadonly InterruptResponse[]options· optionalResumeOptions<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· requiredSubmitInput<TState>options· optional{ readonly signal?: AbortSignal; }
Returns
Promise<CompleteOutcome>subscribe · overload 1
subscribe(notify: () => void): () => void;Parameters
notify· required() => void
Returns
() => voidthreadId
The thread this session owns. The factory always supplies it.
readonly threadId?: string;