@agen-ai/agent-runtime 0.3.1 → 0.4.1

package/dist/adapterValidation.js

@@ -13,6 +13,11 @@ import {
   throwIfAgentOperationAborted
 } from "./foundation.js";
 import { containsAgentControlCharacter } from "./internal/controlCharacters.js";
+import { withAgentSessionHostBinding } from "./hostBindings/lifetime.js";
+import { invokeAgentSessionOpening } from "./hostBindings/opening.js";
+import { validateAgentSessionHostBindingSupport } from "./hostBindings/validation.js";
+import { createSessionInteractionOwner } from "./sessionInteractions/lifetime.js";
+import { validateSessionInteractionSupport } from "./sessionInteractions/validation.js";
 import {
   validateAgentProviderOperationResult,
   validateAgentProviderOutputForContext
@@ -22,6 +27,7 @@ import {
   openIdentityCreatingAgentProviderSession,
   validateAgentProviderSession
 } from "./sessionValidation.js";
+const validatedAdapters = /* @__PURE__ */ new WeakMap();
 function parseWorkingDirectory(value) {
   if (value.length < 1 || value.length > 4096 || !path.isAbsolute(value) || path.normalize(value) !== value || containsAgentControlCharacter(value)) {
     throw new TypeError(
@@ -40,8 +46,9 @@ function assertAuthenticationOutputKind(providerKey, output) {
     "Authentication may emit only authentication, lifecycle, or evidence output."
   );
 }
-function validateAgentProviderAdapter(capabilityInput, adapter) {
+function validateAgentProviderAdapter(capabilityInput, adapterInput) {
   const capabilities = parseAgentCapabilities(capabilityInput);
+  const adapter = validatedAdapters.get(adapterInput) ?? adapterInput;
   if (adapter === null || typeof adapter !== "object" || typeof adapter.createSession !== "function" || adapter.resumption === null || typeof adapter.resumption !== "object" || !["supported", "unsupported"].includes(adapter.resumption.kind) || adapter.resumption.kind === "supported" && typeof adapter.resumption.resumeSession !== "function" || adapter.branching === null || typeof adapter.branching !== "object" || !["through_turn", "unsupported"].includes(adapter.branching.kind) || adapter.branching.kind === "through_turn" && typeof adapter.branching.branchSession !== "function" || adapter.authentication === null || typeof adapter.authentication !== "object" || !["supported", "unsupported"].includes(adapter.authentication.kind) || adapter.authentication.kind === "supported" && (typeof adapter.authentication.start !== "function" || typeof adapter.authentication.cancel !== "function")) {
     throwAgentProviderContractError(
       capabilities.providerKey,
@@ -57,83 +64,153 @@ function validateAgentProviderAdapter(capabilityInput, adapter) {
     );
   }
   const declaredResumption = adapter.resumption;
+  const sessionInteractions = validateSessionInteractionSupport(capabilities, adapter);
+  let hostBinding;
+  try {
+    hostBinding = validateAgentSessionHostBindingSupport(adapter.hostBinding);
+  } catch {
+    return throwAgentProviderContractError(
+      capabilities.providerKey,
+      "invalid_adapter",
+      "Provider declared invalid session host binding support."
+    );
+  }
   const resumption = declaredResumption.kind === "unsupported" ? Object.freeze({ kind: "unsupported" }) : Object.freeze({
     kind: "supported",
-    resumeSession: async (resumeInput) => {
-      throwIfAgentOperationAborted(resumeInput.signal);
-      const parsed = parseAgentSessionOpenInput({
-        operation: "resume",
-        sessionId: resumeInput.sessionId,
-        binding: resumeInput.binding,
-        configuration: resumeInput.configuration
-      });
-      if (parsed.operation !== "resume") {
-        throw new TypeError("Expected a resume session input.");
-      }
-      assertAgentSessionConfigurationSupported(
-        capabilities,
-        parsed.configuration
-      );
-      const workingDirectory = parseWorkingDirectory(
-        resumeInput.workingDirectory
-      );
-      const binding = parsed.binding;
-      const candidate = await declaredResumption.resumeSession({
-        sessionId: parsed.sessionId,
-        workingDirectory,
-        binding,
-        configuration: parsed.configuration,
-        ...resumeInput.signal === void 0 ? {} : { signal: resumeInput.signal }
-      });
-      try {
-        return validateAgentProviderSession({
+    resumeSession: async (resumeInput) => withAgentSessionHostBinding({
+      providerKey: capabilities.providerKey,
+      binding: resumeInput.hostBinding,
+      openingInput: resumeInput,
+      support: hostBinding,
+      open: async (lease) => {
+        throwIfAgentOperationAborted(resumeInput.signal);
+        const parsed = parseAgentSessionOpenInput({
+          operation: "resume",
+          sessionId: resumeInput.sessionId,
+          binding: resumeInput.binding,
+          configuration: resumeInput.configuration
+        });
+        if (parsed.operation !== "resume") {
+          throw new TypeError("Expected a resume session input.");
+        }
+        assertAgentSessionConfigurationSupported(
           capabilities,
+          parsed.configuration
+        );
+        const workingDirectory = parseWorkingDirectory(
+          resumeInput.workingDirectory
+        );
+        const binding = parsed.binding;
+        const interactions = createSessionInteractionOwner({
+          providerKey: capabilities.providerKey,
           sessionId: parsed.sessionId,
-          candidate,
-          expectedBinding: binding
+          operation: "resume",
+          support: sessionInteractions,
+          ...resumeInput.interactions === void 0 ? {} : { context: resumeInput.interactions },
+          ...resumeInput.signal === void 0 ? {} : { signal: resumeInput.signal }
+        });
+        const candidate = await invokeAgentSessionOpening({
+          providerKey: capabilities.providerKey,
+          openingInput: resumeInput,
+          lease,
+          ...interactions === void 0 ? {} : { interactions },
+          open: (context) => declaredResumption.resumeSession(context),
+          candidateInput: {
+            sessionId: parsed.sessionId,
+            workingDirectory,
+            binding,
+            configuration: parsed.configuration,
+            ...lease === void 0 ? {} : { hostBinding: lease.binding },
+            ...interactions === void 0 ? {} : { interactions: interactions.facade },
+            ...(interactions?.openingSignal ?? resumeInput.signal) === void 0 ? {} : { signal: interactions?.openingSignal ?? resumeInput.signal }
+          }
         });
-      } catch (error) {
-        return closeRejectedAgentProviderSession(candidate, error);
+        try {
+          const session = validateAgentProviderSession({
+            capabilities,
+            sessionId: parsed.sessionId,
+            candidate,
+            expectedBinding: binding,
+            ...interactions === void 0 ? {} : { sessionInteractionOwner: interactions },
+            ...lease === void 0 ? {} : { hostBindingLease: lease }
+          });
+          interactions?.adopt();
+          return session;
+        } catch (error) {
+          return closeRejectedAgentProviderSession(
+            candidate,
+            error,
+            lease === void 0 ? void 0 : { providerKey: capabilities.providerKey, lease },
+            { providerKey: capabilities.providerKey, input: resumeInput },
+            interactions
+          );
+        }
       }
-    }
+    })
   });
   const declaredBranching = adapter.branching;
   const branching = declaredBranching.kind === "unsupported" ? Object.freeze({ kind: "unsupported" }) : Object.freeze({
     kind: "through_turn",
-    branchSession: async (branchInput) => {
-      throwIfAgentOperationAborted(branchInput.signal);
-      const parsed = parseAgentSessionOpenInput({
-        operation: "branch",
-        sessionId: branchInput.sessionId,
-        source: branchInput.source,
-        configuration: branchInput.configuration
-      });
-      if (parsed.operation !== "branch") {
-        throw new TypeError("Expected a branch session input.");
-      }
-      assertAgentSessionConfigurationSupported(
-        capabilities,
-        parsed.configuration
-      );
-      const workingDirectory = parseWorkingDirectory(
-        branchInput.workingDirectory
-      );
-      const sourceBinding = parsed.source.binding;
-      return openIdentityCreatingAgentProviderSession({
-        capabilities,
-        sessionId: parsed.sessionId,
-        observer: branchInput.onBindingCreated,
-        sourceBinding,
-        open: (observer) => declaredBranching.branchSession({
+    branchSession: async (branchInput) => withAgentSessionHostBinding({
+      providerKey: capabilities.providerKey,
+      binding: branchInput.hostBinding,
+      openingInput: branchInput,
+      support: hostBinding,
+      open: async (lease) => {
+        throwIfAgentOperationAborted(branchInput.signal);
+        const parsed = parseAgentSessionOpenInput({
+          operation: "branch",
+          sessionId: branchInput.sessionId,
+          source: branchInput.source,
+          configuration: branchInput.configuration
+        });
+        if (parsed.operation !== "branch") {
+          throw new TypeError("Expected a branch session input.");
+        }
+        assertAgentSessionConfigurationSupported(
+          capabilities,
+          parsed.configuration
+        );
+        const workingDirectory = parseWorkingDirectory(
+          branchInput.workingDirectory
+        );
+        const sourceBinding = parsed.source.binding;
+        const interactions = createSessionInteractionOwner({
+          providerKey: capabilities.providerKey,
           sessionId: parsed.sessionId,
-          workingDirectory,
-          source: parsed.source,
-          configuration: parsed.configuration,
-          onBindingCreated: observer,
+          operation: "branch",
+          support: sessionInteractions,
+          ...branchInput.interactions === void 0 ? {} : { context: branchInput.interactions },
           ...branchInput.signal === void 0 ? {} : { signal: branchInput.signal }
-        })
-      });
-    }
+        });
+        return openIdentityCreatingAgentProviderSession({
+          capabilities,
+          sessionId: parsed.sessionId,
+          observer: branchInput.onBindingCreated,
+          sourceBinding,
+          openingInput: branchInput,
+          ...interactions === void 0 ? {} : { sessionInteractionOwner: interactions },
+          ...lease === void 0 ? {} : { hostBindingLease: lease },
+          open: (observer) => invokeAgentSessionOpening({
+            providerKey: capabilities.providerKey,
+            openingInput: branchInput,
+            lease,
+            ...interactions === void 0 ? {} : { interactions },
+            open: (context) => declaredBranching.branchSession(context),
+            candidateInput: {
+              sessionId: parsed.sessionId,
+              workingDirectory,
+              source: parsed.source,
+              configuration: parsed.configuration,
+              onBindingCreated: observer,
+              ...lease === void 0 ? {} : { hostBinding: lease.binding },
+              ...interactions === void 0 ? {} : { interactions: interactions.facade },
+              ...(interactions?.openingSignal ?? branchInput.signal) === void 0 ? {} : { signal: interactions?.openingSignal ?? branchInput.signal }
+            }
+          })
+        });
+      }
+    })
   });
   const declaredAuthentication = adapter.authentication;
   const authenticationFlows = capabilities.authentication.kind === "supported" ? capabilities.authentication.flows : [];
@@ -204,38 +281,68 @@ function validateAgentProviderAdapter(capabilityInput, adapter) {
       return result;
     }
   });
-  return Object.freeze({
-    createSession: async (createInput) => {
-      throwIfAgentOperationAborted(createInput.signal);
-      const parsed = parseAgentSessionOpenInput({
-        operation: "create",
-        sessionId: createInput.sessionId,
-        configuration: createInput.configuration
-      });
-      assertAgentSessionConfigurationSupported(
-        capabilities,
-        parsed.configuration
-      );
-      const workingDirectory = parseWorkingDirectory(
-        createInput.workingDirectory
-      );
-      return openIdentityCreatingAgentProviderSession({
-        capabilities,
-        sessionId: parsed.sessionId,
-        observer: createInput.onBindingCreated,
-        open: (observer) => adapter.createSession({
+  const validated = Object.freeze({
+    hostBinding,
+    sessionInteractions,
+    createSession: async (createInput) => withAgentSessionHostBinding({
+      providerKey: capabilities.providerKey,
+      binding: createInput.hostBinding,
+      openingInput: createInput,
+      support: hostBinding,
+      open: async (lease) => {
+        throwIfAgentOperationAborted(createInput.signal);
+        const parsed = parseAgentSessionOpenInput({
+          operation: "create",
+          sessionId: createInput.sessionId,
+          configuration: createInput.configuration
+        });
+        assertAgentSessionConfigurationSupported(
+          capabilities,
+          parsed.configuration
+        );
+        const workingDirectory = parseWorkingDirectory(
+          createInput.workingDirectory
+        );
+        const interactions = createSessionInteractionOwner({
+          providerKey: capabilities.providerKey,
           sessionId: parsed.sessionId,
-          workingDirectory,
-          configuration: parsed.configuration,
-          onBindingCreated: observer,
+          operation: "create",
+          support: sessionInteractions,
+          ...createInput.interactions === void 0 ? {} : { context: createInput.interactions },
           ...createInput.signal === void 0 ? {} : { signal: createInput.signal }
-        })
-      });
-    },
+        });
+        return openIdentityCreatingAgentProviderSession({
+          capabilities,
+          sessionId: parsed.sessionId,
+          observer: createInput.onBindingCreated,
+          openingInput: createInput,
+          ...interactions === void 0 ? {} : { sessionInteractionOwner: interactions },
+          ...lease === void 0 ? {} : { hostBindingLease: lease },
+          open: (observer) => invokeAgentSessionOpening({
+            providerKey: capabilities.providerKey,
+            openingInput: createInput,
+            lease,
+            ...interactions === void 0 ? {} : { interactions },
+            open: (context) => adapter.createSession(context),
+            candidateInput: {
+              sessionId: parsed.sessionId,
+              workingDirectory,
+              configuration: parsed.configuration,
+              onBindingCreated: observer,
+              ...lease === void 0 ? {} : { hostBinding: lease.binding },
+              ...interactions === void 0 ? {} : { interactions: interactions.facade },
+              ...(interactions?.openingSignal ?? createInput.signal) === void 0 ? {} : { signal: interactions?.openingSignal ?? createInput.signal }
+            }
+          })
+        });
+      }
+    }),
     resumption,
     branching,
     authentication
   });
+  validatedAdapters.set(validated, adapter);
+  return validated;
 }
 export {
   validateAgentProviderAdapter

package/dist/artifacts.js

@@ -18,7 +18,6 @@ class AgentArtifactCandidateError extends TypeError {
     this.code = code;
     this.name = "AgentArtifactCandidateError";
   }
-  code;
 }
 function candidateError(code) {
   throw new AgentArtifactCandidateError(code);

package/dist/contractErrors.d.ts

@@ -1,11 +1,24 @@
 import type { AgentProviderKey } from "@agen-ai/agent-protocol";
-export declare const AGENT_PROVIDER_CONTRACT_ERROR_CODES: readonly ["capability_port_mismatch", "invalid_adapter", "invalid_session", "invalid_binding", "binding_callback_missing", "binding_callback_repeated", "binding_callback_mismatch", "resume_binding_mismatch", "branch_binding_reused", "session_closed", "session_unusable", "concurrent_turn", "active_turn_mismatch", "invalid_operation_result", "invalid_inventory", "invalid_collaboration_transition", "input_operation_mismatch", "output_session_mismatch", "output_turn_mismatch", "output_authentication_attempt_mismatch", "output_operation_mismatch", "output_collaboration_mismatch", "output_resource_mismatch", "output_capability_mismatch", "input_capability_mismatch", "invalid_turn_sequence", "request_resolution_mismatch", "configuration_key_unsupported", "configuration_value_unsupported", "request_pending"];
+import type { MaybePromise } from "./foundation.js";
+export declare const AGENT_PROVIDER_CONTRACT_ERROR_CODES: readonly ["capability_port_mismatch", "invalid_adapter", "invalid_session", "invalid_binding", "binding_callback_missing", "binding_callback_repeated", "binding_callback_mismatch", "resume_binding_mismatch", "branch_binding_reused", "session_closed", "session_unusable", "concurrent_turn", "active_turn_mismatch", "invalid_operation_result", "invalid_inventory", "invalid_collaboration_transition", "input_operation_mismatch", "output_session_mismatch", "output_turn_mismatch", "output_authentication_attempt_mismatch", "output_operation_mismatch", "output_collaboration_mismatch", "output_resource_mismatch", "output_capability_mismatch", "input_capability_mismatch", "invalid_turn_sequence", "request_resolution_mismatch", "configuration_key_unsupported", "configuration_value_unsupported", "request_pending", "invalid_host_binding", "host_binding_unsupported", "host_binding_reused", "host_binding_closed", "host_tool_name_conflict", "host_tool_input_invalid", "host_tool_result_invalid", "host_tool_capacity_exhausted", "invalid_session_interaction", "session_interactions_unsupported"];
 export type AgentProviderContractErrorCode = (typeof AGENT_PROVIDER_CONTRACT_ERROR_CODES)[number];
-export type AgentProviderDelegatedOperation = "steer_turn" | "invoke_operation" | "apply_configuration" | "spawn_collaboration" | "control_collaboration";
+export type AgentProviderDelegatedOperation = "resolve_request" | "steer_turn" | "invoke_operation" | "apply_configuration" | "spawn_collaboration" | "control_collaboration";
 export declare class AgentProviderContractError extends Error {
     readonly providerKey: AgentProviderKey;
     readonly code: AgentProviderContractErrorCode;
-    constructor(providerKey: AgentProviderKey, code: AgentProviderContractErrorCode, message: string);
+    constructor(providerKey: AgentProviderKey, code: AgentProviderContractErrorCode, message: string, options?: ErrorOptions);
+}
+export declare class AgentProviderSessionCleanupError extends AggregateError {
+    readonly providerKey: AgentProviderKey;
+    readonly retryCleanup: () => Promise<void>;
+    constructor(input: Readonly<{
+        providerKey: AgentProviderKey;
+        errors: readonly unknown[];
+        retryCleanup: () => MaybePromise<void>;
+    }>);
+}
+export declare class AgentProviderHostBindingCleanupError extends AgentProviderSessionCleanupError {
+    constructor(input: ConstructorParameters<typeof AgentProviderSessionCleanupError>[0]);
 }
 export declare class AgentProviderDelegatedOperationError extends Error {
     readonly providerKey: AgentProviderKey;

package/dist/contractErrors.js

@@ -28,17 +28,53 @@ const AGENT_PROVIDER_CONTRACT_ERROR_CODES = [
   "request_resolution_mismatch",
   "configuration_key_unsupported",
   "configuration_value_unsupported",
-  "request_pending"
+  "request_pending",
+  "invalid_host_binding",
+  "host_binding_unsupported",
+  "host_binding_reused",
+  "host_binding_closed",
+  "host_tool_name_conflict",
+  "host_tool_input_invalid",
+  "host_tool_result_invalid",
+  "host_tool_capacity_exhausted",
+  "invalid_session_interaction",
+  "session_interactions_unsupported"
 ];
 class AgentProviderContractError extends Error {
-  constructor(providerKey, code, message) {
-    super(message);
+  constructor(providerKey, code, message, options) {
+    super(message, options);
     this.providerKey = providerKey;
     this.code = code;
     this.name = "AgentProviderContractError";
   }
+}
+class AgentProviderSessionCleanupError extends AggregateError {
   providerKey;
-  code;
+  retryCleanup;
+  constructor(input) {
+    super(input.errors, "Provider session cleanup remains incomplete.");
+    this.name = "AgentProviderSessionCleanupError";
+    this.providerKey = input.providerKey;
+    let completed = false;
+    let pending = null;
+    this.retryCleanup = () => {
+      if (completed) return Promise.resolve();
+      if (pending) return pending;
+      pending = Promise.resolve().then(() => input.retryCleanup()).then(() => {
+        completed = true;
+      }).finally(() => {
+        pending = null;
+      });
+      return pending;
+    };
+  }
+}
+class AgentProviderHostBindingCleanupError extends AgentProviderSessionCleanupError {
+  constructor(input) {
+    super(input);
+    this.name = "AgentProviderHostBindingCleanupError";
+    this.message = "Provider session host binding cleanup remains incomplete.";
+  }
 }
 class AgentProviderDelegatedOperationError extends Error {
   constructor(providerKey, operation, cause) {
@@ -50,8 +86,6 @@ class AgentProviderDelegatedOperationError extends Error {
     this.operation = operation;
     this.name = "AgentProviderDelegatedOperationError";
   }
-  providerKey;
-  operation;
   providerExecution = "started";
 }
 function throwAgentProviderContractError(providerKey, code, message) {
@@ -61,5 +95,7 @@ export {
   AGENT_PROVIDER_CONTRACT_ERROR_CODES,
   AgentProviderContractError,
   AgentProviderDelegatedOperationError,
+  AgentProviderHostBindingCleanupError,
+  AgentProviderSessionCleanupError,
   throwAgentProviderContractError
 };

package/dist/hostBindings/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export { validateAgentSessionHostBinding, validateAgentHostToolInvocation, validateAgentHostToolResult } from "./validation.js";
+export { AGENT_HOST_TOOL_SCHEMA_DIALECT } from "./schema.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/hostBindings/index.js

@@ -0,0 +1,9 @@
+export * from "./types.js";
+import { validateAgentSessionHostBinding, validateAgentHostToolInvocation, validateAgentHostToolResult } from "./validation.js";
+import { AGENT_HOST_TOOL_SCHEMA_DIALECT } from "./schema.js";
+export {
+  AGENT_HOST_TOOL_SCHEMA_DIALECT,
+  validateAgentHostToolInvocation,
+  validateAgentHostToolResult,
+  validateAgentSessionHostBinding
+};

package/dist/hostBindings/lifetime.d.ts

@@ -0,0 +1,25 @@
+import { type AgentProviderKey } from "@agen-ai/agent-protocol";
+import { AgentProviderHostBindingCleanupError } from "../contractErrors.js";
+import { type MaybePromise } from "../foundation.js";
+import type { AgentProviderSession } from "../sessions.js";
+import type { AgentSessionHostBinding, AgentSessionHostBindingSupport } from "./types.js";
+export interface AgentHostBindingLease {
+    readonly binding: AgentSessionHostBinding;
+    readonly initialize: (support: AgentSessionHostBindingSupport) => void;
+    readonly stop: () => void;
+    readonly release: () => Promise<void>;
+}
+export declare function createAgentHostBindingCleanupError(input: Readonly<{
+    providerKey: AgentProviderKey;
+    lease: AgentHostBindingLease;
+    errors: readonly unknown[];
+    retryCleanup: () => MaybePromise<void>;
+}>): AgentProviderHostBindingCleanupError;
+export declare function withAgentSessionHostBinding(input: Readonly<{
+    providerKey: AgentProviderKey;
+    binding?: AgentSessionHostBinding;
+    openingInput?: object;
+    support: AgentSessionHostBindingSupport;
+    open: (lease?: AgentHostBindingLease) => MaybePromise<AgentProviderSession>;
+}>): Promise<AgentProviderSession>;
+//# sourceMappingURL=lifetime.d.ts.map

package/dist/hostBindings/lifetime.js

@@ -0,0 +1,147 @@
+import { AgentProviderContractError, AgentProviderHostBindingCleanupError } from "../contractErrors.js";
+import { throwIfAgentOperationAborted } from "../foundation.js";
+import { associateAgentSessionCleanupError } from "../sessionCleanup.js";
+import { dataRecord } from "./schema.js";
+import { hostBindingEnvelope, validateAgentHostToolInvocation, validateAgentHostToolResult, validateAgentSessionHostBinding } from "./validation.js";
+const claimedBindings = /* @__PURE__ */ new WeakSet();
+const cleanupLeases = /* @__PURE__ */ new WeakMap();
+function createAgentHostBindingCleanupError(input) {
+  const error = new AgentProviderHostBindingCleanupError(input);
+  cleanupLeases.set(error, input.lease);
+  return error;
+}
+function claimBinding(providerKey, input) {
+  const fail = (code, message) => {
+    throw new AgentProviderContractError(providerKey, code, message);
+  };
+  let original;
+  try {
+    original = hostBindingEnvelope(input);
+  } catch {
+    return fail("invalid_host_binding", "Host binding requires a valid identity and callable ownership ports.");
+  }
+  if (claimedBindings.has(original)) fail("host_binding_reused", "Host binding is already claimed by a session opening.");
+  claimedBindings.add(original);
+  const releaseCallback = original.release.bind(original);
+  const lifetime = new AbortController();
+  const invocations = /* @__PURE__ */ new Map();
+  let facade;
+  let released = false;
+  let releasePromise = null;
+  const stop = () => {
+    lifetime.abort(new DOMException("The host binding was closed.", "AbortError"));
+  };
+  const release = () => {
+    if (released) return Promise.resolve();
+    if (releasePromise) return releasePromise;
+    stop();
+    releasePromise = Promise.resolve().then(async () => {
+      await Promise.allSettled(invocations.values());
+      await releaseCallback();
+      released = true;
+    }).finally(() => {
+      releasePromise = null;
+    });
+    return releasePromise;
+  };
+  const initialize = (support) => {
+    if (support.kind === "unsupported") return fail("host_binding_unsupported", "Provider does not support session host bindings.");
+    let validated;
+    try {
+      if (original.instructions !== void 0) {
+        const instructions = dataRecord(original.instructions);
+        if (!support.instructionPlacements.includes(instructions.placement)) {
+          fail("host_binding_unsupported", "Provider does not support the requested instruction placement.");
+        }
+      }
+      validated = validateAgentSessionHostBinding({ binding: original, support });
+    } catch (error) {
+      if (error instanceof AgentProviderContractError) throw error;
+      return fail("invalid_host_binding", "Host binding metadata is invalid.");
+    }
+    const invoke = (input2) => {
+      if (lifetime.signal.aborted) fail("host_binding_closed", "Host binding no longer accepts invocations.");
+      let invocation;
+      try {
+        invocation = validateAgentHostToolInvocation({ binding: validated, invocation: input2 });
+      } catch {
+        return fail("host_tool_input_invalid", "Host tool invocation has invalid arguments.");
+      }
+      const { invocationId } = invocation;
+      throwIfAgentOperationAborted(input2.signal);
+      if (invocations.has(invocationId)) fail("host_tool_input_invalid", "Host tool invocation is already active.");
+      if (invocations.size >= 16) fail("host_tool_capacity_exhausted", "Host binding has reached its invocation limit.");
+      const signal = input2.signal === void 0 ? lifetime.signal : AbortSignal.any([lifetime.signal, input2.signal]);
+      const promise = Promise.resolve().then(async () => {
+        let result;
+        try {
+          throwIfAgentOperationAborted(signal);
+          result = await validated.invoke({ ...invocation, signal });
+        } catch {
+          return Object.freeze({ kind: "error", error: Object.freeze({
+            category: "unknown",
+            code: "host_tool_failed",
+            message: "The host tool did not return a result.",
+            recovery: Object.freeze({ kind: "unknown" })
+          }) });
+        }
+        try {
+          return validateAgentHostToolResult(result);
+        } catch {
+          return fail("host_tool_result_invalid", "Host tool returned an invalid or oversized result.");
+        }
+      }).finally(() => {
+        invocations.delete(invocationId);
+      });
+      invocations.set(invocationId, promise);
+      return promise;
+    };
+    facade = Object.freeze({
+      ...validated,
+      invoke,
+      release: () => fail("invalid_host_binding", "Only the session owner may release a host binding.")
+    });
+  };
+  return {
+    get binding() {
+      if (!facade) return fail("invalid_host_binding", "Host binding has not been initialized.");
+      return facade;
+    },
+    initialize,
+    stop,
+    release
+  };
+}
+async function withAgentSessionHostBinding(input) {
+  let lease;
+  try {
+    if (input.binding !== void 0) {
+      lease = claimBinding(input.providerKey, input.binding);
+      lease.initialize(input.support);
+    }
+    return await input.open(lease);
+  } catch (error) {
+    if (lease && error instanceof AgentProviderHostBindingCleanupError && cleanupLeases.get(error) === lease) {
+      throw input.openingInput ? associateAgentSessionCleanupError(error, input.openingInput) : error;
+    }
+    if (lease) {
+      lease.stop();
+      try {
+        await lease.release();
+      } catch (cleanupError) {
+        const retained = createAgentHostBindingCleanupError({
+          providerKey: input.providerKey,
+          lease,
+          errors: [error, cleanupError],
+          retryCleanup: lease.release
+        });
+        throw input.openingInput ? associateAgentSessionCleanupError(retained, input.openingInput) : retained;
+      }
+    }
+    throw error;
+  }
+}
+export {
+  createAgentHostBindingCleanupError,
+  withAgentSessionHostBinding
+};

package/dist/hostBindings/opening.d.ts

@@ -0,0 +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