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()
Parameters
SessionScopedParams<typeof void>
required
Type:
SessionScopedParamsReturns
PlanAcceptResponse
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
decideRepoIndex()
sourceEventId is the offer’s event).
Parameters
string
required
required
Returns
RepoIndexDecideResponse
editPlan()
Parameters
SessionScopedParams<typeof void>
required
Type:
SessionScopedParamsReturns
PlanEditResponse
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>
getNetPolicy()
Returns
NetPolicyGetResponse
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:
SessionNotificationheartbeat()
_cognition.ai/session/heartbeat). Send periodically during long
unattended waits.
Returns
Promise<void>
instrument()
observer until the session detaches.
Parameters
required
listSecrets()
Returns
SecretListResponse
loadPage()
_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()
Parameters
boolean
Returns
Promise<void>
postMessage()
session/prompt; the returned promise settles when the turn ends, with
the same result the original prompt resolves to.
Parameters
required
Returns
PromptResult
provideSecret()
request_secret), optionally saving it.
Parameters
SessionScopedParams<typeof void>
required
Type:
SessionScopedParamsReturns
SecretProvideResponse
reboot()
_cognition.ai/session/reboot).
Returns
Promise<void>
rename()
_cognition.ai/session/rename). Available on both
cloud and local agents; check devin.supports("cognition.ai/sessionRename").
Parameters
string
required
Returns
Promise<void>
respondToPermission()
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
Type:
SessionScopedParamsReturns
PermissionRespondResponse
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
saveSecret()
suggest_save_secret request from the agent.
Parameters
SessionScopedParams<typeof void>
required
Type:
SessionScopedParamsReturns
SecretSaveResponse
send()
prompt builders) to
attach images, audio, or embedded resources.
Parameters
required
Returns
PromptResult
sendFeedback()
eventId is given.
Parameters
SessionScopedParams<typeof void>
required
Type:
SessionScopedParamsReturns
SessionFeedbackResponse
setMode()
"ask", "accept-edits").
Parameters
string
required
Returns
Promise<void>
setOrg()
setRepos). Changing the organization resets any repositories
set earlier, since they are scoped to it.
Parameters
string
required
string[]
Returns
Promise<void>
setRepos()
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()
Parameters
number
required
Returns
SessionSpendingLimitSetResponse
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
togglePlanConfirmMode()
planEventId.
Parameters
string
required
Returns
PlanToggleConfirmModeResponse
updateNetPolicy()
request_network_access from
the agent (networkAccessRequestId + networkAccessDomains /
denyNetworkAccessRequest).
Parameters
SessionScopedParams<typeof void>
required
Type:
SessionScopedParamsReturns
NetPolicyUpdateResponse
updateQueue()
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
Type:
SessionScopedParamsReturns
QueuedMessagesUpdateResponse
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
