agentfootprint 10.2.0 → 10.3.0

package/dist/esm/core/agent/nativeOutputFormat.d.ts

@@ -0,0 +1,85 @@
+/**
+ * nativeOutputFormat — the ONE builder of the JSON Schema that
+ * `.outputSchema(parser, { strategy: 'native' })` sends as the provider's
+ * structured-output format (Anthropic's `output_config.format`).
+ *
+ * Pattern: pure transform over plain JSON, run once at build
+ *          (`AgentBuilder · resolveOutputEnforcement`); no scope, no I/O.
+ * Role:    core/ agent leaf. Its input is the SAME schema the `'tool-forced'`
+ *          strategy puts on its synthetic tool (`outputEnforcement.ts ·
+ *          resolveJsonSchema`: the `jsonSchema` option, else the parser's own
+ *          `toJsonSchema()`), and the SAME parser judges every answer after —
+ *          so the wire copy may be looser than the contract, never different
+ *          from it.
+ *
+ * THE RULES, from Anthropic's structured-outputs page ("JSON Schema
+ * limitations", fetched 2026-10-14 —
+ * https://platform.claude.com/docs/en/build-with-claude/structured-outputs),
+ * and the shape of the SDK's own transform (`@anthropic-ai/sdk` ·
+ * `transformJSONSchema`, which moves what the API does not take into the
+ * description):
+ *   - KEPT: `type`, `properties`, `required`, `items`, `anyOf`, `allOf`,
+ *     local `$ref` with `$defs` / `definitions`, `enum` and `const` of
+ *     scalars, `default`, `description`, `title`, the ten supported string
+ *     `format`s, `minItems` of 0 or 1, and a `pattern` with no backreference,
+ *     lookaround or word boundary. `oneOf` is sent as `anyOf`.
+ *   - CLOSED: every object gets `additionalProperties: false` — the only value
+ *     the API takes.
+ *   - MOVED INTO THE DESCRIPTION, on the wire copy only: every constraint the
+ *     API does not take (`minimum`, `maximum`, `multipleOf`, `minLength`,
+ *     `maxLength`, `minItems` above 1 — sent as 1 —, `maxItems`, an
+ *     unsupported `format` or `pattern`, …). The model still reads them; the
+ *     parser still enforces them.
+ *   - REFUSED BY NAME (`NativeOutputSchemaError`): what the API cannot express
+ *     — a recursive schema, an external or dangling `$ref` (checked on the
+ *     source AND on the wire copy, whose renamed paths a reference could
+ *     miss), an `enum` or `const` holding an object or array, `allOf` beside
+ *     a `$ref`, a node with no type (an open `unknown` value), and an object
+ *     with open keys (`additionalProperties` given a schema, `true` or `{}`
+ *     on an object naming no properties, a bare `{ type: 'object' }`, or
+ *     `patternProperties`: closing it would make every map empty while the
+ *     parser accepted it).
+ *   - DROPPED: the meta keys `$schema`, `$id`, `$comment`, `$anchor`.
+ *
+ * THE RESERVED `_findings` KEY. With `.findings()` armed, the instruction tells
+ * the model it may carry its standings on a JSON answer as a top-level
+ * `_findings.previous`. Under `additionalProperties: false` a key the schema
+ * does not name cannot be written at all, so the answer standings would stop
+ * without a sound. Armed, the root gains the optional `_findings` property
+ * the served contract allows (`findings/reserved.ts · findingsAnswerSchema`) —
+ * unless the author's schema names its own `_findings`, which wins; a root
+ * that is not an object cannot carry it and is refused. Unarmed, the schema
+ * is the author's alone.
+ *
+ * @example
+ *   nativeOutputFormat(
+ *     { type: 'object', properties: { n: { type: 'integer', minimum: 1 } }, required: ['n'] },
+ *     { findings: false },
+ *   );
+ *   // { type: 'json_schema', schema: { type: 'object',
+ *   //   properties: { n: { type: 'integer', description: '{minimum: 1}' } },
+ *   //   required: ['n'], additionalProperties: false } }
+ */
+type Json = Readonly<Record<string, unknown>>;
+/** What `LLMRequest.outputFormat` carries. */
+export interface NativeOutputFormat {
+    readonly type: 'json_schema';
+    readonly schema: Json;
+}
+/** A schema the provider's structured output cannot express, named. */
+export declare class NativeOutputSchemaError extends Error {
+    /** JSON-pointer-like path of the node refused (`'#'` is the root). */
+    readonly path: string;
+    constructor(path: string, reason: string);
+}
+/**
+ * The structured-output format for `jsonSchema`, made API-compatible as the
+ * file header lists, with the reserved `_findings` property when the findings
+ * ledger is armed. Deep-frozen; the input is never edited.
+ *
+ * @throws NativeOutputSchemaError naming the node the API cannot express.
+ */
+export declare function nativeOutputFormat(jsonSchema: Json, arms: {
+    readonly findings: boolean;
+}): NativeOutputFormat;
+export {};

package/dist/esm/core/agent/nativeOutputFormat.js

@@ -0,0 +1,384 @@
+/**
+ * nativeOutputFormat — the ONE builder of the JSON Schema that
+ * `.outputSchema(parser, { strategy: 'native' })` sends as the provider's
+ * structured-output format (Anthropic's `output_config.format`).
+ *
+ * Pattern: pure transform over plain JSON, run once at build
+ *          (`AgentBuilder · resolveOutputEnforcement`); no scope, no I/O.
+ * Role:    core/ agent leaf. Its input is the SAME schema the `'tool-forced'`
+ *          strategy puts on its synthetic tool (`outputEnforcement.ts ·
+ *          resolveJsonSchema`: the `jsonSchema` option, else the parser's own
+ *          `toJsonSchema()`), and the SAME parser judges every answer after —
+ *          so the wire copy may be looser than the contract, never different
+ *          from it.
+ *
+ * THE RULES, from Anthropic's structured-outputs page ("JSON Schema
+ * limitations", fetched 2026-10-14 —
+ * https://platform.claude.com/docs/en/build-with-claude/structured-outputs),
+ * and the shape of the SDK's own transform (`@anthropic-ai/sdk` ·
+ * `transformJSONSchema`, which moves what the API does not take into the
+ * description):
+ *   - KEPT: `type`, `properties`, `required`, `items`, `anyOf`, `allOf`,
+ *     local `$ref` with `$defs` / `definitions`, `enum` and `const` of
+ *     scalars, `default`, `description`, `title`, the ten supported string
+ *     `format`s, `minItems` of 0 or 1, and a `pattern` with no backreference,
+ *     lookaround or word boundary. `oneOf` is sent as `anyOf`.
+ *   - CLOSED: every object gets `additionalProperties: false` — the only value
+ *     the API takes.
+ *   - MOVED INTO THE DESCRIPTION, on the wire copy only: every constraint the
+ *     API does not take (`minimum`, `maximum`, `multipleOf`, `minLength`,
+ *     `maxLength`, `minItems` above 1 — sent as 1 —, `maxItems`, an
+ *     unsupported `format` or `pattern`, …). The model still reads them; the
+ *     parser still enforces them.
+ *   - REFUSED BY NAME (`NativeOutputSchemaError`): what the API cannot express
+ *     — a recursive schema, an external or dangling `$ref` (checked on the
+ *     source AND on the wire copy, whose renamed paths a reference could
+ *     miss), an `enum` or `const` holding an object or array, `allOf` beside
+ *     a `$ref`, a node with no type (an open `unknown` value), and an object
+ *     with open keys (`additionalProperties` given a schema, `true` or `{}`
+ *     on an object naming no properties, a bare `{ type: 'object' }`, or
+ *     `patternProperties`: closing it would make every map empty while the
+ *     parser accepted it).
+ *   - DROPPED: the meta keys `$schema`, `$id`, `$comment`, `$anchor`.
+ *
+ * THE RESERVED `_findings` KEY. With `.findings()` armed, the instruction tells
+ * the model it may carry its standings on a JSON answer as a top-level
+ * `_findings.previous`. Under `additionalProperties: false` a key the schema
+ * does not name cannot be written at all, so the answer standings would stop
+ * without a sound. Armed, the root gains the optional `_findings` property
+ * the served contract allows (`findings/reserved.ts · findingsAnswerSchema`) —
+ * unless the author's schema names its own `_findings`, which wins; a root
+ * that is not an object cannot carry it and is refused. Unarmed, the schema
+ * is the author's alone.
+ *
+ * @example
+ *   nativeOutputFormat(
+ *     { type: 'object', properties: { n: { type: 'integer', minimum: 1 } }, required: ['n'] },
+ *     { findings: false },
+ *   );
+ *   // { type: 'json_schema', schema: { type: 'object',
+ *   //   properties: { n: { type: 'integer', description: '{minimum: 1}' } },
+ *   //   required: ['n'], additionalProperties: false } }
+ */
+import { findingsAnswerSchema } from './findings/reserved.js';
+import { RESERVED_ANSWER_KEY } from './findings/types.js';
+/** A schema the provider's structured output cannot express, named. */
+export class NativeOutputSchemaError extends Error {
+    /** JSON-pointer-like path of the node refused (`'#'` is the root). */
+    path;
+    constructor(path, reason) {
+        super(`AgentBuilder.outputSchema: strategy 'native' sends the schema as Anthropic's ` +
+            `output_config.format, and the node at ${path} cannot be expressed there: ${reason} ` +
+            `Change the schema, or use { strategy: 'instruct', retries: N }, which takes any ` +
+            `parser and judges the same contract.`);
+        this.name = 'NativeOutputSchemaError';
+        this.path = path;
+    }
+}
+const SUPPORTED_FORMATS = new Set([
+    'date-time',
+    'time',
+    'date',
+    'duration',
+    'email',
+    'hostname',
+    'uri',
+    'ipv4',
+    'ipv6',
+    'uuid',
+]);
+const META_KEYS = new Set(['$schema', '$id', '$comment', '$anchor']);
+/** Annotations kept as they are (the docs list `default`; the rest are words). */
+const KEPT_AS_IS = new Set(['description', 'title', 'default', 'required']);
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isObjectNode(node) {
+    const type = node.type;
+    return (type === 'object' ||
+        (Array.isArray(type) && type.includes('object')) ||
+        isObject(node.properties));
+}
+/** A pattern the API's regex subset refuses: a backreference, lookaround or word boundary. */
+function unsupportedPattern(pattern) {
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === '\\') {
+            const next = pattern[i + 1];
+            if (next !== undefined && /[1-9kbB]/.test(next))
+                return true;
+            i++;
+            continue;
+        }
+        if (ch === '(' && pattern[i + 1] === '?') {
+            const rest = pattern.slice(i + 2, i + 4);
+            if (rest.startsWith('=') || rest.startsWith('!') || rest === '<=' || rest === '<!')
+                return true;
+        }
+    }
+    return false;
+}
+function deepFreeze(value) {
+    if (typeof value === 'object' && value !== null && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+// ─── Refusals that need the whole schema: $ref resolution ─────────────
+function resolvePointer(root, ref) {
+    if (ref === '#')
+        return root;
+    if (!ref.startsWith('#/'))
+        return undefined;
+    let node = root;
+    for (const raw of ref.slice(2).split('/')) {
+        let key;
+        try {
+            key = decodeURIComponent(raw).replace(/~1/g, '/').replace(/~0/g, '~');
+        }
+        catch {
+            return undefined; // a malformed escape points at nothing — refused by name below
+        }
+        if (typeof node !== 'object' || node === null)
+            return undefined;
+        node = node[key];
+    }
+    return node;
+}
+/**
+ * Refuse an external, dangling or recursive `$ref`. A depth-first walk that
+ * expands each local reference with the chain of references being expanded
+ * (`open`); meeting one of them again is recursion. A reference fully
+ * expanded once without meeting itself is `settled` and not walked again.
+ */
+function assertReferencesExpressible(root, copy) {
+    const settled = new Set();
+    const open = new Set();
+    const walk = (node, path) => {
+        if (Array.isArray(node)) {
+            node.forEach((child, i) => walk(child, `${path}/${i}`));
+            return;
+        }
+        if (!isObject(node))
+            return;
+        const ref = node.$ref;
+        if (typeof ref === 'string') {
+            if (!ref.startsWith('#')) {
+                throw new NativeOutputSchemaError(path, `'$ref': '${ref}' is an external reference, and only references inside the ` +
+                    `schema ('#/$defs/…') are supported.`);
+            }
+            if (open.has(ref)) {
+                throw new NativeOutputSchemaError(path, `'$ref': '${ref}' refers back into a definition it is part of — a recursive ` +
+                    `schema, which is not supported.`);
+            }
+            if (!settled.has(ref)) {
+                const target = resolvePointer(root, ref);
+                if (!isObject(target)) {
+                    throw new NativeOutputSchemaError(path, copy === 'source'
+                        ? `'$ref': '${ref}' points at nothing in this schema.`
+                        : `'$ref': '${ref}' points into a part of the schema the wire copy does not ` +
+                            `keep at that path (oneOf is sent as anyOf; keywords the API does not take ` +
+                            `move into the description). Point it at a $defs entry.`);
+                }
+                open.add(ref);
+                walk(target, ref);
+                open.delete(ref);
+                settled.add(ref);
+            }
+        }
+        // Definitions are walked too, referenced or not: a definition that
+        // reaches itself is recursive either way, and an unreferenced one is
+        // still sent.
+        for (const [key, child] of Object.entries(node)) {
+            if (key !== '$ref')
+                walk(child, `${path}/${key}`);
+        }
+    };
+    open.add('#');
+    walk(root, '#');
+}
+// ─── The node transform ───────────────────────────────────────────────
+function describe(node, moved) {
+    const entries = Object.entries(moved);
+    if (entries.length === 0)
+        return;
+    const words = `{${entries.map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(', ')}}`;
+    const existing = typeof node.description === 'string' ? node.description : undefined;
+    node.description = existing ? `${existing}\n\n${words}` : words;
+}
+function transformNode(node, path) {
+    if (!isObject(node)) {
+        throw new NativeOutputSchemaError(path, 'a schema must be an object, and this one is not.');
+    }
+    const has = (key) => Object.prototype.hasOwnProperty.call(node, key);
+    if (!has('type') &&
+        !has('anyOf') &&
+        !has('oneOf') &&
+        !has('allOf') &&
+        !has('$ref') &&
+        !has('enum') &&
+        !has('const')) {
+        throw new NativeOutputSchemaError(path, 'it has no type — an open value (z.unknown(), z.any(), {}) is any JSON at all, which ' +
+            'the structured output cannot decode without recursion. Give it a type.');
+    }
+    if (Array.isArray(node.enum) && node.enum.some((v) => typeof v === 'object' && v !== null)) {
+        throw new NativeOutputSchemaError(path, 'its enum holds an object or an array; enum values must be strings, numbers, ' +
+            'booleans or null.');
+    }
+    if (typeof node.const === 'object' && node.const !== null) {
+        throw new NativeOutputSchemaError(path, 'its const is an object or an array; a const must be a string, number, boolean or null.');
+    }
+    if (has('allOf') &&
+        Array.isArray(node.allOf) &&
+        node.allOf.some((s) => isObject(s) && has$ref(s))) {
+        throw new NativeOutputSchemaError(path, 'allOf with a $ref inside it is not supported.');
+    }
+    // Open keys: a map whose entries the API could never produce once closed.
+    // A value schema for the extra keys, a pattern for them, or an object that
+    // names no properties and does not say it is closed (`{ type: 'object' }`,
+    // `additionalProperties: true` or `{}` — zod's `z.record(…)` emits these).
+    const namesNoProperties = !isObject(node.properties) || Object.keys(node.properties).length === 0;
+    if (has('patternProperties') ||
+        (isObject(node.additionalProperties) && Object.keys(node.additionalProperties).length > 0) ||
+        (isObjectNode(node) && namesNoProperties && node.additionalProperties !== false)) {
+        throw new NativeOutputSchemaError(path, 'it is an object with open keys (a record or map: additionalProperties given a schema ' +
+            'or left open, or patternProperties). The API takes only additionalProperties: false, ' +
+            'which would make every such map empty while the parser accepted it. Name the keys as ' +
+            'properties.');
+    }
+    // A reference stands alone, as the SDK's transform sends it: its target
+    // carries the shape, and siblings beside a `$ref` are not part of the subset
+    // — except the definitions it may point into (a root `$ref` beside its
+    // `definitions`, as zod-to-json-schema writes with a name).
+    if (has('$ref')) {
+        const ref = { $ref: node.$ref };
+        for (const key of ['$defs', 'definitions']) {
+            if (isObject(node[key]))
+                ref[key] = transformDefinitions(node[key], `${path}/${key}`);
+        }
+        return ref;
+    }
+    const out = {};
+    const moved = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (META_KEYS.has(key))
+            continue;
+        switch (key) {
+            case 'type':
+            case 'enum':
+            case 'const':
+                out[key] = value;
+                break;
+            case 'properties':
+                if (isObject(value)) {
+                    out.properties = Object.fromEntries(Object.entries(value).map(([name, child]) => [
+                        name,
+                        transformNode(child, `${path}/properties/${name}`),
+                    ]));
+                }
+                else
+                    moved[key] = value;
+                break;
+            case 'items':
+                if (isObject(value))
+                    out.items = transformNode(value, `${path}/items`);
+                else
+                    moved[key] = value;
+                break;
+            case 'anyOf':
+            case 'oneOf':
+            case 'allOf':
+                if (Array.isArray(value)) {
+                    const target = key === 'allOf' ? 'allOf' : 'anyOf';
+                    out[target] = value.map((child, i) => transformNode(child, `${path}/${key}/${i}`));
+                }
+                else
+                    moved[key] = value;
+                break;
+            case '$defs':
+            case 'definitions':
+                if (isObject(value))
+                    out[key] = transformDefinitions(value, `${path}/${key}`);
+                else
+                    moved[key] = value;
+                break;
+            case 'format':
+                if (SUPPORTED_FORMATS.has(value))
+                    out.format = value;
+                else
+                    moved[key] = value;
+                break;
+            case 'pattern':
+                if (typeof value === 'string' && !unsupportedPattern(value))
+                    out.pattern = value;
+                else
+                    moved[key] = value;
+                break;
+            case 'minItems':
+                if (value === 0 || value === 1)
+                    out.minItems = value;
+                else {
+                    moved[key] = value;
+                    if (typeof value === 'number' && value > 1)
+                        out.minItems = 1;
+                }
+                break;
+            case 'additionalProperties':
+                // `true`, `{}` or `false`: closed below. A schema was refused above.
+                break;
+            default:
+                if (KEPT_AS_IS.has(key))
+                    out[key] = value;
+                else
+                    moved[key] = value;
+        }
+    }
+    if (isObjectNode(node)) {
+        if (out.properties === undefined)
+            out.properties = {};
+        out.additionalProperties = false;
+    }
+    describe(out, moved);
+    return out;
+}
+function transformDefinitions(defs, path) {
+    return Object.fromEntries(Object.entries(defs).map(([name, child]) => [name, transformNode(child, `${path}/${name}`)]));
+}
+function has$ref(node) {
+    return Object.prototype.hasOwnProperty.call(node, '$ref');
+}
+// ─── The one entry point ──────────────────────────────────────────────
+/**
+ * The structured-output format for `jsonSchema`, made API-compatible as the
+ * file header lists, with the reserved `_findings` property when the findings
+ * ledger is armed. Deep-frozen; the input is never edited.
+ *
+ * @throws NativeOutputSchemaError naming the node the API cannot express.
+ */
+export function nativeOutputFormat(jsonSchema, arms) {
+    let source = jsonSchema;
+    if (arms.findings) {
+        if (!isObjectNode(jsonSchema)) {
+            throw new NativeOutputSchemaError('#', `.findings() lets a JSON answer carry its standings as a top-level ` +
+                `'${RESERVED_ANSWER_KEY}' property, and this root is not an object schema with ` +
+                `properties, so the structured output would refuse the key and the standings would ` +
+                `stop. Give the answer an object root.`);
+        }
+        const properties = isObject(jsonSchema.properties) ? jsonSchema.properties : {};
+        if (!Object.prototype.hasOwnProperty.call(properties, RESERVED_ANSWER_KEY)) {
+            source = {
+                ...jsonSchema,
+                properties: { ...properties, [RESERVED_ANSWER_KEY]: findingsAnswerSchema() },
+            };
+        }
+    }
+    assertReferencesExpressible(source, 'source');
+    const schema = transformNode(source, '#');
+    // And again on what is SENT: a reference into a path the copy renamed or
+    // moved would dangle on the wire, a 400 on every call.
+    assertReferencesExpressible(schema, 'wire');
+    return deepFreeze({ type: 'json_schema', schema });
+}
+//# sourceMappingURL=nativeOutputFormat.js.map

package/dist/esm/core/agent/nativeOutputFormat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nativeOutputFormat.js","sourceRoot":"","sources":["../../../../src/core/agent/nativeOutputFormat.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/agent/outputEnforcement.d.ts

@@ -33,7 +33,7 @@
  * after it — there is no trailing sentence for injected text to pre-empt.
  * Identical reasoning, identical shape, to the compaction frame.
  */
-import type { LLMMessage, LLMResponse, LLMToolSchema } from '../../adapters/types.js';
+import type { LLMMessage, LLMRequest, LLMResponse, LLMToolSchema } from '../../adapters/types.js';
 import { type OutputSchemaParser } from '../outputSchema.js';
 /**
  * One row per final-answer attempt an enforcing agent made, in order.
@@ -76,7 +76,21 @@ export interface OutputAttempt {
      * converge.
      */
     readonly brokenBy?: string;
+    /**
+     * Set when the attempt failed because the provider STOPPED, not because the
+     * text failed the parser: a `strategy: 'native'` answer that ended with a
+     * {@link NativeStopReason}, where the structured-output format does not
+     * hold. Such an answer fails even when it parses; a `'refusal'` is never
+     * re-asked (the row is `'exhausted'` at once).
+     */
+    readonly stopReason?: NativeStopReason;
 }
+/**
+ * The stops under which a structured-output format does not hold: a refusal,
+ * and the two truncations — the answer's own cap (`'max_tokens'`) and the
+ * context window (`'model_context_window_exceeded'`).
+ */
+export type NativeStopReason = 'refusal' | 'max_tokens' | 'model_context_window_exceeded';
 /** The scope surface this file needs. Structurally a `TypedScope<AgentState>`. */
 export interface OutputLedgerScope {
     outputAttempts?: readonly OutputAttempt[];
@@ -97,7 +111,22 @@ export interface OutputFailure {
      *  friends attach the real error there); fall back to the wrapper's. */
     readonly error: string;
     readonly path?: string;
+    /** The provider's stop that failed the attempt — see `OutputAttempt.stopReason`. */
+    readonly stopReason?: NativeStopReason;
 }
+/**
+ * Fail a `strategy: 'native'` answer by its stop reason, before the parser.
+ *
+ * Anthropic's structured-outputs page: on `stop_reason: "refusal"` "the output
+ * may not match your schema because the refusal message takes precedence",
+ * and on `"max_tokens"` "the output may be incomplete and not match your
+ * schema". So the format was not in force for this text, and an answer that
+ * happens to parse is still not one the format produced — delivering it as
+ * constrained would be a silent pass. Returns `undefined` under any other
+ * strategy or stop. The words are the library's own, naming the stop; the
+ * failure then takes the ordinary path (retry, or exhausted and unmet).
+ */
+export declare function nativeStopFailure(enforcement: Pick<ResolvedOutputEnforcement, 'outputFormat'>, stopReason: string | undefined): OutputFailure | undefined;
 /**
  * Flatten whatever the parser threw into {@link OutputFailure}.
  *
@@ -178,6 +207,9 @@ export interface ResolvedOutputEnforcement {
     readonly retries: number;
     /** The synthetic tool, pre-built. Present only under `'tool-forced'`. */
     readonly schemaTool?: LLMToolSchema;
+    /** The structured-output format, pre-built by `nativeOutputFormat`.
+     *  Present only under `'native'`. */
+    readonly outputFormat?: NonNullable<LLMRequest['outputFormat']>;
     /** True when `.outputFallback()` is configured. The decider carries it so
      *  the unmet-contract signal can say that a tier exists which `run()` does
      *  not reach — the fallback itself lives at the caller's boundary. */

package/dist/esm/core/agent/outputEnforcement.js

@@ -50,6 +50,39 @@ export function recordOutputAttempt(scope, row) {
     // deep-proxy view, and the commit must be detached plain data.
     scope.outputAttempts = [...prev, row];
 }
+/**
+ * Fail a `strategy: 'native'` answer by its stop reason, before the parser.
+ *
+ * Anthropic's structured-outputs page: on `stop_reason: "refusal"` "the output
+ * may not match your schema because the refusal message takes precedence",
+ * and on `"max_tokens"` "the output may be incomplete and not match your
+ * schema". So the format was not in force for this text, and an answer that
+ * happens to parse is still not one the format produced — delivering it as
+ * constrained would be a silent pass. Returns `undefined` under any other
+ * strategy or stop. The words are the library's own, naming the stop; the
+ * failure then takes the ordinary path (retry, or exhausted and unmet).
+ */
+export function nativeStopFailure(enforcement, stopReason) {
+    if (enforcement.outputFormat === undefined)
+        return undefined;
+    if (stopReason !== 'refusal' &&
+        stopReason !== 'max_tokens' &&
+        stopReason !== 'model_context_window_exceeded')
+        return undefined;
+    // Quoted to the model on a re-ask (`buildCorrectiveTurn`), so it states the
+    // past fact only — no advice to the developer, no destination.
+    return {
+        stage: 'schema-validate',
+        error: stopReason === 'refusal'
+            ? "The provider stopped with stop_reason 'refusal': the model declined, and the " +
+                'structured-output format does not hold for a refusal, so this text is not accepted ' +
+                'as the answer even where it parses.'
+            : `The provider stopped with stop_reason '${stopReason}': the answer was cut off ` +
+                'before it was complete, so the structured-output format does not hold for it and it ' +
+                'is not accepted even where it parses.',
+        stopReason,
+    };
+}
 /**
  * Flatten whatever the parser threw into {@link OutputFailure}.
  *

package/dist/esm/core/agent/outputEnforcement.js.map

@@ -1 +1 @@
-{"version":3,"file":"outputEnforcement.js","sourceRoot":"","sources":["../../../../src/core/agent/outputEnforcement.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"outputEnforcement.js","sourceRoot":"","sources":["../../../../src/core/agent/outputEnforcement.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/agent/stages/answerValidation.d.ts

@@ -12,4 +12,4 @@ import type { RouteBranch } from './route.js';
  * as its result, and a composition mounting the chart took `'final'` for the
  * agent's answer. Routed on, the chart ends with no answer and the verdict in
  * its state (`core/terminalVerdict.ts`). */
-export declare function withAnswerValidation(decide: (scope: TypedScope<AgentState>) => RouteBranch | Promise<RouteBranch>, config: ResolvedAnswerValidation, parser: OutputSchemaParser<unknown> | undefined, store: ArtifactStore | undefined, hasOutstandingConsent: () => boolean): (scope: TypedScope<AgentState>) => Promise<RouteBranch>;
+export declare function withAnswerValidation(decide: (scope: TypedScope<AgentState>) => RouteBranch | Promise<RouteBranch>, config: ResolvedAnswerValidation, parser: OutputSchemaParser<unknown> | undefined, store: ArtifactStore | undefined, hasOutstandingConsent: () => boolean, nativeOutput?: boolean): (scope: TypedScope<AgentState>) => Promise<RouteBranch>;