@zvada/agent-server 0.2.0

package/src/core/runtime/agent-runtime.ts

@@ -0,0 +1,363 @@
+import type {
+	AgentCapabilities,
+	AgentHarness,
+	LifecycleEvent,
+	PermissionOption,
+	PermissionOutcome,
+	PermissionToolCall,
+	RunRequest,
+	StopReason,
+	TokenUsage,
+} from "../../protocol/index.ts";
+import { DEFAULT_TOKEN_USAGE, generateUUIDv7 } from "../../protocol/index.ts";
+import type { AgentExecuteOptions, PermissionDecision } from "../agents/base.ts";
+import {
+	type ErrorCategory,
+	classifyError,
+	isCancellation,
+	isRecoverable,
+} from "../agents/error-classifier.ts";
+import type { AgentRegistry } from "../agents/registry.ts";
+import { EventProcessor } from "./event-processor.ts";
+import type { EventSink } from "./event-sink.ts";
+
+/** What a completed turn reports back to the caller (in addition to the streamed events). */
+export interface RunSummary {
+	sessionId: string;
+	turnId: string;
+	harness: AgentHarness;
+	/** Native session/thread id to persist for a future resume. */
+	nativeSessionId?: string;
+	/** When the turn requested a resume: whether the harness honored it. */
+	resumed?: boolean;
+	usage: TokenUsage;
+	/** Normalized terminal status (same value as the `turn.ended` event). */
+	stopReason: StopReason;
+	finishReason?: string;
+	cost?: number;
+	error?: { category: ErrorCategory; message: string };
+	cancelled: boolean;
+}
+
+/** The standard options offered for every brokered permission request. */
+const PERMISSION_OPTIONS: PermissionOption[] = [
+	{ optionId: "allow", name: "Allow", kind: "allow_once" },
+	{ optionId: "reject", name: "Reject", kind: "reject_once" },
+];
+
+interface PendingPermission {
+	sessionId: string;
+	/** Resolves the request and emits `permission.resolved`; await the returned
+	 * promise to order that emit (the turn-end drain does, so it lands before
+	 * `turn.ended`). */
+	settle: (outcome: PermissionOutcome) => void | Promise<void>;
+}
+
+/**
+ * The engine. Owns no transport and no harness specifics: it routes a
+ * RunRequest to the right harness + adapter, drives the per-turn loop, brokers
+ * permission round-trips, and streams normalized LifecycleEvents to a sink.
+ */
+export class AgentRuntime {
+	/** Permission requests awaiting `respondPermission`, across all live turns. */
+	private readonly pendingPermissions = new Map<string, PendingPermission>();
+	private readonly activeRuns = new Set<Promise<RunSummary>>();
+	private shutdownPromise?: Promise<void>;
+
+	constructor(private readonly registry: AgentRegistry) {}
+
+	get harnesses(): AgentHarness[] {
+		return this.registry.list();
+	}
+
+	capabilities(harness: AgentHarness): AgentCapabilities {
+		return this.registry.getAgent(harness).capabilities;
+	}
+
+	/**
+	 * Answer a pending `permission.requested` event. Returns false when the
+	 * request is unknown (already resolved, cancelled, or a sessionId mismatch).
+	 */
+	respondPermission(sessionId: string, requestId: string, outcome: PermissionOutcome): boolean {
+		const pending = this.pendingPermissions.get(requestId);
+		if (!pending || pending.sessionId !== sessionId) return false;
+		void pending.settle(outcome);
+		return true;
+	}
+
+	run(
+		request: RunRequest,
+		sink: EventSink,
+		opts: { signal?: AbortSignal } = {},
+	): Promise<RunSummary> {
+		if (this.shutdownPromise) return Promise.reject(new Error("agent runtime is shutting down"));
+		const running = this.executeRun(request, sink, opts);
+		this.activeRuns.add(running);
+		running.then(
+			() => this.activeRuns.delete(running),
+			() => this.activeRuns.delete(running),
+		);
+		return running;
+	}
+
+	private async executeRun(
+		request: RunRequest,
+		sink: EventSink,
+		opts: { signal?: AbortSignal },
+	): Promise<RunSummary> {
+		const { sessionId, turnId, input, config } = request;
+		const agent = this.registry.getAgent(config.harness);
+		const transformer = this.registry.getAdapter(config.harness)({ sessionId });
+		const processor = new EventProcessor(sessionId, turnId, {
+			harness: config.harness,
+			model: config.model,
+		});
+
+		// Isolate sink failures: a misbehaving transport must never break the
+		// turn's lifecycle bracketing (turn.started ... turn.ended).
+		const emit = async (e: LifecycleEvent) => {
+			try {
+				await sink.emit(e);
+			} catch {
+				// swallow — the sink owns its own reliability
+			}
+		};
+
+		let nativeSessionId: string | undefined;
+		let resumed: boolean | undefined;
+		let sessionEmitted = false;
+		const flushSession = async () => {
+			if (nativeSessionId && !sessionEmitted) {
+				sessionEmitted = true;
+				await emit({
+					type: "session.created",
+					sessionId,
+					nativeSessionId,
+					harness: config.harness,
+					model: config.model,
+					...(resumed !== undefined && { resumed }),
+					timestamp: Date.now(),
+				});
+			}
+		};
+
+		// --- permission broker (one scope per turn) ----------------------------
+		const turnRequestIds = new Set<string>();
+		const requestPermission = async (
+			toolCall: PermissionToolCall,
+			permOpts?: { signal?: AbortSignal },
+		): Promise<PermissionDecision> => {
+			if (permOpts?.signal?.aborted) return { decision: "cancel" };
+			const requestId = generateUUIDv7();
+			// Register BEFORE emitting so even a sink that answers synchronously
+			// from its emit() finds the pending entry.
+			let resolveOutcome!: (o: PermissionOutcome) => void;
+			const outcomePromise = new Promise<PermissionOutcome>((resolve) => {
+				resolveOutcome = resolve;
+			});
+			const settle = (o: PermissionOutcome): Promise<void> | void => {
+				if (!this.pendingPermissions.delete(requestId)) return;
+				turnRequestIds.delete(requestId);
+				resolveOutcome(o);
+				// Returned so the in-run drain can sequence this before turn.ended;
+				// external callers (respondPermission/cancel) ignore it.
+				return emit({
+					type: "permission.resolved",
+					sessionId,
+					turnId,
+					requestId,
+					outcome: o,
+					timestamp: Date.now(),
+				});
+			};
+			this.pendingPermissions.set(requestId, { sessionId, settle });
+			turnRequestIds.add(requestId);
+			permOpts?.signal?.addEventListener("abort", () => void settle({ outcome: "cancelled" }), {
+				once: true,
+			});
+			await emit({
+				type: "permission.requested",
+				sessionId,
+				turnId,
+				requestId,
+				title: toolCall.title ?? `Allow tool: ${toolCall.toolName}`,
+				toolCall,
+				options: PERMISSION_OPTIONS,
+				timestamp: Date.now(),
+			});
+			const outcome = await outcomePromise;
+			if (outcome.outcome === "cancelled") return { decision: "cancel" };
+			const selected = PERMISSION_OPTIONS.find((o) => o.optionId === outcome.optionId);
+			return selected?.kind === "allow_once" || selected?.kind === "allow_always"
+				? { decision: "allow" }
+				: { decision: "deny", reason: "Denied by user" };
+		};
+		/** Cancellation / turn end resolves everything still pending as cancelled.
+		 * Awaited so every `permission.resolved` is emitted before `turn.ended`. */
+		const drainPermissions = async () => {
+			const settles = [...turnRequestIds].map((requestId) =>
+				this.pendingPermissions.get(requestId)?.settle({ outcome: "cancelled" }),
+			);
+			await Promise.all(settles);
+		};
+
+		await emit({ type: "turn.started", turnId, sessionId, timestamp: Date.now() });
+
+		const options: AgentExecuteOptions = {
+			sessionId,
+			turnId,
+			cwd: config.cwd,
+			model: config.model,
+			thinkingLevel: config.thinkingLevel,
+			permissionMode: config.permissionMode,
+			maxTurns: config.maxTurns,
+			systemPromptAppend: config.systemPromptAppend,
+			resumeSessionId: config.resumeSessionId,
+			resumeSessionAt: config.resumeSessionAt,
+			additionalDirectories: config.additionalDirectories,
+			mcpServers: config.mcpServers,
+			env: config.env,
+			apiKey: config.apiKey,
+			disableTools: config.disableTools,
+			signal: opts.signal,
+			onNativeSession: (id, info) => {
+				// Agents report exactly once per turn (the claude fallback defers its
+				// report until the surviving session is known); guard against a
+				// misbehaving harness re-reporting after emission. Agents always pass
+				// their honest `resumed` judgment — the runtime surfaces it only when
+				// this turn actually REQUESTED a resume.
+				if (sessionEmitted) return;
+				nativeSessionId = id;
+				if (config.resumeSessionId && info?.resumed !== undefined) resumed = info.resumed;
+			},
+			onPermissionRequest: requestPermission,
+		};
+
+		let cancelled = false;
+		let errored: { category: ErrorCategory; message: string } | undefined;
+
+		try {
+			for await (const raw of agent.execute(input, options)) {
+				await flushSession();
+				if (config.includeRaw) {
+					await emit({
+						type: "raw",
+						sessionId,
+						turnId,
+						harness: config.harness,
+						data: raw,
+						timestamp: Date.now(),
+					});
+				}
+				for (const ae of transformer.process(raw)) {
+					for (const le of processor.handle(ae)) await emit(le);
+				}
+			}
+			await flushSession();
+		} catch (err) {
+			cancelled = isCancellation(err);
+			if (!cancelled) {
+				const category = classifyError(err);
+				const message = err instanceof Error ? err.message : String(err);
+				errored = { category, message };
+				await emit({
+					type: "error",
+					turnId,
+					sessionId,
+					error: message,
+					recoverable: isRecoverable(category),
+					code: category,
+					stack: err instanceof Error ? err.stack : undefined,
+					timestamp: Date.now(),
+				});
+			}
+		} finally {
+			await drainPermissions();
+		}
+
+		const result = transformer.finish();
+		cancelled = cancelled || Boolean(result.cancelled);
+		if (result.error && !errored && !cancelled) {
+			errored = { category: classifyError(new Error(result.error)), message: result.error };
+		}
+		const stopReason: StopReason = cancelled
+			? "cancelled"
+			: errored
+				? "error"
+				: (result.stopReason ?? "end_turn");
+		const terminalResult =
+			errored && !result.error ? { ...result, error: errored.message } : result;
+		for (const le of processor.finish(terminalResult, stopReason)) await emit(le);
+
+		return {
+			sessionId,
+			turnId,
+			harness: config.harness,
+			nativeSessionId,
+			...(resumed !== undefined && { resumed }),
+			usage: result.usage ?? DEFAULT_TOKEN_USAGE,
+			stopReason,
+			finishReason: result.finishReason,
+			cost: result.cost,
+			error: errored,
+			cancelled,
+		};
+	}
+
+	async cancel(harness: AgentHarness, sessionId: string): Promise<void> {
+		// Unblock any harness parked on an approval before (and regardless of)
+		// the agent-level abort. `settle` removes the entry from the map itself.
+		for (const pending of [...this.pendingPermissions.values()]) {
+			if (pending.sessionId === sessionId) void pending.settle({ outcome: "cancelled" });
+		}
+		await this.registry.getAgent(harness).cancel(sessionId);
+	}
+
+	/** Dispose one idle logical session and its harness-native resources. */
+	async closeSession(harness: AgentHarness, sessionId: string): Promise<void> {
+		await Promise.all(
+			[...this.pendingPermissions.values()]
+				.filter((pending) => pending.sessionId === sessionId)
+				.map((pending) => pending.settle({ outcome: "cancelled" })),
+		);
+		const agent = this.registry.getAgent(harness);
+		if (agent.release) await agent.release(sessionId);
+		else await agent.cancel(sessionId);
+	}
+
+	/** Give up on stragglers after this long; the process is exiting anyway. */
+	private static readonly DEFAULT_DRAIN_TIMEOUT_MS = 10_000;
+
+	shutdown(opts: { drainTimeoutMs?: number } = {}): Promise<void> {
+		// Memoized: the first caller's timeout wins.
+		this.shutdownPromise ??= this.performShutdown(
+			opts.drainTimeoutMs ?? AgentRuntime.DEFAULT_DRAIN_TIMEOUT_MS,
+		);
+		return this.shutdownPromise;
+	}
+
+	private async performShutdown(drainTimeoutMs: number): Promise<void> {
+		await Promise.all(
+			[...this.pendingPermissions.values()].map((pending) =>
+				pending.settle({ outcome: "cancelled" }),
+			),
+		);
+		this.pendingPermissions.clear();
+		let terminationError: unknown;
+		try {
+			await this.registry.terminateAll();
+		} catch (error) {
+			terminationError = error;
+		}
+		// Drain active runs, but don't let a harness that ignores its abort
+		// signal hang the process's shutdown forever.
+		await Promise.race([
+			Promise.allSettled([...this.activeRuns]),
+			new Promise<void>((resolve) => {
+				const timer = setTimeout(resolve, drainTimeoutMs);
+				timer.unref?.();
+			}),
+		]);
+		if (terminationError !== undefined) throw terminationError;
+	}
+}

package/src/core/runtime/event-processor.ts

@@ -0,0 +1,218 @@
+import { generateUUIDv7 } from "../../protocol/index.ts";
+import type { Delta, LifecycleEvent, Part, StopReason } from "../../protocol/index.ts";
+import type { AdapterEvent, TransformResult } from "../agents/types.ts";
+
+/** Where a part lives on the wire — fixed at first emission for the whole turn. */
+interface PartAddress {
+	messageId: string;
+	outputIndex: number;
+	partIndex: number;
+}
+
+/**
+ * Turns the harness-agnostic AdapterEvent stream into wire LifecycleEvents.
+ * Owns all id/index bookkeeping: assigns message ids, per-message output
+ * indices, and per-part indices, and brackets messages with started/ended.
+ *
+ * Parts are registered turn-wide: a part keeps the message/indices of its
+ * first emission even when updated after that message ended (e.g. a tool
+ * completing after the model message that issued it) — consumers upsert by
+ * `part.id`. One instance per turn.
+ */
+export class EventProcessor {
+	private openMessageId?: string;
+	/** `parentToolUseId` of the open message (undefined for top-level messages). */
+	private openMessageParent?: string;
+	private currentOutputIndex = -1;
+	private nextOutputIndex = 0;
+	private nextPartIndex = 0;
+	private readonly partAddressById = new Map<string, PartAddress>();
+
+	constructor(
+		private readonly sessionId: string,
+		private readonly turnId: string,
+		private readonly meta: { harness?: string; model?: string } = {},
+	) {}
+
+	*handle(ev: AdapterEvent): Generator<LifecycleEvent> {
+		switch (ev.kind) {
+			case "message-start":
+				yield* this.openMessage(ev.role);
+				return;
+			case "message-end":
+				yield* this.closeMessage();
+				return;
+			case "part-open":
+			case "part-update":
+				yield* this.emitPart(ev.part);
+				return;
+			case "text-delta": {
+				const e = this.delta(ev.partId, { type: "text-delta", text: ev.text });
+				if (e) yield e;
+				return;
+			}
+			case "reasoning-delta": {
+				const e = this.delta(ev.partId, { type: "reasoning-delta", text: ev.text });
+				if (e) yield e;
+				return;
+			}
+			case "tool-input-delta": {
+				const e = this.delta(ev.partId, {
+					type: "tool-input-delta",
+					toolCallId: ev.toolCallId,
+					toolName: ev.toolName,
+					input: ev.input,
+				});
+				if (e) yield e;
+				return;
+			}
+			case "usage":
+				yield {
+					type: "session.usage",
+					sessionId: this.sessionId,
+					turnId: this.turnId,
+					used: ev.used,
+					...(ev.size !== undefined && { size: ev.size }),
+					...(ev.cost !== undefined && { cost: ev.cost }),
+					timestamp: Date.now(),
+				};
+				return;
+			case "compacted":
+				yield {
+					type: "session.compacted",
+					sessionId: this.sessionId,
+					turnId: this.turnId,
+					...(ev.trigger && { trigger: ev.trigger }),
+					...(ev.preTokens !== undefined && { preTokens: ev.preTokens }),
+					...(ev.postTokens !== undefined && { postTokens: ev.postTokens }),
+					timestamp: Date.now(),
+				};
+				return;
+		}
+	}
+
+	*finish(result: TransformResult, stopReason: StopReason): Generator<LifecycleEvent> {
+		yield* this.closeMessage();
+		yield {
+			type: "turn.ended",
+			turnId: this.turnId,
+			sessionId: this.sessionId,
+			stopReason,
+			finishReason: result.finishReason,
+			tokens: result.usage,
+			cost: result.cost,
+			error:
+				result.error && !result.cancelled
+					? { name: "AgentError", message: result.error }
+					: undefined,
+			timestamp: Date.now(),
+		};
+	}
+
+	private *openMessage(
+		role: "assistant" | "user",
+		parentToolUseId?: string,
+	): Generator<LifecycleEvent> {
+		if (this.openMessageId) yield* this.closeMessage();
+		const messageId = generateUUIDv7();
+		this.openMessageId = messageId;
+		this.openMessageParent = parentToolUseId;
+		this.currentOutputIndex = this.nextOutputIndex++;
+		this.nextPartIndex = 0;
+		yield {
+			type: "message.started",
+			turnId: this.turnId,
+			messageId,
+			outputIndex: this.currentOutputIndex,
+			role,
+			// A parented message is a sub-agent's output — nests under its tool call,
+			// not a top-level model message (see DESIGN.md D5).
+			...(parentToolUseId && { parentToolUseId }),
+			timestamp: Date.now(),
+			metadata: {
+				sessionId: this.sessionId,
+				...(this.meta.harness && { harness: this.meta.harness }),
+				...(this.meta.model && { model: this.meta.model }),
+			},
+		};
+	}
+
+	private *closeMessage(): Generator<LifecycleEvent> {
+		if (!this.openMessageId) return;
+		yield {
+			type: "message.ended",
+			turnId: this.turnId,
+			messageId: this.openMessageId,
+			timestamp: Date.now(),
+		};
+		this.openMessageId = undefined;
+		this.openMessageParent = undefined;
+	}
+
+	/** Ensure an open message whose parent matches the incoming part. A part
+	 * whose `parentToolUseId` differs from the open message (main↔sub-agent, or
+	 * between sibling sub-agents) starts a new message so sub-agent output is
+	 * grouped under its own parented message rather than mixed into another. */
+	private *ensureMessage(parentToolUseId?: string): Generator<LifecycleEvent> {
+		if (this.openMessageId && this.openMessageParent !== parentToolUseId) {
+			yield* this.closeMessage();
+		}
+		if (!this.openMessageId) yield* this.openMessage("assistant", parentToolUseId);
+	}
+
+	/** Resolve (or assign) the wire address of a part. Yields a message.started
+	 * first when the part is new and no matching message is open. */
+	private *addressFor(
+		partId: string,
+		parentToolUseId?: string,
+	): Generator<LifecycleEvent, PartAddress> {
+		const existing = this.partAddressById.get(partId);
+		if (existing) return existing;
+		yield* this.ensureMessage(parentToolUseId);
+		const address: PartAddress = {
+			messageId: this.openMessageId as string,
+			outputIndex: this.currentOutputIndex,
+			partIndex: this.nextPartIndex++,
+		};
+		this.partAddressById.set(partId, address);
+		return address;
+	}
+
+	private *emitPart(part: Part): Generator<LifecycleEvent> {
+		const address = yield* this.addressFor(part.id, part.parentToolUseId);
+		// Snapshot: adapters mutate their part objects in place across
+		// open/update, so we must clone at emit time or buffered consumers would
+		// all observe the final state. Stamp ownership so the part is
+		// self-describing on the wire.
+		const snapshot = structuredClone(part);
+		snapshot.sessionId = this.sessionId;
+		snapshot.messageId = address.messageId;
+		yield {
+			type: "message.part",
+			turnId: this.turnId,
+			messageId: address.messageId,
+			outputIndex: address.outputIndex,
+			partIndex: address.partIndex,
+			part: snapshot,
+			...(snapshot.parentToolUseId && { parentToolUseId: snapshot.parentToolUseId }),
+			timestamp: Date.now(),
+		};
+	}
+
+	private delta(partId: string, delta: Delta): LifecycleEvent | null {
+		// Deltas only ever follow a part-open, so an unknown part id means a
+		// misbehaving adapter — drop rather than fabricate an address.
+		const address = this.partAddressById.get(partId);
+		if (!address) return null;
+		return {
+			type: "message.part.delta",
+			turnId: this.turnId,
+			messageId: address.messageId,
+			outputIndex: address.outputIndex,
+			partIndex: address.partIndex,
+			partId,
+			delta,
+			timestamp: Date.now(),
+		};
+	}
+}

package/src/core/runtime/event-sink.ts

@@ -0,0 +1,37 @@
+import type { LifecycleEvent } from "../../protocol/index.ts";
+
+/**
+ * The single output port of the engine. A consumer implements `emit` to forward
+ * normalized events wherever they need to go (WebSocket, SSE, stdout, a buffer).
+ * The engine never assumes a transport.
+ */
+export interface EventSink {
+	emit(event: LifecycleEvent): void | Promise<void>;
+}
+
+/** Build a sink from a plain callback. */
+export function callbackSink(fn: (event: LifecycleEvent) => void | Promise<void>): EventSink {
+	return { emit: fn };
+}
+
+/** A sink that accumulates events in memory — handy for tests and batch runs. */
+export class CollectingSink implements EventSink {
+	readonly events: LifecycleEvent[] = [];
+
+	emit(event: LifecycleEvent): void {
+		this.events.push(event);
+	}
+
+	byType<T extends LifecycleEvent["type"]>(type: T): Extract<LifecycleEvent, { type: T }>[] {
+		return this.events.filter((e): e is Extract<LifecycleEvent, { type: T }> => e.type === type);
+	}
+}
+
+/** Fan out to several sinks at once. */
+export function teeSink(...sinks: EventSink[]): EventSink {
+	return {
+		async emit(event) {
+			for (const sink of sinks) await sink.emit(event);
+		},
+	};
+}

package/src/core/utils/errors.ts

@@ -0,0 +1,41 @@
+/** Base class for all errors thrown by the engine. */
+export class AgentServerError extends Error {
+	constructor(
+		message: string,
+		readonly code: string,
+	) {
+		super(message);
+		this.name = "AgentServerError";
+	}
+}
+
+export class HarnessNotFoundError extends AgentServerError {
+	constructor(harness: string) {
+		super(`No agent registered for harness: ${harness}`, "HARNESS_NOT_FOUND");
+		this.name = "HarnessNotFoundError";
+	}
+}
+
+export class AgentExecutionError extends AgentServerError {
+	constructor(message: string, options?: { cause?: unknown }) {
+		super(message, "AGENT_EXECUTION_ERROR");
+		this.name = "AgentExecutionError";
+		if (options?.cause !== undefined) this.cause = options.cause;
+	}
+}
+
+export class CliNotFoundError extends AgentServerError {
+	constructor(name: string, hint?: string) {
+		super(`Required CLI not found on PATH: ${name}${hint ? ` — ${hint}` : ""}`, "CLI_NOT_FOUND");
+		this.name = "CliNotFoundError";
+	}
+}
+
+/** Managed CLI provisioning failed (download, integrity, or a bad override). */
+export class CliProvisionError extends AgentServerError {
+	constructor(message: string, options?: { cause?: unknown }) {
+		super(message, "CLI_PROVISION_FAILED");
+		this.name = "CliProvisionError";
+		if (options?.cause !== undefined) this.cause = options.cause;
+	}
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+// @zvada/agent-server — the root export is the wire contract (zod-only, safe
+// in any runtime). The seats live behind subpaths: ./core embeds the engine,
+// ./server serves the wire, ./client talks to one.
+export * from "./protocol/index.ts";