# SessionHandle

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

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

## Properties

| Property | Modifier | Type | Defined in |
| ------ | ------ | ------ | ------ |
| <a id="property-id"></a> `id` | `readonly` | `string` | core/src/sessions.ts:21 |

## Methods

### events()

```ts
events(opts?): AsyncIterable<UncageEvent>;
```

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

Replays from the store, then streams live events. Never ends on its own; abort via `signal`.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `opts?` | \{ `after?`: `number`; `signal?`: `AbortSignal`; \} |
| `opts.after?` | `number` |
| `opts.signal?` | `AbortSignal` |

#### Returns

`AsyncIterable`\<`UncageEvent`\>

***

### get()

```ts
get(): 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/sessions.ts:22

#### 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`;
\}\>

***

### snapshot()

```ts
snapshot(): Promise<{
  lastSequence: number;
  pendingApprovals: object[];
  runs: object[];
  session: {
     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/sessions.ts:23

#### Returns

`Promise`\<\{
  `lastSequence`: `number`;
  `pendingApprovals`: `object`[];
  `runs`: `object`[];
  `session`: \{
     `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`;
  \};
\}\>

***

### startRun()

```ts
startRun(b): 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/sessions.ts:28

Returns once the run is queued; execution continues in the background. `manifest` (connected
mode) offers site tools and skills to the runtime for this run; tool calls go to `callTool`.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `b` | `object` & [`StartRunOptions`](https://uncage.vercel.app/docs/api/core/interfaces/startrunoptions.md) |

#### 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"`;
\}\>
