@zvada/agent-server 0.2.0

package/src/protocol/async-queue.ts

@@ -0,0 +1,68 @@
+/**
+ * Single-consumer async channel. Producers `push()` values and then `end()`
+ * (graceful) or `fail(error)` (consumers reject once buffered values drain);
+ * a single consumer iterates with `for await`. `push` after end/fail is a
+ * no-op; `return()` lets a consumer `break` out and end the stream. Shared by
+ * core (prompt feeding, per-turn event buffering) and client (turn streams).
+ */
+export class AsyncQueue<T> implements AsyncIterableIterator<T> {
+	private queue: T[] = [];
+	private waiting: Array<{
+		resolve: (r: IteratorResult<T>) => void;
+		reject: (e: unknown) => void;
+	}> = [];
+	private done = false;
+	private failure: unknown;
+
+	push(value: T): void {
+		if (this.done) return;
+		const w = this.waiting.shift();
+		if (w) w.resolve({ value, done: false });
+		else this.queue.push(value);
+	}
+
+	end(): void {
+		if (this.done) return;
+		this.done = true;
+		for (const w of this.waiting) w.resolve({ value: undefined as never, done: true });
+		this.waiting = [];
+	}
+
+	fail(error: unknown): void {
+		if (this.done) return;
+		this.done = true;
+		this.failure = error;
+		for (const w of this.waiting) w.reject(error);
+		this.waiting = [];
+	}
+
+	get size(): number {
+		return this.queue.length;
+	}
+
+	next(): Promise<IteratorResult<T>> {
+		// Check length, not the shifted value: a queued `undefined`/falsy item is
+		// a real value and must not be mistaken for an empty queue.
+		if (this.queue.length > 0) {
+			return Promise.resolve({ value: this.queue.shift() as T, done: false });
+		}
+		if (this.done) {
+			return this.failure !== undefined
+				? Promise.reject(this.failure)
+				: Promise.resolve({ value: undefined as never, done: true });
+		}
+		return new Promise((resolve, reject) => this.waiting.push({ resolve, reject }));
+	}
+
+	return(): Promise<IteratorResult<T>> {
+		// IteratorClose is terminal: a consumer that breaks has discarded every
+		// buffered value, even when return() is called directly.
+		this.queue = [];
+		this.end();
+		return Promise.resolve({ value: undefined as never, done: true });
+	}
+
+	[Symbol.asyncIterator](): AsyncIterableIterator<T> {
+		return this;
+	}
+}

package/src/protocol/config.ts

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import { AgentHarnessSchema } from "./harness.ts";
+import { AgentInputSchema } from "./part-input.ts";
+import { ThinkingLevelSchema } from "./thinking.ts";
+
+/**
+ * Permission posture for a turn. `bypassPermissions`/`yolo` auto-approve every
+ * tool (the right default inside a sandbox); `plan` is read-only planning;
+ * `dontAsk` never prompts — unapproved tools are denied, sandboxes stay at
+ * their normal (non-dangerous) level. Harnesses map this onto their own modes.
+ */
+export const PermissionModeSchema = z.enum([
+	"default",
+	"plan",
+	"acceptEdits",
+	"dontAsk",
+	"bypassPermissions",
+]);
+export type PermissionMode = z.infer<typeof PermissionModeSchema>;
+
+/** Minimal external MCP server descriptor (stdio or http/sse). */
+export const McpServerConfigSchema = z.discriminatedUnion("type", [
+	z.object({
+		type: z.literal("stdio"),
+		command: z.string(),
+		args: z.array(z.string()).optional(),
+		env: z.record(z.string(), z.string()).optional(),
+	}),
+	z.object({
+		type: z.literal("http"),
+		url: z.string(),
+		headers: z.record(z.string(), z.string()).optional(),
+	}),
+	z.object({
+		type: z.literal("sse"),
+		url: z.string(),
+		headers: z.record(z.string(), z.string()).optional(),
+	}),
+]);
+export type McpServerConfig = z.infer<typeof McpServerConfigSchema>;
+
+/** Everything needed to configure a turn against a harness. */
+export const RunConfigSchema = z.object({
+	harness: AgentHarnessSchema,
+	/** Free-form model id/alias; omit to use the harness default. */
+	model: z.string().optional(),
+	thinkingLevel: ThinkingLevelSchema.optional(),
+	/** Working directory the agent operates in. */
+	cwd: z.string(),
+	/**
+	 * Extra directories the agent may access beyond `cwd`. Mapped by the
+	 * claude-code and codex-sdk harnesses; codex-app-server and acp have no
+	 * native equivalent today and ignore it.
+	 */
+	additionalDirectories: z.array(z.string()).optional(),
+	systemPromptAppend: z.string().optional(),
+	maxTurns: z.number().int().positive().optional(),
+	permissionMode: PermissionModeSchema.optional(),
+	/**
+	 * Native session/thread id to resume (from a prior `session.created`). When
+	 * set, the harness continues that conversation instead of starting fresh.
+	 */
+	resumeSessionId: z.string().optional(),
+	/**
+	 * Resume from a specific historical message within the resumed session
+	 * (branch/retry flows). Claude-only today; other harnesses ignore it.
+	 */
+	resumeSessionAt: z.string().optional(),
+	mcpServers: z.record(z.string(), McpServerConfigSchema).optional(),
+	/** Extra env vars layered onto the agent subprocess. */
+	env: z.record(z.string(), z.string()).optional(),
+	/** Per-turn API key override (BYOK). Falls back to ambient/proxy auth. */
+	apiKey: z.string().optional(),
+	/**
+	 * Disable all built-in tools for this turn (text-only). Honored by harnesses
+	 * that support it (Claude); Codex achieves the same via a read-only sandbox.
+	 */
+	disableTools: z.boolean().optional(),
+	/**
+	 * Interleave `raw` passthrough events (the harness's unparsed events) with
+	 * the normalized stream. Migration/debug escape hatch — see `RawEvent`.
+	 */
+	includeRaw: z.boolean().optional(),
+});
+export type RunConfig = z.infer<typeof RunConfigSchema>;
+
+/**
+ * A single request to run one turn.
+ *  - `sessionId` is OUR stable logical id (the session-manager key). It is the
+ *    same across every turn of a conversation.
+ *  - the harness-native id (for resume) is discovered at runtime and surfaced
+ *    via the `session.created` lifecycle event.
+ */
+export const RunRequestSchema = z.object({
+	sessionId: z.string(),
+	turnId: z.string(),
+	input: AgentInputSchema,
+	config: RunConfigSchema,
+});
+export type RunRequest = z.infer<typeof RunRequestSchema>;

package/src/protocol/factories.ts

@@ -0,0 +1,125 @@
+import { generateUUIDv7 } from "./ids.ts";
+import type { ReasoningPart, TextPart, ToolPart } from "./parts.ts";
+import type { ToolKind, ToolLocation } from "./tool-state.ts";
+
+/** Context an adapter threads through while building parts for one message. */
+export interface StreamContext {
+	sessionId: string;
+	messageId: string;
+	parentToolUseId?: string;
+}
+
+/** Optional normalized metadata for a tool part (see ToolPart). */
+export interface ToolMeta {
+	kind?: ToolKind;
+	title?: string;
+	locations?: ToolLocation[];
+}
+
+export function createTextPart(ctx: StreamContext, text: string, streaming = true): TextPart {
+	return {
+		id: generateUUIDv7(),
+		sessionId: ctx.sessionId,
+		messageId: ctx.messageId,
+		...(ctx.parentToolUseId && { parentToolUseId: ctx.parentToolUseId }),
+		type: "text",
+		text,
+		state: streaming ? "streaming" : "done",
+	};
+}
+
+export function createReasoningPart(
+	ctx: StreamContext,
+	text: string,
+	streaming = true,
+): ReasoningPart {
+	return {
+		id: generateUUIDv7(),
+		sessionId: ctx.sessionId,
+		messageId: ctx.messageId,
+		...(ctx.parentToolUseId && { parentToolUseId: ctx.parentToolUseId }),
+		type: "reasoning",
+		text,
+		state: streaming ? "streaming" : "done",
+	};
+}
+
+function toolBase(ctx: StreamContext, toolCallId: string, toolName: string, meta?: ToolMeta) {
+	return {
+		id: generateUUIDv7(),
+		sessionId: ctx.sessionId,
+		messageId: ctx.messageId,
+		...(ctx.parentToolUseId && { parentToolUseId: ctx.parentToolUseId }),
+		type: "tool" as const,
+		toolCallId,
+		toolName,
+		...(meta?.kind && { kind: meta.kind }),
+		...(meta?.title && { title: meta.title }),
+		...(meta?.locations?.length && { locations: meta.locations }),
+	};
+}
+
+export function createToolPart(
+	ctx: StreamContext,
+	toolCallId: string,
+	toolName: string,
+	input: Record<string, unknown>,
+	meta?: ToolMeta,
+): ToolPart {
+	return {
+		...toolBase(ctx, toolCallId, toolName, meta),
+		state: { status: "in_progress", input, time: { start: Date.now() } },
+	};
+}
+
+/** A tool call whose input is still streaming in (partial JSON not yet parseable). */
+export function createPendingToolPart(
+	ctx: StreamContext,
+	toolCallId: string,
+	toolName: string,
+	meta?: ToolMeta,
+): ToolPart {
+	return {
+		...toolBase(ctx, toolCallId, toolName, meta),
+		state: { status: "pending", partialInput: "" },
+	};
+}
+
+/** Mutates a pending tool part into `in_progress` once its input has fully parsed. */
+export function startToolPart(part: ToolPart, input: Record<string, unknown>): void {
+	if (part.state.status === "pending") {
+		part.state = { status: "in_progress", input, time: { start: Date.now() } };
+	}
+}
+
+/** Appends a streamed JSON fragment to a still-pending tool part. */
+export function appendToolInput(part: ToolPart, partialJson: string): void {
+	if (part.state.status === "pending") {
+		part.state.partialInput += partialJson;
+	}
+}
+
+/** Attach/refresh normalized metadata on an existing tool part. */
+export function setToolMeta(part: ToolPart, meta: ToolMeta): void {
+	if (meta.kind) part.kind = meta.kind;
+	if (meta.title) part.title = meta.title;
+	if (meta.locations?.length) part.locations = meta.locations;
+}
+
+/** Mutates a tool part into its terminal `completed`/`failed` state. */
+export function completeToolPart(
+	part: ToolPart,
+	result: { output: string; isError?: boolean; title?: string },
+): void {
+	const start = part.state.status === "in_progress" ? part.state.time.start : Date.now();
+	const input = "input" in part.state ? part.state.input : {};
+	part.state = result.isError
+		? { status: "failed", input, error: result.output, time: { start, end: Date.now() } }
+		: {
+				status: "completed",
+				input,
+				output: result.output,
+				title: result.title ?? part.toolName,
+				time: { start, end: Date.now() },
+			};
+}

package/src/protocol/harness.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+
+/**
+ * The agent harnesses this engine can drive:
+ *  - `claude-code`        — Claude Code via @anthropic-ai/claude-agent-sdk (CLI under the hood)
+ *  - `codex-sdk`          — OpenAI Codex via @openai/codex-sdk (wraps the `codex` CLI in exec mode)
+ *  - `codex-app-server`   — OpenAI Codex via `codex app-server` (long-lived JSON-RPC subprocess)
+ *  - `acp`                — any Agent Client Protocol v1 agent subprocess (`gemini --acp`,
+ *                           `claude-code-acp`, `codex-acp`, ACP registry agents); the launch
+ *                           command is operator-configured, never taken from the wire
+ */
+export const AGENT_HARNESSES = ["claude-code", "codex-sdk", "codex-app-server", "acp"] as const;
+export type AgentHarness = (typeof AGENT_HARNESSES)[number];
+export const AgentHarnessSchema = z.enum(AGENT_HARNESSES);
+
+export function isAgentHarness(value: string): value is AgentHarness {
+	return (AGENT_HARNESSES as readonly string[]).includes(value);
+}
+
+/**
+ * How a harness handles changing the model mid-conversation:
+ *  - `in-session`      — swap live without losing context (Claude `setModel`)
+ *  - `restart-session` — must start a fresh underlying session (Codex)
+ *  - `unsupported`     — model is fixed for the life of the session
+ */
+export const ModelSwitchModeSchema = z.enum(["in-session", "restart-session", "unsupported"]);
+export type ModelSwitchMode = z.infer<typeof ModelSwitchModeSchema>;
+
+/**
+ * Declarative feature matrix per harness. Callers consult this to decide what
+ * is safe to ask for (e.g. whether to expect resume, or whether a model change
+ * forces a restart). Returned in the engine's session snapshot.
+ */
+export const AgentCapabilitiesSchema = z.object({
+	/** Can feed multiple turns into one long-lived underlying session. */
+	multiTurn: z.boolean(),
+	/** Can resume a prior session from its native id. */
+	sessionResume: z.boolean(),
+	/** How a model change is handled. */
+	modelSwitch: ModelSwitchModeSchema,
+	/** Honors a thinking/reasoning-effort level. */
+	thinkingLevels: z.boolean(),
+	/** Accepts image input parts. */
+	images: z.boolean(),
+	/** Accepts external MCP servers. */
+	mcpServers: z.boolean(),
+	/** Can raise interactive `permission.requested` round-trips mid-turn. */
+	permissionRequests: z.boolean(),
+});
+export type AgentCapabilities = z.infer<typeof AgentCapabilitiesSchema>;

package/src/protocol/ids.ts

@@ -0,0 +1,53 @@
+/**
+ * UUIDv7 — time-ordered identifiers. The leading 48 bits are a millisecond
+ * timestamp, so ids sort chronologically (handy for ordering parts/messages
+ * without a separate createdAt column). Uses Web Crypto, available on both
+ * Bun and Node >= 20 via `globalThis.crypto`.
+ */
+export function generateUUIDv7(): string {
+	const timestamp = Date.now();
+
+	const rand = new Uint8Array(10);
+	crypto.getRandomValues(rand);
+
+	const bytes = new Uint8Array(16);
+
+	// 48-bit big-endian timestamp.
+	bytes[0] = (timestamp / 2 ** 40) & 0xff;
+	bytes[1] = (timestamp / 2 ** 32) & 0xff;
+	bytes[2] = (timestamp / 2 ** 24) & 0xff;
+	bytes[3] = (timestamp / 2 ** 16) & 0xff;
+	bytes[4] = (timestamp / 2 ** 8) & 0xff;
+	bytes[5] = timestamp & 0xff;
+
+	// version (7) + 4 bits random
+	bytes[6] = 0x70 | (rand[0]! & 0x0f);
+	bytes[7] = rand[1]!;
+	// variant (10xx) + 6 bits random
+	bytes[8] = 0x80 | (rand[2]! & 0x3f);
+	bytes[9] = rand[3]!;
+	bytes[10] = rand[4]!;
+	bytes[11] = rand[5]!;
+	bytes[12] = rand[6]!;
+	bytes[13] = rand[7]!;
+	bytes[14] = rand[8]!;
+	bytes[15] = rand[9]!;
+
+	const hex: string[] = [];
+	for (let i = 0; i < 16; i++) hex.push(bytes[i]!.toString(16).padStart(2, "0"));
+	return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex
+		.slice(6, 8)
+		.join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10, 16).join("")}`;
+}
+
+/** Extract the embedded millisecond timestamp from a UUIDv7. */
+export function timestampFromUUIDv7(id: string): number {
+	const hex = id.replace(/-/g, "").slice(0, 12);
+	return Number.parseInt(hex, 16);
+}
+
+/** Short, non-sortable id for ad-hoc correlation (e.g. JSON-RPC request ids). */
+export function generateId(prefix?: string): string {
+	const id = crypto.randomUUID().replace(/-/g, "").slice(0, 16);
+	return prefix ? `${prefix}_${id}` : id;
+}

package/src/protocol/index.ts

@@ -0,0 +1,16 @@
+// @zvada/agent-server/protocol — the wire contract.
+// Normalized data shapes shared by the engine and every consumer.
+
+export * from "./ids.ts";
+export * from "./async-queue.ts";
+export * from "./tokens.ts";
+export * from "./tool-state.ts";
+export * from "./parts.ts";
+export * from "./part-input.ts";
+export * from "./factories.ts";
+export * from "./harness.ts";
+export * from "./thinking.ts";
+export * from "./models.ts";
+export * from "./config.ts";
+export * from "./lifecycle.ts";
+export * from "./wire.ts";