agentfootprint 10.2.0 → 10.3.0

package/dist/esm/adapters/requestRefusal.js

@@ -1,10 +1,12 @@
 /** Request-contract refusals are terminal, not provider availability failures. */
 import { UnsupportedToolChoiceError } from './forcedToolChoice.js';
+import { UnsupportedNativeOutputError } from './nativeOutputSchema.js';
 import { UnsupportedThinkingError } from '../thinking/errors.js';
 import { UnsafeThinkingReplayError } from '../thinking/replay.js';
 /** Deliberately narrow: unrelated application errors keep their existing policy. */
 export function isRequestRefusal(error) {
     return (error instanceof UnsupportedToolChoiceError ||
+        error instanceof UnsupportedNativeOutputError ||
         error instanceof UnsupportedThinkingError ||
         error instanceof UnsafeThinkingReplayError);
 }

package/dist/esm/adapters/requestRefusal.js.map

@@ -1 +1 @@
-{"version":3,"file":"requestRefusal.js","sourceRoot":"","sources":["../../../src/adapters/requestRefusal.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,OAAO,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAElE,oFAAoF;AACpF,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,CACL,KAAK,YAAY,0BAA0B;QAC3C,KAAK,YAAY,wBAAwB;QACzC,KAAK,YAAY,yBAAyB,CAC3C,CAAC;AACJ,CAAC"}
+{"version":3,"file":"requestRefusal.js","sourceRoot":"","sources":["../../../src/adapters/requestRefusal.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,OAAO,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAElE,oFAAoF;AACpF,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,CACL,KAAK,YAAY,0BAA0B;QAC3C,KAAK,YAAY,4BAA4B;QAC7C,KAAK,YAAY,wBAAwB;QACzC,KAAK,YAAY,yBAAyB,CAC3C,CAAC;AACJ,CAAC"}

package/dist/esm/adapters/types.d.ts

@@ -318,6 +318,22 @@ export interface LLMRequest {
         readonly type: 'tool';
         readonly name: string;
     };
+    /**
+     * Constrain the model's TEXT answer to a JSON Schema with the provider's
+     * own structured output — `.outputSchema(parser, { strategy: 'native' })`.
+     * The Anthropic adapters write it as `output_config: { format }`
+     * (https://platform.claude.com/docs/en/build-with-claude/structured-outputs).
+     *
+     * Same rule as {@link toolChoice}: when `nativeOutputSchemaFor(provider,
+     * model)` answers false the agent refuses at run start, naming both, and an
+     * adapter that cannot put it on its wire refuses with an
+     * `UnsupportedNativeOutputError` before anything is sent — never drops it.
+     * The schema is the wire copy `nativeOutputFormat` built; send it as-is.
+     */
+    readonly outputFormat?: {
+        readonly type: 'json_schema';
+        readonly schema: Readonly<Record<string, unknown>>;
+    };
 }
 export interface LLMResponse {
     /** Ordered replay evidence, retained with the assistant message. */
@@ -421,6 +437,14 @@ export interface LLMResponse {
 export interface WireToolManifest {
     /** Tool names as they appear in the serialized body, in wire order. */
     readonly toolNames: readonly string[];
+    /**
+     * Present only when the serialized body carried a structured-output format
+     * (Anthropic's `output_config.format`) — its `type`, read back from the
+     * body. Absent means none crossed. A `strategy: 'native'` agent refuses a
+     * stated manifest without it: the provider declared the capability and the
+     * request went out unconstrained.
+     */
+    readonly outputFormat?: 'json_schema';
 }
 export interface LLMChunk {
     readonly tokenIndex: number;
@@ -680,6 +704,22 @@ export interface LLMProvider {
      * forward it as a value. `withFallback` intersects both sides per model.
      */
     readonly supportsForcedToolChoice?: (model: string) => boolean;
+    /**
+     * Whether this adapter puts {@link LLMRequest.outputFormat} on its wire —
+     * the provider's own structured output, `strategy: 'native'`. **Absence
+     * means NO**, for the reason `carriesForcedToolChoice` gives: a format that
+     * quietly vanishes costs the guarantee the strategy was chosen for. Declared
+     * by `anthropic()`, `browserAnthropic()` and the mock; read with
+     * `nativeOutputSchemaFor(provider, model)`. A WRAPPER must forward it;
+     * `withFallback` publishes the AND of its pair.
+     */
+    readonly carriesNativeOutputSchema?: boolean;
+    /**
+     * Optional per-model restriction on {@link carriesNativeOutputSchema}, the
+     * `supportsForcedToolChoice` twin: both must answer true. A plain function
+     * of the model id (no `this`); the adapter resolves its own shorthand.
+     */
+    readonly supportsNativeOutputSchema?: (model: string) => boolean;
     /**
      * `hooks` (v7.8) is optional and additive — implementations may declare
      * `complete(req)` with no second parameter and stay assignable. A LEAF

package/dist/esm/adapters/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/adapters/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAkOH;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAwB,MAAM,CAAC,MAAM,CAAC;IAC5E,MAAM;IACN,WAAW;CACZ,CAAC,CAAC;AAqpBH;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAsC,EACtC,UAAgC;IAEhC,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,UAAU,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAC5C,OAAO,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;AACxD,CAAC;AAqID;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAgGpD;uDACuD;AACvD,MAAM,UAAU,kBAAkB,CAChC,OAAoB;IAEpB,OAAO,OAAO,OAAO,CAAC,WAAW,KAAK,UAAU,CAAC;AACnD,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/adapters/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAkOH;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAwB,MAAM,CAAC,MAAM,CAAC;IAC5E,MAAM;IACN,WAAW;CACZ,CAAC,CAAC;AA6rBH;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAsC,EACtC,UAAgC;IAEhC,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,UAAU,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAC5C,OAAO,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;AACxD,CAAC;AAqID;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAgGpD;uDACuD;AACvD,MAAM,UAAU,kBAAkB,CAChC,OAAoB;IAEpB,OAAO,OAAO,OAAO,CAAC,WAAW,KAAK,UAAU,CAAC;AACnD,CAAC"}

package/dist/esm/core/Agent.d.ts

@@ -812,6 +812,12 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      * on validation failure.
      */
     parseOutputAsync<T = unknown>(raw: string): Promise<T>;
+    /**
+     * A typed answer that failed: rethrow, or — with `.outputFallback()` and an
+     * `OutputSchemaError` — hand it to the 3-tier fallback. The one settle for
+     * `parseOutputAsync`'s parse failure and `runTyped`'s native stop failure.
+     */
+    private settleTypedFailure;
     /**
      * Corrective re-asks the agent's LAST run paid for, read off its own ledger.
      *
@@ -1425,6 +1431,16 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      * even show was broken.
      */
     private assertForcedToolChoiceSupported;
+    /**
+     * Refuse, at run start, a `'native'` output strategy on a provider that
+     * does not put a structured-output format on its wire, or on a model that
+     * does not take one — the `assertForcedToolChoiceSupported` twin, for the
+     * same reasons: run start because a decorated provider is only what it is
+     * once composed; a refusal because `'instruct'` asks in prose for what this
+     * strategy constrains at decoding, and a quiet swap would be config that
+     * lies.
+     */
+    private assertNativeOutputSchemaSupported;
     private createExecutor;
     /**
      * File the run-configuration manifest (9.41.0) — which adapters and

package/dist/esm/core/Agent.js

@@ -20,6 +20,7 @@ import { PolicyHaltError } from '../security/PolicyHaltError.js';
 import { updateSkillHistory as updateSkillHistoryStage } from '../cache/CacheGateDecider.js';
 import { cacheStrategyFor } from '../cache/cacheStrategyFor.js';
 import { forcedToolChoiceFor, UnsupportedToolChoiceError } from '../adapters/forcedToolChoice.js';
+import { nativeOutputSchemaFor, UnsupportedNativeOutputError, } from '../adapters/nativeOutputSchema.js';
 import { isRequestRefusal } from '../adapters/requestRefusal.js';
 import { assistantReplayFields } from './agent/assistantReplay.js';
 import { buildBrainFor, describeServingBrain } from './agent/skillBrains.js';
@@ -1423,29 +1424,38 @@ export class Agent extends RunnerBase {
             return applyOutputSchema(raw, parser);
         }
         catch (err) {
-            if (!this.outputFallbackCfg || !(err instanceof OutputSchemaError))
-                throw err;
-            // Engage the 3-tier fallback. The dispatcher gives us the
-            // typed-event entry; we synthesize a minimal event shape since
-            // these events have no per-stage anchor.
-            // Typed via `OutputFallbackEmit`, so the registry — not a grep — is what
-            // decides these two names are real. The cast is now only the envelope
-            // assembly (type + payload are already checked against the event map).
-            const emit = (eventType, payload) => {
-                try {
-                    this.dispatcher.dispatch({
-                        type: eventType,
-                        timestamp: Date.now(),
-                        payload,
-                    });
-                }
-                catch {
-                    /* observability errors must not poison the fallback path */
-                }
-            };
-            return applyOutputFallback(raw, parser, this.outputFallbackCfg, emit, err, this.lastRunRetriesSpent());
+            return this.settleTypedFailure(raw, err);
         }
     }
+    /**
+     * A typed answer that failed: rethrow, or — with `.outputFallback()` and an
+     * `OutputSchemaError` — hand it to the 3-tier fallback. The one settle for
+     * `parseOutputAsync`'s parse failure and `runTyped`'s native stop failure.
+     */
+    async settleTypedFailure(raw, err) {
+        const parser = this.outputSchemaParser;
+        if (!this.outputFallbackCfg || !(err instanceof OutputSchemaError))
+            throw err;
+        // Engage the 3-tier fallback. The dispatcher gives us the
+        // typed-event entry; we synthesize a minimal event shape since
+        // these events have no per-stage anchor.
+        // Typed via `OutputFallbackEmit`, so the registry — not a grep — is what
+        // decides these two names are real. The cast is now only the envelope
+        // assembly (type + payload are already checked against the event map).
+        const emit = (eventType, payload) => {
+            try {
+                this.dispatcher.dispatch({
+                    type: eventType,
+                    timestamp: Date.now(),
+                    payload,
+                });
+            }
+            catch {
+                /* observability errors must not poison the fallback path */
+            }
+        };
+        return applyOutputFallback(raw, parser, this.outputFallbackCfg, emit, err, this.lastRunRetriesSpent());
+    }
     /**
      * Corrective re-asks the agent's LAST run paid for, read off its own ledger.
      *
@@ -1484,6 +1494,15 @@ export class Agent extends RunnerBase {
             throw new Error('Agent.runTyped: run paused — typed mode does not support pauses. ' +
                 'Use agent.run() + agent.parseOutput(...) after resume.');
         }
+        // `strategy: 'native'`: an answer whose last attempt failed on a refusal
+        // or truncation stop is refused here even when its text parses — the
+        // format did not hold for it (outputEnforcement.ts · nativeStopFailure).
+        // FIRST, before any delivery path. It takes the same path a parse failure
+        // takes, `.outputFallback()` included.
+        const stopped = this.outputEnforcement?.outputFormat !== undefined ? this.outputContractUnmet() : undefined;
+        if (stopped?.stopReason !== undefined) {
+            return this.settleTypedFailure(out, new OutputSchemaError(stopped.error, { rawOutput: out, stage: stopped.stage }));
+        }
         if (this.answerValidationConfig !== undefined) {
             // The validator judged the schema's JSON output. Do not run a transforming
             // or stateful parser again and hand back a value the validator never saw.
@@ -2991,9 +3010,38 @@ export class Agent extends RunnerBase {
             `{ strategy: 'instruct', retries: N } on this provider — it works on every wire — or ` +
             `run the forced strategy on a provider that declares the capability.`);
     }
+    /**
+     * Refuse, at run start, a `'native'` output strategy on a provider that
+     * does not put a structured-output format on its wire, or on a model that
+     * does not take one — the `assertForcedToolChoiceSupported` twin, for the
+     * same reasons: run start because a decorated provider is only what it is
+     * once composed; a refusal because `'instruct'` asks in prose for what this
+     * strategy constrains at decoding, and a quiet swap would be config that
+     * lies.
+     */
+    assertNativeOutputSchemaSupported() {
+        if (this.outputEnforcement?.outputFormat === undefined)
+            return;
+        const first = this.reliabilityConfig?.providers?.[0];
+        const provider = first?.provider ?? this.provider;
+        const model = first?.model ?? this.model;
+        if (provider.carriesNativeOutputSchema === true) {
+            // A configured agent resolves its model at seed; callLLM judges it there.
+            if ((first === undefined && this.runConfigFn !== undefined) ||
+                nativeOutputSchemaFor(provider, model))
+                return;
+            throw new UnsupportedNativeOutputError({ provider: provider.name, model });
+        }
+        throw new Error(`Agent: .outputSchema(parser, { strategy: 'native' }) needs a provider that puts a ` +
+            `structured-output format on its wire, and '${provider.name}' does not declare one. ` +
+            `anthropic(), browserAnthropic() and the mock do; the Bedrock and gateway adapters do ` +
+            `not in this release. Use { strategy: 'instruct', retries: N } on this provider — it ` +
+            `works on every wire — or run the native strategy on a provider that declares it.`);
+    }
     createExecutor(runOptions) {
         this.assertDeliverableRoles();
         this.assertForcedToolChoiceSupported();
+        this.assertNativeOutputSchemaSupported();
         const correlationId = runOptions?.correlationId;
         const traceId = runOptions?.traceId ?? runOptions?.env?.traceId;
         const sessionId = runOptions?.sessionId;
@@ -4620,6 +4668,10 @@ export class Agent extends RunnerBase {
             ...(this.outputEnforcement?.schemaTool !== undefined && {
                 schemaTool: this.outputEnforcement.schemaTool,
             }),
+            // The structured-output format, under `strategy: 'native'` only.
+            ...(this.outputEnforcement?.outputFormat !== undefined && {
+                outputFormat: this.outputEnforcement.outputFormat,
+            }),
             ...(this.thinkingBudget !== undefined && { thinkingBudget: this.thinkingBudget }),
             // Only a configured agent reads `scope.resolvedModel` — see the dep's
             // JSDoc for why this is a build-time flag and not a runtime fallback.
@@ -4751,7 +4803,7 @@ export class Agent extends RunnerBase {
         answerArmed ? true : undefined);
         const routeDecider = this.answerValidationConfig === undefined
             ? baseRouteDecider
-            : withAnswerValidation(baseRouteDecider, this.answerValidationConfig, this.outputSchemaParser, artifactStore, () => this.consentOutstanding.size > 0);
+            : withAnswerValidation(baseRouteDecider, this.answerValidationConfig, this.outputSchemaParser, artifactStore, () => this.consentOutstanding.size > 0, this.outputEnforcement?.outputFormat !== undefined);
         // `.limitsTravelWithTheAnswer()` on a TYPED answer — decided once, here.
         // An output schema makes the answer JSON, and the appended block would
         // make it JSON followed by prose, which `runTyped()` cannot parse. So the