Skip to main content

Constructor

Parameters

string
required
JsonRpcConnection
required

Returns

CloudSession

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

acceptPlan()

Accept a plan the agent proposed so it starts executing.

Parameters

SessionScopedParams<typeof void>
required

Returns

PlanAcceptResponse

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.

configOption()

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

Parameters

string
required

Returns

SessionConfigOption

decideRepoIndex()

Answer the agent’s offer to index a repository (sourceEventId is the offer’s event).

Parameters

string
required

Returns

RepoIndexDecideResponse

editPlan()

Replace the body (and optionally title / summary) of a proposed plan.

Parameters

SessionScopedParams<typeof void>
required

Returns

PlanEditResponse

enableTurnStateUpdates()

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

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

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>

getNetPolicy()

The session’s network allowlist policy.

Returns

NetPolicyGetResponse

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

heartbeat()

Keep the session’s VM from idling out while a client is attached (_cognition.ai/session/heartbeat). Send periodically during long unattended waits.

Returns

Promise<void>

instrument()

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

Parameters

listSecrets()

The secrets (names only) available to this session.

Returns

SecretListResponse

loadPage()

Backfill older history after a tail replay (_cognition.ai/session/loadPage): the dense page of events whose ordinals are strictly below startIndex (start with LoadedCloudSession.tail.olderIndex). The server defaults limit to its page size and caps it.

Parameters

number
required
number

Returns

HistoryPage

markRead()

Mark the session read (or unread again) for the current user.

Parameters

boolean

Returns

Promise<void>

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

provideSecret()

Hand the agent a secret it asked for (request_secret), optionally saving it.

Parameters

SessionScopedParams<typeof void>
required

Returns

SecretProvideResponse

reboot()

Reboot the session’s VM (_cognition.ai/session/reboot).

Returns

Promise<void>

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>

respondToPermission()

Answer a permission request by id — for requests surfaced as permission_request tool calls in the transcript (e.g. raised while no client was attached), as opposed to live session/request_permission requests, which go through onPermission.

Parameters

SessionScopedParams<typeof void>
required

Returns

PermissionRespondResponse

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

saveSecret()

Decide on a suggest_save_secret request from the agent.

Parameters

SessionScopedParams<typeof void>
required

Returns

SecretSaveResponse

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

sendFeedback()

Rate the session, or a single message when eventId is given.

Parameters

SessionScopedParams<typeof void>
required

Returns

SessionFeedbackResponse

setMode()

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

Parameters

string
required

Returns

Promise<void>

setOrg()

Select the organization the session is created in (before the first prompt), optionally with its repositories in the same request (see setRepos). Changing the organization resets any repositories set earlier, since they are scoped to it.

Parameters

string
required
string[]

Returns

Promise<void>

setRepos()

Repositories this session is about, set before the first prompt — the web app’s repository picker. Devin treats them as the relevant repos (prompt hint, knowledge and routing scope), runs their configured setup on boot when the organization has one, and clones anything else on demand; access is still decided by the organization’s git permissions. Names are the ones devin.api.repositories.listRepositories returns (owner/repo on github.com, host/path elsewhere) — only repositories granted to the organization are selectable, though Devin can still clone public ones when asked in the prompt. Throws a DevinError naming any repository the organization cannot access instead of letting the agent drop it silently.

Parameters

string[]
required

Returns

Promise<void>

setSpendingLimit()

Cap the ACUs this session may spend.

Parameters

number
required

Returns

SessionSpendingLimitSetResponse

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

togglePlanConfirmMode()

Toggle whether the agent must confirm before acting on the plan at planEventId.

Parameters

string
required

Returns

PlanToggleConfirmModeResponse

updateNetPolicy()

Replace the network policy, or answer a request_network_access from the agent (networkAccessRequestId + networkAccessDomains / denyNetworkAccessRequest).

Parameters

SessionScopedParams<typeof void>
required

Returns

NetPolicyUpdateResponse

updateQueue()

Edit the send queue: messages held to be delivered once the agent is ready (op: "add" | "edit" | "remove" | "send_now" | "hold" | "reorder" | "clear"). The agent echoes the new queue via _cognition.ai/messages_in_queued.

Parameters

SessionScopedParams<"_cognition.ai/queuedMessages/update">
required

Returns

QueuedMessagesUpdateResponse

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