The VS Code of video editing, built for agents.
TypeScript
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
// The host owns every chat: its summary and transcript, the harness
// session behind it (at most one, closed after ten idle minutes), the
// turn that is running and the question it may be waiting on. Clients
// are views: they open a chat for a snapshot and then get its events,
// and they can come and go at any time without disturbing a turn.
import { randomUUID } from "node:crypto";
import { mkdir, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { basename, join } from "node:path";
import { isPersistedEvent, reduce } from "../reduce";
import { HARNESS_IDS, HARNESS_LABELS, isHarnessId, titleFor } from "../protocol";
import { withAttachments, chatInstructions } from "./harness";
import type {
ChatEvent,
ChatSnapshot,
ChatSummary,
ClientMsg,
ErrorCode,
HarnessId,
HarnessInfo,
HostMsg,
Item,
Method,
MethodParams,
MethodResult,
ModelRef,
RequestResponse,
TurnStatus,
} from "../protocol";
import type { Transcript } from "../reduce";
import type { HostEnv } from "./env";
import type { Emit, Harness, HarnessSession, McpConfig, TurnOutcome } from "./harness";
import type { ChatMeta, ChatStore } from "./store";
export class HostError extends Error {
readonly code: ErrorCode;
constructor(code: ErrorCode, message: string) {
super(message);
this.name = "HostError";
this.code = code;
}
}
export type Connection = { send(message: HostMsg): void };
export type AgentHostOptions = {
store: ChatStore;
harnesses: Harness[];
/** Resolves once the environment is hydrated; probes wait for it. */
env: Promise<HostEnv>;
mcp: McpConfig | null;
instructions?: string;
version: string;
/** How long a session outlives its last turn. */
idleMs?: number;
/** How old a probe may be before `refresh` re-runs it. */
probeMaxAgeMs?: number;
/** Where uploaded attachments are written; default a folder in the system temp dir. */
uploadDir?: string;
log?: (message: string) => void;
};
type Chat = {
meta: ChatMeta;
transcript: Transcript;
/** Whether `transcript` has been folded from disk yet. */
loaded: boolean;
seq: number;
session: HarnessSession | null;
idleTimer: ReturnType<typeof setTimeout> | null;
turn: { id: string; done: Promise<void>; interrupted: boolean } | null;
/** Items started in this turn and not yet completed, with their latest text. */
open: Map<string, Item>;
subscribers: Set<Connection>;
/** Whether the "editor tools unavailable" notice has been posted. */
noticedNoMcp: boolean;
};
const IDLE_MS = 10 * 60 * 1000;
const PROBE_MAX_AGE_MS = 60 * 1000;
export class AgentHost {
private readonly options: AgentHostOptions;
private readonly chats = new Map<string, Chat>();
private readonly connections = new Set<Connection>();
private readonly harnessById = new Map<HarnessId, Harness>();
private readonly probes = new Map<HarnessId, { info: HarnessInfo; at: number }>();
private probing: Promise<HarnessInfo[]> | null = null;
private probeAbort: AbortController | null = null;
private stopping = false;
constructor(options: AgentHostOptions) {
this.options = options;
for (const harness of options.harnesses) this.harnessById.set(harness.id, harness);
}
private log(message: string): void {
this.options.log?.(message);
}
// ---------------------------------------------------------------------
// Lifecycle
/** Loads the chat metas and settles anything a crash left running. */
async start(): Promise<void> {
for (const meta of await this.options.store.list()) {
const chat = this.register(meta);
if (meta.status !== "idle") {
// The harness process is gone with the last host; the turn is over.
await this.options.store.append(meta.id, { type: "turn.completed", turnId: "recovered", status: "interrupted" });
chat.meta = { ...meta, status: "idle" };
await this.options.store.writeMeta(chat.meta);
}
}
void this.probeAll();
}
async stop(): Promise<void> {
this.stopping = true;
this.probeAbort?.abort();
const chats = [...this.chats.values()];
await Promise.all(
chats.map(async (chat) => {
if (chat.idleTimer) clearTimeout(chat.idleTimer);
if (chat.turn) {
chat.turn.interrupted = true;
chat.session?.respond(chat.transcript.pending?.id ?? "", "cancel");
await chat.session?.interrupt().catch(() => {});
await chat.turn.done.catch(() => {});
}
await chat.session?.close().catch(() => {});
chat.session = null;
}),
);
}
// ---------------------------------------------------------------------
// Connections
connect(connection: Connection): { receive(raw: string): void; disconnect(): void } {
this.connections.add(connection);
connection.send({ t: "harnesses", harnesses: this.harnessList() });
return {
receive: (raw) => void this.receive(connection, raw),
disconnect: () => {
this.connections.delete(connection);
for (const chat of this.chats.values()) chat.subscribers.delete(connection);
},
};
}
private async receive(connection: Connection, raw: string): Promise<void> {
let message: ClientMsg;
try {
message = JSON.parse(raw) as ClientMsg;
} catch {
return;
}
if (!message || message.t !== "req" || typeof message.id !== "string") return;
try {
const data = await this.handle(connection, message.method, message.params);
connection.send({ t: "res", id: message.id, ok: true, data });
} catch (error) {
const failure =
error instanceof HostError ? error : new HostError("internal", (error as Error)?.message ?? String(error));
if (!(error instanceof HostError)) this.log(`${message.method} failed: ${failure.message}`);
connection.send({ t: "res", id: message.id, ok: false, error: { code: failure.code, message: failure.message } });
}
}
/** Dispatches one request. Public so tests can drive the host without a socket. */
async handle<M extends Method>(connection: Connection, method: M, params: unknown): Promise<MethodResult<M>> {
type R = MethodResult<M>;
const p = (params ?? {}) as MethodParams<M>;
switch (method) {
case "harnesses.list":
return this.listHarnesses((p as MethodParams<"harnesses.list">).refresh === true) as Promise<R>;
case "chats.list":
return this.listChats(requireString(p, "projectId")) as R;
case "chats.open":
return this.openChat(connection, requireString(p, "chatId")) as Promise<R>;
case "chats.close":
this.get(requireString(p, "chatId")).subscribers.delete(connection);
return undefined as R;
case "chats.delete":
return this.deleteChat(requireString(p, "chatId")) as Promise<R>;
case "turn.send":
return this.send(connection, p as MethodParams<"turn.send">) as Promise<R>;
case "turn.interrupt":
return this.interrupt(requireString(p, "chatId")) as Promise<R>;
case "attachments.upload":
return this.upload(p as MethodParams<"attachments.upload">) as Promise<R>;
case "request.respond": {
const { chatId, requestId, response } = p as MethodParams<"request.respond">;
return this.respond(requireString({ chatId }, "chatId"), requireString({ requestId }, "requestId"), response) as R;
}
default:
throw new HostError("bad-request", `Unknown method ${String(method)}`);
}
}
// ---------------------------------------------------------------------
// Attachments
/**
* A folder of its own per upload keeps the file's name — `image.png` for a
* screenshot — without two uploads landing on the same path.
*/
private async upload(params: MethodParams<"attachments.upload">): Promise<{ path: string }> {
const name = basename(requireString(params, "name")).replace(/^\.+/, "") || "pasted";
const data = requireString(params, "data");
const dir = join(this.options.uploadDir ?? join(tmpdir(), "diffusion-studio-pasted"), randomUUID());
await mkdir(dir, { recursive: true });
const path = join(dir, name);
await writeFile(path, Buffer.from(data, "base64"));
return { path };
}
// ---------------------------------------------------------------------
// Harnesses
private harnessList(): HarnessInfo[] {
return HARNESS_IDS.filter((id) => this.harnessById.has(id)).map(
(id) => this.probes.get(id)?.info ?? { id, label: HARNESS_LABELS[id], status: "checking", models: [] },
);
}
private async listHarnesses(refresh: boolean): Promise<HarnessInfo[]> {
const oldest = Math.min(...[...this.probes.values()].map((entry) => entry.at), Infinity);
const stale = this.probes.size < this.harnessById.size || Date.now() - oldest > (this.options.probeMaxAgeMs ?? PROBE_MAX_AGE_MS);
if (refresh && stale) return this.probeAll();
if (this.probing) return this.probing;
return this.harnessList();
}
private probeAll(): Promise<HarnessInfo[]> {
if (this.probing) return this.probing;
const abort = new AbortController();
this.probeAbort = abort;
this.probing = (async () => {
const env = await this.options.env;
await Promise.all(
[...this.harnessById.values()].map(async (harness) => {
let info: HarnessInfo;
try {
info = await harness.probe(env, abort.signal);
} catch (error) {
info = {
id: harness.id,
label: HARNESS_LABELS[harness.id],
status: "error",
detail: (error as Error)?.message ?? String(error),
models: [],
};
}
this.probes.set(harness.id, { info, at: Date.now() });
}),
);
const list = this.harnessList();
this.broadcast({ t: "harnesses", harnesses: list });
return list;
})().finally(() => {
this.probing = null;
if (this.probeAbort === abort) this.probeAbort = null;
});
return this.probing;
}
// ---------------------------------------------------------------------
// Chats
private register(meta: ChatMeta): Chat {
const chat: Chat = {
meta,
transcript: { items: [], pending: null, turnId: null, chat: null },
loaded: false,
seq: 0,
session: null,
idleTimer: null,
turn: null,
open: new Map(),
subscribers: new Set(),
noticedNoMcp: false,
};
this.chats.set(meta.id, chat);
return chat;
}
private get(chatId: string): Chat {
const chat = this.chats.get(chatId);
if (!chat) throw new HostError("not-found", `No chat ${chatId}`);
return chat;
}
private summary(chat: Chat): ChatSummary {
const { cwd: _cwd, resume: _resume, ...summary } = chat.meta;
return summary;
}
private listChats(projectId: string): ChatSummary[] {
return [...this.chats.values()]
.filter((chat) => chat.meta.projectId === projectId)
.sort((a, b) => b.meta.updatedAt - a.meta.updatedAt)
.map((chat) => this.summary(chat));
}
private async ensureLoaded(chat: Chat): Promise<void> {
if (chat.loaded) return;
const transcript = await this.options.store.readTranscript(chat.meta.id);
// A turn that started while the file was read has already put items in memory.
if (chat.loaded) return;
chat.transcript = { ...transcript, items: [...transcript.items, ...chat.transcript.items], pending: chat.transcript.pending, turnId: chat.transcript.turnId };
chat.loaded = true;
}
private async openChat(connection: Connection, chatId: string): Promise<ChatSnapshot> {
const chat = this.get(chatId);
await this.ensureLoaded(chat);
chat.subscribers.add(connection);
return { chat: this.summary(chat), items: chat.transcript.items, seq: chat.seq, pending: chat.transcript.pending };
}
private async deleteChat(chatId: string): Promise<void> {
const chat = this.get(chatId);
if (chat.turn) await this.interrupt(chatId);
if (chat.idleTimer) clearTimeout(chat.idleTimer);
await chat.session?.close().catch(() => {});
chat.session = null;
this.chats.delete(chatId);
await this.options.store.remove(chatId);
}
/** Deletes every chat of a project, stopping any that is running: its folder is gone. */
async deleteChats(projectId: string): Promise<void> {
const ids = [...this.chats.values()].filter((chat) => chat.meta.projectId === projectId).map((chat) => chat.meta.id);
await Promise.all(
ids.map((id) => this.deleteChat(id).catch((error: Error) => this.log(`delete ${id} failed: ${error.message}`))),
);
}
// ---------------------------------------------------------------------
// Turns
private async send(connection: Connection, params: MethodParams<"turn.send">): Promise<{ chatId: string }> {
const text = typeof params.text === "string" ? params.text : "";
const projectId = requireString(params, "projectId");
const cwd = requireString(params, "cwd");
const model = validateModel(params.model);
const attachments = Array.isArray(params.attachments) ? params.attachments.filter((a): a is string => typeof a === "string") : [];
if (!text.trim() && attachments.length === 0) throw new HostError("bad-request", "Nothing to send");
let chat: Chat;
if (params.chatId) {
chat = this.get(params.chatId);
if (chat.meta.harness !== model.harness) throw new HostError("harness-mismatch", "A chat keeps the harness it started with");
if (chat.turn) throw new HostError("busy", "A turn is already running");
await this.ensureLoaded(chat);
} else if (!this.harnessById.has(model.harness)) {
throw new HostError("harness-unavailable", `${HARNESS_LABELS[model.harness]} is not available`);
} else {
const now = Date.now();
chat = this.register({
id: randomUUID(),
projectId,
title: titleFor(text || attachments.map(baseName).join(", ")),
harness: model.harness,
model: model.model,
status: "idle",
createdAt: now,
updatedAt: now,
cwd,
resume: null,
});
chat.loaded = true;
chat.subscribers.add(connection);
}
const probe = this.probes.get(model.harness)?.info ?? (await this.probeAll()).find((info) => info.id === model.harness);
if (probe && probe.status !== "ready") {
if (!params.chatId) this.chats.delete(chat.meta.id);
throw new HostError("harness-unavailable", probe.detail ?? `${probe.label} is ${probe.status.replace("-", " ")}`);
}
if (chat.idleTimer) clearTimeout(chat.idleTimer);
chat.idleTimer = null;
// The project's folder moved since the session opened — a draft that was
// saved — and the session would go on working in the old one. Closed, it
// opens again in the new folder and resumes the same conversation: both
// harnesses find a session by its id, wherever it was started.
if (chat.session && chat.meta.cwd !== cwd) {
const session = chat.session;
chat.session = null;
await session.close().catch(() => {});
}
const turnId = randomUUID();
const user: Item = { id: `u-${turnId.slice(0, 12)}`, kind: "user", text, ...(attachments.length ? { attachments } : {}) };
chat.meta = { ...chat.meta, cwd, model: model.model, status: "running", updatedAt: Date.now() };
await this.options.store.writeMeta(chat.meta);
const emit = this.emitter(chat, turnId);
let resolveDone!: () => void;
const done = new Promise<void>((resolve) => (resolveDone = resolve));
chat.turn = { id: turnId, done, interrupted: false };
emit({ type: "chat.updated", chat: this.summary(chat) });
emit({ type: "turn.started", turnId, model: model.model, user });
void this.runTurn(chat, turnId, withAttachments(text, attachments), model.model, emit).finally(resolveDone);
return { chatId: chat.meta.id };
}
private emitter(chat: Chat, turnId: string): Emit {
return (event) => {
if (event.type === "turn.completed") event = { ...event, turnId };
chat.transcript = reduce(chat.transcript, event);
// Track what is still open, so an ended turn can close it out.
if (event.type === "item.started") chat.open.set(event.item.id, event.item);
else if (event.type === "item.completed") chat.open.delete(event.item.id);
else if (event.type === "item.delta" && chat.open.has(event.itemId)) {
const current = chat.transcript.items.find((item) => item.id === event.itemId);
if (current) chat.open.set(event.itemId, current);
}
if (event.type === "request.opened" && chat.meta.status === "running") {
chat.meta = { ...chat.meta, status: "waiting", updatedAt: Date.now() };
void this.options.store.writeMeta(chat.meta);
this.publish(chat, { type: "chat.updated", chat: this.summary(chat) });
} else if (event.type === "request.resolved" && chat.meta.status === "waiting" && chat.turn) {
chat.meta = { ...chat.meta, status: "running", updatedAt: Date.now() };
void this.options.store.writeMeta(chat.meta);
this.publish(chat, { type: "chat.updated", chat: this.summary(chat) });
}
this.publish(chat, event);
};
}
private publish(chat: Chat, event: ChatEvent): void {
chat.seq += 1;
if (isPersistedEvent(event)) {
this.options.store.append(chat.meta.id, event).catch((error: Error) => this.log(`append failed: ${error.message}`));
}
const message: HostMsg = { t: "event", chatId: chat.meta.id, seq: chat.seq, event };
for (const subscriber of chat.subscribers) subscriber.send(message);
}
private async runTurn(chat: Chat, turnId: string, text: string, model: string, emit: Emit): Promise<void> {
let outcome: TurnOutcome;
try {
if (!this.options.mcp && !chat.noticedNoMcp) {
chat.noticedNoMcp = true;
emit({ type: "item.completed", item: { id: `n-${turnId.slice(0, 12)}`, kind: "notice", level: "info", text: "Editor tools unavailable" } });
}
const session = await this.ensureSession(chat, model, emit);
outcome = (await session.send(text, model, emit)) ?? { status: "completed" };
} catch (error) {
const message = (error as Error)?.message ?? String(error);
outcome = chat.turn?.interrupted ? { status: "interrupted" } : { status: "failed", error: message };
if (!chat.turn?.interrupted) {
emit({ type: "item.completed", item: { id: `n-${turnId.slice(0, 12)}-err`, kind: "notice", level: "error", text: message } });
}
}
if (chat.turn?.interrupted && outcome.status === "completed") outcome = { status: "interrupted" };
this.finalizeOpen(chat, outcome.status, emit);
emit({ type: "turn.completed", turnId, status: outcome.status, ...(outcome.error ? { error: outcome.error } : {}) });
chat.turn = null;
chat.meta = { ...chat.meta, status: "idle", resume: chat.session?.resume ?? chat.meta.resume, updatedAt: Date.now() };
await this.options.store.writeMeta(chat.meta);
emit({ type: "chat.updated", chat: this.summary(chat) });
this.scheduleIdle(chat);
}
/** Whatever the harness left open is closed out so the log holds what was seen. */
private finalizeOpen(chat: Chat, status: TurnStatus, emit: Emit): void {
for (const item of [...chat.open.values()]) {
const latest = chat.transcript.items.find((entry) => entry.id === item.id) ?? item;
if (latest.kind === "tool") {
emit({ type: "item.completed", item: { ...latest, status: status === "completed" ? "done" : "failed" } });
} else if (latest.kind === "assistant" || latest.kind === "reasoning") {
if (latest.text) emit({ type: "item.completed", item: latest });
else chat.open.delete(item.id);
} else {
emit({ type: "item.completed", item: latest });
}
}
chat.open.clear();
}
private async ensureSession(chat: Chat, model: string, emit: Emit): Promise<HarnessSession> {
if (chat.session) return chat.session;
const harness = this.harnessById.get(chat.meta.harness);
if (!harness) throw new HostError("harness-unavailable", `${HARNESS_LABELS[chat.meta.harness]} is not available`);
const env = await this.options.env;
const session = await harness.open({
cwd: chat.meta.cwd,
model,
resume: chat.meta.resume ?? undefined,
mcp: this.options.mcp,
instructions: chatInstructions(chat.meta.cwd, this.options.instructions),
env,
emit,
});
chat.session = session;
chat.meta = { ...chat.meta, resume: session.resume };
return session;
}
private scheduleIdle(chat: Chat): void {
if (chat.idleTimer) clearTimeout(chat.idleTimer);
if (this.stopping) return;
chat.idleTimer = setTimeout(() => {
chat.idleTimer = null;
if (chat.turn) return;
const session = chat.session;
chat.session = null;
void session?.close().catch(() => {});
}, this.options.idleMs ?? IDLE_MS);
}
private async interrupt(chatId: string): Promise<void> {
const chat = this.get(chatId);
const turn = chat.turn;
if (!turn) return;
turn.interrupted = true;
const pending = chat.transcript.pending;
if (pending) chat.session?.respond(pending.id, "cancel");
await chat.session?.interrupt().catch(() => {});
await turn.done;
}
private respond(chatId: string, requestId: string, response: RequestResponse): void {
const chat = this.get(chatId);
const pending = chat.transcript.pending;
if (!pending || pending.id !== requestId || !chat.session) throw new HostError("no-request", "No question is waiting");
if (response !== "skip" && response !== "cancel" && (typeof response !== "object" || typeof response.answers !== "object")) {
throw new HostError("bad-request", "Malformed response");
}
chat.session.respond(requestId, response);
}
private broadcast(message: HostMsg): void {
for (const connection of this.connections) connection.send(message);
}
}
function requireString(record: object, key: string): string {
const value = (record as Record<string, unknown>)[key];
if (typeof value !== "string" || !value) throw new HostError("bad-request", `Missing ${key}`);
return value;
}
function validateModel(value: unknown): ModelRef {
const model = value as Partial<ModelRef> | undefined;
if (!model || !isHarnessId(model.harness) || typeof model.model !== "string") {
throw new HostError("bad-request", "Missing model");
}
return { harness: model.harness, model: model.model };
}
function baseName(path: string): string {
return path.replace(/[/\\]+$/, "").split(/[/\\]/).pop() || path;
}