@agen-ai/agent-runtime 0.4.3 → 0.4.4

package/dist/generation/deadline.js

@@ -0,0 +1,81 @@
+import { throwIfAgentOperationAborted } from "../foundation.js";
+import { AgentGenerationError } from "./errors.js";
+const AGENT_GENERATION_TIMEOUT_MS = 3e5;
+const AGENT_GENERATION_MAX_TIMEOUT_MS = 36e5;
+const AGENT_GENERATION_OBSERVER_TIMEOUT_MS = 3e4;
+const AGENT_GENERATION_REQUEST_TIMEOUT_MS = 3e5;
+const AGENT_GENERATION_RESPONSE_TIMEOUT_MS = 3e4;
+const AGENT_GENERATION_CLEANUP_TIMEOUT_MS = 3e4;
+const AGENT_GENERATION_REQUEST_LIMIT = 8;
+function waitForGenerationWork(work, signal) {
+  if (signal.aborted) {
+    try {
+      throwIfAgentOperationAborted(signal);
+    } catch (error) {
+      return Promise.reject(error);
+    }
+  }
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      try {
+        throwIfAgentOperationAborted(signal);
+      } catch (error) {
+        reject(error);
+      }
+    };
+    signal.addEventListener("abort", abort, { once: true });
+    void work.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+  });
+}
+function createGenerationDeadline(deadlineAt, callerSignal) {
+  const controller = new AbortController();
+  const abort = () => {
+    try {
+      throwIfAgentOperationAborted(callerSignal);
+    } catch (error) {
+      controller.abort(error);
+    }
+  };
+  callerSignal?.addEventListener("abort", abort, { once: true });
+  if (callerSignal?.aborted) abort();
+  const expire = () => controller.abort(new AgentGenerationError("timeout", "Object generation exceeded its deadline."));
+  const timeout = setTimeout(expire, Math.max(0, deadlineAt - Date.now()));
+  return {
+    signal: controller.signal,
+    check() {
+      if (Date.now() >= deadlineAt && !controller.signal.aborted) expire();
+      throwIfAgentOperationAborted(controller.signal);
+    },
+    stop(error) {
+      controller.abort(error);
+    },
+    dispose() {
+      clearTimeout(timeout);
+      callerSignal?.removeEventListener("abort", abort);
+    }
+  };
+}
+async function waitForBoundedGenerationWork(work, signal, timeoutMs, error) {
+  const controller = new AbortController();
+  const expiresAt = Date.now() + timeoutMs;
+  const timeout = setTimeout(() => controller.abort(error), timeoutMs);
+  try {
+    const result = await waitForGenerationWork(work, AbortSignal.any([signal, controller.signal]));
+    if (Date.now() >= expiresAt) throw error;
+    return result;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+export {
+  AGENT_GENERATION_CLEANUP_TIMEOUT_MS,
+  AGENT_GENERATION_MAX_TIMEOUT_MS,
+  AGENT_GENERATION_OBSERVER_TIMEOUT_MS,
+  AGENT_GENERATION_REQUEST_LIMIT,
+  AGENT_GENERATION_REQUEST_TIMEOUT_MS,
+  AGENT_GENERATION_RESPONSE_TIMEOUT_MS,
+  AGENT_GENERATION_TIMEOUT_MS,
+  createGenerationDeadline,
+  waitForBoundedGenerationWork,
+  waitForGenerationWork
+};

package/dist/generation/decoding.d.ts

@@ -0,0 +1,4 @@
+import { type AgentJsonObject, type AgentOutputDefinition, type AgentOutputSchema } from "@agen-ai/agent-protocol";
+export declare function captureGenerationCandidate(schema: AgentOutputSchema, value: unknown, maxOutputBytes: number): AgentJsonObject;
+export declare function decodeGenerationCandidate<T>(definition: AgentOutputDefinition<T>, candidate: AgentJsonObject, maxOutputBytes: number): T;
+//# sourceMappingURL=decoding.d.ts.map

package/dist/generation/decoding.js

@@ -0,0 +1,59 @@
+import { normalizeAgentStructuredOutputIssues, validateAgentOutputValue } from "@agen-ai/agent-protocol";
+import { AgentGenerationError } from "./errors.js";
+function freezeJson(value) {
+  if (value === null || typeof value !== "object") return;
+  for (const child of Object.values(value)) freezeJson(child);
+  Object.freeze(value);
+}
+function captureGenerationCandidate(schema, value, maxOutputBytes) {
+  const parsed = validateAgentOutputValue(schema, value, { maxOutputBytes });
+  if (!parsed.success) throw new AgentGenerationError("generation_failed", "Structured generation did not produce a valid object.");
+  freezeJson(parsed.data);
+  return parsed.data;
+}
+function isJsonArray(value) {
+  return Array.isArray(value);
+}
+function equalJson(left, right) {
+  if (left === right) return true;
+  if (left === null || right === null || typeof left !== "object" || typeof right !== "object") return false;
+  if (isJsonArray(left) || isJsonArray(right)) {
+    return isJsonArray(left) && isJsonArray(right) && left.length === right.length && left.every((child, index) => equalJson(child, right[index]));
+  }
+  const keys = Object.keys(left);
+  return keys.length === Object.keys(right).length && keys.every((key) => Object.hasOwn(right, key) && equalJson(left[key], right[key]));
+}
+function decodeGenerationCandidate(definition, candidate, maxOutputBytes) {
+  let decoded;
+  try {
+    decoded = definition.decode(candidate);
+  } catch (cause) {
+    throw new AgentGenerationError("decoding_failed", "Object decoder failed.", { cause });
+  }
+  try {
+    if (!decoded.success) throw new AgentGenerationError("decoding_failed", "Object decoder rejected the generated value.", {
+      issues: normalizeAgentStructuredOutputIssues(decoded.issues)
+    });
+    const value = decoded.data;
+    const admitted = validateAgentOutputValue(definition.schema, value, { maxOutputBytes });
+    if (!admitted.success) {
+      throw new AgentGenerationError("decoding_failed", "Object decoder returned invalid JSON data.", {
+        issues: normalizeAgentStructuredOutputIssues(admitted.issues)
+      });
+    }
+    if (!equalJson(candidate, admitted.data)) {
+      throw new AgentGenerationError("decoding_failed", "Object decoder must preserve the generated JSON value.", {
+        issues: normalizeAgentStructuredOutputIssues([{ code: "decoded_value_changed", path: [], message: "Object decoder changed the generated JSON value." }])
+      });
+    }
+    freezeJson(value);
+    return value;
+  } catch (cause) {
+    if (cause instanceof AgentGenerationError) throw cause;
+    throw new AgentGenerationError("decoding_failed", "Object decoder failed.", { cause });
+  }
+}
+export {
+  captureGenerationCandidate,
+  decodeGenerationCandidate
+};

package/dist/generation/errors.d.ts

@@ -0,0 +1,29 @@
+import type { AgentProviderKey, AgentStructuredOutputUnavailableReason, ValidationIssue } from "@agen-ai/agent-protocol";
+import { AgentProviderSessionCleanupError } from "../contractErrors.js";
+import type { AgentRequestResolutionResult } from "../sessions.js";
+import type { AgentGeneratedObject } from "./types.js";
+export declare const AGENT_GENERATION_ERROR_CODES: readonly ["unsupported", "interaction_required", "generation_failed", "decoding_failed", "observer_failed", "request_failed", "timeout"];
+export type AgentGenerationErrorCode = (typeof AGENT_GENERATION_ERROR_CODES)[number];
+export declare class AgentGenerationError extends Error {
+    readonly code: AgentGenerationErrorCode;
+    readonly reason?: AgentStructuredOutputUnavailableReason;
+    readonly issues?: readonly ValidationIssue[];
+    readonly receipt?: AgentRequestResolutionResult;
+    constructor(code: AgentGenerationErrorCode, message: string, options?: ErrorOptions & Readonly<{
+        reason?: AgentStructuredOutputUnavailableReason;
+        issues?: readonly ValidationIssue[];
+        receipt?: AgentRequestResolutionResult;
+    }>);
+}
+export declare class AgentGenerationCleanupError<T = unknown> extends AgentProviderSessionCleanupError {
+    readonly primaryError?: unknown;
+    readonly result?: AgentGeneratedObject<T>;
+    constructor(input: Readonly<{
+        providerKey: AgentProviderKey;
+        errors: readonly unknown[];
+        retryCleanup: () => Promise<void>;
+        primaryError?: unknown;
+        result?: AgentGeneratedObject<T>;
+    }>);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/generation/errors.js

@@ -0,0 +1,39 @@
+import { AgentProviderSessionCleanupError } from "../contractErrors.js";
+const AGENT_GENERATION_ERROR_CODES = [
+  "unsupported",
+  "interaction_required",
+  "generation_failed",
+  "decoding_failed",
+  "observer_failed",
+  "request_failed",
+  "timeout"
+];
+class AgentGenerationError extends Error {
+  constructor(code, message, options) {
+    super(message, options);
+    this.code = code;
+    this.name = "AgentGenerationError";
+    this.reason = options?.reason;
+    this.issues = options?.issues;
+    this.receipt = options?.receipt;
+  }
+  reason;
+  issues;
+  receipt;
+}
+class AgentGenerationCleanupError extends AgentProviderSessionCleanupError {
+  primaryError;
+  result;
+  constructor(input) {
+    super(input);
+    this.name = "AgentGenerationCleanupError";
+    this.message = "Object generation cleanup remains incomplete.";
+    this.primaryError = input.primaryError;
+    this.result = input.result;
+  }
+}
+export {
+  AGENT_GENERATION_ERROR_CODES,
+  AgentGenerationCleanupError,
+  AgentGenerationError
+};

package/dist/generation/generateObject.d.ts

@@ -0,0 +1,3 @@
+import type { AgentGeneratedObject, AgentGenerateObjectInput } from "./types.js";
+export declare function generateObject<T>(input: AgentGenerateObjectInput<T>): Promise<AgentGeneratedObject<T>>;
+//# sourceMappingURL=generateObject.d.ts.map

package/dist/generation/generateObject.js

@@ -0,0 +1,148 @@
+import {
+  AgentProtocolValidationError
+} from "@agen-ai/agent-protocol";
+import { AgentProviderContractError, AgentProviderSessionCleanupError } from "../contractErrors.js";
+import { isAgentOperationAbortError } from "../foundation.js";
+import { createGenerationCleanupOwner } from "./cleanup.js";
+import { captureGenerationCandidate, decodeGenerationCandidate } from "./decoding.js";
+import { AGENT_GENERATION_OBSERVER_TIMEOUT_MS, createGenerationDeadline, waitForBoundedGenerationWork, waitForGenerationWork } from "./deadline.js";
+import { AgentGenerationCleanupError, AgentGenerationError } from "./errors.js";
+import { preflightGeneration } from "./preflight.js";
+import { createGenerationRequests } from "./requests.js";
+function unavailableFailure(output) {
+  return new AgentGenerationError("generation_failed", "Object generation did not complete with a structured object.", output.kind === "unavailable" ? {
+    reason: output.reason,
+    ...output.reason !== "schema_mismatch" || output.issues === void 0 ? {} : {
+      issues: Object.freeze(output.issues.map((issue) => Object.freeze({ ...issue, path: Object.freeze([...issue.path]) })))
+    }
+  } : void 0);
+}
+function executionFailure(cause) {
+  if (cause instanceof AgentGenerationError || cause instanceof AgentProtocolValidationError || cause instanceof AgentProviderContractError || isAgentOperationAbortError(cause)) return cause;
+  return new AgentGenerationError("generation_failed", "Object generation execution failed.", { cause });
+}
+async function generateObject(input) {
+  const admitted = preflightGeneration(input);
+  const deadline = createGenerationDeadline(admitted.deadlineAt, input.signal);
+  let primary;
+  let failed = false;
+  let result;
+  let stopRequests = () => {
+  };
+  const owner = createGenerationCleanupOwner({ turnId: admitted.turn.turnId, stopCallbacks: () => stopRequests() });
+  let shutdown;
+  const fail = (error) => {
+    if (failed) return;
+    failed = true;
+    primary = error;
+    shutdown = owner.cleanup(true);
+    void shutdown.catch(() => {
+    });
+    deadline.stop(error);
+  };
+  const aborted = () => fail(deadline.signal.reason);
+  deadline.signal.addEventListener("abort", aborted, { once: true });
+  let opening;
+  let opened = false;
+  try {
+    const output = Object.freeze({ kind: "json_schema", schema: admitted.schema });
+    let bindingSeen = false;
+    opening = Promise.resolve().then(() => input.instance.adapter.createSession({
+      ...admitted.session,
+      signal: deadline.signal,
+      ...admitted.capability.scope === "session" ? { output } : {},
+      onBindingCreated() {
+        bindingSeen = true;
+      }
+    }));
+    owner.setOpening(opening);
+    const session = await waitForGenerationWork(opening, deadline.signal);
+    opened = true;
+    deadline.check();
+    if (!bindingSeen) throw new AgentProviderContractError(input.instance.capabilities.providerKey, "binding_callback_missing", "Object generation opening did not report its session binding.");
+    const execution = session.startTurn({
+      ...admitted.turn,
+      signal: deadline.signal,
+      ...admitted.capability.scope === "turn" ? { output } : {},
+      onProviderExecutionStarted: owner.markEntered
+    });
+    const requests = createGenerationRequests({
+      handler: input.onRequest,
+      execution,
+      signal: deadline.signal,
+      deadlineAt: admitted.deadlineAt,
+      owner,
+      fail,
+      checkDeadline: deadline.check
+    });
+    stopRequests = requests.stop;
+    let terminal;
+    const reader = (async () => {
+      for await (const outputEvent of execution.outputs) {
+        if (outputEvent.kind === "event") {
+          const event = outputEvent.event;
+          if (event.type === "turn.completed") {
+            owner.markTerminal();
+            terminal = event.payload.outcome === "completed" && event.payload.structuredOutput.kind === "json" ? { outcome: "completed", candidate: captureGenerationCandidate(admitted.schema, event.payload.structuredOutput.value, admitted.capability.maxOutputBytes) } : { outcome: "failed", error: unavailableFailure(event.payload.structuredOutput) };
+          }
+          requests.observe(event);
+        }
+        if (!failed && input.onOutput) {
+          const observer = input.onOutput;
+          const callback = owner.retain(Promise.resolve().then(() => {
+            if (!failed) return observer(outputEvent);
+          }));
+          try {
+            await waitForBoundedGenerationWork(
+              callback,
+              deadline.signal,
+              AGENT_GENERATION_OBSERVER_TIMEOUT_MS,
+              new AgentGenerationError("observer_failed", "Object output observer exceeded its deadline.")
+            );
+            deadline.check();
+          } catch (cause) {
+            try {
+              deadline.check();
+            } catch (error) {
+              fail(error);
+            }
+            if (!failed) fail(cause instanceof AgentGenerationError ? cause : new AgentGenerationError("observer_failed", "Object output observer failed.", { cause }));
+          }
+        }
+      }
+    })();
+    owner.retain(reader);
+    await waitForGenerationWork(reader, deadline.signal);
+    if (failed) throw primary;
+    deadline.check();
+    if (!terminal || terminal.outcome !== "completed") {
+      throw terminal?.outcome === "failed" ? terminal.error : new AgentGenerationError("generation_failed", "Object generation stream ended without a terminal result.");
+    }
+    const value = decodeGenerationCandidate({ schema: admitted.schema, decode: admitted.decode }, terminal.candidate, admitted.capability.maxOutputBytes);
+    deadline.check();
+    result = Object.freeze({ value, sessionId: admitted.session.sessionId, turnId: admitted.turn.turnId });
+  } catch (cause) {
+    if (!opened && cause instanceof AgentProviderSessionCleanupError && !failed) throw cause;
+    fail(executionFailure(cause));
+  } finally {
+    deadline.signal.removeEventListener("abort", aborted);
+    deadline.dispose();
+  }
+  try {
+    await (shutdown ?? owner.cleanup(failed));
+  } catch (cleanupError) {
+    throw new AgentGenerationCleanupError({
+      providerKey: input.instance.capabilities.providerKey,
+      errors: failed ? [primary, cleanupError] : [cleanupError],
+      retryCleanup: () => owner.cleanup(failed),
+      ...failed ? { primaryError: primary } : {},
+      ...result === void 0 ? {} : { result }
+    });
+  }
+  if (failed) throw primary;
+  if (!result) throw new AgentGenerationError("generation_failed", "Object generation returned no validated result.");
+  return result;
+}
+export {
+  generateObject
+};

package/dist/generation/index.d.ts

@@ -0,0 +1,5 @@
+export { generateObject } from "./generateObject.js";
+export { AGENT_GENERATION_ERROR_CODES, AgentGenerationError, AgentGenerationCleanupError } from "./errors.js";
+export type { AgentGenerationErrorCode } from "./errors.js";
+export type { AgentGenerateObjectInput, AgentGeneratedObject } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/generation/index.js

@@ -0,0 +1,8 @@
+import { generateObject } from "./generateObject.js";
+import { AGENT_GENERATION_ERROR_CODES, AgentGenerationError, AgentGenerationCleanupError } from "./errors.js";
+export {
+  AGENT_GENERATION_ERROR_CODES,
+  AgentGenerationCleanupError,
+  AgentGenerationError,
+  generateObject
+};

package/dist/generation/preflight.d.ts

@@ -0,0 +1,25 @@
+import type { AgentGenerateObjectInput } from "./types.js";
+export declare function preflightGeneration<T>(input: AgentGenerateObjectInput<T>): {
+    schema: import("@agen-ai/agent-protocol").AgentOutputSchema;
+    decode: (value: import("@agen-ai/agent-protocol").AgentJsonObject) => import("@agen-ai/agent-protocol").AgentProtocolParseResult<T>;
+    capability: Readonly<{
+        kind: "supported";
+        mechanism: "native";
+        schemaProfile: typeof import("@agen-ai/agent-protocol").AGENT_OUTPUT_SCHEMA_PROFILE;
+        scope: "turn" | "session";
+        maxSchemaBytes: number;
+        maxOutputBytes: number;
+        resume: false;
+        branch: false;
+    }>;
+    session: {
+        configuration: import("@agen-ai/agent-protocol").AgentSessionConfiguration;
+        interactions?: import("../index.js").AgentSessionInteractionContext;
+        sessionId: import("@agen-ai/agent-protocol").AgentSessionId;
+        workingDirectory: string;
+        hostBinding?: import("../index.js").AgentSessionHostBinding;
+    };
+    turn: import("@agen-ai/agent-protocol").AgentTurnRunInput;
+    deadlineAt: number;
+};
+//# sourceMappingURL=preflight.d.ts.map

package/dist/generation/preflight.js

@@ -0,0 +1,48 @@
+import {
+  agentProtocolSerializedJsonBytes,
+  parseAgentOutputSchema,
+  parseAgentSessionOpenInput,
+  parseAgentTurnRunInput
+} from "@agen-ai/agent-protocol";
+import { assertAgentSessionConfigurationSupported } from "../configurationValidation.js";
+import { throwAgentProviderContractError } from "../contractErrors.js";
+import { throwIfAgentOperationAborted } from "../foundation.js";
+import { assertAgentTurnInputCapability } from "../sessionValidation.js";
+import { AGENT_GENERATION_MAX_TIMEOUT_MS, AGENT_GENERATION_TIMEOUT_MS } from "./deadline.js";
+import { AgentGenerationError } from "./errors.js";
+function preflightGeneration(input) {
+  throwIfAgentOperationAborted(input.signal);
+  const timeoutMs = input.timeoutMs ?? AGENT_GENERATION_TIMEOUT_MS;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > AGENT_GENERATION_MAX_TIMEOUT_MS) {
+    throw new RangeError("Object generation timeout must be a positive integer of at most one hour.");
+  }
+  for (const key of ["output", "signal", "onBindingCreated", "nativeContinuations"]) {
+    if (Reflect.has(input.session, key)) throw new TypeError(`Object generation owns session ${key}.`);
+  }
+  for (const key of ["output", "signal", "onProviderExecutionStarted"]) {
+    if (Reflect.has(input.turn, key)) throw new TypeError(`Object generation owns turn ${key}.`);
+  }
+  if (typeof input.output?.decode !== "function") throw new TypeError("Object generation requires an output decoder.");
+  if (input.onOutput !== void 0 && typeof input.onOutput !== "function") throw new TypeError("Object output observer must be a function.");
+  if (input.onRequest !== void 0 && typeof input.onRequest !== "function") throw new TypeError("Object request handler must be a function.");
+  const schema = parseAgentOutputSchema(input.output.schema);
+  const capability = input.instance.capabilities.turns.structuredOutput;
+  if (capability.kind !== "supported") throw new AgentGenerationError("unsupported", "Provider does not support structured object generation.");
+  const boundedSchema = parseAgentOutputSchema(schema, { maxOutputBytes: capability.maxOutputBytes });
+  if (agentProtocolSerializedJsonBytes(boundedSchema) > capability.maxSchemaBytes) {
+    throwAgentProviderContractError(input.instance.capabilities.providerKey, "invalid_structured_output", "Object schema exceeds the provider's advertised byte limit.");
+  }
+  const session = parseAgentSessionOpenInput({ operation: "create", sessionId: input.session.sessionId, configuration: input.session.configuration });
+  assertAgentSessionConfigurationSupported(input.instance.capabilities, session.configuration);
+  const turn = parseAgentTurnRunInput(input.turn);
+  assertAgentTurnInputCapability({ capability: input.instance.capabilities.input, parts: turn.parts, providerKey: input.instance.capabilities.providerKey });
+  if (!input.instance.capabilities.turns.interactionModes.includes(turn.interactionMode)) {
+    throwAgentProviderContractError(input.instance.capabilities.providerKey, "input_capability_mismatch", "Provider does not support the requested interaction mode.");
+  }
+  const deadlineAt = Math.min(Date.now() + timeoutMs, turn.deadlineAt === void 0 ? Infinity : Date.parse(turn.deadlineAt));
+  if (deadlineAt <= Date.now()) throw new AgentGenerationError("timeout", "Object generation deadline has expired.");
+  return { schema: boundedSchema, decode: input.output.decode, capability, session: { ...input.session, configuration: session.configuration }, turn, deadlineAt };
+}
+export {
+  preflightGeneration
+};

package/dist/generation/requests.d.ts

@@ -0,0 +1,17 @@
+import type { AgentEvent } from "@agen-ai/agent-protocol";
+import type { AgentProviderTurnExecution } from "../sessions.js";
+import type { GenerationCleanupOwner } from "./cleanup.js";
+import type { AgentGenerateObjectInput } from "./types.js";
+export declare function createGenerationRequests(input: Readonly<{
+    handler: AgentGenerateObjectInput<unknown>["onRequest"];
+    execution: AgentProviderTurnExecution;
+    signal: AbortSignal;
+    deadlineAt: number;
+    owner: GenerationCleanupOwner;
+    fail: (error: unknown) => void;
+    checkDeadline: () => void;
+}>): {
+    stop(): void;
+    observe(event: AgentEvent): void;
+};
+//# sourceMappingURL=requests.d.ts.map

package/dist/generation/requests.js

@@ -0,0 +1,117 @@
+import { parseAgentRequest } from "@agen-ai/agent-protocol";
+import { throwIfAgentOperationAborted } from "../foundation.js";
+import {
+  AGENT_GENERATION_REQUEST_LIMIT,
+  AGENT_GENERATION_REQUEST_TIMEOUT_MS,
+  AGENT_GENERATION_RESPONSE_TIMEOUT_MS,
+  waitForBoundedGenerationWork
+} from "./deadline.js";
+import { AgentGenerationError } from "./errors.js";
+function createGenerationRequests(input) {
+  const records = /* @__PURE__ */ new Map();
+  let stopped = false;
+  const retire = (record) => {
+    record.live = false;
+    record.controller.abort(new DOMException("The generation request is no longer available.", "AbortError"));
+  };
+  return {
+    stop() {
+      stopped = true;
+      for (const record of records.values()) retire(record);
+    },
+    observe(event) {
+      if (event.type === "request.unavailable") {
+        const record2 = records.get(event.payload.requestId);
+        if (record2) retire(record2);
+        return;
+      }
+      if (event.type === "turn.completed") {
+        for (const record2 of records.values()) retire(record2);
+        return;
+      }
+      if (event.type !== "request.opened" || stopped) return;
+      if (!input.handler) {
+        input.fail(new AgentGenerationError("interaction_required", "Object generation requires a request handler."));
+        return;
+      }
+      if (records.size >= AGENT_GENERATION_REQUEST_LIMIT) {
+        input.fail(new AgentGenerationError("request_failed", "Object generation exceeded its active request handler limit."));
+        return;
+      }
+      const request = parseAgentRequest(event.payload.request);
+      const record = { controller: new AbortController(), live: true, pending: 0, finished: false };
+      records.set(request.requestId, record);
+      const handler = input.handler;
+      const signal = AbortSignal.any([input.signal, record.controller.signal]);
+      let expiry;
+      if (request.expiresAt !== void 0) {
+        const expiresAt = Date.parse(request.expiresAt);
+        const remaining = expiresAt - Date.now();
+        if (remaining <= 0) retire(record);
+        else if (expiresAt < input.deadlineAt) expiry = setTimeout(() => retire(record), remaining);
+      }
+      const clearRecord = () => {
+        if (record.finished && record.pending === 0 && records.get(request.requestId) === record) records.delete(request.requestId);
+      };
+      const retain = (work) => {
+        record.pending += 1;
+        void work.then(() => {
+          record.pending -= 1;
+          clearRecord();
+        }, () => {
+          record.pending -= 1;
+          clearRecord();
+        });
+        return input.owner.retain(work);
+      };
+      let deliveryEntered = false;
+      const task = (async () => {
+        try {
+          const callback = retain(Promise.resolve().then(() => {
+            throwIfAgentOperationAborted(signal);
+            return handler(request, { signal });
+          }));
+          const resolution = await waitForBoundedGenerationWork(
+            callback,
+            signal,
+            AGENT_GENERATION_REQUEST_TIMEOUT_MS,
+            new AgentGenerationError("request_failed", "Object generation request handler exceeded its deadline.")
+          );
+          input.checkDeadline();
+          if (!record.live || stopped || signal.aborted) return;
+          const delivery = retain(Promise.resolve().then(() => {
+            input.checkDeadline();
+            if (!record.live || stopped) throw new DOMException("The generation request is no longer available.", "AbortError");
+            deliveryEntered = true;
+            return input.execution.resolveRequest({ resolution, signal: input.signal });
+          }));
+          const receipt = await waitForBoundedGenerationWork(
+            delivery,
+            input.signal,
+            AGENT_GENERATION_RESPONSE_TIMEOUT_MS,
+            new AgentGenerationError("request_failed", "Object generation request delivery exceeded its deadline.")
+          );
+          if (receipt.status !== "delivered") {
+            input.fail(new AgentGenerationError("request_failed", "Object generation request was not delivered.", { receipt, cause: receipt }));
+          }
+        } catch (cause) {
+          try {
+            input.checkDeadline();
+          } catch {
+          }
+          if ((record.live || deliveryEntered) && !stopped && !input.signal.aborted) {
+            input.fail(cause instanceof AgentGenerationError ? cause : new AgentGenerationError("request_failed", "Object generation request handler or delivery failed.", { cause }));
+          }
+        } finally {
+          if (expiry !== void 0) clearTimeout(expiry);
+          record.finished = true;
+          clearRecord();
+        }
+      })();
+      input.owner.retain(task);
+    }
+  };
+}
+export {
+  createGenerationRequests
+};

package/dist/generation/types.d.ts

@@ -0,0 +1,22 @@
+import type { AgentOutputDefinition, AgentRequest, AgentRequestResolution, AgentSessionId, AgentTurnId } from "@agen-ai/agent-protocol";
+import type { MaybePromise } from "../foundation.js";
+import type { ValidatedMaterializedAgentProviderInstance } from "../providerDriver.js";
+import type { AgentCreateSessionInput, AgentProviderOutputObserver, AgentProviderStartTurnInput } from "../sessions.js";
+export interface AgentGenerateObjectInput<T> {
+    readonly instance: ValidatedMaterializedAgentProviderInstance;
+    readonly session: Omit<AgentCreateSessionInput, "output" | "signal" | "onBindingCreated" | "nativeContinuations">;
+    readonly turn: Omit<AgentProviderStartTurnInput, "output" | "signal" | "onProviderExecutionStarted">;
+    readonly output: AgentOutputDefinition<T>;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly onOutput?: AgentProviderOutputObserver;
+    readonly onRequest?: (request: AgentRequest, context: Readonly<{
+        signal: AbortSignal;
+    }>) => MaybePromise<AgentRequestResolution>;
+}
+export interface AgentGeneratedObject<T> {
+    readonly value: T;
+    readonly sessionId: AgentSessionId;
+    readonly turnId: AgentTurnId;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/index.d.ts

@@ -15,6 +15,9 @@ export * from "./readiness.js";
 export * from "./sessions.js";
 export * from "./sessionInteractions/index.js";
 export * from "./nativeContinuations/index.js";
+export { parseAgentExecutionInputMessageId, type AgentExecutionInput, type AgentExecutionInputMessage, type AgentExecutionInputMessageId, type AgentExecutionInputOutcome, type AgentExecutionInputReceipt, type AgentExecutionInputSupport, } from "./executionInput/index.js";
+export { createAgentStructuredOutputCandidate } from "./structuredOutput/candidate.js";
+export type { AgentStructuredOutputCandidate, AgentStructuredOutputCandidateResult, CreateAgentStructuredOutputCandidateInput, } from "./structuredOutput/candidate.js";
 export { createAgentProviderSessionCleanupError, isAgentProviderSessionCleanupErrorFor } from "./sessionCleanup.js";
 export * from "./text.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -15,9 +15,15 @@ export * from "./readiness.js";
 export * from "./sessions.js";
 export * from "./sessionInteractions/index.js";
 export * from "./nativeContinuations/index.js";
+import {
+  parseAgentExecutionInputMessageId
+} from "./executionInput/index.js";
+import { createAgentStructuredOutputCandidate } from "./structuredOutput/candidate.js";
 import { createAgentProviderSessionCleanupError, isAgentProviderSessionCleanupErrorFor } from "./sessionCleanup.js";
 export * from "./text.js";
 export {
   createAgentProviderSessionCleanupError,
-  isAgentProviderSessionCleanupErrorFor
+  createAgentStructuredOutputCandidate,
+  isAgentProviderSessionCleanupErrorFor,
+  parseAgentExecutionInputMessageId
 };

package/dist/nativeContinuations/admission.js

@@ -147,6 +147,7 @@ async function dispatchPreparedSessionResponse(input) {
     if (outcomeFailure) throw outcomeFailure;
     if (earlyOutcome) throw continuationError(owner, "invalid_native_continuation", "Prepared outcome forbids native response dispatch.");
     if (value.kind === "native_continuation") {
+      owner.validationOwner.requireNativeContinuationSupport();
       owner.requireContinuation(input.candidate.request.kind);
       reservation = owner.validationOwner.reserveExecution();
       const turnId = parseAgentTurnId(`native-${randomUUID()}`);