@agen-ai/agent-runtime 0.4.0 → 0.4.2

package/dist/hostBindings/opening.d.ts

@@ -1,12 +1,14 @@
 import type { AgentProviderKey } from "@agen-ai/agent-protocol";
 import type { MaybePromise } from "../foundation.js";
 import type { AgentProviderSession, AgentProviderSessionContext } from "../sessions.js";
+import type { SessionInteractionOwner } from "../sessionInteractions/lifetime.js";
 import { type AgentHostBindingLease } from "./lifetime.js";
 export declare function invokeAgentSessionOpening<Input extends AgentProviderSessionContext>(input: Readonly<{
     providerKey: AgentProviderKey;
     openingInput: object;
     candidateInput: Input;
     lease: AgentHostBindingLease | undefined;
+    interactions?: SessionInteractionOwner;
     open: (context: Input) => MaybePromise<AgentProviderSession>;
 }>): Promise<AgentProviderSession>;
 //# sourceMappingURL=opening.d.ts.map

package/dist/hostBindings/opening.js

@@ -2,6 +2,7 @@ import { AgentProviderSessionCleanupError } from "../contractErrors.js";
 import { associateAgentSessionCleanupError, isAgentProviderSessionCleanupErrorFor } from "../sessionCleanup.js";
 import { createAgentHostBindingCleanupError } from "./lifetime.js";
 async function invokeAgentSessionOpening(input) {
+  if (input.interactions) return invokeInteractiveSessionOpening({ ...input, interactions: input.interactions });
   try {
     return await input.open(input.candidateInput);
   } catch (error) {
@@ -19,6 +20,63 @@ async function invokeAgentSessionOpening(input) {
     throw associateAgentSessionCleanupError(retained, input.openingInput);
   }
 }
+async function invokeInteractiveSessionOpening(input) {
+  let actual;
+  try {
+    input.interactions.requireUsable();
+    actual = Promise.resolve(input.open(input.candidateInput));
+  } catch (cause) {
+    actual = Promise.reject(cause);
+  }
+  void actual.catch(() => {
+  });
+  try {
+    const candidate = await Promise.race([actual, input.interactions.failure.then((cause) => {
+      throw cause;
+    })]);
+    input.interactions.requireUsable();
+    return candidate;
+  } catch (error) {
+    input.interactions.stop();
+    input.lease?.stop();
+    let providerClosed = false;
+    let nativeCleanup;
+    let nativeCleanupRetained = false;
+    const cleanup = async () => {
+      let candidate;
+      try {
+        candidate = await actual;
+      } catch (cause) {
+        if (isAgentProviderSessionCleanupErrorFor(cause, input.candidateInput) && cause.providerKey === input.providerKey) {
+          nativeCleanup = cause;
+          if (!nativeCleanupRetained) {
+            nativeCleanupRetained = true;
+            throw cause;
+          }
+        }
+      }
+      if (!providerClosed) {
+        if (nativeCleanup) await nativeCleanup.retryCleanup();
+        else if (candidate) await candidate.close({ reason: "contract_rejected" });
+        providerClosed = true;
+      }
+      await input.interactions.join();
+      await input.lease?.release();
+    };
+    try {
+      await input.interactions.close(cleanup, false);
+    } catch (cleanupError) {
+      const ownership = {
+        providerKey: input.providerKey,
+        errors: [error, cleanupError],
+        retryCleanup: () => input.interactions.close(cleanup, false)
+      };
+      const retained = input.lease ? createAgentHostBindingCleanupError({ ...ownership, lease: input.lease }) : new AgentProviderSessionCleanupError(ownership);
+      throw associateAgentSessionCleanupError(retained, input.openingInput);
+    }
+    throw error;
+  }
+}
 export {
   invokeAgentSessionOpening
 };

package/dist/index.d.ts

@@ -13,6 +13,8 @@ export * from "./providerDriver.js";
 export * from "./providerInstanceRegistry.js";
 export * from "./readiness.js";
 export * from "./sessions.js";
+export * from "./sessionInteractions/index.js";
+export * from "./nativeContinuations/index.js";
 export { createAgentProviderSessionCleanupError, isAgentProviderSessionCleanupErrorFor } from "./sessionCleanup.js";
 export * from "./text.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -13,6 +13,8 @@ export * from "./providerDriver.js";
 export * from "./providerInstanceRegistry.js";
 export * from "./readiness.js";
 export * from "./sessions.js";
+export * from "./sessionInteractions/index.js";
+export * from "./nativeContinuations/index.js";
 import { createAgentProviderSessionCleanupError, isAgentProviderSessionCleanupErrorFor } from "./sessionCleanup.js";
 export * from "./text.js";
 export {

package/dist/nativeContinuations/admission.d.ts

@@ -0,0 +1,17 @@
+import { type AgentSessionResponse } from "@agen-ai/agent-protocol";
+import type { AgentRequestResolutionResult } from "../sessions.js";
+import type { SessionInteractionOwner } from "../sessionInteractions/lifetime.js";
+import type { AgentProviderPreparedSessionInteraction } from "../sessionInteractions/types.js";
+import type { AgentSessionResponseAttemptId } from "./types.js";
+export declare function mintSessionResponseAttemptId(): AgentSessionResponseAttemptId;
+export declare function dispatchPreparedSessionResponse(input: Readonly<{
+    owner: SessionInteractionOwner;
+    candidate: AgentProviderPreparedSessionInteraction;
+    response: AgentSessionResponse;
+    attemptId: AgentSessionResponseAttemptId;
+    signal: AbortSignal;
+    requireCurrent: () => void;
+    onDispatch: (deadline: number) => void;
+    observeActualReceipt: (work: Promise<AgentRequestResolutionResult>) => void;
+}>): Promise<AgentRequestResolutionResult>;
+//# sourceMappingURL=admission.d.ts.map

package/dist/nativeContinuations/admission.js

@@ -0,0 +1,250 @@
+import { randomUUID } from "node:crypto";
+import { parseAgentTurnId } from "@agen-ai/agent-protocol";
+import { AgentProviderContractError, AgentProviderSessionCleanupError } from "../contractErrors.js";
+import { interactionRecord } from "../sessionInteractions/validation.js";
+import { hasExactOwnKeys } from "../internal/objectShape.js";
+import { validateAgentRequestResolutionResult } from "../turnExecution/receipts.js";
+function mintSessionResponseAttemptId() {
+  return randomUUID();
+}
+function continuationError(owner, code, message, cause) {
+  return new AgentProviderContractError(owner.providerKey, code, message, ...cause === void 0 ? [] : [{ cause }]);
+}
+function until(work, deadline, failure, signal) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(failure()), Math.max(0, deadline - Date.now()));
+    const aborted = () => reject(signal?.reason ?? new DOMException("Prepared response was aborted.", "AbortError"));
+    signal?.addEventListener("abort", aborted, { once: true });
+    if (signal?.aborted) aborted();
+    void work.then(resolve, reject).finally(() => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", aborted);
+    });
+  });
+}
+function capturePrepared(input) {
+  const value = interactionRecord(input);
+  if (typeof value.dispatch !== "function" || typeof value.cancel !== "function") throw new TypeError("Prepared response requires dispatch and cancellation ports.");
+  if (value.kind === "no_continuation" && hasExactOwnKeys(value, ["kind", "dispatch", "cancel"])) {
+    return Object.freeze({ kind: "no_continuation", dispatch: value.dispatch.bind(input), cancel: value.cancel.bind(input) });
+  }
+  if (value.kind === "native_continuation" && hasExactOwnKeys(value, ["kind", "dispatch", "cancel", "createExecution", "outcome"]) && typeof value.createExecution === "function" && value.outcome && typeof interactionRecord(value.outcome).then === "function") {
+    return Object.freeze({
+      kind: "native_continuation",
+      dispatch: value.dispatch.bind(input),
+      cancel: value.cancel.bind(input),
+      createExecution: value.createExecution.bind(input),
+      outcome: Promise.resolve(value.outcome)
+    });
+  }
+  throw new TypeError("Invalid prepared response.");
+}
+function outcome(input) {
+  const value = interactionRecord(input);
+  if (!hasExactOwnKeys(value, ["kind"]) || value.kind !== "started" && value.kind !== "not_started") throw new TypeError("Invalid continuation outcome.");
+  return Object.freeze({ kind: value.kind });
+}
+async function dispatchPreparedSessionResponse(input) {
+  const { owner } = input;
+  const readinessDeadline = Date.now() + 3e4;
+  const controller = new AbortController();
+  const signal = AbortSignal.any([input.signal, controller.signal, owner.openingSignal]);
+  let prepared;
+  let execution;
+  let reservation;
+  let entered = false;
+  let callback;
+  let callbackFailure;
+  let cancelAttempt;
+  let canceled = false;
+  let actualOutcome;
+  let earlyOutcome;
+  let outcomeFailure;
+  let resolveOutcome;
+  let rejectOutcome;
+  const publicOutcome = new Promise((resolve, reject) => {
+    resolveOutcome = resolve;
+    rejectOutcome = reject;
+  });
+  void publicOutcome.catch(() => {
+  });
+  const actualPreparation = owner.track(Promise.resolve().then(() => {
+    input.requireCurrent();
+    owner.requireUsable();
+    return input.candidate.prepareResponse({
+      response: input.response,
+      responseAttemptId: input.attemptId,
+      signal
+    });
+  }).then((value) => {
+    try {
+      return capturePrepared(value);
+    } catch (cause) {
+      throw continuationError(owner, "invalid_native_continuation", "Provider returned an invalid prepared response.", cause);
+    }
+  }).then((value) => {
+    prepared = value;
+    if (value.kind === "native_continuation") {
+      actualOutcome = owner.track(value.outcome.then((value2) => {
+        const parsed = outcome(value2);
+        if (!entered) {
+          earlyOutcome = parsed;
+          if (parsed.kind === "started") throw continuationError(owner, "invalid_native_continuation", "Provider started native work before dispatch.");
+        }
+        return parsed;
+      }).catch((cause) => {
+        throw cause instanceof AgentProviderContractError && cause.code === "invalid_native_continuation" ? cause : continuationError(owner, "invalid_native_continuation", "Provider native continuation outcome is invalid.", cause);
+      }));
+      void actualOutcome.catch((cause) => {
+        outcomeFailure = cause;
+        if (entered) owner.fail(cause);
+      });
+    }
+    return value;
+  }));
+  void actualPreparation.catch(() => {
+  });
+  const cancel = () => {
+    if (canceled) return Promise.resolve();
+    if (cancelAttempt) return cancelAttempt;
+    controller.abort(new DOMException("Prepared response admission was canceled.", "AbortError"));
+    cancelAttempt = (async () => {
+      let value;
+      try {
+        value = prepared ?? await actualPreparation;
+      } catch (cause) {
+        cleanup();
+        owner.fail(cause);
+        throw continuationError(owner, "native_continuation_preparation_failed", "Preparation failed without returning its allocated cancellation owner.", cause);
+      }
+      execution?.stop(new DOMException("Prepared execution admission was canceled.", "AbortError"));
+      await value.cancel();
+      execution?.settleNoWork();
+      await execution?.join();
+      if (value.kind === "native_continuation") {
+        const result = await actualOutcome;
+        if (result?.kind !== "not_started") throw continuationError(owner, "invalid_native_continuation", "Canceled preparation did not prove no native work.");
+      }
+      resolveOutcome(Object.freeze({ kind: "not_started" }));
+      await callback?.catch(() => {
+      });
+      if (reservation) owner.validationOwner.releaseExecution(reservation);
+      canceled = true;
+    })().finally(() => {
+      cancelAttempt = void 0;
+    });
+    void cancelAttempt.catch(() => {
+    });
+    return cancelAttempt;
+  };
+  const cleanup = owner.retainPreparation(async () => {
+    if (!entered) await cancel();
+  });
+  try {
+    const value = await until(actualPreparation, readinessDeadline, () => continuationError(owner, "native_continuation_preparation_failed", "Native continuation preparation did not finish before its deadline."), signal);
+    input.requireCurrent();
+    owner.requireUsable();
+    if (outcomeFailure) throw outcomeFailure;
+    if (earlyOutcome) throw continuationError(owner, "invalid_native_continuation", "Prepared outcome forbids native response dispatch.");
+    if (value.kind === "native_continuation") {
+      owner.requireContinuation(input.candidate.request.kind);
+      reservation = owner.validationOwner.reserveExecution();
+      const turnId = parseAgentTurnId(`native-${randomUUID()}`);
+      execution = owner.validationOwner.installNativeExecution(reservation, turnId, (executionSignal) => value.createExecution({ turnId, signal: executionSignal }));
+      const offered = execution;
+      try {
+        callback = Promise.resolve(owner.continuations.onExecution(Object.freeze({
+          sessionId: owner.sessionId,
+          requestId: input.candidate.request.requestId,
+          responseAttemptId: input.attemptId,
+          execution: offered.execution,
+          outcome: publicOutcome
+        })));
+      } catch (cause) {
+        callbackFailure = { cause };
+        callback = Promise.reject(cause);
+      }
+      owner.track(callback);
+      const rejection = new Promise((_, reject) => {
+        void callback.catch(reject);
+      });
+      void callback.catch((cause) => {
+        callbackFailure = { cause };
+        if (entered) owner.fail(cause);
+      });
+      await until(
+        Promise.race([offered.readerReady, rejection]),
+        readinessDeadline,
+        () => continuationError(owner, "native_continuation_reader_not_ready", "Native continuation requires an outstanding output pull."),
+        signal
+      );
+    }
+    input.requireCurrent();
+    owner.requireUsable();
+    if (signal.aborted) throw signal.reason;
+    if (Date.now() >= readinessDeadline) throw continuationError(owner, "native_continuation_reader_not_ready", "Native continuation reader admission expired.");
+    if (callbackFailure) throw continuationError(owner, "native_continuation_reader_not_ready", "Native continuation host rejected output ownership before dispatch.", callbackFailure.cause);
+    if (outcomeFailure || earlyOutcome) throw outcomeFailure ?? continuationError(owner, "invalid_native_continuation", "Prepared outcome arrived before dispatch.");
+    if (reservation && !owner.validationOwner.ownsExecution(reservation)) throw continuationError(owner, "invalid_native_continuation", "Native continuation lost its execution reservation.");
+    try {
+      execution?.admitDispatch();
+    } catch (cause) {
+      throw continuationError(owner, "native_continuation_reader_not_ready", "Native continuation output ownership ended before dispatch.", cause);
+    }
+    const responseDeadline = Date.now() + owner.limits.responseTimeoutMs;
+    entered = true;
+    input.onDispatch(responseDeadline);
+    let actualReceipt;
+    try {
+      actualReceipt = Promise.resolve(value.dispatch()).then((result) => validateAgentRequestResolutionResult(result, owner.providerKey));
+    } catch (cause) {
+      actualReceipt = Promise.reject(cause);
+    }
+    owner.track(actualReceipt);
+    input.observeActualReceipt(actualReceipt);
+    if (actualOutcome && execution) {
+      const currentExecution = execution;
+      const exactReservation = reservation;
+      const observedOutcome = until(actualOutcome, responseDeadline, () => continuationError(owner, "invalid_native_continuation", "Native continuation outcome did not settle before its response deadline."));
+      owner.track(observedOutcome.then(async (result) => {
+        resolveOutcome(result);
+        if (result.kind === "not_started") currentExecution.settleNoWork();
+        else currentExecution.markStarted();
+        await currentExecution.completed;
+        await actualReceipt.catch(() => {
+        });
+        await callback?.catch(() => {
+        });
+        await currentExecution.join();
+        owner.validationOwner.releaseExecution(exactReservation);
+      }).catch((cause) => {
+        rejectOutcome(cause);
+        owner.fail(cause);
+      }));
+    }
+    return await until(actualReceipt, responseDeadline, () => new Error("Session response delivery observation expired."));
+  } catch (cause) {
+    if (entered) throw cause;
+    let failure = cause;
+    if (!(cause instanceof AgentProviderContractError) && !(cause instanceof DOMException && cause.name === "AbortError")) {
+      failure = continuationError(owner, prepared ? "native_continuation_reader_not_ready" : "native_continuation_preparation_failed", "Native continuation failed before response entry.", cause);
+    }
+    try {
+      await until(cancel(), Date.now() + owner.limits.cleanupTimeoutMs, () => new Error("Prepared cancellation did not finish before its deadline."));
+    } catch (cleanupFailure) {
+      owner.fail(failure);
+      throw new AgentProviderSessionCleanupError({ providerKey: owner.providerKey, errors: [failure, cleanupFailure], retryCleanup: async () => {
+        if (prepared) await cancel();
+        else await owner.cleanupFailedPreparation();
+      } });
+    }
+    if (failure instanceof AgentProviderContractError && failure.code === "invalid_native_continuation") owner.fail(failure);
+    throw failure;
+  } finally {
+    if (entered || canceled) cleanup();
+  }
+}
+export {
+  dispatchPreparedSessionResponse,
+  mintSessionResponseAttemptId
+};

package/dist/nativeContinuations/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/nativeContinuations/index.js

@@ -0,0 +1 @@
+export * from "./types.js";

package/dist/nativeContinuations/types.d.ts

@@ -0,0 +1,52 @@
+import type { AgentRequestId, AgentSessionId, AgentTurnId } from "@agen-ai/agent-protocol";
+import type { MaybePromise } from "../foundation.js";
+import type { AgentProviderTurnExecution, AgentRequestResolutionResult } from "../sessions.js";
+import type { AgentSessionInteractionOpeningOperation } from "../sessionInteractions/types.js";
+declare const agentSessionResponseAttemptIdBrand: unique symbol;
+export type AgentSessionResponseAttemptId = string & {
+    readonly [agentSessionResponseAttemptIdBrand]: "AgentSessionResponseAttemptId";
+};
+export type AgentNativeContinuationTiming = "after_open_return" | "before_open_return" | "before_binding";
+export interface AgentNativeContinuationMapping {
+    readonly openingOperation: AgentSessionInteractionOpeningOperation;
+    readonly requestKind: "form" | "plan_review";
+    readonly timing: AgentNativeContinuationTiming;
+}
+export type AgentNativeContinuationSupport = Readonly<{
+    kind: "unsupported";
+}> | Readonly<{
+    kind: "supported";
+    mappings: readonly [AgentNativeContinuationMapping, ...AgentNativeContinuationMapping[]];
+    producerOwnership: "exclusive";
+}>;
+export type AgentNativeContinuationOutcome = Readonly<{
+    kind: "started";
+}> | Readonly<{
+    kind: "not_started";
+}>;
+export interface AgentPreparedSessionResponseControl {
+    readonly dispatch: () => Promise<AgentRequestResolutionResult>;
+    readonly cancel: () => Promise<void>;
+}
+export type AgentPreparedSessionResponse = (AgentPreparedSessionResponseControl & Readonly<{
+    kind: "no_continuation";
+}>) | (AgentPreparedSessionResponseControl & Readonly<{
+    kind: "native_continuation";
+    createExecution: (input: Readonly<{
+        turnId: AgentTurnId;
+        signal: AbortSignal;
+    }>) => AgentProviderTurnExecution;
+    outcome: Promise<AgentNativeContinuationOutcome>;
+}>);
+export interface AgentNativeContinuation {
+    readonly sessionId: AgentSessionId;
+    readonly requestId: AgentRequestId;
+    readonly responseAttemptId: AgentSessionResponseAttemptId;
+    readonly execution: AgentProviderTurnExecution;
+    readonly outcome: Promise<AgentNativeContinuationOutcome>;
+}
+export interface AgentNativeContinuationContext {
+    readonly onExecution: (continuation: AgentNativeContinuation) => MaybePromise<void>;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/outputValidation.js

@@ -56,8 +56,8 @@ function isApprovalRequestCapabilitySupported(capabilities, event) {
   if (request.requestKind !== "approval") return false;
   const capability = capabilities.requests.approval;
   return capability.kind === "supported" && request.options.every(
-    (option) => capability.modes.some(
-      (mode) => mode.persistence === option.persistence && mode.scopeKinds.includes(option.scope.kind)
+    ({ consequence }) => consequence.kind === "provider_managed_remembrance" ? capability.providerManagedRemembrance : capability.modes.some(
+      (mode) => mode.persistence === consequence.persistence && mode.scopeKinds.includes(consequence.scope.kind)
     )
   );
 }
@@ -120,6 +120,7 @@ function isEventCapabilitySupported(capabilities, event) {
     case "context.usage.updated":
       return isContextUsageCapabilitySupported(capabilities, event);
     case "turn.started":
+    case "request.unavailable":
     case "turn.state_changed":
     case "turn.completed":
     case "progress.updated":

package/dist/providerCatalog.d.ts

@@ -9,5 +9,5 @@ export interface AgentProviderInstanceCatalogEntry {
     readonly capabilities: AgentCapabilities;
 }
 export declare function createAgentProviderCatalogEntries(drivers: Iterable<AgentProviderDriver>): readonly AgentProviderCatalogEntry[];
-export declare function createAgentProviderInstanceCatalogEntries(instances: readonly MaterializedAgentProviderInstance[]): readonly AgentProviderInstanceCatalogEntry[];
+export declare function createAgentProviderInstanceCatalogEntries(instances: readonly Pick<MaterializedAgentProviderInstance, "instanceId" | "capabilities">[]): readonly AgentProviderInstanceCatalogEntry[];
 //# sourceMappingURL=providerCatalog.d.ts.map

package/dist/providerDriver.d.ts

@@ -3,7 +3,7 @@ import type { MaybePromise } from "./foundation.js";
 import type { AgentAccountQuotaPort } from "./accountQuota/types.js";
 import type { AgentEnvironmentDiscoveryPort } from "./environment/types.js";
 import type { AgentProviderReadiness } from "./readiness.js";
-import type { AgentProviderAdapter } from "./sessions.js";
+import type { AgentProviderAdapter, AgentValidatedProviderAdapter } from "./sessions.js";
 export interface AgentProviderInstanceDefinition {
     readonly providerKey: AgentProviderKey;
     readonly instanceId: AgentInstanceId;
@@ -21,6 +21,9 @@ export interface MaterializedAgentProviderInstance {
     readonly checkReadiness: (input?: AgentProviderReadinessCheckInput) => MaybePromise<AgentProviderReadiness>;
     readonly dispose: () => MaybePromise<void>;
 }
+export type ValidatedMaterializedAgentProviderInstance = Omit<MaterializedAgentProviderInstance, "adapter"> & Readonly<{
+    adapter: AgentValidatedProviderAdapter;
+}>;
 export interface AgentProviderDriverCreateInput<Configuration> {
     readonly instanceId: AgentInstanceId;
     readonly configuration: Configuration;

package/dist/providerDriver.js

@@ -11,7 +11,6 @@ class AgentProviderConfigurationError extends Error {
     this.providerKey = providerKey;
     this.name = "AgentProviderConfigurationError";
   }
-  providerKey;
 }
 function defineAgentProviderDriver(definition) {
   const providerKey = parseAgentProviderKey(definition.providerKey);

package/dist/providerInstanceRegistry.d.ts

@@ -1,6 +1,6 @@
 import { type AgentInstanceId, type AgentProviderKey } from "@agen-ai/agent-protocol";
 import { type AgentProviderCatalogEntry, type AgentProviderInstanceCatalogEntry } from "./providerCatalog.js";
-import { type AgentProviderDriver, type AgentProviderInstanceDefinition, type MaterializedAgentProviderInstance } from "./providerDriver.js";
+import { type AgentProviderDriver, type AgentProviderInstanceDefinition, type ValidatedMaterializedAgentProviderInstance } from "./providerDriver.js";
 import { type AgentProviderReadiness } from "./readiness.js";
 export declare const AGENT_PROVIDER_REGISTRY_ERROR_CODES: readonly ["invalid_driver", "duplicate_provider", "duplicate_instance", "provider_not_registered", "multiple_instances_unsupported", "invalid_instance_configuration", "instance_materialization_failed", "instance_contract_mismatch", "instance_not_found", "instance_disposed", "instance_cleanup_failed", "registry_disposed"];
 export type AgentProviderRegistryErrorCode = (typeof AGENT_PROVIDER_REGISTRY_ERROR_CODES)[number];
@@ -22,10 +22,10 @@ export declare class AgentProviderRegistryError extends Error {
 export interface AgentProviderRegistry {
     readonly listProviderCatalogEntries: () => readonly AgentProviderCatalogEntry[];
     readonly listInstanceCatalogEntries: () => readonly AgentProviderInstanceCatalogEntry[];
-    readonly listInstances: () => readonly MaterializedAgentProviderInstance[];
-    readonly getInstance: (instanceId: AgentInstanceId) => MaterializedAgentProviderInstance | null;
+    readonly listInstances: () => readonly ValidatedMaterializedAgentProviderInstance[];
+    readonly getInstance: (instanceId: AgentInstanceId) => ValidatedMaterializedAgentProviderInstance | null;
     readonly hasInstance: (instanceId: AgentInstanceId) => boolean;
-    readonly requireInstance: (instanceId: AgentInstanceId) => MaterializedAgentProviderInstance;
+    readonly requireInstance: (instanceId: AgentInstanceId) => ValidatedMaterializedAgentProviderInstance;
     readonly checkReadiness: (instanceId: AgentInstanceId, input?: Readonly<{
         signal?: AbortSignal;
     }>) => Promise<AgentProviderReadiness>;

package/dist/providerInstanceRegistry.js

@@ -213,7 +213,8 @@ async function materializeInstances(input) {
         providerKey: definition.providerKey,
         instanceId: definition.instanceId,
         cleanupFailureInstanceIds,
-        message: error instanceof AgentProviderConfigurationError ? `Agent provider configuration is invalid for ${definition.instanceId}.` : `Agent provider instance ${definition.instanceId} could not be materialized.`
+        message: error instanceof AgentProviderConfigurationError ? `Agent provider configuration is invalid for ${definition.instanceId}.` : `Agent provider instance ${definition.instanceId} could not be materialized.`,
+        cause: error
       });
     }
     let managed;

package/dist/sessionAdmission.d.ts

@@ -0,0 +1,12 @@
+import type { AgentProviderKey, AgentRequestId } from "@agen-ai/agent-protocol";
+export declare function createAgentSessionAdmission<Execution = unknown>(providerKey: AgentProviderKey): {
+    reserveExecution(): object;
+    installExecution(token: object, execution: Execution): void;
+    releaseExecution(token: object): void;
+    readonly execution: Execution | null;
+    ownsExecution(token: object): boolean;
+    stop(): void;
+    claimRequest(requestId: AgentRequestId, duplicateCode: "invalid_turn_sequence" | "invalid_session_interaction"): void;
+};
+export type AgentSessionAdmission = Pick<ReturnType<typeof createAgentSessionAdmission>, "claimRequest">;
+//# sourceMappingURL=sessionAdmission.d.ts.map

package/dist/sessionAdmission.js

@@ -0,0 +1,54 @@
+import { throwAgentProviderContractError } from "./contractErrors.js";
+const MAX_REQUEST_IDENTITIES = 4096;
+const MAX_REQUEST_ID_BYTES = 1048576;
+function createAgentSessionAdmission(providerKey) {
+  const requestIds = /* @__PURE__ */ new Set();
+  let requestIdBytes = 0;
+  let slot;
+  let stopped = false;
+  return {
+    reserveExecution() {
+      if (stopped) throwAgentProviderContractError(providerKey, "session_unusable", "Session admission is stopped.");
+      if (slot) throwAgentProviderContractError(providerKey, "concurrent_turn", "Provider session already owns an execution.");
+      const token = Object.freeze({});
+      slot = { kind: "reserved", token };
+      return token;
+    },
+    installExecution(token, execution) {
+      if (stopped || !slot || slot.token !== token || slot.kind !== "reserved") {
+        throwAgentProviderContractError(providerKey, "invalid_native_continuation", "Execution reservation is no longer installable.");
+      }
+      slot = { kind: "installed", token, execution };
+    },
+    releaseExecution(token) {
+      if (slot?.token === token) slot = void 0;
+    },
+    get execution() {
+      return slot?.kind === "installed" ? slot.execution : null;
+    },
+    ownsExecution(token) {
+      return !stopped && slot?.token === token;
+    },
+    stop() {
+      stopped = true;
+    },
+    claimRequest(requestId, duplicateCode) {
+      if (requestIds.has(requestId)) {
+        throwAgentProviderContractError(providerKey, duplicateCode, "Provider reused a request ID within this session generation.");
+      }
+      const bytes = Buffer.byteLength(requestId, "utf8");
+      if (requestIds.size >= MAX_REQUEST_IDENTITIES || requestIdBytes + bytes > MAX_REQUEST_ID_BYTES) {
+        throwAgentProviderContractError(
+          providerKey,
+          "request_identity_limit_exceeded",
+          "Provider exceeded this session generation's bounded request identity capacity."
+        );
+      }
+      requestIds.add(requestId);
+      requestIdBytes += bytes;
+    }
+  };
+}
+export {
+  createAgentSessionAdmission
+};

package/dist/sessionInteractions/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/sessionInteractions/index.js

@@ -0,0 +1 @@
+export * from "./types.js";