# Store

<!-- https://uncage.vercel.app/docs/api/core/interfaces/store/ -->

Defined in: core/src/store/store.ts:15

## Methods

### appendEvent()

```ts
appendEvent<K>(e): Promise<EventEnvelope<K>>;
```

Defined in: core/src/store/store.ts:27

#### Type Parameters

| Type Parameter |
| ------ |
| <a id="type-parameter-k"></a> `K` *extends* \| `"session.created"` \| `"session.updated"` \| `"run.started"` \| `"run.updated"` \| `"run.completed"` \| `"run.failed"` \| `"run.cancelled"` \| `"run.interrupted"` \| `"message.started"` \| `"message.delta"` \| `"message.completed"` \| `"tool.started"` \| `"tool.updated"` \| `"tool.completed"` \| `"tool.failed"` \| `"approval.requested"` \| `"approval.updated"` \| `"approval.resolved"` \| `"system.warning"` |

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `e` | `Omit`\<`EventEnvelope`\<`K`\>, `"eventId"` \| `"sequence"` \| `"schemaVersion"`\> |

#### Returns

`Promise`\<`EventEnvelope`\<`K`\>\>

***

### casApproval()

```ts
casApproval(
   id, 
   expect, 
   next
): Promise<
  | {
  allowedScopes: ("once" | "session")[];
  availableDecisions: ("deny" | "allow_once" | "allow_session")[];
  category: "file" | "mcp" | "shell" | "network" | "other";
  createdAt: string;
  decision?: "deny" | "allow";
  description?: string;
  expiresAt: string;
  id: string;
  runId: string;
  runtimeId: string;
  sessionId: string;
  state:   | "failed"
     | "cancelled"
     | "pending"
     | "submitting"
     | "approved"
     | "denied"
     | "expired"
     | "reconciling";
  target: {
     command?: string;
     cwd?: string;
     host?: string;
     path?: string;
  };
  title: string;
  toolId?: string;
  version: number;
}
| null>;
```

Defined in: core/src/store/store.ts:38

Atomic compare-and-swap on (state, version). Returns null when the race was lost.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `id` | `string` |
| `expect` | \{ `state`: \| `"failed"` \| `"cancelled"` \| `"pending"` \| `"submitting"` \| `"approved"` \| `"denied"` \| `"expired"` \| `"reconciling"`; `version`: `number`; \} |
| `expect.state` | \| `"failed"` \| `"cancelled"` \| `"pending"` \| `"submitting"` \| `"approved"` \| `"denied"` \| `"expired"` \| `"reconciling"` |
| `expect.version` | `number` |
| `next` | `Partial`\<`ApprovalRequest`\> |

#### Returns

`Promise`\<
  \| \{
  `allowedScopes`: (`"once"` \| `"session"`)[];
  `availableDecisions`: (`"deny"` \| `"allow_once"` \| `"allow_session"`)[];
  `category`: `"file"` \| `"mcp"` \| `"shell"` \| `"network"` \| `"other"`;
  `createdAt`: `string`;
  `decision?`: `"deny"` \| `"allow"`;
  `description?`: `string`;
  `expiresAt`: `string`;
  `id`: `string`;
  `runId`: `string`;
  `runtimeId`: `string`;
  `sessionId`: `string`;
  `state`:   \| `"failed"`
     \| `"cancelled"`
     \| `"pending"`
     \| `"submitting"`
     \| `"approved"`
     \| `"denied"`
     \| `"expired"`
     \| `"reconciling"`;
  `target`: \{
     `command?`: `string`;
     `cwd?`: `string`;
     `host?`: `string`;
     `path?`: `string`;
  \};
  `title`: `string`;
  `toolId?`: `string`;
  `version`: `number`;
\}
  \| `null`\>

***

### close()

```ts
close(): Promise<void>;
```

Defined in: core/src/store/store.ts:58

#### Returns

`Promise`\<`void`\>

***

### createApproval()

```ts
createApproval(a): Promise<void>;
```

Defined in: core/src/store/store.ts:34

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `a` | \{ `allowedScopes`: (`"once"` \| `"session"`)[]; `availableDecisions`: (`"deny"` \| `"allow_once"` \| `"allow_session"`)[]; `category`: `"file"` \| `"mcp"` \| `"shell"` \| `"network"` \| `"other"`; `createdAt`: `string`; `decision?`: `"deny"` \| `"allow"`; `description?`: `string`; `expiresAt`: `string`; `id`: `string`; `runId`: `string`; `runtimeId`: `string`; `sessionId`: `string`; `state`: \| `"failed"` \| `"cancelled"` \| `"pending"` \| `"submitting"` \| `"approved"` \| `"denied"` \| `"expired"` \| `"reconciling"`; `target`: \{ `command?`: `string`; `cwd?`: `string`; `host?`: `string`; `path?`: `string`; \}; `title`: `string`; `toolId?`: `string`; `version`: `number`; \} |
| `a.allowedScopes` | (`"once"` \| `"session"`)[] |
| `a.availableDecisions` | (`"deny"` \| `"allow_once"` \| `"allow_session"`)[] |
| `a.category` | `"file"` \| `"mcp"` \| `"shell"` \| `"network"` \| `"other"` |
| `a.createdAt` | `string` |
| `a.decision?` | `"deny"` \| `"allow"` |
| `a.description?` | `string` |
| `a.expiresAt` | `string` |
| `a.id` | `string` |
| `a.runId` | `string` |
| `a.runtimeId` | `string` |
| `a.sessionId` | `string` |
| `a.state` | \| `"failed"` \| `"cancelled"` \| `"pending"` \| `"submitting"` \| `"approved"` \| `"denied"` \| `"expired"` \| `"reconciling"` |
| `a.target` | \{ `command?`: `string`; `cwd?`: `string`; `host?`: `string`; `path?`: `string`; \} |
| `a.target.command?` | `string` |
| `a.target.cwd?` | `string` |
| `a.target.host?` | `string` |
| `a.target.path?` | `string` |
| `a.title` | `string` |
| `a.toolId?` | `string` |
| `a.version` | `number` |

#### Returns

`Promise`\<`void`\>

***

### createAttachment()

```ts
createAttachment(a): Promise<void>;
```

Defined in: core/src/store/store.ts:43

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `a` | [`StoredAttachment`](https://uncage.vercel.app/docs/api/core/type-aliases/storedattachment.md) |

#### Returns

`Promise`\<`void`\>

***

### createRun()

```ts
createRun(r): Promise<void>;
```

Defined in: core/src/store/store.ts:22

`r.attachments` is not stored here; runs are hydrated from attachments referenced by them.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `r` | \{ `attachments?`: `object`[]; `createdAt`: `string`; `endedAt?`: `string`; `error?`: \{ `code`: \| `"runtime_unavailable"` \| `"auth_required"` \| `"unsupported_capability"` \| `"invalid_workspace"` \| `"session_busy"` \| `"session_read_only"` \| `"not_found"` \| `"unauthorized"` \| `"forbidden_origin"` \| `"invalid_request"` \| `"approval_expired"` \| `"approval_already_resolved"` \| `"event_replay_unavailable"` \| `"runtime_disconnected"` \| `"policy_denied"` \| `"store_locked"` \| `"attachment_too_large"` \| `"attachment_type_unsupported"` \| `"machine_offline"` \| `"machine_not_found"` \| `"upgrade_required"` \| `"tool_failed"` \| `"device_code_expired"` \| `"rate_limited"` \| `"internal_error"`; `details?`: `Record`\<`string`, `unknown`\>; `hint?`: `string`; `message`: `string`; `requestId?`: `string`; `retryable`: `boolean`; \}; `id`: `string`; `prompt`: `string`; `sessionId`: `string`; `startedAt?`: `string`; `state`: \| `"queued"` \| `"running"` \| `"waiting_approval"` \| `"completed"` \| `"failed"` \| `"cancelled"` \| `"interrupted"`; \} |
| `r.attachments?` | `object`[] |
| `r.createdAt` | `string` |
| `r.endedAt?` | `string` |
| `r.error?` | \{ `code`: \| `"runtime_unavailable"` \| `"auth_required"` \| `"unsupported_capability"` \| `"invalid_workspace"` \| `"session_busy"` \| `"session_read_only"` \| `"not_found"` \| `"unauthorized"` \| `"forbidden_origin"` \| `"invalid_request"` \| `"approval_expired"` \| `"approval_already_resolved"` \| `"event_replay_unavailable"` \| `"runtime_disconnected"` \| `"policy_denied"` \| `"store_locked"` \| `"attachment_too_large"` \| `"attachment_type_unsupported"` \| `"machine_offline"` \| `"machine_not_found"` \| `"upgrade_required"` \| `"tool_failed"` \| `"device_code_expired"` \| `"rate_limited"` \| `"internal_error"`; `details?`: `Record`\<`string`, `unknown`\>; `hint?`: `string`; `message`: `string`; `requestId?`: `string`; `retryable`: `boolean`; \} |
| `r.error.code` | \| `"runtime_unavailable"` \| `"auth_required"` \| `"unsupported_capability"` \| `"invalid_workspace"` \| `"session_busy"` \| `"session_read_only"` \| `"not_found"` \| `"unauthorized"` \| `"forbidden_origin"` \| `"invalid_request"` \| `"approval_expired"` \| `"approval_already_resolved"` \| `"event_replay_unavailable"` \| `"runtime_disconnected"` \| `"policy_denied"` \| `"store_locked"` \| `"attachment_too_large"` \| `"attachment_type_unsupported"` \| `"machine_offline"` \| `"machine_not_found"` \| `"upgrade_required"` \| `"tool_failed"` \| `"device_code_expired"` \| `"rate_limited"` \| `"internal_error"` |
| `r.error.details?` | `Record`\<`string`, `unknown`\> |
| `r.error.hint?` | `string` |
| `r.error.message` | `string` |
| `r.error.requestId?` | `string` |
| `r.error.retryable` | `boolean` |
| `r.id` | `string` |
| `r.prompt` | `string` |
| `r.sessionId` | `string` |
| `r.startedAt?` | `string` |
| `r.state` | \| `"queued"` \| `"running"` \| `"waiting_approval"` \| `"completed"` \| `"failed"` \| `"cancelled"` \| `"interrupted"` |

#### Returns

`Promise`\<`void`\>

***

### createSession()

```ts
createSession(s): Promise<void>;
```

Defined in: core/src/store/store.ts:16

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `s` | `object` & `object` |

#### Returns

`Promise`\<`void`\>

***

### deleteOrphanAttachments()

```ts
deleteOrphanAttachments(olderThan): Promise<StoredAttachment[]>;
```

Defined in: core/src/store/store.ts:55

Deletes unreferenced attachments created before `olderThan`; returns the deleted rows.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `olderThan` | `Date` |

#### Returns

`Promise`\<[`StoredAttachment`](https://uncage.vercel.app/docs/api/core/type-aliases/storedattachment.md)[]\>

***

### getApproval()

```ts
getApproval(id): Promise<
  | {
  allowedScopes: ("once" | "session")[];
  availableDecisions: ("deny" | "allow_once" | "allow_session")[];
  category: "file" | "mcp" | "shell" | "network" | "other";
  createdAt: string;
  decision?: "deny" | "allow";
  description?: string;
  expiresAt: string;
  id: string;
  runId: string;
  runtimeId: string;
  sessionId: string;
  state:   | "failed"
     | "cancelled"
     | "pending"
     | "submitting"
     | "approved"
     | "denied"
     | "expired"
     | "reconciling";
  target: {
     command?: string;
     cwd?: string;
     host?: string;
     path?: string;
  };
  title: string;
  toolId?: string;
  version: number;
}
| null>;
```

Defined in: core/src/store/store.ts:35

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `id` | `string` |

#### Returns

`Promise`\<
  \| \{
  `allowedScopes`: (`"once"` \| `"session"`)[];
  `availableDecisions`: (`"deny"` \| `"allow_once"` \| `"allow_session"`)[];
  `category`: `"file"` \| `"mcp"` \| `"shell"` \| `"network"` \| `"other"`;
  `createdAt`: `string`;
  `decision?`: `"deny"` \| `"allow"`;
  `description?`: `string`;
  `expiresAt`: `string`;
  `id`: `string`;
  `runId`: `string`;
  `runtimeId`: `string`;
  `sessionId`: `string`;
  `state`:   \| `"failed"`
     \| `"cancelled"`
     \| `"pending"`
     \| `"submitting"`
     \| `"approved"`
     \| `"denied"`
     \| `"expired"`
     \| `"reconciling"`;
  `target`: \{
     `command?`: `string`;
     `cwd?`: `string`;
     `host?`: `string`;
     `path?`: `string`;
  \};
  `title`: `string`;
  `toolId?`: `string`;
  `version`: `number`;
\}
  \| `null`\>

***

### getAttachment()

```ts
getAttachment(id): Promise<
  | StoredAttachment
| null>;
```

Defined in: core/src/store/store.ts:44

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `id` | `string` |

#### Returns

`Promise`\<
  \| [`StoredAttachment`](https://uncage.vercel.app/docs/api/core/type-aliases/storedattachment.md)
  \| `null`\>

***

### getIdempotent()

```ts
getIdempotent(key, scope): Promise<
  | {
  requestHash: string;
  response: unknown;
}
| null>;
```

Defined in: core/src/store/store.ts:56

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `key` | `string` |
| `scope` | `string` |

#### Returns

`Promise`\<
  \| \{
  `requestHash`: `string`;
  `response`: `unknown`;
\}
  \| `null`\>

***

### getRun()

```ts
getRun(id): Promise<
  | {
  attachments?: object[];
  createdAt: string;
  endedAt?: string;
  error?: {
     code:   | "runtime_unavailable"
        | "auth_required"
        | "unsupported_capability"
        | "invalid_workspace"
        | "session_busy"
        | "session_read_only"
        | "not_found"
        | "unauthorized"
        | "forbidden_origin"
        | "invalid_request"
        | "approval_expired"
        | "approval_already_resolved"
        | "event_replay_unavailable"
        | "runtime_disconnected"
        | "policy_denied"
        | "store_locked"
        | "attachment_too_large"
        | "attachment_type_unsupported"
        | "machine_offline"
        | "machine_not_found"
        | "upgrade_required"
        | "tool_failed"
        | "device_code_expired"
        | "rate_limited"
        | "internal_error";
     details?: Record<string, unknown>;
     hint?: string;
     message: string;
     requestId?: string;
     retryable: boolean;
  };
  id: string;
  prompt: string;
  sessionId: string;
  startedAt?: string;
  state:   | "queued"
     | "running"
     | "waiting_approval"
     | "completed"
     | "failed"
     | "cancelled"
     | "interrupted";
}
| null>;
```

Defined in: core/src/store/store.ts:23

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `id` | `string` |

#### Returns

`Promise`\<
  \| \{
  `attachments?`: `object`[];
  `createdAt`: `string`;
  `endedAt?`: `string`;
  `error?`: \{
     `code`:   \| `"runtime_unavailable"`
        \| `"auth_required"`
        \| `"unsupported_capability"`
        \| `"invalid_workspace"`
        \| `"session_busy"`
        \| `"session_read_only"`
        \| `"not_found"`
        \| `"unauthorized"`
        \| `"forbidden_origin"`
        \| `"invalid_request"`
        \| `"approval_expired"`
        \| `"approval_already_resolved"`
        \| `"event_replay_unavailable"`
        \| `"runtime_disconnected"`
        \| `"policy_denied"`
        \| `"store_locked"`
        \| `"attachment_too_large"`
        \| `"attachment_type_unsupported"`
        \| `"machine_offline"`
        \| `"machine_not_found"`
        \| `"upgrade_required"`
        \| `"tool_failed"`
        \| `"device_code_expired"`
        \| `"rate_limited"`
        \| `"internal_error"`;
     `details?`: `Record`\<`string`, `unknown`\>;
     `hint?`: `string`;
     `message`: `string`;
     `requestId?`: `string`;
     `retryable`: `boolean`;
  \};
  `id`: `string`;
  `prompt`: `string`;
  `sessionId`: `string`;
  `startedAt?`: `string`;
  `state`:   \| `"queued"`
     \| `"running"`
     \| `"waiting_approval"`
     \| `"completed"`
     \| `"failed"`
     \| `"cancelled"`
     \| `"interrupted"`;
\}
  \| `null`\>

***

### getSession()

```ts
getSession(id): Promise<object & object | null>;
```

Defined in: core/src/store/store.ts:17

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `id` | `string` |

#### Returns

`Promise`\<`object` & `object` \| `null`\>

***

### listApprovals()

```ts
listApprovals(q): Promise<object[]>;
```

Defined in: core/src/store/store.ts:36

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `q` | \{ `sessionId`: `string`; `states?`: ( \| `"failed"` \| `"cancelled"` \| `"pending"` \| `"submitting"` \| `"approved"` \| `"denied"` \| `"expired"` \| `"reconciling"`)[]; \} |
| `q.sessionId` | `string` |
| `q.states?` | ( \| `"failed"` \| `"cancelled"` \| `"pending"` \| `"submitting"` \| `"approved"` \| `"denied"` \| `"expired"` \| `"reconciling"`)[] |

#### Returns

`Promise`\<`object`[]\>

***

### listAttachments()

```ts
listAttachments(ids): Promise<StoredAttachment[]>;
```

Defined in: core/src/store/store.ts:46

Returns the existing rows among `ids` (missing ids are simply absent).

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ids` | `string`[] |

#### Returns

`Promise`\<[`StoredAttachment`](https://uncage.vercel.app/docs/api/core/type-aliases/storedattachment.md)[]\>

***

### listRuns()

```ts
listRuns(sessionId): Promise<object[]>;
```

Defined in: core/src/store/store.ts:24

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `sessionId` | `string` |

#### Returns

`Promise`\<`object`[]\>

***

### listRunsInState()

```ts
listRunsInState(states): Promise<object[]>;
```

Defined in: core/src/store/store.ts:26

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `states` | ( \| `"queued"` \| `"running"` \| `"waiting_approval"` \| `"completed"` \| `"failed"` \| `"cancelled"` \| `"interrupted"`)[] |

#### Returns

`Promise`\<`object`[]\>

***

### listSessions()

```ts
listSessions(): Promise<object[]>;
```

Defined in: core/src/store/store.ts:18

#### Returns

`Promise`\<`object`[]\>

***

### markAttachmentsReferenced()

```ts
markAttachmentsReferenced(ids, runId): Promise<number>;
```

Defined in: core/src/store/store.ts:51

All or nothing: sets `referencedByRun` on every one of `ids` when all exist and are
unreferenced, returning `ids.length`; otherwise changes nothing and returns 0.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ids` | `string`[] |
| `runId` | `string` |

#### Returns

`Promise`\<`number`\>

***

### minRetainedSequence()

```ts
minRetainedSequence(sessionId): Promise<number>;
```

Defined in: core/src/store/store.ts:32

0 when nothing was pruned; otherwise the lowest sequence that may still be retained.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `sessionId` | `string` |

#### Returns

`Promise`\<`number`\>

***

### pruneEvents()

```ts
pruneEvents(olderThan): Promise<number>;
```

Defined in: core/src/store/store.ts:33

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `olderThan` | `Date` |

#### Returns

`Promise`\<`number`\>

***

### putIdempotent()

```ts
putIdempotent(
   key, 
   scope, 
   requestHash, 
   response
): Promise<void>;
```

Defined in: core/src/store/store.ts:57

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `key` | `string` |
| `scope` | `string` |
| `requestHash` | `string` |
| `response` | `unknown` |

#### Returns

`Promise`\<`void`\>

***

### readEvents()

```ts
readEvents(
   sessionId, 
   afterSequence, 
   limit?
): Promise<EventEnvelope<
  | "session.created"
  | "session.updated"
  | "run.started"
  | "run.updated"
  | "run.completed"
  | "run.failed"
  | "run.cancelled"
  | "run.interrupted"
  | "message.started"
  | "message.delta"
  | "message.completed"
  | "tool.started"
  | "tool.updated"
  | "tool.completed"
  | "tool.failed"
  | "approval.requested"
  | "approval.updated"
  | "approval.resolved"
| "system.warning">[]>;
```

Defined in: core/src/store/store.ts:30

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `sessionId` | `string` |
| `afterSequence` | `number` |
| `limit?` | `number` |

#### Returns

`Promise`\<`EventEnvelope`\<
  \| `"session.created"`
  \| `"session.updated"`
  \| `"run.started"`
  \| `"run.updated"`
  \| `"run.completed"`
  \| `"run.failed"`
  \| `"run.cancelled"`
  \| `"run.interrupted"`
  \| `"message.started"`
  \| `"message.delta"`
  \| `"message.completed"`
  \| `"tool.started"`
  \| `"tool.updated"`
  \| `"tool.completed"`
  \| `"tool.failed"`
  \| `"approval.requested"`
  \| `"approval.updated"`
  \| `"approval.resolved"`
  \| `"system.warning"`\>[]\>

***

### releaseAttachments()

```ts
releaseAttachments(runId): Promise<void>;
```

Defined in: core/src/store/store.ts:53

Clears `referencedByRun` for attachments marked for `runId` (compensates a failed run start).

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `runId` | `string` |

#### Returns

`Promise`\<`void`\>

***

### updateRun()

```ts
updateRun(id, patch): Promise<{
  attachments?: object[];
  createdAt: string;
  endedAt?: string;
  error?: {
     code:   | "runtime_unavailable"
        | "auth_required"
        | "unsupported_capability"
        | "invalid_workspace"
        | "session_busy"
        | "session_read_only"
        | "not_found"
        | "unauthorized"
        | "forbidden_origin"
        | "invalid_request"
        | "approval_expired"
        | "approval_already_resolved"
        | "event_replay_unavailable"
        | "runtime_disconnected"
        | "policy_denied"
        | "store_locked"
        | "attachment_too_large"
        | "attachment_type_unsupported"
        | "machine_offline"
        | "machine_not_found"
        | "upgrade_required"
        | "tool_failed"
        | "device_code_expired"
        | "rate_limited"
        | "internal_error";
     details?: Record<string, unknown>;
     hint?: string;
     message: string;
     requestId?: string;
     retryable: boolean;
  };
  id: string;
  prompt: string;
  sessionId: string;
  startedAt?: string;
  state:   | "queued"
     | "running"
     | "waiting_approval"
     | "completed"
     | "failed"
     | "cancelled"
     | "interrupted";
}>;
```

Defined in: core/src/store/store.ts:25

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `id` | `string` |
| `patch` | `Partial`\<`Run`\> |

#### Returns

`Promise`\<\{
  `attachments?`: `object`[];
  `createdAt`: `string`;
  `endedAt?`: `string`;
  `error?`: \{
     `code`:   \| `"runtime_unavailable"`
        \| `"auth_required"`
        \| `"unsupported_capability"`
        \| `"invalid_workspace"`
        \| `"session_busy"`
        \| `"session_read_only"`
        \| `"not_found"`
        \| `"unauthorized"`
        \| `"forbidden_origin"`
        \| `"invalid_request"`
        \| `"approval_expired"`
        \| `"approval_already_resolved"`
        \| `"event_replay_unavailable"`
        \| `"runtime_disconnected"`
        \| `"policy_denied"`
        \| `"store_locked"`
        \| `"attachment_too_large"`
        \| `"attachment_type_unsupported"`
        \| `"machine_offline"`
        \| `"machine_not_found"`
        \| `"upgrade_required"`
        \| `"tool_failed"`
        \| `"device_code_expired"`
        \| `"rate_limited"`
        \| `"internal_error"`;
     `details?`: `Record`\<`string`, `unknown`\>;
     `hint?`: `string`;
     `message`: `string`;
     `requestId?`: `string`;
     `retryable`: `boolean`;
  \};
  `id`: `string`;
  `prompt`: `string`;
  `sessionId`: `string`;
  `startedAt?`: `string`;
  `state`:   \| `"queued"`
     \| `"running"`
     \| `"waiting_approval"`
     \| `"completed"`
     \| `"failed"`
     \| `"cancelled"`
     \| `"interrupted"`;
\}\>

***

### updateSession()

```ts
updateSession(id, patch): Promise<{
  activeRunId?: string;
  capabilities: {
     approval: {
        once: boolean;
        session: boolean;
        types: ("file" | "mcp" | "shell" | "network" | "other")[];
     };
     attachments: {
        files: boolean;
        images: boolean;
        maxBytes: number;
        maxImageBytes?: number;
     };
     diffEvents: boolean;
     efforts: ("low" | "medium" | "high" | "xhigh" | "max")[];
     mcp: boolean;
     models: object[];
     modelsAuthoritative?: boolean;
     nativeResume: boolean;
     permissionModes: ("default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions")[];
     siteTools: boolean;
     skills: "unknown" | "supported" | "partial" | "prompt";
     streaming: boolean;
  };
  createdAt: string;
  id: string;
  machineId?: string;
  readOnly: boolean;
  runtimeId: string;
  settings: {
     effort?: "low" | "medium" | "high" | "xhigh" | "max";
     model?: string;
     permissionMode: "default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions";
  };
  status: "ready" | "busy" | "unavailable" | "closed";
  title: string;
  workspace: string;
}>;
```

Defined in: core/src/store/store.ts:20

Keys present in `patch` with value `undefined`/`null` clear nullable fields (activeRunId, nativeSessionRef).

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `id` | `string` |
| `patch` | `Partial`\<\{ `activeRunId?`: `string`; `capabilities`: \{ `approval`: \{ `once`: `boolean`; `session`: `boolean`; `types`: (`"file"` \| `"mcp"` \| `"shell"` \| `"network"` \| `"other"`)[]; \}; `attachments`: \{ `files`: `boolean`; `images`: `boolean`; `maxBytes`: `number`; `maxImageBytes?`: `number`; \}; `diffEvents`: `boolean`; `efforts`: (`"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"`)[]; `mcp`: `boolean`; `models`: `object`[]; `modelsAuthoritative?`: `boolean`; `nativeResume`: `boolean`; `permissionModes`: (`"default"` \| `"acceptEdits"` \| `"plan"` \| `"auto"` \| `"bypassPermissions"`)[]; `siteTools`: `boolean`; `skills`: `"unknown"` \| `"supported"` \| `"partial"` \| `"prompt"`; `streaming`: `boolean`; \}; `createdAt`: `string`; `id`: `string`; `machineId?`: `string`; `readOnly`: `boolean`; `runtimeId`: `string`; `settings`: \{ `effort?`: `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"`; `model?`: `string`; `permissionMode`: `"default"` \| `"acceptEdits"` \| `"plan"` \| `"auto"` \| `"bypassPermissions"`; \}; `status`: `"ready"` \| `"busy"` \| `"unavailable"` \| `"closed"`; `title`: `string`; `workspace`: `string`; \}\> & `object` |

#### Returns

`Promise`\<\{
  `activeRunId?`: `string`;
  `capabilities`: \{
     `approval`: \{
        `once`: `boolean`;
        `session`: `boolean`;
        `types`: (`"file"` \| `"mcp"` \| `"shell"` \| `"network"` \| `"other"`)[];
     \};
     `attachments`: \{
        `files`: `boolean`;
        `images`: `boolean`;
        `maxBytes`: `number`;
        `maxImageBytes?`: `number`;
     \};
     `diffEvents`: `boolean`;
     `efforts`: (`"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"`)[];
     `mcp`: `boolean`;
     `models`: `object`[];
     `modelsAuthoritative?`: `boolean`;
     `nativeResume`: `boolean`;
     `permissionModes`: (`"default"` \| `"acceptEdits"` \| `"plan"` \| `"auto"` \| `"bypassPermissions"`)[];
     `siteTools`: `boolean`;
     `skills`: `"unknown"` \| `"supported"` \| `"partial"` \| `"prompt"`;
     `streaming`: `boolean`;
  \};
  `createdAt`: `string`;
  `id`: `string`;
  `machineId?`: `string`;
  `readOnly`: `boolean`;
  `runtimeId`: `string`;
  `settings`: \{
     `effort?`: `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"`;
     `model?`: `string`;
     `permissionMode`: `"default"` \| `"acceptEdits"` \| `"plan"` \| `"auto"` \| `"bypassPermissions"`;
  \};
  `status`: `"ready"` \| `"busy"` \| `"unavailable"` \| `"closed"`;
  `title`: `string`;
  `workspace`: `string`;
\}\>
