@agen-ai/agent-runtime 0.4.0 → 0.4.2

package/README.md

@@ -9,9 +9,14 @@ 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.
-Upgrade consumers from `0.3.1` using the coordinated release and its migration guide.
+This unpublished source candidate implements Agent Protocol V12 at coordinated SDK version `0.4.2`,
+including tagged decision responses and exact turn request unavailability. Published `0.4.1`
+retains V11 and its qualification evidence; the earlier `0.4.0` release retains V10.
+The runtime also provides neutral session forms, plan reviews, staged native continuations and
+explicit human-wait policies. Provider mappings require their own support and qualification.
+Keep all installed SDK packages at the same version; the [0.4.2 migration
+guide](../../MIGRATING-TO-0.4.2.md) covers tagged responses, continuous request output and store
+contract changes. Generic contract proof and exact native qualification are separate boundaries.
 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 +24,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 +34,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 +79,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 +201,164 @@ 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, form or plan review outside a model turn through
+`sessionInteractions`. Support is separate from portable turn capabilities: absence means
+`{ kind: 'unsupported' }`. Supported adapters declare exact
+`{ openingOperation, requestKind }` mappings, `producerOwnership: 'exclusive'` and supported
+`humanWait` modes. Create support does not imply resume or branch support. Supplying a handler
+or policy for an unsupported mapping rejects before candidate opening.
+
+Driver authors implement `AgentProviderAdapter` with candidate opening inputs
+`AgentProviderCreateSessionInput`, `AgentProviderResumeSessionInput` and
+`AgentProviderBranchSessionInput`. The runtime installs their producer facade before entering
+that opening. Registry consumers receive `AgentValidatedProviderAdapter` in a
+`ValidatedMaterializedAgentProviderInstance`; they use `AgentCreateSessionInput`,
+`AgentResumeSessionInput` and `AgentBranchSessionInput`. These types separate provider offers
+from application handlers. Revalidating an adapter retains its original candidate ownership.
+
+Install `interactions.onRequest` before opening. The application callback receives a bound
+`AgentSessionInteraction` containing its immutable portable request, observed deadline,
+eligibility signal, terminal promise and `respond` capability. Narrow `request.kind` before
+reading workspace targets, form fields or the exact plan snapshot. Responses are tagged by
+kind and validate the offered choice and action; forms validate field answers, and plan
+responses validate plan ID and revision. Only revision accepts required nonblank feedback.
+
+For an already selected validated `adapter`, host-owned `openingInput` and UI-owned map:
+
+```ts
+import type { AgentCreateSessionInput, AgentSessionInteraction } from '@agen-ai/agent-runtime';
+
+const pending = new Map<string, AgentSessionInteraction>();
+const input: AgentCreateSessionInput = {
+  ...openingInput,
+  interactions: {
+    onRequest(interaction) {
+      pending.set(interaction.request.requestId, interaction);
+    },
+  },
+};
+const session = await adapter.createSession(input);
+// Narrow request.kind and present the actual offered choices before answering.
+// A workspace decision uses respond({ kind: 'decision', choiceId }).
+// Retire the UI entry when interaction.signal aborts; keep entered receipt ownership.
+```
+
+A handler can return after handing the capability to an owned UI, or return a promise whose
+actual work remains tracked. Opening may return while a request remains pending. Session
+requests do not become `AgentEvent` request outputs or execution `resolveRequest` calls.
+The complete public [lifecycle example](../../examples/lifecycle-interactions.ts) 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. An ordinary noninteractive opening omits
+`interactions`; no automatic answer policy is installed. A provider requiring a handler must
+reject that opening. Authentication retains its separate bounded owner.
+
+`respond` allows one unsettled response attempt per request:
+
+| Receipt | Meaning |
+| --- | --- |
+| `delivered` | The provider-owned handler accepted the exact response. This does not prove model consumption, continuation start, successful effects or persistence. |
+| `rejected` with `requestState: 'pending'` | Definitive refusal permits a later attempt only if the request remains live. A concurrent response also receives pending refusal without entering overlapping delivery. |
+| `rejected` with `requestState: 'unavailable'` | The request cannot be answered again. |
+| `delivery_uncertain` | Entered delivery did not establish acceptance or refusal. Mutation is fenced; retain cleanup and do not replay the response. |
+
+Terminals are `answered`, `rejected`, `delivery_uncertain`, `withdrawn`, `expired`,
+`session_closed` and `failed`. `answered.response` retains accepted kind, choice and action,
+plus plan ID/revision where applicable; it does not duplicate form values or revision feedback.
+`expired.source` distinguishes provider expiry from host policy. A terminal ends answer
+eligibility, independently of an entered attempt's receipt. A delivered or rejected/pending
+receipt racing withdrawal remains unchanged and cannot restore the retired request.
+
+Local parse and pre-abort errors remain precise before provider entry. Entered response
+exceptions or observation timeout return uncertainty. Successful cleanup cannot establish
+whether an uncertain answer was accepted or authorize replay. Eligibility abortion, terminal
+settlement and promise observation are not proof that producers or callbacks have joined.
+
+### Human waiting and retention
+
+Omitting `humanWait`, or selecting `{ kind: 'bounded' }`, retains the finite default.
+The only numeric human timeout is `limits.requestTimeoutMs`. An explicitly supported
+`humanWait: { kind: 'until_withdrawn_or_closed' }` installs no SDK human timer. Supplying a
+`requestTimeoutMs` property in that mode rejects before opening, even when it equals the
+default. The producer facade omits that property in unbounded mode.
+
+The descriptor's optional `expiresAt` means actual provider expiry. At validated offer time,
+the runtime fixes `interaction.deadline` to the earlier provider expiry or bounded host policy;
+provider expiry wins a tie. No provider expiry and no host timer yields `{ kind: 'no_deadline' }`.
+Presentation delay and queue residence do not restart this deadline. Expiry never fabricates an
+answer. Without independently qualified provider-local survival semantics, expiry initiates
+owned shutdown. Exact withdrawal remains distinct from expiry or general transport failure.
+
+| Limit | Default | Allowed override |
+| --- | --- | --- |
+| `maxRetainedRequests` | 8 | 1 to 32 |
+| `maxRetainedBytes` | 524,288 bytes | 65,536 to 2,097,152 bytes |
+| `requestTimeoutMs` in bounded mode | 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 |
+
+Retained descriptor bytes include each immutable plan snapshot once. Separately bounded
+response material remains charged to its single unsettled attempt. Terminal requests stay
+retained until actual native terminal, response and presentation callback work drain.
+Unknown fields, fractional values and out-of-range overrides reject. Human-wait policy does
+not remove response, preparation, cleanup, authentication, transport or capacity bounds.
+All turn and session request IDs share the fixed session-generation census of 4,096 IDs and
+1 MiB of UTF-8 identity bytes; tombstones are not evicted to grant reuse.
+
+### Native continuations
+
+A response that can start native work uses a provider `prepared` interaction. Effect-free
+`prepareResponse` receives the exact parsed response and runtime-owned attempt identity.
+It returns either `no_continuation` or `native_continuation`, with once-only `dispatch` and
+idempotent predispatch `cancel` operations. Direct interactions may only deliver responses
+that cannot start execution. A known no-work action does not reserve an execution.
+
+The application installs `nativeContinuations.onExecution` before opening. Exact support
+includes the opening operation, request kind and timing; it does not imply other combinations.
+When preparation selects a continuation, the runtime synchronously reserves the same slot
+used by caller `startTurn`, allocates a turn identity and adopts the candidate through ordinary
+output validation. It never creates a synthetic caller prompt or calls candidate `startTurn`.
+
+The host must actually call `next()` on the supplied execution's sole output iterator. Merely
+retaining the handle or acquiring an iterator is insufficient. The parked wrapper pull proves
+reader readiness without touching the candidate iterator before dispatch. A handler may await
+that first output: dispatch does not wait for callback fulfillment. After readiness, runtime
+rechecks exact request, attempt, opening, deadline and slot ownership before entering dispatch.
+Output produced during dispatch stays on that original reader.
+
+One fixed 30-second window covers preparation and reader readiness from response claim.
+Predispatch failure cancels and joins allocated source/callback ownership before releasing the
+slot. Failed cleanup retains the stopped owner and its retry handle. A started execution uses
+normal session quiescence and output cleanup. The independent continuation `outcome` reports
+`started` or `not_started`; a delivery receipt proves neither. Missing outcome cannot free a
+slot or rewrite a delivered receipt. One dispatch-anchored response deadline observes both
+receipt and outcome; uncertainty fences mutation without dropping either owner.
+
+Opening timing is explicit: `after_open_return`, `before_open_return`, or `before_binding`.
+The opening owner exists before candidate entry and transfers atomically after exact binding
+validation. Exceptional data awaiting binding is limited to 16 envelopes, 1 MiB and 30 seconds.
+It cannot invent a binding or route output by working directory. Core timing support does not
+qualify a native provider mapping; select only that provider's explicitly supported tuple.
+
+### Close and retained cleanup
+
+Close fences opening/session admission and starts native quiescence before joining preparation,
+responses, output and callbacks. A callback ignoring abort remains owned. Host binding and
+installation resources are released only after actual native cleanup and joins succeed.
+The opening signal applies until adoption; later cancellation belongs to the returned session
+or response owner.
+
+If opening fails with incomplete cleanup, call
+`isAgentProviderSessionCleanupErrorFor(error, openingInput)` with the exact original object.
+Retain the matching `AgentProviderSessionCleanupError` and its bound `retryCleanup()`; keep
+registry, instance, host resources and installation references until it succeeds. A returned
+session with failed close likewise retains cleanup through that session and its cleanup error.
+An observation timeout cannot detach actual work. Retry joins the same owner without opening
+another session or resending a response. Serialized errors and request IDs cannot restore
+callable cleanup or response authority. Adapter authors preserve failed opening ownership with
+`createAgentProviderSessionCleanupError({ openingInput, providerKey, errors, retryCleanup })`.
+
 ## Session-local host tools and instructions
 
 A host can pass an optional `AgentSessionHostBinding` when creating, resuming or branching a
@@ -343,12 +518,28 @@ 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.
+`resolutionFor(request, { signal })` accepts the existing synchronous resolution callback,
+an asynchronous callback, or `undefined` to deliberately leave a request unanswered. Its
+request-scoped signal aborts when the original output stream reports that exact request
+unavailable, when the turn completes, or when conformance cleanup begins. Honor the signal
+to dismiss pending human input; do not fabricate a denial or retry an answer after retirement.
+The runner continuously reads the same execution while callbacks and delivery receipts are
+pending. A returned answer is checked against the exact offered request before delivery.
+`request_resolution` appears in the report only after a delivered receipt;
+`request_unavailability` records consumption of a native retirement event. Opening a request
+alone proves neither. The runner checks session controls before its main turn and inspects
+turn-produced resources after terminal output while the session remains open. It then starts session
+close before joining its reader and actual callback tasks; failure also starts close before joins. Original
+failures and cleanup failures remain observable. A callback that ignores cancellation
+remains owned until its actual promise settles.
+
+The coordinated SDK release is `0.4.1` and implements Agent Protocol V11.
+The earlier `0.4.0` release retains 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.d.ts

@@ -1,4 +1,6 @@
 import { type AgentCapabilities } from "@agen-ai/agent-protocol";
-import type { AgentProviderAdapter } from "./sessions.js";
-export declare function validateAgentProviderAdapter(capabilityInput: AgentCapabilities, adapterInput: AgentProviderAdapter): AgentProviderAdapter;
+import type { AgentProviderAdapter, AgentValidatedProviderAdapter } from "./sessions.js";
+export declare function validateAgentProviderAdapter(capabilities: AgentCapabilities, candidate: AgentProviderAdapter): AgentValidatedProviderAdapter;
+export declare function validateAgentProviderAdapter(capabilities: AgentCapabilities, candidate: AgentValidatedProviderAdapter): AgentValidatedProviderAdapter;
+export declare function validateAgentProviderAdapter(capabilities: AgentCapabilities, candidate: AgentProviderAdapter | AgentValidatedProviderAdapter): AgentValidatedProviderAdapter;
 //# sourceMappingURL=adapterValidation.d.ts.map

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, validateNativeContinuationSupport } from "./sessionInteractions/validation.js";
 import {
   validateAgentProviderOperationResult,
   validateAgentProviderOutputForContext
@@ -23,9 +25,13 @@ import {
 import {
   closeRejectedAgentProviderSession,
   openIdentityCreatingAgentProviderSession,
-  validateAgentProviderSession
+  validateAgentProviderSession,
+  createAgentSessionValidationOwner
 } from "./sessionValidation.js";
 const validatedAdapters = /* @__PURE__ */ new WeakMap();
+function isCandidateAdapter(adapter) {
+  return !validatedAdapters.has(adapter);
+}
 function parseWorkingDirectory(value) {
   if (value.length < 1 || value.length > 4096 || !path.isAbsolute(value) || path.normalize(value) !== value || containsAgentControlCharacter(value)) {
     throw new TypeError(
@@ -46,7 +52,15 @@ function assertAuthenticationOutputKind(providerKey, output) {
 }
 function validateAgentProviderAdapter(capabilityInput, adapterInput) {
   const capabilities = parseAgentCapabilities(capabilityInput);
-  const adapter = validatedAdapters.get(adapterInput) ?? adapterInput;
+  if (!isCandidateAdapter(adapterInput)) return validateAgentProviderAdapter(capabilities, validatedAdapters.get(adapterInput));
+  const adapter = adapterInput;
+  const returnedOpening = (promise, opening) => {
+    void promise.then(() => {
+      queueMicrotask(() => opening.owner?.markReturned());
+    }, () => {
+    });
+    return promise;
+  };
   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,
@@ -62,6 +76,8 @@ function validateAgentProviderAdapter(capabilityInput, adapterInput) {
     );
   }
   const declaredResumption = adapter.resumption;
+  const sessionInteractions = validateSessionInteractionSupport(capabilities, adapter);
+  const nativeContinuations = validateNativeContinuationSupport(capabilities, adapter, sessionInteractions);
   let hostBinding;
   try {
     hostBinding = validateAgentSessionHostBindingSupport(adapter.hostBinding);
@@ -74,7 +90,7 @@ function validateAgentProviderAdapter(capabilityInput, adapterInput) {
   }
   const resumption = declaredResumption.kind === "unsupported" ? Object.freeze({ kind: "unsupported" }) : Object.freeze({
     kind: "supported",
-    resumeSession: async (resumeInput) => withAgentSessionHostBinding({
+    resumeSession: async (resumeInput, invocation = {}) => withAgentSessionHostBinding({
       providerKey: capabilities.providerKey,
       binding: resumeInput.hostBinding,
       openingInput: resumeInput,
@@ -98,10 +114,25 @@ function validateAgentProviderAdapter(capabilityInput, adapterInput) {
           resumeInput.workingDirectory
         );
         const binding = parsed.binding;
+        const validationOwner = createAgentSessionValidationOwner(capabilities, parsed.sessionId);
+        const interactions = createSessionInteractionOwner({
+          providerKey: capabilities.providerKey,
+          sessionId: parsed.sessionId,
+          operation: "resume",
+          support: sessionInteractions,
+          nativeSupport: nativeContinuations,
+          validationOwner,
+          ...resumeInput.nativeContinuations === void 0 ? {} : { continuations: resumeInput.nativeContinuations },
+          ...resumeInput.interactions === void 0 ? {} : { context: resumeInput.interactions },
+          ...resumeInput.signal === void 0 ? {} : { signal: resumeInput.signal }
+        });
+        if (interactions) invocation.owner = interactions;
+        interactions?.bind();
         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 +140,29 @@ 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,
+            validationOwner,
             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
           );
         }
       }
@@ -134,7 +171,7 @@ function validateAgentProviderAdapter(capabilityInput, adapterInput) {
   const declaredBranching = adapter.branching;
   const branching = declaredBranching.kind === "unsupported" ? Object.freeze({ kind: "unsupported" }) : Object.freeze({
     kind: "through_turn",
-    branchSession: async (branchInput) => withAgentSessionHostBinding({
+    branchSession: async (branchInput, invocation = {}) => withAgentSessionHostBinding({
       providerKey: capabilities.providerKey,
       binding: branchInput.hostBinding,
       openingInput: branchInput,
@@ -158,17 +195,33 @@ function validateAgentProviderAdapter(capabilityInput, adapterInput) {
           branchInput.workingDirectory
         );
         const sourceBinding = parsed.source.binding;
+        const validationOwner = createAgentSessionValidationOwner(capabilities, parsed.sessionId);
+        const interactions = createSessionInteractionOwner({
+          providerKey: capabilities.providerKey,
+          sessionId: parsed.sessionId,
+          operation: "branch",
+          support: sessionInteractions,
+          nativeSupport: nativeContinuations,
+          validationOwner,
+          ...branchInput.nativeContinuations === void 0 ? {} : { continuations: branchInput.nativeContinuations },
+          ...branchInput.interactions === void 0 ? {} : { context: branchInput.interactions },
+          ...branchInput.signal === void 0 ? {} : { signal: branchInput.signal }
+        });
+        if (interactions) invocation.owner = interactions;
         return openIdentityCreatingAgentProviderSession({
           capabilities,
+          validationOwner,
           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 +230,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 }
             }
           })
         });
@@ -253,54 +307,89 @@ function validateAgentProviderAdapter(capabilityInput, adapterInput) {
       return result;
     }
   });
-  const validated = Object.freeze({
-    hostBinding,
-    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
-        );
-        return openIdentityCreatingAgentProviderSession({
-          capabilities,
-          sessionId: parsed.sessionId,
-          observer: createInput.onBindingCreated,
+  const createSession = async (createInput, invocation = {}) => 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 validationOwner = createAgentSessionValidationOwner(capabilities, parsed.sessionId);
+      const interactions = createSessionInteractionOwner({
+        providerKey: capabilities.providerKey,
+        sessionId: parsed.sessionId,
+        operation: "create",
+        support: sessionInteractions,
+        nativeSupport: nativeContinuations,
+        validationOwner,
+        ...createInput.nativeContinuations === void 0 ? {} : { continuations: createInput.nativeContinuations },
+        ...createInput.interactions === void 0 ? {} : { context: createInput.interactions },
+        ...createInput.signal === void 0 ? {} : { signal: createInput.signal }
+      });
+      if (interactions) invocation.owner = interactions;
+      return openIdentityCreatingAgentProviderSession({
+        capabilities,
+        validationOwner,
+        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 === void 0 ? {} : { hostBindingLease: lease },
-          open: (observer) => invokeAgentSessionOpening({
-            providerKey: capabilities.providerKey,
-            openingInput: createInput,
-            lease,
-            open: (context) => adapter.createSession(context),
-            candidateInput: {
-              sessionId: parsed.sessionId,
-              workingDirectory,
-              configuration: parsed.configuration,
-              onBindingCreated: observer,
-              ...lease === void 0 ? {} : { hostBinding: lease.binding },
-              ...createInput.signal === void 0 ? {} : { signal: createInput.signal }
-            }
-          })
-        });
-      }
-    }),
+          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 }
+          }
+        })
+      });
+    }
+  });
+  const openingAdapter = Object.freeze({
+    hostBinding,
+    sessionInteractions,
+    nativeContinuations,
+    createSession,
     resumption,
     branching,
     authentication
   });
+  const validated = Object.freeze({
+    ...openingAdapter,
+    createSession: (input) => {
+      const invocation = {};
+      return returnedOpening(createSession(input, invocation), invocation);
+    },
+    resumption: resumption.kind === "unsupported" ? resumption : Object.freeze({ kind: "supported", resumeSession: (input) => {
+      const invocation = {};
+      return returnedOpening(resumption.resumeSession(input, invocation), invocation);
+    } }),
+    branching: branching.kind === "unsupported" ? branching : Object.freeze({ kind: "through_turn", branchSession: (input) => {
+      const invocation = {};
+      return returnedOpening(branching.branchSession(input, invocation), invocation);
+    } })
+  });
   validatedAdapters.set(validated, adapter);
   return validated;
 }

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", "request_identity_limit_exceeded", "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", "native_continuations_unsupported", "native_continuation_preparation_failed", "native_continuation_reader_not_ready", "native_continuation_limit_exceeded", "invalid_native_continuation"];
 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

@@ -26,6 +26,7 @@ const AGENT_PROVIDER_CONTRACT_ERROR_CODES = [
   "input_capability_mismatch",
   "invalid_turn_sequence",
   "request_resolution_mismatch",
+  "request_identity_limit_exceeded",
   "configuration_key_unsupported",
   "configuration_value_unsupported",
   "request_pending",
@@ -36,17 +37,22 @@ 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",
+  "native_continuations_unsupported",
+  "native_continuation_preparation_failed",
+  "native_continuation_reader_not_ready",
+  "native_continuation_limit_exceeded",
+  "invalid_native_continuation"
 ];
 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 +92,6 @@ class AgentProviderDelegatedOperationError extends Error {
     this.operation = operation;
     this.name = "AgentProviderDelegatedOperationError";
   }
-  providerKey;
-  operation;
   providerExecution = "started";
 }
 function throwAgentProviderContractError(providerKey, code, message) {