A personal agent with a browser, terminal, files, and work that keeps going built with CopilotKit and AG-UI.
TypeScript
import { randomUUID } from "node:crypto";
import { z } from "zod";
import type { BrowserSession } from "../../../packages/domain/src/index.ts";
import type { Auth } from "./auth.ts";
import { browserConsole } from "./browser-console.ts";
import type { Config } from "./config.ts";
import type { Store } from "./db.ts";
import { AppError } from "./errors.ts";
import type { Files } from "./files.ts";
const sessionSchema = z.object({
id: z.string(),
title: z.string(),
url: z.string(),
status: z.enum(["idle", "active", "closed", "error"]),
updatedAt: z.string(),
});
const readSchema = z.object({
url: z.string(),
title: z.string().max(300),
text: z.string().max(100_000),
truncated: z.boolean(),
});
const failureSchema = z.object({
id: z.string(),
name: z.string(),
code: z.string(),
message: z.string(),
createdAt: z.string(),
});
type ChatBrowser = { id: string; sessionId: string };
const BROWSER_SESSION_ID =
/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
function assertSessionId(id: string): void {
if (!BROWSER_SESSION_ID.test(id)) throw new AppError("Browser session not found", 404);
}
export class BrowserService {
private readonly queues = new Map<string, Promise<unknown>>();
private health?: { checkedAt: number; reachable: Promise<boolean> };
constructor(
private readonly db: Store,
private readonly config: Config,
private readonly auth: Auth,
private readonly files: Files,
private readonly now: () => number = Date.now,
) {}
/** Whether the configured worker answers its health check, cached briefly for snapshots. */
reachable(): Promise<boolean> {
if (!this.config.workerUrl || !this.config.workerToken) return Promise.resolve(false);
const now = this.now();
if (this.health && now - this.health.checkedAt < 15_000) return this.health.reachable;
const reachable = fetch(`${this.config.workerUrl}/health`, {
signal: AbortSignal.timeout(2000),
}).then(
(response) => response.ok,
() => false,
);
this.health = { checkedAt: now, reachable };
return reachable;
}
private async serial<T>(id: string, operation: () => Promise<T>): Promise<T> {
const next = (this.queues.get(id) ?? Promise.resolve()).catch(() => {}).then(operation);
this.queues.set(id, next);
try {
return await next;
} finally {
if (this.queues.get(id) === next) this.queues.delete(id);
}
}
private async request(path: string, body?: unknown, signal?: AbortSignal) {
signal?.throwIfAborted();
if (!this.config.workerUrl || !this.config.workerToken)
throw new AppError("Browser worker is not configured. Start it using the setup guide.", 503);
let response: Response;
try {
response = await fetch(`${this.config.workerUrl}${path}`, {
method: body === undefined ? "GET" : "POST",
headers: {
Authorization: `Bearer ${this.config.workerToken}`,
"Content-Type": "application/json",
},
body: body === undefined ? undefined : JSON.stringify(body),
signal: signal
? AbortSignal.any([signal, AbortSignal.timeout(45000)])
: AbortSignal.timeout(45000),
});
} catch {
signal?.throwIfAborted();
throw new AppError(
"Browser worker is unavailable. Check that its container is running.",
503,
);
}
if (!response.ok) {
const payload = await response.json().catch(() => null);
throw new AppError(
typeof payload?.error?.message === "string"
? payload.error.message
: "Browser request failed",
502,
);
}
return response;
}
async get(owner: string, id: string) {
assertSessionId(id);
const value = await this.db.get<BrowserSession>(owner, "browsers", id);
if (!value) throw new AppError("Browser session not found", 404);
return value;
}
decorate(owner: string, session: BrowserSession) {
return {
...session,
consoleUrl: this.auth.sign(owner, `/api/browsers/${session.id}/console`),
previewUrl: this.auth.sign(owner, `/api/browsers/${session.id}/preview`),
};
}
private async save(owner: string, payload: unknown, expectedId: string) {
const session = sessionSchema.parse(payload);
if (session.id !== expectedId)
throw new AppError("Browser worker returned a different session", 502);
await this.db.put(owner, "browsers", session);
return this.decorate(owner, session);
}
async create(owner: string, url: string, signal?: AbortSignal) {
const id = randomUUID();
// Record ownership before calling the worker, including when its response is lost.
await this.db.put(owner, "browsers", {
id,
url,
title: "New browser session",
status: "idle",
updatedAt: new Date().toISOString(),
});
return this.reopen(owner, id, url, signal);
}
private async openOwned(owner: string, id: string, url?: string, signal?: AbortSignal) {
const value = await this.get(owner, id);
const target = url ?? value.url;
try {
const response = await this.request("/sessions", { id, url: target }, signal);
return await this.save(owner, await response.json(), id);
} catch (error) {
signal?.throwIfAborted();
await this.save(
owner,
{ ...value, url: target, status: "error", updatedAt: new Date().toISOString() },
id,
);
throw error;
}
}
reopen(owner: string, id: string, url?: string, signal?: AbortSignal) {
return this.serial(id, () => this.openOwned(owner, id, url, signal));
}
navigate(owner: string, id: string, url: string) {
return this.reopen(owner, id, url);
}
private async readOwned(owner: string, id: string, signal?: AbortSignal) {
const session = await this.get(owner, id);
const result = readSchema.parse(
await (
await this.request(`/sessions/${encodeURIComponent(id)}/read`, undefined, signal)
).json(),
);
await this.save(
owner,
{
...session,
url: result.url,
title: result.title,
status: "active",
updatedAt: new Date().toISOString(),
},
id,
);
return result;
}
read(owner: string, id: string) {
return this.serial(id, () => this.readOwned(owner, id));
}
async observe(owner: string, url: string, existingId?: string, signal?: AbortSignal) {
const id = existingId ?? (await this.create(owner, url, signal)).id;
return this.serial(id, async () => {
signal?.throwIfAborted();
if (existingId) await this.openOwned(owner, id, url, signal);
signal?.throwIfAborted();
return { sessionId: id, ...(await this.readOwned(owner, id, signal)) };
});
}
async observeForThread(owner: string, threadId: string, url: string, signal?: AbortSignal) {
signal?.throwIfAborted();
// Persist the association before contacting the worker so failed/lost responses
// and later chat turns keep using the same profile instead of exhausting its limit.
const association =
(await this.db.get<ChatBrowser>(owner, "chat-browsers", threadId)) ??
(await this.db.insertIfAbsent(owner, "chat-browsers", {
id: threadId,
sessionId: randomUUID(),
})) ??
(await this.db.get<ChatBrowser>(owner, "chat-browsers", threadId));
if (!association) throw new AppError("Could not reserve the chat browser session", 500);
const id = association.sessionId;
await this.db.insertIfAbsent(owner, "browsers", {
id,
url,
title: "New browser session",
status: "idle",
updatedAt: new Date().toISOString(),
});
return this.serial(id, async () => {
signal?.throwIfAborted();
await this.openOwned(owner, id, url, signal);
signal?.throwIfAborted();
const page = await this.readOwned(owner, id, signal);
signal?.throwIfAborted();
return {
sessionId: id,
...page,
text: page.text.slice(0, 30_000),
truncated: page.truncated || page.text.length > 30_000,
};
});
}
async close(owner: string, id: string) {
return this.serial(id, async () => {
await this.get(owner, id);
return this.save(
owner,
await (await this.request(`/sessions/${encodeURIComponent(id)}/close`, {})).json(),
id,
);
});
}
async preview(owner: string, id: string) {
await this.get(owner, id);
return this.request(`/sessions/${encodeURIComponent(id)}/screenshot`);
}
async input(owner: string, id: string, value: unknown) {
if (!value || typeof value !== "object" || Array.isArray(value))
throw new AppError("A JSON object is required for browser input", 422);
return this.serial(id, async () => {
await this.get(owner, id);
return this.save(
owner,
await (await this.request(`/sessions/${encodeURIComponent(id)}/input`, value)).json(),
id,
);
});
}
async imports(owner: string, id: string) {
return this.serial(id, () => this.importsOwned(owner, id));
}
private async importsOwned(owner: string, id: string) {
await this.get(owner, id);
const { downloads, failures } = z
.object({
downloads: z.array(
z.object({ id: z.string(), name: z.string(), size: z.number(), mimeType: z.string() }),
),
failures: z.array(failureSchema),
})
.parse(await (await this.request(`/sessions/${encodeURIComponent(id)}/downloads`)).json());
const saved = [];
for (const download of downloads) {
const existing = await this.db.get<{ fileId: string }>(
owner,
"browser-downloads",
download.id,
);
if (existing) {
saved.push(this.files.signed(owner, await this.files.get(owner, existing.fileId)));
continue;
}
const response = await this.request(
`/sessions/${encodeURIComponent(id)}/downloads/${encodeURIComponent(download.id)}`,
);
const file = await this.files.import(
owner,
download.name,
new Uint8Array(await response.arrayBuffer()),
`Browser · ${id}`,
);
await this.db.put(owner, "browser-downloads", { id: download.id, fileId: file.id });
saved.push(file);
}
return { files: saved, failures };
}
console(owner: string, id: string) {
return browserConsole(this.auth.sign(owner, `/api/browsers/${id}/preview`));
}
}