@zvada/agent-server 0.2.1 → 0.3.0

package/src/{core/agents/error-classifier.ts → protocol/errors.ts}

@@ -1,20 +1,42 @@
+import { z } from "zod";
+import { openVocabulary } from "./vocabulary.ts";
+
 /**
- * Maps a raw harness error into a stable category, so callers can react
- * (retry on `network`/`rate_limit`, surface `auth` prominently, treat `abort`
- * as success). Distilled from deus-machine's lifecycle classifier.
+ * The one error vocabulary (Law: one shape per concept). Used by
+ * `turn.ended.error`, the standalone `error` event, and `RunSummary.error`.
+ *
+ * OPEN (Law 3): products may extend with their own categories (deus adds
+ * "db_write"); unknown non-`_` values are reserved for this protocol.
+ * `usage_limit` (plan/quota exhausted) and `rate_limit` (429/backoff) are
+ * deliberately distinct — they need different user guidance; collapsing them
+ * is a display choice, never a wire merge.
  */
 export const ERROR_CATEGORIES = [
 	"auth",
 	"rate_limit",
+	"usage_limit",
 	"context_limit",
 	"network",
 	"abort",
+	"invalid_request",
 	"process_exit",
-	"usage_limit",
-	"unknown",
+	"internal",
 ] as const;
-export type ErrorCategory = (typeof ERROR_CATEGORIES)[number];
+export type ErrorCategory = (typeof ERROR_CATEGORIES)[number] | (string & {});
+export const ErrorCategorySchema = openVocabulary<ErrorCategory>();
+
+export const ErrorInfoSchema = z.object({
+	category: ErrorCategorySchema,
+	message: z.string(),
+});
+export type ErrorInfo = z.infer<typeof ErrorInfoSchema>;
 
+/**
+ * Maps a raw harness error into a stable category, so callers can react
+ * (retry on `network`/`rate_limit`, surface `auth` prominently, treat `abort`
+ * as success). Rule order matters. Distilled from deus-machine's lifecycle
+ * classifier; lives in /protocol because categories are vocabulary.
+ */
 const RULES: ReadonlyArray<[ErrorCategory, readonly string[]]> = [
 	["abort", ["aborted", "aborterror", "cancelled", "canceled", "interrupted", "sigint"]],
 	[
@@ -46,6 +68,10 @@ const RULES: ReadonlyArray<[ErrorCategory, readonly string[]]> = [
 			"socket hang up",
 		],
 	],
+	[
+		"invalid_request",
+		["invalid request", "invalid_request_error", "status 400", "http 400", "bad request"],
+	],
 	["process_exit", ["exited with code", "process exited", "spawn", "enoent", "killed"]],
 ];
 
@@ -54,7 +80,7 @@ export function classifyError(error: unknown): ErrorCategory {
 	for (const [category, needles] of RULES) {
 		if (needles.some((n) => message.includes(n))) return category;
 	}
-	return "unknown";
+	return "internal";
 }
 
 /** Whether a turn can plausibly be retried after this error. */

package/src/protocol/factories.ts

@@ -1,12 +1,13 @@
 import { generateUUIDv7 } from "./ids.ts";
-import type { ReasoningPart, TextPart, ToolPart } from "./parts.ts";
-import type { ToolKind, ToolLocation } from "./tool-state.ts";
+import type { AgentInput } from "./part-input.ts";
+import type { Part, ReasoningPart, SubagentMetadata, TextPart, ToolPart } from "./parts.ts";
+import type { ToolKind, ToolLocation, ToolResultContent } from "./tool-state.ts";
 
 /** Context an adapter threads through while building parts for one message. */
 export interface StreamContext {
 	sessionId: string;
 	messageId: string;
-	parentToolUseId?: string;
+	parentToolCallId?: string;
 }
 
 /** Optional normalized metadata for a tool part (see ToolPart). */
@@ -14,6 +15,8 @@ export interface ToolMeta {
 	kind?: ToolKind;
 	title?: string;
 	locations?: ToolLocation[];
+	/** Present when this tool spawns a subagent (implies kind "task"). */
+	subagent?: SubagentMetadata;
 }
 
 export function createTextPart(ctx: StreamContext, text: string, streaming = true): TextPart {
@@ -21,7 +24,7 @@ export function createTextPart(ctx: StreamContext, text: string, streaming = tru
 		id: generateUUIDv7(),
 		sessionId: ctx.sessionId,
 		messageId: ctx.messageId,
-		...(ctx.parentToolUseId && { parentToolUseId: ctx.parentToolUseId }),
+		...(ctx.parentToolCallId && { parentToolCallId: ctx.parentToolCallId }),
 		type: "text",
 		text,
 		state: streaming ? "streaming" : "done",
@@ -37,7 +40,7 @@ export function createReasoningPart(
 		id: generateUUIDv7(),
 		sessionId: ctx.sessionId,
 		messageId: ctx.messageId,
-		...(ctx.parentToolUseId && { parentToolUseId: ctx.parentToolUseId }),
+		...(ctx.parentToolCallId && { parentToolCallId: ctx.parentToolCallId }),
 		type: "reasoning",
 		text,
 		state: streaming ? "streaming" : "done",
@@ -49,13 +52,14 @@ function toolBase(ctx: StreamContext, toolCallId: string, toolName: string, meta
 		id: generateUUIDv7(),
 		sessionId: ctx.sessionId,
 		messageId: ctx.messageId,
-		...(ctx.parentToolUseId && { parentToolUseId: ctx.parentToolUseId }),
+		...(ctx.parentToolCallId && { parentToolCallId: ctx.parentToolCallId }),
 		type: "tool" as const,
 		toolCallId,
 		toolName,
-		...(meta?.kind && { kind: meta.kind }),
+		...(meta?.subagent ? { kind: "task" as const } : meta?.kind ? { kind: meta.kind } : {}),
 		...(meta?.title && { title: meta.title }),
 		...(meta?.locations?.length && { locations: meta.locations }),
+		...(meta?.subagent && { subagent: meta.subagent }),
 	};
 }
 
@@ -101,7 +105,12 @@ export function appendToolInput(part: ToolPart, partialJson: string): void {
 
 /** 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.subagent) {
+		part.subagent = meta.subagent;
+		part.kind = "task";
+	} else if (meta.kind) {
+		part.kind = meta.kind;
+	}
 	if (meta.title) part.title = meta.title;
 	if (meta.locations?.length) part.locations = meta.locations;
 }
@@ -109,7 +118,15 @@ export function setToolMeta(part: ToolPart, meta: ToolMeta): void {
 /** Mutates a tool part into its terminal `completed`/`failed` state. */
 export function completeToolPart(
 	part: ToolPart,
-	result: { output: string; isError?: boolean; title?: string },
+	result: {
+		output: string;
+		isError?: boolean;
+		title?: string;
+		/** Display-grade structured output (diffs, images, terminals). */
+		content?: ToolResultContent[];
+		/** Machine channel: harness-native extras (e.g. exitCode). */
+		metadata?: Record<string, unknown>;
+	},
 ): void {
 	const start = part.state.status === "in_progress" ? part.state.time.start : Date.now();
 	const input = "input" in part.state ? part.state.input : {};
@@ -119,7 +136,86 @@ export function completeToolPart(
 				status: "completed",
 				input,
 				output: result.output,
-				title: result.title ?? part.toolName,
+				...(result.title !== undefined && { title: result.title }),
+				...(result.content?.length && { content: result.content }),
+				...(result.metadata && { metadata: result.metadata }),
 				time: { start, end: Date.now() },
 			};
 }
+
+/**
+ * The user echo's message id, derived from the turn id.
+ *
+ * A DELIBERATE, documented exception to Law 8 (engine-minted UUIDv7): the echo
+ * is not new information, it is the caller's own input played back, and one
+ * turn has exactly one echo message. Deriving the id means a consumer can
+ * predict the echo byte-for-byte from the `turnId` it minted — so an
+ * optimistically-rendered prompt bubble IS the echo (same id, same parts)
+ * instead of a look-alike that has to be reconciled and swapped. The
+ * reconcile-by-turnId dance every product wrote is what this replaces.
+ *
+ * Ids stay opaque to peers: nothing may parse structure out of them. This is a
+ * PRODUCER rule (how the engine mints), matched by a consumer helper — not a
+ * licence to infer turn ids from message ids elsewhere.
+ *
+ * Two consequences of NOT being UUIDv7, for consumers that leaned on Law 8's
+ * side effects: echo ids do not TIME-SORT against UUIDv7 ids (`echo-` sorts
+ * after every hex digit — never order by id), and they do not fit uuid-typed
+ * columns or id-derived timestamps (`createdAtFromUUID7(echoId)` is 0 — derive
+ * the echo's time from the `turnId` FIELD the event/row carries, never by
+ * parsing the echo id string; ids stay opaque).
+ */
+export function echoMessageId(turnId: string): string {
+	return `echo-${turnId}`;
+}
+
+/** The id of the echo part at `index` — same derivation, same predictability. */
+export function echoPartId(turnId: string, index: number): string {
+	return `echo-${turnId}-${index}`;
+}
+
+/**
+ * Build the parts for the user echo (spec §7.2) from a turn's input. Part ids
+ * are derived from the turn (see `echoPartId`), so the whole echo message is
+ * predictable from `{turnId, input}` alone. The EventProcessor stamps
+ * `sessionId`/`messageId` at emit time. Text `elements` spans ride `_meta`
+ * (the part vocabulary stays output-shaped; the spans are UI-authored
+ * annotations).
+ */
+export function createUserEchoParts(input: AgentInput, turnId: string): Part[] {
+	const items = typeof input === "string" ? [{ type: "text" as const, text: input }] : input;
+	const parts: Part[] = [];
+	for (let index = 0; index < items.length; index++) {
+		const item = items[index] as (typeof items)[number];
+		const base = { id: echoPartId(turnId, index), sessionId: "", messageId: "" };
+		if (item.type === "text") {
+			parts.push({
+				...base,
+				type: "text",
+				text: item.text,
+				state: "done",
+				...("elements" in item && item.elements?.length
+					? { _meta: { elements: item.elements } }
+					: {}),
+			});
+		} else if (item.type === "image") {
+			parts.push({
+				...base,
+				type: "image",
+				...(item.data !== undefined && { data: item.data }),
+				...(item.url !== undefined && { url: item.url }),
+				mimeType: item.mimeType,
+			});
+		} else {
+			parts.push({
+				...base,
+				type: "file",
+				...(item.data !== undefined && { data: item.data }),
+				...(item.url !== undefined && { url: item.url }),
+				mimeType: item.mimeType,
+				...(item.filename !== undefined && { filename: item.filename }),
+			});
+		}
+	}
+	return parts;
+}

package/src/protocol/guards.ts

@@ -0,0 +1,53 @@
+// The Law-6 membership tests, kept in one zod-free module.
+//
+// A guard is a string comparison against a frozen list — but when it lives
+// next to the schema it guards, importing it pulls zod (and the whole part /
+// event union) into the importer's bundle. Browser consumers pay ~100kB to ask
+// "is this part type one I know?". These are re-exported from `./index.ts`
+// (nothing moved for `@zvada/agent-server/protocol` importers) and are also
+// reachable directly as `@zvada/agent-server/protocol/guards`, which is
+// guaranteed zod-free at runtime (`test/protocol/zod-free.test.ts` walks the
+// transitive import graph).
+//
+// Type-only imports below are erased at compile time and cost nothing at
+// runtime — the modules they name are never loaded by this one.
+import type { DecodedLifecycleEvent, UnknownEvent } from "./lifecycle.ts";
+import type { Part, UnknownPart } from "./parts.ts";
+
+export const PART_TYPES = ["text", "reasoning", "tool", "image", "file"] as const;
+
+export function isKnownPartType(type: unknown): type is (typeof PART_TYPES)[number] {
+	return typeof type === "string" && (PART_TYPES as readonly string[]).includes(type);
+}
+
+export function isUnknownPart(part: Part | UnknownPart): part is UnknownPart {
+	return !isKnownPartType(part.type);
+}
+// No per-type guards for known parts: `p.type === "text"` narrows natively.
+
+export const LIFECYCLE_EVENT_TYPES = [
+	"session.created",
+	"session.ended",
+	"turn.started",
+	"message.started",
+	"message.part",
+	"message.part.delta",
+	"message.ended",
+	"turn.ended",
+	"session.usage",
+	"session.compaction",
+	"error",
+	"permission.requested",
+	"permission.resolved",
+	"raw",
+] as const;
+
+export function isKnownLifecycleEventType(
+	type: unknown,
+): type is (typeof LIFECYCLE_EVENT_TYPES)[number] {
+	return typeof type === "string" && (LIFECYCLE_EVENT_TYPES as readonly string[]).includes(type);
+}
+
+export function isUnknownEvent(event: DecodedLifecycleEvent | UnknownEvent): event is UnknownEvent {
+	return !isKnownLifecycleEventType((event as { type: string }).type);
+}

package/src/protocol/index.ts

@@ -3,8 +3,13 @@
 
 export * from "./ids.ts";
 export * from "./async-queue.ts";
+export * from "./meta.ts";
+export * from "./time.ts";
+export * from "./vocabulary.ts";
+export * from "./errors.ts";
 export * from "./tokens.ts";
 export * from "./tool-state.ts";
+export * from "./guards.ts";
 export * from "./parts.ts";
 export * from "./part-input.ts";
 export * from "./factories.ts";
@@ -13,4 +18,9 @@ export * from "./thinking.ts";
 export * from "./models.ts";
 export * from "./config.ts";
 export * from "./lifecycle.ts";
+export * from "./stop-reasons.ts";
+export * from "./seq-cursor.ts";
+export * from "./reduce.ts";
+export * from "./selectors.ts";
+export * from "./verify.ts";
 export * from "./wire.ts";