@zvada/agent-server 0.2.2 → 0.3.1

package/src/protocol/lifecycle.ts

@@ -1,28 +1,56 @@
 import { z } from "zod";
+import { ErrorCategorySchema, ErrorInfoSchema } from "./errors.ts";
+import { isKnownLifecycleEventType } from "./guards.ts";
 import { AgentHarnessSchema } from "./harness.ts";
-import { PartSchema } from "./parts.ts";
+import { MetaSchema } from "./meta.ts";
+import { type Part, PartSchema, type UnknownPart, decodePart } from "./parts.ts";
+import { EpochMsSchema } from "./time.ts";
 import { TokenUsageSchema } from "./tokens.ts";
 import { ToolKindSchema, ToolLocationSchema } from "./tool-state.ts";
+import { openVocabulary } from "./vocabulary.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.
+ * Every event carries `sessionId`, `timestamp` (epoch ms), and `_meta`.
  *
  * Ordering within a turn:
- *   session.created? -> turn.started -> (message.started -> message.part*
- *   / message.part.delta* -> message.ended)* -> turn.ended
+ *   turn.started
+ *     -> [ USER ECHO: message.started{role:"user", outputIndex:0}
+ *          -> message.part* -> message.ended ]
+ *     -> ( message.started{role:"assistant"} -> message.part*
+ *          / message.part.delta* -> message.ended )*
+ *     -> turn.ended
+ *   session.created lands WHEN THE HARNESS FIRST REPORTS its native session id
+ *   — its first yield — so arriving MID-TURN, after the echo and before the
+ *   first assistant message, is the normal case rather than an anomaly. It
+ *   cannot be hoisted: the id does not exist until the harness produces it,
+ *   and holding the echo back for it would delay the transcript of every turn
+ *   on a subprocess spawn. Persist it whenever it arrives; never treat it as a
+ *   turn preamble.
+ *   session.compaction may appear anywhere within a turn (position = first
+ *   appearance). permission.* and raw interleave anywhere within a turn.
+ *   session.ended may follow at any later point.
  *
- * 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.
+ * Exceptions to strict message bracketing:
+ *  - a `message.part` may arrive after its message (or turn) ended — a tool
+ *    completing late. The event's `messageId` names the ORIGINAL message and
+ *    the upsert lands there.
+ *  - snapshots are authoritative over deltas: a content-bearing `message.part`
+ *    wipes the delta accumulator for that part; later deltas append to the
+ *    replacement. A non-terminal snapshot must not carry partially-accumulated
+ *    streamed content (field-ownership rule).
  */
 
 /**
- * Why a turn stopped (ACP-aligned, plus `error`). This is the normalized
+ * Why a turn stopped (ACP StopReason verbatim, plus `error`). Normalized
  * terminal status; the raw provider string travels in `finishReason`.
+ *
+ * OPEN (Law 3): `_`-prefixed values are adapter extensions (e.g. Claude's
+ * error_max_budget_usd -> `_max_budget`); unknown non-`_` values are reserved
+ * for this protocol and MUST be preserved. `refusal` covers provider
+ * content-filter/safety stops.
  */
 export const STOP_REASONS = [
 	"end_turn",
@@ -32,8 +60,25 @@ export const STOP_REASONS = [
 	"cancelled",
 	"error",
 ] as const;
-export type StopReason = (typeof STOP_REASONS)[number];
-export const StopReasonSchema = z.enum(STOP_REASONS);
+export type StopReason = (typeof STOP_REASONS)[number] | (string & {});
+export const StopReasonSchema = openVocabulary<StopReason>();
+
+/** Why a harness session ended. OPEN. */
+export const SESSION_END_REASONS = ["idle", "replaced", "released", "shutdown"] as const;
+export type SessionEndReason = (typeof SESSION_END_REASONS)[number] | (string & {});
+export const SessionEndReasonSchema = openVocabulary<SessionEndReason>();
+
+/** Compaction entity status. OPEN. */
+export const COMPACTION_STATUSES = ["in_progress", "completed", "failed", "cancelled"] as const;
+export type CompactionStatus = (typeof COMPACTION_STATUSES)[number] | (string & {});
+export const CompactionStatusSchema = openVocabulary<CompactionStatus>();
+
+/** What caused a compaction (Claude: `auto` | `manual`). OPEN. */
+export const COMPACTION_TRIGGERS = ["auto", "manual"] as const;
+export type CompactionTrigger = (typeof COMPACTION_TRIGGERS)[number] | (string & {});
+export const CompactionTriggerSchema = openVocabulary<CompactionTrigger>();
+
+// ---- session events ---------------------------------------------------------
 
 /** Emitted once the harness-native session id is known — persist it to resume later. */
 export const SessionCreatedEventSchema = z.object({
@@ -51,22 +96,110 @@ export const SessionCreatedEventSchema = z.object({
 	 * successful resume (Claude).
 	 */
 	resumed: z.boolean().optional(),
-	timestamp: z.number(),
+	timestamp: EpochMsSchema,
+	_meta: MetaSchema,
 });
 export type SessionCreatedEvent = z.infer<typeof SessionCreatedEventSchema>;
 
+/** The harness session is over (idle timeout, replacement, release, shutdown). */
+export const SessionEndedEventSchema = z.object({
+	type: z.literal("session.ended"),
+	sessionId: z.string(),
+	reason: SessionEndReasonSchema,
+	timestamp: EpochMsSchema,
+	_meta: MetaSchema,
+});
+export type SessionEndedEvent = z.infer<typeof SessionEndedEventSchema>;
+
+/**
+ * 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: EpochMsSchema,
+	_meta: MetaSchema,
+});
+export type SessionUsageEvent = z.infer<typeof SessionUsageEventSchema>;
+
+/**
+ * The compaction entity: an ID-addressed, POSITIONAL timeline entity — UPSERT
+ * by `compactionId`. The first event for an id anchors the entity's position
+ * in the ordered stream (the reducer places it there in the timeline); later
+ * upserts advance `status` and stream `summary` without moving it. Neither a
+ * part nor a bare notification: a replayed transcript needs the divider IN the
+ * order (Codex deprecated their session-level notification for exactly this;
+ * matches ACP's session-compaction draft so a future binding is a passthrough).
+ */
+export const SessionCompactionEventSchema = z.object({
+	type: z.literal("session.compaction"),
+	sessionId: z.string(),
+	turnId: z.string(),
+	compactionId: z.string(),
+	status: CompactionStatusSchema,
+	/** What triggered it, when known (Claude: `manual` | `auto`). */
+	trigger: CompactionTriggerSchema.optional(),
+	/** Context tokens before/after the compaction, when reported. */
+	preTokens: z.number().optional(),
+	postTokens: z.number().optional(),
+	/** User-displayable summary; may stream via successive upserts. */
+	summary: z.string().optional(),
+	/** Part ids the summary subsumed — auditable compaction lineage. */
+	abstractsIds: z.array(z.string()).optional(),
+	timestamp: EpochMsSchema,
+	_meta: MetaSchema,
+});
+export type SessionCompactionEvent = z.infer<typeof SessionCompactionEventSchema>;
+
+// ---- turn events ------------------------------------------------------------
+
 export const TurnStartedEventSchema = z.object({
 	type: z.literal("turn.started"),
-	turnId: z.string(),
 	sessionId: z.string(),
-	timestamp: z.number(),
+	turnId: z.string(),
+	timestamp: EpochMsSchema,
+	_meta: MetaSchema,
 });
 export type TurnStartedEvent = z.infer<typeof TurnStartedEventSchema>;
 
+export const TurnEndedEventSchema = z.object({
+	type: z.literal("turn.ended"),
+	sessionId: z.string(),
+	turnId: z.string(),
+	/** Normalized terminal status — `cancelled` and `error` are first-class. */
+	stopReason: StopReasonSchema,
+	/** Raw provider finish string (`end_turn`, `completed`, …), always preserved when reported. */
+	finishReason: z.string().optional(),
+	/** The turn's BILLING total (never the context gauge — that is session.usage). */
+	tokens: TokenUsageSchema.optional(),
+	/** USD for this turn, when reported. */
+	cost: z.number().optional(),
+	/** Present when stopReason === "error". */
+	error: ErrorInfoSchema.optional(),
+	timestamp: EpochMsSchema,
+	_meta: MetaSchema,
+});
+export type TurnEndedEvent = z.infer<typeof TurnEndedEventSchema>;
+
+// ---- message + part events --------------------------------------------------
+
 export const MessageStartedEventSchema = z.object({
 	type: z.literal("message.started"),
+	sessionId: z.string(),
 	turnId: z.string(),
 	messageId: z.string(),
+	/** Position of this message within the turn. The user echo is 0; assistant messages are 1..n. */
 	outputIndex: z.number(),
 	role: z.enum(["user", "assistant"]),
 	/**
@@ -75,36 +208,37 @@ export const MessageStartedEventSchema = z.object({
 	 * 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(),
+	parentToolCallId: z.string().optional(),
+	model: z.string().optional(),
+	timestamp: EpochMsSchema,
+	_meta: MetaSchema,
 });
 export type MessageStartedEvent = z.infer<typeof MessageStartedEventSchema>;
 
-/** A fully-formed (or newly-finalized) part snapshot. Upsert by `part.id`. */
+/**
+ * A full part snapshot. UPSERT by `part.id` — authoritative, idempotent,
+ * re-delivery-safe. Full-snapshot semantics, never field patches: "clear a
+ * field" = omit it from the next snapshot.
+ */
 export const MessagePartEventSchema = z.object({
 	type: z.literal("message.part"),
+	sessionId: z.string(),
 	turnId: z.string(),
 	messageId: z.string(),
 	outputIndex: z.number(),
+	/** Position of this part within its message — persist as the ordering key. */
 	partIndex: z.number(),
 	part: PartSchema,
-	parentToolUseId: z.string().optional(),
-	timestamp: z.number(),
+	timestamp: EpochMsSchema,
+	_meta: MetaSchema,
 });
 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("text"), text: z.string() }),
+	z.object({ type: z.literal("reasoning"), text: z.string() }),
 	z.object({
-		type: z.literal("tool-input-delta"),
+		type: z.literal("tool_input"),
 		toolCallId: z.string(),
 		toolName: z.string(),
 		input: z.string(),
@@ -112,103 +246,47 @@ export const DeltaSchema = z.discriminatedUnion("type", [
 ]);
 export type Delta = z.infer<typeof DeltaSchema>;
 
-/** An incremental update to a streaming part (text/reasoning/tool-input). */
+/**
+ * An additive streaming aid for a streaming part field. Advisory: snapshots
+ * are authoritative and wipe accumulated deltas. Deltas are NON-DURABLE —
+ * `events/replay` may omit them; snapshots fully reconstruct state.
+ */
 export const MessagePartDeltaEventSchema = z.object({
 	type: z.literal("message.part.delta"),
+	sessionId: z.string(),
 	turnId: z.string(),
 	messageId: z.string(),
 	outputIndex: z.number(),
 	partIndex: z.number(),
 	partId: z.string(),
 	delta: DeltaSchema,
-	parentToolUseId: z.string().optional(),
-	timestamp: z.number(),
+	timestamp: EpochMsSchema,
+	_meta: MetaSchema,
 });
 export type MessagePartDeltaEvent = z.infer<typeof MessagePartDeltaEventSchema>;
 
+/** Bracket marker ONLY — billing lives on turn.ended, never here. */
 export const MessageEndedEventSchema = z.object({
 	type: z.literal("message.ended"),
+	sessionId: z.string(),
 	turnId: z.string(),
 	messageId: z.string(),
-	timestamp: z.number(),
+	timestamp: EpochMsSchema,
+	_meta: MetaSchema,
 });
 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([
+/** OPEN (Law 3) — but unknown outcomes/kinds MUST be handled conservatively: never treated as approval. */
+export const PERMISSION_OPTION_KINDS = [
 	"allow_once",
 	"allow_always",
 	"reject_once",
 	"reject_always",
-]);
-export type PermissionOptionKind = z.infer<typeof PermissionOptionKindSchema>;
+] as const;
+export type PermissionOptionKind = (typeof PERMISSION_OPTION_KINDS)[number] | (string & {});
+export const PermissionOptionKindSchema = openVocabulary<PermissionOptionKind>();
 
 export const PermissionOptionSchema = z.object({
 	optionId: z.string(),
@@ -234,7 +312,16 @@ export const PermissionToolCallSchema = z.object({
 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("selected"),
+		optionId: z.string(),
+		/**
+		 * Allow-with-modified-input. Without this, products bypass the broker
+		 * entirely (Claude's canUseTool supports it; ACP v1's outcome could not
+		 * carry it).
+		 */
+		updatedInput: z.record(z.string(), z.unknown()).optional(),
+	}),
 	z.object({ outcome: z.literal("cancelled") }),
 ]);
 export type PermissionOutcome = z.infer<typeof PermissionOutcomeSchema>;
@@ -243,6 +330,8 @@ 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.
+ * `options` is THE source of buttons — clients render the server's list,
+ * never derive affordances from local policy.
  */
 export const PermissionRequestedEventSchema = z.object({
 	type: z.literal("permission.requested"),
@@ -258,28 +347,48 @@ export const PermissionRequestedEventSchema = z.object({
 	 */
 	toolCall: PermissionToolCallSchema.optional(),
 	options: z.array(PermissionOptionSchema),
-	timestamp: z.number(),
+	timestamp: EpochMsSchema,
+	_meta: MetaSchema,
 });
 export type PermissionRequestedEvent = z.infer<typeof PermissionRequestedEventSchema>;
 
-/** A pending permission request was answered (or cancelled). */
+/** A pending permission request was answered (or cancelled). Resolves exactly once. */
 export const PermissionResolvedEventSchema = z.object({
 	type: z.literal("permission.resolved"),
 	sessionId: z.string(),
 	turnId: z.string(),
 	requestId: z.string(),
 	outcome: PermissionOutcomeSchema,
-	timestamp: z.number(),
+	timestamp: EpochMsSchema,
+	_meta: MetaSchema,
 });
 export type PermissionResolvedEvent = z.infer<typeof PermissionResolvedEventSchema>;
 
-// ---- raw passthrough ---------------------------------------------------------
+// ---- error + raw ------------------------------------------------------------
+
+export const ErrorEventSchema = z.object({
+	type: z.literal("error"),
+	/** Absent only for pre-session failures. */
+	sessionId: z.string().optional(),
+	turnId: z.string().optional(),
+	category: ErrorCategorySchema,
+	message: z.string(),
+	/**
+	 * true = the turn continues (retry/backoff in flight). Consumers MUST NOT
+	 * flip UI to an error state on recoverable errors — surface as diagnostics.
+	 */
+	recoverable: z.boolean(),
+	stack: z.string().optional(),
+	timestamp: EpochMsSchema,
+	_meta: MetaSchema,
+});
+export type ErrorEvent = z.infer<typeof ErrorEventSchema>;
 
 /**
  * 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.
+ * interleaved with the normalized stream. Escape hatch for debugging and
+ * fixture recording — `data` carries NO stability guarantees and is not part
+ * of the contract. Building a product pipeline on `raw` is a bug.
  */
 export const RawEventSchema = z.object({
 	type: z.literal("raw"),
@@ -287,12 +396,16 @@ export const RawEventSchema = z.object({
 	turnId: z.string(),
 	harness: AgentHarnessSchema,
 	data: z.unknown(),
-	timestamp: z.number(),
+	timestamp: EpochMsSchema,
+	_meta: MetaSchema,
 });
 export type RawEvent = z.infer<typeof RawEventSchema>;
 
+// ---- the union --------------------------------------------------------------
+
 export const LifecycleEventSchema = z.discriminatedUnion("type", [
 	SessionCreatedEventSchema,
+	SessionEndedEventSchema,
 	TurnStartedEventSchema,
 	MessageStartedEventSchema,
 	MessagePartEventSchema,
@@ -300,10 +413,74 @@ export const LifecycleEventSchema = z.discriminatedUnion("type", [
 	MessageEndedEventSchema,
 	TurnEndedEventSchema,
 	SessionUsageEventSchema,
-	SessionCompactedEventSchema,
+	SessionCompactionEventSchema,
 	ErrorEventSchema,
 	PermissionRequestedEventSchema,
 	PermissionResolvedEventSchema,
 	RawEventSchema,
 ]);
 export type LifecycleEvent = z.infer<typeof LifecycleEventSchema>;
+
+/**
+ * Law 6 — tolerant of the unknown, strict about the known: an event with an
+ * unknown `type` is preserved (in order, never dropped) as an UnknownEvent;
+ * a KNOWN type with a malformed body is a hard error.
+ */
+export interface UnknownEvent {
+	type: string & {};
+	sessionId?: string;
+	raw: Record<string, unknown>;
+}
+
+/**
+ * A `message.part` whose part may be an `UnknownPart`: the event envelope is
+ * protocol-owned (strict), the part inside it is not (Law 6).
+ */
+export interface DecodedMessagePartEvent extends Omit<MessagePartEvent, "part"> {
+	part: Part | UnknownPart;
+}
+
+/**
+ * What a Law-6 decoder yields for a KNOWN event type. Identical to
+ * `LifecycleEvent` except that `message.part` may carry an unknown part — so
+ * every `LifecycleEvent` is a `DecodedLifecycleEvent`, and consumers that
+ * accept this type accept both.
+ */
+export type DecodedLifecycleEvent =
+	| Exclude<LifecycleEvent, MessagePartEvent>
+	| DecodedMessagePartEvent;
+
+/** The `message.part` envelope without its part — decoded separately, leniently. */
+const MessagePartEnvelopeSchema = MessagePartEventSchema.omit({ part: true });
+
+/**
+ * Decode a wire value into a LifecycleEvent, preserving unknown event types
+ * (and unknown PART types inside `message.part`) instead of dropping them.
+ * Throws on a known type with a malformed body.
+ *
+ * This is the decoder every wire consumer should use — dropping an event a
+ * newer server sent is not a graceful degradation, it is a hole in the
+ * transcript and, for a seq-tracking client, a fabricated gap.
+ */
+export function decodeLifecycleEvent(value: unknown): DecodedLifecycleEvent | UnknownEvent {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		throw new Error("lifecycle event must be an object");
+	}
+	const record = value as Record<string, unknown>;
+	const type = record.type;
+	if (typeof type !== "string" || type.length === 0) {
+		throw new Error("lifecycle event is missing its type");
+	}
+	if (!isKnownLifecycleEventType(type)) {
+		const sessionId = typeof record.sessionId === "string" ? record.sessionId : undefined;
+		return { type, ...(sessionId !== undefined ? { sessionId } : {}), raw: record };
+	}
+	if (type === "message.part") {
+		return { ...MessagePartEnvelopeSchema.parse(record), part: decodePart(record.part) };
+	}
+	return LifecycleEventSchema.parse(value);
+}
+
+// `LIFECYCLE_EVENT_TYPES`, `isKnownLifecycleEventType` and `isUnknownEvent`
+// live in `./guards.ts` — same exports from the barrel, but reachable without
+// loading zod.

package/src/protocol/meta.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+/**
+ * The extension slot (Law 4 — ACP pattern): present on every event, part,
+ * tool state, and result-content item. Adapters and products MUST NOT add
+ * root-level fields to canonical types — all root names are reserved for
+ * future protocol versions; extensions live here under namespaced keys
+ * (`deus/...`, `agnt/...`).
+ *
+ * Reserved keys (W3C trace context, MCP-compatible): `traceparent`,
+ * `tracestate`, `baggage`.
+ */
+export const MetaSchema = z.record(z.string(), z.unknown()).optional();
+export type Meta = Record<string, unknown>;

package/src/protocol/part-input.ts

@@ -1,10 +1,31 @@
 import { z } from "zod";
 
+/**
+ * A UI-authored span over the text (mentions, pills, inline references) that
+ * survives the round trip through the model, the user echo, and persistence.
+ * The model sees plain text; `byteRange` is [start, end) over the UTF-8 bytes
+ * of the parent `text`.
+ */
+export const TextElementSchema = z.object({
+	byteRange: z
+		.tuple([z.number().int().nonnegative(), z.number().int().nonnegative()])
+		.refine(([start, end]) => start <= end, {
+			// A reversed range would survive the echo and persistence, and every
+			// consumer slicing with it would render an empty or wrong span with
+			// the producer bug invisible — reject it at the boundary.
+			message: "byteRange must be ordered: start <= end",
+		}),
+	/** Human-readable placeholder for the element, displayed in the UI. */
+	placeholder: z.string().optional(),
+});
+export type TextElement = z.infer<typeof TextElementSchema>;
+
 /** 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),
+	elements: z.array(TextElementSchema).optional(),
 });
 export type TextPartInput = z.infer<typeof TextPartInputSchema>;
 
@@ -15,11 +36,15 @@ export const ImagePartInputSchema = z
 		/** 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(),
+		mimeType: z.string(),
+		// No `filename` here: ImagePartSchema has no such field, so accepting it
+		// would validate a value the echo then silently drops (Law 7).
 	})
-	.refine((part) => part.url !== undefined || part.data !== undefined, {
-		message: "image input requires a non-empty url or data payload",
+	.refine((part) => (part.data !== undefined) !== (part.url !== undefined), {
+		// Exactly one, matching the OUTPUT part schemas' `exactlyOneSource`: an
+		// input carrying both would echo as a part every consumer's decode
+		// rejects — the ambiguity dies at the boundary, not on the stream.
+		message: "image input requires exactly one of data | url",
 	});
 export type ImagePartInput = z.infer<typeof ImagePartInputSchema>;
 
@@ -29,11 +54,11 @@ export const FilePartInputSchema = z
 		id: z.string().optional(),
 		url: z.string().min(1).optional(),
 		data: z.string().min(1).optional(),
-		mediaType: z.string(),
+		mimeType: 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",
+	.refine((part) => (part.data !== undefined) !== (part.url !== undefined), {
+		message: "file input requires exactly one of data | url",
 	});
 export type FilePartInput = z.infer<typeof FilePartInputSchema>;
 
@@ -48,6 +73,30 @@ export type PartInput = z.infer<typeof PartInputSchema>;
 export const AgentInputSchema = z.union([z.string(), z.array(PartInputSchema)]);
 export type AgentInput = z.infer<typeof AgentInputSchema>;
 
+/**
+ * Decode an untrusted value (an HTTP body, a queue message, a DB column) into
+ * an `AgentInput`, or throw with a message that names the offending path.
+ *
+ * The schema is the contract; a hand-rolled decoder in front of it is where
+ * tolerance for shapes the engine never accepted creeps in (`content` arrays,
+ * bare `{text}` objects) and where the error a product shows its user
+ * degrades to "invalid input". (An empty STRING is valid input — deliberately:
+ * "continue" semantics belong to the product, not the schema.)
+ */
+export function parseAgentInput(value: unknown): AgentInput {
+	const parsed = AgentInputSchema.safeParse(value);
+	if (parsed.success) return parsed.data;
+	// A union failure's own message is just "Invalid input" — the useful paths
+	// and messages live one level down, in the per-branch issue lists.
+	const flattened = parsed.error.issues.flatMap((issue) =>
+		issue.code === "invalid_union" ? issue.errors.flat() : [issue],
+	);
+	const detail = flattened
+		.map((issue) => `${issue.path.length ? `${issue.path.join(".")}: ` : ""}${issue.message}`)
+		.join("; ");
+	throw new Error(`invalid agent input: ${detail}`, { cause: parsed.error });
+}
+
 /** Collapse an AgentInput down to the text the model sees first. */
 export function inputToText(input: AgentInput): string {
 	if (typeof input === "string") return input;