@agen-ai/agent-runtime 0.1.0

package/dist/sessionValidation.js

@@ -0,0 +1,767 @@
+import {
+  matchesAgentSessionBinding,
+  parseAgentRequestResolution,
+  parseAgentRequestResolutionFor,
+  parseAgentSessionBinding,
+  parseAgentSessionConfiguration,
+  parseAgentTurnId,
+  parseAgentTurnInputContent,
+  parseAgentTurnInterruptionInput,
+  parseAgentTurnRunInput
+} from "@agen-ai/agent-protocol";
+import {
+  assertAgentSessionConfigurationSupported
+} from "./configurationValidation.js";
+import {
+  AgentProviderDelegatedOperationError,
+  throwAgentProviderContractError
+} from "./contractErrors.js";
+import {
+  throwIfAgentOperationAborted
+} from "./foundation.js";
+import {
+  validateAgentProviderOperationResult,
+  validateAgentProviderOutputForContext
+} from "./outputValidation.js";
+import { validateAgentTurnSteeringResult } from "./steeringValidation.js";
+function validateSessionPorts(capabilities, session) {
+  if (typeof session.runTurn !== "function" || typeof session.resolveRequest !== "function" || typeof session.close !== "function" || session.interruption === null || typeof session.interruption !== "object" || !["supported", "unsupported"].includes(session.interruption.kind) || session.steering === null || typeof session.steering !== "object" || !["supported", "unsupported"].includes(session.steering.kind) || session.configuration === null || typeof session.configuration !== "object" || !["managed", "selectable"].includes(session.configuration.kind)) {
+    throwAgentProviderContractError(
+      capabilities.providerKey,
+      "invalid_session",
+      `Provider ${capabilities.providerKey} returned an incomplete session.`
+    );
+  }
+  if (session.interruption.kind === "supported" !== capabilities.turns.interrupt || session.steering.kind === "supported" !== (capabilities.turns.steer.kind === "supported") || session.configuration.kind !== capabilities.configuration.kind || session.interruption.kind === "supported" && typeof session.interruption.interruptTurn !== "function" || session.steering.kind === "supported" && typeof session.steering.steerTurn !== "function" || session.configuration.kind === "selectable" && typeof session.configuration.applyConfiguration !== "function") {
+    throwAgentProviderContractError(
+      capabilities.providerKey,
+      "capability_port_mismatch",
+      `Provider ${capabilities.providerKey} session ports do not match its capabilities.`
+    );
+  }
+}
+function invalidTurnSequence(providerKey, message) {
+  return throwAgentProviderContractError(
+    providerKey,
+    "invalid_turn_sequence",
+    message
+  );
+}
+function completeTurnSequence(input) {
+  if (input.pendingRequests.size > 0) {
+    invalidTurnSequence(
+      input.providerKey,
+      "Provider completed a turn while an interaction request remained pending."
+    );
+  }
+  input.state.terminal = true;
+  input.state.waiting = false;
+}
+const FINAL_DIFF_TRAILING_EVENT_TYPES = [
+  "artifact.referenced",
+  "provider.diagnostic",
+  "runtime.error",
+  "runtime.warning",
+  "turn.completed"
+];
+function observeTurnEvent(input) {
+  const { event, openedRequestIds, pendingRequests, providerKey, state } = input;
+  if (state.terminal) {
+    invalidTurnSequence(
+      providerKey,
+      "Provider emitted an event after turn completion."
+    );
+  }
+  if (event.type === "turn.started") {
+    if (state.started) {
+      invalidTurnSequence(
+        providerKey,
+        "Provider emitted turn.started more than once."
+      );
+    }
+    state.started = true;
+  } else if (!state.started) {
+    invalidTurnSequence(
+      providerKey,
+      "Provider emitted turn data before turn.started."
+    );
+  }
+  if (state.fileChangeMode === "final_diff") {
+    if (event.type === "turn.diff.updated") {
+      if (pendingRequests.size > 0) {
+        invalidTurnSequence(
+          providerKey,
+          "Provider emitted a terminal diff while an interaction request remained pending."
+        );
+      }
+      if (state.finalDiffObserved) {
+        invalidTurnSequence(
+          providerKey,
+          "Provider emitted more than one terminal diff for a turn."
+        );
+      }
+      state.finalDiffObserved = true;
+    } else if (state.finalDiffObserved && !FINAL_DIFF_TRAILING_EVENT_TYPES.includes(event.type)) {
+      invalidTurnSequence(
+        providerKey,
+        "Provider emitted turn materialization after its terminal diff."
+      );
+    }
+  }
+  if (event.type === "request.opened") {
+    if (pendingRequests.size > 0) {
+      invalidTurnSequence(
+        providerKey,
+        "Provider opened more than one pending request for a session."
+      );
+    }
+    const requestId = event.payload.request.requestId;
+    if (openedRequestIds.has(requestId)) {
+      invalidTurnSequence(
+        providerKey,
+        "Provider reused a request ID within a session."
+      );
+    }
+    openedRequestIds.add(requestId);
+    pendingRequests.set(requestId, {
+      request: event.payload.request,
+      turnId: event.turnId
+    });
+  }
+  if (event.type === "turn.state_changed") {
+    state.waiting = event.payload.state === "waiting_for_request";
+    if (state.waiting && !pendingRequests.has(event.payload.requestId)) {
+      invalidTurnSequence(
+        providerKey,
+        "Provider entered a waiting state for a request it did not open."
+      );
+    }
+  }
+  if (event.type === "turn.completed") {
+    completeTurnSequence({ providerKey, state, pendingRequests });
+  }
+}
+function assertStableTurnBoundary(input) {
+  const terminal = input.state.terminal && !input.state.waiting;
+  const waiting = !input.state.terminal && input.state.waiting && input.pendingRequests.size === 1;
+  if (terminal && input.pendingRequests.size === 0 || waiting) return;
+  invalidTurnSequence(
+    input.providerKey,
+    "Provider turn must finish with completion or exactly one pending request."
+  );
+}
+function replacePendingRequests(target, source) {
+  target.clear();
+  for (const [requestId, pending] of source) target.set(requestId, pending);
+}
+function trackActiveTurnOperation(turn) {
+  if (!turn) return null;
+  let settle;
+  const settlement = new Promise((resolve) => {
+    settle = resolve;
+  });
+  turn.inFlightOperations.add(settlement);
+  return () => {
+    turn.inFlightOperations.delete(settlement);
+    settle();
+  };
+}
+function interruptionTerminalizesTurn(input) {
+  if (["completed", "canceled"].includes(input.result.status)) {
+    return true;
+  }
+  return (input.result.outputs ?? []).some(
+    (output) => output.kind === "event" && output.event.turnId === input.turnId && output.event.type === "turn.completed"
+  );
+}
+function observeTurnOperationOutputs(input) {
+  for (const output of input.outputs ?? []) {
+    if (output.kind !== "event") continue;
+    observeTurnEvent({
+      providerKey: input.providerKey,
+      event: output.event,
+      state: input.state,
+      pendingRequests: input.pendingRequests,
+      openedRequestIds: input.openedRequestIds
+    });
+  }
+}
+function reconstructWaitingTurn(input) {
+  const targetedPendingRequests = new Map(
+    [...input.pendingRequests].filter(
+      ([, pending]) => pending.turnId === input.turnId
+    )
+  );
+  if (targetedPendingRequests.size === 0) return null;
+  return {
+    state: {
+      fileChangeMode: input.fileChangeMode,
+      started: true,
+      terminal: false,
+      waiting: true,
+      finalDiffObserved: false
+    },
+    pendingRequests: targetedPendingRequests
+  };
+}
+function clearPendingRequestsForTurn(pendingRequests, turnId) {
+  for (const [requestId, pending] of pendingRequests) {
+    if (pending.turnId === turnId) pendingRequests.delete(requestId);
+  }
+}
+function assertAgentTurnInputCapability(input) {
+  const imageParts = input.parts.filter((part) => part.type === "image");
+  if (imageParts.length === 0) return;
+  const imageCapability = input.capability.images;
+  if (imageCapability.kind === "unsupported") {
+    throwAgentProviderContractError(
+      input.providerKey,
+      "input_capability_mismatch",
+      `Provider ${input.providerKey} does not accept image input.`
+    );
+  }
+  const reject = (reason) => throwAgentProviderContractError(
+    input.providerKey,
+    "input_capability_mismatch",
+    `Provider ${input.providerKey} cannot accept this image input: ${reason}.`
+  );
+  if (imageParts.length > imageCapability.maxImages) {
+    reject("image count exceeds the declared limit");
+  }
+  if (!imageCapability.supportsImageOnly && !input.parts.some((part) => part.type === "text" && part.text.trim().length > 0)) {
+    reject("image-only input is unsupported");
+  }
+  let totalBytes = 0;
+  for (const part of imageParts) {
+    const { source } = part;
+    if (!imageCapability.sourceKinds.includes(source.type)) {
+      reject(`source kind ${source.type} is unsupported`);
+    }
+    if (!imageCapability.mediaTypes.includes(source.mediaType)) {
+      reject(`media type ${source.mediaType} is unsupported`);
+    }
+    if (source.byteSize > imageCapability.maxBytesPerImage) {
+      reject("an image exceeds the declared byte limit");
+    }
+    if (source.widthPixels > imageCapability.maxWidthPixels || source.heightPixels > imageCapability.maxHeightPixels || source.widthPixels * source.heightPixels > imageCapability.maxPixelsPerImage) {
+      reject("an image exceeds the declared dimension or pixel limit");
+    }
+    totalBytes += source.byteSize;
+  }
+  if (totalBytes > imageCapability.maxTotalBytes) {
+    reject("aggregate image bytes exceed the declared limit");
+  }
+}
+function validateAgentProviderSession(input) {
+  const { capabilities, sessionId } = input;
+  const providerKey = capabilities.providerKey;
+  if (input.candidate === null || typeof input.candidate !== "object") {
+    throwAgentProviderContractError(
+      providerKey,
+      "invalid_session",
+      "Provider returned an invalid session."
+    );
+  }
+  let binding;
+  try {
+    binding = parseAgentSessionBinding(input.candidate.binding);
+  } catch {
+    throwAgentProviderContractError(
+      providerKey,
+      "invalid_binding",
+      "Provider returned an invalid binding."
+    );
+  }
+  if (input.expectedBinding && !matchesAgentSessionBinding(binding, input.expectedBinding)) {
+    throwAgentProviderContractError(
+      providerKey,
+      "resume_binding_mismatch",
+      "Provider resumed another binding."
+    );
+  }
+  if (input.sourceBinding && matchesAgentSessionBinding(binding, input.sourceBinding)) {
+    throwAgentProviderContractError(
+      providerKey,
+      "branch_binding_reused",
+      "Provider branch reused its source binding."
+    );
+  }
+  validateSessionPorts(capabilities, input.candidate);
+  const pendingRequests = /* @__PURE__ */ new Map();
+  const openedRequestIds = /* @__PURE__ */ new Set();
+  let activeTurn = null;
+  let closePromise = null;
+  let closed = false;
+  let unusable = false;
+  const requireOpen = () => {
+    if (closed)
+      throwAgentProviderContractError(
+        providerKey,
+        "session_closed",
+        "Provider session is closed."
+      );
+  };
+  const requireUsable = () => {
+    requireOpen();
+    if (unusable) {
+      throwAgentProviderContractError(
+        providerKey,
+        "session_unusable",
+        "Provider session cannot be reused after an incomplete operation."
+      );
+    }
+  };
+  const outputContext = (turnId) => ({
+    capabilities,
+    providerKey,
+    sessionId,
+    ...turnId === void 0 ? {} : { turnId }
+  });
+  const delegateOperation = async (operation, turnId) => {
+    try {
+      return validateAgentProviderOperationResult(
+        await operation(),
+        outputContext(turnId)
+      );
+    } catch (error) {
+      unusable = true;
+      throw error;
+    }
+  };
+  const runTurn = async function* (turnInput) {
+    requireUsable();
+    throwIfAgentOperationAborted(turnInput.signal);
+    const parsedInput = parseAgentTurnRunInput({
+      turnId: turnInput.turnId,
+      interactionMode: turnInput.interactionMode,
+      parts: turnInput.parts,
+      ...turnInput.summary === void 0 ? {} : { summary: turnInput.summary },
+      ...turnInput.deadlineAt === void 0 ? {} : { deadlineAt: turnInput.deadlineAt }
+    });
+    assertAgentTurnInputCapability({
+      capability: capabilities.input,
+      parts: parsedInput.parts,
+      providerKey
+    });
+    if (!capabilities.turns.interactionModes.includes(parsedInput.interactionMode)) {
+      throwAgentProviderContractError(
+        providerKey,
+        "input_capability_mismatch",
+        `Provider ${providerKey} does not support ${parsedInput.interactionMode} turn interaction mode.`
+      );
+    }
+    if (pendingRequests.size > 0) {
+      throwAgentProviderContractError(
+        providerKey,
+        "request_pending",
+        "Provider session cannot start another turn while a request is pending."
+      );
+    }
+    if (activeTurn !== null) {
+      throwAgentProviderContractError(
+        providerKey,
+        "concurrent_turn",
+        "Provider session already has an active turn."
+      );
+    }
+    let reachedStableBoundary = false;
+    const currentTurn = {
+      turnId: parsedInput.turnId,
+      pendingRequests: /* @__PURE__ */ new Map(),
+      state: {
+        fileChangeMode: capabilities.output.fileChanges,
+        started: false,
+        terminal: false,
+        waiting: false,
+        finalDiffObserved: false
+      },
+      inFlightOperations: /* @__PURE__ */ new Set()
+    };
+    activeTurn = currentTurn;
+    try {
+      turnInput.onProviderExecutionStarted?.();
+      for await (const candidate of input.candidate.runTurn({
+        ...parsedInput,
+        ...turnInput.signal === void 0 ? {} : { signal: turnInput.signal }
+      })) {
+        const output = validateAgentProviderOutputForContext(
+          candidate,
+          outputContext(parsedInput.turnId)
+        );
+        if (output.kind === "event") {
+          observeTurnEvent({
+            providerKey,
+            event: output.event,
+            state: currentTurn.state,
+            pendingRequests: currentTurn.pendingRequests,
+            openedRequestIds
+          });
+        }
+        yield output;
+      }
+      while (currentTurn.inFlightOperations.size > 0) {
+        await Promise.all(currentTurn.inFlightOperations);
+      }
+      if (!currentTurn.state.started) {
+        invalidTurnSequence(
+          providerKey,
+          "Provider turn must emit turn.started before reaching a stable boundary."
+        );
+      }
+      assertStableTurnBoundary({
+        providerKey,
+        state: currentTurn.state,
+        pendingRequests: currentTurn.pendingRequests
+      });
+      if (currentTurn.state.waiting) {
+        replacePendingRequests(pendingRequests, currentTurn.pendingRequests);
+      }
+      reachedStableBoundary = true;
+    } finally {
+      if (!reachedStableBoundary) unusable = true;
+      if (activeTurn === currentTurn) activeTurn = null;
+    }
+  };
+  const resolveRequest = async function* (requestInput) {
+    requireUsable();
+    throwIfAgentOperationAborted(requestInput.signal);
+    const resolution = parseAgentRequestResolution(requestInput.resolution);
+    const pending = pendingRequests.get(resolution.requestId);
+    if (!pending) {
+      throwAgentProviderContractError(
+        providerKey,
+        "request_resolution_mismatch",
+        "Provider request resolution does not identify a pending request."
+      );
+    }
+    try {
+      parseAgentRequestResolutionFor(pending.request, resolution);
+    } catch {
+      throwAgentProviderContractError(
+        providerKey,
+        "request_resolution_mismatch",
+        "Provider request resolution does not match the opened request."
+      );
+    }
+    const nextPendingRequests = new Map(pendingRequests);
+    nextPendingRequests.delete(resolution.requestId);
+    if (activeTurn !== null) {
+      throwAgentProviderContractError(
+        providerKey,
+        "concurrent_turn",
+        "Provider session already has an active turn."
+      );
+    }
+    const currentTurn = {
+      turnId: pending.turnId,
+      pendingRequests: nextPendingRequests,
+      state: {
+        fileChangeMode: capabilities.output.fileChanges,
+        started: true,
+        terminal: false,
+        waiting: false,
+        finalDiffObserved: false
+      },
+      inFlightOperations: /* @__PURE__ */ new Set()
+    };
+    let reachedStableBoundary = false;
+    activeTurn = currentTurn;
+    try {
+      for await (const candidate of input.candidate.resolveRequest({
+        resolution,
+        ...requestInput.signal === void 0 ? {} : { signal: requestInput.signal }
+      })) {
+        const output = validateAgentProviderOutputForContext(
+          candidate,
+          outputContext(pending.turnId)
+        );
+        if (output.kind === "event") {
+          observeTurnEvent({
+            providerKey,
+            event: output.event,
+            state: currentTurn.state,
+            pendingRequests: currentTurn.pendingRequests,
+            openedRequestIds
+          });
+        }
+        yield output;
+      }
+      while (currentTurn.inFlightOperations.size > 0) {
+        await Promise.all(currentTurn.inFlightOperations);
+      }
+      assertStableTurnBoundary({
+        providerKey,
+        state: currentTurn.state,
+        pendingRequests: currentTurn.pendingRequests
+      });
+      replacePendingRequests(pendingRequests, currentTurn.pendingRequests);
+      reachedStableBoundary = true;
+    } finally {
+      if (!reachedStableBoundary) unusable = true;
+      if (activeTurn === currentTurn) activeTurn = null;
+    }
+  };
+  const declaredInterruption = input.candidate.interruption;
+  const interruption = declaredInterruption.kind === "unsupported" ? Object.freeze({ kind: "unsupported" }) : Object.freeze({
+    kind: "supported",
+    interruptTurn: async (interruptionInput) => {
+      requireUsable();
+      throwIfAgentOperationAborted(interruptionInput.signal);
+      const parsed = parseAgentTurnInterruptionInput({
+        turnId: interruptionInput.turnId,
+        reason: interruptionInput.reason,
+        ...interruptionInput.requestedAt === void 0 ? {} : { requestedAt: interruptionInput.requestedAt }
+      });
+      const targetedActiveTurn = activeTurn?.turnId === parsed.turnId ? activeTurn : null;
+      const targetedWaitingTurn = targetedActiveTurn === null ? reconstructWaitingTurn({
+        pendingRequests,
+        turnId: parsed.turnId,
+        fileChangeMode: capabilities.output.fileChanges
+      }) : null;
+      const targetedTurn = targetedActiveTurn ?? targetedWaitingTurn;
+      if (targetedTurn === null) {
+        throwAgentProviderContractError(
+          providerKey,
+          "active_turn_mismatch",
+          "Provider interruption does not identify an active or waiting turn."
+        );
+      }
+      const settleActiveInterruption = trackActiveTurnOperation(
+        targetedActiveTurn
+      );
+      try {
+        const result = await delegateOperation(
+          () => declaredInterruption.interruptTurn({
+            ...parsed,
+            ...interruptionInput.signal === void 0 ? {} : { signal: interruptionInput.signal }
+          }),
+          parsed.turnId
+        );
+        const terminalized = interruptionTerminalizesTurn({
+          turnId: parsed.turnId,
+          result
+        });
+        if (terminalized || result.status === "accepted") {
+          clearPendingRequestsForTurn(pendingRequests, parsed.turnId);
+          clearPendingRequestsForTurn(
+            targetedTurn.pendingRequests,
+            parsed.turnId
+          );
+          targetedTurn.state.waiting = false;
+        }
+        try {
+          observeTurnOperationOutputs({
+            providerKey,
+            outputs: result.outputs,
+            state: targetedTurn.state,
+            pendingRequests: targetedTurn.pendingRequests,
+            openedRequestIds
+          });
+          if (terminalized && !targetedTurn.state.terminal) {
+            completeTurnSequence({
+              providerKey,
+              state: targetedTurn.state,
+              pendingRequests: targetedTurn.pendingRequests
+            });
+          }
+        } catch (error) {
+          unusable = true;
+          throw error;
+        }
+        if (result.status === "accepted" && targetedWaitingTurn !== null && !terminalized) {
+          unusable = true;
+        }
+        return result;
+      } finally {
+        settleActiveInterruption?.();
+      }
+    }
+  });
+  const declaredSteering = input.candidate.steering;
+  const steering = declaredSteering.kind === "unsupported" ? Object.freeze({ kind: "unsupported" }) : Object.freeze({
+    kind: "supported",
+    steerTurn: async (steeringInput) => {
+      requireUsable();
+      throwIfAgentOperationAborted(steeringInput.signal);
+      const turnId = parseAgentTurnId(steeringInput.turnId);
+      if (activeTurn?.turnId !== turnId || activeTurn.state.terminal || activeTurn.state.waiting) {
+        throwAgentProviderContractError(
+          providerKey,
+          "active_turn_mismatch",
+          "Provider steering does not identify a running turn."
+        );
+      }
+      const content = parseAgentTurnInputContent({
+        parts: steeringInput.parts,
+        ...steeringInput.summary === void 0 ? {} : { summary: steeringInput.summary }
+      });
+      assertAgentTurnInputCapability({
+        capability: capabilities.turns.steer.kind === "supported" ? capabilities.turns.steer.input : capabilities.input,
+        parts: content.parts,
+        providerKey
+      });
+      const targetedActiveTurn = activeTurn;
+      const settleSteering = trackActiveTurnOperation(targetedActiveTurn);
+      try {
+        try {
+          return validateAgentTurnSteeringResult(
+            await declaredSteering.steerTurn({
+              turnId,
+              ...content,
+              ...steeringInput.signal === void 0 ? {} : { signal: steeringInput.signal }
+            }),
+            providerKey
+          );
+        } catch (error) {
+          unusable = true;
+          throw new AgentProviderDelegatedOperationError(
+            providerKey,
+            "steer_turn",
+            error
+          );
+        }
+      } finally {
+        settleSteering?.();
+      }
+    }
+  });
+  const declaredConfiguration = input.candidate.configuration;
+  const configuration = declaredConfiguration.kind === "managed" ? Object.freeze({ kind: "managed" }) : Object.freeze({
+    kind: "selectable",
+    applyConfiguration: async (configurationInput) => {
+      requireUsable();
+      throwIfAgentOperationAborted(configurationInput.signal);
+      const configuration2 = parseAgentSessionConfiguration(
+        configurationInput.configuration
+      );
+      assertAgentSessionConfigurationSupported(
+        capabilities,
+        configuration2
+      );
+      return delegateOperation(
+        () => declaredConfiguration.applyConfiguration({
+          configuration: configuration2,
+          ...configurationInput.signal === void 0 ? {} : { signal: configurationInput.signal }
+        })
+      );
+    }
+  });
+  const close = (closeInput) => {
+    if (closed) return Promise.resolve();
+    if (closePromise) return closePromise;
+    throwIfAgentOperationAborted(closeInput.signal);
+    if (closeInput.reason !== void 0 && ![
+      "idle",
+      "shutdown",
+      "replaced",
+      "contract_rejected",
+      "error",
+      "other"
+    ].includes(closeInput.reason)) {
+      throw new TypeError("Provider session close reason is unsupported.");
+    }
+    unusable = true;
+    closePromise = Promise.resolve().then(() => input.candidate.close(closeInput)).then(() => {
+      closed = true;
+    }).finally(() => {
+      closePromise = null;
+    });
+    return closePromise;
+  };
+  return Object.freeze({
+    binding,
+    runTurn,
+    resolveRequest,
+    interruption,
+    steering,
+    configuration,
+    close
+  });
+}
+async function closeRejectedAgentProviderSession(session, error) {
+  if (!session || typeof session.close !== "function") throw error;
+  try {
+    await session.close({ reason: "contract_rejected" });
+  } catch (cleanupError) {
+    throw new AggregateError(
+      [error, cleanupError],
+      "Provider returned an invalid session and cleanup failed."
+    );
+  }
+  throw error;
+}
+function bindingTracker(input) {
+  let observed = null;
+  return {
+    observe(candidate) {
+      if (observed) {
+        throwAgentProviderContractError(
+          input.providerKey,
+          "binding_callback_repeated",
+          "Provider reported session binding creation more than once."
+        );
+      }
+      let binding;
+      try {
+        binding = parseAgentSessionBinding(candidate);
+      } catch {
+        throwAgentProviderContractError(
+          input.providerKey,
+          "invalid_binding",
+          "Provider reported an invalid binding."
+        );
+      }
+      if (input.sourceBinding && matchesAgentSessionBinding(binding, input.sourceBinding)) {
+        throwAgentProviderContractError(
+          input.providerKey,
+          "branch_binding_reused",
+          "Provider branch reused its source binding."
+        );
+      }
+      input.observer(binding);
+      observed = binding;
+    },
+    requireMatch(binding) {
+      if (!observed) {
+        throwAgentProviderContractError(
+          input.providerKey,
+          "binding_callback_missing",
+          "Provider did not report binding creation before returning a session."
+        );
+      }
+      if (!matchesAgentSessionBinding(observed, binding)) {
+        throwAgentProviderContractError(
+          input.providerKey,
+          "binding_callback_mismatch",
+          "Provider returned a different binding than it reported."
+        );
+      }
+    }
+  };
+}
+async function openIdentityCreatingAgentProviderSession(input) {
+  const tracker = bindingTracker({
+    providerKey: input.capabilities.providerKey,
+    observer: input.observer,
+    ...input.sourceBinding === void 0 ? {} : { sourceBinding: input.sourceBinding }
+  });
+  let candidate = null;
+  try {
+    candidate = await input.open(tracker.observe);
+    const session = validateAgentProviderSession({
+      capabilities: input.capabilities,
+      sessionId: input.sessionId,
+      candidate,
+      ...input.sourceBinding === void 0 ? {} : { sourceBinding: input.sourceBinding }
+    });
+    tracker.requireMatch(session.binding);
+    return session;
+  } catch (error) {
+    return closeRejectedAgentProviderSession(candidate, error);
+  }
+}
+export {
+  closeRejectedAgentProviderSession,
+  openIdentityCreatingAgentProviderSession,
+  validateAgentProviderSession
+};