Skip to main content

Constructor

Parameters

string
required
JsonRpcConnection
required

Returns

LocalSession

Properties

undefined | readonly SessionConfigOption[]
required
Type: SessionConfigOptionThe session settings the agent exposes (model, mode, …) with their current and accepted values, as last reported on a session/new, session/load or session/set_config_option result. undefined until the agent has reported any.
JsonRpcConnection
required
string
required
undefined | Readonly<CognitionSessionMeta>
required
Type: CognitionSessionMetaThe latest session-level snapshot the agent stamped on an update (cognition.ai/session): status, URL, finished outcome, whether input is disabled, what the user must do. Cloud sessions carry it on most notifications, so this is current without waiting for a status event.
undefined | (notification: CognitionExtensionNotification) => void
required
Type: CognitionExtensionNotificationCalled with each typed _cognition.ai/* extension notification for this session (agent stopped, compaction, connection retries, …).
undefined | PermissionHandler
required
Type: PermissionHandlerAnswer this session’s permission requests (e.g. running a shell command). Takes precedence over the client-level onPermission for this session; when neither is set, requests are rejected so unattended runs are safe by default. Settable via createSession({ onPermission }) or directly.
undefined | string
required
The session’s web URL (cognition.ai/url session meta), once the agent has stamped it on an update — cloud sessions carry it from the first notification; local sessions have none.

Methods

backgroundSubagent()

Move a running subagent to the background (requires cognition.ai/subagentControl).

Parameters

string
required

Returns

Promise<void>

beginReplay()

Route updates into a replay buffer instead of the turn stream while a session/load request is in flight (the agent replays the session’s transcript as session/update notifications before responding).

cancel()

Cancel the in-flight turn, if any.

cancelSubagent()

Cancel a running subagent.

Parameters

string
required

Returns

Promise<void>

configOption()

The config option with this id (id on ACP v1, configId on v2), if reported.

Parameters

string
required

Returns

SessionConfigOption

enableTurnStateUpdates()

On ACP v2 connections the session/prompt response is an immediate ack; turns end on the idle state_update notification instead.

end()

Tell the agent the client is done with this session so it can release session-scoped resources (background shells, subagents, watchers). reason is free-form, for the agent’s logs.

Parameters

string
required

Returns

Promise<void>

endReplay()

Stop capturing replay updates and return them.

Returns

SessionUpdate

enrichPermissionRequest()

Enrich a permission request with the merged snapshot of the tool call it gates: agents often send only a toolCallId reference (the full tool call was already streamed as a tool_call update).

Parameters

Returns

PermissionRequest

events()

Every live update for this session as typed SessionEvents — the session-wide counterpart of stream. status events say when Devin starts working, is waiting on the user, or finishes; lifecycle when its runtime sleeps or exits; activity and typing what it is doing right now; message_delta, thought_delta, user_message, tool_call, plan and pull_request cover the transcript.

Parameters

Returns

SessionEvent

export()

Export the session transcript for diagnostics (_cognition.ai/diagnostics/sessionExport; requires the cognition.ai/diagnosticsSessionExport client capability, on by default).

Parameters

"forest"

Returns

SessionExportResponse

extNotify()

Send a session-scoped _cognition.ai/* notification (no response).

Parameters

M
required
SessionScopedParams<M>
required
Send a session-scoped _cognition.ai/* notification (no response).

Parameters

string
required
unknown

extRequest()

Send a session-scoped _cognition.ai/* request with this session’s id filled in. Typed when the method is in the generated registry (CognitionAgentResponseMap); any other _cognition.ai/* method is accepted untyped. Use this for Cognition methods that have no dedicated helper yet, e.g. session.extRequest(SESSION_RENAME_METHOD, { title: "Fix flaky test" }). An explicit directory variant is sent without adding a session id.

Parameters

M
required
SessionScopedParams<M>
required

Returns

CognitionRequestResult
Send a session-scoped _cognition.ai/* request with this session’s id filled in. Typed when the method is in the generated registry (CognitionAgentResponseMap); any other _cognition.ai/* method is accepted untyped. Use this for Cognition methods that have no dedicated helper yet, e.g. session.extRequest(SESSION_RENAME_METHOD, { title: "Fix flaky test" }). An explicit directory variant is sent without adding a session id.

Parameters

string
required
unknown

Returns

Promise<T>

foregroundSubagent()

Bring a backgrounded subagent to the foreground.

Parameters

string
required

Returns

Promise<void>

forkFromStep()

Fork a new session from targetNodeId without touching the workspace.

Parameters

number
required

Returns

RevertForkFromStepResponse

handleConnectionClosed()

The connection dropped: fail the in-flight turn (on v2 its prompt response was only an ack, so nothing else would ever end it) and release any drain barrier so callers aren’t stranded.

Parameters

handleExtension()

Parameters

string
required
unknown
required

handleReleased()

The client stopped routing notifications to this session (it was released or closed): nothing more will arrive, so end the session-wide iterators, present and future.

handleResult()

Record the session snapshot a session/new, session/resume, session/set_config_option or session/prompt result carries, so meta, url and configOptions are set without waiting for a live update.

Parameters

unknown
required

handleUpdate()

Route one session/update notification. Cloud agents stamp the session snapshot on the notification’s _meta rather than the update’s, so both are consulted.

Parameters

Pick<SessionNotification, "update" | "_meta">
required

instrument()

Report this session’s prompts, live updates, extensions and replay to observer until the session detaches.

Parameters

listRevertSteps()

The conversation steps that can be reverted to (requires cognition.ai/revert).

Returns

RevertListStepsResponse

models()

The models the CLI accepts for this session and the one in effect, as advertised on createSession / loadSession and refreshed by setModel. Fusion pairings appear as fusion-<leader>-sidekick-<sidekick> ids. undefined when the agent has not reported a model option.

Returns

SessionModels

postMessage()

Inject a user message into the in-flight turn. The agent folds the message into the running turn (interrupting the current inference if one is streaming) — it is not queued as a separate turn. Sent as a concurrent session/prompt; the returned promise settles when the turn ends, with the same result the original prompt resolves to.

Parameters

required

Returns

PromptResult

previewRevert()

What reverting to targetNodeId would undo, without doing it.

Parameters

number
required

Returns

RevertPreviewResponse

rename()

Rename the session (_cognition.ai/session/rename). Available on both cloud and local agents; check devin.supports("cognition.ai/sessionRename").

Parameters

string
required

Returns

Promise<void>

resumeRevert()

After reverting past an ask_user_question step, resume the agent from that question so it can be answered again.

Parameters

number
required

Returns

RevertResumeResponse

revert()

Revert the conversation and workspace to targetNodeId. The agent forks the history and hides this session from session/list; forkedSessionId in the result is the session to continue in.

Parameters

number
required

Returns

RevertExecuteResponse

reviseCommand()

Ask the agent to revise a command it proposed (editable commands) before it runs, explaining what to change in note.

Parameters

string
required
string
required

Returns

CommandReviseResponse

run()

Send a prompt and get a Turn: for await it for typed SessionEvents, await it for the SessionOutcome (stop reason, accumulated text, tool calls — and structured output validated against options.output, e.g. a zod schema).
With an output schema the outcome’s output is the validated T (validation failure rejects the turn; a turn that stops without end_turn resolves, but reading output throws); without one it is undefined.

Parameters

required
RunOptions<T> & { output: StandardSchema<T> }
required

Returns

Turn
Send a prompt and get a Turn: for await it for typed SessionEvents, await it for the SessionOutcome (stop reason, accumulated text, tool calls — and structured output validated against options.output, e.g. a zod schema).
With an output schema the outcome’s output is the validated T (validation failure rejects the turn; a turn that stops without end_turn resolves, but reading output throws); without one it is undefined.

Parameters

required
Omit<RunOptions<unknown>, "output"> & { output: undefined }

Returns

Turn
Send a prompt and get a Turn: for await it for typed SessionEvents, await it for the SessionOutcome (stop reason, accumulated text, tool calls — and structured output validated against options.output, e.g. a zod schema).
With an output schema the outcome’s output is the validated T (validation failure rejects the turn; a turn that stops without end_turn resolves, but reading output throws); without one it is undefined.

Parameters

required
RunOptions<T>
required

Returns

Turn

send()

Send a prompt and wait for the turn to finish, discarding updates. Pass a string for plain text, or content blocks (see the prompt builders) to attach images, audio, or embedded resources.

Parameters

required

Returns

PromptResult

setMode()

Switch the session’s permission mode (e.g. "ask", "accept-edits").

Parameters

string
required

Returns

Promise<void>

setModel()

Switch the model for subsequent turns. The CLI accepts only the models and Fusion pairings it advertises (see models); anything else rejects with a ModelRejectedError and leaves the current model.

Parameters

string | FusionModel
required

Returns

Promise<void>

share()

Create a share link for the session (requires cognition.ai/sessionShare).

Returns

SessionShareResponse

stream()

Send a prompt and yield typed SessionEvents as they stream (message/thought deltas, merged tool-call snapshots, plans…), returning the turn result once the agent stops. Use streamUpdates for the raw ACP notifications.

Parameters

required

Returns

SessionEventPromptResult

streamUpdates()

Send a prompt and yield the agent’s raw session/update notifications as they stream, returning the turn result once the agent stops.

Parameters

required

Returns

SessionUpdatePromptResult

updates()

Every live session/update for this session as it arrives — from turns this client started and from turns driven elsewhere alike. Subscribes on the first pull; ends when the consumer stops (break, return(), or signal) or the session is released, and throws ConnectionClosedError when the connection drops. Replayed history from loadSession() is not delivered here.

Parameters

Returns

SessionUpdate