@agen-ai/agent-runtime 0.4.0 → 0.4.1

package/README.md

@@ -9,8 +9,9 @@ sessions; each returned session owns its binding and conversation-local operatio
 The runtime depends only on `@agen-ai/agent-protocol`. It has no concept of tenants, SaaS
 workspaces, assigned users, database rows, persistence sequence, visibility, billing, host boots,
 distributed leases, or storage policy. A host must authorize and select an instance before calling this SPI.
-This source package implements Agent Protocol V10 as part of the coordinated SDK
-`0.4.0` contract.
+This source package implements Agent Protocol V11 at coordinated SDK version `0.4.1`,
+which remains unpublished. The published release remains `0.4.0` with V10. The source candidate
+also includes the additive session-interaction API.
 Upgrade consumers from `0.3.1` using the coordinated release and its migration guide.
 The SDK contract version is independent of private transport and product persistence versions. This
 is intentionally one coordinated tuple rather than a deployable mixed-version graph.
@@ -19,7 +20,7 @@ is intentionally one coordinated tuple rather than a deployable mixed-version gr
 
 - `@agen-ai/agent-runtime` exports the public driver, instance, adapter, session, output,
   readiness, account-quota port validation, bounded-evidence, artifact-candidate,
-  capability-bound interaction validation, and registry APIs.
+  capability-bound interaction validation, session-lifetime interaction and cleanup APIs, and registry APIs.
 - `@agen-ai/agent-runtime/environment` exports the instance discovery and session observation ports.
 - `@agen-ai/agent-runtime/testing` exports the deterministic fake provider and reusable
   conformance runner.
@@ -29,7 +30,8 @@ is intentionally one coordinated tuple rather than a deployable mixed-version gr
 1. Define an `AgentProviderDriver` with `defineAgentProviderDriver`.
 2. Give caller-owned instance definitions to `createAgentProviderRegistry`.
 3. Select a materialized instance by opaque `instanceId`.
-4. Create, resume, or branch a provider session through its adapter.
+4. Create, resume, or branch a provider session through its adapter. If supported and needed,
+   supply the session-interaction handler on that opening input before calling the adapter.
 5. Call `startTurn` and consume its single `outputs` stream incrementally. Submit human answers with
    the same execution's `resolveRequest`, which returns an independent delivery receipt. Neutral `AgentEvent`
    output carries bounded provider source evidence atomically. A `request.opened` output may also
@@ -73,8 +75,19 @@ Explicit iterator return and normal end join native cleanup for at most 1,000 ms
 Approval continuations are refusal-first. Before delegating to the candidate adapter, the
 validated session proves that the request is still pending and unexpired and that a selected
 `optionId` was offered by that exact request. Provider-emitted approval requests must correlate to
-a live item or exact proposed-plan artifact, and every option must fit an advertised
-persistence/scope mode. Item identities are monotonic throughout a turn, including every request
+a live item or exact proposed-plan artifact. A scoped consequence must fit an exact advertised
+persistence/scope mode; a provider-managed remembrance consequence requires
+`providerManagedRemembrance: true` and retains explicit unknown duration and applicability.
+A delivered answer does not prove that a provider wrote a remembered rule. Exact offered IDs,
+once-only response entry, and uncertain-delivery fencing remain unchanged.
+Present every offered option's decision and consequence, then return the exact option chosen by
+the caller; options with the same immediate decision can have different consequences. A human
+handler should run independently while the original `execution.outputs` reader keeps consuming
+progress. Resolve on that same execution, inspect its receipt, and retain its output and cleanup
+owners through terminal settlement. A remembered answer creates no SDK rule or future automatic
+answer; later requests still need their own offered choice. An uncertain answer must not be replayed.
+
+Item identities are monotonic throughout a turn, including every request
 continuation: an adapter cannot restart an observed identity, change its kind, erase prior progress
 through an unknown-status update, regress it from in-progress to pending, or revive it after a
 terminal event or status. An `item.completed` event must carry `completed`, `failed`, or `canceled`
@@ -184,6 +197,100 @@ identity, declared bounds, forward-only lifecycle transitions, and per-output ba
 the operation result may settle. Collaboration and generated-resource observations retain the
 same correlation and lifecycle validation at their respective ports.
 
+## Session-lifetime interactions
+
+An adapter can offer a decision outside any model turn through `sessionInteractions`.
+Its support declaration is separate from V11 turn capabilities: absence means
+`{ kind: 'unsupported' }`; supported adapters name exact `openingOperations`, declare
+`requestKinds: ['decision']` and require `producerOwnership: 'exclusive'`. Supplying
+`interactions` for an unsupported opening raises `session_interactions_unsupported` before
+delegating that opening. An adapter's create support does not imply resume or branch support.
+
+Install `interactions.onRequest` before opening. The callback receives a bound
+`AgentSessionInteraction` containing the portable request, an eligibility signal, a
+terminal promise and `respond({ choiceId, signal? })`. The handler can return immediately
+after handing the capability to an owned UI, or return the promise for its work. Opening
+may return while the decision remains pending; questions can also arrive after return.
+Do not block session creation waiting for every human decision or route these decisions
+through `startTurn`, `AgentEvent`, or an execution's `resolveRequest`.
+
+For an already selected `adapter`, host-owned `openingInput` and UI-owned map, register early:
+
+```ts
+import type { AgentProviderCreateSessionInput, AgentSessionInteraction } from '@agen-ai/agent-runtime';
+
+const pending = new Map<string, AgentSessionInteraction>();
+const input: AgentProviderCreateSessionInput = {
+  ...openingInput,
+  interactions: {
+    onRequest(interaction) {
+      pending.set(interaction.request.requestId, interaction);
+    },
+  },
+};
+const session = await adapter.createSession(input);
+// Present the request target and every choice consequence before selecting a choice.
+// Answer using that retained interaction's respond({ choiceId }) capability.
+// The UI retires terminal entries and observes interaction.signal.
+```
+
+The complete public [lifecycle example](../../examples/lifecycle-interactions.ts) uses a
+consumer-owned adapter, opens with a pending decision, selects a synthetic decline and joins
+cleanup without a model turn. It needs only the core protocol/runtime dependency closure.
+For an ordinary noninteractive opening, omit `interactions` from the input. The runtime
+does not install an automatic answer policy; a provider requiring a handler must reject that
+opening. Keep authentication and interactive materialization in their existing owners.
+
+`respond` validates the choice against this exact request and allows one active response:
+
+| Receipt | Meaning |
+| --- | --- |
+| `delivered` | The provider-owned handler accepted the exact choice. The interaction becomes `answered`; this does not prove a wire write, native consumption, effect completion or persistent storage. |
+| `rejected` with `requestState: 'pending'` | Definitive refusal preserves this request's eligibility. A second response while one is active also receives pending refusal; it cannot start overlapping native delivery. |
+| `rejected` with `requestState: 'unavailable'` | The request has retired and the capability cannot answer it again. |
+| `delivery_uncertain` | Entered delivery did not establish acceptance or refusal. The session is fenced against further mutation; close it without replaying the choice. |
+
+Malformed choices and pre-aborted response inputs preserve their original errors before provider
+entry. An entered response that throws or exceeds its response deadline returns uncertainty,
+even if the provider later settles. Closing or aborting does not make an entered answer safe
+to repeat. Successful cleanup never resolves that uncertainty or authorizes replay.
+
+Terminal variants are `answered`, `rejected`, `delivery_uncertain`, `withdrawn`, `expired`,
+`session_closed`, and `failed`. `interaction.signal` controls answer eligibility and UI
+presentation; terminal settlement records the decision lifecycle. Neither means the native
+producer, entered response or callback has stopped. Close first fences admission and starts
+native shutdown, then joins the actual response, terminal and callback work. A callback that
+ignores abort remains owned. Request expiry or handler failure fails the interaction owner;
+cleanup and its original failure remain observable through the owning session.
+
+The runtime validates integer overrides once on the opening context:
+
+| Limit | Default | Allowed override |
+| --- | --- | --- |
+| `maxRetainedRequests` | 8 | 1 to 32 |
+| `maxRetainedBytes` | 524,288 bytes | 65,536 to 2,097,152 bytes |
+| `requestTimeoutMs` | 300,000 ms | 1,000 to 1,800,000 ms |
+| `responseTimeoutMs` | 30,000 ms | 1,000 to 120,000 ms |
+| `cleanupTimeoutMs` | 30,000 ms | 1,000 to 120,000 ms |
+
+Request eligibility uses the earlier provider expiry or runtime request deadline. Retained
+capacity includes terminal requests whose native terminal, response or callback has not drained.
+Unknown fields, fractional values and values outside the bounds reject the opening context.
+The opening signal applies until the session is adopted; later cancellation belongs to the
+returned session or a specific response rather than the completed opening call.
+
+If an opening fails with incomplete cleanup, use
+`isAgentProviderSessionCleanupErrorFor(error, openingInput)` with the exact input object
+passed to the adapter, such as `input` above.
+Retain that `AgentProviderSessionCleanupError` and its bound `retryCleanup()`; keep the
+registry, instance, host resources and installation references owned until it succeeds.
+A returned session with failed close likewise retains cleanup through the session and any
+returned cleanup error. An observation timeout does not detach the actual work. Retry joins
+the same owner and never opens another session or resends a choice. Serialized errors and
+request IDs cannot restore callable cleanup or response authority. Adapter authors use
+`createAgentProviderSessionCleanupError({ openingInput, providerKey, errors, retryCleanup })`
+to preserve a failed opening's exact cleanup owner.
+
 ## Session-local host tools and instructions
 
 A host can pass an optional `AgentSessionHostBinding` when creating, resuming or branching a
@@ -343,12 +450,13 @@ turn/request ordering, request resolution, steering, interruption, configuration
 close, and idempotent disposal. Unsupported operations must remain explicit discriminants and
 must not expose handlers.
 
-The coordinated SDK version is `0.4.0` and implements Agent Protocol V10.
+The coordinated source SDK version is `0.4.1`, remains unpublished and implements Agent Protocol V11.
+The published coordinated release remains `0.4.0` with V10.
 The earlier public `0.3.0` and `0.3.1` releases implemented V9 and remain historical.
 Keep installed packages in the seven-package SDK release family on the coordinated version; the
 orchestration and ACP packages remain optional. Every materialized instance requires `environment` and
 `accountQuota`; every session requires `environment`. The former standalone `integrations`
-observation port is removed. The public runtime implements Agent Protocol V10 with one current
+observation port is removed. The public runtime implements Agent Protocol V11 with one current
 adapter/session surface. Package versions remain independent of private transport and product
 persistence versions.
 

package/dist/adapterValidation.js

@@ -16,6 +16,8 @@ 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
@@ -62,6 +64,7 @@ function validateAgentProviderAdapter(capabilityInput, adapterInput) {
     );
   }
   const declaredResumption = adapter.resumption;
+  const sessionInteractions = validateSessionInteractionSupport(capabilities, adapter);
   let hostBinding;
   try {
     hostBinding = validateAgentSessionHostBindingSupport(adapter.hostBinding);
@@ -98,10 +101,19 @@ function validateAgentProviderAdapter(capabilityInput, adapterInput) {
           resumeInput.workingDirectory
         );
         const binding = parsed.binding;
+        const interactions = createSessionInteractionOwner({
+          providerKey: capabilities.providerKey,
+          sessionId: parsed.sessionId,
+          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,
@@ -109,23 +121,28 @@ function validateAgentProviderAdapter(capabilityInput, adapterInput) {
             binding,
             configuration: parsed.configuration,
             ...lease === void 0 ? {} : { hostBinding: lease.binding },
-            ...resumeInput.signal === void 0 ? {} : { signal: resumeInput.signal }
+            ...interactions === void 0 ? {} : { interactions: interactions.facade },
+            ...(interactions?.openingSignal ?? resumeInput.signal) === void 0 ? {} : { signal: interactions?.openingSignal ?? resumeInput.signal }
           }
         });
         try {
-          return validateAgentProviderSession({
+          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 }
+            { providerKey: capabilities.providerKey, input: resumeInput },
+            interactions
           );
         }
       }
@@ -158,17 +175,27 @@ function validateAgentProviderAdapter(capabilityInput, adapterInput) {
           branchInput.workingDirectory
         );
         const sourceBinding = parsed.source.binding;
+        const interactions = createSessionInteractionOwner({
+          providerKey: capabilities.providerKey,
+          sessionId: parsed.sessionId,
+          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,
@@ -177,7 +204,8 @@ function validateAgentProviderAdapter(capabilityInput, adapterInput) {
               configuration: parsed.configuration,
               onBindingCreated: observer,
               ...lease === void 0 ? {} : { hostBinding: lease.binding },
-              ...branchInput.signal === void 0 ? {} : { signal: branchInput.signal }
+              ...interactions === void 0 ? {} : { interactions: interactions.facade },
+              ...(interactions?.openingSignal ?? branchInput.signal) === void 0 ? {} : { signal: interactions?.openingSignal ?? branchInput.signal }
             }
           })
         });
@@ -255,6 +283,7 @@ function validateAgentProviderAdapter(capabilityInput, adapterInput) {
   });
   const validated = Object.freeze({
     hostBinding,
+    sessionInteractions,
     createSession: async (createInput) => withAgentSessionHostBinding({
       providerKey: capabilities.providerKey,
       binding: createInput.hostBinding,
@@ -274,16 +303,26 @@ function validateAgentProviderAdapter(capabilityInput, adapterInput) {
         const workingDirectory = parseWorkingDirectory(
           createInput.workingDirectory
         );
+        const interactions = createSessionInteractionOwner({
+          providerKey: capabilities.providerKey,
+          sessionId: parsed.sessionId,
+          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,
@@ -291,7 +330,8 @@ function validateAgentProviderAdapter(capabilityInput, adapterInput) {
               configuration: parsed.configuration,
               onBindingCreated: observer,
               ...lease === void 0 ? {} : { hostBinding: lease.binding },
-              ...createInput.signal === void 0 ? {} : { signal: createInput.signal }
+              ...interactions === void 0 ? {} : { interactions: interactions.facade },
+              ...(interactions?.openingSignal ?? createInput.signal) === void 0 ? {} : { signal: interactions?.openingSignal ?? createInput.signal }
             }
           })
         });

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,12 +1,12 @@
 import type { AgentProviderKey } from "@agen-ai/agent-protocol";
 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"];
+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 = "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;

package/dist/contractErrors.js

@@ -36,17 +36,17 @@ const AGENT_PROVIDER_CONTRACT_ERROR_CODES = [
   "host_tool_name_conflict",
   "host_tool_input_invalid",
   "host_tool_result_invalid",
-  "host_tool_capacity_exhausted"
+  "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";
   }
-  providerKey;
-  code;
 }
 class AgentProviderSessionCleanupError extends AggregateError {
   providerKey;
@@ -86,8 +86,6 @@ class AgentProviderDelegatedOperationError extends Error {
     this.operation = operation;
     this.name = "AgentProviderDelegatedOperationError";
   }
-  providerKey;
-  operation;
   providerExecution = "started";
 }
 function throwAgentProviderContractError(providerKey, code, message) {

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,7 @@ export * from "./providerDriver.js";
 export * from "./providerInstanceRegistry.js";
 export * from "./readiness.js";
 export * from "./sessions.js";
+export * from "./sessionInteractions/index.js";
 export { createAgentProviderSessionCleanupError, isAgentProviderSessionCleanupErrorFor } from "./sessionCleanup.js";
 export * from "./text.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

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

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)
     )
   );
 }

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.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/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";

package/dist/sessionInteractions/lifetime.d.ts

@@ -0,0 +1,52 @@
+import type { AgentError, AgentProviderKey, AgentSessionId } from "@agen-ai/agent-protocol";
+import type { MaybePromise } from "../foundation.js";
+import type { AgentSessionInteractionContext, AgentSessionInteractionOpeningOperation, AgentSessionInteractionSupport, AgentSessionInteractionTerminal } from "./types.js";
+import { SessionInteractionRequest } from "./request.js";
+import { type ValidatedSessionInteractionContext } from "./validation.js";
+export declare function sessionInteractionError(code: string, message: string, uncertain?: boolean): AgentError;
+export declare function waitForInteractionWork<Result>(work: Promise<Result>, timeoutMs: number): Promise<Result>;
+export declare class SessionInteractionOwner {
+    readonly providerKey: AgentProviderKey;
+    readonly sessionId: AgentSessionId;
+    readonly facade: AgentSessionInteractionContext;
+    readonly openingSignal: AbortSignal;
+    readonly limits: ValidatedSessionInteractionContext["limits"];
+    readonly failure: Promise<unknown>;
+    private readonly controller;
+    private readonly requests;
+    private readonly work;
+    private state;
+    private retainedBytes;
+    private fatal;
+    private fenceCause;
+    private resolveFailure;
+    private removeOpeningAbort;
+    private automaticClose;
+    private cleanupAttempt;
+    private cleanupDeadline;
+    private cleanupComplete;
+    private cleanupFailure;
+    private adopted;
+    private readonly context;
+    constructor(providerKey: AgentProviderKey, sessionId: AgentSessionId, context: AgentSessionInteractionContext, signal?: AbortSignal);
+    track<Result>(promise: Promise<Result>): Promise<Result>;
+    get accepting(): boolean;
+    requireUsable(): void;
+    private offer;
+    installClose(close: () => Promise<void>): void;
+    adopt(): void;
+    fence(cause: unknown, source: SessionInteractionRequest): void;
+    fail(cause: unknown): void;
+    stop(terminal?: AgentSessionInteractionTerminal): void;
+    join(): Promise<void>;
+    close(cleanup: () => MaybePromise<void>, explicit: boolean): Promise<void>;
+}
+export declare function createSessionInteractionOwner(input: Readonly<{
+    providerKey: AgentProviderKey;
+    sessionId: AgentSessionId;
+    operation: AgentSessionInteractionOpeningOperation;
+    support: AgentSessionInteractionSupport;
+    context?: AgentSessionInteractionContext;
+    signal?: AbortSignal;
+}>): SessionInteractionOwner | undefined;
+//# sourceMappingURL=lifetime.d.ts.map