> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CloudDevin

> What every ACP Devin client provides, cloud or local.

```typescript
class CloudDevin extends AcpClient<CloudSession, CloudSessionOptions, CloudLoadSessionOptions> implements DevinClient<CloudSession, CloudSessionOptions, CloudLoadSessionOptions>
```

## Properties

**api** `DevinApiClient` *required*

Escape hatch: the full generated v3 API client.

**capabilities** `AgentCapabilitiesMeta` *required*

The agent's `cognition.ai/*` capability flags (`agentCapabilities._meta`).

**connection** `JsonRpcConnection` *required*

**initialize** `InitializeResult` *required*

The agent's `initialize` response (capabilities, auth methods).

**onAgentRequest** `undefined | AgentRequestHandler` *required*

**Type:** `undefined | AgentRequestHandler`

Answer agent → client requests the SDK does not handle itself (anything
but `session/request_permission`). Without a handler — or when the
handler returns `undefined` — built-in defaults apply (diagnostics report
none) and other methods are declined with `method not found`.

**onExtension** `undefined | (notification: CognitionExtensionNotification) =\> void` *required*

**Type:** `undefined | (notification: CognitionExtensionNotification) => void`

Observe connection-scoped `_cognition.ai/*` notifications — those without
a `sessionId` (or one that matches no tracked session), e.g.
`mcp/serversChanged` and `plugins/changed`. Session-scoped notifications
go to the owning session's `onExtension` instead.

**promptCapabilities** `PromptCapabilities` *required*

Which `session/prompt` content blocks the agent accepts, and the cloud size limits.

**protocolVersion** `number` *required*

The ACP protocol version the agent settled on (`1` or `2`).

## Methods

### \[asyncDispose]\()

```typescript
[asyncDispose](): Promise<void>
```

`await using devin = …` closes the client at scope exit, once the connection has shut down.

#### Returns

`Promise<void>`

### assertNotOpen()

```typescript
assertNotOpen(sessionId: string): void
```

Throw unless no session with this id is open on this client.

#### Parameters

**sessionId** `string` *required*

### attach()

```typescript
attach(sessionId: string, options?: CloudLoadSessionOptions): Promise<CloudSession>
```

Join an existing cloud session without replaying its transcript (`replay: "none"` unless overridden).

#### Parameters

**sessionId** `string` *required*

**options** `CloudLoadSessionOptions`

#### Returns

`Promise<CloudSession>`

### attachTo()

```typescript
attachTo(ws: WebSocketLike, options?: CloudDevinOptions): Promise<CloudDevin>
```

Attach to an already-open ACP WebSocket. Exposed for tests and custom
transports; most callers want `connect`. Closes `ws` if the
handshake fails.

#### Parameters

**ws** `WebSocketLike` *required*

**options** `CloudDevinOptions`

#### Returns

`Promise<CloudDevin>`

### close()

```typescript
close(): void
```

Shut down the connection. In-flight prompts reject.

### closePullRequest()

```typescript
closePullRequest(prPath: string): Promise<PrCloseResponse>
```

Close a pull request without merging (`github.com/owner/repo/pull/123`).

#### Parameters

**prPath** `string` *required*

#### Returns

`Promise<PrCloseResponse>`

### closeSession()

```typescript
closeSession(sessionId: string): Promise<void>
```

Detach from a session on this connection (ACP v2 `session/close`): the
agent cancels any turn this client started and stops sending it updates.
On v1 agents this only releases the session locally.

#### Parameters

**sessionId** `string` *required*

#### Returns

`Promise<void>`

### connect()

```typescript
connect(options?: CloudDevinOptions): Promise<CloudDevin>
```

Open the ACP WebSocket and perform the `initialize` handshake.

#### Parameters

**options** `CloudDevinOptions`

#### Returns

`Promise<CloudDevin>`

### createSecret()

```typescript
createSecret(params: SecretCreateParams): Promise<SecretCreateResponse>
```

Create an organization or user secret Devin can use in sessions.

#### Parameters

**params** `SecretCreateParams` *required*

#### Returns

`Promise<SecretCreateResponse>`

### createSession()

```typescript
createSession(options?: CloudSessionOptions): Promise<CloudSession>
```

Create a new cloud session. The Devin session itself is created lazily on
the first prompt; `orgId` and `repos` are applied to the pending session
before that (in one request when both are given).

#### Parameters

**options** `CloudSessionOptions`

#### Returns

`Promise<CloudSession>`

### extNotify()

```typescript
extNotify(method: M, params: CognitionRequestParams<M>): void
```

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

#### Parameters

**method** `M` *required*

**params** `CognitionRequestParams\<M\>` *required*

**Type:** `CognitionRequestParams<M>`

```typescript
extNotify(method: string, params?: unknown): void
```

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

#### Parameters

**method** `string` *required*

**params** `unknown`

### extRequest()

```typescript
extRequest(method: M, params: CognitionRequestParams<M>): Promise<CognitionRequestResult<M>>
```

Send a connection-scoped `_cognition.ai/*` request. Typed when the method
is in the generated registry (`CognitionAgentResponseMap`); any other
`_cognition.ai/*` method is accepted untyped. For session-scoped methods
prefer `AcpSession.extRequest`, which fills in the session id.

#### Parameters

**method** `M` *required*

**params** `CognitionRequestParams\<M\>` *required*

**Type:** `CognitionRequestParams<M>`

#### Returns

`Promise<CognitionRequestResult<M>>`

```typescript
extRequest(method: string, params?: unknown): Promise<T>
```

Send a connection-scoped `_cognition.ai/*` request. Typed when the method
is in the generated registry (`CognitionAgentResponseMap`); any other
`_cognition.ai/*` method is accepted untyped. For session-scoped methods
prefer `AcpSession.extRequest`, which fills in the session id.

#### Parameters

**method** `string` *required*

**params** `unknown`

#### Returns

`Promise<T>`

### handshake()

```typescript
handshake(connection: JsonRpcConnection, clientCapabilities?: CognitionClientCapabilities, acpVersion?: AcpProtocolVersion): Promise<InitializeResult>
```

Offer the selected version. V2 offers include v1 initialization fields
so v1-only agents can still negotiate v1.

#### Parameters

**connection** `JsonRpcConnection` *required*

**clientCapabilities** `CognitionClientCapabilities`

**acpVersion** `AcpProtocolVersion`

#### Returns

`Promise<InitializeResult>`

### launchSession()

```typescript
launchSession(input: PromptInput, options: LaunchSessionOptions<CloudSessionOptions, T> & { turn: RunOptions<T> & { output: StandardSchema<T> } }): Promise<LaunchedSession<CloudSession, T>>
```

Create a session and submit its first turn. Resolves on `turn.accepted`,
not the turn's outcome. Cancel explicitly with `session.cancel()`.
Startup errors after creation preserve `sessionId`; never retry blindly.

#### Parameters

**input** `PromptInput` *required*

**options** `LaunchSessionOptions\<CloudSessionOptions, T\> & \{ turn: RunOptions\<T\> & \{ output…` *required*

**Type:** `LaunchSessionOptions<CloudSessionOptions, T> & { turn: RunOptions<T> & { output: StandardSchema<T> } }`

#### Returns

`Promise<LaunchedSession<CloudSession, T>>`

```typescript
launchSession(input: PromptInput, options?: LaunchSessionOptions<CloudSessionOptions, unknown> & { turn: Omit<RunOptions<unknown>, "output"> & { output: undefined } }): Promise<LaunchedSession<CloudSession, undefined>>
```

Create a session and submit its first turn. Resolves on `turn.accepted`,
not the turn's outcome. Cancel explicitly with `session.cancel()`.
Startup errors after creation preserve `sessionId`; never retry blindly.

#### Parameters

**input** `PromptInput` *required*

**options** `LaunchSessionOptions\<CloudSessionOptions, unknown\> & \{ turn: Omit\<RunOptions\<un…`

**Type:** `LaunchSessionOptions<CloudSessionOptions, unknown> & { turn: Omit<RunOptions<unknown>, "output"> & { output: undefined } }`

#### Returns

`Promise<LaunchedSession<CloudSession, undefined>>`

```typescript
launchSession(input: PromptInput, options: LaunchSessionOptions<CloudSessionOptions, T>): Promise<LaunchedSession<CloudSession, undefined | T>>
```

Create a session and submit its first turn. Resolves on `turn.accepted`,
not the turn's outcome. Cancel explicitly with `session.cancel()`.
Startup errors after creation preserve `sessionId`; never retry blindly.

#### Parameters

**input** `PromptInput` *required*

**options** `LaunchSessionOptions\<CloudSessionOptions, T\>` *required*

**Type:** `LaunchSessionOptions<CloudSessionOptions, T>`

#### Returns

`Promise<LaunchedSession<CloudSession, undefined | T>>`

### listSessions()

```typescript
listSessions(options?: CloudListSessionsOptions): Promise<SessionInfo[]>
```

List the user's cloud sessions, most recently updated first. Returns the
first page only (the agent's page size); use `listSessionsPage` to
paginate with `cursor`.

#### Parameters

**options** `CloudListSessionsOptions`

#### Returns

`Promise<SessionInfo[]>`

### listSessionsPage()

```typescript
listSessionsPage(options?: CloudListSessionsOptions): Promise<CloudSessionsPage>
```

One page of the user's cloud sessions plus the cursor for the next.

#### Parameters

**options** `CloudListSessionsOptions`

#### Returns

`Promise<CloudSessionsPage>`

### loadSession()

```typescript
loadSession(sessionId: string, options?: CloudLoadSessionOptions): Promise<LoadedCloudSession>
```

Resume an existing cloud session by id (`devin-…`). On ACP v2 this is
`session/resume` (with `replayFrom` chosen by `options.replay`); on v1 it
is `session/load`, which always replays the whole transcript.

#### Parameters

**sessionId** `string` *required*

**options** `CloudLoadSessionOptions`

#### Returns

`Promise<LoadedCloudSession>`

### mcpServers()

```typescript
mcpServers(options: SessionOptions): McpServer[]
```

#### Parameters

**options** `SessionOptions` *required*

#### Returns

`McpServer[]`

### mergePullRequest()

```typescript
mergePullRequest(prPath: string, options?: MergePullRequestOptions): Promise<PrMergeResponse>
```

Merge a pull request Devin opened, via Devin's GitHub integration.
`prPath` is `github.com/owner/repo/pull/123`.

#### Parameters

**prPath** `string` *required*

**options** `MergePullRequestOptions`

#### Returns

`Promise<PrMergeResponse>`

### openSession()

```typescript
openSession(session: CloudSession, options: SessionOptions, establish?: () => Promise<unknown>): Promise<CloudSession>
```

Bring a freshly constructed session live: wire its permission handler,
route notifications to it, and run the agent request that establishes it
(`session/new` follow-ups such as choosing the model or organization). A
failing request releases the session and surfaces as a
[SessionStartupError](https://docs.devin.ai/sdk/reference/classes/SessionStartupError.md) carrying the allocated id.

#### Parameters

**session** `CloudSession` *required*

**options** `SessionOptions` *required*

**establish** `() =\> Promise\<unknown\>`

#### Returns

`Promise<CloudSession>`

### pullRequestMergeStatus()

```typescript
pullRequestMergeStatus(prPath: string): Promise<PrMergeStatusResponse>
```

Mergeability / CI state of a pull request (`github.com/owner/repo/pull/123`).

#### Parameters

**prPath** `string` *required*

#### Returns

`Promise<PrMergeStatusResponse>`

### pullRequestReviewJob()

```typescript
pullRequestReviewJob(prPath: string, jobId: string, versionId: string): Promise<PrReviewJobResponse>
```

One Devin Review job (with findings) for a pull request.

#### Parameters

**prPath** `string` *required*

**jobId** `string` *required*

**versionId** `string` *required*

#### Returns

`Promise<PrReviewJobResponse>`

### pullRequestReviewJobs()

```typescript
pullRequestReviewJobs(prPath: string): Promise<PrReviewJobsResponse>
```

Devin Review jobs that ran against a pull request.

#### Parameters

**prPath** `string` *required*

#### Returns

`Promise<PrReviewJobsResponse>`

### releaseSession()

```typescript
releaseSession(sessionId: string): void
```

Detach a session: active turns reject, observers end, and the handle cannot send requests.

#### Parameters

**sessionId** `string` *required*

### resumeSession()

```typescript
resumeSession(session: CloudSession, options: SessionOptions, load: () => Promise<unknown>): Promise<LoadedSession<CloudSession>>
```

Resume an existing session: like `openSession`, but the agent
replays history as `session/update` notifications before `load` settles;
those are captured and returned instead of being delivered live. Refuses
a session that is already open on this client, since loading it again
would steal its notification routing.

#### Parameters

**session** `CloudSession` *required*

**options** `SessionOptions` *required*

**load** `() =\> Promise\<unknown\>` *required*

#### Returns

`Promise<LoadedSession<CloudSession>>`

### supports()

```typescript
supports(capability: string): boolean
```

Whether the agent advertised a `cognition.ai/*` capability, e.g.
`devin.supports("cognition.ai/sessionRename")` before calling
`session.rename()`.

#### Parameters

**capability** `string` *required*

#### Returns

`boolean`

### track()

```typescript
track(session: AcpSession): void
```

Register a session so its notifications are routed to it.

#### Parameters

**session** `AcpSession` *required*

### untrack()

```typescript
untrack(sessionId: string): void
```

Stop routing notifications to a session (e.g. after deleting it).

#### Parameters

**sessionId** `string` *required*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.