@agen-ai/agent-runtime 0.2.1 → 0.2.3

package/dist/sessionValidation.js

@@ -1,17 +1,33 @@
 import {
+  AGENT_COLLABORATION_GRAPH_LIMITS,
   matchesAgentSessionBinding,
+  parseAgentCollaborationControlInput,
+  parseAgentCollaborationSpawnInput,
+  parseAgentConfigurationSelectionFor,
+  parseAgentGeneratedResourceId,
+  parseAgentOperationInvocation,
+  parseAgentOperationInvocationFor,
   parseAgentRequestResolution,
   parseAgentRequestResolutionFor,
   parseAgentSessionBinding,
-  parseAgentSessionConfiguration,
   parseAgentTurnId,
   parseAgentTurnInputContent,
   parseAgentTurnInterruptionInput,
   parseAgentTurnRunInput
 } from "@agen-ai/agent-protocol";
 import {
-  assertAgentSessionConfigurationSupported
-} from "./configurationValidation.js";
+  createAgentArtifactCandidate
+} from "./artifacts.js";
+import {
+  validateAgentCollaborationNodeForCapabilities,
+  validateAgentConfigurationCatalogForCapabilities,
+  validateAgentGeneratedResourceForCapabilities,
+  validateAgentIntegrationCatalogForCapabilities,
+  validateAgentManagedContentCatalogForCapabilities,
+  validateAgentOperationCatalogForCapabilities,
+  validateAgentOperationResultForInvocation,
+  validateAgentOperationResultTransition
+} from "./interactionValidation.js";
 import {
   AgentProviderDelegatedOperationError,
   throwAgentProviderContractError
@@ -24,15 +40,59 @@ import {
   validateAgentProviderOutputForContext
 } from "./outputValidation.js";
 import { validateAgentTurnSteeringResult } from "./steeringValidation.js";
+function hasExactOwnKeys(candidate, expectedKeys) {
+  const ownKeys = Reflect.ownKeys(candidate);
+  if (ownKeys.some((key) => typeof key !== "string")) return false;
+  const actualKeys = ownKeys.sort();
+  const canonicalExpectedKeys = [...expectedKeys].sort();
+  return actualKeys.length === canonicalExpectedKeys.length && actualKeys.every((key, index) => key === canonicalExpectedKeys[index]);
+}
 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)) {
+  if (!hasExactOwnKeys(session, [
+    "binding",
+    "runTurn",
+    "resolveRequest",
+    "interruption",
+    "steering",
+    "configuration",
+    "operations",
+    "managedContent",
+    "integrations",
+    "collaboration",
+    "generatedResources",
+    "close"
+  ]) || 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) || session.operations === null || typeof session.operations !== "object" || !["supported", "unsupported"].includes(session.operations.kind) || session.managedContent === null || typeof session.managedContent !== "object" || !["supported", "unsupported"].includes(session.managedContent.kind) || session.integrations === null || typeof session.integrations !== "object" || !["supported", "unsupported"].includes(session.integrations.kind) || session.collaboration === null || typeof session.collaboration !== "object" || !["supported", "unsupported"].includes(session.collaboration.kind) || session.generatedResources === null || typeof session.generatedResources !== "object" || !["supported", "unsupported"].includes(session.generatedResources.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") {
+  if (!hasExactOwnKeys(
+    session.interruption,
+    session.interruption.kind === "supported" ? ["kind", "interruptTurn"] : ["kind"]
+  ) || !hasExactOwnKeys(
+    session.steering,
+    session.steering.kind === "supported" ? ["kind", "steerTurn"] : ["kind"]
+  ) || !hasExactOwnKeys(
+    session.configuration,
+    session.configuration.kind === "selectable" ? ["kind", "listConfiguration", "applyConfigurationSelection"] : ["kind"]
+  ) || !hasExactOwnKeys(
+    session.operations,
+    session.operations.kind === "supported" ? ["kind", "listOperations", "invokeOperation"] : ["kind"]
+  ) || !hasExactOwnKeys(
+    session.managedContent,
+    session.managedContent.kind === "supported" ? ["kind", "listManagedContent"] : ["kind"]
+  ) || !hasExactOwnKeys(
+    session.integrations,
+    session.integrations.kind === "supported" ? ["kind", "observeIntegrations"] : ["kind"]
+  ) || !hasExactOwnKeys(
+    session.collaboration,
+    session.collaboration.kind === "supported" ? ["kind", "spawnCollaboration", "controlCollaboration"] : ["kind"]
+  ) || !hasExactOwnKeys(
+    session.generatedResources,
+    session.generatedResources.kind === "supported" ? ["kind", "getGeneratedResource"] : ["kind"]
+  ) || 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.listConfiguration !== "function" || typeof session.configuration.applyConfigurationSelection !== "function") || session.operations.kind === "supported" !== (capabilities.operations.kind === "supported") || session.operations.kind === "supported" && (typeof session.operations.listOperations !== "function" || typeof session.operations.invokeOperation !== "function") || session.managedContent.kind === "supported" !== (capabilities.managedContent.kind === "supported") || session.managedContent.kind === "supported" && typeof session.managedContent.listManagedContent !== "function" || session.integrations.kind === "supported" !== (capabilities.integrations.kind === "supported") || session.integrations.kind === "supported" && typeof session.integrations.observeIntegrations !== "function" || session.collaboration.kind === "supported" !== (capabilities.collaboration.kind === "supported") || session.collaboration.kind === "supported" && (typeof session.collaboration.spawnCollaboration !== "function" || typeof session.collaboration.controlCollaboration !== "function") || session.generatedResources.kind === "supported" !== (capabilities.generatedResources.kind === "supported") || session.generatedResources.kind === "supported" && typeof session.generatedResources.getGeneratedResource !== "function") {
     throwAgentProviderContractError(
       capabilities.providerKey,
       "capability_port_mismatch",
@@ -40,6 +100,58 @@ function validateSessionPorts(capabilities, session) {
     );
   }
 }
+const TERMINAL_COLLABORATION_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "canceled"
+]);
+function evaluateCollaborationGraphAdmission(input) {
+  const existing = input.nodes.get(input.candidate.collaborationId);
+  if (existing !== void 0) {
+    const parent2 = existing.parentCollaborationId === void 0 ? void 0 : input.nodes.get(existing.parentCollaborationId);
+    return parent2 === void 0 ? Object.freeze({ kind: "admitted" }) : Object.freeze({ kind: "admitted", parent: parent2 });
+  }
+  const reservation = input.reservations.get(input.candidate.collaborationId);
+  if (reservation !== void 0 && reservation.parentCollaborationId !== input.candidate.parentCollaborationId) {
+    return Object.freeze({ kind: "conflict" });
+  }
+  const parent = input.candidate.parentCollaborationId === void 0 ? void 0 : input.nodes.get(input.candidate.parentCollaborationId);
+  if (input.candidate.parentCollaborationId === void 0 && input.candidate.rootCollaborationId !== input.candidate.collaborationId || input.candidate.parentCollaborationId !== void 0 && (parent === void 0 || input.candidate.rootCollaborationId !== parent.rootCollaborationId || TERMINAL_COLLABORATION_STATUSES.has(parent.status) || parent.closedAt !== void 0)) {
+    return Object.freeze({ kind: "conflict" });
+  }
+  let depth = 1;
+  const visitedIds = /* @__PURE__ */ new Set([input.candidate.collaborationId]);
+  for (let ancestor = parent; ancestor !== void 0; ) {
+    if (visitedIds.has(ancestor.collaborationId)) {
+      return Object.freeze({ kind: "conflict" });
+    }
+    visitedIds.add(ancestor.collaborationId);
+    depth += 1;
+    if (ancestor.parentCollaborationId === void 0) break;
+    ancestor = input.nodes.get(ancestor.parentCollaborationId);
+    if (ancestor === void 0) {
+      return Object.freeze({ kind: "conflict" });
+    }
+  }
+  if (reservation !== void 0) {
+    return parent === void 0 ? Object.freeze({ kind: "admitted" }) : Object.freeze({ kind: "admitted", parent });
+  }
+  const unmaterializedReservations = [...input.reservations].filter(
+    ([collaborationId]) => !input.nodes.has(collaborationId)
+  );
+  const childCount = parent === void 0 ? 0 : [...input.nodes.values()].filter(
+    (node) => node.parentCollaborationId === parent.collaborationId
+  ).length + unmaterializedReservations.filter(
+    ([, retainedReservation]) => retainedReservation.parentCollaborationId === parent.collaborationId
+  ).length;
+  const activeCount = [...input.nodes.values()].filter(
+    (node) => !TERMINAL_COLLABORATION_STATUSES.has(node.status)
+  ).length + unmaterializedReservations.length;
+  if (input.nodes.size + unmaterializedReservations.length >= AGENT_COLLABORATION_GRAPH_LIMITS.maxNodes || childCount >= input.capability.maxChildrenPerNode || depth > input.capability.maxDepth || input.candidate.active && activeCount >= input.capability.maxActiveNodes) {
+    return Object.freeze({ kind: "capacity_exceeded" });
+  }
+  return parent === void 0 ? Object.freeze({ kind: "admitted" }) : Object.freeze({ kind: "admitted", parent });
+}
 function invalidTurnSequence(providerKey, message) {
   return throwAgentProviderContractError(
     providerKey,
@@ -59,13 +171,61 @@ function completeTurnSequence(input) {
 }
 const FINAL_DIFF_TRAILING_EVENT_TYPES = [
   "artifact.referenced",
+  "collaboration.updated",
+  "operation.updated",
   "provider.diagnostic",
+  "resource.updated",
   "runtime.error",
   "runtime.warning",
   "turn.completed"
 ];
+const TERMINAL_ITEM_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "canceled"
+]);
+function observeItemLifecycle(input) {
+  const { event, providerKey, state } = input;
+  const previous = state.observedItems.get(event.payload.itemId);
+  if (event.type === "item.completed" && !TERMINAL_ITEM_STATUSES.has(event.payload.status)) {
+    invalidTurnSequence(
+      providerKey,
+      "Provider completed an item without a terminal item status."
+    );
+  }
+  if (previous?.terminal) {
+    invalidTurnSequence(
+      providerKey,
+      "Provider emitted an item lifecycle event after the item became terminal."
+    );
+  }
+  if (previous?.itemKind !== void 0 && previous.itemKind !== event.payload.itemKind) {
+    invalidTurnSequence(
+      providerKey,
+      "Provider changed the kind of an existing item identity."
+    );
+  }
+  if (previous !== void 0 && event.type === "item.started") {
+    invalidTurnSequence(
+      providerKey,
+      "Provider started an item identity more than once."
+    );
+  }
+  if (previous?.inProgressObserved && event.payload.status === "pending") {
+    invalidTurnSequence(
+      providerKey,
+      "Provider regressed an in-progress item to pending."
+    );
+  }
+  state.observedItems.set(event.payload.itemId, {
+    itemKind: event.payload.itemKind,
+    status: event.payload.status,
+    inProgressObserved: previous?.inProgressObserved === true || event.payload.status === "in_progress",
+    terminal: event.type === "item.completed" || TERMINAL_ITEM_STATUSES.has(event.payload.status)
+  });
+}
 function assertApprovalSubjectCorrelation(input) {
-  const request = input.event.payload.request;
+  const { request } = input;
   if (request.requestKind !== "approval") return;
   if (request.subject.kind === "plan") {
     if (input.state.proposedPlans.get(request.subject.artifactId) !== request.requestId) {
@@ -76,14 +236,24 @@ function assertApprovalSubjectCorrelation(input) {
     }
     return;
   }
-  const status = input.state.observedItems.get(request.subject.itemId);
-  if (status !== "pending" && status !== "in_progress") {
+  const item = input.state.observedItems.get(request.subject.itemId);
+  const itemIsLive = item !== void 0 && !item.terminal && (item.status === "pending" || item.status === "in_progress" || item.status === "unknown" && item.inProgressObserved);
+  if (!itemIsLive) {
     invalidTurnSequence(
       input.providerKey,
       "Provider approval request does not identify a live item from this turn."
     );
   }
 }
+function assertPendingApprovalSubjectCorrelations(input) {
+  for (const pending of input.pendingRequests.values()) {
+    assertApprovalSubjectCorrelation({
+      providerKey: input.providerKey,
+      request: pending.request,
+      state: input.state
+    });
+  }
+}
 function observeContextUsage(input) {
   const previous = input.state.latestByScope.get(input.usage.measurementScope);
   if (previous !== void 0) {
@@ -123,6 +293,11 @@ function observeContextUsage(input) {
   input.state.latestByScope.set(input.usage.measurementScope, input.usage);
   input.state.compactionReadyScopes.delete(input.usage.measurementScope);
 }
+function observeContextMaterializationBoundary(state) {
+  state.latestByScope.delete("materialization");
+  state.cumulativeByScope.delete("materialization");
+  state.compactionReadyScopes.delete("materialization");
+}
 function observeTurnEvent(input) {
   const {
     contextUsageState,
@@ -175,7 +350,12 @@ function observeTurnEvent(input) {
     }
   }
   if (event.type === "item.started" || event.type === "item.updated" || event.type === "item.completed") {
-    state.observedItems.set(event.payload.itemId, event.payload.status);
+    observeItemLifecycle({ providerKey, event, state });
+    assertPendingApprovalSubjectCorrelations({
+      providerKey,
+      pendingRequests,
+      state
+    });
     if (event.payload.itemKind === "context_compaction" && event.type === "item.completed" && event.payload.status === "completed") {
       for (const scope of ["session", "materialization"]) {
         contextUsageState.compactionReadyScopes.add(scope);
@@ -184,6 +364,11 @@ function observeTurnEvent(input) {
   }
   if (event.type === "turn.plan.proposed") {
     state.proposedPlans.set(event.payload.artifactId, event.payload.requestId);
+    assertPendingApprovalSubjectCorrelations({
+      providerKey,
+      pendingRequests,
+      state
+    });
   }
   if (event.type === "context.usage.updated") {
     observeContextUsage({
@@ -206,7 +391,11 @@ function observeTurnEvent(input) {
         "Provider reused a request ID within a session."
       );
     }
-    assertApprovalSubjectCorrelation({ providerKey, event, state });
+    assertApprovalSubjectCorrelation({
+      providerKey,
+      request: event.payload.request,
+      state
+    });
     openedRequestIds.add(requestId);
     pendingRequests.set(requestId, {
       request: event.payload.request,
@@ -226,6 +415,98 @@ function observeTurnEvent(input) {
     completeTurnSequence({ providerKey, state, pendingRequests });
   }
 }
+function observeTurnOutput(input) {
+  if (input.output.kind === "lifecycle" && input.output.lifecycle.type === "process.started") {
+    observeContextMaterializationBoundary(input.contextUsageState);
+  }
+  if (input.output.kind !== "event") return;
+  if (input.output.event.type === "operation.updated") {
+    const result = validateAgentOperationResultTransition({
+      providerKey: input.providerKey,
+      candidate: input.output.event.payload.result,
+      previous: input.interactionState.operationResults.get(
+        input.output.event.payload.result.invocationId
+      )
+    });
+    input.interactionState.operationResults.set(result.invocationId, result);
+    const invocation = input.interactionState.operationInvocations.get(
+      result.invocationId
+    );
+    if (invocation !== void 0) invocation.result = result;
+  }
+  if (input.output.event.type === "collaboration.updated") {
+    const node = validateAgentCollaborationNodeForCapabilities({
+      capabilities: input.capabilities,
+      candidate: input.output.event.payload.node,
+      previous: input.interactionState.collaborationNodes.get(
+        input.output.event.payload.node.collaborationId
+      )
+    });
+    const capability = input.capabilities.collaboration;
+    if (capability.kind !== "supported") {
+      throwAgentProviderContractError(
+        input.providerKey,
+        "output_capability_mismatch",
+        "Provider emitted collaboration state without declaring support."
+      );
+    }
+    const admission = evaluateCollaborationGraphAdmission({
+      capability,
+      candidate: {
+        collaborationId: node.collaborationId,
+        rootCollaborationId: node.rootCollaborationId,
+        ...node.parentCollaborationId === void 0 ? {} : { parentCollaborationId: node.parentCollaborationId },
+        active: !TERMINAL_COLLABORATION_STATUSES.has(node.status)
+      },
+      nodes: input.interactionState.collaborationNodes,
+      reservations: input.interactionState.collaborationSpawnReservations
+    });
+    if (admission.kind === "conflict") {
+      throwAgentProviderContractError(
+        input.providerKey,
+        "output_collaboration_mismatch",
+        "Provider emitted a collaboration node outside the canonical graph."
+      );
+    }
+    if (admission.kind === "capacity_exceeded") {
+      throwAgentProviderContractError(
+        input.providerKey,
+        "output_capability_mismatch",
+        "Provider emitted a collaboration graph outside its declared limits."
+      );
+    }
+    input.interactionState.collaborationNodes.set(node.collaborationId, node);
+  }
+  if (input.output.event.type === "resource.updated") {
+    const capability = input.capabilities.generatedResources;
+    const resourceId = input.output.event.payload.resource.resourceId;
+    if (capability.kind !== "supported" || !input.state.generatedResourceIds.has(resourceId) && input.state.generatedResourceIds.size >= capability.maxResourcesPerTurn) {
+      throwAgentProviderContractError(
+        input.providerKey,
+        "output_capability_mismatch",
+        "Provider exceeded its declared generated-resource count for the turn."
+      );
+    }
+    const resource = validateAgentGeneratedResourceForCapabilities({
+      capabilities: input.capabilities,
+      candidate: input.output.event.payload.resource,
+      expectedResourceId: input.output.event.payload.resource.resourceId,
+      previous: input.interactionState.generatedResources.get(
+        input.output.event.payload.resource.resourceId
+      )
+    });
+    input.state.generatedResourceIds.add(resource.resourceId);
+    input.interactionState.generatedResources.set(resource.resourceId, resource);
+  }
+  observeTurnEvent({
+    providerKey: input.providerKey,
+    event: input.output.event,
+    state: input.state,
+    pendingRequests: input.pendingRequests,
+    openedRequestIds: input.openedRequestIds,
+    contextUsageState: input.contextUsageState
+  });
+}
 function assertStableTurnBoundary(input) {
   const terminal = input.state.terminal && !input.state.waiting;
   const waiting = !input.state.terminal && input.state.waiting && input.pendingRequests.size === 1;
@@ -261,14 +542,15 @@ function interruptionTerminalizesTurn(input) {
 }
 function observeTurnOperationOutputs(input) {
   for (const output of input.outputs ?? []) {
-    if (output.kind !== "event") continue;
-    observeTurnEvent({
+    observeTurnOutput({
       providerKey: input.providerKey,
-      event: output.event,
+      output,
       state: input.state,
       pendingRequests: input.pendingRequests,
       openedRequestIds: input.openedRequestIds,
-      contextUsageState: input.contextUsageState
+      contextUsageState: input.contextUsageState,
+      capabilities: input.capabilities,
+      interactionState: input.interactionState
     });
   }
 }
@@ -278,17 +560,9 @@ function reconstructWaitingTurn(input) {
       ([, pending]) => pending.turnId === input.turnId
     )
   );
-  if (targetedPendingRequests.size === 0) return null;
+  if (targetedPendingRequests.size === 0 || input.state === void 0 || input.state.terminal || !input.state.waiting) return null;
   return {
-    state: {
-      fileChangeMode: input.fileChangeMode,
-      observedItems: /* @__PURE__ */ new Map(),
-      proposedPlans: /* @__PURE__ */ new Map(),
-      started: true,
-      terminal: false,
-      waiting: true,
-      finalDiffObserved: false
-    },
+    state: input.state,
     pendingRequests: targetedPendingRequests
   };
 }
@@ -376,12 +650,22 @@ function validateAgentProviderSession(input) {
   }
   validateSessionPorts(capabilities, input.candidate);
   const pendingRequests = /* @__PURE__ */ new Map();
+  const waitingTurnStates = /* @__PURE__ */ new Map();
   const openedRequestIds = /* @__PURE__ */ new Set();
   const contextUsageState = {
     latestByScope: /* @__PURE__ */ new Map(),
     cumulativeByScope: /* @__PURE__ */ new Map(),
     compactionReadyScopes: /* @__PURE__ */ new Set()
   };
+  const interactionState = {
+    operationResults: /* @__PURE__ */ new Map(),
+    operationInvocations: /* @__PURE__ */ new Map(),
+    collaborationNodes: /* @__PURE__ */ new Map(),
+    collaborationSpawnReservations: /* @__PURE__ */ new Map(),
+    generatedResources: /* @__PURE__ */ new Map()
+  };
+  const collaborationNodes = interactionState.collaborationNodes;
+  const collaborationSpawnReservations = interactionState.collaborationSpawnReservations;
   let activeTurn = null;
   let closePromise = null;
   let closed = false;
@@ -421,6 +705,39 @@ function validateAgentProviderSession(input) {
       throw error;
     }
   };
+  const delegateProviderMutation = async (input2) => {
+    let executionStarted = false;
+    const onProviderExecutionStarted = () => {
+      if (executionStarted) {
+        throwAgentProviderContractError(
+          providerKey,
+          "invalid_operation_result",
+          "Provider reported operation execution more than once."
+        );
+      }
+      input2.observer?.();
+      executionStarted = true;
+    };
+    try {
+      const candidate = await input2.invoke(onProviderExecutionStarted);
+      if (!executionStarted) {
+        throwAgentProviderContractError(
+          providerKey,
+          "invalid_operation_result",
+          "Provider completed an operation without reporting execution start."
+        );
+      }
+      return input2.validate(candidate);
+    } catch (error) {
+      if (!executionStarted) throw error;
+      unusable = true;
+      throw new AgentProviderDelegatedOperationError(
+        providerKey,
+        input2.operation,
+        error
+      );
+    }
+  };
   const runTurn = async function* (turnInput) {
     requireUsable();
     throwIfAgentOperationAborted(turnInput.signal);
@@ -465,6 +782,7 @@ function validateAgentProviderSession(input) {
         fileChangeMode: capabilities.output.fileChanges,
         observedItems: /* @__PURE__ */ new Map(),
         proposedPlans: /* @__PURE__ */ new Map(),
+        generatedResourceIds: /* @__PURE__ */ new Set(),
         started: false,
         terminal: false,
         waiting: false,
@@ -483,16 +801,16 @@ function validateAgentProviderSession(input) {
           candidate,
           outputContext(parsedInput.turnId)
         );
-        if (output.kind === "event") {
-          observeTurnEvent({
-            providerKey,
-            event: output.event,
-            state: currentTurn.state,
-            pendingRequests: currentTurn.pendingRequests,
-            openedRequestIds,
-            contextUsageState
-          });
-        }
+        observeTurnOutput({
+          capabilities,
+          providerKey,
+          output,
+          state: currentTurn.state,
+          pendingRequests: currentTurn.pendingRequests,
+          openedRequestIds,
+          contextUsageState,
+          interactionState
+        });
         yield output;
       }
       while (currentTurn.inFlightOperations.size > 0) {
@@ -511,6 +829,9 @@ function validateAgentProviderSession(input) {
       });
       if (currentTurn.state.waiting) {
         replacePendingRequests(pendingRequests, currentTurn.pendingRequests);
+        waitingTurnStates.set(currentTurn.turnId, currentTurn.state);
+      } else {
+        waitingTurnStates.delete(currentTurn.turnId);
       }
       reachedStableBoundary = true;
     } finally {
@@ -555,18 +876,19 @@ function validateAgentProviderSession(input) {
         "Provider session already has an active turn."
       );
     }
+    const waitingTurnState = waitingTurnStates.get(pending.turnId);
+    if (waitingTurnState === void 0 || waitingTurnState.terminal || !waitingTurnState.waiting) {
+      throwAgentProviderContractError(
+        providerKey,
+        "request_resolution_mismatch",
+        "Provider request resolution does not identify a waiting turn."
+      );
+    }
+    waitingTurnState.waiting = false;
     const currentTurn = {
       turnId: pending.turnId,
       pendingRequests: nextPendingRequests,
-      state: {
-        fileChangeMode: capabilities.output.fileChanges,
-        observedItems: /* @__PURE__ */ new Map(),
-        proposedPlans: /* @__PURE__ */ new Map(),
-        started: true,
-        terminal: false,
-        waiting: false,
-        finalDiffObserved: false
-      },
+      state: waitingTurnState,
       inFlightOperations: /* @__PURE__ */ new Set()
     };
     let reachedStableBoundary = false;
@@ -580,16 +902,16 @@ function validateAgentProviderSession(input) {
           candidate,
           outputContext(pending.turnId)
         );
-        if (output.kind === "event") {
-          observeTurnEvent({
-            providerKey,
-            event: output.event,
-            state: currentTurn.state,
-            pendingRequests: currentTurn.pendingRequests,
-            openedRequestIds,
-            contextUsageState
-          });
-        }
+        observeTurnOutput({
+          capabilities,
+          providerKey,
+          output,
+          state: currentTurn.state,
+          pendingRequests: currentTurn.pendingRequests,
+          openedRequestIds,
+          contextUsageState,
+          interactionState
+        });
         yield output;
       }
       while (currentTurn.inFlightOperations.size > 0) {
@@ -601,6 +923,11 @@ function validateAgentProviderSession(input) {
         pendingRequests: currentTurn.pendingRequests
       });
       replacePendingRequests(pendingRequests, currentTurn.pendingRequests);
+      if (currentTurn.state.waiting) {
+        waitingTurnStates.set(currentTurn.turnId, currentTurn.state);
+      } else {
+        waitingTurnStates.delete(currentTurn.turnId);
+      }
       reachedStableBoundary = true;
     } finally {
       if (!reachedStableBoundary) unusable = true;
@@ -622,7 +949,7 @@ function validateAgentProviderSession(input) {
       const targetedWaitingTurn = targetedActiveTurn === null ? reconstructWaitingTurn({
         pendingRequests,
         turnId: parsed.turnId,
-        fileChangeMode: capabilities.output.fileChanges
+        state: waitingTurnStates.get(parsed.turnId)
       }) : null;
       const targetedTurn = targetedActiveTurn ?? targetedWaitingTurn;
       if (targetedTurn === null) {
@@ -654,15 +981,18 @@ function validateAgentProviderSession(input) {
             parsed.turnId
           );
           targetedTurn.state.waiting = false;
+          waitingTurnStates.delete(parsed.turnId);
         }
         try {
           observeTurnOperationOutputs({
+            capabilities,
             providerKey,
             outputs: result.outputs,
             state: targetedTurn.state,
             pendingRequests: targetedTurn.pendingRequests,
             openedRequestIds,
-            contextUsageState
+            contextUsageState,
+            interactionState
           });
           if (terminalized && !targetedTurn.state.terminal) {
             completeTurnSequence({
@@ -735,22 +1065,433 @@ function validateAgentProviderSession(input) {
   const declaredConfiguration = input.candidate.configuration;
   const configuration = declaredConfiguration.kind === "managed" ? Object.freeze({ kind: "managed" }) : Object.freeze({
     kind: "selectable",
-    applyConfiguration: async (configurationInput) => {
+    listConfiguration: async (listInput = {}) => {
       requireUsable();
-      throwIfAgentOperationAborted(configurationInput.signal);
-      const configuration2 = parseAgentSessionConfiguration(
-        configurationInput.configuration
+      throwIfAgentOperationAborted(listInput.signal);
+      return validateAgentConfigurationCatalogForCapabilities(
+        capabilities,
+        await declaredConfiguration.listConfiguration(
+          listInput.signal === void 0 ? {} : { signal: listInput.signal }
+        )
       );
-      assertAgentSessionConfigurationSupported(
+    },
+    applyConfigurationSelection: async (configurationInput) => {
+      requireUsable();
+      throwIfAgentOperationAborted(configurationInput.signal);
+      const catalog = validateAgentConfigurationCatalogForCapabilities(
         capabilities,
-        configuration2
+        await declaredConfiguration.listConfiguration(
+          configurationInput.signal === void 0 ? {} : { signal: configurationInput.signal }
+        )
       );
-      return delegateOperation(
-        () => declaredConfiguration.applyConfiguration({
-          configuration: configuration2,
+      let selection;
+      try {
+        selection = parseAgentConfigurationSelectionFor(
+          catalog,
+          configurationInput.selection
+        );
+      } catch {
+        return throwAgentProviderContractError(
+          providerKey,
+          "configuration_value_unsupported",
+          "Configuration selection is stale or outside the offered catalog."
+        );
+      }
+      return delegateProviderMutation({
+        operation: "apply_configuration",
+        observer: configurationInput.onProviderExecutionStarted,
+        invoke: (onProviderExecutionStarted) => declaredConfiguration.applyConfigurationSelection({
+          selection,
+          onProviderExecutionStarted,
           ...configurationInput.signal === void 0 ? {} : { signal: configurationInput.signal }
+        }),
+        validate: (candidate) => validateAgentProviderOperationResult(
+          candidate,
+          outputContext()
+        )
+      });
+    }
+  });
+  const declaredOperations = input.candidate.operations;
+  const operations = declaredOperations.kind === "unsupported" ? Object.freeze({ kind: "unsupported" }) : Object.freeze({
+    kind: "supported",
+    listOperations: async (listInput = {}) => {
+      requireUsable();
+      throwIfAgentOperationAborted(listInput.signal);
+      return validateAgentOperationCatalogForCapabilities(
+        capabilities,
+        await declaredOperations.listOperations(
+          listInput.signal === void 0 ? {} : { signal: listInput.signal }
+        )
+      );
+    },
+    invokeOperation: async (operationInput) => {
+      requireUsable();
+      throwIfAgentOperationAborted(operationInput.signal);
+      let invocation;
+      try {
+        invocation = parseAgentOperationInvocation(operationInput.invocation);
+      } catch {
+        return throwAgentProviderContractError(
+          providerKey,
+          "input_operation_mismatch",
+          "Operation invocation is invalid."
+        );
+      }
+      const catalog = validateAgentOperationCatalogForCapabilities(
+        capabilities,
+        await declaredOperations.listOperations(
+          operationInput.signal === void 0 ? {} : { signal: operationInput.signal }
+        )
+      );
+      const descriptor = catalog.operations.find(
+        (operation) => operation.operationId === invocation.operationId
+      );
+      if (descriptor === void 0) {
+        return throwAgentProviderContractError(
+          providerKey,
+          "input_operation_mismatch",
+          "Operation invocation does not identify an offered operation."
+        );
+      }
+      try {
+        invocation = parseAgentOperationInvocationFor(
+          descriptor,
+          invocation
+        );
+      } catch {
+        return throwAgentProviderContractError(
+          providerKey,
+          "input_operation_mismatch",
+          "Operation invocation is stale or outside the offered descriptor."
+        );
+      }
+      const existing = interactionState.operationInvocations.get(
+        invocation.invocationId
+      );
+      if (existing !== void 0) {
+        if (JSON.stringify(existing.invocation) !== JSON.stringify(invocation)) {
+          return throwAgentProviderContractError(
+            providerKey,
+            "input_operation_mismatch",
+            "Operation invocation ID was reused with conflicting input."
+          );
+        }
+        if (descriptor.idempotency === "required" && existing.result !== void 0) {
+          return existing.result;
+        }
+        return throwAgentProviderContractError(
+          providerKey,
+          "input_operation_mismatch",
+          "Operation invocation ID is already active or is not replayable."
+        );
+      }
+      const trackedInvocation = {
+        invocation
+      };
+      interactionState.operationInvocations.set(
+        invocation.invocationId,
+        trackedInvocation
+      );
+      try {
+        const result = await delegateProviderMutation({
+          operation: "invoke_operation",
+          observer: operationInput.onProviderExecutionStarted,
+          invoke: (onProviderExecutionStarted) => declaredOperations.invokeOperation({
+            invocation,
+            onProviderExecutionStarted,
+            ...operationInput.signal === void 0 ? {} : { signal: operationInput.signal }
+          }),
+          validate: (candidate) => {
+            const result2 = validateAgentOperationResultTransition({
+              providerKey,
+              candidate: validateAgentOperationResultForInvocation(
+                providerKey,
+                descriptor,
+                invocation,
+                candidate
+              ),
+              previous: interactionState.operationResults.get(
+                invocation.invocationId
+              )
+            });
+            interactionState.operationResults.set(
+              result2.invocationId,
+              result2
+            );
+            return result2;
+          }
+        });
+        trackedInvocation.result = result;
+        return result;
+      } catch (error) {
+        if (!(error instanceof AgentProviderDelegatedOperationError)) {
+          interactionState.operationInvocations.delete(
+            invocation.invocationId
+          );
+        }
+        throw error;
+      }
+    }
+  });
+  const declaredManagedContent = input.candidate.managedContent;
+  const managedContent = declaredManagedContent.kind === "unsupported" ? Object.freeze({ kind: "unsupported" }) : Object.freeze({
+    kind: "supported",
+    listManagedContent: async (listInput = {}) => {
+      requireUsable();
+      throwIfAgentOperationAborted(listInput.signal);
+      return validateAgentManagedContentCatalogForCapabilities(
+        capabilities,
+        await declaredManagedContent.listManagedContent(
+          listInput.signal === void 0 ? {} : { signal: listInput.signal }
+        )
+      );
+    }
+  });
+  const declaredIntegrations = input.candidate.integrations;
+  const integrations = declaredIntegrations.kind === "unsupported" ? Object.freeze({ kind: "unsupported" }) : Object.freeze({
+    kind: "supported",
+    observeIntegrations: async (listInput = {}) => {
+      requireUsable();
+      throwIfAgentOperationAborted(listInput.signal);
+      return validateAgentIntegrationCatalogForCapabilities(
+        capabilities,
+        await declaredIntegrations.observeIntegrations(
+          listInput.signal === void 0 ? {} : { signal: listInput.signal }
+        )
+      );
+    }
+  });
+  const declaredCollaboration = input.candidate.collaboration;
+  const collaboration = declaredCollaboration.kind === "unsupported" ? Object.freeze({ kind: "unsupported" }) : Object.freeze({
+    kind: "supported",
+    spawnCollaboration: async (collaborationInput) => {
+      requireUsable();
+      throwIfAgentOperationAborted(collaborationInput.signal);
+      let spawn;
+      try {
+        spawn = parseAgentCollaborationSpawnInput(collaborationInput.spawn);
+      } catch {
+        return throwAgentProviderContractError(
+          providerKey,
+          "input_operation_mismatch",
+          "Collaboration spawn input is invalid."
+        );
+      }
+      const capability = capabilities.collaboration;
+      if (capability.kind !== "supported" || !capability.controlActions.includes("spawn") || !capability.roles.includes(spawn.role) || collaborationNodes.has(spawn.collaborationId) || collaborationSpawnReservations.has(spawn.collaborationId)) {
+        return throwAgentProviderContractError(
+          providerKey,
+          "input_capability_mismatch",
+          "Collaboration spawn is outside the provider's declared capability."
+        );
+      }
+      const observedParent = spawn.parentCollaborationId === void 0 ? void 0 : collaborationNodes.get(spawn.parentCollaborationId);
+      const admission = evaluateCollaborationGraphAdmission({
+        capability,
+        candidate: {
+          collaborationId: spawn.collaborationId,
+          rootCollaborationId: observedParent?.rootCollaborationId ?? spawn.collaborationId,
+          ...spawn.parentCollaborationId === void 0 ? {} : { parentCollaborationId: spawn.parentCollaborationId },
+          active: true
+        },
+        nodes: collaborationNodes,
+        reservations: collaborationSpawnReservations
+      });
+      if (admission.kind === "conflict") {
+        return throwAgentProviderContractError(
+          providerKey,
+          "input_operation_mismatch",
+          "Collaboration parent is unavailable in the canonical graph."
+        );
+      }
+      if (admission.kind === "capacity_exceeded") {
+        return throwAgentProviderContractError(
+          providerKey,
+          "input_capability_mismatch",
+          "Collaboration graph limit would be exceeded."
+        );
+      }
+      const parent = admission.parent;
+      collaborationSpawnReservations.set(
+        spawn.collaborationId,
+        Object.freeze({
+          ...spawn.parentCollaborationId === void 0 ? {} : { parentCollaborationId: spawn.parentCollaborationId }
         })
       );
+      try {
+        const node = await delegateProviderMutation({
+          operation: "spawn_collaboration",
+          observer: collaborationInput.onProviderExecutionStarted,
+          invoke: (onProviderExecutionStarted) => declaredCollaboration.spawnCollaboration({
+            spawn,
+            onProviderExecutionStarted,
+            ...collaborationInput.signal === void 0 ? {} : { signal: collaborationInput.signal }
+          }),
+          validate: (candidate) => {
+            const node2 = validateAgentCollaborationNodeForCapabilities({
+              capabilities,
+              candidate
+            });
+            if (node2.collaborationId !== spawn.collaborationId || node2.parentCollaborationId !== spawn.parentCollaborationId || node2.role !== spawn.role || node2.title !== spawn.title || node2.objective !== spawn.objective || node2.createdAt !== spawn.createdAt || node2.rootCollaborationId !== (parent?.rootCollaborationId ?? spawn.collaborationId)) {
+              return throwAgentProviderContractError(
+                providerKey,
+                "output_collaboration_mismatch",
+                "Provider collaboration node does not match the spawn input."
+              );
+            }
+            return node2;
+          }
+        });
+        collaborationNodes.set(node.collaborationId, node);
+        collaborationSpawnReservations.delete(spawn.collaborationId);
+        return node;
+      } catch (error) {
+        if (!(error instanceof AgentProviderDelegatedOperationError)) {
+          collaborationSpawnReservations.delete(spawn.collaborationId);
+        }
+        throw error;
+      }
+    },
+    controlCollaboration: async (collaborationInput) => {
+      requireUsable();
+      throwIfAgentOperationAborted(collaborationInput.signal);
+      let control;
+      try {
+        control = parseAgentCollaborationControlInput(
+          collaborationInput.control
+        );
+      } catch {
+        return throwAgentProviderContractError(
+          providerKey,
+          "input_operation_mismatch",
+          "Collaboration control input is invalid."
+        );
+      }
+      const capability = capabilities.collaboration;
+      const previous = collaborationNodes.get(control.collaborationId);
+      if (capability.kind !== "supported" || !capability.controlActions.includes(control.action) || previous === void 0) {
+        return throwAgentProviderContractError(
+          providerKey,
+          "input_capability_mismatch",
+          "Collaboration control is outside the observed graph or declared capability."
+        );
+      }
+      const terminal = ["completed", "failed", "canceled"].includes(
+        previous.status
+      );
+      if (control.action === "close" && previous.closedAt !== void 0) {
+        return previous;
+      }
+      if (control.action === "close" && !terminal || control.action === "stop" && terminal || control.action === "steer" && terminal || control.action !== "inspect" && previous.closedAt !== void 0) {
+        return throwAgentProviderContractError(
+          providerKey,
+          "input_capability_mismatch",
+          "Collaboration control is unavailable in the current lifecycle state."
+        );
+      }
+      const node = await delegateProviderMutation({
+        operation: "control_collaboration",
+        observer: collaborationInput.onProviderExecutionStarted,
+        invoke: (onProviderExecutionStarted) => declaredCollaboration.controlCollaboration({
+          control,
+          onProviderExecutionStarted,
+          ...collaborationInput.signal === void 0 ? {} : { signal: collaborationInput.signal }
+        }),
+        validate: (candidate) => {
+          const validated = validateAgentCollaborationNodeForCapabilities({
+            capabilities,
+            candidate,
+            previous
+          });
+          if (control.action === "stop" && validated.status !== "canceled" || control.action === "close" && (validated.status !== previous.status || validated.closedAt === void 0)) {
+            return throwAgentProviderContractError(
+              providerKey,
+              "output_collaboration_mismatch",
+              "Provider collaboration result does not settle the requested control action."
+            );
+          }
+          return validated;
+        }
+      });
+      collaborationNodes.set(node.collaborationId, node);
+      return node;
+    }
+  });
+  function validateGeneratedResourceInspection(candidate, resourceId) {
+    if (candidate === null || typeof candidate !== "object" || !hasExactOwnKeys(candidate, [
+      "descriptor",
+      ..."candidate" in candidate ? ["candidate"] : []
+    ])) {
+      return throwAgentProviderContractError(
+        providerKey,
+        "output_resource_mismatch",
+        "Provider returned an invalid generated-resource inspection."
+      );
+    }
+    const rawInspection = candidate;
+    const descriptor = validateAgentGeneratedResourceForCapabilities({
+      capabilities,
+      candidate: rawInspection.descriptor,
+      expectedResourceId: resourceId,
+      previous: interactionState.generatedResources.get(resourceId)
+    });
+    const hasCandidate = Object.prototype.hasOwnProperty.call(
+      rawInspection,
+      "candidate"
+    );
+    if (descriptor.status === "available" !== hasCandidate) {
+      return throwAgentProviderContractError(
+        providerKey,
+        "output_resource_mismatch",
+        "Exactly available generated resources must include owned artifact bytes."
+      );
+    }
+    if (!hasCandidate) return Object.freeze({ descriptor });
+    let artifactCandidate;
+    try {
+      artifactCandidate = createAgentArtifactCandidate(
+        rawInspection.candidate
+      );
+    } catch {
+      return throwAgentProviderContractError(
+        providerKey,
+        "output_resource_mismatch",
+        "Provider returned invalid generated-resource artifact bytes."
+      );
+    }
+    const artifact = artifactCandidate.descriptor;
+    const expectedArtifactKind = descriptor.kind === "image" ? "image" : "file";
+    if (artifactCandidate.delivery !== "required_before_reference" || artifact.artifactId !== descriptor.artifactId || artifact.kind !== expectedArtifactKind || artifact.displayName !== descriptor.displayName || artifact.mediaType !== descriptor.mediaType || artifact.byteSize !== descriptor.byteSize || artifact.digest?.algorithm !== "sha256" || artifact.digest?.value !== descriptor.sha256 || artifact.summary !== descriptor.summary) {
+      return throwAgentProviderContractError(
+        providerKey,
+        "output_resource_mismatch",
+        "Generated-resource metadata does not match its immutable artifact candidate."
+      );
+    }
+    return Object.freeze({ descriptor, candidate: artifactCandidate });
+  }
+  const declaredGeneratedResources = input.candidate.generatedResources;
+  const generatedResources = declaredGeneratedResources.kind === "unsupported" ? Object.freeze({ kind: "unsupported" }) : Object.freeze({
+    kind: "supported",
+    getGeneratedResource: async (resourceInput) => {
+      requireUsable();
+      throwIfAgentOperationAborted(resourceInput.signal);
+      const resourceId = parseAgentGeneratedResourceId(
+        resourceInput.resourceId
+      );
+      const inspection = validateGeneratedResourceInspection(
+        await declaredGeneratedResources.getGeneratedResource({
+          resourceId,
+          ...resourceInput.signal === void 0 ? {} : { signal: resourceInput.signal }
+        }),
+        resourceId
+      );
+      interactionState.generatedResources.set(
+        inspection.descriptor.resourceId,
+        inspection.descriptor
+      );
+      return inspection;
     }
   });
   const close = (closeInput) => {
@@ -782,6 +1523,11 @@ function validateAgentProviderSession(input) {
     interruption,
     steering,
     configuration,
+    operations,
+    managedContent,
+    integrations,
+    collaboration,
+    generatedResources,
     close
   });
 }