@jigging/agent-method 0.1.0-alpha.4 → 0.1.0-alpha.6

package/AGENTS.md

@@ -30,6 +30,9 @@ ordinary Flow, preserving operator ownership of Agent execution.
   Final receipt presence must match the initial session request; malformed or
   unsolicited receipts fail without discarding settled turn evidence.
   Callback or cleanup failures retain received turns in `AgentConversationError`.
+  Its bounded summary preserves the first already-exposed Error message without
+  invoking getters or traversing arbitrary causes. Diagnostic display replaces
+  malformed Unicode; full original errors remain available.
   Optional synchronous `onEvent` owns its public update channel and reports
   observation loss separately from execution settlement. It never privately
   echoes filtered data or requires a Log grant. Async routing uses `events`.
@@ -55,6 +58,10 @@ ordinary Flow, preserving operator ownership of Agent execution.
   are checked before dispatch. `structuredOutput: 'json-schema'` explicitly
   adds the API's strict schema request; prompt mode is the default. Both modes
   check results locally and never fall back or retry on rejection.
+  HTTP failures retain closed status-derived diagnostics and corrective guidance;
+  only an exact allowlisted API parameter name may be projected from rejection.
+  Provider error text, headers and rejected values never enter diagnostics.
+  A response establishes neither remote effect rollback nor safe replay.
   Endpoint, credentials and request policy belong to the host grant. No retries,
   native Agent dependency, channel projection or direct networking. Skill contents
   and guidance arrive as explicit caller data, not host-authenticated provenance.
@@ -73,6 +80,8 @@ ordinary Flow, preserving operator ownership of Agent execution.
 - The ordinary ACP package imports this same method. `checkAgentResult` lets
   consumers independently check any selected
   Agent's dynamic structured result; it grants no authority or provenance.
+  Its validated `AgentResult` is assignable to portable FLOW JSON without a
+  cast; arbitrary exceptions and non-JSON values are not.
 
 ## Work Guidance
 
@@ -83,6 +92,9 @@ ordinary Flow, preserving operator ownership of Agent execution.
 
 ## Verification
 
+- Synthetic SDK subprocesses use the running test executable, not ambient PATH
+  discovery, so protocol evidence stays bound to the selected Bun runtime.
+
 - The build clears only generated `dist/` before compiling, so removed source
   cannot survive in the packed runtime or declaration files.
 

package/README.md

@@ -133,8 +133,11 @@ The caller declares the exact Agent bundle and required mechanisms once in
 `FLOW.meta.json`. The helper resolves channel agreements through that slot:
 
 With Jig, import the installed bundle in one step into an existing `contracts/`
-parent: `jig import-contract node_modules/@jigging/agent-method/FLOW.contract.json flows/worker/contracts/agent-run`.
+parent: `jig import-contract npm:@jigging/agent-method flows/worker/contracts/agent-run`.
 This copies the validated offline closure without running code or granting authority.
+Resolution starts from that parent and uses the nearest ordinary installation,
+including a Flow-local or project-root dependency. The
+[conversation guide](https://jig.md/guide/conversations) supplies a complete caller.
 
 ```json
 {
@@ -282,6 +285,11 @@ Tool requests, asynchronous or failed responses, unknown termination reasons,
 malformed replies and non-200 HTTP statuses fail without echoing provider error
 bodies. Refusal and explicit token exhaustion remain `blocked` and `limit`
 outcomes. No request is retried, including after cancellation or uncertain dispatch.
+HTTP rejection errors retain status-derived `details` (`phase`, `api`, `status`,
+`category`, `retry`, and an optional recognized `parameter`) and explain which configuration to check. Provider bodies
+remain private, unknown parameters remain unknown, and a received response
+does not prove remote rollback or safe replay. See the
+[diagnostic guide](https://jig.md/guide/agent-method#diagnose-a-failed-request).
 
 The exact Agent Run contract declares optional updates. This HTTP implementation
 rejects a requested channel before dispatch; it supplies no streaming or ACP

package/dist/api.js

@@ -73,7 +73,7 @@ export function parseApiResult(result, api) {
         !Object.hasOwn(http, 'body'))
         return invalid('HTTP slot returned invalid response evidence');
     if (http.status !== 200)
-        return invalid(`Agent endpoint returned HTTP ${http.status}; no automatic retry was attempted`);
+        return rejectedHttp(http.status, api, http.body);
     if (canonicalJson(http.body).byteLength > 12_582_912)
         throw new AgentMethodError('RESOURCE_EXHAUSTED', 'Agent HTTP response exceeds 12 MiB');
     const body = ordinaryRecord(http.body);
@@ -162,3 +162,69 @@ function responsesResult(body) {
 function invalid(message) {
     throw new AgentMethodError('INVALID_RESULT', message);
 }
+function rejectedHttp(status, api, body) {
+    // Project status and exact known parameter names, never free-form text. Even an apparently
+    // harmless error field can contain credentials, input, or terminal controls.
+    let category = 'unexpected-status';
+    let action = 'Check the selected endpoint and its documented API format.';
+    const error = ordinaryRecord(ordinaryRecord(body)?.error);
+    const parameters = {
+        model: 'model',
+        store: 'endpoint support for store: false',
+        ...(api === 'responses'
+            ? {
+                max_output_tokens: 'maxCompletionTokens',
+                input: 'api',
+                'text.format': 'structuredOutput',
+            }
+            : {
+                max_completion_tokens: 'maxCompletionTokens',
+                messages: 'api',
+                response_format: 'structuredOutput',
+            }),
+    };
+    const parameter = (status === 400 || status === 422) &&
+        typeof error?.param === 'string' &&
+        Object.hasOwn(parameters, error.param)
+        ? error.param
+        : undefined;
+    if (status === 400 || status === 422) {
+        category = 'request';
+        action =
+            parameter === undefined
+                ? 'Check the Agent Binding model, api, structuredOutput and token settings against the endpoint requirements. The rejected parameter is unknown.'
+                : `The provider reports a rejected ${parameter} parameter. Check ${parameters[parameter]} against the endpoint requirements.`;
+    }
+    else if (status === 401 || status === 403) {
+        category = status === 401 ? 'authentication' : 'permission';
+        action =
+            'Check the operator credential and account permissions for the reviewed HTTP grant. Keep credentials in the operator environment.';
+    }
+    else if (status === 402) {
+        category = 'account';
+        action = 'Check the selected account quota or balance and request token budget.';
+    }
+    else if (status === 404) {
+        category = 'endpoint';
+        action =
+            'Check the reviewed endpoint URL and selected model availability. The status alone does not distinguish a missing route from an unavailable model.';
+    }
+    else if (status === 429) {
+        category = 'capacity';
+        action =
+            'Check the selected account and model rate or quota limits before explicitly starting new work.';
+    }
+    else if (status >= 500) {
+        category = 'provider';
+        action =
+            'Check provider availability. This response does not establish whether remote work occurred.';
+    }
+    throw new AgentMethodError('INVALID_RESULT', `Agent ${api} endpoint returned HTTP ${status}. ${action} The endpoint returned a response; no automatic retry was attempted.`, Object.freeze({
+        phase: 'provider-response',
+        api,
+        status,
+        category,
+        retry: 'not-attempted',
+        ...(parameter === undefined ? {} : { parameter }),
+    }));
+}

package/dist/conversation.js

@@ -4,12 +4,33 @@ export class AgentConversationError extends AggregateError {
     turns;
     settlement;
     constructor(errors, turns, settlement) {
-        super(errors, 'Agent conversation did not complete cleanly', { cause: errors[0] });
+        super(errors, conversationFailureMessage(errors[0]), { cause: errors[0] });
         this.turns = turns;
         this.settlement = settlement;
         this.name = 'AgentConversationError';
     }
 }
+function conversationFailureMessage(error) {
+    const heading = 'Agent conversation did not complete cleanly';
+    if (!(error instanceof Error))
+        return heading;
+    // Reuse the error already exposed to this caller, without invoking getters
+    // or traversing arbitrary causes. Full primary/cleanup errors remain retained.
+    const message = Object.getOwnPropertyDescriptor(error, 'message')?.value;
+    if (typeof message !== 'string' || !message.trim())
+        return heading;
+    let summary = '';
+    let count = 0;
+    for (const character of message) {
+        if (count++ === 240)
+            return `${heading}: ${summary}…`;
+        // Error text is a diagnostic, not a JSON/0 application value. Preserve the
+        // full original cause, but keep its display summary valid portable text.
+        const point = character.charCodeAt(0);
+        summary += character.length === 1 && point >= 0xd800 && point <= 0xdfff ? '�' : character;
+    }
+    return `${heading}: ${summary}`;
+}
 function deferred() {
     let resolve;
     let reject;

package/dist/errors.d.ts

@@ -1,5 +1,7 @@
+import type { JsonObject } from './json.js';
 export type AgentMethodErrorCode = 'INVALID_INPUT' | 'RESOURCE_EXHAUSTED' | 'INVALID_RESULT';
 export declare class AgentMethodError extends Error {
     readonly code: AgentMethodErrorCode;
-    constructor(code: AgentMethodErrorCode, message: string);
+    readonly details?: JsonObject | undefined;
+    constructor(code: AgentMethodErrorCode, message: string, details?: JsonObject | undefined);
 }

package/dist/errors.js

@@ -1,8 +1,10 @@
 export class AgentMethodError extends Error {
     code;
-    constructor(code, message) {
+    details;
+    constructor(code, message, details) {
         super(message);
         this.code = code;
+        this.details = details;
         this.name = 'AgentMethodError';
     }
 }

package/dist/flow.js

@@ -1862,9 +1862,11 @@ function redirectApplicationConsole() {
 // src/errors.ts
 class AgentMethodError extends Error {
   code;
-  constructor(code, message) {
+  details;
+  constructor(code, message, details) {
     super(message);
     this.code = code;
+    this.details = details;
     this.name = "AgentMethodError";
   }
 }
@@ -2518,7 +2520,7 @@ function parseApiResult(result, api) {
   if (record?.outcome !== "done" || http === undefined || typeof http.status !== "number" || !Number.isInteger(http.status) || http.status < 200 || http.status > 599 || !Object.hasOwn(http, "body"))
     return invalid("HTTP slot returned invalid response evidence");
   if (http.status !== 200)
-    return invalid(`Agent endpoint returned HTTP ${http.status}; no automatic retry was attempted`);
+    return rejectedHttp(http.status, api, http.body);
   if (canonicalJson(http.body).byteLength > 12582912)
     throw new AgentMethodError("RESOURCE_EXHAUSTED", "Agent HTTP response exceeds 12 MiB");
   const body = ordinaryRecord(http.body);
@@ -2593,6 +2595,52 @@ function responsesResult(body) {
 function invalid(message) {
   throw new AgentMethodError("INVALID_RESULT", message);
 }
+function rejectedHttp(status, api, body) {
+  let category = "unexpected-status";
+  let action = "Check the selected endpoint and its documented API format.";
+  const error = ordinaryRecord(ordinaryRecord(body)?.error);
+  const parameters = {
+    model: "model",
+    store: "endpoint support for store: false",
+    ...api === "responses" ? {
+      max_output_tokens: "maxCompletionTokens",
+      input: "api",
+      "text.format": "structuredOutput"
+    } : {
+      max_completion_tokens: "maxCompletionTokens",
+      messages: "api",
+      response_format: "structuredOutput"
+    }
+  };
+  const parameter = (status === 400 || status === 422) && typeof error?.param === "string" && Object.hasOwn(parameters, error.param) ? error.param : undefined;
+  if (status === 400 || status === 422) {
+    category = "request";
+    action = parameter === undefined ? "Check the Agent Binding model, api, structuredOutput and token settings against the endpoint requirements. The rejected parameter is unknown." : `The provider reports a rejected ${parameter} parameter. Check ${parameters[parameter]} against the endpoint requirements.`;
+  } else if (status === 401 || status === 403) {
+    category = status === 401 ? "authentication" : "permission";
+    action = "Check the operator credential and account permissions for the reviewed HTTP grant. Keep credentials in the operator environment.";
+  } else if (status === 402) {
+    category = "account";
+    action = "Check the selected account quota or balance and request token budget.";
+  } else if (status === 404) {
+    category = "endpoint";
+    action = "Check the reviewed endpoint URL and selected model availability. The status alone does not distinguish a missing route from an unavailable model.";
+  } else if (status === 429) {
+    category = "capacity";
+    action = "Check the selected account and model rate or quota limits before explicitly starting new work.";
+  } else if (status >= 500) {
+    category = "provider";
+    action = "Check provider availability. This response does not establish whether remote work occurred.";
+  }
+  throw new AgentMethodError("INVALID_RESULT", `Agent ${api} endpoint returned HTTP ${status}. ${action} The endpoint returned a response; no automatic retry was attempted.`, Object.freeze({
+    phase: "provider-response",
+    api,
+    status,
+    category,
+    retry: "not-attempted",
+    ...parameter === undefined ? {} : { parameter }
+  }));
+}
 // src/index.ts
 var MAX_CONTENT_BYTES = 1048576;
 var encoder3 = new TextEncoder;
@@ -2771,7 +2819,7 @@ async function agentFlow(run) {
     return { outcome: resultValue.outcome, output: { ...resultValue.output } };
   } catch (error) {
     if (error instanceof AgentMethodError)
-      throw new OperationError(error.code, error.message);
+      throw new OperationError(error.code, error.message, error.details);
     throw error;
   }
 }

package/dist/index.d.ts

@@ -51,14 +51,14 @@ export interface PreparedAgent {
     readonly request: AgentTransportInput;
     readonly session?: AgentSessionRequest;
 }
-export interface AgentResult {
+export type AgentResult = {
     readonly outcome: 'done' | 'blocked' | 'limit';
     readonly output: {
         readonly text: string;
         readonly structured?: JsonValue;
         readonly session?: AgentSessionReceipt;
     };
-}
+};
 /** Independently check an Agent Flow result at its consumer's boundary. */
 export declare function checkAgentResult(value: unknown, responseSchema?: JsonObject): AgentResult;
 /** Prepare one bounded request. The returned data confers no execution authority. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jigging/agent-method",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.6",
   "description": "A reusable bounded Agent method with an ordinary FLOW entrypoint",
   "license": "MPL-2.0",
   "repository": {
@@ -47,7 +47,7 @@
     "test"
   ],
   "devDependencies": {
-    "@jigging/flow": "0.1.0-alpha.12",
+    "@jigging/flow": "0.1.0-alpha.13",
     "@types/node": "24.13.3",
     "typescript": "7.0.2"
   }

package/src/api.ts

@@ -91,8 +91,7 @@ export function parseApiResult(result: unknown, api: Api): AgentTransportResult
     !Object.hasOwn(http, 'body')
   )
     return invalid('HTTP slot returned invalid response evidence')
-  if (http.status !== 200)
-    return invalid(`Agent endpoint returned HTTP ${http.status}; no automatic retry was attempted`)
+  if (http.status !== 200) return rejectedHttp(http.status, api, http.body)
   if (canonicalJson(http.body as JsonObject).byteLength > 12_582_912)
     throw new AgentMethodError('RESOURCE_EXHAUSTED', 'Agent HTTP response exceeds 12 MiB')
   const body = ordinaryRecord(http.body)
@@ -189,3 +188,70 @@ function responsesResult(body: Record<string, unknown> | undefined): AgentTransp
 function invalid(message: string): never {
   throw new AgentMethodError('INVALID_RESULT', message)
 }
+
+function rejectedHttp(status: number, api: Api, body: unknown): never {
+  // Project status and exact known parameter names, never free-form text. Even an apparently
+  // harmless error field can contain credentials, input, or terminal controls.
+  let category = 'unexpected-status'
+  let action = 'Check the selected endpoint and its documented API format.'
+  const error = ordinaryRecord(ordinaryRecord(body)?.error)
+  const parameters: Record<string, string> = {
+    model: 'model',
+    store: 'endpoint support for store: false',
+    ...(api === 'responses'
+      ? {
+          max_output_tokens: 'maxCompletionTokens',
+          input: 'api',
+          'text.format': 'structuredOutput',
+        }
+      : {
+          max_completion_tokens: 'maxCompletionTokens',
+          messages: 'api',
+          response_format: 'structuredOutput',
+        }),
+  }
+  const parameter =
+    (status === 400 || status === 422) &&
+    typeof error?.param === 'string' &&
+    Object.hasOwn(parameters, error.param)
+      ? error.param
+      : undefined
+  if (status === 400 || status === 422) {
+    category = 'request'
+    action =
+      parameter === undefined
+        ? 'Check the Agent Binding model, api, structuredOutput and token settings against the endpoint requirements. The rejected parameter is unknown.'
+        : `The provider reports a rejected ${parameter} parameter. Check ${parameters[parameter]} against the endpoint requirements.`
+  } else if (status === 401 || status === 403) {
+    category = status === 401 ? 'authentication' : 'permission'
+    action =
+      'Check the operator credential and account permissions for the reviewed HTTP grant. Keep credentials in the operator environment.'
+  } else if (status === 402) {
+    category = 'account'
+    action = 'Check the selected account quota or balance and request token budget.'
+  } else if (status === 404) {
+    category = 'endpoint'
+    action =
+      'Check the reviewed endpoint URL and selected model availability. The status alone does not distinguish a missing route from an unavailable model.'
+  } else if (status === 429) {
+    category = 'capacity'
+    action =
+      'Check the selected account and model rate or quota limits before explicitly starting new work.'
+  } else if (status >= 500) {
+    category = 'provider'
+    action =
+      'Check provider availability. This response does not establish whether remote work occurred.'
+  }
+  throw new AgentMethodError(
+    'INVALID_RESULT',
+    `Agent ${api} endpoint returned HTTP ${status}. ${action} The endpoint returned a response; no automatic retry was attempted.`,
+    Object.freeze({
+      phase: 'provider-response',
+      api,
+      status,
+      category,
+      retry: 'not-attempted',
+      ...(parameter === undefined ? {} : { parameter }),
+    }),
+  )
+}

package/src/conversation.ts

@@ -65,11 +65,30 @@ export class AgentConversationError extends AggregateError {
     readonly turns: readonly AgentTurn[],
     readonly settlement?: RunResult,
   ) {
-    super(errors, 'Agent conversation did not complete cleanly', { cause: errors[0] })
+    super(errors, conversationFailureMessage(errors[0]), { cause: errors[0] })
     this.name = 'AgentConversationError'
   }
 }
 
+function conversationFailureMessage(error: unknown): string {
+  const heading = 'Agent conversation did not complete cleanly'
+  if (!(error instanceof Error)) return heading
+  // Reuse the error already exposed to this caller, without invoking getters
+  // or traversing arbitrary causes. Full primary/cleanup errors remain retained.
+  const message = Object.getOwnPropertyDescriptor(error, 'message')?.value
+  if (typeof message !== 'string' || !message.trim()) return heading
+  let summary = ''
+  let count = 0
+  for (const character of message) {
+    if (count++ === 240) return `${heading}: ${summary}…`
+    // Error text is a diagnostic, not a JSON/0 application value. Preserve the
+    // full original cause, but keep its display summary valid portable text.
+    const point = character.charCodeAt(0)
+    summary += character.length === 1 && point >= 0xd800 && point <= 0xdfff ? '�' : character
+  }
+  return `${heading}: ${summary}`
+}
+
 function deferred<T>() {
   let resolve!: (value: T) => void
   let reject!: (error: unknown) => void

package/src/errors.ts

@@ -1,9 +1,12 @@
+import type { JsonObject } from './json.js'
+
 export type AgentMethodErrorCode = 'INVALID_INPUT' | 'RESOURCE_EXHAUSTED' | 'INVALID_RESULT'
 
 export class AgentMethodError extends Error {
   constructor(
     readonly code: AgentMethodErrorCode,
     message: string,
+    readonly details?: JsonObject,
   ) {
     super(message)
     this.name = 'AgentMethodError'

package/src/flow.ts

@@ -56,7 +56,8 @@ export async function agentFlow(run: RunContext): Promise<RunResult> {
     const resultValue = finishAgent(prepared, parseApiResult(result, api))
     return { outcome: resultValue.outcome, output: { ...resultValue.output } }
   } catch (error) {
-    if (error instanceof AgentMethodError) throw new OperationError(error.code, error.message)
+    if (error instanceof AgentMethodError)
+      throw new OperationError(error.code, error.message, error.details)
     throw error
   }
 }

package/src/index.ts

@@ -64,7 +64,7 @@ export interface PreparedAgent {
   readonly session?: AgentSessionRequest
 }
 
-export interface AgentResult {
+export type AgentResult = {
   readonly outcome: 'done' | 'blocked' | 'limit'
   readonly output: {
     readonly text: string

package/test/api.test.ts

@@ -1,6 +1,7 @@
 import { expect, test } from 'bun:test'
 import { readFile } from 'node:fs/promises'
 import { parseApiResult, prepareApiRequest } from '../src/api.js'
+import { AgentMethodError } from '../src/errors.js'
 import { finishAgent, prepareAgent } from '../src/index.js'
 
 const prepared = prepareAgent({ instructions: 'Answer.' })
@@ -118,6 +119,95 @@ test('HTTP and malformed replies remain failures, without echoing provider data'
     expect(() => chatResult(result)).toThrow()
 })
 
+test('HTTP diagnostics identify safe status facts and corrective settings without provider text', () => {
+  const categories = [
+    [400, 'request'],
+    [422, 'request'],
+    [401, 'authentication'],
+    [403, 'permission'],
+    [402, 'account'],
+    [404, 'endpoint'],
+    [429, 'capacity'],
+    [500, 'provider'],
+    [301, 'unexpected-status'],
+  ] as const
+  for (const api of ['chat-completions', 'responses'] as const) {
+    for (const [status, category] of categories) {
+      let error: unknown
+      try {
+        parseApiResult(
+          {
+            outcome: 'done',
+            output: {
+              status,
+              body: {
+                error: {
+                  message: 'private-input-and-key\u001b[31m',
+                  code: 'secret',
+                  param: 'secret',
+                },
+              },
+            },
+          },
+          api,
+        )
+      } catch (failure) {
+        error = failure
+      }
+      if (!(error instanceof AgentMethodError)) throw new Error('Expected provider rejection')
+      expect(error.code).toBe('INVALID_RESULT')
+      expect(error.details).toEqual({
+        phase: 'provider-response',
+        api,
+        status,
+        category,
+        retry: 'not-attempted',
+      })
+      expect(error.message).toContain('no automatic retry')
+      expect(error.message).toContain('endpoint returned a response')
+      expect(JSON.stringify(error)).not.toContain('private-input-and-key')
+      expect(JSON.stringify(error)).not.toContain('secret')
+      if (status === 422) expect(error.message).toContain('rejected parameter is unknown')
+      if (status === 500) expect(error.message).toContain('whether remote work occurred')
+    }
+  }
+})
+
+test('only exact known API parameter names can be projected from provider rejection', () => {
+  for (const [api, parameter, setting] of [
+    ['chat-completions', 'max_completion_tokens', 'maxCompletionTokens'],
+    ['responses', 'text.format', 'structuredOutput'],
+  ] as const) {
+    for (const param of [parameter, 'unknown-secret', '__proto__', `${parameter}\u001b[31m`]) {
+      let error: unknown
+      try {
+        parseApiResult(
+          {
+            outcome: 'done',
+            output: {
+              status: 422,
+              body: {
+                error: { param, message: 'private-input-and-key' },
+              },
+            },
+          },
+          api,
+        )
+      } catch (failure) {
+        error = failure
+      }
+      if (!(error instanceof AgentMethodError)) throw new Error('Expected provider rejection')
+      if (param === parameter) {
+        expect(error.details?.parameter).toBe(parameter)
+        expect(error.message).toContain(`Check ${setting}`)
+      } else expect(error.details?.parameter).toBeUndefined()
+      expect(error.message).not.toContain('private-input-and-key')
+      expect(error.message).not.toContain('unknown-secret')
+      expect(error.message).not.toContain('\u001b')
+    }
+  }
+})
+
 test('complete answers, refusals and exhausted completions retain distinct outcomes', () => {
   expect(chatResult(response('Answer.', 'stop', { tool_calls: [] })).output.text).toBe('Answer.')
   expect(finishAgent(prepared, chatResult(response()))).toEqual({

package/test/conversation.test.ts

@@ -1,8 +1,33 @@
 import { expect, test } from 'bun:test'
+import { AgentConversationError } from '../src/conversation.js'
+
+test('conversation failure summary preserves a bounded already-exposed cause without getters', () => {
+  const cause = new Error('Agent endpoint returned HTTP401. Check operator authentication.')
+  const cleanup = new Error('Cleanup failed')
+  const failure = new AgentConversationError([cause, cleanup], [])
+  expect(failure.message).toContain(cause.message)
+  expect(failure.errors).toEqual([cause, cleanup])
+  expect(failure.cause).toBe(cause)
+  const hostile = new Error()
+  Object.defineProperty(hostile, 'message', {
+    get() {
+      throw new Error('must not read getter')
+    },
+  })
+  expect(new AgentConversationError([hostile], []).message).toBe(
+    'Agent conversation did not complete cleanly',
+  )
+  expect(
+    Array.from(new AgentConversationError([new Error('🙂'.repeat(1000))], []).message).length,
+  ).toBeLessThan(300)
+  const malformed = new Error('bad\ud800text')
+  expect(new AgentConversationError([malformed], []).message).toContain('bad�text')
+  expect(new AgentConversationError([malformed], []).cause).toBe(malformed)
+})
 
 /** Synthetic Agent host, real public SDK subprocess. No native-client qualification. */
 async function exercise(mode: string) {
-  const process = Bun.spawn([Bun.which('bun')!, `${import.meta.dir}/conversation-fixture.ts`], {
+  const process = Bun.spawn([globalThis.process.execPath, `${import.meta.dir}/conversation-fixture.ts`], {
     stdin: 'pipe',
     stdout: 'pipe',
     stderr: 'pipe',

package/test/fixtures/public-result-types.ts

@@ -0,0 +1,17 @@
+import { type AgentResult, checkAgentResult } from '@jigging/agent-method'
+import type { JsonValue, RunHandler } from '@jigging/flow'
+
+const result: AgentResult = checkAgentResult({ outcome: 'done', output: { text: 'answer' } })
+const direct: JsonValue = result
+const nested: JsonValue = { agent: result }
+const handler: RunHandler = async () => ({ outcome: 'done', output: result })
+
+void [direct, nested, handler]
+
+// @ts-expect-error Functions are not JSON values.
+const functionOutput: JsonValue = () => 'answer'
+// @ts-expect-error Undefined is not a JSON value.
+const undefinedOutput: JsonValue = undefined
+// @ts-expect-error Error objects are not JSON values.
+const errorOutput: JsonValue = new Error('unhandled')
+void [functionOutput, undefinedOutput, errorOutput]

package/test/pack.test.ts

@@ -60,6 +60,94 @@ test('ordinary packing retains editable source, registry dependencies and a stan
       ],
       { cwd: extracted, stdio: 'pipe' },
     )
+    // Exercise the packed entrypoint and real SDK wire, outside the workspace.
+    // The HTTP peer is deliberately inert: this is protocol evidence, not a
+    // provider or containment qualification.
+    const child = Bun.spawn([process.execPath, 'FLOW.ts'], {
+      cwd: extracted,
+      stdin: 'pipe',
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const timer = setTimeout(() => child.kill(), 10_000)
+    let calls = 0
+    let terminal: unknown
+    let buffer = ''
+    const stderr = new Response(child.stderr).text()
+    try {
+      child.stdin.write(
+        `${JSON.stringify({
+          jsonrpc: '2.0',
+          id: 'host:1',
+          method: 'flow/run',
+          params: {
+            protocol: 'run/0',
+            input: { instructions: 'private fixture input' },
+            settings: { model: 'fixture-model' },
+            attachments: {},
+            channels: {},
+            scratch: temporary,
+            deadlineUnixMs: Date.now() + 10_000,
+          },
+        })}\n`,
+      )
+      for await (const chunk of child.stdout) {
+        buffer += new TextDecoder().decode(chunk)
+        expect(buffer.length).toBeLessThan(64 * 1024)
+        while (true) {
+          const newline = buffer.indexOf('\n')
+          if (newline < 0) break
+          const frame = JSON.parse(buffer.slice(0, newline))
+          buffer = buffer.slice(newline + 1)
+          if (frame.method === 'flow/call') {
+            calls++
+            expect(frame.params.slot).toBe('http')
+            child.stdin.write(
+              `${JSON.stringify({
+                jsonrpc: '2.0',
+                id: frame.id,
+                result: {
+                  outcome: 'done',
+                  output: {
+                    status: 422,
+                    body: {
+                      error: {
+                        param: 'max_completion_tokens',
+                        message: 'private fixture input and key',
+                      },
+                    },
+                  },
+                },
+              })}\n`,
+            )
+          } else if (frame.id === 'host:1') {
+            terminal = frame
+            child.stdin.end()
+          }
+        }
+      }
+      // A clean protocol exit does not turn an operational error into success.
+      expect(await child.exited).toBe(0)
+      expect(calls).toBe(1)
+      expect(terminal).toMatchObject({
+        error: {
+          data: {
+            code: 'INVALID_RESULT',
+            details: {
+              status: 422,
+              parameter: 'max_completion_tokens',
+              retry: 'not-attempted',
+            },
+          },
+        },
+      })
+      expect(JSON.stringify(terminal)).not.toContain('private fixture input')
+      expect(await stderr).not.toContain('private fixture input')
+    } finally {
+      clearTimeout(timer)
+      child.kill()
+      await child.exited
+    }
     pack(extracted, repacked)
     const next = (await readdir(repacked)).filter((name) => name.endsWith('.tgz'))
     expect(next).toHaveLength(1)

package/test/public-result-types.test.ts

@@ -0,0 +1,52 @@
+import { test } from 'bun:test'
+import { execFileSync } from 'node:child_process'
+import { copyFile, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+test('public Agent results compose with FLOW JSON without casts', async () => {
+  const method = fileURLToPath(new URL('../', import.meta.url))
+  const flow = fileURLToPath(new URL('../../flow-sdk/', import.meta.url))
+  const consumer = await mkdtemp(join(tmpdir(), 'agent-public-types-'))
+  try {
+    await mkdir(join(consumer, 'node_modules/@jigging'), { recursive: true })
+    await symlink(method, join(consumer, 'node_modules/@jigging/agent-method'))
+    await symlink(flow, join(consumer, 'node_modules/@jigging/flow'))
+    await writeFile(join(consumer, 'package.json'), '{"private":true,"type":"module"}\n')
+    await copyFile(
+      new URL('./fixtures/public-result-types.ts', import.meta.url),
+      join(consumer, 'consumer.ts'),
+    )
+    const guide = await readFile(
+      new URL('../../../docs/jig/guide/conversations.md', import.meta.url),
+      'utf8',
+    )
+    const caller = Array.from(guide.matchAll(/```ts\n([\s\S]*?)\n```/g))
+      .map((match) => match[1])
+      .find((source) => source?.includes('await handle('))
+    if (!caller) throw new Error('The conversation guide must retain a complete caller.')
+    await writeFile(join(consumer, 'conversation.ts'), caller)
+    execFileSync(
+      process.execPath,
+      [
+        join(method, 'node_modules/typescript/bin/tsc'),
+        '--ignoreConfig',
+        '--noEmit',
+        '--strict',
+        '--exactOptionalPropertyTypes',
+        '--target',
+        'ES2022',
+        '--module',
+        'NodeNext',
+        '--moduleResolution',
+        'NodeNext',
+        'consumer.ts',
+        'conversation.ts',
+      ],
+      { cwd: consumer, stdio: 'pipe' },
+    )
+  } finally {
+    await rm(consumer, { recursive: true, force: true })
+  }
+})

package/test/skills-flow.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test } from 'bun:test'
-import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'
+import { mkdir, mkdtemp, realpath, rm, symlink, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
@@ -13,7 +13,9 @@ afterEach(async () => {
   for (const root of temporary.splice(0)) await rm(root, { recursive: true, force: true })
 })
 const fixture = async () => {
-  const root = await mkdtemp(join(tmpdir(), 'agent-method-test-'))
+  // macOS's temporary-directory spelling can itself traverse /var's symlink.
+  // Supply a canonical root so the reader still tests package symlink refusal.
+  const root = await realpath(await mkdtemp(join(tmpdir(), 'agent-method-test-')))
   temporary.push(root)
   await mkdir(join(root, 'skills', 'check'), { recursive: true })
   await writeFile(join(root, 'skills', 'check', 'SKILL.md'), 'Exact guidance.\n')
@@ -170,6 +172,32 @@ describe('ordinary Flow wiring', () => {
     expect(calls).toBe(1)
   })
 
+  test('provider response diagnostics cross the ordinary Flow error boundary once', async () => {
+    let calls = 0
+    const run = {
+      input: { instructions: 'private task' },
+      settings: { model: 'fixture-model' },
+      attachments: {},
+      channels: {},
+      signal: new AbortController().signal,
+      call: async () => {
+        calls++
+        return { outcome: 'done', output: { status: 422, body: { error: 'private task and key' } } }
+      },
+    } as unknown as RunContext
+    await expect(agentFlow(run)).rejects.toMatchObject({
+      code: 'INVALID_RESULT',
+      details: {
+        phase: 'provider-response',
+        api: 'chat-completions',
+        status: 422,
+        category: 'request',
+        retry: 'not-attempted',
+      },
+    })
+    expect(calls).toBe(1)
+  })
+
   test('selected Responses schema mode reaches HTTP once and returns a checked result', async () => {
     let calls = 0
     const signal = new AbortController().signal