@theoremjs/agents 0.3.4-next.524.g5000023 → 0.3.4-next.528.g44c76f9

package/esm/src/guardrails/error.d.ts

@@ -18,6 +18,10 @@ declare function errorCopyText(copy: ErrorCopies, labels?: LabelOverrides): stri
 declare function publicError(err: unknown, labels?: LabelOverrides): string;
 /** Raw diagnostic for hosts, traces, and logs; never shown to end users. Each cause that says something new follows on its own line. */
 declare function describeError(err: unknown): string;
+/** fetch rejects only when no response came back, so any non-abort, non-timeout rejection is `network`. */
+declare function networkError(err: unknown): unknown;
+/** `send`, with a failed send or body read named as `networkError` names it. */
+declare function sendOrNetworkError(send: typeof fetch, ...args: Parameters<typeof fetch>): Promise<Response>;
 type ProducedError = TurnEventOf<'error'> & {
     errorInternal: string;
 };
@@ -28,4 +32,4 @@ declare function withPublicLabels(event: TurnEvent, labels?: LabelOverrides): Tu
 export type { ErrorCopies, ErrorCopy, ErrorKind, TheoremErrorOptions } from './theorem-error.js';
 export { ERROR_KINDS } from './theorem-error.js';
 export type { ProducedError };
-export { describeError, errorCopyText, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, publicError, TheoremError, throwIfAborted, toErrorEvent, withPublicLabels, };
+export { describeError, errorCopyText, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, networkError, publicError, sendOrNetworkError, TheoremError, throwIfAborted, toErrorEvent, withPublicLabels, };

package/esm/src/guardrails/error.js

@@ -88,6 +88,49 @@ function describeError(err) {
     }
     return lines.join('\n');
 }
+/** fetch rejects only when no response came back, so any non-abort, non-timeout rejection is `network`. */
+function networkError(err) {
+    if (err instanceof TheoremError || isAbortError(err) || isTimeoutError(err)) {
+        return err;
+    }
+    return new TheoremError('network', describeError(err), { cause: err });
+}
+/** `response` with a body whose read that fails is named as `networkError` names it. */
+function bodyOrNetworkError(response) {
+    if (!response.body)
+        return response;
+    const reader = response.body.getReader();
+    const body = new ReadableStream({
+        async pull(controller) {
+            try {
+                const next = await reader.read();
+                if (next.done)
+                    controller.close();
+                else
+                    controller.enqueue(next.value);
+            }
+            catch (err) {
+                controller.error(networkError(err));
+            }
+        },
+        cancel: (reason) => reader.cancel(reason),
+    }, { highWaterMark: 0 });
+    const named = new Response(body, response);
+    Object.defineProperties(named, {
+        url: { value: response.url },
+        redirected: { value: response.redirected },
+    });
+    return named;
+}
+/** `send`, with a failed send or body read named as `networkError` names it. */
+async function sendOrNetworkError(send, ...args) {
+    try {
+        return bodyOrNetworkError(await send(...args));
+    }
+    catch (err) {
+        throw networkError(err);
+    }
+}
 /** No user wording yet: `withPublicLabels` adds it where the event reaches the host, the one place that knows the profile. */
 function toErrorEvent(err) {
     return {
@@ -112,4 +155,4 @@ function withPublicLabels(event, labels) {
     return event;
 }
 export { ERROR_KINDS } from './theorem-error.js';
-export { describeError, errorCopyText, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, publicError, TheoremError, throwIfAborted, toErrorEvent, withPublicLabels, };
+export { describeError, errorCopyText, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, networkError, publicError, sendOrNetworkError, TheoremError, throwIfAborted, toErrorEvent, withPublicLabels, };

package/esm/src/guardrails/network.js

@@ -1,4 +1,4 @@
-import { TheoremError } from './error.js';
+import { sendOrNetworkError, TheoremError } from './error.js';
 /**
  * IPv4 ranges refused outright:
  * - Loopback: 127.0.0.0/8
@@ -265,7 +265,7 @@ export async function fetchGuarded(url, init, options) {
                 sent.set(name, value);
             }
         }
-        const response = await fetchFn(target.href, {
+        const response = await sendOrNetworkError(fetchFn, target.href, {
             ...init,
             method,
             headers: sent,
@@ -305,7 +305,7 @@ export function dnsOverHttpsResolver(options) {
         const url = new URL(options.endpoint);
         url.searchParams.set('name', hostname);
         url.searchParams.set('type', String(type));
-        const response = await fetchFn(url.href, {
+        const response = await sendOrNetworkError(fetchFn, url.href, {
             headers: { accept: 'application/dns-json' },
             ...(signal ? { signal } : {}),
         });

package/esm/src/kernel/engine/decision.d.ts

@@ -5,16 +5,26 @@ import type { KernelRegistry } from '../registry/kernel-registry.js';
 import type { DecisionProfile, DecisionRequest, DecisionResult } from '../types.js';
 /** Each decision failure code, and the error kind it reads as. */
 declare const DECISION_ERROR_KINDS: {
+    readonly invalid_config: "config";
     readonly invalid_request: "request";
+    readonly invalid_input: "input";
+    readonly not_allowed: "action";
     readonly authentication: "auth";
     readonly permission: "auth";
     readonly rate_limited: "rate_limit";
+    readonly busy: "busy";
+    readonly unsupported: "unsupported";
     readonly unavailable: "unavailable";
     readonly network: "network";
     readonly timeout: "timeout";
     readonly cancelled: "cancelled";
     readonly malformed_response: "bad_response";
+    readonly refused: "safety";
+    readonly blocked: "blocked";
     readonly disclosure_blocked: "blocked";
+    readonly declined: "declined";
+    readonly failed: "failed";
+    readonly internal: "internal";
 };
 /**
  * A normalized native-decision failure; response bodies are deliberately omitted. What the

package/esm/src/kernel/engine/decision.js

@@ -1,4 +1,4 @@
-import { TheoremError, throwIfAborted } from '../../guardrails/error.js';
+import { errorKind, TheoremError, throwIfAborted } from '../../guardrails/error.js';
 import { labelText } from '../../guardrails/labels.js';
 import { traceJson } from '../../observability/trace-span.js';
 import { guardedCall } from '../provider-runtime.js';
@@ -8,16 +8,47 @@ import { tracedCall } from './call-trace.js';
 import { referencedAssets } from './decision-references.js';
 /** Each decision failure code, and the error kind it reads as. */
 const DECISION_ERROR_KINDS = {
+    invalid_config: 'config',
     invalid_request: 'request',
+    invalid_input: 'input',
+    not_allowed: 'action',
     authentication: 'auth',
     permission: 'auth',
     rate_limited: 'rate_limit',
+    busy: 'busy',
+    unsupported: 'unsupported',
     unavailable: 'unavailable',
     network: 'network',
     timeout: 'timeout',
     cancelled: 'cancelled',
     malformed_response: 'bad_response',
+    refused: 'safety',
+    blocked: 'blocked',
     disclosure_blocked: 'blocked',
+    declined: 'declined',
+    failed: 'failed',
+    internal: 'internal',
+};
+/** Each kind's code: a thrown failure keeps its kind. */
+const DECISION_CODES = {
+    config: 'invalid_config',
+    request: 'invalid_request',
+    input: 'invalid_input',
+    action: 'not_allowed',
+    auth: 'authentication',
+    rate_limit: 'rate_limited',
+    busy: 'busy',
+    unsupported: 'unsupported',
+    unavailable: 'unavailable',
+    bad_response: 'malformed_response',
+    network: 'network',
+    timeout: 'timeout',
+    safety: 'refused',
+    blocked: 'blocked',
+    declined: 'declined',
+    failed: 'failed',
+    cancelled: 'cancelled',
+    internal: 'internal',
 };
 /**
  * A normalized native-decision failure; response bodies are deliberately omitted. What the
@@ -363,25 +394,10 @@ function recordResult(root, result) {
 function decisionProviderError(error) {
     if (error instanceof DecisionError)
         return error;
-    const kind = error instanceof TheoremError
-        ? error.kind
-        : error instanceof TypeError
-            ? 'network'
-            : 'bad_response';
-    const codes = {
-        auth: 'authentication',
-        rate_limit: 'rate_limited',
-        network: 'network',
-        busy: 'unavailable',
-        unavailable: 'unavailable',
-        timeout: 'timeout',
-        cancelled: 'cancelled',
-        request: 'invalid_request',
-        unsupported: 'invalid_request',
-    };
+    const kind = errorKind(error);
     const code = kind === 'auth' && isRecord(error) && error.status === 403
         ? 'permission'
-        : (codes[kind] ?? 'malformed_response');
+        : DECISION_CODES[kind];
     return new DecisionError(code, 
     // why: A framework failure's message holds no response body, and says what stopped the decision.
     error instanceof TheoremError ? error.message : labelText('provider.decision_failed'), isRecord(error) && typeof error.status === 'number' ? error.status : undefined, { cause: error });

package/esm/src/kernel/tools/coordinate.js

@@ -1,7 +1,7 @@
 import { TheoremError, throwIfAborted } from '../../guardrails/error.js';
 import { labelText } from '../../guardrails/labels.js';
 import { jsonObjectSchema } from '../json.js';
-import { operationUnavailable, operationWireValue, toolInvocationHash, toolOperationOutcomeSchema, } from './operation.js';
+import { operationBroken, operationWireValue, toolInvocationHash, toolOperationOutcomeSchema, } from './operation.js';
 class ReplayedOperation {
     outcome;
     constructor(outcome) {
@@ -41,7 +41,7 @@ class CoordinatedExecution {
         if (result.kind === 'running' || result.kind === 'uncertain')
             throw uncertainError();
         if (result.kind !== 'acquired' || typeof result.claimToken !== 'string' || !result.claimToken)
-            throw operationUnavailable();
+            throw operationBroken("The tool coordinator's begin returned no claim"); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         this.claim = { ...operation, claimToken: result.claimToken };
         throwIfAborted(this.signal);
         return this.claim;
@@ -64,7 +64,7 @@ class CoordinatedExecution {
             return undefined;
         }
         if (!this.terminal)
-            throw operationUnavailable();
+            throw operationBroken('The tool run ended with no terminal event'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         const { modelResult, outputRaw, failure, awaiting, denied, callNotStarted, aborted, pendingInject, } = settlement;
         const effects = this.claim ? (failure ? 'unknown' : 'completed') : 'not_started';
         const outcome = {
@@ -96,7 +96,7 @@ class CoordinatedExecution {
         if (saved.event.tool.operationId !== operationId ||
             saved.event.tool.callId !== callId ||
             saved.event.tool.name !== toolId)
-            throw operationUnavailable();
+            throw operationBroken("The tool coordinator's saved outcome is another operation's"); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         this.committed = true;
         return saved;
     }
@@ -122,7 +122,7 @@ export async function* coordinateTool(coordinator, identity, invocation, signal,
         throw uncertainError();
     if (existing?.kind === 'settled') {
         if (!authorizeReplay)
-            throw operationUnavailable();
+            throw operationBroken('A settled tool operation has no replay check'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         const saved = execution.replay(new ReplayedOperation(existing.outcome));
         await authorizeReplay(saved);
         throwIfAborted(signal);
@@ -146,7 +146,7 @@ export async function* coordinateTool(coordinator, identity, invocation, signal,
     catch (error) {
         if (error instanceof ReplayedOperation) {
             if (!authorizeReplay)
-                throw operationUnavailable();
+                throw operationBroken('A settled tool operation has no replay check'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
             const saved = execution.replay(error);
             await authorizeReplay(saved);
             yield saved.event;

package/esm/src/kernel/tools/execute.js

@@ -16,7 +16,7 @@ import { dispatchToolBody, failedActivity, failedActivityOf, failureEvent, messa
 import { HandlerEvents } from './handler-events.js';
 import { fetchToolImages } from './image-fetch.js';
 import { formatToolFailureForModel, formatToolResult, frameToolFailure } from './model-text.js';
-import { operationUnavailable, operationWireValue } from './operation.js';
+import { operationBroken, operationWireValue } from './operation.js';
 import { checkPermission, gateDetails, isGateResumeDenied, isGateResumeGranted, isResumeContinuation, } from './permission.js';
 import { executeHttpTool, executeMcpTool, failureWithoutSecret, modelResultFromOutput, omitSecret, outcomeFromUnauth, parseToolOutput, refusedCredentialOutcome, resolveToolAuth, withMedia, } from './remote.js';
 import { extractLoadedIds, profileToolAllow, profileToolsSpec, promoteLoadedTools, } from './resolve.js';
@@ -467,13 +467,14 @@ async function* receivePageAnswer(tool, ctx, claim, base) {
     const execution = ctx.pageExecution;
     if (tool.answeredBy !== 'page' || !execution)
         return ctx;
-    if (!claim?.invocation)
-        throw operationUnavailable();
+    if (!claim?.invocation) {
+        throw new TheoremError('config', `Page tool '${tool.name}' needs a tool execution coordinator (execution)`);
+    }
     const argumentsForPage = jsonObjectSchema.parse(operationWireValue(claim.invocation.preparedInput));
     const dispatch = await execution.dispatch(claim, ctx.signal);
     throwIfAborted(ctx.signal);
     if (!dispatch.grantId)
-        throw operationUnavailable();
+        throw operationBroken('The page dispatch returned no grantId'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     yield toolEvent(base, {
         phase: 'dispatch',
         grantId: dispatch.grantId,

package/esm/src/kernel/tools/memory-execution.js

@@ -1,4 +1,5 @@
-import { operationUnavailable, } from './operation.js';
+import { TheoremError } from '../../guardrails/error.js';
+import { operationBroken, } from './operation.js';
 /** How many operations a memory coordinator tracks before it refuses new ones. */
 const DEFAULT_MEMORY_EXECUTION_LIMIT = 256;
 /**
@@ -23,6 +24,8 @@ export function createMemoryToolExecution(options = {}) {
         const record = records.get(keyOf(claim));
         return record?.state === 'running' && record.claimToken === claim.claimToken;
     };
+    const full = () => new TheoremError('config', `The memory tool coordinator holds its maxOperations of ${limit}`);
+    const notHeld = () => operationBroken('The memory tool coordinator holds no running claim for this token'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     return {
         lookup: (operation) => Promise.resolve(known(operation)),
         begin: (operation) => {
@@ -30,28 +33,29 @@ export function createMemoryToolExecution(options = {}) {
             if (earlier)
                 return Promise.resolve(earlier);
             if (records.size >= limit)
-                return Promise.reject(operationUnavailable());
+                return Promise.reject(full());
             const claimToken = crypto.randomUUID();
             records.set(keyOf(operation), { state: 'running', claimToken });
             return Promise.resolve({ kind: 'acquired', claimToken });
         },
         settle: (claim, outcome) => {
             if (!holds(claim))
-                return Promise.reject(operationUnavailable());
+                return Promise.reject(notHeld());
             records.set(keyOf(claim), { state: 'settled', outcome });
             return Promise.resolve();
         },
         settleNotStarted: (operation, outcome) => {
-            if (records.has(keyOf(operation)))
-                return Promise.reject(operationUnavailable());
+            if (records.has(keyOf(operation))) {
+                return Promise.reject(operationBroken('The memory tool coordinator already has a record for this operation'));
+            }
             if (records.size >= limit)
-                return Promise.reject(operationUnavailable());
+                return Promise.reject(full());
             records.set(keyOf(operation), { state: 'settled', outcome });
             return Promise.resolve();
         },
         markUncertain: (claim) => {
             if (!holds(claim))
-                return Promise.reject(operationUnavailable());
+                return Promise.reject(notHeld());
             records.set(keyOf(claim), { state: 'uncertain' });
             return Promise.resolve();
         },

package/esm/src/kernel/tools/operation.d.ts

@@ -67,7 +67,8 @@ export interface ToolExecutionCoordinator {
     settleNotStarted(operation: ToolOperationIdentity, outcome: ToolOperationOutcome): Promise<void>;
     markUncertain(claim: ToolOperationClaim, reason: ToolOperationUncertainty): Promise<void>;
 }
-export declare function operationUnavailable(): TheoremError;
+/** A coordinator, a page dispatch or the kernel broke the tool-operation contract. */
+export declare function operationBroken(reason: string): TheoremError;
 export declare function toolInvocationHash(value: unknown): Promise<string>;
 export declare const toolOperationOutcomeSchema: z.ZodType<ToolOperationOutcome>;
 export declare function operationWireValue(value: unknown): JsonValue;

package/esm/src/kernel/tools/operation.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { publicError, TheoremError } from '../../guardrails/error.js';
+import { TheoremError } from '../../guardrails/error.js';
 import { errorKindSchema, guardrailHit, provenance } from '../../guardrails/event-schemas.js';
 import { jsonObjectSchema, jsonValueSchema } from '../json.js';
 import { interactionPartSchema, TURN_EVENT_SCHEMAS, turnHistoryMessageSchema, } from '../turn-events.js';
@@ -7,10 +7,9 @@ export const savedToolInvocationSchema = z.strictObject({
     accepted: jsonObjectSchema,
     preparedInput: jsonValueSchema,
 });
-export function operationUnavailable() {
-    const error = new TheoremError('unavailable', '');
-    error.message = publicError(error);
-    return error;
+/** A coordinator, a page dispatch or the kernel broke the tool-operation contract. */
+export function operationBroken(reason) {
+    return new TheoremError('internal', reason);
 }
 export async function toolInvocationHash(value) {
     const ordered = (item) => {
@@ -78,20 +77,23 @@ export function operationWireValue(value) {
         if (!item || typeof item !== 'object')
             return item;
         if (ancestors.has(item))
-            throw operationUnavailable();
+            throw operationBroken('Tool operation value has a cycle'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         const prototype = Object.getPrototypeOf(item);
         if (!Array.isArray(item) && prototype !== Object.prototype && prototype !== null) {
-            throw operationUnavailable();
+            throw operationBroken('Tool operation value holds an object that is not plain data'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        if (Object.hasOwn(item, '__proto__')) {
+            throw operationBroken('Tool operation value has an own __proto__ key'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         }
-        if (Object.hasOwn(item, '__proto__'))
-            throw operationUnavailable();
         ancestors.add(item);
         try {
             if (Array.isArray(item))
                 return item.map(normalize);
             const entries = Object.entries(Object.getOwnPropertyDescriptors(item));
-            if (entries.some(([, descriptor]) => descriptor.get || descriptor.set))
-                throw operationUnavailable();
+            const accessor = entries.find(([, descriptor]) => descriptor.get || descriptor.set);
+            if (accessor) {
+                throw operationBroken(`Tool operation value has a getter or setter at '${accessor[0]}'`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            }
             return Object.fromEntries(entries
                 .filter(([, descriptor]) => descriptor.enumerable && descriptor.value !== undefined)
                 .map(([key, descriptor]) => [key, normalize(descriptor.value)]));

package/esm/src/kernel/tools/remote.js

@@ -382,13 +382,20 @@ async function* remoteAuthAndPreBody(args) {
         ...(authRes.audience ? { audience: authRes.audience } : {}),
     };
 }
+/** A thrown request's code: a kind with a code of its own, else `request_failed`. */
+const THROWN_CODES = {
+    network: 'network_error',
+    cancelled: 'cancelled',
+    timeout: 'timeout',
+};
 function* thrownOutcome(err, checks) {
     if (errorKind(err) === 'blocked') {
         const blocked = networkBlockedEvent();
         checks.record(blocked);
         return failureOutcome(yield* networkBlocked(err, blocked), false);
     }
-    return failureOutcome({ code: 'network_error', kind: 'network', message: messageOf(err) }, false);
+    const kind = errorKind(err);
+    return failureOutcome({ code: THROWN_CODES[kind] ?? 'request_failed', kind, message: messageOf(err) }, false);
 }
 const OMIT_CREDENTIAL = '[omitted - credential]';
 /** The most of an error or unparseable body quoted back in a failure message. */

package/esm/src/providers/shared/retry.js

@@ -1,5 +1,4 @@
-import { TheoremError } from '../../guardrails/error.js';
-import { networkError } from './upstream-tap.js';
+import { networkError, TheoremError } from '../../guardrails/error.js';
 const BACKOFF_MS = [1000, 2000, 4000, 8000];
 /** All the waiting one call may do between tries; a wait that would pass it sends the last answer back. */
 export const WAIT_BUDGET_MS = 5000;

package/esm/src/providers/shared/upstream-tap.d.ts

@@ -3,6 +3,4 @@ export declare function tapeHeaderValue(key: string, value: string): string;
 export declare function tapeHeaders(headers?: HeadersInit): Record<string, string>;
 export declare function throwRow(err: unknown): Record<string, unknown>;
 export declare function tapFetch(tap: ModelRequest['tapUpstream'], send?: typeof fetch, keySlot?: KeySlot): typeof fetch;
-/** fetch rejects only when no response came back, so any non-abort, non-timeout rejection is `network`. */
-export declare function networkError(err: unknown): unknown;
 export declare function networkFetch(send?: typeof fetch): typeof fetch;

package/esm/src/providers/shared/upstream-tap.js

@@ -1,4 +1,4 @@
-import { describeError, isAbortError, isTimeoutError, TheoremError, } from '../../guardrails/error.js';
+import { sendOrNetworkError } from '../../guardrails/error.js';
 const SECRET_HEADER = /key|auth|cookie|secret|token/i;
 export function tapeHeaderValue(key, value) {
     if (SECRET_HEADER.test(key)) {
@@ -66,20 +66,6 @@ export function tapFetch(tap, send = fetch, keySlot) {
         }
     };
 }
-/** fetch rejects only when no response came back, so any non-abort, non-timeout rejection is `network`. */
-export function networkError(err) {
-    if (err instanceof TheoremError || isAbortError(err) || isTimeoutError(err)) {
-        return err;
-    }
-    return new TheoremError('network', describeError(err), { cause: err });
-}
 export function networkFetch(send = fetch) {
-    return async (url, init) => {
-        try {
-            return await send(url, init);
-        }
-        catch (err) {
-            throw networkError(err);
-        }
-    };
+    return (url, init) => sendOrNetworkError(send, url, init);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/agents",
-  "version": "0.3.4-next.524.g5000023",
+  "version": "0.3.4-next.528.g44c76f9",
   "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
   "keywords": [
     "agent",