# Uncage

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

Defined in: core/src/uncage.ts:54

## Properties

| Property | Modifier | Type | Description | Defined in |
| ------ | ------ | ------ | ------ | ------ |
| <a id="property-approvals"></a> `approvals` | `public` | `object` | - | core/src/uncage.ts:80 |
| `approvals.decide` | `public` | (`id`, `d`, `idempotencyKey`) => `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`; \}\> | - | core/src/uncage.ts:82 |
| `approvals.list` | `public` | (`q`) => `Promise`\<`object`[]\> | - | core/src/uncage.ts:81 |
| <a id="property-attachments"></a> `attachments` | `public` | `object` | - | core/src/uncage.ts:67 |
| `attachments.add` | `public` | (`sessionId`, `input`) => `Promise`\<\{ `createdAt`: `string`; `id`: `string`; `kind`: `"file"` \| `"image"`; `mime`: `string`; `name`: `string`; `sessionId`: `string`; `sha256`: `string`; `size`: `number`; \}\> | `body` may be a byte array or a stream (e.g. a Node request); stored under the session workspace. | core/src/uncage.ts:69 |
| `attachments.get` | `public` | (`id`) => `Promise`\<\{ `absPath`: `string`; `attachment`: \{ `createdAt`: `string`; `id`: `string`; `kind`: `"file"` \| `"image"`; `mime`: `string`; `name`: `string`; `sessionId`: `string`; `sha256`: `string`; `size`: `number`; \}; \}\> | - | core/src/uncage.ts:70 |
| `attachments.pruneOrphans` | `public` | (`olderThan`) => `Promise`\<`number`\> | Deletes attachments never sent with a run and created before `olderThan`. | core/src/uncage.ts:72 |
| <a id="property-events"></a> `events` | `public` | `object` | - | core/src/uncage.ts:84 |
| `events.readAfter` | `public` | (`sessionId`, `after`, `limit?`) => `Promise`\<`UncageEvent`[]\> | At most `limit` (default 500, max 1000) committed events of the session with sequence > `after` (clamped to an integer >= 0), in sequence order: a page for catch-up / replication. `not_found` for an unknown session; `event_replay_unavailable` when retention already pruned part of the range. | core/src/uncage.ts:91 |
| <a id="property-runs"></a> `runs` | `public` | `object` | - | core/src/uncage.ts:74 |
| `runs.cancel` | `public` | (`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"`; \}\> | - | core/src/uncage.ts:76 |
| `runs.get` | `public` | (`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"`; \}\> | - | core/src/uncage.ts:75 |
| `runs.listActive` | `public` | () => `Promise`\<`object`[]\> | Active runs across all sessions, newest first. | core/src/uncage.ts:78 |
| <a id="property-runtimes"></a> `runtimes` | `public` | `object` | - | core/src/uncage.ts:55 |
| `runtimes.get` | `public` | (`id`) => `Promise`\<\{ `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`; \}; `displayName`: `string`; `hint?`: `string`; `icon?`: \{ `dark?`: `string`; `light`: `string`; \}; `id`: `string`; `installUrl?`: `string`; `message?`: `string`; `status`: \| `"auth_required"` \| `"error"` \| `"available"` \| `"not_installed"` \| `"incompatible"`; `version?`: `string`; \}\> | - | core/src/uncage.ts:55 |
| `runtimes.list` | `public` | () => `Promise`\<`object`[]\> | - | core/src/uncage.ts:55 |
| <a id="property-sessions"></a> `sessions` | `public` | `object` | - | core/src/uncage.ts:56 |
| `sessions.create` | `public` | (`b`, `opts?`) => `Promise`\<[`SessionHandle`](https://uncage.vercel.app/docs/api/core/interfaces/sessionhandle.md)\> | `opts.id` lets a host pick the session id up front (e.g. the connected agent names the per-session workspace directory after it); it must look like `newId('ses')` and be unused. | core/src/uncage.ts:61 |
| `sessions.get` | `public` | (`id`) => `Promise`\<[`SessionHandle`](https://uncage.vercel.app/docs/api/core/interfaces/sessionhandle.md)\> | - | core/src/uncage.ts:62 |
| `sessions.list` | `public` | () => `Promise`\<`object`[]\> | - | core/src/uncage.ts:63 |
| `sessions.updateSettings` | `public` | (`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`; \}\> | Validated against the policy and the runtime's capabilities; emits `session.updated`. | core/src/uncage.ts:65 |
| <a id="property-workspace"></a> `workspace` | `readonly` | `object` | The resolved workspace config: new sessions default to `default`, all live under `allowedRoots`. | core/src/uncage.ts:94 |
| `workspace.allowedRoots` | `readonly` | readonly `string`[] | - | core/src/uncage.ts:94 |
| `workspace.default` | `readonly` | `string` | - | core/src/uncage.ts:94 |

## Methods

### close()

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

Defined in: core/src/uncage.ts:95

#### Returns

`Promise`\<`void`\>
