Constructor
Parameters
string
required
JsonRpcConnection
required
Returns
AcpSession
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
beginReplay()
session/load request is in flight (the agent replays the session’s
transcript as session/update notifications before responding).
cancel()
configOption()
id on ACP v1, configId on v2), if reported.
Parameters
string
required
Returns
SessionConfigOption
enableTurnStateUpdates()
session/prompt response is an immediate ack;
turns end on the idle state_update notification instead.
endReplay()
Returns
SessionUpdate
enrichPermissionRequest()
toolCallId reference (the full tool
call was already streamed as a tool_call update).
Parameters
required
Returns
PermissionRequest
events()
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()
_cognition.ai/* notification (no response).
Parameters
M
required
SessionScopedParams<M>
required
Type:
SessionScopedParams_cognition.ai/* notification (no response).
Parameters
string
required
unknown
extRequest()
_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
Type:
SessionScopedParamsReturns
CognitionRequestResult
_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>
handleConnectionClosed()
Parameters
required
handleExtension()
Parameters
string
required
unknown
required
handleReleased()
handleResult()
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()
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
Type:
SessionNotificationinstrument()
observer until the session detaches.
Parameters
required
postMessage()
session/prompt; the returned promise settles when the turn ends, with
the same result the original prompt resolves to.
Parameters
required
Returns
PromptResult
rename()
_cognition.ai/session/rename). Available on both
cloud and local agents; check devin.supports("cognition.ai/sessionRename").
Parameters
string
required
Returns
Promise<void>
run()
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).
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
Type:
RunOptionsStandardSchemaReturns
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).
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 }
Type:
RunOptionsReturns
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).
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
Type:
RunOptionsReturns
Turn
send()
prompt builders) to
attach images, audio, or embedded resources.
Parameters
required
Returns
PromptResult
setMode()
"ask", "accept-edits").
Parameters
string
required
Returns
Promise<void>
stream()
streamUpdates for the
raw ACP notifications.
Parameters
required
Returns
SessionEventPromptResult
streamUpdates()
session/update notifications
as they stream, returning the turn result once the agent stops.
Parameters
required
Returns
SessionUpdatePromptResult
updates()
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