@particle-academy/prism-harness 0.4.0 → 0.6.0

package/README.md

@@ -3,9 +3,11 @@
 Durable agent sessions — threads, session state and store drivers. The
 TypeScript port of [`particle-academy/prism-harness`](https://github.com/Particle-Academy/prism-harness).
 
-Zero runtime dependencies. Node 20+.
+Zero runtime dependencies. Node 22+.
 
-This package is private while coordinated parity work is in progress.
+```
+npm install @particle-academy/prism-harness
+```
 
 ```ts
 import { FileSessionStore, MemorySessionStore, PrismHarness } from '@particle-academy/prism-harness';
@@ -107,6 +109,8 @@ as `request.providerOptions`, on every step of every run in that mode. Pass them
 to your provider call (with `prism-ts`, `withProviderOptions()`):
 
 ```ts
+import { ModeRegistry } from '@particle-academy/prism-harness';
+
 new ModeRegistry({
   modes: { overseer: { system_prompt: '...', provider_options: { thinking: { type: 'adaptive' } } } },
 });
@@ -131,12 +135,83 @@ sent to the provider once. Return a call's provider ids as `resultId`,
 `reasoningId` and `reasoningSummary`, and provider state for the turn as
 `additionalContent`: they are recorded and come back in `messages`.
 
+## Structured turns
+
+When the answer is a document rather than prose, hand the turn a schema:
+
+```ts
+const schema = {
+  name: 'plan',
+  type: 'object',
+  properties: {
+    title: { type: 'string' },
+    steps: { type: 'array', items: { type: 'string' } },
+  },
+  required: ['title', 'steps'],
+};
+
+const response = await runtime.sendStructured(session, 'Plan the release', schema);
+
+response.structured; // { title: 'Ship it', steps: ['write', 'test'] }
+response.text; // the document as the model wrote it
+```
+
+It is the same run as `send()` — the mode's system prompt, its tools, the step
+budget, the events — asking the provider for structured output. Your client
+receives the schema as `request.schema` and returns what it parsed as
+`response.structured`; with `prism-ts` that is `Prism.structured().withSchema()`
+and the response's `structured`.
+
+**The thread keeps the text, with the parsed object beside it.** The assistant
+message is the raw document, and `structured` rides along in the row's
+`additional_content`. A later turn replays the conversation as messages and reads
+the text, so a thread that contains a structured answer reads like any other.
+
+**A document that misses the schema is refused, not repaired.**
+
+```ts
+import { HarnessError } from '@particle-academy/prism-harness';
+
+try {
+  const plan = (await runtime.sendStructured(session, brief, schema)).structured;
+} catch (error) {
+  if (error instanceof HarnessError) {
+    error.code; // structured_schema_violation, or structured_unreadable
+    error.problems; // every way it missed, not the first
+    error.document; // what the model actually said
+  }
+}
+```
+
+Nothing is coerced, nothing is trimmed to the fields that fit, and the result is
+never an empty document. An empty plan settles a batch as `done`, which reads
+exactly like a considered answer of "nothing to propose" — the failure this
+refusal exists to prevent. The exchange is still recorded, and the run is marked
+failed: a thread that omits the answer it did not like cannot explain the retry
+sitting next to it. The run row and the `run.failed` event name the CODE, not the
+message — the message quotes the values that missed, and an event carrying those
+would ship model output to every listener, which is the same reason tool
+arguments are names-only here.
+
+The check reads the schema's own JSON Schema, so a hand-written schema is held to
+the same terms. `schemaProblems()` is exported if you want it directly. It checks
+declared types, required keys, enum members, array items, and — where a schema
+closes itself — keys nobody declared. It does not read `$ref`, `allOf`, `oneOf`
+or the numeric and string facets; what it cannot read, it passes, rather than
+reporting a constraint it did not actually check. The same rules as the PHP
+reference, message for message, so a document refused in one language is refused
+in the other for the same stated reason.
+
 ## Approvals
 
 A mode names the tools a person must approve:
 
 ```ts
-guarded: { system_prompt: '...', tools: ['read', 'delete'], requires_approval: ['delete'] },
+new ModeRegistry({
+  modes: {
+    guarded: { system_prompt: '...', tools: ['read', 'delete'], requires_approval: ['delete'] },
+  },
+});
 ```
 
 A step that calls one stops with `finishReason: 'awaiting_approval'`. The calls
@@ -144,6 +219,8 @@ that need nobody have already run. Record a decision for every pending approval,
 then resume with an empty prompt:
 
 ```ts
+import { recordApproval } from '@particle-academy/prism-harness';
+
 const response = await runtime.send(session, 'Clean up the failed run');
 
 if (response.finishReason === 'awaiting_approval') {

package/dist/errors.d.ts

@@ -68,12 +68,30 @@ export type HarnessErrorCode =
 /** A turn attachment carries no bytes, no file id and no chunks. */
  | 'attachment_empty'
 /** Attachments were offered with an empty prompt, which sends no user message. */
- | 'attachment_without_prompt';
+ | 'attachment_without_prompt'
+/** A structured turn came back with text holding no readable document. */
+ | 'structured_unreadable'
+/** A structured turn returned a document its schema refuses. */
+ | 'structured_schema_violation';
 export interface HarnessErrorOptions {
     cause?: unknown;
+    /** The model's own text, on a structured failure. See `HarnessError.document`. */
+    document?: string;
+    /** Every way a document missed its schema, on a structured failure. */
+    problems?: readonly string[];
 }
 export declare class HarnessError extends Error {
     readonly code: HarnessErrorCode;
+    /**
+     * The model's own text, on a structured failure.
+     *
+     * It travels on the error because the first question anyone asks is "what did
+     * it actually say", and an error that answers it turns a support thread into
+     * a log line. It is model output: log it where you log model output.
+     */
+    readonly document?: string;
+    /** Every way a document missed its schema, rather than only the first. */
+    readonly problems: readonly string[];
     constructor(code: HarnessErrorCode, message: string, options?: HarnessErrorOptions);
     static sessionLocked(key: string, waitSeconds: number): HarnessError;
     /**
@@ -216,4 +234,20 @@ export declare class HarnessError extends Error {
     static attachmentEmpty(index: number): HarnessError;
     /** An empty prompt resumes a paused run and sends no user message, so attachments would vanish. */
     static attachmentWithoutPrompt(): HarnessError;
+    /**
+     * A structured turn whose text held no document at all.
+     *
+     * Separate from the schema violation because the caller's next move differs:
+     * an apology in prose or a truncated answer is a prompting or a budget
+     * problem, and a document with the wrong shape is a schema one.
+     */
+    static structuredUnreadable(document: string): HarnessError;
+    /**
+     * Valid JSON, wrong shape.
+     *
+     * NOT coerced, not trimmed to the fields that fit, and never an empty
+     * document: one that fails the contract arriving as `{}` reads to the code
+     * receiving it exactly like a considered answer of "nothing".
+     */
+    static structuredSchemaViolation(document: string, problems: readonly string[]): HarnessError;
 }

package/dist/errors.js

@@ -1,9 +1,21 @@
 export class HarnessError extends Error {
     code;
+    /**
+     * The model's own text, on a structured failure.
+     *
+     * It travels on the error because the first question anyone asks is "what did
+     * it actually say", and an error that answers it turns a support thread into
+     * a log line. It is model output: log it where you log model output.
+     */
+    document;
+    /** Every way a document missed its schema, rather than only the first. */
+    problems;
     constructor(code, message, options = {}) {
         super(message, options);
         this.name = 'HarnessError';
         this.code = code;
+        this.document = options.document;
+        this.problems = options.problems ?? [];
     }
     static sessionLocked(key, waitSeconds) {
         return new HarnessError('session_locked', `Could not acquire the lock on session [${key}] within ${waitSeconds}s. ` +
@@ -220,4 +232,24 @@ export class HarnessError extends Error {
         return new HarnessError('attachment_without_prompt', 'Attachments need a prompt to travel with. An empty prompt resumes a paused run and sends no user ' +
             'message, so these attachments would be dropped without a word.');
     }
+    /**
+     * A structured turn whose text held no document at all.
+     *
+     * Separate from the schema violation because the caller's next move differs:
+     * an apology in prose or a truncated answer is a prompting or a budget
+     * problem, and a document with the wrong shape is a schema one.
+     */
+    static structuredUnreadable(document) {
+        return new HarnessError('structured_unreadable', 'The model returned no readable document for a structured turn. Its text is on this error as document.', { document });
+    }
+    /**
+     * Valid JSON, wrong shape.
+     *
+     * NOT coerced, not trimmed to the fields that fit, and never an empty
+     * document: one that fails the contract arriving as `{}` reads to the code
+     * receiving it exactly like a considered answer of "nothing".
+     */
+    static structuredSchemaViolation(document, problems) {
+        return new HarnessError('structured_schema_violation', `The model returned a document that does not satisfy the schema: ${problems.join(' ')}`, { document, problems });
+    }
 }

package/dist/index.d.ts

@@ -26,7 +26,8 @@ export type { DoctorFinding, DoctorReport, DoctorSubjects } from './doctor.js';
 export { AgentRuntime, recordApproval } from './runtime.js';
 export { assistantRow, threadView, toolResultEntry, toolResultRow } from './thread-rows.js';
 export type { ApprovalDecisionEntry, ApprovalRequestEntry, AssistantRow, ToolCallInput, ToolCallRow, ToolResultEntry, ToolResultRow, } from './thread-rows.js';
-export type { AgentResponse, AgentRuntimeOptions, LlmClient, LlmRequest, LlmResponse, LlmToolCall, PendingApproval, } from './runtime.js';
+export type { AgentResponse, AgentRuntimeOptions, LlmClient, LlmRequest, LlmResponse, LlmToolCall, PendingApproval, StructuredAgentResponse, } from './runtime.js';
+export { schemaName, schemaProblems } from './structured.js';
 export { DEFAULT_LEASE_SECONDS, TASK_STATES, asAgentTask, attributesToRecord, canonicalTaskJson, isTaskState, isTerminalState, recordToAttributes, taskRecordFrom, withAgentTask, } from './tasks.js';
 export type { AgentTask, AgentTaskAttributeSource, AgentTaskAttributes, AgentTaskRecord, AgentTaskSource, LeasedAgentTask, TaskOutcome, TaskState, } from './tasks.js';
 export { StoreTaskSource, StoredAgentTask } from './store-task-source.js';

package/dist/index.js

@@ -14,6 +14,7 @@ export { HarnessEvents } from './events.js';
 export { diagnose } from './doctor.js';
 export { AgentRuntime, recordApproval } from './runtime.js';
 export { assistantRow, threadView, toolResultEntry, toolResultRow } from './thread-rows.js';
+export { schemaName, schemaProblems } from './structured.js';
 export { DEFAULT_LEASE_SECONDS, TASK_STATES, asAgentTask, attributesToRecord, canonicalTaskJson, isTaskState, isTerminalState, recordToAttributes, taskRecordFrom, withAgentTask, } from './tasks.js';
 export { StoreTaskSource, StoredAgentTask } from './store-task-source.js';
 export { agentCompletionTool } from './task-tools.js';

package/dist/runtime.d.ts

@@ -28,6 +28,15 @@ export interface LlmRequest {
      * interpret them.
      */
     providerOptions: Readonly<JsonObject>;
+    /**
+     * The JSON Schema a structured turn asks the answer to satisfy.
+     *
+     * Absent on an ordinary turn. A client passes it to its provider's structured
+     * mode (for prism-ts, `Prism.structured().withSchema()`) and returns what it
+     * parsed as `structured`; the harness checks that against this same schema
+     * before the caller sees it.
+     */
+    schema?: Readonly<JsonObject>;
 }
 export interface LlmToolCall {
     id: string;
@@ -58,6 +67,14 @@ export interface LlmResponse {
      * straight through and read it back from `messages`.
      */
     additionalContent?: Readonly<JsonObject>;
+    /**
+     * The document a structured turn parsed out of `text`.
+     *
+     * Null when the text held none — an apology in prose, a truncated answer, a
+     * fence that never closed. The harness tells that case apart from a document
+     * with the wrong shape, because the caller's next move differs.
+     */
+    structured?: JsonValue | null;
 }
 export type LlmClient = (request: LlmRequest) => Promise<LlmResponse>;
 export interface AgentResponse {
@@ -72,6 +89,17 @@ export interface AgentResponse {
     /** Set when the run stopped because the tree ran out of budget, or was cancelled. */
     stoppedBecause: string | null;
 }
+/**
+ * One structured run's result: the document, and the text it was read from.
+ *
+ * BOTH, not one. `structured` is what the caller asked for, and `text` is what
+ * the model actually sent — which is also exactly what the thread stored, so a
+ * transcript and a parse can be compared rather than trusted.
+ */
+export interface StructuredAgentResponse extends AgentResponse {
+    /** Checked against the schema before it got here; a run that could not produce one threw. */
+    structured: JsonValue;
+}
 export interface PendingApproval {
     /** The APPROVAL id: what `recordApproval()` answers. Not the tool call id. */
     id: string;
@@ -98,6 +126,28 @@ export declare class AgentRuntime {
      * second instruction competing with the one the tool call came from.
      */
     send(session: Session, prompt: string, toolNames?: readonly string[], context?: RunContext, additionalContent?: readonly unknown[]): Promise<AgentResponse>;
+    /**
+     * A turn whose answer is a document.
+     *
+     * The same run as `send()` — same mode, same tools, same budget, same events,
+     * same approvals — with a schema the answer has to satisfy. The schema
+     * travels on the request for the client to hand its provider, and what comes
+     * back is checked against it here before the caller sees it.
+     *
+     * WHAT THE THREAD KEEPS IS THE TEXT, with the parsed document beside it as
+     * `structured` in the assistant row's `additional_content`. Never instead of
+     * it: a later turn replays this conversation as messages, and a transcript
+     * that reads differently because of the SHAPE of the request that produced it
+     * is a difference nothing reports.
+     *
+     * A FAILED DOCUMENT IS STILL RECORDED, and then thrown. The exchange
+     * happened, and a thread that omits the answer it did not like cannot explain
+     * the retry sitting next to it. The run is marked failed and `run.failed` is
+     * emitted, as for any other failure.
+     *
+     * @throws HarnessError `structured_unreadable` or `structured_schema_violation`
+     */
+    sendStructured(session: Session, prompt: string, schema: Readonly<JsonObject>, toolNames?: readonly string[], context?: RunContext, additionalContent?: readonly unknown[]): Promise<StructuredAgentResponse>;
 }
 /**
  * Answer a pending approval, durably.

package/dist/runtime.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { assistantRow, threadView, toolResultEntry, toolResultRow, } from './thread-rows.js';
 import { admitAttachments } from './attachments.js';
 import { HarnessError } from './errors.js';
+import { schemaName, schemaProblems } from './structured.js';
 import { RunBudget, RunContext } from './subagents.js';
 /**
  * The loop: prompt in, turns out, everything recorded.
@@ -47,6 +48,35 @@ export class AgentRuntime {
      * second instruction competing with the one the tool call came from.
      */
     async send(session, prompt, toolNames, context, additionalContent = []) {
+        return await this.#turn(session, prompt, toolNames, context, additionalContent);
+    }
+    /**
+     * A turn whose answer is a document.
+     *
+     * The same run as `send()` — same mode, same tools, same budget, same events,
+     * same approvals — with a schema the answer has to satisfy. The schema
+     * travels on the request for the client to hand its provider, and what comes
+     * back is checked against it here before the caller sees it.
+     *
+     * WHAT THE THREAD KEEPS IS THE TEXT, with the parsed document beside it as
+     * `structured` in the assistant row's `additional_content`. Never instead of
+     * it: a later turn replays this conversation as messages, and a transcript
+     * that reads differently because of the SHAPE of the request that produced it
+     * is a difference nothing reports.
+     *
+     * A FAILED DOCUMENT IS STILL RECORDED, and then thrown. The exchange
+     * happened, and a thread that omits the answer it did not like cannot explain
+     * the retry sitting next to it. The run is marked failed and `run.failed` is
+     * emitted, as for any other failure.
+     *
+     * @throws HarnessError `structured_unreadable` or `structured_schema_violation`
+     */
+    async sendStructured(session, prompt, schema, toolNames, context, additionalContent = []) {
+        const response = await this.#turn(session, prompt, toolNames, context, additionalContent, schema);
+        // Narrowed by #turn: with a schema it always returns the structured shape.
+        return response;
+    }
+    async #turn(session, prompt, toolNames, context, additionalContent = [], schema) {
         // Refused before a run exists: a bad attachment is a mistake in the call,
         // and it should not cost a run, events or budget.
         const attachments = admitAttachments(prompt, additionalContent);
@@ -89,10 +119,21 @@ export class AgentRuntime {
                     : { type: 'user', content: prompt, additional_content: [...attachments, { text: prompt }], additional_attributes: {} };
                 await thread.record([turn], runId);
             }
-            return await this.#loop(session, mode, run, runId, provider, model, offered, called);
+            return await this.#loop(session, mode, run, runId, provider, model, offered, called, schema);
         }
         catch (error) {
-            const failure = error instanceof Error ? error.message : String(error);
+            // THE MODEL'S OWN WORDS DO NOT BELONG IN A RUN ROW OR AN EVENT. A schema
+            // violation names the values that missed, so its message carries pieces
+            // of the document — and an event carrying those would put model output in
+            // every listener's telemetry, which is the same reason tool arguments are
+            // names-only here. The document is already in the thread, in full, where
+            // it is read deliberately rather than shipped by default. An error that
+            // holds one records its CODE.
+            const failure = error instanceof HarnessError && error.document !== undefined
+                ? error.code
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
             await session.failRun(runId, failure);
             this.#events?.emit({
                 type: 'run.failed',
@@ -105,7 +146,7 @@ export class AgentRuntime {
             throw error;
         }
     }
-    async #loop(session, mode, run, runId, provider, model, offered, called) {
+    async #loop(session, mode, run, runId, provider, model, offered, called, schema) {
         const thread = session.thread();
         let text = '';
         let finishReason = 'stop';
@@ -123,6 +164,7 @@ export class AgentRuntime {
                 provider,
                 model,
                 providerOptions: mode.providerOptions,
+                ...(schema === undefined ? {} : { schema }),
             });
             run.ledger.recordSteps(1);
             run.ledger.recordCost(response.costUsd ?? null);
@@ -137,9 +179,22 @@ export class AgentRuntime {
             // The next step's request is built from this row, so it keeps what a
             // provider needs sent back: each call's arguments and provider ids, the
             // turn's provider state, and the approvals it is waiting on (G-58).
-            await thread.record([assistantRow(response.text, toolCalls, response.additionalContent, requests)], runId);
+            const answering = schema !== undefined && toolCalls.length === 0;
+            const metadata = answering
+                ? { ...(response.additionalContent ?? {}), structured: response.structured ?? null }
+                : response.additionalContent;
+            await thread.record([assistantRow(response.text, toolCalls, metadata, requests)], runId);
             if (toolCalls.length === 0) {
-                return await this.#finish(session, runId, called, finishReason, text, run, null);
+                if (schema !== undefined) {
+                    // Recorded first, then checked: the exchange happened either way, and
+                    // a failure here fails the run through the caller's catch.
+                    this.#assertDocument(schema, response);
+                }
+                const finished = await this.#finish(session, runId, called, finishReason, text, run, null);
+                if (schema === undefined)
+                    return finished;
+                const structured = { ...finished, structured: response.structured };
+                return structured;
             }
             // The calls that need nobody run now, as in the reference, and their
             // results are recorded even when the step then stops for a person.
@@ -280,6 +335,22 @@ export class AgentRuntime {
             return toolResultEntry(call, `The tool failed: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    /**
+     * Refuse a document the caller cannot use, naming which of the two it is.
+     *
+     * Text holding no document at all and a document with the wrong shape are
+     * separate codes because the next move differs: the first is a prompting or
+     * budget problem, the second a schema one.
+     */
+    #assertDocument(schema, response) {
+        if (response.structured === undefined || response.structured === null) {
+            throw HarnessError.structuredUnreadable(response.text);
+        }
+        const problems = schemaProblems(schema, response.structured, schemaName(schema));
+        if (problems.length > 0) {
+            throw HarnessError.structuredSchemaViolation(response.text, problems);
+        }
+    }
     async #finish(session, runId, called, finishReason, text, run, stoppedBecause) {
         await session.completeRun(runId, finishReason, called);
         this.#events?.emit({

package/dist/structured.d.ts

@@ -0,0 +1,37 @@
+import type { JsonObject, JsonValue } from './json.js';
+/**
+ * Does a document the model returned actually satisfy the schema it was given?
+ *
+ * A provider that supports strict structured output answers yes by
+ * construction. Most do not, and the ones that do can still be pointed at a
+ * model or an endpoint where the mode is unavailable — so the question has to
+ * be asked here, once, on the way back.
+ *
+ * WHY THIS IS NOT COERCION. The tempting alternative is to keep the fields that
+ * fit and drop the rest, which turns a wrong answer into a plausible one: a
+ * planning agent that returns a document missing its `nodes` array becomes a
+ * plan with no steps, and an empty plan settles a batch as done.
+ *
+ * WHAT IT CHECKS is what a JSON schema says without needing a resolver: the
+ * declared type, the required keys, the members of an enum, the items of an
+ * array, and, where a schema closes itself to additions, keys nobody declared.
+ *
+ * WHAT IT DOES NOT CHECK: `$ref`, `allOf`, `oneOf`, `not`, and the numeric and
+ * string facets (`minimum`, `pattern`, `minLength`). Each would be a partial
+ * implementation of a specification this package has no business owning, and a
+ * partial validator that reports nothing for a constraint it cannot read is
+ * worse than one whose limits are written down. What it cannot read, it passes.
+ *
+ * The same rules as `Prism\Harness\Structured\SchemaCheck` in the PHP
+ * reference, message for message, so a document refused in one language is
+ * refused in the others for the same stated reason.
+ */
+export declare function schemaProblems(schema: JsonObject, document: JsonValue, name?: string): string[];
+/**
+ * What to call the document in a problem message.
+ *
+ * A schema that names itself — Prism's `ObjectSchema` writes `name` — gets its
+ * own name in the path, so `plan.steps[1].do` reads the way the schema's author
+ * wrote it. Anything else is just "document".
+ */
+export declare function schemaName(schema: Readonly<JsonObject>): string;

package/dist/structured.js

@@ -0,0 +1,158 @@
+/**
+ * Does a document the model returned actually satisfy the schema it was given?
+ *
+ * A provider that supports strict structured output answers yes by
+ * construction. Most do not, and the ones that do can still be pointed at a
+ * model or an endpoint where the mode is unavailable — so the question has to
+ * be asked here, once, on the way back.
+ *
+ * WHY THIS IS NOT COERCION. The tempting alternative is to keep the fields that
+ * fit and drop the rest, which turns a wrong answer into a plausible one: a
+ * planning agent that returns a document missing its `nodes` array becomes a
+ * plan with no steps, and an empty plan settles a batch as done.
+ *
+ * WHAT IT CHECKS is what a JSON schema says without needing a resolver: the
+ * declared type, the required keys, the members of an enum, the items of an
+ * array, and, where a schema closes itself to additions, keys nobody declared.
+ *
+ * WHAT IT DOES NOT CHECK: `$ref`, `allOf`, `oneOf`, `not`, and the numeric and
+ * string facets (`minimum`, `pattern`, `minLength`). Each would be a partial
+ * implementation of a specification this package has no business owning, and a
+ * partial validator that reports nothing for a constraint it cannot read is
+ * worse than one whose limits are written down. What it cannot read, it passes.
+ *
+ * The same rules as `Prism\Harness\Structured\SchemaCheck` in the PHP
+ * reference, message for message, so a document refused in one language is
+ * refused in the others for the same stated reason.
+ */
+export function schemaProblems(schema, document, name = 'document') {
+    return check(schema, document, name);
+}
+function check(schema, value, path) {
+    if (Array.isArray(schema.anyOf)) {
+        return checkAnyOf(schema.anyOf, value, path);
+    }
+    if (Array.isArray(schema.enum)) {
+        return schema.enum.some((member) => member === value)
+            ? []
+            : [`${path} is ${describe(value)}, which is not one of ${members(schema.enum)}.`];
+    }
+    const types = declaredTypes(schema);
+    if (types.length === 0) {
+        // Nothing declared to check against. A schema that says nothing about a
+        // value cannot be violated by it.
+        return [];
+    }
+    if (!types.some((type) => matches(type, value))) {
+        return [`${path} is ${describe(value)}, and the schema asks for ${members(types)}.`];
+    }
+    if (types.includes('object') && isObject(value)) {
+        return checkObject(schema, value, path);
+    }
+    if (types.includes('array') && Array.isArray(value)) {
+        return checkArray(schema, value, path);
+    }
+    return [];
+}
+function checkAnyOf(branches, value, path) {
+    for (const branch of branches) {
+        if (isObject(branch) && check(branch, value, path).length === 0)
+            return [];
+    }
+    return [`${path} is ${describe(value)}, which satisfies none of the alternatives the schema allows.`];
+}
+function checkObject(schema, value, path) {
+    const problems = [];
+    const properties = isObject(schema.properties) ? schema.properties : {};
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    for (const name of required) {
+        if (typeof name === 'string' && !(name in value)) {
+            problems.push(`${path}.${name} is required and missing.`);
+        }
+    }
+    for (const [name, property] of Object.entries(properties)) {
+        if (!isObject(property) || !(name in value))
+            continue;
+        problems.push(...check(property, value[name], `${path}.${name}`));
+    }
+    // Only where the schema closed itself. An open object invites the extra key,
+    // so reporting it would be this package's opinion rather than the schema's.
+    if (schema.additionalProperties === false) {
+        for (const name of Object.keys(value)) {
+            if (!(name in properties)) {
+                problems.push(`${path}.${name} was returned, and the schema declares no such property.`);
+            }
+        }
+    }
+    return problems;
+}
+function checkArray(schema, value, path) {
+    if (!isObject(schema.items))
+        return [];
+    const items = schema.items;
+    return value.flatMap((item, index) => check(items, item, `${path}[${index}]`));
+}
+/** The declared types, as a list — a nullable schema declares two. */
+function declaredTypes(schema) {
+    if (typeof schema.type === 'string')
+        return [schema.type];
+    if (Array.isArray(schema.type))
+        return schema.type.filter((type) => typeof type === 'string');
+    return [];
+}
+function matches(type, value) {
+    switch (type) {
+        case 'string':
+            return typeof value === 'string';
+        // An integer satisfies `number`, as JSON Schema says it does. The other
+        // direction does not, and JavaScript is where that is easiest to get wrong:
+        // 2.0 parses as the same number as 2, so `Number.isInteger` is the test
+        // rather than the absence of a fractional part in the source text.
+        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 'null':
+            return value === null;
+        case 'array':
+            return Array.isArray(value);
+        case 'object':
+            return isObject(value);
+        default:
+            return true;
+    }
+}
+function describe(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'an array';
+    if (typeof value === 'object')
+        return 'an object';
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'string') {
+        return `the string "${value.length > 40 ? `${value.slice(0, 40)}…` : value}"`;
+    }
+    return `the number ${value}`;
+}
+function members(values) {
+    return values
+        .map((value) => (typeof value === 'string' ? `'${value}'` : JSON.stringify(value)))
+        .join(', ');
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * What to call the document in a problem message.
+ *
+ * A schema that names itself — Prism's `ObjectSchema` writes `name` — gets its
+ * own name in the path, so `plan.steps[1].do` reads the way the schema's author
+ * wrote it. Anything else is just "document".
+ */
+export function schemaName(schema) {
+    return typeof schema.name === 'string' && schema.name !== '' ? schema.name : 'document';
+}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@particle-academy/prism-harness",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Durable agent sessions for TypeScript — threads, session state and store drivers.",
   "type": "module",
   "sideEffects": false,
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "exports": {
     ".": {