Skip to content

UncageClient

View as Markdown

Defined in: client/src/client.ts:80

attachmentUrl(attachmentId): string;

Defined in: client/src/client.ts:94

Parameter Type
attachmentId string

string


cancelRun(runId): Promise<{
attachments?: object[];
createdAt: string;
endedAt?: string;
error?: {
code: | "auth_required"
| "runtime_unavailable"
| "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: client/src/client.ts:87

Parameter Type
runId string

Promise<{ attachments?: object[]; createdAt: string; endedAt?: string; error?: { code: | "auth_required" | "runtime_unavailable" | "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"; }>


createSession(b): Promise<{
activeRunId?: string;
capabilities: {
approval: {
once: boolean;
session: boolean;
types: ("mcp" | "file" | "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: client/src/client.ts:83

Parameter Type
b CreateSessionRequest

Promise<{ activeRunId?: string; capabilities: { approval: { once: boolean; session: boolean; types: ("mcp" | "file" | "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; }>


decide(
approvalId,
d,
idempotencyKey?
): Promise<{
allowedScopes: ("once" | "session")[];
availableDecisions: ("deny" | "allow_once" | "allow_session")[];
category: "mcp" | "file" | "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;
}>;

Defined in: client/src/client.ts:96

Parameter Type
approvalId string
d { decision: "deny" | "allow"; reason?: string; scope: "once" | "session"; }
d.decision "deny" | "allow"
d.reason? string
d.scope "once" | "session"
idempotencyKey? string

Promise<{ allowedScopes: ("once" | "session")[]; availableDecisions: ("deny" | "allow_once" | "allow_session")[]; category: "mcp" | "file" | "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; }>


decideDevice(code, approve): Promise<DeviceDecision>;

Defined in: client/src/client.ts:121

Connected mode: approves (binds the computer to the signed-in user) or denies a device code.

Parameter Type
code string
approve boolean

Promise<DeviceDecision>


health(): Promise<{
ok: true;
protocol: "1.0";
}>;

Defined in: client/src/client.ts:81

Promise<{ ok: true; protocol: "1.0"; }>


installInfo(): Promise<InstallInfo>;

Defined in: client/src/client.ts:115

Connected mode: the install and setup commands for connecting a computer.

Promise<InstallInfo>


listActiveRuns(): Promise<object[]>;

Defined in: client/src/client.ts:95

Promise<object[]>


listSessions(): Promise<object[]>;

Defined in: client/src/client.ts:84

Promise<object[]>


lookupDevice(code): Promise<DeviceLookup | null>;

Defined in: client/src/client.ts:119

Connected mode: a pending device code for the approve screen, or null if unknown / no longer pending.

Parameter Type
code string

Promise<DeviceLookup | null>


machines(): Promise<object[]>;

Defined in: client/src/client.ts:113

Connected mode (an Uncage hub): the signed-in user’s computers. A local daemon has no /machines and rejects with status 404, which is how UIs tell the two modes apart.

Promise<object[]>


reconnect(opts?): void;

Defined in: client/src/client.ts:108

Restarts the open subscriptions at once from their last sequence (no duplicates, no gap), skipping any backoff wait. Call it when a mobile app returns to the foreground. No-op when nothing is subscribed.

A stream that is live and received bytes (an event or the server’s heartbeat) within the last 20 s is kept: it is only restarted if no byte arrives before that window runs out (a socket that died silently while the app was briefly in the background). { force: true } restarts every stream regardless.

Parameter Type
opts? { force?: boolean; }
opts.force? boolean

void


revokeMachine(machineId): Promise<void>;

Defined in: client/src/client.ts:117

Connected mode: disconnects (revokes) one of the user’s computers.

Parameter Type
machineId string

Promise<void>


runtimes(): Promise<object[]>;

Defined in: client/src/client.ts:82

Promise<object[]>


snapshot(sessionId): Promise<{
lastSequence: number;
pendingApprovals: object[];
runs: object[];
session: {
activeRunId?: string;
capabilities: {
approval: {
once: boolean;
session: boolean;
types: ("mcp" | "file" | "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: client/src/client.ts:85

Parameter Type
sessionId string

Promise<{ lastSequence: number; pendingApprovals: object[]; runs: object[]; session: { activeRunId?: string; capabilities: { approval: { once: boolean; session: boolean; types: ("mcp" | "file" | "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(sessionId, b): Promise<{
attachments?: object[];
createdAt: string;
endedAt?: string;
error?: {
code: | "auth_required"
| "runtime_unavailable"
| "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: client/src/client.ts:86

Parameter Type
sessionId string
b { attachmentIds?: string[]; prompt: string; }
b.attachmentIds? string[]
b.prompt string

Promise<{ attachments?: object[]; createdAt: string; endedAt?: string; error?: { code: | "auth_required" | "runtime_unavailable" | "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"; }>


subscribe(sessionId, h): () => void;

Defined in: client/src/client.ts:97

Parameter Type
sessionId string
h SubscribeHandlers

() => void


updateSettings(sessionId, patch): Promise<{
activeRunId?: string;
capabilities: {
approval: {
once: boolean;
session: boolean;
types: ("mcp" | "file" | "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: client/src/client.ts:88

Parameter Type
sessionId string
patch Partial<SessionSettings>

Promise<{ activeRunId?: string; capabilities: { approval: { once: boolean; session: boolean; types: ("mcp" | "file" | "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; }>


uploadAttachment(
sessionId,
file,
opts?
): Promise<{
createdAt: string;
id: string;
kind: "file" | "image";
mime: string;
name: string;
sessionId: string;
sha256: string;
size: number;
}>;

Defined in: client/src/client.ts:93

Uploads a file: a browser File (Blob & { name }) or, in React Native, a picked file reference { uri, name, type } (read through the runtime’s built-in fetch(uri)).

Parameter Type
sessionId string
file RNFile | Blob & object
opts? { signal?: AbortSignal; }
opts.signal? AbortSignal

Promise<{ createdAt: string; id: string; kind: "file" | "image"; mime: string; name: string; sessionId: string; sha256: string; size: number; }>