@zvada/agent-server 0.2.2 → 0.3.1

package/src/protocol/selectors.ts

@@ -0,0 +1,162 @@
+// Read-only projections of a folded `ConversationState`.
+//
+// `reduceConversation` says what the stream MEANS; these say what a UI or an
+// API layer then ASKS of it. Every one of them was written independently — and
+// differently — in each product before it landed here: the turn grouping (with
+// the guard that keeps a finished turn out of streaming UI), the subagent
+// nesting map, the "what is the agent doing right now" indicator, and the
+// tool-result text every renderer falls back to.
+//
+// Pure, allocation-light, and derived — never cached in state, never a source
+// of truth. Call them per render.
+
+import type { ConversationMessage, ConversationState, TimelineEntry } from "./reduce.ts";
+import type { ToolState } from "./tool-state.ts";
+
+/**
+ * One rendered turn card: a run of consecutive timeline entries that belong to
+ * the same turn and the same speaker.
+ */
+export interface ConversationTurnGroup {
+	turnId: string;
+	role: "user" | "assistant";
+	/** Messages (and compactions) in stream order. */
+	entries: TimelineEntry[];
+	/** True for the final group only — see `groupIntoTurns`. */
+	isLatest: boolean;
+}
+
+/**
+ * Group the timeline into turn cards: consecutive entries break into a new
+ * group when the speaker changes or the turn changes. (A group carries one
+ * `turnId`, so two back-to-back user echoes from different turns stay
+ * separate even though the role is unchanged.) Compactions are engine-side
+ * content and group as `assistant` within their turn — a divider that renders
+ * inside the run it interrupted, which is where it happened.
+ *
+ * `isLatest` is TRUE FOR THE FINAL GROUP ONLY, and only while nothing follows
+ * it. That guard is the whole point: a consumer renders the latest group in
+ * streaming mode (expanded, live cursor), and the moment the next turn's user
+ * echo lands, the previous group MUST lose the flag. Without it, the gap
+ * between "user submits" and "first assistant part arrives" re-opens the
+ * finished turn in streaming mode — the completed answer visibly reverts to
+ * "working". Combine with your own busy flag (`isLatest && role ===
+ * "assistant" && isWorking`), never with position alone.
+ */
+export function groupIntoTurns(state: ConversationState): ConversationTurnGroup[] {
+	const groups: ConversationTurnGroup[] = [];
+	let current: ConversationTurnGroup | undefined;
+	for (const entry of state.timeline) {
+		const role = entry.kind === "message" ? entry.role : "assistant";
+		if (!current || current.turnId !== entry.turnId || current.role !== role) {
+			current = { turnId: entry.turnId, role, entries: [], isLatest: false };
+			groups.push(current);
+		}
+		current.entries.push(entry);
+	}
+	const last = groups[groups.length - 1];
+	if (last) last.isLatest = true;
+	return groups;
+}
+
+/**
+ * Subagent output, keyed by the `toolCallId` of the tool that spawned it.
+ *
+ * A message with `parentToolCallId` is NOT top-level model output — rendering
+ * it in the main flow double-prints the subagent's work next to the tool card
+ * that owns it. Consumers nest `subagentGroups(state).get(part.toolCallId)`
+ * under the tool part and filter parented messages out of the main timeline
+ * (`groupIntoTurns` keeps them, because "which turn did this belong to" is
+ * still true — the filtering is a rendering choice).
+ */
+export function subagentGroups(state: ConversationState): Map<string, ConversationMessage[]> {
+	const groups = new Map<string, ConversationMessage[]>();
+	for (const entry of state.timeline) {
+		if (entry.kind !== "message" || entry.parentToolCallId === undefined) continue;
+		const group = groups.get(entry.parentToolCallId);
+		if (group) group.push(entry);
+		else groups.set(entry.parentToolCallId, [entry]);
+	}
+	return groups;
+}
+
+/** What the agent is doing right now, for a live activity indicator. */
+export type AgentActivity = "thinking" | "generating" | "tool_running" | "tool_failed" | "idle";
+
+/**
+ * Derive the live activity from the LAST part of the LAST top-level assistant
+ * message of the LAST ACTIVE turn: reasoning → `thinking`, text →
+ * `generating`, a pending/in-progress tool → `tool_running`, a failed tool →
+ * `tool_failed`.
+ *
+ * Everything else is `idle` — no active turn, no assistant output yet, an
+ * unknown part type, or a part that says nothing about what happens next (a
+ * completed tool: the model is about to speak, but the stream has not said so
+ * yet). `idle` DURING an active turn means "between observable activities",
+ * not "finished": a consumer with its own busy flag renders its default
+ * working state there rather than nothing.
+ *
+ * Subagent messages (`parentToolCallId`) are skipped: the main thread's
+ * activity is the spawning tool call, which stays `tool_running` for as long
+ * as the subagent works — otherwise the indicator would flicker on the
+ * subagent's internal steps.
+ */
+export function agentActivity(state: ConversationState): AgentActivity {
+	let activeTurnId: string | undefined;
+	for (let i = state.turns.length - 1; i >= 0; i--) {
+		const turn = state.turns[i];
+		if (turn?.status === "active") {
+			activeTurnId = turn.turnId;
+			break;
+		}
+	}
+	if (activeTurnId === undefined) return "idle";
+
+	for (let i = state.timeline.length - 1; i >= 0; i--) {
+		const entry = state.timeline[i];
+		if (entry?.kind !== "message") continue;
+		if (entry.turnId !== activeTurnId) continue;
+		if (entry.role !== "assistant" || entry.parentToolCallId !== undefined) continue;
+		// ONLY the latest such message speaks for "now". Falling through to an
+		// older one would resurrect its last state — a finished message's text
+		// part reading as `generating` minutes after it closed.
+		const part = entry.parts[entry.parts.length - 1];
+		// A just-opened message with no parts yet: between activities.
+		if (!part) return "idle";
+		// Unknown part types carry a `raw` bag and nothing we can interpret.
+		if ("raw" in part) return "idle";
+		if (part.type === "tool") {
+			// Tools may settle AFTER their message ends (the contract's late
+			// re-statement), so tool activity outranks the message bracket.
+			const status = part.state.status;
+			if (status === "failed") return "tool_failed";
+			if (status === "pending" || status === "in_progress") return "tool_running";
+			return "idle";
+		}
+		// Text/reasoning only speak while their message is still open — an
+		// ended message's last words are history, not activity.
+		if (entry.endedAt !== undefined) return "idle";
+		if (part.type === "reasoning") return "thinking";
+		if (part.type === "text") return "generating";
+		return "idle";
+	}
+	return "idle";
+}
+
+/**
+ * The tool result as display text: a completed call's `output`, a failed
+ * call's `error`, and "" for everything that has not produced one yet
+ * (`pending`, `in_progress`) or never will (`cancelled`).
+ *
+ * The empty string is deliberate and load-bearing: a renderer that shows this
+ * unconditionally shows nothing for a call in flight, instead of the
+ * placeholder prose ("Running…", "Cancelled") each consumer invented
+ * differently. Structured output (`state.content`: diffs, images, terminals)
+ * is a richer view a renderer opts into — `output` stays the universal
+ * fallback, per the three-audience doctrine.
+ */
+export function toolResultText(state: ToolState): string {
+	if (state.status === "completed") return state.output;
+	if (state.status === "failed") return state.error;
+	return "";
+}

package/src/protocol/seq-cursor.ts

@@ -0,0 +1,87 @@
+/**
+ * What one envelope's `seq` means for a session's cursor.
+ *
+ *  - `deliver`   — the expected next envelope; the cursor advanced to it.
+ *  - `duplicate` — already delivered (a replay overlap, a resync); drop it.
+ *                  The cursor does NOT move.
+ *  - `gap`       — envelopes were missed; hold this one and heal (replay).
+ *                  The cursor does NOT move, so the healed events still land
+ *                  in order.
+ *  - `reset`     — `seq` restarted at 1 while the cursor was past it: the
+ *                  session log began again (a new server process behind a
+ *                  reconnecting transport). The cursor resets and DELIVERS
+ *                  this envelope — treating it as a duplicate silently drops
+ *                  the entire post-restart stream, which is exactly the bug
+ *                  this verdict exists to prevent. The caller must drop the
+ *                  state it was holding for the dead log (held-back envelopes,
+ *                  partial reconstruction); the fresh log is authoritative.
+ *
+ * The reset rule is a HEURISTIC with two documented blind spots — at the seq
+ * layer, a restart is indistinguishable from a redelivery in exactly these:
+ * a restart seen while the cursor sits at 1 (the fresh seq 1 reads as a
+ * duplicate), and a restart first contacted mid-stream (fresh seq k ≤ last
+ * reads as a duplicate). Callers with a second signal close them: the wire
+ * client does not guess at all — `initialize` returns a per-process
+ * `instanceId` and a reconnect re-handshake adopts the fresh logs outright;
+ * a consumer without a handshake (a browser folding forwarded envelopes)
+ * treats any backwards seq beyond the immediately-last frame as a
+ * replacement.
+ */
+export type SeqVerdict = "deliver" | "duplicate" | "gap" | "reset";
+
+/**
+ * Per-session `seq` bookkeeping — the whole of "did I already see this, did I
+ * miss something, did the server restart", with no transport, no schemas and
+ * no dependencies.
+ *
+ * This is the wire client's own discipline, hoisted so the consumers that
+ * cannot use the client (a backend folding envelopes forwarded over its own
+ * WebSocket, a Durable Object replaying a log) get the same answers instead of
+ * a fourth hand-rolled variant. `AgentServerClient` is implemented on it.
+ */
+export interface SeqCursor {
+	/** Classify `seq` for `sessionId`, advancing the cursor when it delivers. */
+	advance(sessionId: string, seq: number): SeqVerdict;
+	/** Forget the session entirely — the next `seq` starts a fresh stream. */
+	reset(sessionId: string): void;
+	/**
+	 * Force the watermark (an evicted prefix accepted as lost, a snapshot
+	 * restored from durable state). The next contiguous envelope is `seq + 1`.
+	 */
+	seek(sessionId: string, seq: number): void;
+	/** Highest delivered `seq` for the session; 0 when none is known. */
+	last(sessionId: string): number;
+	/** The sessions with a cursor — what to resync after a reconnect. */
+	sessions(): string[];
+}
+
+export function createSeqCursor(): SeqCursor {
+	const lastSeq = new Map<string, number>();
+	return {
+		advance(sessionId, seq) {
+			const last = lastSeq.get(sessionId) ?? 0;
+			if (seq === 1 && last > 1) {
+				lastSeq.set(sessionId, seq);
+				return "reset";
+			}
+			if (seq <= last) return "duplicate";
+			if (seq === last + 1) {
+				lastSeq.set(sessionId, seq);
+				return "deliver";
+			}
+			return "gap";
+		},
+		reset(sessionId) {
+			lastSeq.delete(sessionId);
+		},
+		seek(sessionId, seq) {
+			lastSeq.set(sessionId, seq);
+		},
+		last(sessionId) {
+			return lastSeq.get(sessionId) ?? 0;
+		},
+		sessions() {
+			return [...lastSeq.keys()];
+		},
+	};
+}

package/src/protocol/stop-reasons.ts

@@ -0,0 +1,45 @@
+import type { StopReason } from "./lifecycle.ts";
+
+/**
+ * The stop reasons that mean "the turn finished the way it was supposed to".
+ * A subset of `STOP_REASONS` — everything except `error`.
+ *
+ * `cancelled` is CLEAN: the user asked for the turn to stop and it stopped.
+ * Products that treat it as a failure paint an error banner over the user's
+ * own action (all three copies of this set in the wild got this right, and
+ * two of them then drifted on `refusal` and `max_turn_requests`).
+ *
+ * Zod-free and dependency-free on purpose: this is a membership test, and a
+ * consumer branching on a stop reason should not have to load the schemas.
+ */
+export const CLEAN_STOP_REASONS = [
+	"end_turn",
+	"max_tokens",
+	"max_turn_requests",
+	"refusal",
+	"cancelled",
+] as const;
+
+/**
+ * True when the turn stopped for a reason this build knows to be clean.
+ *
+ * `StopReason` is an OPEN vocabulary (Law 3): a newer engine's value, or an
+ * adapter's `_`-prefixed extension, reaches an older consumer unchanged. Such
+ * a value is classified as NOT clean — the conservative direction. Showing a
+ * failure affordance for an outcome we cannot interpret is recoverable (the
+ * user retries); silently rendering an unknown outcome as success is not (the
+ * turn looks complete, the work is gone, nothing points at the cause).
+ */
+export function isCleanStop(reason: StopReason | undefined): boolean {
+	return (CLEAN_STOP_REASONS as readonly string[]).includes(reason as string);
+}
+
+/**
+ * The complement of `isCleanStop`: `error`, plus every stop reason this build
+ * does not know (see the conservative-classification note above). `undefined`
+ * — a turn with no stop reason at all — is a failure too: a turn that ended
+ * without saying why did not end well.
+ */
+export function isFailureStopReason(reason: StopReason | undefined): boolean {
+	return !isCleanStop(reason);
+}

package/src/protocol/time.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+
+/**
+ * Law 5 — every instant on this wire is epoch MILLISECONDS, as an integer.
+ * One schema, used by every `timestamp` and every nested `time.start`/
+ * `time.end`, so the boundary validation is real rather than prose: a bare
+ * `z.number()` accepts `-5`, `1.5` and `-0`, all of which round-trip silently
+ * and then sort, subtract and render wrong (a seconds-based stamp lands in
+ * 1970; `-0` breaks `Object.is` keyed caches).
+ */
+export const EpochMsSchema = z
+	.number()
+	.int()
+	.nonnegative()
+	// -0 passes `>= 0`; it is not a legal instant, and it survives JSON as `0`
+	// only by accident of the serializer.
+	.refine((value) => !Object.is(value, -0), { message: "epoch-ms must not be -0" });
+export type EpochMs = z.infer<typeof EpochMsSchema>;
+
+/** A start/end span in epoch ms (tool executions, thinking blocks). */
+export const TimeSpanSchema = z.object({ start: EpochMsSchema, end: EpochMsSchema });
+/** A span whose end is unknown while the thing is still running. */
+export const OpenTimeSpanSchema = z.object({ start: EpochMsSchema, end: EpochMsSchema.optional() });

package/src/protocol/tokens.ts

@@ -4,6 +4,14 @@ import { z } from "zod";
  * Normalized token accounting. Every harness reports usage differently
  * (Claude: input/output/cache_creation/cache_read; Codex: input/output/
  * reasoning/cached). Adapters fold those into this single shape.
+ *
+ * INVARIANTS (normative — so consumers never subtract):
+ *  - `input` is NON-CACHED input tokens ONLY; billed input =
+ *    `input + cache.read + cache.write` (the three are disjoint).
+ *  - `reasoning` is a subset of `output` (output already includes it).
+ *  - `writeEphemeral5m`/`writeEphemeral1h` are subsets of `cache.write`.
+ * Providers that fold cache hits into a total prompt count are unfolded once,
+ * at the adapter — never downstream.
  */
 export const TokenUsageSchema = z.object({
 	input: z.number().default(0),
@@ -13,6 +21,10 @@ export const TokenUsageSchema = z.object({
 		.object({
 			read: z.number().default(0),
 			write: z.number().default(0),
+			/** Anthropic 5m-TTL cache-creation bucket, when reported. */
+			writeEphemeral5m: z.number().optional(),
+			/** Anthropic 1h-TTL cache-creation bucket, when reported. */
+			writeEphemeral1h: z.number().optional(),
 		})
 		.optional(),
 });
@@ -26,6 +38,11 @@ export const DEFAULT_TOKEN_USAGE: TokenUsage = {
 	cache: { read: 0, write: 0 },
 };
 
+function addOptional(a: number | undefined, b: number | undefined): number | undefined {
+	if (a === undefined && b === undefined) return undefined;
+	return (a ?? 0) + (b ?? 0);
+}
+
 export function addTokenUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
 	return {
 		input: a.input + b.input,
@@ -34,6 +51,12 @@ export function addTokenUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
 		cache: {
 			read: (a.cache?.read ?? 0) + (b.cache?.read ?? 0),
 			write: (a.cache?.write ?? 0) + (b.cache?.write ?? 0),
+			...(addOptional(a.cache?.writeEphemeral5m, b.cache?.writeEphemeral5m) !== undefined
+				? { writeEphemeral5m: addOptional(a.cache?.writeEphemeral5m, b.cache?.writeEphemeral5m) }
+				: {}),
+			...(addOptional(a.cache?.writeEphemeral1h, b.cache?.writeEphemeral1h) !== undefined
+				? { writeEphemeral1h: addOptional(a.cache?.writeEphemeral1h, b.cache?.writeEphemeral1h) }
+				: {}),
 		},
 	};
 }

package/src/protocol/tool-state.ts

@@ -1,19 +1,39 @@
 import { z } from "zod";
+import { MetaSchema } from "./meta.ts";
+import { EpochMsSchema, TimeSpanSchema } from "./time.ts";
+import { openVocabulary } from "./vocabulary.ts";
 
 /**
  * Runtime tool lifecycle: a tool call moves pending -> in_progress ->
- * completed|failed (ACP-aligned status names). `pending` carries the partial
- * (streaming) JSON input before it parses; the other states carry the
- * fully-parsed input object.
+ * completed | failed | cancelled (ACP ToolCallStatus verbatim, incl. v2's
+ * `cancelled`). `pending` carries the partial (streaming) JSON input before it
+ * parses; the other states carry the fully-parsed input object. `cancelled` is
+ * the terminal for tools in flight when a turn is cancelled — the reducer
+ * applies it implicitly at `turn.ended{stopReason:"cancelled"}`; producers MAY
+ * also emit the terminal snapshot explicitly.
+ *
+ * The status set is a STRUCTURAL discriminator (each status has its own
+ * payload), so the union below is closed; new statuses are protocol additions,
+ * not extensions.
  */
-export const RUNTIME_TOOL_STATUSES = ["pending", "in_progress", "completed", "failed"] as const;
+export const RUNTIME_TOOL_STATUSES = [
+	"pending",
+	"in_progress",
+	"completed",
+	"failed",
+	"cancelled",
+] as const;
 export type RuntimeToolStatus = (typeof RUNTIME_TOOL_STATUSES)[number];
-export const RuntimeToolStatusSchema = z.enum(RUNTIME_TOOL_STATUSES);
 
 /**
- * What a tool call does, normalized across harnesses (ACP's ToolKind
- * taxonomy). Lets a consumer pick an icon / verb without knowing
- * provider-native tool names.
+ * What a tool call does, normalized across harnesses — ACP's ToolKind taxonomy
+ * verbatim, plus `task` (subagent spawn; ACP has no subagent concept). Lets a
+ * consumer pick an icon / verb without knowing provider-native tool names.
+ *
+ * OPEN vocabulary (Law 3): unknown non-`_` values are reserved for this
+ * protocol and MUST be preserved; `_`-prefixed values are adapter/product
+ * extensions. Display groupings (e.g. edit|delete|move -> a "write" card) are
+ * consumer maps, not wire vocabulary.
  */
 export const TOOL_KINDS = [
 	"read",
@@ -25,31 +45,56 @@ export const TOOL_KINDS = [
 	"think",
 	"fetch",
 	"switch_mode",
+	"task",
 	"other",
 ] as const;
-export type ToolKind = (typeof TOOL_KINDS)[number];
-export const ToolKindSchema = z.enum(TOOL_KINDS);
+export type ToolKind = (typeof TOOL_KINDS)[number] | (string & {});
+export const ToolKindSchema = openVocabulary<ToolKind>();
 
-/** A file location a tool call touches — lets UIs "follow along". */
+/** A file location a tool call touches — lets UIs "follow along". (ACP shape.) */
 export const ToolLocationSchema = z.object({
 	path: z.string(),
 	line: z.number().optional(),
 });
 export type ToolLocation = z.infer<typeof ToolLocationSchema>;
 
-export const ToolAttachmentSchema = z.object({
-	type: z.string(),
-	command: z.string().optional(),
-	output: z.string().optional(),
-	exitCode: z.number().optional(),
-	path: z.string().optional(),
-	diff: z.string().optional(),
-});
-export type ToolAttachment = z.infer<typeof ToolAttachmentSchema>;
+/**
+ * Structured, display-grade tool output. Three-audience doctrine:
+ * `ToolStateCompleted.output` (string) is the MODEL-facing factual record and
+ * universal rendering fallback; `content` is the display-grade structured
+ * view; `metadata` is the machine channel (exitCode, ...).
+ */
+export const ToolResultContentSchema = z.discriminatedUnion("type", [
+	z.object({ type: z.literal("text"), text: z.string(), _meta: MetaSchema }),
+	z.object({
+		type: z.literal("image"),
+		/** Base64-encoded bytes. */
+		data: z.string(),
+		mimeType: z.string(),
+		_meta: MetaSchema,
+	}),
+	z.object({
+		type: z.literal("diff"),
+		path: z.string(),
+		/** Absent for file creation. */
+		oldText: z.string().optional(),
+		newText: z.string(),
+		_meta: MetaSchema,
+	}),
+	z.object({
+		type: z.literal("terminal"),
+		/** Display anchor only — a separate ID domain from toolCallId. */
+		terminalId: z.string(),
+		_meta: MetaSchema,
+	}),
+]);
+export type ToolResultContent = z.infer<typeof ToolResultContentSchema>;
 
 export const ToolStatePendingSchema = z.object({
 	status: z.literal("pending"),
+	/** Raw streamed JSON input — possibly invalid; parse best-effort for early render. */
 	partialInput: z.string(),
+	_meta: MetaSchema,
 });
 export type ToolStatePending = z.infer<typeof ToolStatePendingSchema>;
 
@@ -57,18 +102,23 @@ export const ToolStateInProgressSchema = z.object({
 	status: z.literal("in_progress"),
 	input: z.record(z.string(), z.unknown()),
 	title: z.string().optional(),
-	time: z.object({ start: z.number() }),
+	time: z.object({ start: EpochMsSchema }),
+	_meta: MetaSchema,
 });
 export type ToolStateInProgress = z.infer<typeof ToolStateInProgressSchema>;
 
 export const ToolStateCompletedSchema = z.object({
 	status: z.literal("completed"),
 	input: z.record(z.string(), z.unknown()),
+	/** Model-facing factual record; always present as the rendering fallback. */
 	output: z.string(),
-	title: z.string(),
+	/** Display-grade structured output, when expressible (diffs, images, terminals). */
+	content: z.array(ToolResultContentSchema).optional(),
+	/** Machine channel: harness-native extras (e.g. `exitCode`). */
 	metadata: z.record(z.string(), z.unknown()).optional(),
-	time: z.object({ start: z.number(), end: z.number() }),
-	attachments: z.array(ToolAttachmentSchema).optional(),
+	title: z.string().optional(),
+	time: TimeSpanSchema,
+	_meta: MetaSchema,
 });
 export type ToolStateCompleted = z.infer<typeof ToolStateCompletedSchema>;
 
@@ -76,14 +126,24 @@ export const ToolStateFailedSchema = z.object({
 	status: z.literal("failed"),
 	input: z.record(z.string(), z.unknown()),
 	error: z.string(),
-	time: z.object({ start: z.number(), end: z.number() }),
+	time: TimeSpanSchema,
+	_meta: MetaSchema,
 });
 export type ToolStateFailed = z.infer<typeof ToolStateFailedSchema>;
 
+export const ToolStateCancelledSchema = z.object({
+	status: z.literal("cancelled"),
+	input: z.record(z.string(), z.unknown()),
+	time: TimeSpanSchema,
+	_meta: MetaSchema,
+});
+export type ToolStateCancelled = z.infer<typeof ToolStateCancelledSchema>;
+
 export const ToolStateSchema = z.discriminatedUnion("status", [
 	ToolStatePendingSchema,
 	ToolStateInProgressSchema,
 	ToolStateCompletedSchema,
 	ToolStateFailedSchema,
+	ToolStateCancelledSchema,
 ]);
 export type ToolState = z.infer<typeof ToolStateSchema>;