> ## 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.

# LocalSession

> A session running on this machine via the Devin CLI.

```typescript
class LocalSession extends AcpSession
```

## Constructor

```typescript
LocalSession(id: string, connection: JsonRpcConnection): LocalSession
```

### Parameters

**id** `string` *required*

**connection** `JsonRpcConnection` *required*

### Returns

`LocalSession`

## Properties

**configOptions** `undefined | readonly SessionConfigOption[]` *required*

**Type:** `undefined | readonly SessionConfigOption[]`

The 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.

**connection** `JsonRpcConnection` *required*

**id** `string` *required*

**meta** `undefined | Readonly\<CognitionSessionMeta\>` *required*

**Type:** `undefined | Readonly<CognitionSessionMeta>`

The 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.

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

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

Called with each typed `_cognition.ai/*` extension notification for this
session (agent stopped, compaction, connection retries, …).

**onPermission** `undefined | PermissionHandler` *required*

**Type:** `undefined | PermissionHandler`

Answer 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.

**url** `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()

```typescript
backgroundSubagent(agentId: string): Promise<void>
```

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

#### Parameters

**agentId** `string` *required*

#### Returns

`Promise<void>`

### beginReplay()

```typescript
beginReplay(): void
```

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()

```typescript
cancel(): void
```

Cancel the in-flight turn, if any.

### cancelSubagent()

```typescript
cancelSubagent(agentId: string): Promise<void>
```

Cancel a running subagent.

#### Parameters

**agentId** `string` *required*

#### Returns

`Promise<void>`

### configOption()

```typescript
configOption(id: string): undefined | SessionConfigOption
```

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

#### Parameters

**id** `string` *required*

#### Returns

`undefined | SessionConfigOption`

### enableTurnStateUpdates()

```typescript
enableTurnStateUpdates(): void
```

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

### end()

```typescript
end(reason: string, options?: EndSessionOptions): Promise<void>
```

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

**reason** `string` *required*

**options** `EndSessionOptions`

#### Returns

`Promise<void>`

### endReplay()

```typescript
endReplay(): SessionUpdate[]
```

Stop capturing replay updates and return them.

#### Returns

`SessionUpdate[]`

### enrichPermissionRequest()

```typescript
enrichPermissionRequest(request: PermissionRequest): PermissionRequest
```

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

**request** `PermissionRequest` *required*

#### Returns

`PermissionRequest`

### events()

```typescript
events(options?: ObserveOptions): AsyncGenerator<SessionEvent>
```

Every live update for this session as typed [SessionEvent](https://docs.devin.ai/sdk/reference/types/SessionEvent.md)s — 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.

```ts
const session = await devin.attach("devin-…");
for await (const event of session.events()) {
  if (event.type === "status") console.log(event.status, event.userActionRequired);
}
```

#### Parameters

**options** `ObserveOptions`

#### Returns

`AsyncGenerator<SessionEvent>`

### export()

```typescript
export(format?: "forest"): Promise<SessionExportResponse>
```

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

#### Parameters

**format** `"forest"`

#### Returns

`Promise<SessionExportResponse>`

### extNotify()

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

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

#### Parameters

**method** `M` *required*

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

**Type:** `SessionScopedParams<M>`

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

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

#### Parameters

**method** `string` *required*

**params** `unknown`

### extRequest()

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

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

**method** `M` *required*

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

**Type:** `SessionScopedParams<M>`

#### Returns

`Promise<CognitionRequestResult<M>>`

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

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

**method** `string` *required*

**params** `unknown`

#### Returns

`Promise<T>`

### foregroundSubagent()

```typescript
foregroundSubagent(agentId: string): Promise<void>
```

Bring a backgrounded subagent to the foreground.

#### Parameters

**agentId** `string` *required*

#### Returns

`Promise<void>`

### forkFromStep()

```typescript
forkFromStep(targetNodeId: number): Promise<RevertForkFromStepResponse>
```

Fork a new session from `targetNodeId` without touching the workspace.

#### Parameters

**targetNodeId** `number` *required*

#### Returns

`Promise<RevertForkFromStepResponse>`

### handleConnectionClosed()

```typescript
handleConnectionClosed(error: ConnectionClosedError): void
```

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

**error** `ConnectionClosedError` *required*

### handleExtension()

```typescript
handleExtension(method: string, params: unknown): void
```

#### Parameters

**method** `string` *required*

**params** `unknown` *required*

### handleReleased()

```typescript
handleReleased(): void
```

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()

```typescript
handleResult(result: unknown): void
```

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

**result** `unknown` *required*

### handleUpdate()

```typescript
handleUpdate(__namedParameters: Pick<SessionNotification, "update" | "_meta">): void
```

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

**\_\_namedParameters** `Pick\<SessionNotification, "update" | "_meta"\>` *required*

**Type:** `Pick<SessionNotification, "update" | "_meta">`

### instrument()

```typescript
instrument(observer: SessionObserver): void
```

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

#### Parameters

**observer** `SessionObserver` *required*

### listRevertSteps()

```typescript
listRevertSteps(): Promise<RevertListStepsResponse>
```

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

#### Returns

`Promise<RevertListStepsResponse>`

### models()

```typescript
models(): undefined | SessionModels
```

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

`undefined | SessionModels`

### postMessage()

```typescript
postMessage(input: PromptInput, options?: PromptOptions): Promise<PromptResult>
```

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

**input** `PromptInput` *required*

**options** `PromptOptions`

#### Returns

`Promise<PromptResult>`

### previewRevert()

```typescript
previewRevert(targetNodeId: number): Promise<RevertPreviewResponse>
```

What reverting to `targetNodeId` would undo, without doing it.

#### Parameters

**targetNodeId** `number` *required*

#### Returns

`Promise<RevertPreviewResponse>`

### rename()

```typescript
rename(title: string): Promise<void>
```

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

#### Parameters

**title** `string` *required*

#### Returns

`Promise<void>`

### resumeRevert()

```typescript
resumeRevert(questionNodeId: number): Promise<RevertResumeResponse>
```

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

#### Parameters

**questionNodeId** `number` *required*

#### Returns

`Promise<RevertResumeResponse>`

### revert()

```typescript
revert(targetNodeId: number, options?: RevertOptions): Promise<RevertExecuteResponse>
```

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

**targetNodeId** `number` *required*

**options** `RevertOptions`

#### Returns

`Promise<RevertExecuteResponse>`

### reviseCommand()

```typescript
reviseCommand(command: string, note: string): Promise<CommandReviseResponse>
```

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

#### Parameters

**command** `string` *required*

**note** `string` *required*

#### Returns

`Promise<CommandReviseResponse>`

### run()

```typescript
run(input: PromptInput, options: RunOptions<T> & { output: StandardSchema<T> }): Turn<T>
```

Send a prompt and get a [Turn](https://docs.devin.ai/sdk/reference/classes/Turn.md): `for await` it for typed
[SessionEvent](https://docs.devin.ai/sdk/reference/types/SessionEvent.md)s, `await` it for the [SessionOutcome](https://docs.devin.ai/sdk/reference/interfaces/SessionOutcome.md)
(stop reason, accumulated text, tool calls — and structured output
validated against `options.output`, e.g. a zod schema).

```ts
const outcome = await session.run("Summarize the repo", {
  output: z.object({ summary: z.string() }),
});
outcome.output.summary;
```

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

**input** `PromptInput` *required*

**options** `RunOptions\<T\> & \{ output: StandardSchema\<T\> \}` *required*

**Type:** `RunOptions<T> & { output: StandardSchema<T> }`

#### Returns

`Turn<T>`

```typescript
run(input: PromptInput, options?: Omit<RunOptions<unknown>, "output"> & { output: undefined }): Turn
```

Send a prompt and get a [Turn](https://docs.devin.ai/sdk/reference/classes/Turn.md): `for await` it for typed
[SessionEvent](https://docs.devin.ai/sdk/reference/types/SessionEvent.md)s, `await` it for the [SessionOutcome](https://docs.devin.ai/sdk/reference/interfaces/SessionOutcome.md)
(stop reason, accumulated text, tool calls — and structured output
validated against `options.output`, e.g. a zod schema).

```ts
const outcome = await session.run("Summarize the repo", {
  output: z.object({ summary: z.string() }),
});
outcome.output.summary;
```

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

**input** `PromptInput` *required*

**options** `Omit\<RunOptions\<unknown\>, "output"\> & \{ output: undefined \}`

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

#### Returns

`Turn`

```typescript
run(input: PromptInput, options: RunOptions<T>): Turn<undefined | T>
```

Send a prompt and get a [Turn](https://docs.devin.ai/sdk/reference/classes/Turn.md): `for await` it for typed
[SessionEvent](https://docs.devin.ai/sdk/reference/types/SessionEvent.md)s, `await` it for the [SessionOutcome](https://docs.devin.ai/sdk/reference/interfaces/SessionOutcome.md)
(stop reason, accumulated text, tool calls — and structured output
validated against `options.output`, e.g. a zod schema).

```ts
const outcome = await session.run("Summarize the repo", {
  output: z.object({ summary: z.string() }),
});
outcome.output.summary;
```

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

**input** `PromptInput` *required*

**options** `RunOptions\<T\>` *required*

**Type:** `RunOptions<T>`

#### Returns

`Turn<undefined | T>`

### send()

```typescript
send(input: PromptInput, options?: PromptOptions): Promise<PromptResult>
```

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

**input** `PromptInput` *required*

**options** `PromptOptions`

#### Returns

`Promise<PromptResult>`

### setMode()

```typescript
setMode(modeId: string): Promise<void>
```

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

#### Parameters

**modeId** `string` *required*

#### Returns

`Promise<void>`

### setModel()

```typescript
setModel(model: string | FusionModel): Promise<void>
```

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](https://docs.devin.ai/sdk/reference/classes/ModelRejectedError.md) and leaves the current model.

#### Parameters

**model** `string | FusionModel` *required*

**Type:** `string | FusionModel`

#### Returns

`Promise<void>`

### share()

```typescript
share(): Promise<SessionShareResponse>
```

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

#### Returns

`Promise<SessionShareResponse>`

### stream()

```typescript
stream(input: PromptInput, options?: PromptOptions): AsyncGenerator<SessionEvent, PromptResult, undefined>
```

Send a prompt and yield typed [SessionEvent](https://docs.devin.ai/sdk/reference/types/SessionEvent.md)s 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

**input** `PromptInput` *required*

**options** `PromptOptions`

#### Returns

`AsyncGenerator<SessionEvent, PromptResult, undefined>`

### streamUpdates()

```typescript
streamUpdates(input: PromptInput, options?: PromptOptions): AsyncGenerator<SessionUpdate, PromptResult, undefined>
```

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

#### Parameters

**input** `PromptInput` *required*

**options** `PromptOptions`

#### Returns

`AsyncGenerator<SessionUpdate, PromptResult, undefined>`

### updates()

```typescript
updates(__namedParameters?: ObserveOptions): AsyncGenerator<SessionUpdate>
```

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](https://docs.devin.ai/sdk/reference/classes/ConnectionClosedError.md) when the connection drops. Replayed history
from `loadSession()` is not delivered here.

#### Parameters

**\_\_namedParameters** `ObserveOptions`

#### Returns

`AsyncGenerator<SessionUpdate>`


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