@particle-academy/prism-harness 0.7.0 → 0.8.0

package/README.md

@@ -202,6 +202,15 @@ 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.
 
+## Failed model steps
+
+A client response with `finishReason: 'error'` or `'unknown'` ends the run with
+`HarnessError.code === 'model_step_failed'`. Its `finishReason` identifies which
+of those two finishes occurred; the error message contains no model output.
+The step, cost, and assistant response are recorded before the error is raised.
+Tools requested by that response are refused, with no pending approval authority,
+so approving or resuming later cannot execute them. A new turn can still be sent.
+
 ## Approvals
 
 A mode names the tools a person must approve:

package/dist/errors.d.ts

@@ -18,6 +18,8 @@ export type HarnessErrorCode =
  | 'tool_not_available'
 /** A run was refused — by budget, by depth, or by a cancelled ledger. */
  | 'run_not_permitted'
+/** A model returned a terminal error/unknown finish; its tools must not run. */
+ | 'model_step_failed'
 /** A stored payload could not be mapped back into a value object. */
  | 'unmappable_content'
 /** A session was asked to do something that needs a runtime it does not have. */
@@ -75,6 +77,7 @@ export type HarnessErrorCode =
  | 'structured_schema_violation';
 export interface HarnessErrorOptions {
     cause?: unknown;
+    finishReason?: 'error' | '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. */
@@ -82,6 +85,7 @@ export interface HarnessErrorOptions {
 }
 export declare class HarnessError extends Error {
     readonly code: HarnessErrorCode;
+    readonly finishReason?: 'error' | 'unknown';
     /**
      * The model's own text, on a structured failure.
      *
@@ -106,6 +110,7 @@ export declare class HarnessError extends Error {
     static unknownStoreDriver(slot: string, driver: string): HarnessError;
     static toolNotAvailable(name: string, available: readonly string[]): HarnessError;
     static runNotPermitted(reason: string): HarnessError;
+    static modelStepFailed(finishReason: 'error' | 'unknown'): HarnessError;
     static unmappableContent(description: string, options?: HarnessErrorOptions): HarnessError;
     static modeNotConfigured(name: string): HarnessError;
     static modeMalformed(name: string, detail: string): HarnessError;

package/dist/errors.js

@@ -1,5 +1,6 @@
 export class HarnessError extends Error {
     code;
+    finishReason;
     /**
      * The model's own text, on a structured failure.
      *
@@ -14,6 +15,10 @@ export class HarnessError extends Error {
         super(message, options);
         this.name = 'HarnessError';
         this.code = code;
+        if (options.finishReason !== undefined && options.finishReason !== 'error' && options.finishReason !== 'unknown') {
+            throw new TypeError('Model step finish reason must be error or unknown');
+        }
+        this.finishReason = options.finishReason;
         this.document = options.document;
         this.problems = options.problems ?? [];
     }
@@ -44,6 +49,12 @@ export class HarnessError extends Error {
     static runNotPermitted(reason) {
         return new HarnessError('run_not_permitted', reason);
     }
+    static modelStepFailed(finishReason) {
+        if (finishReason !== 'error' && finishReason !== 'unknown') {
+            throw new TypeError('Model step finish reason must be error or unknown');
+        }
+        return new HarnessError('model_step_failed', `Model step failed: ${finishReason}.`, { finishReason });
+    }
     static unmappableContent(description, options = {}) {
         return new HarnessError('unmappable_content', `Could not rebuild stored content: ${description}.`, options);
     }

package/dist/runtime.js

@@ -171,7 +171,8 @@ export class AgentRuntime {
             text = response.text;
             finishReason = response.finishReason;
             const toolCalls = response.toolCalls ?? [];
-            const gated = toolCalls.filter((call) => mode.needsApproval(call.name));
+            const failedFinish = finishReason === 'error' || finishReason === 'unknown' ? finishReason : null;
+            const gated = failedFinish === null ? toolCalls.filter((call) => mode.needsApproval(call.name)) : [];
             const requests = gated.map((call) => ({
                 approval_id: `apr_${randomUUID().replaceAll('-', '')}`,
                 tool_call_id: call.id,
@@ -184,6 +185,14 @@ export class AgentRuntime {
                 ? { ...(response.additionalContent ?? {}), structured: response.structured ?? null }
                 : response.additionalContent;
             await thread.record([assistantRow(response.text, toolCalls, metadata, requests)], runId);
+            if (failedFinish !== null) {
+                // Complete the transcript with refusals, never approval requests, so a
+                // later resume cannot dispatch calls from this failed response.
+                if (toolCalls.length > 0) {
+                    await thread.record([toolResultRow(toolCalls.map(call => toolResultEntry(call, `Not run: model step failed (${failedFinish}).`)))], runId);
+                }
+                throw HarnessError.modelStepFailed(failedFinish);
+            }
             if (toolCalls.length === 0) {
                 if (schema !== undefined) {
                     // Recorded first, then checked: the exchange happened either way, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/prism-harness",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Durable agent sessions for TypeScript — threads, session state and store drivers.",
   "type": "module",
   "sideEffects": false,