@zvada/agent-server 0.2.0

package/src/protocol/lifecycle.ts

@@ -0,0 +1,309 @@
+import { z } from "zod";
+import { AgentHarnessSchema } from "./harness.ts";
+import { PartSchema } from "./parts.ts";
+import { TokenUsageSchema } from "./tokens.ts";
+import { ToolKindSchema, ToolLocationSchema } from "./tool-state.ts";
+
+/**
+ * The normalized event stream every harness is funneled into. Consumers (a WS
+ * bridge, an SSE endpoint, a CLI, a test sink) subscribe to these and never see
+ * raw SDK payloads. All keys are camelCase; serialize at your transport edge.
+ *
+ * Ordering within a turn:
+ *   session.created? -> turn.started -> (message.started -> message.part*
+ *   / message.part.delta* -> message.ended)* -> turn.ended
+ *
+ * Two exceptions to strict message bracketing:
+ *  - a `message.part` may arrive after its message ended (a tool completing
+ *    after the model message that issued it) — upsert by `part.id`.
+ *  - `permission.requested`/`permission.resolved` and `raw` events interleave
+ *    anywhere between turn.started and turn.ended.
+ */
+
+/**
+ * Why a turn stopped (ACP-aligned, plus `error`). This is the normalized
+ * terminal status; the raw provider string travels in `finishReason`.
+ */
+export const STOP_REASONS = [
+	"end_turn",
+	"max_tokens",
+	"max_turn_requests",
+	"refusal",
+	"cancelled",
+	"error",
+] as const;
+export type StopReason = (typeof STOP_REASONS)[number];
+export const StopReasonSchema = z.enum(STOP_REASONS);
+
+/** Emitted once the harness-native session id is known — persist it to resume later. */
+export const SessionCreatedEventSchema = z.object({
+	type: z.literal("session.created"),
+	sessionId: z.string(),
+	/** Native id to pass back as `resumeSessionId` (Claude session_id / Codex threadId). */
+	nativeSessionId: z.string(),
+	harness: AgentHarnessSchema,
+	model: z.string().optional(),
+	/**
+	 * Present only when this turn requested a resume: whether the harness
+	 * actually continued that conversation. `false` = it fell back to a fresh
+	 * session (context lost) — surface this, never swallow it. Compare with
+	 * this flag, not ids: some harnesses mint a NEW nativeSessionId on a
+	 * successful resume (Claude).
+	 */
+	resumed: z.boolean().optional(),
+	timestamp: z.number(),
+});
+export type SessionCreatedEvent = z.infer<typeof SessionCreatedEventSchema>;
+
+export const TurnStartedEventSchema = z.object({
+	type: z.literal("turn.started"),
+	turnId: z.string(),
+	sessionId: z.string(),
+	timestamp: z.number(),
+});
+export type TurnStartedEvent = z.infer<typeof TurnStartedEventSchema>;
+
+export const MessageStartedEventSchema = z.object({
+	type: z.literal("message.started"),
+	turnId: z.string(),
+	messageId: z.string(),
+	outputIndex: z.number(),
+	role: z.enum(["user", "assistant"]),
+	/**
+	 * Set when this message is a sub-agent's output: the `toolCallId` of the
+	 * tool (e.g. Task) that spawned it. Such a message is NOT a top-level model
+	 * message — consumers nest it under that tool call. Absent for top-level
+	 * messages.
+	 */
+	parentToolUseId: z.string().optional(),
+	timestamp: z.number(),
+	metadata: z
+		.object({
+			sessionId: z.string().optional(),
+			harness: z.string().optional(),
+			model: z.string().optional(),
+		})
+		.optional(),
+});
+export type MessageStartedEvent = z.infer<typeof MessageStartedEventSchema>;
+
+/** A fully-formed (or newly-finalized) part snapshot. Upsert by `part.id`. */
+export const MessagePartEventSchema = z.object({
+	type: z.literal("message.part"),
+	turnId: z.string(),
+	messageId: z.string(),
+	outputIndex: z.number(),
+	partIndex: z.number(),
+	part: PartSchema,
+	parentToolUseId: z.string().optional(),
+	timestamp: z.number(),
+});
+export type MessagePartEvent = z.infer<typeof MessagePartEventSchema>;
+
+export const DeltaSchema = z.discriminatedUnion("type", [
+	z.object({ type: z.literal("text-delta"), text: z.string() }),
+	z.object({ type: z.literal("reasoning-delta"), text: z.string() }),
+	z.object({
+		type: z.literal("tool-input-delta"),
+		toolCallId: z.string(),
+		toolName: z.string(),
+		input: z.string(),
+	}),
+]);
+export type Delta = z.infer<typeof DeltaSchema>;
+
+/** An incremental update to a streaming part (text/reasoning/tool-input). */
+export const MessagePartDeltaEventSchema = z.object({
+	type: z.literal("message.part.delta"),
+	turnId: z.string(),
+	messageId: z.string(),
+	outputIndex: z.number(),
+	partIndex: z.number(),
+	partId: z.string(),
+	delta: DeltaSchema,
+	parentToolUseId: z.string().optional(),
+	timestamp: z.number(),
+});
+export type MessagePartDeltaEvent = z.infer<typeof MessagePartDeltaEventSchema>;
+
+export const MessageEndedEventSchema = z.object({
+	type: z.literal("message.ended"),
+	turnId: z.string(),
+	messageId: z.string(),
+	timestamp: z.number(),
+});
+export type MessageEndedEvent = z.infer<typeof MessageEndedEventSchema>;
+
+export const TurnEndedEventSchema = z.object({
+	type: z.literal("turn.ended"),
+	turnId: z.string(),
+	sessionId: z.string(),
+	/** Normalized terminal status — `cancelled` and `error` are first-class. */
+	stopReason: StopReasonSchema,
+	/** Raw provider finish string (`end_turn`, `completed`, …), when reported. */
+	finishReason: z.string().optional(),
+	tokens: TokenUsageSchema.optional(),
+	cost: z.number().optional(),
+	error: z.object({ name: z.string(), message: z.string() }).optional(),
+	timestamp: z.number(),
+});
+export type TurnEndedEvent = z.infer<typeof TurnEndedEventSchema>;
+
+/**
+ * Context-window gauge, emitted whenever the harness reports fresh numbers
+ * (per model message on Claude, per token-count update on Codex, per ACP
+ * `usage_update`). Vocabulary tracks ACP's stable `usage_update` shape:
+ * `used`/`size`/`cost`. Distinct from `turn.ended.tokens`, which is the
+ * turn's billing total — this is "how full is the session right now".
+ */
+export const SessionUsageEventSchema = z.object({
+	type: z.literal("session.usage"),
+	sessionId: z.string(),
+	turnId: z.string(),
+	/** Tokens currently occupying the context window (prompt + output). */
+	used: z.number(),
+	/** The model's context-window size, when the harness reports it. */
+	size: z.number().optional(),
+	/** Cumulative session cost in USD, when the harness reports it. */
+	cost: z.number().optional(),
+	timestamp: z.number(),
+});
+export type SessionUsageEvent = z.infer<typeof SessionUsageEventSchema>;
+
+/**
+ * The harness compacted the session's history (context summarization). A
+ * boundary marker, not a rewrite: consumers that render history decide what
+ * to do at the boundary; the engine stays append-only.
+ */
+export const SessionCompactedEventSchema = z.object({
+	type: z.literal("session.compacted"),
+	sessionId: z.string(),
+	turnId: z.string(),
+	/** What triggered it, when known (Claude: `manual` | `auto`). */
+	trigger: z.string().optional(),
+	/** Context tokens before/after the compaction, when reported. */
+	preTokens: z.number().optional(),
+	postTokens: z.number().optional(),
+	timestamp: z.number(),
+});
+export type SessionCompactedEvent = z.infer<typeof SessionCompactedEventSchema>;
+
+export const ErrorEventSchema = z.object({
+	type: z.literal("error"),
+	turnId: z.string().optional(),
+	sessionId: z.string().optional(),
+	error: z.string(),
+	recoverable: z.boolean(),
+	code: z.string().optional(),
+	stack: z.string().optional(),
+	timestamp: z.number(),
+});
+export type ErrorEvent = z.infer<typeof ErrorEventSchema>;
+
+// ---- permissions (ACP request_permission-shaped) ----------------------------
+
+export const PermissionOptionKindSchema = z.enum([
+	"allow_once",
+	"allow_always",
+	"reject_once",
+	"reject_always",
+]);
+export type PermissionOptionKind = z.infer<typeof PermissionOptionKindSchema>;
+
+export const PermissionOptionSchema = z.object({
+	optionId: z.string(),
+	name: z.string(),
+	kind: PermissionOptionKindSchema,
+});
+export type PermissionOption = z.infer<typeof PermissionOptionSchema>;
+
+/** The tool call a permission request is about (snapshot, not a live part). */
+export const PermissionToolCallSchema = z.object({
+	/**
+	 * The `toolCallId` of the in-flight tool part this request gates. Real for
+	 * codex approvals AND Claude (`canUseTool` exposes `toolUseID` since SDK
+	 * 0.2.138). Optional only for harnesses that genuinely cannot correlate.
+	 */
+	toolCallId: z.string().optional(),
+	toolName: z.string(),
+	kind: ToolKindSchema.optional(),
+	title: z.string().optional(),
+	locations: z.array(ToolLocationSchema).optional(),
+	rawInput: z.record(z.string(), z.unknown()).optional(),
+});
+export type PermissionToolCall = z.infer<typeof PermissionToolCallSchema>;
+
+export const PermissionOutcomeSchema = z.discriminatedUnion("outcome", [
+	z.object({ outcome: z.literal("selected"), optionId: z.string() }),
+	z.object({ outcome: z.literal("cancelled") }),
+]);
+export type PermissionOutcome = z.infer<typeof PermissionOutcomeSchema>;
+
+/**
+ * The harness is blocked waiting for a decision. Answer via
+ * `AgentRuntime.respondPermission(sessionId, requestId, outcome)`. Pending
+ * requests resolve as `cancelled` when the turn is cancelled or ends.
+ */
+export const PermissionRequestedEventSchema = z.object({
+	type: z.literal("permission.requested"),
+	sessionId: z.string(),
+	turnId: z.string(),
+	requestId: z.string(),
+	/** Human-readable one-line prompt, always present (render this). */
+	title: z.string(),
+	/**
+	 * Structured context when the request gates a tool call — today every
+	 * harness permission is tool-scoped, but the field is optional because a
+	 * future `acp` harness can raise subject-less requests (ACP v2 shape).
+	 */
+	toolCall: PermissionToolCallSchema.optional(),
+	options: z.array(PermissionOptionSchema),
+	timestamp: z.number(),
+});
+export type PermissionRequestedEvent = z.infer<typeof PermissionRequestedEventSchema>;
+
+/** A pending permission request was answered (or cancelled). */
+export const PermissionResolvedEventSchema = z.object({
+	type: z.literal("permission.resolved"),
+	sessionId: z.string(),
+	turnId: z.string(),
+	requestId: z.string(),
+	outcome: PermissionOutcomeSchema,
+	timestamp: z.number(),
+});
+export type PermissionResolvedEvent = z.infer<typeof PermissionResolvedEventSchema>;
+
+// ---- raw passthrough ---------------------------------------------------------
+
+/**
+ * Opt-in (`RunConfig.includeRaw`) passthrough of the harness's raw event,
+ * interleaved with the normalized stream. Escape hatch for migration,
+ * debugging, and fixture recording — `data` carries NO stability guarantees
+ * and is not part of the contract.
+ */
+export const RawEventSchema = z.object({
+	type: z.literal("raw"),
+	sessionId: z.string(),
+	turnId: z.string(),
+	harness: AgentHarnessSchema,
+	data: z.unknown(),
+	timestamp: z.number(),
+});
+export type RawEvent = z.infer<typeof RawEventSchema>;
+
+export const LifecycleEventSchema = z.discriminatedUnion("type", [
+	SessionCreatedEventSchema,
+	TurnStartedEventSchema,
+	MessageStartedEventSchema,
+	MessagePartEventSchema,
+	MessagePartDeltaEventSchema,
+	MessageEndedEventSchema,
+	TurnEndedEventSchema,
+	SessionUsageEventSchema,
+	SessionCompactedEventSchema,
+	ErrorEventSchema,
+	PermissionRequestedEventSchema,
+	PermissionResolvedEventSchema,
+	RawEventSchema,
+]);
+export type LifecycleEvent = z.infer<typeof LifecycleEventSchema>;

package/src/protocol/models.ts

@@ -0,0 +1,45 @@
+import type { AgentHarness } from "./harness.ts";
+import type { ThinkingLevel } from "./thinking.ts";
+
+/**
+ * Advisory catalog of known-good models per harness. `model` on a RunConfig is
+ * a free-form string (harnesses pass it through), so unlisted models still work;
+ * this catalog drives UIs/pickers and supplies sensible per-harness defaults.
+ */
+export interface ModelInfo {
+	readonly id: string;
+	readonly harness: AgentHarness;
+	readonly label: string;
+	readonly thinking: readonly ThinkingLevel[];
+}
+
+const ALL: readonly ThinkingLevel[] = ["off", "low", "medium", "high", "xhigh"];
+
+export const MODEL_CATALOG: readonly ModelInfo[] = [
+	// Claude (the claude CLI also accepts the bare aliases "sonnet"/"opus"/"haiku").
+	{ id: "sonnet", harness: "claude-code", label: "Claude Sonnet (latest)", thinking: ALL },
+	{ id: "opus", harness: "claude-code", label: "Claude Opus (latest)", thinking: ALL },
+	{ id: "haiku", harness: "claude-code", label: "Claude Haiku (latest)", thinking: ALL },
+	// Codex (shared between codex-sdk and codex-app-server).
+	{ id: "gpt-5.5", harness: "codex-sdk", label: "GPT-5.5", thinking: ALL },
+	{ id: "gpt-5.5-codex", harness: "codex-sdk", label: "GPT-5.5 Codex", thinking: ALL },
+	{ id: "gpt-5.5", harness: "codex-app-server", label: "GPT-5.5", thinking: ALL },
+	{ id: "gpt-5.5-codex", harness: "codex-app-server", label: "GPT-5.5 Codex", thinking: ALL },
+];
+
+/**
+ * Default model per harness. `undefined` means "let the harness/CLI use its own
+ * configured default" (Codex reads `~/.codex/config.toml`).
+ */
+export const DEFAULT_MODELS: Record<AgentHarness, string | undefined> = {
+	"claude-code": "sonnet",
+	"codex-sdk": undefined,
+	"codex-app-server": undefined,
+	// ACP v1 has no portable model parameter (selection is agent-defined via
+	// config options), so the target agent always uses its own default.
+	acp: undefined,
+};
+
+export function modelsForHarness(harness: AgentHarness): readonly ModelInfo[] {
+	return MODEL_CATALOG.filter((m) => m.harness === harness);
+}

package/src/protocol/part-input.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+
+/** Inbound user content for a turn: plain text, or multimodal blocks. */
+export const TextPartInputSchema = z.object({
+	type: z.literal("text"),
+	id: z.string().optional(),
+	text: z.string().min(1),
+});
+export type TextPartInput = z.infer<typeof TextPartInputSchema>;
+
+export const ImagePartInputSchema = z
+	.object({
+		type: z.literal("image"),
+		id: z.string().optional(),
+		/** Either a URL or base64 `data` (one is required). */
+		url: z.string().min(1).optional(),
+		data: z.string().min(1).optional(),
+		mediaType: z.string(),
+		filename: z.string().optional(),
+	})
+	.refine((part) => part.url !== undefined || part.data !== undefined, {
+		message: "image input requires a non-empty url or data payload",
+	});
+export type ImagePartInput = z.infer<typeof ImagePartInputSchema>;
+
+export const FilePartInputSchema = z
+	.object({
+		type: z.literal("file"),
+		id: z.string().optional(),
+		url: z.string().min(1).optional(),
+		data: z.string().min(1).optional(),
+		mediaType: z.string(),
+		filename: z.string().optional(),
+	})
+	.refine((part) => part.url !== undefined || part.data !== undefined, {
+		message: "file input requires a non-empty url or data payload",
+	});
+export type FilePartInput = z.infer<typeof FilePartInputSchema>;
+
+export const PartInputSchema = z.discriminatedUnion("type", [
+	TextPartInputSchema,
+	ImagePartInputSchema,
+	FilePartInputSchema,
+]);
+export type PartInput = z.infer<typeof PartInputSchema>;
+
+/** A turn's input is either a bare string or a list of typed parts. */
+export const AgentInputSchema = z.union([z.string(), z.array(PartInputSchema)]);
+export type AgentInput = z.infer<typeof AgentInputSchema>;
+
+/** Collapse an AgentInput down to the text the model sees first. */
+export function inputToText(input: AgentInput): string {
+	if (typeof input === "string") return input;
+	return input
+		.filter((p): p is TextPartInput => p.type === "text")
+		.map((p) => p.text)
+		.join("\n\n");
+}

package/src/protocol/parts.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { ToolKindSchema, ToolLocationSchema, ToolStateSchema } from "./tool-state.ts";
+
+/**
+ * A Part is the atomic unit of assistant output, normalized across harnesses.
+ * Every part belongs to a message within a session. Parts stream: a TextPart
+ * arrives `streaming` and is finalized `done`; a ToolPart's `state` advances
+ * through the tool lifecycle. `parentToolUseId` links a part produced inside a
+ * sub-agent / nested tool execution back to the tool call that spawned it.
+ *
+ * Rule: this union contains only part types adapters actually emit — the
+ * protocol advertises nothing it doesn't deliver.
+ */
+const PartBase = z.object({
+	id: z.string(),
+	sessionId: z.string(),
+	messageId: z.string(),
+	parentToolUseId: z.string().optional(),
+});
+
+export const TextPartSchema = PartBase.extend({
+	type: z.literal("text"),
+	text: z.string(),
+	state: z.enum(["streaming", "done"]).optional(),
+});
+export type TextPart = z.infer<typeof TextPartSchema>;
+
+export const ReasoningPartSchema = PartBase.extend({
+	type: z.literal("reasoning"),
+	text: z.string(),
+	state: z.enum(["streaming", "done"]).optional(),
+	providerMetadata: z.record(z.string(), z.unknown()).optional(),
+});
+export type ReasoningPart = z.infer<typeof ReasoningPartSchema>;
+
+export const ToolPartSchema = PartBase.extend({
+	type: z.literal("tool"),
+	toolCallId: z.string(),
+	/** Provider-native tool name (`Bash`, `shell`, `mcp.search`, …). */
+	toolName: z.string(),
+	/** Normalized classification of what the call does (ACP ToolKind). */
+	kind: ToolKindSchema.optional(),
+	/** Human-readable label when the harness provides one. */
+	title: z.string().optional(),
+	/** Files this call touches, for follow-along UIs. */
+	locations: z.array(ToolLocationSchema).optional(),
+	state: ToolStateSchema,
+});
+export type ToolPart = z.infer<typeof ToolPartSchema>;
+
+export const PartSchema = z.discriminatedUnion("type", [
+	TextPartSchema,
+	ReasoningPartSchema,
+	ToolPartSchema,
+]);
+export type Part = z.infer<typeof PartSchema>;
+
+export const isTextPart = (p: Part): p is TextPart => p.type === "text";
+export const isReasoningPart = (p: Part): p is ReasoningPart => p.type === "reasoning";
+export const isToolPart = (p: Part): p is ToolPart => p.type === "tool";

package/src/protocol/thinking.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+
+/**
+ * A single, harness-agnostic reasoning dial. Each harness maps it to its own
+ * native control: Claude -> adaptive `thinking` + `effort`; Codex ->
+ * `ReasoningEffort`.
+ */
+export const THINKING_LEVELS = ["off", "low", "medium", "high", "xhigh"] as const;
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+export const ThinkingLevelSchema = z.enum(THINKING_LEVELS);
+export const DEFAULT_THINKING_LEVEL: ThinkingLevel = "medium";
+
+export function isThinkingLevel(v: string): v is ThinkingLevel {
+	return (THINKING_LEVELS as readonly string[]).includes(v);
+}
+
+/** Codex reasoning-effort string for a level (matches the `ReasoningEffort` enum). */
+export type CodexReasoningEffort = "minimal" | "low" | "medium" | "high" | "xhigh";
+export function codexReasoningEffort(level: ThinkingLevel): CodexReasoningEffort {
+	switch (level) {
+		case "off":
+			return "minimal";
+		case "low":
+			return "low";
+		case "medium":
+			return "medium";
+		case "high":
+			return "high";
+		case "xhigh":
+			return "xhigh";
+	}
+}

package/src/protocol/tokens.ts

@@ -0,0 +1,39 @@
+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.
+ */
+export const TokenUsageSchema = z.object({
+	input: z.number().default(0),
+	output: z.number().default(0),
+	reasoning: z.number().optional(),
+	cache: z
+		.object({
+			read: z.number().default(0),
+			write: z.number().default(0),
+		})
+		.optional(),
+});
+
+export type TokenUsage = z.infer<typeof TokenUsageSchema>;
+
+export const DEFAULT_TOKEN_USAGE: TokenUsage = {
+	input: 0,
+	output: 0,
+	reasoning: 0,
+	cache: { read: 0, write: 0 },
+};
+
+export function addTokenUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
+	return {
+		input: a.input + b.input,
+		output: a.output + b.output,
+		reasoning: (a.reasoning ?? 0) + (b.reasoning ?? 0),
+		cache: {
+			read: (a.cache?.read ?? 0) + (b.cache?.read ?? 0),
+			write: (a.cache?.write ?? 0) + (b.cache?.write ?? 0),
+		},
+	};
+}

package/src/protocol/tool-state.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+
+/**
+ * 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.
+ */
+export const RUNTIME_TOOL_STATUSES = ["pending", "in_progress", "completed", "failed"] 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.
+ */
+export const TOOL_KINDS = [
+	"read",
+	"edit",
+	"delete",
+	"move",
+	"search",
+	"execute",
+	"think",
+	"fetch",
+	"switch_mode",
+	"other",
+] as const;
+export type ToolKind = (typeof TOOL_KINDS)[number];
+export const ToolKindSchema = z.enum(TOOL_KINDS);
+
+/** A file location a tool call touches — lets UIs "follow along". */
+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>;
+
+export const ToolStatePendingSchema = z.object({
+	status: z.literal("pending"),
+	partialInput: z.string(),
+});
+export type ToolStatePending = z.infer<typeof ToolStatePendingSchema>;
+
+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() }),
+});
+export type ToolStateInProgress = z.infer<typeof ToolStateInProgressSchema>;
+
+export const ToolStateCompletedSchema = z.object({
+	status: z.literal("completed"),
+	input: z.record(z.string(), z.unknown()),
+	output: z.string(),
+	title: z.string(),
+	metadata: z.record(z.string(), z.unknown()).optional(),
+	time: z.object({ start: z.number(), end: z.number() }),
+	attachments: z.array(ToolAttachmentSchema).optional(),
+});
+export type ToolStateCompleted = z.infer<typeof ToolStateCompletedSchema>;
+
+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() }),
+});
+export type ToolStateFailed = z.infer<typeof ToolStateFailedSchema>;
+
+export const ToolStateSchema = z.discriminatedUnion("status", [
+	ToolStatePendingSchema,
+	ToolStateInProgressSchema,
+	ToolStateCompletedSchema,
+	ToolStateFailedSchema,
+]);
+export type ToolState = z.infer<typeof ToolStateSchema>;