@gajae-code/coding-agent 0.3.1 → 0.4.0

package/src/modes/shared/agent-wire/workflow-gate-broker.ts

@@ -0,0 +1,324 @@
+/**
+ * Durable workflow gate broker (#315).
+ *
+ * Owns gate identity and lifecycle for one run:
+ *  - run-scoped, monotonic, stable gate ids
+ *  - pending gate persisted BEFORE it is emitted
+ *  - resolution persisted BEFORE the workflow is allowed to advance
+ *  - response-body hash + idempotency-key rules (cached replay, conflict detection)
+ *  - exactly-once advance + audit
+ *
+ * Persistence is injected via {@link GateStore}; the in-memory store is used in
+ * tests, the file-backed store gives crash-durable behavior for real runs.
+ */
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+import type {
+	RpcWorkflowGate,
+	RpcWorkflowGateContext,
+	RpcWorkflowGateKind,
+	RpcWorkflowGateOption,
+	RpcWorkflowGateResolution,
+	RpcWorkflowGateResponse,
+	RpcWorkflowStage,
+} from "../../rpc/rpc-types";
+import { RESERVED_WORKFLOW_STAGES } from "../../rpc/rpc-types";
+import { answerHashOf, canonicalJson, compileGateSchema, schemaHash, validateGateAnswer } from "./workflow-gate-schema";
+
+const V1_STAGES: readonly RpcWorkflowStage[] = ["deep-interview", "ralplan", "ultragoal"];
+
+export interface PersistedGate {
+	gate: RpcWorkflowGate;
+	status: "pending" | "accepted";
+	idempotencyKey?: string;
+	responseHash?: string;
+	/** Raw accepted answer, retained so a crashed advance can be replayed. */
+	answer?: unknown;
+	resolution?: RpcWorkflowGateResolution;
+	advanced: boolean;
+}
+
+export interface GateStore {
+	nextSeq(stage: RpcWorkflowStage): number;
+	put(record: PersistedGate): void;
+	get(gateId: string): PersistedGate | undefined;
+	/** All persisted gate records (used for crash recovery). */
+	list(): PersistedGate[];
+}
+
+export class MemoryGateStore implements GateStore {
+	private counters = new Map<RpcWorkflowStage, number>();
+	private gates = new Map<string, PersistedGate>();
+
+	nextSeq(stage: RpcWorkflowStage): number {
+		const next = (this.counters.get(stage) ?? 0) + 1;
+		this.counters.set(stage, next);
+		return next;
+	}
+	put(record: PersistedGate): void {
+		this.gates.set(record.gate.gate_id, structuredClone(record));
+	}
+	get(gateId: string): PersistedGate | undefined {
+		const r = this.gates.get(gateId);
+		return r ? structuredClone(r) : undefined;
+	}
+	list(): PersistedGate[] {
+		return [...this.gates.values()].map(r => structuredClone(r));
+	}
+}
+
+interface FileState {
+	counters: Record<string, number>;
+	gates: Record<string, PersistedGate>;
+}
+
+/** Crash-durable JSON-file backed store. Writes the full state on every mutation. */
+export class FileGateStore implements GateStore {
+	private state: FileState;
+	constructor(private readonly filePath: string) {
+		mkdirSync(path.dirname(filePath), { recursive: true });
+		this.state = this.load();
+	}
+	private load(): FileState {
+		let raw: string;
+		try {
+			raw = readFileSync(this.filePath, "utf8");
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code === "ENOENT") return { counters: {}, gates: {} };
+			throw err;
+		}
+		try {
+			return JSON.parse(raw) as FileState;
+		} catch (err) {
+			// Fail closed: a corrupt state file must not be silently reset (that would
+			// drop counters/gates and risk gate-id reuse). Quarantine + throw.
+			const quarantine = `${this.filePath}.corrupt-${Date.now()}`;
+			try {
+				renameSync(this.filePath, quarantine);
+			} catch {
+				/* best-effort quarantine */
+			}
+			throw new Error(
+				`corrupt gate store at ${this.filePath} (quarantined to ${quarantine}): ${(err as Error).message}`,
+			);
+		}
+	}
+	private flush(): void {
+		// Atomic write: serialize to a temp file, fsync, then rename over the target.
+		const tmp = `${this.filePath}.tmp-${process.pid}-${Date.now()}`;
+		const fd = openSync(tmp, "w");
+		try {
+			writeFileSync(fd, JSON.stringify(this.state, null, 2));
+			fsyncSync(fd);
+		} finally {
+			closeSync(fd);
+		}
+		renameSync(tmp, this.filePath);
+	}
+	nextSeq(stage: RpcWorkflowStage): number {
+		const next = (this.state.counters[stage] ?? 0) + 1;
+		this.state.counters[stage] = next;
+		this.flush();
+		return next;
+	}
+	put(record: PersistedGate): void {
+		this.state.gates[record.gate.gate_id] = record;
+		this.flush();
+	}
+	get(gateId: string): PersistedGate | undefined {
+		const r = this.state.gates[gateId];
+		return r ? (JSON.parse(JSON.stringify(r)) as PersistedGate) : undefined;
+	}
+	list(): PersistedGate[] {
+		return Object.values(this.state.gates).map(r => JSON.parse(JSON.stringify(r)) as PersistedGate);
+	}
+}
+
+export type GateAuditEvent =
+	| { event: "gate_emitted"; gate_id: string; stage: RpcWorkflowStage; kind: RpcWorkflowGateKind }
+	| { event: "gate_response_accepted"; gate_id: string; answer_hash: string }
+	| { event: "gate_response_rejected"; gate_id: string; answer_hash: string }
+	| { event: "gate_response_idempotent_replay"; gate_id: string }
+	| { event: "gate_response_idempotency_conflict"; gate_id: string }
+	| { event: "gate_response_already_resolved"; gate_id: string }
+	| { event: "gate_response_unknown_gate"; gate_id: string }
+	| { event: "gate_advance_recovered"; gate_id: string };
+
+export interface BrokerHooks {
+	/** Called once when a pending gate has been persisted and should be emitted. */
+	emit?(gate: RpcWorkflowGate): void;
+	/**
+	 * Invoked to advance the workflow after an accepted resolution is durably
+	 * committed. MUST be idempotent keyed by `gate.gate_id`: `recover()` replays
+	 * it for any gate left `accepted` but not `advanced` by a crash.
+	 */
+	advance?(gate: RpcWorkflowGate, answer: unknown): void | Promise<void>;
+	/** Append-only audit sink. */
+	audit?(event: GateAuditEvent): void;
+}
+
+export interface OpenGateInput {
+	stage: RpcWorkflowStage;
+	kind: RpcWorkflowGateKind;
+	schema: RpcWorkflowGate["schema"];
+	options?: RpcWorkflowGateOption[];
+	context?: RpcWorkflowGateContext;
+}
+
+export class WorkflowGateBrokerError extends Error {
+	constructor(
+		readonly code: "unknown_gate" | "already_resolved" | "idempotency_conflict" | "invalid_workflow_stage",
+		message: string,
+	) {
+		super(message);
+		this.name = "WorkflowGateBrokerError";
+	}
+}
+
+export class WorkflowGateBroker {
+	constructor(
+		private readonly runId: string,
+		private readonly store: GateStore,
+		private readonly hooks: BrokerHooks = {},
+	) {}
+
+	private runShort(): string {
+		return this.runId.replace(/[^a-zA-Z0-9]/g, "").slice(-8) || "run";
+	}
+
+	/** Open and emit a gate. The pending record is persisted BEFORE emission. */
+	openGate(input: OpenGateInput): RpcWorkflowGate {
+		if (RESERVED_WORKFLOW_STAGES.includes(input.stage) || !V1_STAGES.includes(input.stage)) {
+			throw new WorkflowGateBrokerError(
+				"invalid_workflow_stage",
+				`stage "${input.stage}" is not a v1 workflow stage`,
+			);
+		}
+		// Asserts schema shape (throws WorkflowGateSchemaError on unsupported keywords).
+		compileGateSchema(input.schema);
+		const seq = this.store.nextSeq(input.stage).toString().padStart(6, "0");
+		const gateId = `wg_${this.runShort()}_${input.stage}_${seq}`;
+		const gate: RpcWorkflowGate = {
+			type: "workflow_gate",
+			gate_id: gateId,
+			stage: input.stage,
+			kind: input.kind,
+			schema: input.schema,
+			schema_hash: schemaHash(input.schema),
+			options: input.options,
+			context: input.context ?? {},
+			created_at: new Date().toISOString(),
+			required: true,
+		};
+		// Persist pending BEFORE emit so a crash never loses an emitted gate.
+		this.store.put({ gate, status: "pending", advanced: false });
+		this.hooks.emit?.(gate);
+		this.hooks.audit?.({ event: "gate_emitted", gate_id: gateId, stage: gate.stage, kind: gate.kind });
+		return gate;
+	}
+
+	/**
+	 * Resolve a gate with an answer. Validates against the advertised schema.
+	 * On success the resolution is persisted BEFORE `advance` is invoked exactly
+	 * once. Invalid answers leave the gate pending (per #315 acceptance).
+	 */
+	async resolve(response: RpcWorkflowGateResponse): Promise<RpcWorkflowGateResolution> {
+		const record = this.store.get(response.gate_id);
+		if (!record) {
+			this.hooks.audit?.({ event: "gate_response_unknown_gate", gate_id: response.gate_id });
+			throw new WorkflowGateBrokerError("unknown_gate", `no pending gate ${response.gate_id}`);
+		}
+		const responseHash = answerHashOf({ gate_id: response.gate_id, answer: response.answer });
+
+		if (record.status === "accepted") {
+			const sameBody = record.responseHash === responseHash;
+			const sameKey = record.idempotencyKey === response.idempotency_key;
+			if (response.idempotency_key !== undefined && sameKey && sameBody) {
+				this.hooks.audit?.({ event: "gate_response_idempotent_replay", gate_id: response.gate_id });
+				return record.resolution as RpcWorkflowGateResolution;
+			}
+			if (response.idempotency_key !== undefined && sameKey && !sameBody) {
+				this.hooks.audit?.({ event: "gate_response_idempotency_conflict", gate_id: response.gate_id });
+				throw new WorkflowGateBrokerError(
+					"idempotency_conflict",
+					`idempotency_conflict: gate ${response.gate_id} resolved with a different body`,
+				);
+			}
+			this.hooks.audit?.({ event: "gate_response_already_resolved", gate_id: response.gate_id });
+			throw new WorkflowGateBrokerError("already_resolved", `already_resolved: gate ${response.gate_id}`);
+		}
+
+		const compiled = compileGateSchema(record.gate.schema);
+		const validationError = validateGateAnswer(compiled, response.gate_id, response.answer);
+		const answerHash = answerHashOf(response.answer);
+		if (validationError) {
+			// Leave the gate pending so the agent can retry with a valid answer.
+			this.hooks.audit?.({ event: "gate_response_rejected", gate_id: response.gate_id, answer_hash: answerHash });
+			return {
+				gate_id: response.gate_id,
+				status: "rejected",
+				answer_hash: answerHash,
+				resolved_at: new Date().toISOString(),
+				error: validationError,
+			};
+		}
+
+		const resolution: RpcWorkflowGateResolution = {
+			gate_id: response.gate_id,
+			status: "accepted",
+			answer_hash: answerHash,
+			resolved_at: new Date().toISOString(),
+		};
+		// Persist resolution BEFORE advancing the workflow (exactly-once advance).
+		// `answer` is retained so a crash before the advanced:true write can be
+		// recovered via recover().
+		this.store.put({
+			gate: record.gate,
+			status: "accepted",
+			idempotencyKey: response.idempotency_key,
+			responseHash,
+			answer: response.answer,
+			resolution,
+			advanced: false,
+		});
+		this.hooks.audit?.({ event: "gate_response_accepted", gate_id: response.gate_id, answer_hash: answerHash });
+		await this.hooks.advance?.(record.gate, response.answer);
+		this.store.put({
+			gate: record.gate,
+			status: "accepted",
+			idempotencyKey: response.idempotency_key,
+			responseHash,
+			answer: response.answer,
+			resolution,
+			advanced: true,
+		});
+		return resolution;
+	}
+
+	/**
+	 * Recover any gate left `accepted` but not `advanced` by a crash between the
+	 * durable accept and the advanced commit. Replays `advance` (which must be
+	 * idempotent) exactly once per gate and marks it advanced. Returns the ids
+	 * that were recovered.
+	 */
+	async recover(): Promise<string[]> {
+		const recovered: string[] = [];
+		for (const listed of this.store.list()) {
+			if (listed.status !== "accepted" || listed.advanced) continue;
+			// Re-read immediately before advancing so a concurrent recoverer that
+			// already advanced this gate (stale snapshot) cannot double-advance.
+			const rec = this.store.get(listed.gate.gate_id);
+			if (rec?.status !== "accepted" || rec.advanced) continue;
+			await this.hooks.advance?.(rec.gate, rec.answer);
+			this.store.put({ ...rec, advanced: true });
+			this.hooks.audit?.({ event: "gate_advance_recovered", gate_id: rec.gate.gate_id });
+			recovered.push(rec.gate.gate_id);
+		}
+		return recovered;
+	}
+
+	/** Canonical serialization helper (exposed for callers/tests). */
+	static canonical(value: unknown): string {
+		return canonicalJson(value);
+	}
+}

package/src/modes/shared/agent-wire/workflow-gate-schema.ts

@@ -0,0 +1,331 @@
+/**
+ * Workflow gate answer-schema wrapper (#315).
+ *
+ * Validates gate answers against the JSON Schema advertised with each
+ * `workflow_gate` event. The dialect is a documented, constrained subset of
+ * JSON Schema 2020-12. Schemas are checked for shape (supported keywords, size,
+ * depth) at gate-construction time so the server never advertises a schema it
+ * cannot validate; compiled validators are cached by canonical schema hash.
+ *
+ * The validation internals are intentionally isolated behind {@link compileGateSchema}
+ * and {@link validateGateAnswer} so a full JSON Schema engine (e.g. Ajv) can be
+ * swapped in later without changing callers.
+ */
+import { createHash } from "node:crypto";
+import type { RpcJsonSchema, RpcWorkflowGateValidationError } from "../../rpc/rpc-types";
+
+/** Keywords this wrapper understands. Any other keyword is rejected. */
+const SUPPORTED_KEYWORDS = new Set<keyof RpcJsonSchema>([
+	"type",
+	"enum",
+	"const",
+	"properties",
+	"required",
+	"additionalProperties",
+	"items",
+	"minLength",
+	"maxLength",
+	"minItems",
+	"maxItems",
+	"uniqueItems",
+	"minimum",
+	"maximum",
+	"title",
+	"description",
+	"oneOf",
+	"anyOf",
+]);
+
+const SUPPORTED_TYPES = new Set(["string", "number", "integer", "boolean", "object", "array", "null"]);
+
+export const GATE_SCHEMA_LIMITS = {
+	maxSchemaBytes: 64 * 1024,
+	maxDepth: 16,
+	maxProperties: 256,
+	maxEnumValues: 512,
+	maxAnswerBytes: 256 * 1024,
+} as const;
+
+/** Thrown at gate construction when a schema is unsupported or too large. */
+export class WorkflowGateSchemaError extends Error {
+	readonly code = "invalid_workflow_gate_schema";
+	constructor(message: string) {
+		super(message);
+		this.name = "WorkflowGateSchemaError";
+	}
+}
+
+/** Canonical (stable-key-ordered) JSON serialization used for hashing. */
+export function canonicalJson(value: unknown): string {
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	const keys = Object.keys(value as Record<string, unknown>).sort();
+	const entries = keys.map(k => `${JSON.stringify(k)}:${canonicalJson((value as Record<string, unknown>)[k])}`);
+	return `{${entries.join(",")}}`;
+}
+
+export function schemaHash(schema: RpcJsonSchema): string {
+	return createHash("sha256").update(canonicalJson(schema)).digest("hex");
+}
+
+function answerHashOf(answer: unknown): string {
+	return createHash("sha256").update(canonicalJson(answer)).digest("hex");
+}
+
+/** Validate the schema *shape*. Throws WorkflowGateSchemaError on any problem. */
+export function assertSupportedGateSchema(schema: RpcJsonSchema): void {
+	const serialized = canonicalJson(schema);
+	if (Buffer.byteLength(serialized, "utf8") > GATE_SCHEMA_LIMITS.maxSchemaBytes) {
+		throw new WorkflowGateSchemaError(`schema exceeds ${GATE_SCHEMA_LIMITS.maxSchemaBytes} bytes`);
+	}
+	walkSchema(schema, 0, "#");
+}
+
+function walkSchema(schema: RpcJsonSchema, depth: number, path: string): void {
+	if (depth > GATE_SCHEMA_LIMITS.maxDepth) {
+		throw new WorkflowGateSchemaError(`schema nesting exceeds depth ${GATE_SCHEMA_LIMITS.maxDepth} at ${path}`);
+	}
+	if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
+		throw new WorkflowGateSchemaError(`schema node at ${path} must be an object`);
+	}
+	for (const key of Object.keys(schema)) {
+		if (!SUPPORTED_KEYWORDS.has(key as keyof RpcJsonSchema)) {
+			throw new WorkflowGateSchemaError(`unsupported keyword "${key}" at ${path}`);
+		}
+	}
+	if (schema.type !== undefined && !SUPPORTED_TYPES.has(schema.type)) {
+		throw new WorkflowGateSchemaError(`unsupported type "${schema.type}" at ${path}`);
+	}
+	if (schema.enum !== undefined) {
+		if (!Array.isArray(schema.enum)) throw new WorkflowGateSchemaError(`enum at ${path} must be an array`);
+		if (schema.enum.length > GATE_SCHEMA_LIMITS.maxEnumValues) {
+			throw new WorkflowGateSchemaError(`enum at ${path} exceeds ${GATE_SCHEMA_LIMITS.maxEnumValues} values`);
+		}
+	}
+	for (const meta of ["title", "description"] as const) {
+		if (schema[meta] !== undefined && typeof schema[meta] !== "string") {
+			throw new WorkflowGateSchemaError(`${meta} at ${path} must be a string`);
+		}
+	}
+	for (const limit of ["minLength", "maxLength", "minItems", "maxItems"] as const) {
+		const v = schema[limit];
+		if (v !== undefined && (typeof v !== "number" || !Number.isInteger(v) || v < 0)) {
+			throw new WorkflowGateSchemaError(`${limit} at ${path} must be a non-negative integer`);
+		}
+	}
+	if (schema.uniqueItems !== undefined && typeof schema.uniqueItems !== "boolean") {
+		throw new WorkflowGateSchemaError(`uniqueItems at ${path} must be a boolean`);
+	}
+	for (const limit of ["minimum", "maximum"] as const) {
+		const v = schema[limit];
+		if (v !== undefined && (typeof v !== "number" || !Number.isFinite(v))) {
+			throw new WorkflowGateSchemaError(`${limit} at ${path} must be a finite number`);
+		}
+	}
+	if (
+		schema.required !== undefined &&
+		!(Array.isArray(schema.required) && schema.required.every(r => typeof r === "string"))
+	) {
+		throw new WorkflowGateSchemaError(`required at ${path} must be an array of strings`);
+	}
+	if (schema.properties !== undefined) {
+		if (typeof schema.properties !== "object" || schema.properties === null || Array.isArray(schema.properties)) {
+			throw new WorkflowGateSchemaError(`properties at ${path} must be an object`);
+		}
+		const propKeys = Object.keys(schema.properties);
+		if (propKeys.length > GATE_SCHEMA_LIMITS.maxProperties) {
+			throw new WorkflowGateSchemaError(`properties at ${path} exceed ${GATE_SCHEMA_LIMITS.maxProperties}`);
+		}
+		for (const k of propKeys) walkSchema(schema.properties[k] as RpcJsonSchema, depth + 1, `${path}/properties/${k}`);
+	}
+	if (schema.additionalProperties !== undefined && typeof schema.additionalProperties !== "boolean") {
+		if (
+			typeof schema.additionalProperties !== "object" ||
+			schema.additionalProperties === null ||
+			Array.isArray(schema.additionalProperties)
+		) {
+			throw new WorkflowGateSchemaError(`additionalProperties at ${path} must be a boolean or schema object`);
+		}
+		walkSchema(schema.additionalProperties, depth + 1, `${path}/additionalProperties`);
+	}
+	if (schema.items !== undefined) walkSchema(schema.items, depth + 1, `${path}/items`);
+	for (const combiner of ["oneOf", "anyOf"] as const) {
+		const branches = schema[combiner];
+		if (branches !== undefined) {
+			if (!Array.isArray(branches)) throw new WorkflowGateSchemaError(`${combiner} at ${path} must be an array`);
+			for (let i = 0; i < branches.length; i++)
+				walkSchema(branches[i] as RpcJsonSchema, depth + 1, `${path}/${combiner}/${i}`);
+		}
+	}
+}
+
+type SchemaError = { path: string; keyword: string; message: string; expected?: unknown };
+
+/** A compiled, cached validator for one schema. */
+export interface CompiledGateSchema {
+	readonly schema: RpcJsonSchema;
+	readonly hash: string;
+	validate(answer: unknown): SchemaError[];
+}
+
+const compileCache = new Map<string, CompiledGateSchema>();
+
+/** Compile (and cache) a validator for a schema. Asserts shape on first compile. */
+export function compileGateSchema(schema: RpcJsonSchema): CompiledGateSchema {
+	const hash = schemaHash(schema);
+	const cached = compileCache.get(hash);
+	if (cached) return cached;
+	assertSupportedGateSchema(schema);
+	const compiled: CompiledGateSchema = {
+		schema,
+		hash,
+		validate: answer => {
+			const errors: SchemaError[] = [];
+			const serialized = canonicalJson(answer);
+			if (Buffer.byteLength(serialized, "utf8") > GATE_SCHEMA_LIMITS.maxAnswerBytes) {
+				errors.push({ path: "#", keyword: "maxAnswerBytes", message: "answer too large" });
+				return errors;
+			}
+			validateValue(schema, answer, "#", errors);
+			return errors;
+		},
+	};
+	compileCache.set(hash, compiled);
+	return compiled;
+}
+
+function typeMatches(type: NonNullable<RpcJsonSchema["type"]>, value: unknown): boolean {
+	switch (type) {
+		case "string":
+			return typeof value === "string";
+		case "number":
+			return typeof value === "number" && Number.isFinite(value);
+		case "integer":
+			return typeof value === "number" && Number.isInteger(value);
+		case "boolean":
+			return typeof value === "boolean";
+		case "object":
+			return typeof value === "object" && value !== null && !Array.isArray(value);
+		case "array":
+			return Array.isArray(value);
+		case "null":
+			return value === null;
+	}
+}
+
+function validateValue(schema: RpcJsonSchema, value: unknown, path: string, errors: SchemaError[]): void {
+	if (schema.type !== undefined && !typeMatches(schema.type, value)) {
+		errors.push({ path, keyword: "type", message: `expected ${schema.type}`, expected: schema.type });
+		return;
+	}
+	if (schema.const !== undefined && canonicalJson(value) !== canonicalJson(schema.const)) {
+		errors.push({ path, keyword: "const", message: "value does not equal const", expected: schema.const });
+	}
+	if (schema.enum !== undefined) {
+		const ok = schema.enum.some(e => canonicalJson(e) === canonicalJson(value));
+		if (!ok) errors.push({ path, keyword: "enum", message: "value not in enum", expected: schema.enum });
+	}
+	if (typeof value === "string") {
+		if (schema.minLength !== undefined && value.length < schema.minLength) {
+			errors.push({
+				path,
+				keyword: "minLength",
+				message: `shorter than ${schema.minLength}`,
+				expected: schema.minLength,
+			});
+		}
+		if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+			errors.push({
+				path,
+				keyword: "maxLength",
+				message: `longer than ${schema.maxLength}`,
+				expected: schema.maxLength,
+			});
+		}
+	}
+	if (typeof value === "number") {
+		if (schema.minimum !== undefined && value < schema.minimum) {
+			errors.push({ path, keyword: "minimum", message: `less than ${schema.minimum}`, expected: schema.minimum });
+		}
+		if (schema.maximum !== undefined && value > schema.maximum) {
+			errors.push({ path, keyword: "maximum", message: `greater than ${schema.maximum}`, expected: schema.maximum });
+		}
+	}
+	if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+		const obj = value as Record<string, unknown>;
+		for (const req of schema.required ?? []) {
+			if (!(req in obj))
+				errors.push({ path: `${path}/${req}`, keyword: "required", message: "missing required property" });
+		}
+		const props = schema.properties ?? {};
+		for (const [k, v] of Object.entries(obj)) {
+			if (props[k]) {
+				validateValue(props[k], v, `${path}/${k}`, errors);
+			} else if (schema.additionalProperties === false) {
+				errors.push({ path: `${path}/${k}`, keyword: "additionalProperties", message: "unexpected property" });
+			} else if (typeof schema.additionalProperties === "object" && schema.additionalProperties !== null) {
+				validateValue(schema.additionalProperties, v, `${path}/${k}`, errors);
+			}
+		}
+	}
+	if (Array.isArray(value)) {
+		if (schema.minItems !== undefined && value.length < schema.minItems) {
+			errors.push({
+				path,
+				keyword: "minItems",
+				message: `fewer than ${schema.minItems} items`,
+				expected: schema.minItems,
+			});
+		}
+		if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+			errors.push({
+				path,
+				keyword: "maxItems",
+				message: `more than ${schema.maxItems} items`,
+				expected: schema.maxItems,
+			});
+		}
+		if (schema.uniqueItems) {
+			const seen = new Set<string>();
+			for (const item of value) {
+				const key = canonicalJson(item);
+				if (seen.has(key)) {
+					errors.push({ path, keyword: "uniqueItems", message: "array items must be unique" });
+					break;
+				}
+				seen.add(key);
+			}
+		}
+		if (schema.items) {
+			for (let i = 0; i < value.length; i++)
+				validateValue(schema.items as RpcJsonSchema, value[i], `${path}/${i}`, errors);
+		}
+	}
+	for (const combiner of ["oneOf", "anyOf"] as const) {
+		const branches = schema[combiner];
+		if (!branches) continue;
+		const matchCount = branches.filter(b => {
+			const sub: SchemaError[] = [];
+			validateValue(b, value, path, sub);
+			return sub.length === 0;
+		}).length;
+		const ok = combiner === "oneOf" ? matchCount === 1 : matchCount >= 1;
+		if (!ok) errors.push({ path, keyword: combiner, message: `value did not satisfy ${combiner}` });
+	}
+}
+
+/**
+ * Validate an answer against a compiled gate schema. Returns `null` on success
+ * or a typed {@link RpcWorkflowGateValidationError} on mismatch.
+ */
+export function validateGateAnswer(
+	compiled: CompiledGateSchema,
+	gateId: string,
+	answer: unknown,
+): RpcWorkflowGateValidationError | null {
+	const errors = compiled.validate(answer);
+	if (errors.length === 0) return null;
+	return { code: "invalid_workflow_gate_answer", gate_id: gateId, schema_hash: compiled.hash, errors };
+}
+
+export { answerHashOf };

package/src/modes/theme/theme.ts

@@ -129,6 +129,7 @@ export type SymbolKey =
 	| "thinking.medium"
 	| "thinking.high"
 	| "thinking.xhigh"
+	| "thinking.max"
 	// Checkboxes
 	| "checkbox.checked"
 	| "checkbox.unchecked"
@@ -292,6 +293,7 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"thinking.medium": "◒ med",
 	"thinking.high": "◕ high",
 	"thinking.xhigh": "◉ xhigh",
+	"thinking.max": "◉ max",
 	// Checkboxes
 	"checkbox.checked": "☑",
 	"checkbox.unchecked": "☐",
@@ -542,6 +544,7 @@ const NERD_SYMBOLS: SymbolMap = {
 	"thinking.high": "\u{F111} high",
 	// pick: 🧠 xhi | alt:  xhi  xhi
 	"thinking.xhigh": "\u{F06D} xhi",
+	"thinking.max": "\u{F06D} max",
 	// Checkboxes
 	// pick:  | alt:  
 	"checkbox.checked": "\uf14a",
@@ -712,6 +715,7 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"thinking.medium": "[med]",
 	"thinking.high": "[high]",
 	"thinking.xhigh": "[xhi]",
+	"thinking.max": "[max]",
 	// Checkboxes
 	"checkbox.checked": "[x]",
 	"checkbox.unchecked": "[ ]",
@@ -1316,6 +1320,7 @@ export class Theme {
 			case "high":
 				return (str: string) => this.fg("thinkingHigh", str);
 			case "xhigh":
+			case "max":
 				return (str: string) => this.fg("thinkingXhigh", str);
 			default:
 				return (str: string) => this.fg("thinkingOff", str);
@@ -1487,6 +1492,7 @@ export class Theme {
 			medium: this.#symbols["thinking.medium"],
 			high: this.#symbols["thinking.high"],
 			xhigh: this.#symbols["thinking.xhigh"],
+			max: this.#symbols["thinking.max"],
 		};
 	}