@agen-ai/agent-runtime 0.2.2 → 0.2.4

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,7 +171,10 @@ 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"
@@ -305,6 +420,84 @@ function observeTurnOutput(input) {
     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,
@@ -314,6 +507,45 @@ function observeTurnOutput(input) {
     contextUsageState: input.contextUsageState
   });
 }
+const SESSION_OPERATION_OBSERVATION_EVENT_TYPES = /* @__PURE__ */ new Set([
+  "item.started",
+  "item.updated",
+  "item.completed",
+  "progress.updated",
+  "context.usage.updated",
+  "operation.updated",
+  "resource.updated",
+  "runtime.warning",
+  "runtime.error",
+  "provider.diagnostic"
+]);
+function observeSessionOperationOutput(input) {
+  if (input.output.kind === "event") {
+    const event = input.output.event;
+    if (!SESSION_OPERATION_OBSERVATION_EVENT_TYPES.has(event.type)) {
+      invalidTurnSequence(
+        input.providerKey,
+        "Provider emitted turn-owned output from a session operation."
+      );
+    }
+    if ((event.type === "item.started" || event.type === "item.updated" || event.type === "item.completed") && event.payload.itemKind !== "context_compaction") {
+      invalidTurnSequence(
+        input.providerKey,
+        "Provider emitted a non-compaction item from a session operation."
+      );
+    }
+  }
+  observeTurnOutput({
+    capabilities: input.capabilities,
+    providerKey: input.providerKey,
+    output: input.output,
+    state: input.state,
+    pendingRequests: /* @__PURE__ */ new Map(),
+    openedRequestIds: /* @__PURE__ */ new Set(),
+    contextUsageState: input.contextUsageState,
+    interactionState: input.interactionState
+  });
+}
 function assertStableTurnBoundary(input) {
   const terminal = input.state.terminal && !input.state.waiting;
   const waiting = !input.state.terminal && input.state.waiting && input.pendingRequests.size === 1;
@@ -355,7 +587,9 @@ function observeTurnOperationOutputs(input) {
       state: input.state,
       pendingRequests: input.pendingRequests,
       openedRequestIds: input.openedRequestIds,
-      contextUsageState: input.contextUsageState
+      contextUsageState: input.contextUsageState,
+      capabilities: input.capabilities,
+      interactionState: input.interactionState
     });
   }
 }
@@ -462,6 +696,15 @@ function validateAgentProviderSession(input) {
     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;
@@ -501,6 +744,49 @@ 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;
+    };
+    const onOutput = async (candidate) => {
+      if (!executionStarted) {
+        throwAgentProviderContractError(
+          providerKey,
+          "invalid_operation_result",
+          "Provider emitted operation output before reporting execution start."
+        );
+      }
+      await input2.observeOutput?.(candidate);
+    };
+    try {
+      const candidate = await input2.invoke(onProviderExecutionStarted, onOutput);
+      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);
@@ -545,6 +831,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,
@@ -564,12 +851,14 @@ function validateAgentProviderSession(input) {
           outputContext(parsedInput.turnId)
         );
         observeTurnOutput({
+          capabilities,
           providerKey,
           output,
           state: currentTurn.state,
           pendingRequests: currentTurn.pendingRequests,
           openedRequestIds,
-          contextUsageState
+          contextUsageState,
+          interactionState
         });
         yield output;
       }
@@ -663,12 +952,14 @@ function validateAgentProviderSession(input) {
           outputContext(pending.turnId)
         );
         observeTurnOutput({
+          capabilities,
           providerKey,
           output,
           state: currentTurn.state,
           pendingRequests: currentTurn.pendingRequests,
           openedRequestIds,
-          contextUsageState
+          contextUsageState,
+          interactionState
         });
         yield output;
       }
@@ -743,12 +1034,14 @@ function validateAgentProviderSession(input) {
         }
         try {
           observeTurnOperationOutputs({
+            capabilities,
             providerKey,
             outputs: result.outputs,
             state: targetedTurn.state,
             pendingRequests: targetedTurn.pendingRequests,
             openedRequestIds,
-            contextUsageState
+            contextUsageState,
+            interactionState
           });
           if (terminalized && !targetedTurn.state.terminal) {
             completeTurnSequence({
@@ -821,22 +1114,467 @@ 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;
+      let observationTurnId;
+      try {
+        invocation = parseAgentOperationInvocation(operationInput.invocation);
+        observationTurnId = parseAgentTurnId(
+          operationInput.observationTurnId
+        );
+      } 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
+      };
+      const observationState = {
+        fileChangeMode: capabilities.output.fileChanges,
+        observedItems: /* @__PURE__ */ new Map(),
+        proposedPlans: /* @__PURE__ */ new Map(),
+        generatedResourceIds: /* @__PURE__ */ new Set(),
+        started: true,
+        terminal: false,
+        waiting: false,
+        finalDiffObserved: false
+      };
+      interactionState.operationInvocations.set(
+        invocation.invocationId,
+        trackedInvocation
+      );
+      try {
+        const result = await delegateProviderMutation({
+          operation: "invoke_operation",
+          observer: operationInput.onProviderExecutionStarted,
+          invoke: (onProviderExecutionStarted, onOutput) => declaredOperations.invokeOperation({
+            invocation,
+            observationTurnId,
+            onProviderExecutionStarted,
+            onOutput,
+            ...operationInput.signal === void 0 ? {} : { signal: operationInput.signal }
+          }),
+          observeOutput: async (candidate) => {
+            const output = validateAgentProviderOutputForContext(
+              candidate,
+              {
+                ...outputContext(observationTurnId),
+                operationInvocationId: invocation.invocationId
+              }
+            );
+            observeSessionOperationOutput({
+              capabilities,
+              providerKey,
+              output,
+              state: observationState,
+              contextUsageState,
+              interactionState
+            });
+            await operationInput.onOutput?.(output);
+          },
+          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) => {
@@ -868,6 +1606,11 @@ function validateAgentProviderSession(input) {
     interruption,
     steering,
     configuration,
+    operations,
+    managedContent,
+    integrations,
+    collaboration,
+    generatedResources,
     close
   });
 }