A desktop coding agent with free access to frontier models.
TypeScript
/**
* The messages between the server's main thread and its capture worker
* (capture-client.ts, capture-worker.ts). The main thread calls the
* CaptureHost methods named in CaptureCalls; the worker asks the main thread
* for what only it can do (the gateway broker's authenticated requests, and
* external egress through the embedding runtime's network stack) and reports
* logs and closed sessions. Everything is plain data; request and response
* bodies travel as transferred buffers.
*/
import type { CaptureHost, EngineReplacement, EngineTarget, LateWritesGate, PromptRecord } from "./capture-host.js";
import type { ApprovalMode } from "./approval-mode.js";
import type { BoxCaptureInfo } from "./box/service.js";
import type { CommandEventType } from "./command-events.js";
import type { FolderGateOptions } from "./session-archive/detect.js";
import type { TraceCapabilities, UploadRequestOptions, UploadWebVisit } from "./session-uploader.js";
/** How the capture stops: `archiveFinals` false (the account is gone) packs no final project archives. */
export type CaptureStopOptions = { archiveFinals: boolean };
/** CaptureHost methods callable from the main thread, with their arguments. */
export type CaptureCalls = {
markClaude: [sessionId: string, version: string];
markNotClaude: [sessionId: string];
startSession: [sessionId: string, workspaceId: string, root: string, turnsBefore?: number];
boxSession: [sessionId: string, box: BoxCaptureInfo | null];
sessionPolicy: [sessionId: string];
pinPolicy: [sessionId: string, policy: string];
holdUploads: [sessionId: string, state: "pending" | "refused" | "confirmed", seq: number];
permissionMode: [mode: ApprovalMode | null];
recordTrace: [sessionId: string, type: string, data?: unknown];
flushTrace: [sessionId: string, finalTrace?: unknown];
finishSession: [sessionId: string, finalTrace?: unknown];
recordPrompt: [sessionId: string, prompt: PromptRecord];
captureSnapshot: [sessionId: string, trigger: "prompt" | "turn_completed", outcome?: "aborted"];
steerTurn: [sessionId: string, steer: Record<string, unknown>];
recordCommand: [sessionId: string, type: CommandEventType, data: Record<string, unknown>];
followSteer: [sessionId: string, target: EngineTarget];
recordWebVisit: [sessionId: string, visit: UploadWebVisit];
archiveSessionStarted: [sessionId: string, root: string, target: EngineTarget];
archiveStartGate: [sessionId: string, root: string, lateWrites?: LateWritesGate | null];
observeSession: [sessionId: string, target: EngineTarget];
engineReplaced: [closedBaseUrl: string, replacement: EngineReplacement];
sessionDeleted: [sessionId: string];
signOut: [];
stop: [options?: CaptureStopOptions];
idle: [];
diagnostics: [];
filesUsedStatus: [];
pendingUploads: [];
flushPending: [budgetMs: number];
};
export type CaptureCallName = keyof CaptureCalls;
/** One call; `id` is set when the caller waits for its result. */
export type CaptureCall = { [M in CaptureCallName]: { kind: "call"; id: number | null; method: M; args: CaptureCalls[M] } }[CaptureCallName];
/** What a worker asks of the main thread. `channel` says whose request it is: archive requests are aborted first at shutdown. */
export type HostRequest =
| { type: "upload"; sessionId: string; body: Uint8Array<ArrayBuffer>; options?: UploadRequestOptions }
| { type: "uploadFile"; sessionId: string; path: string; size: number; options?: UploadRequestOptions }
| { type: "capabilities" }
| { type: "accountId" }
| { type: "engineTarget"; sessionId: string; workspaceId: string }
| { type: "sessionIntegrity"; sessionId: string; summary?: boolean; turns?: number }
| { type: "refreshAccessToken" }
| { type: "archiveRequest"; path: string; method: "GET" | "POST"; body?: string; refresh?: false }
| { type: "fetch"; url: string; method: string; headers: Array<[string, string]>; body?: Uint8Array<ArrayBuffer> | string };
export type RequestChannel = "uploader" | "archive";
export type SerializedResponse = { status: number; statusText: string; headers: Array<[string, string]>; body: ArrayBuffer | null };
export type RequestResult =
| { kind: "result"; id: number; ok: true; response: SerializedResponse | null; token?: string | null; value?: TraceCapabilities; account?: string | null; target?: EngineTarget | null }
| { kind: "result"; id: number; ok: false; error: string; name: string };
export type ToWorker = CaptureCall | RequestResult;
export type FromWorker =
| { kind: "ready" }
| { kind: "log"; level: "info" | "warn"; message: string; attributes?: Record<string, unknown> }
| { kind: "closed"; sessionId: string }
| { kind: "reply"; id: number; ok: true; value: unknown }
| { kind: "reply"; id: number; ok: false; error: string }
| { kind: "request"; id: number; channel: RequestChannel; request: HostRequest }
| { kind: "abort"; id: number };
/** What the worker is built with (its workerData): the main thread's hooks become requests. */
export type CaptureWorkerInit = {
stateDir: string;
appVersion: string;
engineVersion: string;
/** The main thread can name the signed-in account (spooled uploads are stamped with it). */
accountId: boolean;
/** The main thread can read the server's integrity record of a chat. */
sessionIntegrity: boolean;
/** The main thread can name the engine holding a chat (to settle a turn a previous process left open). */
engineTarget: boolean;
sessionUploader: { upload: boolean; uploadFile: boolean; capabilities: boolean; refreshAccessToken: boolean; gatewayUrl?: string; accessToken?: string };
/** The install log's folders (install-log-host.ts), when the engines have the wrappers. */
installLog?: { raw: string; bin: string } | null;
boxInstallLog?: { raw: string; bin: string } | null;
archive: {
enabled: boolean;
excludedDirs: string[];
folderGate?: FolderGateOptions;
request: boolean;
refreshAccessToken: boolean;
gatewayUrl?: string;
accessToken?: string;
baseIdleMs?: number;
baseMaxDeferMs?: number;
};
};
export async function serializeResponse(response: Response): Promise<SerializedResponse> {
const body = response.body ? await boundedResponseBody(response) : null;
return {
status: response.status,
statusText: response.statusText,
headers: [...response.headers],
body: body && body.byteLength > 0 ? body : null,
};
}
const MAX_RELAY_RESPONSE_BYTES = 1024 * 1024;
async function boundedResponseBody(response: Response): Promise<ArrayBuffer | null> {
if (!response.body) return null;
const reader = response.body.getReader();
const chunks: Uint8Array[] = [];
let total = 0;
try {
while (true) {
const result = await reader.read();
if (result.done) break;
total += result.value.byteLength;
if (total > MAX_RELAY_RESPONSE_BYTES) {
await reader.cancel("capture relay response too large").catch(() => undefined);
throw new Error("capture relay response exceeds its bound");
}
chunks.push(result.value);
}
} finally {
reader.releaseLock();
}
const body = new Uint8Array(total);
let offset = 0;
for (const chunk of chunks) {
body.set(chunk, offset);
offset += chunk.byteLength;
}
return body.buffer;
}
const NULL_BODY_STATUSES = new Set([101, 204, 205, 304]);
export function deserializeResponse(value: SerializedResponse): Response {
return new Response(NULL_BODY_STATUSES.has(value.status) ? null : value.body, {
status: value.status,
statusText: value.statusText,
headers: value.headers,
});
}
/** The buffers of a request or result that can be transferred instead of copied. */
export function transferables(value: HostRequest | SerializedResponse | null): ArrayBuffer[] {
if (!value) return [];
const body = "body" in value ? value.body : undefined;
if (body instanceof ArrayBuffer) return [body];
if (body instanceof Uint8Array && body.byteOffset === 0 && body.byteLength === body.buffer.byteLength) return [body.buffer];
return [];
}
/** Runs one call on a host (the worker's, or the in-process fallback). */
export function invokeCapture(host: CaptureHost, call: CaptureCall): unknown {
switch (call.method) {
case "markClaude":
return host.markClaude(...call.args);
case "markNotClaude":
return host.markNotClaude(...call.args);
case "startSession":
return host.startSession(...call.args);
case "boxSession":
return host.boxSession(...call.args);
case "sessionPolicy":
return host.sessionPolicy(...call.args);
case "pinPolicy":
return host.pinPolicy(...call.args);
case "holdUploads":
return host.holdUploads(...call.args);
case "permissionMode":
return host.permissionMode(...call.args);
case "recordTrace":
return host.recordTrace(...call.args);
case "flushTrace":
return host.flushTrace(...call.args);
case "finishSession":
return host.finishSession(...call.args);
case "recordPrompt":
return host.recordPrompt(...call.args);
case "captureSnapshot":
return host.captureSnapshot(...call.args);
case "steerTurn":
return host.steerTurn(...call.args);
case "recordCommand":
return host.recordCommand(...call.args);
case "followSteer":
return host.followSteer(...call.args);
case "recordWebVisit":
return host.recordWebVisit(...call.args);
case "archiveSessionStarted":
return host.archiveSessionStarted(...call.args);
case "archiveStartGate":
return host.archiveStartGate(...call.args);
case "observeSession":
return host.observeSession(...call.args);
case "engineReplaced":
return host.engineReplaced(...call.args);
case "sessionDeleted":
return host.sessionDeleted(...call.args);
case "signOut":
return host.signOut();
case "stop":
return host.stop(...call.args);
case "idle":
return host.idle();
case "diagnostics":
return host.diagnostics();
case "filesUsedStatus":
return host.filesUsedStatus();
case "pendingUploads":
return host.pendingUploads();
case "flushPending":
return host.flushPending(...call.args);
}
}