@workerdeck/server 3.4.0 → 3.5.0

package/build/index.mjs

@@ -1,9 +1,9 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { createServer } from "node:http";
 import { WebSocketServer } from "ws";
-import { BrowserBridgeExecutor, PEER_MESSAGE_MAX_CHARS, PEER_RECENT_DEFAULT, PEER_RECENT_MAX, SHELL_REFUSAL, SHELL_REFUSAL as SHELL_REFUSAL$1, SessionRunner, TTY_REDRAW_CARRY, agentMayWrite, attachmentKind, checkClaudeAuth, clampShellTail, contextResetDirectoryHandle, createEngineSession, encodeShellKeys, getEngineAdapter, installContextResetDirectory, installPeerDirectory, installShellDirectory, isSlashCommand, normalizeMediaType, peerDirectoryHandle, peerSummary, recentLines, shellDirectoryHandle, shellOwnershipRefusal, shellSummary, shellTail, shellToolNeedsCard, ttyRedraws, ttyText, withoutGatewaySecrets } from "@workerdeck/core";
+import { BrowserBridgeExecutor, PEER_MESSAGE_MAX_CHARS, PEER_RECENT_DEFAULT, PEER_RECENT_MAX, SHELL_REFUSAL, SHELL_REFUSAL as SHELL_REFUSAL$1, SessionRunner, TTY_REDRAW_CARRY, agentMayWrite, attachmentKind, checkClaudeAuth, clampShellTail, composeInstructions, contextResetDirectoryHandle, createEngineSession, encodeShellKeys, getEngineAdapter, installContextResetDirectory, installPeerDirectory, installShellDirectory, isSlashCommand, normalizeMediaType, peerDirectoryHandle, peerSummary, recentLines, shellDirectoryHandle, shellOwnershipRefusal, shellSummary, shellTail, shellToolNeedsCard, ttyRedraws, ttyText, withoutGatewaySecrets } from "@workerdeck/core";
 import { JobQueue } from "@workerdeck/queue";
-import { ENGINE_CAPABILITIES, PEER_MENTION_MAX, PROTOCOL_VERSION, SHELL_ARTIFACT_MAX_BYTES, SHELL_ARTIFACT_TTL_MS, SHELL_ATTACH_REPLAY_BYTES, SHELL_COLS, SHELL_COMMAND_MAX, SHELL_INPUT_MAX, SHELL_LABEL_MAX, SHELL_LINGER_MS, SHELL_MAX_COLS, SHELL_MAX_ROWS, SHELL_MAX_RUNNING_PER_SESSION, SHELL_MAX_RUNNING_TOTAL, SHELL_MIN_COLS, SHELL_MIN_ROWS, SHELL_READ_MAX_LINES, SHELL_ROWS, SHELL_SPILL_BYTES, SHELL_TAIL_FLUSH_MS, SHELL_TAIL_RING_BYTES, SHELL_WAIT_DEFAULT_MS, SHELL_WAIT_MAX_MS, costOfByModel, imagePartRef, isJobRun, mergeByModel, mergePricing, peerMentionKey, peerMentionSlug, pickCreateSessionRequest, scanPeerMentions, sessionState, subscriptionComparison, supportsPermissionMode } from "@workerdeck/protocol";
+import { AGENT_SLEEP_AFTER_MS_DEFAULT, ENGINE_CAPABILITIES, PEER_MENTION_MAX, PROTOCOL_VERSION, SHELL_ARTIFACT_MAX_BYTES, SHELL_ARTIFACT_TTL_MS, SHELL_ATTACH_REPLAY_BYTES, SHELL_COLS, SHELL_COMMAND_MAX, SHELL_INPUT_MAX, SHELL_LABEL_MAX, SHELL_LINGER_MS, SHELL_MAX_COLS, SHELL_MAX_ROWS, SHELL_MAX_RUNNING_PER_SESSION, SHELL_MAX_RUNNING_TOTAL, SHELL_MIN_COLS, SHELL_MIN_ROWS, SHELL_READ_MAX_LINES, SHELL_ROWS, SHELL_SPILL_BYTES, SHELL_TAIL_FLUSH_MS, SHELL_TAIL_RING_BYTES, SHELL_WAIT_DEFAULT_MS, SHELL_WAIT_MAX_MS, agentRef, costOfByModel, imagePartRef, isJobRun, mergeByModel, mergePricing, peerMentionKey, peerMentionSlug, pickCreateSessionRequest, scanPeerMentions, sessionState, subscriptionComparison, supportsPermissionMode, teamReaches } from "@workerdeck/protocol";
 import { chmodSync, closeSync, constants, createReadStream, existsSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { arch, homedir, hostname, platform, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -520,7 +520,10 @@ const DEFAULT_PER_MINUTE = 10;
 const DEFAULT_MAX_HOPS = 12;
 const WINDOW_MS = 6e4;
 function visible(from, to) {
-	return to.id !== from.id && scopeMatches(from.scope, to.scope);
+	return to.id !== from.id && scopeMatches(from.scope, to.scope) && teamReaches(from.agent, to.agent);
+}
+function relayable(info, exposed) {
+	return info.status !== "closed" && info.agent?.lead === void 0 && scopeMatches(exposed, info.scope);
 }
 function relayEntry(info, live) {
 	const items = info.checklist;
@@ -681,11 +684,11 @@ function createPeerService(deps) {
 	};
 	const exposedInfo = async (sessionId, exposed) => {
 		const info = await infoOf(sessionId);
-		return info && info.status !== "closed" && scopeMatches(exposed, info.scope) ? info : void 0;
+		return info && relayable(info, exposed) ? info : void 0;
 	};
 	const relayEntries = async (exposed) => {
 		const live = new Set(registry().list().map((info) => info.id));
-		return (await allSessions()).filter((info) => info.status !== "closed" && scopeMatches(exposed, info.scope)).map((info) => relayEntry(info, live.has(info.id)));
+		return (await allSessions()).filter((info) => relayable(info, exposed)).map((info) => relayEntry(info, live.has(info.id)));
 	};
 	const relayPeek = async (sessionId, recent, exposed) => {
 		const info = await exposedInfo(sessionId, exposed);
@@ -743,8 +746,9 @@ function resolvePeerMentions(rows, text) {
 		else byKey.set(key, [row]);
 	};
 	for (const row of rows) {
-		add(peerMentionKey(peerMentionSlug(row.title, row.id)), row);
-		add(peerMentionKey(row.id), row);
+		const keys = /* @__PURE__ */ new Set([peerMentionKey(peerMentionSlug(row.title, row.id)), peerMentionKey(row.id)]);
+		if (row.agent) keys.add(peerMentionKey(peerMentionSlug(row.agent, row.id)));
+		for (const key of keys) add(key, row);
 	}
 	const resolved = [];
 	const seen = /* @__PURE__ */ new Set();
@@ -760,7 +764,7 @@ function resolvePeerMentions(rows, text) {
 		resolved.push({
 			typed: token.body,
 			id: target.id,
-			name: target.title,
+			name: target.agent ?? target.title,
 			engine: target.engine,
 			status: target.status,
 			cwd: target.cwd,
@@ -2372,6 +2376,576 @@ function machineId() {
 	return cached;
 }
 //#endregion
+//#region src/services/agents.ts
+const NAMES = [
+	"Atlas",
+	"Juno",
+	"Pip",
+	"Rook",
+	"Marlow",
+	"Orbit",
+	"Fern",
+	"Quill",
+	"Sable",
+	"Wren",
+	"Ember",
+	"Moss",
+	"Nova",
+	"Otto",
+	"Pike",
+	"Rune",
+	"Sage",
+	"Tansy",
+	"Vale",
+	"Yarrow",
+	"Basil",
+	"Cedar",
+	"Dune",
+	"Flint",
+	"Hazel",
+	"Iris",
+	"Kestrel",
+	"Lark",
+	"Maple",
+	"Nettle",
+	"Onyx",
+	"Piper",
+	"Reed",
+	"Sorrel",
+	"Thistle",
+	"Umber",
+	"Willow",
+	"Zephyr"
+];
+const MAX_NAME = 64;
+const MAX_BRIEF = 16e3;
+const CONFIG_KEYS = [
+	"cwd",
+	"profile",
+	"model",
+	"reasoningEffort",
+	"permissionMode",
+	"brief",
+	"agentContextReset",
+	"sleepAfterMs"
+];
+var AgentService = class {
+	#store;
+	#basePath;
+	#avatars;
+	#sleepAfterMs;
+	#now;
+	#agents = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.#store = options.store;
+		this.#basePath = options.basePath;
+		this.#avatars = options.avatars ?? false;
+		this.#sleepAfterMs = options.sleepAfterMs ?? AGENT_SLEEP_AFTER_MS_DEFAULT;
+		this.#now = options.now ?? Date.now;
+	}
+	async hydrate() {
+		this.#agents = new Map((await this.#store.list()).map((agent) => [agent.id, agent]));
+	}
+	list() {
+		return [...this.#agents.values()].map((agent) => this.public(agent));
+	}
+	get(id) {
+		return this.#agents.get(id);
+	}
+	bySession(sessionId) {
+		for (const agent of this.#agents.values()) if (agent.sessionId === sessionId) return agent;
+	}
+	decorate(info) {
+		const agent = this.bySession(info.id);
+		if (!agent) return info;
+		const leadName = agent.lead === void 0 ? void 0 : this.#agents.get(agent.lead)?.name;
+		return {
+			...info,
+			agent: agentRef(this.public(agent), {
+				leadName,
+				leads: this.hasMembers(agent.id)
+			})
+		};
+	}
+	briefFor(sessionId) {
+		return (sessionId === void 0 ? void 0 : this.bySession(sessionId)?.config.brief?.trim()) || void 0;
+	}
+	sleepAfterFor(sessionId) {
+		const agent = this.bySession(sessionId);
+		return agent ? agent.config.sleepAfterMs ?? this.#sleepAfterMs : void 0;
+	}
+	public(agent) {
+		const { avatarSeed: _seed, avatarRecipe: _recipe, avatar: _avatar, ...info } = agent;
+		return this.#avatars ? {
+			...info,
+			avatar: `${this.#basePath}/agents/${agent.id}/avatar.png`
+		} : info;
+	}
+	draft(input) {
+		const config = readConfig(input.config);
+		if ("error" in config) return config;
+		const name = input.name === void 0 ? this.#suggestName() : readName(input.name);
+		if (typeof name !== "string") return name;
+		const id = randomUUID();
+		const at = this.#now();
+		const agent = {
+			id,
+			name,
+			createdAt: at,
+			updatedAt: at,
+			avatarSeed: id,
+			pastSessions: [],
+			config
+		};
+		if (input.lead !== void 0 && input.lead !== null) {
+			const refused = typeof input.lead === "string" ? this.leadRefusal(agent, input.lead) : {
+				status: 400,
+				error: "lead must be an agent id"
+			};
+			if (refused) return refused;
+			agent.lead = input.lead;
+		}
+		return agent;
+	}
+	async save(agent) {
+		const stored = {
+			...agent,
+			updatedAt: this.#now()
+		};
+		await this.#store.save(stored);
+		this.#agents.set(stored.id, stored);
+		return stored;
+	}
+	async bind(agent, sessionId) {
+		const past = agent.sessionId !== void 0 && agent.sessionId !== sessionId ? [...agent.pastSessions, agent.sessionId] : agent.pastSessions;
+		return this.save({
+			...agent,
+			sessionId,
+			pastSessions: past
+		});
+	}
+	hasMembers(id) {
+		for (const agent of this.#agents.values()) if (agent.lead === id) return true;
+		return false;
+	}
+	members(id) {
+		return [...this.#agents.values()].filter((agent) => agent.lead === id).sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+	}
+	leadRefusal(mover, leadId) {
+		if (leadId === mover.id) return {
+			status: 409,
+			error: "an agent cannot lead its own team"
+		};
+		const lead = this.#agents.get(leadId);
+		if (!lead) return {
+			status: 404,
+			error: `no such agent: ${leadId}`
+		};
+		if (lead.lead !== void 0) return {
+			status: 409,
+			error: `${lead.name} is a member of a team; teams are one level deep`
+		};
+		if (this.hasMembers(mover.id)) return {
+			status: 409,
+			error: `${mover.name} leads a team; teams are one level deep`
+		};
+		return null;
+	}
+	async update(id, patch) {
+		const agent = this.#agents.get(id);
+		if (!agent) return {
+			status: 404,
+			error: `no such agent: ${id}`
+		};
+		const next = { ...agent };
+		if (patch.name !== void 0) {
+			const name = readName(patch.name);
+			if (typeof name !== "string") return name;
+			next.name = name;
+		}
+		if (patch.config !== void 0) {
+			if (!isRecord$1(patch.config)) return {
+				status: 400,
+				error: "config must be an object"
+			};
+			const config = readConfig({
+				...agent.config,
+				...patch.config
+			});
+			if ("error" in config) return config;
+			next.config = config;
+		}
+		if (patch.lead === null) delete next.lead;
+		else if (patch.lead !== void 0) {
+			if (typeof patch.lead !== "string") return {
+				status: 400,
+				error: "lead must be an agent id or null"
+			};
+			const refused = this.leadRefusal(agent, patch.lead);
+			if (refused) return refused;
+			next.lead = patch.lead;
+		}
+		if (patch.order !== void 0) {
+			if (typeof patch.order !== "number" || !Number.isFinite(patch.order)) return {
+				status: 400,
+				error: "order must be a number"
+			};
+			next.order = patch.order;
+		}
+		return this.save(next);
+	}
+	async retire(id, members) {
+		const agent = this.#agents.get(id);
+		if (!agent) return {
+			status: 404,
+			error: `no such agent: ${id}`
+		};
+		const crew = this.members(id);
+		const retired = [agent, ...members === "retire" ? crew : []];
+		const released = [];
+		if (members === "release") for (const member of crew) {
+			const { lead: _lead, ...rest } = member;
+			released.push(await this.save(rest));
+		}
+		for (const gone of retired) {
+			await this.#store.delete(gone.id);
+			this.#agents.delete(gone.id);
+		}
+		return {
+			retired,
+			released
+		};
+	}
+	#suggestName() {
+		const taken = new Set([...this.#agents.values()].map((agent) => agent.name.toLowerCase()));
+		const free = NAMES.find((name) => !taken.has(name.toLowerCase()));
+		if (free) return free;
+		for (let n = 2;; n++) {
+			const name = `${NAMES[n % NAMES.length]} ${n}`;
+			if (!taken.has(name.toLowerCase())) return name;
+		}
+	}
+};
+function isAgentRefusal(value) {
+	return isRecord$1(value) && typeof value.status === "number" && typeof value.error === "string";
+}
+function readName(value) {
+	if (typeof value !== "string" || value.trim() === "") return {
+		status: 400,
+		error: "name must be a non-empty string"
+	};
+	const name = value.trim();
+	return name.length > MAX_NAME ? {
+		status: 400,
+		error: `name is longer than ${MAX_NAME} characters`
+	} : name;
+}
+function readConfig(value) {
+	if (value === void 0) return {};
+	if (!isRecord$1(value)) return {
+		status: 400,
+		error: "config must be an object"
+	};
+	const config = {};
+	for (const key of CONFIG_KEYS) if (value[key] !== void 0) config[key] = value[key];
+	for (const key of [
+		"cwd",
+		"profile",
+		"model",
+		"reasoningEffort",
+		"permissionMode",
+		"brief"
+	]) if (config[key] !== void 0 && typeof config[key] !== "string") return {
+		status: 400,
+		error: `config.${key} must be a string`
+	};
+	if (config.agentContextReset !== void 0 && typeof config.agentContextReset !== "boolean") return {
+		status: 400,
+		error: "config.agentContextReset must be a boolean"
+	};
+	const sleep = config.sleepAfterMs;
+	if (sleep !== void 0 && (typeof sleep !== "number" || !Number.isFinite(sleep) || sleep < 0)) return {
+		status: 400,
+		error: "config.sleepAfterMs must be a non-negative number"
+	};
+	if (typeof config.brief === "string" && config.brief.length > MAX_BRIEF) return {
+		status: 400,
+		error: `config.brief is longer than ${MAX_BRIEF} characters`
+	};
+	return config;
+}
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/lib/host-only-keys.ts
+const HOST_ONLY_KEY_TABLE = {
+	epoch: "durable",
+	pricing: "transient",
+	queryFn: "transient",
+	env: "transient",
+	pathToClaudeCodeExecutable: "durable",
+	extraOptions: "transient",
+	instructions: "transient",
+	defaultApprovalTimeoutMs: "durable",
+	backfillHistory: "durable",
+	historyFn: "transient",
+	sessionInfoFn: "transient",
+	peers: "transient",
+	contextReset: "transient",
+	shells: "transient",
+	shellAgentWrite: "transient",
+	createdByOperator: "durable",
+	fallbackTitle: "transient",
+	startAsleep: "transient",
+	effortDefaults: "transient",
+	connectFn: "transient",
+	codexHome: "durable",
+	codexPathOverride: "durable",
+	languageModel: "transient",
+	tools: "transient",
+	maxSteps: "durable",
+	executor: "transient",
+	executableTools: "transient",
+	vfs: "transient",
+	executionLimits: "durable",
+	executionBackend: "transient",
+	toolTitles: "transient",
+	shouldApprove: "transient",
+	resolveModel: "transient",
+	contextWindow: "transient",
+	reportMcpServers: "transient",
+	onClose: "transient",
+	restore: "transient"
+};
+const HOST_ONLY_KEYS = new Set(Object.keys(HOST_ONLY_KEY_TABLE));
+const DURABLE_HOST_KEYS = Object.entries(HOST_ONLY_KEY_TABLE).filter(([, lifetime]) => lifetime === "durable").map(([key]) => key);
+//#endregion
+//#region src/routes/create-vet.ts
+function vetCreateRequest(ctx, body, auth) {
+	if (typeof body !== "object" || body === null || Array.isArray(body)) return {
+		ok: false,
+		status: 400,
+		error: "request body must be a JSON object"
+	};
+	const hostOnly = Object.keys(body).filter((key) => HOST_ONLY_KEYS.has(key));
+	if (hostOnly.length > 0) return {
+		ok: false,
+		status: 400,
+		error: `host-only runner config is not accepted on a session request: ${hostOnly.join(", ")} (set it from the gateway's buildRunnerConfig hook)`
+	};
+	const req = pickCreateSessionRequest(body);
+	const { availability, factory } = ctx;
+	const early = factory.applyScope(req, auth) ?? refusal(403, factory.applyBypassPolicy(req));
+	if (early) return {
+		ok: false,
+		...early
+	};
+	const resolved = factory.resolveProfile(req.profile, auth.allowedProfiles);
+	if (!resolved.ok) return resolved;
+	const refused = refusal(403, refuseHostAuthority(ctx, req, resolved.profile, auth)) ?? availability.checkAvailable(resolved.profile) ?? factory.checkCwd(req, resolved.profile) ?? refusal(400, factory.checkPermissionMode(req.permissionMode, resolved.profile) ?? factory.checkEngineGrants(req, resolved.profile));
+	if (refused) return {
+		ok: false,
+		...refused
+	};
+	factory.stripInertFields(req, resolved.profile);
+	req.profile = resolved.profile?.name;
+	return {
+		ok: true,
+		request: req
+	};
+}
+function refusal(status, error) {
+	return error === null ? null : {
+		status,
+		error
+	};
+}
+function refuseHostAuthority(ctx, req, profile, auth) {
+	if (ctx.auth.isOperator(auth)) return null;
+	const engine = engineOf(profile);
+	const name = profile?.name ?? "default";
+	if ((engine === "claude" || engine === "codex") && !auth.allowedProfiles?.includes(name)) return `profile '${name}' runs the ${engine} engine on the host; a non-operator caller needs it named in its allowedProfiles`;
+	const mode = refusePermissionMode(req.permissionMode, { operator: false });
+	if (mode) return mode;
+	if (req.allowDangerouslySkipPermissions) return "allowDangerouslySkipPermissions is reserved to operators";
+	if (req.settingSources !== void 0 && req.settingSources.length > 0) return "settingSources is reserved to operators: it loads hooks and settings from the host";
+	if (!(typeof req.mcpServers === "object" && req.mcpServers !== null ? Object.values(req.mcpServers) : []).every(isRemoteMcpServer)) return "a stdio MCP server is reserved to operators: it runs a command on the host";
+	if (req.resume !== void 0 && !ownsSdkSession(ctx, auth, req.resume)) return "resume is limited to a live session this caller can see";
+	return null;
+}
+function ownsSdkSession(ctx, auth, sdkSessionId) {
+	return ctx.registry.list().some((info) => info.sdkSessionId === sdkSessionId && ctx.auth.canSee(auth, info));
+}
+function isRemoteMcpServer(server) {
+	const type = server?.type;
+	return type === "http" || type === "sse";
+}
+//#endregion
+//#region src/routes/agents.ts
+async function handleAgents(ctx, req, res, pathname, auth) {
+	const agents = ctx.agents;
+	const rest = pathname.slice((ctx.basePath + "/agents").length).replace(/^\//, "");
+	if (rest === "") {
+		requireMethod(req, "GET", "POST");
+		if (req.method === "GET") {
+			json(res, 200, { agents: agents.list() });
+			return;
+		}
+		await createAgent(ctx, agents, req, res, auth);
+		return;
+	}
+	const [id, action, ...extra] = rest.split("/").map(decodeURIComponent);
+	const agent = id === void 0 ? void 0 : agents.get(id);
+	if (!agent || extra.length > 0) fail(404, "agent not found");
+	if (action === "restart") {
+		requireMethod(req, "POST");
+		const body = await readJsonBody(req, ctx.maxBodyBytes) ?? {};
+		const previous = agent.sessionId === void 0 ? void 0 : ctx.registry.get(agent.sessionId);
+		const created = await startSession(ctx, agent, typeof body.prompt === "string" ? body.prompt : void 0, auth);
+		const status = previous?.info().status;
+		if (previous && status !== "closed" && status !== "failed") previous.close("server");
+		await respond(ctx, res, 200, await bindWithAvatar(ctx, agent, created), created);
+		return;
+	}
+	if (action === "avatar.png" || action === "avatar-busy.png") {
+		requireMethod(req, "GET");
+		await sendAvatar(ctx, req, res, agent, action === "avatar-busy.png");
+		return;
+	}
+	if (action !== void 0) fail(404, "agent not found");
+	requireMethod(req, "GET", "PATCH", "DELETE");
+	if (req.method === "GET") {
+		await respond(ctx, res, 200, agent);
+		return;
+	}
+	if (req.method === "PATCH") {
+		const patch = await readJsonBody(req, ctx.maxBodyBytes);
+		const updated = await agents.update(agent.id, isRecord(patch) ? patch : {});
+		if (isAgentRefusal(updated)) fail(updated.status, updated.error);
+		await respond(ctx, res, 200, updated);
+		return;
+	}
+	const members = (await readJsonBody(req, ctx.maxBodyBytes) ?? {}).members === "retire" ? "retire" : "release";
+	const outcome = await agents.retire(agent.id, members);
+	if (isAgentRefusal(outcome)) fail(outcome.status, outcome.error);
+	for (const gone of outcome.retired) {
+		const runner = gone.sessionId === void 0 ? void 0 : ctx.registry.get(gone.sessionId);
+		const status = runner?.info().status;
+		if (runner && status !== "closed" && status !== "failed") runner.close("client");
+	}
+	json(res, 200, {
+		retired: outcome.retired.map((a) => a.id),
+		released: outcome.released.map((a) => a.id)
+	});
+}
+async function createAgent(ctx, agents, req, res, auth) {
+	const body = await readJsonBody(req, ctx.maxBodyBytes);
+	if (!isRecord(body)) fail(400, "request body must be a JSON object");
+	if (body.adopt !== void 0) {
+		await adoptSession(ctx, agents, res, body);
+		return;
+	}
+	const draft = agents.draft(body);
+	if (isAgentRefusal(draft)) fail(draft.status, draft.error);
+	const created = await startSession(ctx, draft, typeof body.prompt === "string" ? body.prompt : void 0, auth);
+	await respond(ctx, res, 201, await bindWithAvatar(ctx, draft, created), created);
+}
+async function adoptSession(ctx, agents, res, body) {
+	if (typeof body.adopt !== "string") fail(400, "adopt must be a session id");
+	const info = await sessionInfoOf(ctx, body.adopt);
+	if (!info) fail(404, "session not found");
+	if (agents.bySession(info.id)) fail(409, "that session already belongs to an agent");
+	const draft = agents.draft({
+		name: body.name ?? info.title,
+		config: {
+			...configOf(info),
+			...body.config
+		},
+		lead: body.lead
+	});
+	if (isAgentRefusal(draft)) fail(draft.status, draft.error);
+	await respond(ctx, res, 201, await bindWithAvatar(ctx, draft, info));
+}
+async function bindWithAvatar(ctx, agent, session) {
+	const recipe = agent.avatarRecipe ?? await rollAvatar(ctx, agent, session);
+	return ctx.agents.bind(recipe === void 0 ? agent : {
+		...agent,
+		avatarRecipe: recipe
+	}, session.id);
+}
+async function rollAvatar(ctx, agent, session) {
+	if (!ctx.avatars) return;
+	const project = session ? ctx.projects.withProject(session).project?.root ?? session.cwd : void 0;
+	try {
+		return await ctx.avatars.roll(agent.avatarSeed, session?.engine, project || void 0);
+	} catch {
+		return;
+	}
+}
+async function sendAvatar(ctx, req, res, agent, busy) {
+	const avatars = ctx.avatars;
+	if (!avatars) fail(404, "this gateway draws no avatars");
+	let recipe = agent.avatarRecipe;
+	if (recipe === void 0) {
+		recipe = await rollAvatar(ctx, agent, agent.sessionId === void 0 ? void 0 : await sessionInfoOf(ctx, agent.sessionId));
+		if (recipe === void 0) fail(503, "the avatar pack could not be loaded");
+		await ctx.agents.save({
+			...agent,
+			avatarRecipe: recipe
+		});
+	}
+	const image = busy ? await avatars.busy(recipe) : await avatars.still(recipe);
+	if (!image) fail(404, "this avatar pack has no busy animation");
+	const headers = {
+		"content-type": "image/png",
+		etag: image.etag,
+		"cache-control": "private, max-age=86400"
+	};
+	if (image.durations) headers["x-frame-durations"] = image.durations.join(",");
+	if (req.headers["if-none-match"] === image.etag) {
+		res.writeHead(304, headers).end();
+		return;
+	}
+	res.writeHead(200, headers).end(Buffer.from(image.png));
+}
+async function startSession(ctx, agent, prompt, auth) {
+	const { config } = agent;
+	const vetted = vetCreateRequest(ctx, stripUndefined({
+		cwd: config.cwd,
+		profile: config.profile,
+		model: config.model,
+		reasoningEffort: config.reasoningEffort,
+		permissionMode: config.permissionMode,
+		allowDangerouslySkipPermissions: config.permissionMode === "bypassPermissions" ? true : void 0,
+		agentContextReset: config.agentContextReset ?? true,
+		prompt
+	}), auth);
+	if (!vetted.ok) fail(vetted.status, vetted.error);
+	return (await ctx.factory.createRunner(ctx.factory.buildRunnerConfig(vetted.request, { operator: ctx.auth.isOperator(auth) }), { brief: config.brief?.trim() || void 0 })).info();
+}
+async function respond(ctx, res, status, agent, session) {
+	const info = session ?? (agent.sessionId === void 0 ? void 0 : await sessionInfoOf(ctx, agent.sessionId));
+	const body = { agent: ctx.agents.public(agent) };
+	if (info) body.session = ctx.projects.withProject(info);
+	json(res, status, body);
+}
+function configOf(info) {
+	return stripUndefined({
+		cwd: info.cwd || void 0,
+		profile: info.profile,
+		model: info.model,
+		reasoningEffort: info.effort ?? void 0,
+		permissionMode: info.permissionMode
+	});
+}
+function stripUndefined(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== void 0));
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
 //#region src/routes/executions.ts
 async function handleExecutionResult(ctx, req, res, pathname, auth) {
 	const { auth: authSvc, basePath, parking } = ctx;
@@ -2819,110 +3393,6 @@ async function handleWrite({ ctx, hostFiles, req, res }) {
 	});
 }
 //#endregion
-//#region src/lib/host-only-keys.ts
-const HOST_ONLY_KEY_TABLE = {
-	epoch: "durable",
-	pricing: "transient",
-	queryFn: "transient",
-	env: "transient",
-	pathToClaudeCodeExecutable: "durable",
-	extraOptions: "transient",
-	instructions: "transient",
-	defaultApprovalTimeoutMs: "durable",
-	backfillHistory: "durable",
-	historyFn: "transient",
-	sessionInfoFn: "transient",
-	peers: "transient",
-	contextReset: "transient",
-	shells: "transient",
-	shellAgentWrite: "transient",
-	createdByOperator: "durable",
-	fallbackTitle: "transient",
-	startAsleep: "transient",
-	effortDefaults: "transient",
-	connectFn: "transient",
-	codexHome: "durable",
-	codexPathOverride: "durable",
-	languageModel: "transient",
-	tools: "transient",
-	maxSteps: "durable",
-	executor: "transient",
-	executableTools: "transient",
-	vfs: "transient",
-	executionLimits: "durable",
-	executionBackend: "transient",
-	toolTitles: "transient",
-	shouldApprove: "transient",
-	resolveModel: "transient",
-	contextWindow: "transient",
-	reportMcpServers: "transient",
-	onClose: "transient",
-	restore: "transient"
-};
-const HOST_ONLY_KEYS = new Set(Object.keys(HOST_ONLY_KEY_TABLE));
-const DURABLE_HOST_KEYS = Object.entries(HOST_ONLY_KEY_TABLE).filter(([, lifetime]) => lifetime === "durable").map(([key]) => key);
-//#endregion
-//#region src/routes/create-vet.ts
-function vetCreateRequest(ctx, body, auth) {
-	if (typeof body !== "object" || body === null || Array.isArray(body)) return {
-		ok: false,
-		status: 400,
-		error: "request body must be a JSON object"
-	};
-	const hostOnly = Object.keys(body).filter((key) => HOST_ONLY_KEYS.has(key));
-	if (hostOnly.length > 0) return {
-		ok: false,
-		status: 400,
-		error: `host-only runner config is not accepted on a session request: ${hostOnly.join(", ")} (set it from the gateway's buildRunnerConfig hook)`
-	};
-	const req = pickCreateSessionRequest(body);
-	const { availability, factory } = ctx;
-	const early = factory.applyScope(req, auth) ?? refusal(403, factory.applyBypassPolicy(req));
-	if (early) return {
-		ok: false,
-		...early
-	};
-	const resolved = factory.resolveProfile(req.profile, auth.allowedProfiles);
-	if (!resolved.ok) return resolved;
-	const refused = refusal(403, refuseHostAuthority(ctx, req, resolved.profile, auth)) ?? availability.checkAvailable(resolved.profile) ?? factory.checkCwd(req, resolved.profile) ?? refusal(400, factory.checkPermissionMode(req.permissionMode, resolved.profile) ?? factory.checkEngineGrants(req, resolved.profile));
-	if (refused) return {
-		ok: false,
-		...refused
-	};
-	factory.stripInertFields(req, resolved.profile);
-	req.profile = resolved.profile?.name;
-	return {
-		ok: true,
-		request: req
-	};
-}
-function refusal(status, error) {
-	return error === null ? null : {
-		status,
-		error
-	};
-}
-function refuseHostAuthority(ctx, req, profile, auth) {
-	if (ctx.auth.isOperator(auth)) return null;
-	const engine = engineOf(profile);
-	const name = profile?.name ?? "default";
-	if ((engine === "claude" || engine === "codex") && !auth.allowedProfiles?.includes(name)) return `profile '${name}' runs the ${engine} engine on the host; a non-operator caller needs it named in its allowedProfiles`;
-	const mode = refusePermissionMode(req.permissionMode, { operator: false });
-	if (mode) return mode;
-	if (req.allowDangerouslySkipPermissions) return "allowDangerouslySkipPermissions is reserved to operators";
-	if (req.settingSources !== void 0 && req.settingSources.length > 0) return "settingSources is reserved to operators: it loads hooks and settings from the host";
-	if (!(typeof req.mcpServers === "object" && req.mcpServers !== null ? Object.values(req.mcpServers) : []).every(isRemoteMcpServer)) return "a stdio MCP server is reserved to operators: it runs a command on the host";
-	if (req.resume !== void 0 && !ownsSdkSession(ctx, auth, req.resume)) return "resume is limited to a live session this caller can see";
-	return null;
-}
-function ownsSdkSession(ctx, auth, sdkSessionId) {
-	return ctx.registry.list().some((info) => info.sdkSessionId === sdkSessionId && ctx.auth.canSee(auth, info));
-}
-function isRemoteMcpServer(server) {
-	const type = server?.type;
-	return type === "http" || type === "sse";
-}
-//#endregion
 //#region src/routes/jobs.ts
 async function handleJobs(ctx, req, res, pathname, auth) {
 	const { auth: authSvc, basePath, queue } = ctx;
@@ -3757,6 +4227,11 @@ function httpRoutes(ctx) {
 			auth: "any",
 			handler: (req, res, pathname, auth) => handleProfiles(ctx, req, res, pathname, auth)
 		}),
+		route({
+			match: pathWhere(under("/agents")),
+			auth: "operator",
+			handler: (req, res, pathname, auth) => handleAgents(ctx, req, res, pathname, auth)
+		}),
 		route({
 			match: pathWhere((pathname) => pathname.startsWith(base + "/executions/")),
 			auth: "any",
@@ -3824,6 +4299,36 @@ function pathWhere(test) {
 	return (pathname) => test(pathname) ? pathname : void 0;
 }
 //#endregion
+//#region src/services/agent-store.ts
+function createMemoryAgentStore(seed = []) {
+	const agents = new Map(seed.map((a) => [a.id, a]));
+	return {
+		list: () => [...agents.values()],
+		save: (agent) => void agents.set(agent.id, agent),
+		delete: (id) => void agents.delete(id)
+	};
+}
+function createFileAgentStore(path = join(process.cwd(), ".workerdeck", "agents.json")) {
+	const read = () => {
+		const parsed = readJsonOrSync(path, []);
+		if (!Array.isArray(parsed)) return /* @__PURE__ */ new Map();
+		return new Map(parsed.filter((a) => a && typeof a.id === "string" && typeof a.name === "string").map((a) => [a.id, a]));
+	};
+	const write = (agents) => writeJsonAtomicSync(path, [...agents.values()], { indent: 2 });
+	return {
+		list: () => [...read().values()],
+		save: (agent) => {
+			const agents = read();
+			agents.set(agent.id, agent);
+			write(agents);
+		},
+		delete: (id) => {
+			const agents = read();
+			if (agents.delete(id)) write(agents);
+		}
+	};
+}
+//#endregion
 //#region src/services/attachments.ts
 const DEFAULT_MAX_FILE_BYTES = 10485760;
 const DEFAULT_MAX_SESSION_BYTES = 67108864;
@@ -4044,7 +4549,7 @@ var EngineSleepTimers = class {
 		return this.#options.afterMs > 0 && !this.#closed;
 	}
 	watch(runner) {
-		if (!this.enabled || !runner.sleep) return;
+		if (this.#closed || !runner.sleep || !this.enabled && !this.#options.afterMsFor) return;
 		this.#runners.set(runner.id, runner);
 		const unsubscribe = runner.subscribe((event) => {
 			if (event.type === "status_changed") this.#rearm(runner);
@@ -4066,14 +4571,18 @@ var EngineSleepTimers = class {
 		this.#timers.clear();
 		this.#runners.clear();
 	}
+	#afterMs(sessionId) {
+		return this.#closed ? 0 : this.#options.afterMsFor?.(sessionId) ?? this.#options.afterMs;
+	}
 	#rearm(runner) {
 		this.#disarm(runner.id);
-		if (!this.enabled || !this.#sleepable(runner)) return;
+		const afterMs = this.#afterMs(runner.id);
+		if (afterMs <= 0 || !this.#sleepable(runner)) return;
 		const timer = setTimeout(() => {
 			this.#timers.delete(runner.id);
-			if (!this.enabled || !this.#sleepable(runner)) return;
+			if (this.#afterMs(runner.id) <= 0 || !this.#sleepable(runner)) return;
 			runner.sleep?.().catch((error) => this.#options.onError?.(error, runner.id));
-		}, this.#options.afterMs);
+		}, afterMs);
 		timer.unref?.();
 		this.#timers.set(runner.id, timer);
 	}
@@ -5229,7 +5738,7 @@ function createRelayLink(options, peers, log) {
 	const remoteTarget = parseRelayPeerId;
 	const reachesRemote = async (from) => {
 		const me = await peers.relaySender(from);
-		return me.scope === void 0 || Object.keys(me.scope).length === 0;
+		return (me.scope === void 0 || Object.keys(me.scope).length === 0) && me.agent?.lead === void 0;
 	};
 	return {
 		directory: {
@@ -5507,7 +6016,7 @@ function createSessionFactory(deps) {
 			return adapterFor(profile.engine).sessionEnv?.(profile, process.env) ?? process.env;
 		}
 	};
-	const buildRunner = async (built, restore, id) => {
+	const buildRunner = async (built, restore, id, options) => {
 		const name = built.profile;
 		const profile = name !== void 0 ? profiles.get(name) : void 0;
 		if (name !== void 0 && !profile) throw new Error(`unknown profile: ${name}`);
@@ -5532,6 +6041,8 @@ function createSessionFactory(deps) {
 			const write = deps.shellAgentWrite ?? "read-only";
 			if (write !== "read-only" && built.createdByOperator === true) config.shellAgentWrite = write;
 		}
+		const brief = options?.brief ?? deps.agentBrief?.(id ?? restore?.id);
+		if (brief) config.instructions = composeInstructions(config.instructions, brief);
 		if (config.instructions !== void 0 && capabilities.systemInstructions === false) throw new Error(`the ${engineOf(profile)} engine cannot deliver system instructions`);
 		const runner = profile && isProviderProfile(profile) ? await deps.createEngineRunner({
 			config,
@@ -5549,8 +6060,8 @@ function createSessionFactory(deps) {
 		if (!sameScope(reported, config.scope)) throw new Error(`runner for session ${runner.id} reports scope ${JSON.stringify(reported)}, expected ${JSON.stringify(config.scope)} - echo config.scope from info()`);
 		return runner;
 	};
-	const createRunner = async (config) => {
-		const runner = registry.register(await buildRunner(config));
+	const createRunner = async (config, options) => {
+		const runner = registry.register(await buildRunner(config, void 0, void 0, options));
 		parking.remember(runner.id, config);
 		parking.watch(runner);
 		runner.start();
@@ -5669,7 +6180,13 @@ function createWorkerServer(options = {}) {
 	}
 	const generation = randomUUID();
 	const shells = options.shell?.enabled === true ? shellRegistryFor(options.shell, generation) : null;
-	const projects = new ProjectInfoService({ decorate: (info) => shells ? shells.decorate(info) : info });
+	const agents = new AgentService({
+		store: options.agentStore ?? createMemoryAgentStore(),
+		basePath,
+		avatars: options.avatars !== void 0,
+		sleepAfterMs: options.agentSleepAfterMs
+	});
+	const projects = new ProjectInfoService({ decorate: (info) => agents.decorate(shells ? shells.decorate(info) : info) });
 	const notifier = new SessionNotifier({
 		...options.notifications,
 		decorateInfo: (info) => projects.withProject(info),
@@ -5678,6 +6195,7 @@ function createWorkerServer(options = {}) {
 	const producedFiles = new ProducedFileStore();
 	const engineSleep = new EngineSleepTimers({
 		afterMs: options.engineSleepAfterMs ?? 0,
+		afterMsFor: (sessionId) => agents.sleepAfterFor(sessionId),
 		attachedCount: (sessionId) => bridge.attachedCount(sessionId),
 		onError: (error) => diagnose(error, "engine-sleep")
 	});
@@ -5764,7 +6282,8 @@ function createWorkerServer(options = {}) {
 		pricing: pricing.pricing,
 		registry,
 		parking,
-		bridge
+		bridge,
+		agentBrief: (sessionId) => agents.briefFor(sessionId)
 	});
 	const availability = new AvailabilityTracker({
 		checkCredentials: options.checkCredentials,
@@ -5812,6 +6331,8 @@ function createWorkerServer(options = {}) {
 		availability,
 		auth,
 		factory,
+		agents,
+		avatars: options.avatars,
 		registry,
 		parking,
 		engineSleep,
@@ -5883,6 +6404,7 @@ function createWorkerServer(options = {}) {
 		listen: async (port, host) => {
 			await profiles.refreshStored();
 			await profiles.seedStore();
+			await agents.hydrate();
 			await parking.hydrate();
 			await shells?.hydrate();
 			return new Promise((resolve, reject) => {
@@ -6078,6 +6600,6 @@ function createFileProfileStore(path = join(process.cwd(), ".workerdeck", "profi
 	};
 }
 //#endregion
-export { AttachmentStore, BridgeHub, MemorySessionStore, ProducedFileStore, ProfileUsageTracker, SHELL_REFUSAL, SessionNotifier, SessionParkManager, SessionRegistry, SpendLedger, createFileProfileStore, createFileSessionStore, createFileSpendStore, createMemoryProfileStore, createProviderRunner, createShellDirectory, createShellRegistry, createWorkerServer, dayKey, isDormant, isMissing, readJsonOr, reloadPlan, sandboxedProviderProfile, shellPermitted, toDurableRecord, writeFileAtomic, writeJsonAtomic };
+export { AttachmentStore, BridgeHub, MemorySessionStore, ProducedFileStore, ProfileUsageTracker, SHELL_REFUSAL, SessionNotifier, SessionParkManager, SessionRegistry, SpendLedger, createFileAgentStore, createFileProfileStore, createFileSessionStore, createFileSpendStore, createMemoryAgentStore, createMemoryProfileStore, createProviderRunner, createShellDirectory, createShellRegistry, createWorkerServer, dayKey, isDormant, isMissing, readJsonOr, reloadPlan, sandboxedProviderProfile, shellPermitted, toDurableRecord, writeFileAtomic, writeJsonAtomic };
 
 //# sourceMappingURL=index.mjs.map