@zvada/agent-server 0.2.2 → 0.3.0

package/src/protocol/parts.ts

@@ -1,21 +1,34 @@
 import { z } from "zod";
+import { isKnownPartType } from "./guards.ts";
+import { MetaSchema } from "./meta.ts";
+import { OpenTimeSpanSchema } from "./time.ts";
 import { ToolKindSchema, ToolLocationSchema, ToolStateSchema } from "./tool-state.ts";
 
 /**
- * A Part is the atomic unit of assistant output, normalized across harnesses.
+ * A Part is the atomic unit of message content, 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.
+ * through the tool lifecycle. `parentToolCallId` links a part produced inside
+ * a sub-agent / nested tool execution back to the tool call that spawned it.
+ *
+ * Parts carry NO ordering fields — position is the event's knowledge
+ * (`partIndex`/`outputIndex` on message.* events); a part re-stated late (a
+ * tool completing after its message ended) must not be able to contradict its
+ * own position.
  *
  * Rule: this union contains only part types adapters actually emit — the
- * protocol advertises nothing it doesn't deliver.
+ * protocol advertises nothing it doesn't deliver. There is deliberately no
+ * compaction part (compaction is the `session.compaction` entity) and no
+ * step/turn-mechanics part (mechanics live in events).
  */
 const PartBase = z.object({
+	/** UUIDv7 — THE upsert key. */
 	id: z.string(),
 	sessionId: z.string(),
 	messageId: z.string(),
-	parentToolUseId: z.string().optional(),
+	/** Set when this part was produced inside the subagent spawned by that tool call. */
+	parentToolCallId: z.string().optional(),
+	_meta: MetaSchema,
 });
 
 export const TextPartSchema = PartBase.extend({
@@ -29,32 +42,134 @@ export const ReasoningPartSchema = PartBase.extend({
 	type: z.literal("reasoning"),
 	text: z.string(),
 	state: z.enum(["streaming", "done"]).optional(),
+	/** Thought duration, when the adapter can stamp it (deus renders it). */
+	time: OpenTimeSpanSchema.optional(),
+	/** Harness extras — e.g. `{ redacted: true }` for Claude redacted_thinking. */
 	providerMetadata: z.record(z.string(), z.unknown()).optional(),
 });
 export type ReasoningPart = z.infer<typeof ReasoningPartSchema>;
 
+/**
+ * Metadata about the subagent a `task`-kind tool spawned, populated from the
+ * spawning tool's input (Claude `Task`: description/subagent_type/model).
+ * `agentId` is the harness-native id — the only reliable way to attribute
+ * PARALLEL subagents. Presence of `subagent` implies `kind: "task"`; tool-name
+ * allowlists are forbidden.
+ */
+export const SubagentMetadataSchema = z.object({
+	type: z.string().optional(),
+	description: z.string().optional(),
+	model: z.string().optional(),
+	agentId: z.string().optional(),
+});
+export type SubagentMetadata = z.infer<typeof SubagentMetadataSchema>;
+
 export const ToolPartSchema = PartBase.extend({
 	type: z.literal("tool"),
 	toolCallId: z.string(),
-	/** Provider-native tool name (`Bash`, `shell`, `mcp.search`, …). */
+	/** Provider-native tool name (`Bash`, `shell`, `mcp.search`, …) — the renderer dispatch key. */
 	toolName: z.string(),
-	/** Normalized classification of what the call does (ACP ToolKind). */
+	/** Normalized classification of what the call does (ACP ToolKind + `task`). */
 	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(),
+	/** Present when this tool spawned a subagent (implies kind "task"). */
+	subagent: SubagentMetadataSchema.optional(),
 	state: ToolStateSchema,
 });
 export type ToolPart = z.infer<typeof ToolPartSchema>;
 
+/**
+ * Exactly one of `data` (base64) | `url` — ENFORCED, not merely documented: a
+ * payload-less blob part renders as a broken image, and one carrying both
+ * leaves every consumer to invent its own precedence rule.
+ */
+const exactlyOneSource = (part: { data?: string; url?: string }) =>
+	(part.data !== undefined) !== (part.url !== undefined);
+
+/** Exactly one of `data` (base64) | `url`. Emitted by the user echo and image tool results. */
+export const ImagePartSchema = PartBase.extend({
+	type: z.literal("image"),
+	data: z.string().min(1).optional(),
+	url: z.string().min(1).optional(),
+	mimeType: z.string(),
+}).refine(exactlyOneSource, { message: "image part requires exactly one of data | url" });
+export type ImagePart = z.infer<typeof ImagePartSchema>;
+
+/** Exactly one of `data` (base64) | `url`. Emitted by the user echo. */
+export const FilePartSchema = PartBase.extend({
+	type: z.literal("file"),
+	data: z.string().min(1).optional(),
+	url: z.string().min(1).optional(),
+	mimeType: z.string(),
+	filename: z.string().optional(),
+}).refine(exactlyOneSource, { message: "file part requires exactly one of data | url" });
+export type FilePart = z.infer<typeof FilePartSchema>;
+
 export const PartSchema = z.discriminatedUnion("type", [
 	TextPartSchema,
 	ReasoningPartSchema,
 	ToolPartSchema,
+	ImagePartSchema,
+	FilePartSchema,
 ]);
 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";
+/**
+ * Law 6 — tolerant of the unknown, strict about the known: an unknown part
+ * type is preserved, in order, never dropped. A KNOWN type with a malformed
+ * body is a hard error (never wrapped as unknown).
+ */
+export interface UnknownPart {
+	type: string & {};
+	id: string;
+	sessionId: string;
+	messageId: string;
+	parentToolCallId?: string;
+	raw: Record<string, unknown>;
+	_meta?: Record<string, unknown>;
+}
+
+/**
+ * Decode a wire value into a Part, preserving unknown part types instead of
+ * failing the whole event that carries them (Law 6 is a STORAGE and FORWARDING
+ * requirement — a newer server's part type must survive a round trip through
+ * an older consumer). Throws on a known type with a malformed body, and on an
+ * unknown part that lacks the addressing fields every part owns: without
+ * `id`/`sessionId`/`messageId` there is nothing to upsert by, so it cannot be
+ * preserved in any useful sense.
+ */
+export function decodePart(value: unknown): Part | UnknownPart {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		throw new Error("part must be an object");
+	}
+	const record = value as Record<string, unknown>;
+	if (isKnownPartType(record.type)) return PartSchema.parse(value);
+	const { type, id, sessionId, messageId, parentToolCallId } = record;
+	if (typeof type !== "string" || type.length === 0) {
+		throw new Error("part is missing its type");
+	}
+	if (typeof id !== "string" || typeof sessionId !== "string" || typeof messageId !== "string") {
+		throw new Error(`unknown part type "${type}" is missing its id/sessionId/messageId address`);
+	}
+	const meta = record._meta;
+	return {
+		type,
+		id,
+		sessionId,
+		messageId,
+		...(typeof parentToolCallId === "string" ? { parentToolCallId } : {}),
+		// Law 4 puts extensions in `_meta` on every shape — surface it on the
+		// preserved part too, so a consumer reading `part._meta` does not need
+		// to know to dig through `raw` for it.
+		...(meta !== null && typeof meta === "object" && !Array.isArray(meta)
+			? { _meta: meta as Record<string, unknown> }
+			: {}),
+		raw: record,
+	};
+}
+
+// `PART_TYPES`, `isKnownPartType` and `isUnknownPart` live in `./guards.ts` —
+// same exports from the barrel, but reachable without loading zod.