@agen-ai/agent-runtime 0.4.3 → 0.4.4

package/dist/outputValidation.d.ts

@@ -1,6 +1,7 @@
 import { type AgentCapabilities, type AgentCollaborationId, type AgentGeneratedResourceId, type AgentOperationInvocationId, type AgentProviderKey, type AgentSessionId, type AgentTurnId } from "@agen-ai/agent-protocol";
 import { type AgentProviderOutput } from "./outputs.js";
 import type { AgentProviderOperationResult } from "./sessions.js";
+import type { AgentStructuredOutputBinding } from "./structuredOutput/admission.js";
 export interface AgentProviderOutputValidationContext {
     readonly capabilities: AgentCapabilities;
     readonly providerKey: AgentProviderKey;
@@ -10,6 +11,7 @@ export interface AgentProviderOutputValidationContext {
     readonly operationInvocationId?: AgentOperationInvocationId;
     readonly collaborationId?: AgentCollaborationId;
     readonly generatedResourceId?: AgentGeneratedResourceId;
+    readonly structuredOutputBinding?: AgentStructuredOutputBinding;
 }
 export declare function validateAgentProviderOutputForContext(candidate: AgentProviderOutput, context: AgentProviderOutputValidationContext): AgentProviderOutput;
 export declare function validateAgentProviderOperationResult(candidate: AgentProviderOperationResult, context: AgentProviderOutputValidationContext): AgentProviderOperationResult;

package/dist/outputValidation.js

@@ -1,10 +1,14 @@
 import {
-  parseAgentError
+  AGENT_PROTOCOL_EVENT_BYTES_LIMIT,
+  agentProtocolSerializedJsonBytes,
+  parseAgentError,
+  parseAgentEvent
 } from "@agen-ai/agent-protocol";
 import { throwAgentProviderContractError } from "./contractErrors.js";
 import {
   validateAgentProviderOutput
 } from "./outputs.js";
+import { validateAgentStructuredOutputResult } from "./structuredOutput/validation.js";
 function unsupportedCapabilitySemantic(value) {
   throw new TypeError(
     `Unsupported Agent Protocol capability semantic: ${String(value)}.`
@@ -206,6 +210,30 @@ function validateAgentProviderOutputForContext(candidate, context) {
     );
   }
   assertOutputCapability(context, output);
+  if (output.kind === "event" && output.event.type === "turn.completed") {
+    let structuredOutput = validateAgentStructuredOutputResult({
+      providerKey: context.providerKey,
+      ...context.structuredOutputBinding === void 0 ? {} : { binding: context.structuredOutputBinding },
+      result: output.event.payload.structuredOutput
+    });
+    if (output.event.payload.outcome !== "completed") return output;
+    let event = {
+      ...output.event,
+      payload: { ...output.event.payload, structuredOutput }
+    };
+    if (structuredOutput.kind === "unavailable" && structuredOutput.reason === "schema_mismatch" && structuredOutput.issues !== void 0 && agentProtocolSerializedJsonBytes(event) > AGENT_PROTOCOL_EVENT_BYTES_LIMIT) {
+      structuredOutput = Object.freeze({ kind: "unavailable", reason: "schema_mismatch" });
+      event = { ...event, payload: { ...event.payload, structuredOutput } };
+    }
+    parseAgentEvent(event);
+    return Object.freeze({
+      ...output,
+      event: Object.freeze({
+        ...event,
+        payload: Object.freeze(event.payload)
+      })
+    });
+  }
   return output;
 }
 function validateAgentProviderOperationResult(candidate, context) {

package/dist/sessionInteractions/lifetime.d.ts

@@ -49,6 +49,7 @@ export declare class SessionInteractionOwner {
     constructor(providerKey: AgentProviderKey, sessionId: AgentSessionId, context: AgentSessionInteractionContext, validationOwner: AgentSessionValidationOwner, operation: AgentSessionInteractionOpeningOperation, support: AgentSessionInteractionSupport, nativeSupport: AgentNativeContinuationSupport, continuations?: AgentNativeContinuationContext, signal?: AbortSignal);
     track<Result>(promise: Promise<Result>): Promise<Result>;
     get accepting(): boolean;
+    get hasLiveRequests(): boolean;
     requireUsable(): void;
     private offer;
     requireContinuation(kind: "form" | "plan_review"): void;

package/dist/sessionInteractions/lifetime.js

@@ -102,6 +102,10 @@ class SessionInteractionOwner {
   get accepting() {
     return this.state === "opening" || this.state === "open";
   }
+  get hasLiveRequests() {
+    for (const request of this.requests.values()) if (request.blocksExecutionInput) return true;
+    return false;
+  }
   requireUsable() {
     if (this.fatal) throw this.fatal.cause;
     this.validationOwner.requireUsable();

package/dist/sessionInteractions/request.d.ts

@@ -25,6 +25,7 @@ export declare class SessionInteractionRequest {
     constructor(owner: SessionInteractionOwner, candidate: Candidate, retire: () => void);
     observe(): void;
     setCallback(callback: Promise<void>): void;
+    get blocksExecutionInput(): boolean;
     private scheduleExpiry;
     private expire;
     private protocolFailure;

package/dist/sessionInteractions/request.js

@@ -76,6 +76,9 @@ class SessionInteractionRequest {
       }
     );
   }
+  get blocksExecutionInput() {
+    return this.state.kind !== "terminal" || this.responseWork > 0 || !this.rawTerminalSettled;
+  }
   scheduleExpiry() {
     if (this.candidate.deadlineAt === void 0 || this.state.kind === "terminal") return;
     const remainingMs = this.candidate.deadlineAt - Date.now();

package/dist/sessionValidation.d.ts

@@ -1,4 +1,4 @@
-import { type AgentCapabilities, type AgentCollaborationNode, type AgentContextCumulativeUsage, type AgentContextMeasurementScope, type AgentContextUsage, type AgentGeneratedResourceDescriptor, type AgentItemKind, type AgentItemStatus, type AgentOperationInvocation, type AgentOperationResult, type AgentProviderKey, type AgentSessionBinding, type AgentSessionId, type AgentTurnId } from "@agen-ai/agent-protocol";
+import { type AgentCapabilities, type AgentCollaborationNode, type AgentContextCumulativeUsage, type AgentContextMeasurementScope, type AgentContextUsage, type AgentGeneratedResourceDescriptor, type AgentItemKind, type AgentItemStatus, type AgentOperationInputCapability, type AgentOperationInvocation, type AgentOperationResult, type AgentProviderKey, type AgentSessionBinding, type AgentSessionId, type AgentTurnId } from "@agen-ai/agent-protocol";
 import { type AgentHostBindingLease } from "./hostBindings/lifetime.js";
 import { type MaybePromise } from "./foundation.js";
 import { type AgentProviderOutputValidationContext } from "./outputValidation.js";
@@ -6,6 +6,8 @@ import type { AgentProviderStartTurnInput, AgentProviderSession, AgentSessionBin
 import { type ValidatedAgentTurnExecution, type AdoptedAgentTurnExecution } from "./turnExecution/execution.js";
 import { type PendingAgentRequest } from "./turnExecution/requests.js";
 import type { SessionInteractionOwner } from "./sessionInteractions/lifetime.js";
+import type { AgentExecutionInputSupport } from "./executionInput/types.js";
+import { type AgentStructuredOutputBinding } from "./structuredOutput/admission.js";
 interface ObservedAgentItem {
     readonly itemKind: AgentItemKind;
     readonly status: AgentItemStatus;
@@ -47,7 +49,12 @@ interface ActiveAgentTurn {
     readonly inFlightOperations: Set<Promise<void>>;
     readonly owner: ValidatedAgentTurnExecution;
 }
-export declare function createAgentSessionValidationOwner(capabilities: AgentCapabilities, sessionId: AgentSessionId): {
+export declare function assertAgentTurnInputCapability(input: {
+    readonly capability: AgentOperationInputCapability;
+    readonly parts: AgentProviderStartTurnInput["parts"];
+    readonly providerKey: AgentProviderKey;
+}): void;
+export declare function createAgentSessionValidationOwner(capabilities: AgentCapabilities, sessionId: AgentSessionId, structuredOutputBinding?: AgentStructuredOutputBinding, executionInputSupport?: AgentExecutionInputSupport): {
     sessionAdmission: {
         trackOperation(): () => void;
         joinOperations(): Promise<void>;
@@ -71,11 +78,14 @@ export declare function createAgentSessionValidationOwner(capabilities: AgentCap
     stop(): void;
     completeClose(): void;
     installClose(close: () => Promise<void>): void;
+    installInputContextGuard(guard: () => void): void;
     reserveExecution: () => object;
     ownsExecution: (token: object) => boolean;
     releaseExecution: (token: object) => void;
+    admitTurnOutput(output: unknown, hasOutput: boolean): AgentStructuredOutputBinding | undefined;
+    requireNativeContinuationSupport: () => void;
     installNativeExecution(token: object, turnId: AgentTurnId, createCandidate: (signal: AbortSignal) => AgentProviderTurnExecution): AdoptedAgentTurnExecution;
-    installCallerExecution(token: object, turnInput: AgentProviderStartTurnInput, start: (input: AgentProviderStartTurnInput) => AgentProviderTurnExecution): ValidatedAgentTurnExecution;
+    installCallerExecution(token: object, turnInput: AgentProviderStartTurnInput, start: (input: AgentProviderStartTurnInput) => AgentProviderTurnExecution, binding?: AgentStructuredOutputBinding): ValidatedAgentTurnExecution;
 };
 export type AgentSessionValidationOwner = ReturnType<typeof createAgentSessionValidationOwner>;
 export declare function validateAgentProviderSession(input: {

package/dist/sessionValidation.js

@@ -48,6 +48,10 @@ import { createValidatedAgentTurnExecution, adoptValidatedAgentTurnExecution } f
 import { validateAgentProviderTurnInterruptionResult } from "./turnExecution/receipts.js";
 import { createAgentTurnRequestAdmission } from "./turnExecution/requests.js";
 import { createAgentSessionAdmission } from "./sessionAdmission.js";
+import { createExecutionInputCensus } from "./executionInput/lifetime.js";
+import {
+  admitAgentStructuredOutputTurn
+} from "./structuredOutput/admission.js";
 function validateCloseReason(reason) {
   if (reason !== void 0 && !["idle", "shutdown", "replaced", "contract_rejected", "error", "other"].includes(reason)) {
     throw new TypeError("Provider session close reason is unsupported.");
@@ -620,7 +624,7 @@ function assertAgentTurnInputCapability(input) {
   });
   if (textIssue) rejectReference(`${textIssue.target} must use ${textIssue.format} text`);
 }
-function createAgentSessionValidationOwner(capabilities, sessionId) {
+function createAgentSessionValidationOwner(capabilities, sessionId, structuredOutputBinding, executionInputSupport) {
   const providerKey = capabilities.providerKey;
   const sessionLifetime = new AbortController();
   const sessionAdmission = createAgentSessionAdmission(providerKey);
@@ -639,6 +643,15 @@ function createAgentSessionValidationOwner(capabilities, sessionId) {
   let closed = false;
   let unusable = false;
   let closing;
+  let requireInputContext = () => {
+  };
+  const executionInputCensus = createExecutionInputCensus(providerKey, () => {
+    unusable = true;
+    queueMicrotask(() => {
+      void closing?.().catch(() => {
+      });
+    });
+  });
   const requireOpen = () => {
     if (closed)
       throwAgentProviderContractError(
@@ -677,6 +690,11 @@ function createAgentSessionValidationOwner(capabilities, sessionId) {
     const inFlightOperations = /* @__PURE__ */ new Set();
     const common = {
       providerKey,
+      ...executionInputSupport === void 0 ? {} : { executionInputSupport },
+      executionInputCensus,
+      ownsExecution: () => sessionAdmission.ownsExecution(token),
+      requireInputContext: () => requireInputContext(),
+      structuredOutputBound: source.kind === "caller" && source.binding !== void 0,
       pendingRequests,
       sessionAdmission,
       inFlightOperations,
@@ -684,7 +702,10 @@ function createAgentSessionValidationOwner(capabilities, sessionId) {
       isTerminal: () => state.terminal,
       canRestoreRequest: (pending) => hasLiveApprovalSubject(pending.request, state),
       observe(candidate, requests) {
-        const output = validateAgentProviderOutputForContext(candidate, outputContext(turnId));
+        const output = validateAgentProviderOutputForContext(candidate, {
+          ...outputContext(turnId),
+          ...source.kind !== "caller" || source.binding === void 0 ? {} : { structuredOutputBinding: source.binding }
+        });
         observeTurnOutput({
           capabilities,
           providerKey,
@@ -719,6 +740,15 @@ function createAgentSessionValidationOwner(capabilities, sessionId) {
     }
     return owner;
   }
+  const requireNativeContinuationSupport = () => {
+    if (structuredOutputBinding !== void 0) {
+      throwAgentProviderContractError(
+        providerKey,
+        "structured_output_unsupported",
+        "Schema-bound sessions cannot dispatch native continuations without structured-output admission."
+      );
+    }
+  };
   return {
     sessionAdmission,
     sessionLifetime,
@@ -749,14 +779,38 @@ function createAgentSessionValidationOwner(capabilities, sessionId) {
     installClose(close) {
       closing = close;
     },
+    installInputContextGuard(guard) {
+      requireInputContext = guard;
+    },
     reserveExecution: sessionAdmission.reserveExecution,
     ownsExecution: sessionAdmission.ownsExecution,
     releaseExecution: sessionAdmission.releaseExecution,
+    admitTurnOutput(output, hasOutput) {
+      if (structuredOutputBinding !== void 0 && hasOutput) {
+        throwAgentProviderContractError(
+          providerKey,
+          "structured_output_scope_mismatch",
+          "A schema-bound session cannot override or remove its opening structured-output request."
+        );
+      }
+      return admitAgentStructuredOutputTurn({
+        capabilities,
+        ...structuredOutputBinding === void 0 ? {} : { binding: structuredOutputBinding },
+        output
+      });
+    },
+    requireNativeContinuationSupport,
     installNativeExecution(token, turnId, createCandidate) {
+      requireNativeContinuationSupport();
       return installExecution(token, turnId, { kind: "native", createCandidate });
     },
-    installCallerExecution(token, turnInput, start) {
-      return installExecution(token, turnInput.turnId, { kind: "caller", input: turnInput, start });
+    installCallerExecution(token, turnInput, start, binding) {
+      return installExecution(token, turnInput.turnId, {
+        kind: "caller",
+        input: turnInput,
+        start,
+        ...binding === void 0 ? {} : { binding }
+      });
     }
   };
 }
@@ -796,6 +850,14 @@ function validateAgentProviderSession(input) {
   }
   validateSessionPorts(capabilities, input.candidate);
   const validationOwner = input.validationOwner ?? createAgentSessionValidationOwner(capabilities, sessionId);
+  validationOwner.installInputContextGuard(() => {
+    input.sessionInteractionOwner?.requireUsable();
+    if (input.sessionInteractionOwner?.hasLiveRequests) throwAgentProviderContractError(
+      providerKey,
+      "request_pending",
+      "Execution input cannot enter while a session interaction remains unsettled."
+    );
+  });
   const { sessionLifetime, contextUsageState, interactionState, outputContext } = validationOwner;
   const collaborationNodes = interactionState.collaborationNodes;
   const collaborationSpawnReservations = interactionState.collaborationSpawnReservations;
@@ -862,6 +924,7 @@ function validateAgentProviderSession(input) {
       turnId: turnInput.turnId,
       interactionMode: turnInput.interactionMode,
       parts: turnInput.parts,
+      ...turnInput.output === void 0 ? {} : { output: turnInput.output },
       ...turnInput.summary === void 0 ? {} : { summary: turnInput.summary },
       ...turnInput.deadlineAt === void 0 ? {} : { deadlineAt: turnInput.deadlineAt }
     });
@@ -873,13 +936,15 @@ function validateAgentProviderSession(input) {
         `Provider ${providerKey} does not support ${parsedInput.interactionMode} turn interaction mode.`
       );
     }
+    const binding2 = validationOwner.admitTurnOutput(parsedInput.output, Reflect.has(turnInput, "output"));
     const token = validationOwner.reserveExecution();
     try {
       return validationOwner.installCallerExecution(token, {
         ...parsedInput,
+        ...parsedInput.output === void 0 || binding2 === void 0 ? {} : { output: binding2.request },
         ...turnInput.signal === void 0 ? {} : { signal: turnInput.signal },
         ...turnInput.onProviderExecutionStarted === void 0 ? {} : { onProviderExecutionStarted: turnInput.onProviderExecutionStarted }
-      }, (inputTurn) => input.candidate.startTurn(inputTurn)).execution;
+      }, (inputTurn) => input.candidate.startTurn(inputTurn), binding2).execution;
     } catch (error) {
       validationOwner.releaseExecution(token);
       throw error;
@@ -908,6 +973,7 @@ function validateAgentProviderSession(input) {
       const settleActiveInterruption = trackActiveTurnOperation(
         targetedActiveTurn
       );
+      targetedTurn.owner.closeInputAdmission();
       try {
         const suspendedRequests = targetedTurn.owner.suspendRequests();
         let result;
@@ -939,6 +1005,13 @@ function validateAgentProviderSession(input) {
     steerTurn: async (steeringInput) => {
       requireUsable();
       throwIfAgentOperationAborted(steeringInput.signal);
+      if (Reflect.has(steeringInput, "output")) {
+        throwAgentProviderContractError(
+          providerKey,
+          "structured_output_scope_mismatch",
+          "Steering cannot change a turn's structured-output request."
+        );
+      }
       const turnId = parseAgentTurnId(steeringInput.turnId);
       if (validationOwner.activeTurn?.turnId !== turnId || !validationOwner.activeTurn.owner.hasEntered() || validationOwner.activeTurn.state.terminal || validationOwner.activeTurn.pendingRequests.size > 0) {
         throwAgentProviderContractError(
@@ -1455,7 +1528,7 @@ function validateAgentProviderSession(input) {
     validationOwner.stop();
     input.hostBindingLease?.stop();
     const closingTurn = validationOwner.activeTurn;
-    closingTurn?.owner.stop(new DOMException("The provider session was closed.", "AbortError"));
+    closingTurn?.owner.stop(new DOMException("The provider session was closed.", "AbortError"), "closed");
     const cleanup = async () => {
       if (!providerClosed) {
         await input.candidate.close(closeInput);
@@ -1623,6 +1696,7 @@ async function openIdentityCreatingAgentProviderSession(input) {
   }
 }
 export {
+  assertAgentTurnInputCapability,
   closeRejectedAgentProviderSession,
   createAgentSessionValidationOwner,
   openIdentityCreatingAgentProviderSession,

package/dist/sessions.d.ts

@@ -1,4 +1,4 @@
-import type { AgentAuthenticationFlow, AgentCollaborationControlInput, AgentCollaborationNode, AgentCollaborationSpawnInput, AgentConfigurationCatalog, AgentConfigurationSelectionInput, AgentError, AgentGeneratedResourceDescriptor, AgentGeneratedResourceId, AgentManagedContentCatalog, AgentOperationCatalog, AgentOperationInvocation, AgentOperationResult, AgentRequestResolution, AgentSessionBinding, AgentSessionBranchSource, AgentSessionConfiguration, AgentSessionId, AgentTurnId, AgentTurnInputContent, AgentTurnInteractionMode, AgentTurnInputPart, AgentTurnInterruptionReason } from "@agen-ai/agent-protocol";
+import type { AgentAuthenticationFlow, AgentCollaborationControlInput, AgentCollaborationNode, AgentCollaborationSpawnInput, AgentConfigurationCatalog, AgentConfigurationSelectionInput, AgentError, AgentGeneratedResourceDescriptor, AgentGeneratedResourceId, AgentManagedContentCatalog, AgentOperationCatalog, AgentOperationInvocation, AgentOperationResult, AgentRequestResolution, AgentSessionBinding, AgentSessionBranchSource, AgentSessionConfiguration, AgentSessionId, AgentStructuredOutputRequest, AgentTurnId, AgentTurnInputContent, AgentTurnInteractionMode, AgentTurnInputPart, AgentTurnInterruptionReason } from "@agen-ai/agent-protocol";
 import type { AgentNativeContinuationContext, AgentNativeContinuationSupport } from "./nativeContinuations/types.js";
 import type { MaybePromise } from "./foundation.js";
 import type { AgentSessionHostBinding, AgentSessionHostBindingSupport } from "./hostBindings/types.js";
@@ -6,6 +6,7 @@ import type { AgentProviderOutput } from "./outputs.js";
 import type { AgentArtifactCandidate } from "./artifacts.js";
 import type { AgentProviderSessionInteractionContext, AgentSessionInteractionContext, AgentSessionInteractionSupport } from "./sessionInteractions/types.js";
 import type { AgentEnvironmentObservationPort } from "./environment/types.js";
+import type { AgentExecutionInput, AgentExecutionInputSupport } from "./executionInput/types.js";
 export interface AgentProviderSessionContext {
     readonly sessionId: AgentSessionId;
     readonly workingDirectory: string;
@@ -17,6 +18,7 @@ export interface AgentProviderSessionContext {
 export type AgentSessionBindingCreatedObserver = (binding: AgentSessionBinding) => void;
 export interface AgentProviderCreateSessionInput extends AgentProviderSessionContext {
     readonly onBindingCreated: AgentSessionBindingCreatedObserver;
+    readonly output?: AgentStructuredOutputRequest;
 }
 export interface AgentProviderResumeSessionInput extends AgentProviderSessionContext {
     readonly binding: AgentSessionBinding;
@@ -33,6 +35,7 @@ export interface AgentProviderStartTurnInput {
     readonly parts: readonly AgentTurnInputPart[];
     readonly summary?: string;
     readonly deadlineAt?: string;
+    readonly output?: AgentStructuredOutputRequest;
     readonly signal?: AbortSignal;
     readonly onProviderExecutionStarted?: AgentProviderExecutionStartedObserver;
 }
@@ -55,6 +58,7 @@ export type AgentRequestResolutionResult = Readonly<{
 export interface AgentProviderTurnExecution {
     readonly turnId: AgentTurnId;
     readonly outputs: AsyncIterable<AgentProviderOutput>;
+    readonly input?: AgentExecutionInput;
     readonly resolveRequest: (input: AgentProviderResolveRequestInput) => Promise<AgentRequestResolutionResult>;
 }
 export interface AgentProviderInterruptTurnInput {
@@ -215,6 +219,7 @@ export type AgentProviderAuthentication = Readonly<{
     cancel: (input: AgentProviderAuthenticationCancelInput) => MaybePromise<AgentProviderOperationResult>;
 }>;
 export interface AgentProviderAdapter {
+    readonly executionInput?: AgentExecutionInputSupport;
     readonly sessionInteractions?: AgentSessionInteractionSupport;
     readonly hostBinding?: AgentSessionHostBindingSupport;
     readonly nativeContinuations?: AgentNativeContinuationSupport;
@@ -229,6 +234,7 @@ export type AgentSessionOpenContext = Omit<AgentProviderSessionContext, "interac
 }>;
 export type AgentCreateSessionInput = AgentSessionOpenContext & Readonly<{
     onBindingCreated: AgentSessionBindingCreatedObserver;
+    output?: AgentStructuredOutputRequest;
 }>;
 export type AgentResumeSessionInput = AgentSessionOpenContext & Readonly<{
     binding: AgentSessionBinding;

package/dist/structuredOutput/admission.d.ts

@@ -0,0 +1,16 @@
+import { type AgentCapabilities, type AgentStructuredOutputRequest } from "@agen-ai/agent-protocol";
+export interface AgentStructuredOutputBinding {
+    readonly request: AgentStructuredOutputRequest;
+    readonly maxOutputBytes: number;
+}
+export declare function admitAgentStructuredOutputOpening(input: Readonly<{
+    capabilities: AgentCapabilities;
+    operation: "create" | "resume" | "branch";
+    output: unknown;
+}>): AgentStructuredOutputBinding | undefined;
+export declare function admitAgentStructuredOutputTurn(input: Readonly<{
+    capabilities: AgentCapabilities;
+    binding?: AgentStructuredOutputBinding;
+    output: unknown;
+}>): AgentStructuredOutputBinding | undefined;
+//# sourceMappingURL=admission.d.ts.map

package/dist/structuredOutput/admission.js

@@ -0,0 +1,89 @@
+import {
+  AgentProtocolValidationError,
+  agentProtocolSerializedJsonBytes,
+  parseAgentOutputSchema
+} from "@agen-ai/agent-protocol";
+import { throwAgentProviderContractError } from "../contractErrors.js";
+import { hasExactOwnKeys } from "../internal/objectShape.js";
+function parseOutputRequest(input, maxOutputBytes) {
+  const invalid = () => {
+    throw new AgentProtocolValidationError([{
+      code: "invalid_structured_output_request",
+      message: "Structured output must be a plain json_schema request with only kind and schema data properties.",
+      path: ["output"]
+    }]);
+  };
+  if (input === null || typeof input !== "object") return invalid();
+  let kind;
+  let schema;
+  try {
+    const prototype = Object.getPrototypeOf(input);
+    if (prototype !== Object.prototype && prototype !== null || !hasExactOwnKeys(input, ["kind", "schema"])) return invalid();
+    const kindDescriptor = Object.getOwnPropertyDescriptor(input, "kind");
+    const schemaDescriptor = Object.getOwnPropertyDescriptor(input, "schema");
+    if (!kindDescriptor || !("value" in kindDescriptor) || !kindDescriptor.enumerable || !schemaDescriptor || !("value" in schemaDescriptor) || !schemaDescriptor.enumerable) return invalid();
+    kind = kindDescriptor.value;
+    schema = schemaDescriptor.value;
+  } catch (error) {
+    if (error instanceof AgentProtocolValidationError) throw error;
+    return invalid();
+  }
+  if (kind !== "json_schema") return invalid();
+  return Object.freeze({ kind, schema: parseAgentOutputSchema(schema, { maxOutputBytes }) });
+}
+function admitRequest(capabilities, output) {
+  const capability = capabilities.turns.structuredOutput;
+  if (capability.kind === "unsupported") {
+    throwAgentProviderContractError(
+      capabilities.providerKey,
+      "structured_output_unsupported",
+      "Provider does not support structured output."
+    );
+  }
+  const request = parseOutputRequest(output, capability.maxOutputBytes);
+  if (agentProtocolSerializedJsonBytes(request.schema) > capability.maxSchemaBytes) {
+    throwAgentProviderContractError(
+      capabilities.providerKey,
+      "invalid_structured_output",
+      "Structured output schema exceeds the provider's advertised byte limit."
+    );
+  }
+  return Object.freeze({ request, maxOutputBytes: capability.maxOutputBytes });
+}
+function admitAgentStructuredOutputOpening(input) {
+  if (input.output === void 0) return void 0;
+  const { capabilities } = input;
+  if (input.operation !== "create") {
+    throwAgentProviderContractError(
+      capabilities.providerKey,
+      "structured_output_unsupported",
+      "Structured output cannot be restored through resume or branch."
+    );
+  }
+  const capability = capabilities.turns.structuredOutput;
+  if (capability.kind === "supported" && capability.scope !== "session") {
+    throwAgentProviderContractError(
+      capabilities.providerKey,
+      "structured_output_scope_mismatch",
+      "Provider accepts structured output only when starting a turn."
+    );
+  }
+  return admitRequest(capabilities, input.output);
+}
+function admitAgentStructuredOutputTurn(input) {
+  if (input.output === void 0) return input.binding;
+  const { capabilities } = input;
+  const capability = capabilities.turns.structuredOutput;
+  if (input.binding || capability.kind === "supported" && capability.scope !== "turn") {
+    throwAgentProviderContractError(
+      capabilities.providerKey,
+      "structured_output_scope_mismatch",
+      "Session-scoped structured output cannot be overridden or supplied on a turn."
+    );
+  }
+  return admitRequest(capabilities, input.output);
+}
+export {
+  admitAgentStructuredOutputOpening,
+  admitAgentStructuredOutputTurn
+};

package/dist/structuredOutput/candidate.d.ts

@@ -0,0 +1,22 @@
+import { type AgentOutputSchema, type AgentStructuredOutputResult, type AgentStructuredOutputUnavailableReason } from "@agen-ai/agent-protocol";
+export type AgentStructuredOutputCandidate = Readonly<{
+    kind: "json_text";
+    text: string;
+}> | Readonly<{
+    kind: "json_value";
+    value: unknown;
+}> | Readonly<{
+    kind: "unavailable";
+    reason: AgentStructuredOutputUnavailableReason;
+}>;
+export interface CreateAgentStructuredOutputCandidateInput {
+    readonly schema: AgentOutputSchema;
+    readonly maxOutputBytes?: number;
+    readonly candidate: AgentStructuredOutputCandidate;
+}
+export type AgentStructuredOutputCandidateResult = Exclude<AgentStructuredOutputResult, Readonly<{
+    kind: "not_requested";
+}>>;
+export declare function validateAgentStructuredOutputCandidate(schema: AgentOutputSchema, value: unknown, maxOutputBytes: number): AgentStructuredOutputCandidateResult;
+export declare function createAgentStructuredOutputCandidate(input: CreateAgentStructuredOutputCandidateInput): AgentStructuredOutputCandidateResult;
+//# sourceMappingURL=candidate.d.ts.map

package/dist/structuredOutput/candidate.js

@@ -0,0 +1,64 @@
+import {
+  AGENT_OUTPUT_RAW_JSON_BYTES_LIMIT,
+  AGENT_OUTPUT_VALUE_BYTES_LIMIT,
+  AGENT_STRUCTURED_OUTPUT_UNAVAILABLE_REASONS,
+  parseAgentOutputSchema,
+  validateAgentOutputValue
+} from "@agen-ai/agent-protocol";
+function freezeJson(value) {
+  if (value === null || typeof value !== "object") return;
+  for (const child of Object.values(value)) freezeJson(child);
+  Object.freeze(value);
+}
+function validateAgentStructuredOutputCandidate(schema, value, maxOutputBytes) {
+  const parsed = validateAgentOutputValue(schema, value, { maxOutputBytes });
+  if (!parsed.success) {
+    if (parsed.issues.some((issue) => issue.code === "output_limit_exceeded")) {
+      return Object.freeze({ kind: "unavailable", reason: "output_limit_exceeded" });
+    }
+    if (parsed.issues.some((issue) => issue.code === "invalid_json_data")) {
+      return Object.freeze({ kind: "unavailable", reason: "invalid_json" });
+    }
+    return Object.freeze({ kind: "unavailable", reason: "schema_mismatch", issues: Object.freeze(parsed.issues.map((issue) => Object.freeze({
+      ...issue,
+      path: Object.freeze([...issue.path])
+    }))) });
+  }
+  freezeJson(parsed.data);
+  return Object.freeze({ kind: "json", value: parsed.data });
+}
+function createAgentStructuredOutputCandidate(input) {
+  const schema = parseAgentOutputSchema(input.schema);
+  const maxOutputBytes = input.maxOutputBytes ?? AGENT_OUTPUT_VALUE_BYTES_LIMIT;
+  if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes <= 0 || maxOutputBytes > AGENT_OUTPUT_VALUE_BYTES_LIMIT) {
+    throw new RangeError("Structured output byte limit must be a positive integer within the portable profile ceiling.");
+  }
+  const { candidate } = input;
+  switch (candidate.kind) {
+    case "unavailable":
+      if (!AGENT_STRUCTURED_OUTPUT_UNAVAILABLE_REASONS.includes(candidate.reason)) {
+        throw new TypeError("Structured output candidate has an unsupported unavailable reason.");
+      }
+      return Object.freeze({ kind: "unavailable", reason: candidate.reason });
+    case "json_text": {
+      if (typeof candidate.text !== "string") throw new TypeError("Structured JSON text candidate must contain a string.");
+      if (candidate.text.length > AGENT_OUTPUT_RAW_JSON_BYTES_LIMIT || Buffer.byteLength(candidate.text, "utf8") > AGENT_OUTPUT_RAW_JSON_BYTES_LIMIT) {
+        return Object.freeze({ kind: "unavailable", reason: "output_limit_exceeded" });
+      }
+      let value;
+      try {
+        value = JSON.parse(candidate.text);
+      } catch {
+        return Object.freeze({ kind: "unavailable", reason: "invalid_json" });
+      }
+      return validateAgentStructuredOutputCandidate(schema, value, maxOutputBytes);
+    }
+    case "json_value":
+      return validateAgentStructuredOutputCandidate(schema, candidate.value, maxOutputBytes);
+  }
+  throw new TypeError("Structured output candidate kind is unsupported.");
+}
+export {
+  createAgentStructuredOutputCandidate,
+  validateAgentStructuredOutputCandidate
+};

package/dist/structuredOutput/validation.d.ts

@@ -0,0 +1,8 @@
+import type { AgentProviderKey, AgentStructuredOutputResult } from "@agen-ai/agent-protocol";
+import type { AgentStructuredOutputBinding } from "./admission.js";
+export declare function validateAgentStructuredOutputResult(input: Readonly<{
+    providerKey: AgentProviderKey;
+    binding?: AgentStructuredOutputBinding;
+    result: AgentStructuredOutputResult;
+}>): AgentStructuredOutputResult;
+//# sourceMappingURL=validation.d.ts.map

package/dist/structuredOutput/validation.js

@@ -0,0 +1,26 @@
+import { throwAgentProviderContractError } from "../contractErrors.js";
+import { validateAgentStructuredOutputCandidate } from "./candidate.js";
+function validateAgentStructuredOutputResult(input) {
+  const { binding, result } = input;
+  if (!binding) {
+    if (result.kind !== "not_requested") {
+      throwAgentProviderContractError(
+        input.providerKey,
+        "invalid_structured_output",
+        "Provider reported structured output for a turn without an admitted schema."
+      );
+    }
+    return result;
+  }
+  if (result.kind === "not_requested") {
+    throwAgentProviderContractError(
+      input.providerKey,
+      "invalid_structured_output",
+      "Provider omitted the admitted structured-output contract."
+    );
+  }
+  return result.kind === "json" ? validateAgentStructuredOutputCandidate(binding.request.schema, result.value, binding.maxOutputBytes) : result;
+}
+export {
+  validateAgentStructuredOutputResult
+};