@agen-ai/agent-runtime 0.3.1 → 0.4.0

package/README.md

@@ -8,8 +8,10 @@ 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,
-leases, or storage policy. A host must authorize and select an instance before calling this SPI.
-This source package implements Agent Protocol V9 as part of the coordinated SDK `0.3.1` contract.
+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.
 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.
 
@@ -28,7 +30,8 @@ is intentionally one coordinated tuple rather than a deployable mixed-version gr
 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.
-5. Consume each `runTurn` or `resolveRequest` output stream incrementally. Neutral `AgentEvent`
+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
    carry separately bounded, non-truncated provider request context for continuation; lifecycle,
    authentication, artifact, and standalone diagnostic evidence remain separate output variants.
@@ -77,26 +80,73 @@ through an unknown-status update, regress it from in-progress to pending, or rev
 terminal event or status. An `item.completed` event must carry `completed`, `failed`, or `canceled`
 status. Completion-only snapshots remain valid when no earlier lifecycle event was observed.
 
-The host should serialize mutating operations for a given session. Separate session objects may
-run concurrently, so provider implementations must isolate their conversation-local state.
+A session reserves one turn execution synchronously at `startTurn`. Native execution stays lazy until
+its first output pull; an unused handle has no provider effects. Separate sessions run concurrently.
+The execution's `outputs` has exactly one consumer and one outstanding pull. Its ownership continues
+across human requests until native terminal output, entered response/control settlement, and cleanup.
 
 Materialization-scoped context usage remains monotonic only within one native provider process. A
 provider that replaces that process emits a `process.started` lifecycle output as the explicit
 boundary before reporting usage from the replacement. Validation then clears only the
 `materialization` occupancy, cumulative counters, and compaction allowance; logical `session`
 measurements remain continuous.
-`runTurn` and `resolveRequest` both preserve consumer backpressure: the provider does not resume
-until the consumer requests the next output. Each stream must end at a completed turn or exactly
-one newly pending request. If a consumer abandons a stream, a provider throws, or either stream
-ends before that stable boundary, the validated session becomes unusable and must be closed rather
-than retried. The validated `runTurn` input may observe `onProviderExecutionStarted`; validation
-invokes it exactly at candidate-port delegation, after runtime prechecks pass, and never forwards it
-to the candidate adapter. A delegated mutating operation that throws or returns an invalid result
-has the same effect. Pre-aborted operations fail with `AbortError`; close and disposal must be safe
-to call repeatedly. An accepted interruption of an already-waiting turn does not prove that the
-turn terminalized; unless the result also carries a terminal event, the validated session becomes
-unusable and must be closed and rematerialized. A close failure makes the session unusable while
-leaving close itself retryable.
+`startTurn(input)` returns `{ turnId, outputs, resolveRequest }`. `outputs` preserves per-output
+backpressure and stays open during `waiting_for_request`; the consumer can call
+`execution.resolveRequest({ resolution })` as soon as it receives `request.opened`, before its next
+pull. A later queued waiting observation cannot revive an already answered request. No response
+creates or acquires another output stream.
+
+`resolveRequest` returns one of these delivery receipts:
+
+- `{ status: "delivered" }`: the provider-owned handler accepted the exact canonical answer or step.
+  This includes a mapped form-intent step whose later field answer is still pending. It does not
+  establish a universal transport write, model consumption, effect completion, or turn success.
+- `{ status: "rejected", requestState: "pending" | "unavailable", error }`: the provider definitively
+  refused this answer. Only `pending` preserves that exact callback's answerability; `unavailable`
+  retires it. Neither value terminalizes the original output owner.
+- `{ status: "delivery_uncertain", error }`: native delivery started without definitive acceptance
+  or refusal. Further mutation and replay are forbidden; the original output/cleanup owner remains.
+
+Local parsing, request correlation, expiry, and pre-abort failures reject with their precise original
+errors before candidate entry. Validation atomically claims an answer before invoking the optional
+synchronous `onProviderExecutionStarted` observer and then the candidate. The runtime strips this
+observer from candidate input. A throwing observer prevents native entry and preserves the request
+only while it remains answerable. An unexpected candidate response exception carries
+`AgentProviderDelegatedOperationError` with `operation: "resolve_request"` and started-execution evidence;
+it also forbids further mutation. Concurrent duplicate answers cannot enter the provider twice.
+
+The turn input has the same synchronous start observer at its lazy candidate-entry boundary, after
+prechecks pass. Abort or iterator return before the first pull releases the reservation without
+poisoning the session. An aborted old handle rejects on a later pull. Abandoning an entered output
+consumer stops admission and closes its native owner; an incomplete stream makes the session unusable.
+Interruption remains a session control: dispatch acceptance leaves the original stream open to
+observe actual native cancellation completion. Its `AgentProviderTurnInterruptionResult` carries only
+status and optional error; interruption cannot return turn output. A reserved turn rejects interruption
+with `active_turn_mismatch`, including after iterator acquisition; the first pull must enter the provider.
+Abort or return cancels a reservation locally. Admitted interruption suspends exact request admission;
+definitive failed interruptions restore only the unchanged live callback after every overlapping
+interruption fails. A concurrent response refusal with `requestState: "pending"` retains that callback
+through suspension; an accepted interruption withdraws it regardless of response completion order.
+
+Close first stops admission, signals cancellation, and initiates native quiescence; it then joins
+entered output/response work and drains host callbacks before releasing resources. Native close is
+initiated before joining acknowledgments that depend on it. A failed close keeps the stopped owner
+and host binding retained while close remains retryable. Successful close and disposal are idempotent.
+
+Ordinary answers past a request's `expiresAt` fail locally. A canonical `canceled` resolution still
+checks the live handler's availability; expiry alone cannot establish delivery. Terminal observation
+fences new answers even while an entered response is settling, and waiting observations cannot
+reopen an older request. A host must cancel human decisions when their execution ends and join
+those tasks during cleanup. Keep the session or exact opening-cleanup receipt if cleanup fails;
+disposing its registry or host resources before quiescence would lose the retained owner.
+
+`runtime.retrying` reports a retry already owned by the provider on the active turn. It preserves
+turn ownership, pending requests, and per-output backpressure; it neither starts another execution
+nor completes the turn. It is rejected before `turn.started`, after `turn.completed`, after a
+`final_diff` terminal materialization, and from session-operation observations. The event's neutral
+failure category and recovery hint describe the observed condition. A recovery hint never authorizes
+replaying work or changes an uncertain execution outcome. Contract failures, delegated-operation
+started evidence, and retained cleanup responsibilities remain separate from those failure values.
 
 When context usage is advertised, the validated session enforces the declared measurement scopes
 and cumulative fields across turns. Identical consecutive samples and decreasing cumulative
@@ -104,13 +154,19 @@ counters are rejected. Occupancy may decrease only after a completed advertised
 the next accepted sample consumes that allowance. Context output remains subject to the same
 per-output backpressure and terminal ordering as every other provider event.
 
-When `capabilities.turns.steer` is true, the session exposes `steering.steerTurn`. Steering accepts
+When `capabilities.turns.steer.kind` is `supported`, the session exposes `steering.steerTurn`. Steering accepts
 the existing turn ID plus the same canonical `parts` and optional `summary` used to start a turn.
-It does not create or own an output stream: model output continues on the original `runTurn`
-iterator. The receipt is exactly `delivered`, `rejected` with a bounded neutral error, or
+It requires provider entry on the first output pull; a reserved or merely acquired execution rejects
+steering with `active_turn_mismatch` without calling the provider.
+It does not create or own an output stream: model output continues on the original execution's
+`outputs` iterator. The receipt is exactly `delivered`, `rejected` with a bounded neutral error, or
 `delivery_uncertain` with a bounded neutral error. A provider must use uncertainty when delivery
 may have started but its authoritative acknowledgement was lost; callers cannot safely replay that
-result. The validated runtime preserves pre-delegation validation and abort errors unchanged, while
+result. A returned `delivery_uncertain` makes the validated session unusable for further mutation.
+Keep its original output reader owned while it drains toward terminality; a pending request does not
+end that stream or restore mutation authority. Close the unusable session to quiesce work that cannot
+finish without another response, then rematerialize before further work. The validated runtime preserves pre-delegation
+validation and abort errors unchanged, while
 provider-delegated steering failures throw `AgentProviderDelegatedOperationError` with the original
 cause and explicit started-execution evidence so a host can retire the unusable session. Platform
 scheduling and provider-native queue modes are intentionally outside this SPI.
@@ -128,6 +184,73 @@ 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-local host tools and instructions
+
+A host can pass an optional `AgentSessionHostBinding` when creating, resuming or branching a
+session. The binding contains tool definitions, an invocation callback, optional instructions and
+an idempotent `release` callback. Its callbacks close over host authorization; model arguments do
+not supply that authority. This is an additive runtime SPI. It does not enable managed delegation
+or change native collaboration by itself.
+
+The optional `@agen-ai/agent-orchestration` package sits above this SPI. It owns managed target policy,
+scoped tools and generated delegation guidance; the runtime has no dependency on that package or
+its explicit MCP transport. A parent's end-turn boundary leaves its session binding alive and does
+not cancel independently owned children. AgenAI Workspaces preferences and Hostd production
+integration remain separate product work.
+
+An adapter declares `hostBinding` support, its `callback` or `mcp` transport, and the instruction
+placements it can materialize. Missing support means unsupported. `system` and `developer`
+placements require the corresponding trusted native channels; `tool_context` means tool/server
+guidance. The runtime rejects unsupported requests before native session creation. Adapter authors
+must reject collisions with their native tools and actually install the requested binding.
+
+Tools use a bounded, closed JSON Schema 2020-12 subset: objects with declared properties and no
+additional properties, bounded arrays and strings, finite numbers, safe integers, booleans and
+null. Root schemas declare the dialect. References, remote loading, regular expressions, coercion
+and executable validation are unsupported. A binding allows up to 32 tools, 64 KiB of definition
+data, 32 KiB argument/result envelopes and 16 concurrent callbacks. Runtime validation precedes
+callback entry and validates returned results; callback exceptions become sanitized tool errors.
+
+Every opening needs a fresh binding object, including resume and branch. The validated opening
+claims a minimally valid binding before other opening checks. After that claim, opening failures
+own cleanup; malformed minimal bindings remain caller-owned and a duplicate claim cannot release
+the original session's binding. `validateAgentSessionHostBinding` validates metadata without claiming it. Explicit transport
+adapters can reuse `validateAgentHostToolInvocation({ binding, invocation })` against that validated
+metadata and `validateAgentHostToolResult(value)` without duplicating the bounded schema interpreter.
+These pure validators do not invoke callbacks, claim leases or provide lifecycle ownership.
+
+If a provider opening fails before returning a session and native resources are still pending,
+throw `createAgentProviderSessionCleanupError({ providerKey, openingInput, errors, retryCleanup })`.
+`openingInput` must be the exact context object received by the create/resume/branch port. The
+validated adapter adopts only that exact identity and provider key, stops new host callbacks, and
+retains the original binding. Explicit cleanup retry first quiesces provider resources and then
+releases the binding; propagation does not add another native cleanup attempt. Successful native
+cleanup is retained when only host release needs retry. A plain or foreign cleanup error cannot
+claim the current opening. Callers can use `isAgentProviderSessionCleanupErrorFor(error, input)`
+against their original opening object to identify the retained responsibility.
+
+Closing stops new invocations and aborts active callback signals, then joins provider cleanup and
+callback settlement before releasing the host binding. Ending a turn does not release it. Providers
+must quiesce their output/control producers before their close succeeds and clean up partial native
+resources before throwing an opening error without a session. Preserve callback method receivers.
+Hosts must close their sessions before disposing the instance or registry. Registry disposal retains
+its existing instance ownership and does not inventory or close caller-owned session bindings.
+
+Cleanup failure leaves authority closed and cleanup retryable. An opened session retries through
+`session.close`. If opening fails and cleanup also fails, catch
+`AgentProviderSessionCleanupError` and check
+`isAgentProviderSessionCleanupErrorFor(error, originalOpeningInput)` before assigning its retained
+handle to an opening. Use a distinct input object for each opening and preserve the exact object
+passed to create, resume or branch; copied inputs
+and constructed errors do not match the runtime's private ownership evidence. This also covers
+invalid candidates without host tools. `AgentProviderHostBindingCleanupError` remains the compatible
+subclass for failures involving a claimed host binding. A provider can propagate another opening's
+error, so `instanceof` alone does not establish ownership. Call the matching error's single-flight
+`retryCleanup()` to finish retained cleanup. It closes the exact rejected session before releasing
+the binding; a completed close is not repeated when only host release failed. Keep this error and
+its diagnostic causes on the trusted host boundary. Never serialize its handle or raw diagnostics
+into a model tool result.
+
 ## Minimal driver
 
 ```ts
@@ -178,6 +301,19 @@ The runtime distinguishes programmer/contract failures from provider failures:
 Provider-native exceptions should be normalized or safely wrapped at the provider boundary. Do
 not attach credentials, raw prompts, product identities, or unbounded output to public errors.
 
+Use `AgentError.category`, `code` and `recovery` to describe an expected operational condition.
+They do not replace `AgentProviderContractError`, delegated-operation start evidence, or cleanup
+exceptions. A `runtime.error` observation is not a terminal event; `runtime.retrying` keeps the same
+turn active. Render a definitive failed turn from its `turn.completed` result instead of counting
+each error observation as another failure. A transient classification or a quota reset never proves
+that prior tool effects can be repeated.
+
+Cancellation must retain the current stream and resource owners until native settlement and callback
+quiescence are established. An accepted interruption acknowledges dispatch; it does not establish
+cancellation completion. If the outcome remains unknown, preserve that uncertainty, close the unusable
+session and retain any failed cleanup handle for explicit retry. Successful cleanup does not settle
+the uncertain operation or authorize resending it.
+
 ## Scoped environment observation
 
 `MaterializedAgentProviderInstance.environment` discovers a caller-selected workspace and
@@ -207,11 +343,12 @@ 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 for this source is `0.3.1`, and the source implements Agent Protocol
-V9. The earlier public `0.3.0` release implemented the same protocol and remains historical.
-Upgrade all three SDK packages together. Every materialized instance requires `environment` and
+The coordinated SDK version is `0.4.0` and implements Agent Protocol 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 V9 with one current
+observation port is removed. The public runtime implements Agent Protocol V10 with one current
 adapter/session surface. Package versions remain independent of private transport and product
 persistence versions.
 
@@ -222,3 +359,17 @@ From the public repository root, run `pnpm check`.
 It installs tarballs into a temporary project outside the workspace, typechecks every documented
 entrypoint, runs the fake provider and parser flow, and removes the temporary directory. It never
 publishes or accesses release credentials.
+
+The public repository also contains `examples/delegation`: a shared host composition with direct
+and credentialless ACP workflows plus a separately qualified SQLite/inbox CLI. From that root,
+`pnpm examples:delegation` exercises real steering, queued resume, cancellation and live approval;
+`pnpm examples:delegation:acp` invokes scoped MCP tools and demonstrates a child surviving its
+parent's end-turn boundary. The installed-tarball consumer runs the same source. Synthetic evidence
+does not certify native agents or authorize replay of an uncertain turn.
+
+For the smallest runnable lifecycle example, use
+[`examples/live-request-output.ts`](../../examples/live-request-output.ts) in the public repository
+with `pnpm examples:live-request-output`. It observes unrelated output before answering an exact
+request, with one reader and joined cleanup. The public
+[migration guide](../../MIGRATING-TO-0.4.md#continuous-turn-output-and-independent-answers) shows the
+published-`0.3.1` before-example and an independent human-handler pattern for `0.4.0`.

package/dist/adapterValidation.d.ts

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

package/dist/adapterValidation.js

@@ -13,6 +13,9 @@ 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 {
   validateAgentProviderOperationResult,
   validateAgentProviderOutputForContext
@@ -22,6 +25,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 +44,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 +62,127 @@ function validateAgentProviderAdapter(capabilityInput, adapter) {
     );
   }
   const declaredResumption = adapter.resumption;
+  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,
-          sessionId: parsed.sessionId,
-          candidate,
-          expectedBinding: binding
+          parsed.configuration
+        );
+        const workingDirectory = parseWorkingDirectory(
+          resumeInput.workingDirectory
+        );
+        const binding = parsed.binding;
+        const candidate = await invokeAgentSessionOpening({
+          providerKey: capabilities.providerKey,
+          openingInput: resumeInput,
+          lease,
+          open: (context) => declaredResumption.resumeSession(context),
+          candidateInput: {
+            sessionId: parsed.sessionId,
+            workingDirectory,
+            binding,
+            configuration: parsed.configuration,
+            ...lease === void 0 ? {} : { hostBinding: lease.binding },
+            ...resumeInput.signal === void 0 ? {} : { signal: resumeInput.signal }
+          }
         });
-      } catch (error) {
-        return closeRejectedAgentProviderSession(candidate, error);
+        try {
+          return validateAgentProviderSession({
+            capabilities,
+            sessionId: parsed.sessionId,
+            candidate,
+            expectedBinding: binding,
+            ...lease === void 0 ? {} : { hostBindingLease: lease }
+          });
+        } catch (error) {
+          return closeRejectedAgentProviderSession(
+            candidate,
+            error,
+            lease === void 0 ? void 0 : { providerKey: capabilities.providerKey, lease },
+            { providerKey: capabilities.providerKey, input: resumeInput }
+          );
+        }
       }
-    }
+    })
   });
   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;
+        return openIdentityCreatingAgentProviderSession({
+          capabilities,
           sessionId: parsed.sessionId,
-          workingDirectory,
-          source: parsed.source,
-          configuration: parsed.configuration,
-          onBindingCreated: observer,
-          ...branchInput.signal === void 0 ? {} : { signal: branchInput.signal }
-        })
-      });
-    }
+          observer: branchInput.onBindingCreated,
+          sourceBinding,
+          openingInput: branchInput,
+          ...lease === void 0 ? {} : { hostBindingLease: lease },
+          open: (observer) => invokeAgentSessionOpening({
+            providerKey: capabilities.providerKey,
+            openingInput: branchInput,
+            lease,
+            open: (context) => declaredBranching.branchSession(context),
+            candidateInput: {
+              sessionId: parsed.sessionId,
+              workingDirectory,
+              source: parsed.source,
+              configuration: parsed.configuration,
+              onBindingCreated: observer,
+              ...lease === void 0 ? {} : { hostBinding: lease.binding },
+              ...branchInput.signal === void 0 ? {} : { signal: branchInput.signal }
+            }
+          })
+        });
+      }
+    })
   });
   const declaredAuthentication = adapter.authentication;
   const authenticationFlows = capabilities.authentication.kind === "supported" ? capabilities.authentication.flows : [];
@@ -204,38 +253,56 @@ 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,
+    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,
-          workingDirectory,
-          configuration: parsed.configuration,
-          onBindingCreated: observer,
-          ...createInput.signal === void 0 ? {} : { signal: createInput.signal }
-        })
-      });
-    },
+          observer: createInput.onBindingCreated,
+          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 }
+            }
+          })
+        });
+      }
+    }),
     resumption,
     branching,
     authentication
   });
+  validatedAdapters.set(validated, adapter);
+  return validated;
 }
 export {
   validateAgentProviderAdapter

package/dist/contractErrors.d.ts

@@ -1,12 +1,25 @@
 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"];
 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);
 }
+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;
     readonly operation: AgentProviderDelegatedOperation;