@agen-ai/agent-runtime 0.3.0 → 0.4.0

package/dist/sessions.d.ts

@@ -1,5 +1,6 @@
 import type { AgentAuthenticationFlow, AgentCollaborationControlInput, AgentCollaborationNode, AgentCollaborationSpawnInput, AgentConfigurationCatalog, AgentConfigurationSelectionInput, AgentError, AgentGeneratedResourceDescriptor, AgentGeneratedResourceId, AgentManagedContentCatalog, AgentOperationCatalog, AgentOperationInvocation, AgentOperationResult, AgentRequestResolution, AgentSessionBinding, AgentSessionBranchSource, AgentSessionConfiguration, AgentSessionId, AgentTurnId, AgentTurnInputContent, AgentTurnInteractionMode, AgentTurnInputPart, AgentTurnInterruptionReason } from "@agen-ai/agent-protocol";
 import type { MaybePromise } from "./foundation.js";
+import type { AgentSessionHostBinding, AgentSessionHostBindingSupport } from "./hostBindings/types.js";
 import type { AgentProviderOutput } from "./outputs.js";
 import type { AgentArtifactCandidate } from "./artifacts.js";
 import type { AgentEnvironmentObservationPort } from "./environment/types.js";
@@ -8,6 +9,7 @@ export interface AgentProviderSessionContext {
     readonly workingDirectory: string;
     readonly configuration: AgentSessionConfiguration;
     readonly signal?: AbortSignal;
+    readonly hostBinding?: AgentSessionHostBinding;
 }
 export type AgentSessionBindingCreatedObserver = (binding: AgentSessionBinding) => void;
 export interface AgentProviderCreateSessionInput extends AgentProviderSessionContext {
@@ -22,7 +24,7 @@ export interface AgentProviderBranchSessionInput extends AgentProviderSessionCon
 }
 export type AgentProviderExecutionStartedObserver = () => void;
 export type AgentProviderOutputObserver = (output: AgentProviderOutput) => MaybePromise<void>;
-export interface AgentProviderRunTurnInput {
+export interface AgentProviderStartTurnInput {
     readonly turnId: AgentTurnId;
     readonly interactionMode: AgentTurnInteractionMode;
     readonly parts: readonly AgentTurnInputPart[];
@@ -34,6 +36,23 @@ export interface AgentProviderRunTurnInput {
 export interface AgentProviderResolveRequestInput {
     readonly resolution: AgentRequestResolution;
     readonly signal?: AbortSignal;
+    readonly onProviderExecutionStarted?: AgentProviderExecutionStartedObserver;
+}
+/** Acceptance of the canonical answer or step, not model consumption or turn completion. */
+export type AgentRequestResolutionResult = Readonly<{
+    status: "delivered";
+}> | Readonly<{
+    status: "rejected";
+    requestState: "pending" | "unavailable";
+    error: AgentError;
+}> | Readonly<{
+    status: "delivery_uncertain";
+    error: AgentError;
+}>;
+export interface AgentProviderTurnExecution {
+    readonly turnId: AgentTurnId;
+    readonly outputs: AsyncIterable<AgentProviderOutput>;
+    readonly resolveRequest: (input: AgentProviderResolveRequestInput) => Promise<AgentRequestResolutionResult>;
 }
 export interface AgentProviderInterruptTurnInput {
     readonly turnId: AgentTurnId;
@@ -89,6 +108,11 @@ export interface AgentProviderOperationResult {
     readonly outputs?: readonly AgentProviderOutput[];
     readonly error?: AgentError;
 }
+export interface AgentProviderTurnInterruptionResult {
+    readonly status: AgentProviderOperationStatus;
+    readonly error?: AgentError;
+    readonly outputs?: never;
+}
 export type AgentTurnSteeringResult = Readonly<{
     status: "delivered";
 }> | Readonly<{
@@ -102,7 +126,7 @@ export type AgentTurnInterruption = Readonly<{
     kind: "unsupported";
 }> | Readonly<{
     kind: "supported";
-    interruptTurn: (input: AgentProviderInterruptTurnInput) => MaybePromise<AgentProviderOperationResult>;
+    interruptTurn: (input: AgentProviderInterruptTurnInput) => MaybePromise<AgentProviderTurnInterruptionResult>;
 }>;
 export type AgentTurnSteering = Readonly<{
     kind: "unsupported";
@@ -145,8 +169,7 @@ export type AgentGeneratedResourceAccess = Readonly<{
 }>;
 export interface AgentProviderSession {
     readonly binding: AgentSessionBinding;
-    readonly runTurn: (input: AgentProviderRunTurnInput) => AsyncIterable<AgentProviderOutput>;
-    readonly resolveRequest: (input: AgentProviderResolveRequestInput) => AsyncIterable<AgentProviderOutput>;
+    readonly startTurn: (input: AgentProviderStartTurnInput) => AgentProviderTurnExecution;
     readonly interruption: AgentTurnInterruption;
     readonly steering: AgentTurnSteering;
     readonly configuration: AgentSessionConfigurationControl;
@@ -189,6 +212,7 @@ export type AgentProviderAuthentication = Readonly<{
     cancel: (input: AgentProviderAuthenticationCancelInput) => MaybePromise<AgentProviderOperationResult>;
 }>;
 export interface AgentProviderAdapter {
+    readonly hostBinding?: AgentSessionHostBindingSupport;
     readonly createSession: (input: AgentProviderCreateSessionInput) => MaybePromise<AgentProviderSession>;
     readonly resumption: AgentSessionResumption;
     readonly branching: AgentSessionBranching;

package/dist/testing/conformance.d.ts

@@ -1,6 +1,6 @@
 import { type AgentCollaborationSpawnInput, type AgentConfigurationSelectionInput, type AgentEnvironmentId, type AgentGeneratedResourceId, type AgentOperationInvocation, type AgentRequest, type AgentRequestResolution, type AgentSessionBinding, type AgentSessionBranchSource, type AgentSessionConfiguration, type AgentSessionId, type AgentTurnId, type AgentTurnInputContent } from "@agen-ai/agent-protocol";
 import type { AgentProviderDriver, AgentProviderInstanceDefinition } from "../providerDriver.js";
-import type { AgentProviderRunTurnInput } from "../sessions.js";
+import type { AgentProviderStartTurnInput } from "../sessions.js";
 export interface AgentProviderConformanceScenario {
     readonly driver: AgentProviderDriver;
     readonly definition: AgentProviderInstanceDefinition;
@@ -16,8 +16,8 @@ export interface AgentProviderConformanceScenario {
     readonly branchSessionId?: AgentSessionId;
     readonly abortedSessionId: AgentSessionId;
     readonly interruptionSessionId: AgentSessionId;
-    readonly turn: AgentProviderRunTurnInput;
-    readonly interruptionTurn: AgentProviderRunTurnInput;
+    readonly turn: AgentProviderStartTurnInput;
+    readonly interruptionTurn: AgentProviderStartTurnInput;
     readonly resolutionFor: (request: AgentRequest) => AgentRequestResolution;
     readonly branchSource?: (binding: AgentSessionBinding, turnId: AgentTurnId) => AgentSessionBranchSource;
     readonly steeringInput?: AgentTurnInputContent;

package/dist/testing/conformance.js

@@ -38,7 +38,8 @@ async function checkEnvironmentWatch(input) {
   }
 }
 async function advanceToStartedTurn(session, input) {
-  const iterator = session.runTurn(input)[Symbol.asyncIterator]();
+  const execution = session.startTurn(input);
+  const iterator = execution.outputs[Symbol.asyncIterator]();
   const outputs = [];
   try {
     for (; ; ) {
@@ -50,7 +51,7 @@ async function advanceToStartedTurn(session, input) {
       );
       outputs.push(next.value);
       if (next.value.kind === "event" && next.value.event.type === "turn.started") {
-        return { iterator, outputs };
+        return { execution, iterator, outputs };
       }
     }
   } catch (error) {
@@ -58,18 +59,18 @@ async function advanceToStartedTurn(session, input) {
     throw error;
   }
 }
-async function collectRemainingOutputs(started) {
+async function collectRemainingOutputs(started, resolutionFor) {
   for (; ; ) {
     const next = await started.iterator.next();
     if (next.done) return started.outputs;
     started.outputs.push(next.value);
+    if (next.value.kind === "event" && next.value.event.type === "request.opened" && resolutionFor) {
+      const request = next.value.event.payload.request;
+      const receipt = await started.execution.resolveRequest({ resolution: parseAgentRequestResolutionFor(request, resolutionFor(request)) });
+      requireCheck(receipt.status === "delivered", "request_resolution", "Matching request answer was not accepted by the provider handler.");
+    }
   }
 }
-async function collectOutputs(outputs) {
-  const collected = [];
-  for await (const output of outputs) collected.push(output);
-  return collected;
-}
 function requireOperationStatus(result, statuses, check, message) {
   requireCheck(statuses.includes(result.status), check, message);
 }
@@ -78,6 +79,12 @@ function semanticEvents(outputs) {
     (output) => output.kind === "event" ? [output.event] : []
   );
 }
+function hasStableTurnBoundary(events) {
+  const boundary = events.findLast(
+    (event) => event.type === "turn.completed" || event.type === "turn.state_changed"
+  );
+  return boundary?.type === "turn.completed" || boundary?.type === "turn.state_changed" && boundary.payload.state === "waiting_for_request";
+}
 async function runAgentProviderConformance(scenario) {
   const checks = [];
   try {
@@ -299,7 +306,7 @@ async function runAgentProviderConformance(scenario) {
           "Unsupported steering exposed a handler."
         );
       }
-      turnOutputs = await collectRemainingOutputs(startedTurn);
+      turnOutputs = await collectRemainingOutputs(startedTurn, scenario.resolutionFor);
     } catch (error) {
       await startedTurn.iterator.return?.();
       await created.close({ reason: "contract_rejected" });
@@ -311,32 +318,13 @@ async function runAgentProviderConformance(scenario) {
       "turn_order",
       "Turn did not start first."
     );
-    const lastEvent = events.at(-1);
     requireCheck(
-      lastEvent?.type === "turn.completed" || lastEvent?.type === "turn.state_changed" && lastEvent.payload.state === "waiting_for_request",
+      hasStableTurnBoundary(events),
       "turn_order",
       "Turn did not terminate or enter a waiting state."
     );
     checks.push("turn_order");
-    const openedRequest = events.find(
-      (event) => event.type === "request.opened"
-    );
-    if (openedRequest?.type === "request.opened") {
-      const resolution = parseAgentRequestResolutionFor(
-        openedRequest.payload.request,
-        scenario.resolutionFor(openedRequest.payload.request)
-      );
-      const resolutionOutputs = await collectOutputs(
-        created.resolveRequest({ resolution })
-      );
-      const resolutionBoundary = semanticEvents(resolutionOutputs).at(-1);
-      requireCheck(
-        resolutionBoundary?.type === "turn.completed" || resolutionBoundary?.type === "turn.state_changed" && resolutionBoundary.payload.state === "waiting_for_request",
-        "request_resolution",
-        "Matching request resolution did not reach a stable turn boundary."
-      );
-      checks.push("request_resolution");
-    }
+    if (events.some((event) => event.type === "request.opened")) checks.push("request_resolution");
     checks.push("steering");
     if (instance.capabilities.turns.interrupt) {
       let interruptedBindingCount = 0;
@@ -375,6 +363,12 @@ async function runAgentProviderConformance(scenario) {
           "interruption",
           "Live turn interruption did not succeed."
         );
+        const outputs = await collectRemainingOutputs(liveTurn);
+        requireCheck(
+          semanticEvents(outputs).some((event) => event.type === "turn.completed"),
+          "interruption",
+          "Interrupted turn did not produce native terminal output."
+        );
       } finally {
         await liveTurn?.iterator.return?.();
         await interrupted.close({ reason: "other" });

package/dist/testing/fakeProvider.js

@@ -44,7 +44,7 @@ function defaultCapabilities(providerKey) {
     }
   };
   return parseAgentCapabilities({
-    protocolVersion: 9,
+    protocolVersion: 10,
     providerKey,
     sessions: { create: true, resume: true, branch: { kind: "through_turn" } },
     turns: {
@@ -165,7 +165,7 @@ function sessionBinding(state, sessionId) {
   };
 }
 function eventBase(sessionId, turnId, occurredAt) {
-  return { protocolVersion: 9, sessionId, turnId, occurredAt };
+  return { protocolVersion: 10, sessionId, turnId, occurredAt };
 }
 function fakeEnvironmentSnapshot(environmentId) {
   return parseAgentEnvironmentSnapshot({
@@ -280,7 +280,8 @@ function fakeSession(input) {
     );
   };
   let closed = false;
-  const runTurn = async function* (turnInput) {
+  const interruptedTurns = /* @__PURE__ */ new Set();
+  const outputTurn = async function* (turnInput) {
     throwIfAgentOperationAborted(turnInput.signal);
     input.state.turnIds.push(turnInput.turnId);
     const occurredAt = input.now();
@@ -289,6 +290,14 @@ function fakeSession(input) {
       type: "turn.started",
       payload: { message: "Fake provider turn started." }
     });
+    if (interruptedTurns.has(turnInput.turnId)) {
+      yield createAgentEventOutput({
+        ...eventBase(input.context.sessionId, turnInput.turnId, input.now()),
+        type: "turn.completed",
+        payload: { outcome: "canceled", reason: "Fake provider interrupted." }
+      });
+      return;
+    }
     yield createAgentEventOutput({
       ...eventBase(input.context.sessionId, turnInput.turnId, occurredAt),
       type: "item.started",
@@ -311,10 +320,13 @@ function fakeSession(input) {
     }
     if (input.capabilities.requests.approval.kind === "supported") {
       const request = requestForTurn(turnInput.turnId);
-      pendingRequests.set(request.requestId, {
-        request,
-        turnId: turnInput.turnId
+      let release;
+      const answered = new Promise((resolve) => {
+        release = resolve;
       });
+      pendingRequests.set(request.requestId, { request, turnId: turnInput.turnId, release });
+      const aborted = () => release();
+      turnInput.signal?.addEventListener("abort", aborted, { once: true });
       yield createAgentEventOutput({
         ...eventBase(input.context.sessionId, turnInput.turnId, occurredAt),
         type: "request.opened",
@@ -325,17 +337,30 @@ function fakeSession(input) {
         type: "turn.state_changed",
         payload: { state: "waiting_for_request", requestId: request.requestId }
       });
-      return;
+      try {
+        if (!turnInput.signal?.aborted) await answered;
+        throwIfAgentOperationAborted(turnInput.signal);
+        if (closed) return;
+      } finally {
+        turnInput.signal?.removeEventListener("abort", aborted);
+        pendingRequests.delete(request.requestId);
+      }
+      yield createAgentEventOutput({
+        ...eventBase(input.context.sessionId, turnInput.turnId, input.now()),
+        type: "turn.state_changed",
+        payload: { state: "running" }
+      });
     }
     yield createAgentEventOutput({
       ...eventBase(input.context.sessionId, turnInput.turnId, occurredAt),
       type: "turn.completed",
-      payload: { outcome: "completed", reason: "Fake provider completed." }
+      payload: { outcome: interruptedTurns.has(turnInput.turnId) ? "canceled" : "completed", reason: "Fake provider completed." }
     });
   };
   const close = async () => {
     if (closed) return;
     closed = true;
+    for (const pending of pendingRequests.values()) pending.release();
     input.state.closeCounts.set(
       input.context.sessionId,
       (input.state.closeCounts.get(input.context.sessionId) ?? 0) + 1
@@ -343,49 +368,35 @@ function fakeSession(input) {
   };
   return {
     binding: input.binding,
-    runTurn,
-    resolveRequest: async function* (requestInput) {
-      throwIfAgentOperationAborted(requestInput.signal);
-      const pending = pendingRequests.get(requestInput.resolution.requestId);
-      if (!pending)
-        throw new TypeError("Fake provider has no matching pending request.");
-      const resolution = parseAgentRequestResolutionFor(
-        pending.request,
-        requestInput.resolution
-      );
-      input.state.resolutions.push(resolution);
-      pendingRequests.delete(resolution.requestId);
-      const occurredAt = input.now();
-      yield createAgentEventOutput({
-        ...eventBase(input.context.sessionId, pending.turnId, occurredAt),
-        type: "turn.state_changed",
-        payload: { state: "running" }
-      });
-      yield createAgentEventOutput({
-        ...eventBase(input.context.sessionId, pending.turnId, occurredAt),
-        type: "turn.completed",
-        payload: { outcome: "completed", reason: "Fake request resolved." }
-      });
+    startTurn(turnInput) {
+      return {
+        turnId: turnInput.turnId,
+        outputs: outputTurn(turnInput),
+        async resolveRequest(requestInput) {
+          throwIfAgentOperationAborted(requestInput.signal);
+          const pending = pendingRequests.get(requestInput.resolution.requestId);
+          if (!pending || pending.turnId !== turnInput.turnId) throw new TypeError("Fake provider has no matching pending request.");
+          const resolution = parseAgentRequestResolutionFor(pending.request, requestInput.resolution);
+          input.state.resolutions.push(resolution);
+          pendingRequests.delete(resolution.requestId);
+          pending.release();
+          return { status: "delivered" };
+        }
+      };
     },
     interruption: input.capabilities.turns.interrupt ? {
       kind: "supported",
       interruptTurn: async (interruptionInput) => {
         throwIfAgentOperationAborted(interruptionInput.signal);
         input.state.interruptedTurnIds.push(interruptionInput.turnId);
-        return completedResult([
-          createAgentEventOutput({
-            ...eventBase(
-              input.context.sessionId,
-              interruptionInput.turnId,
-              input.now()
-            ),
-            type: "turn.completed",
-            payload: {
-              outcome: "canceled",
-              reason: interruptionInput.reason
-            }
-          })
-        ]);
+        interruptedTurns.add(interruptionInput.turnId);
+        for (const [requestId, pending] of pendingRequests) {
+          if (pending.turnId === interruptionInput.turnId) {
+            pendingRequests.delete(requestId);
+            pending.release();
+          }
+        }
+        return { status: "accepted" };
       }
     } : { kind: "unsupported" },
     steering: input.capabilities.turns.steer.kind === "supported" ? {

package/dist/turnExecution/execution.d.ts

@@ -0,0 +1,26 @@
+import { type AgentProviderKey } from "@agen-ai/agent-protocol";
+import type { AgentProviderOutput } from "../outputs.js";
+import type { AgentProviderStartTurnInput, AgentProviderTurnExecution } from "../sessions.js";
+import { type PendingAgentRequest, type SuspendedAgentTurnRequests } from "./requests.js";
+export interface ValidatedAgentTurnExecution {
+    readonly execution: AgentProviderTurnExecution;
+    readonly hasEntered: () => boolean;
+    readonly stop: (reason: Error) => void;
+    readonly join: () => Promise<void>;
+    readonly suspendRequests: () => SuspendedAgentTurnRequests;
+}
+export declare function createValidatedAgentTurnExecution(input: Readonly<{
+    providerKey: AgentProviderKey;
+    turnInput: AgentProviderStartTurnInput;
+    pendingRequests: Map<string, PendingAgentRequest>;
+    inFlightOperations: Set<Promise<void>>;
+    start: (input: AgentProviderStartTurnInput) => AgentProviderTurnExecution;
+    requireUsable: () => void;
+    isTerminal: () => boolean;
+    observe: (output: AgentProviderOutput) => AgentProviderOutput;
+    assertCompleted: () => void;
+    release: () => void;
+    retire: () => void;
+    abandon: () => Promise<void>;
+}>): ValidatedAgentTurnExecution;
+//# sourceMappingURL=execution.d.ts.map

package/dist/turnExecution/execution.js

@@ -0,0 +1,214 @@
+import {
+  parseAgentRequestResolution,
+  parseAgentRequestResolutionFor
+} from "@agen-ai/agent-protocol";
+import { AgentProviderDelegatedOperationError, throwAgentProviderContractError } from "../contractErrors.js";
+import { throwIfAgentOperationAborted } from "../foundation.js";
+import { hasExactOwnKeys } from "../internal/objectShape.js";
+import { validateAgentRequestResolutionResult } from "./receipts.js";
+import { createAgentTurnRequestAdmission } from "./requests.js";
+function createValidatedAgentTurnExecution(input) {
+  let state = { kind: "reserved" };
+  let source;
+  const requests = createAgentTurnRequestAdmission({
+    pendingRequests: input.pendingRequests,
+    canRestore: () => state.kind === "entered" && !input.isTerminal()
+  });
+  let acquired = false;
+  let pulling = false;
+  let returnPromise;
+  const lifetime = new AbortController();
+  const nativeOperations = /* @__PURE__ */ new Set();
+  const fail = (code, message) => throwAgentProviderContractError(input.providerKey, code, message);
+  const abortError = () => {
+    try {
+      throwIfAgentOperationAborted(lifetime.signal);
+    } catch (error) {
+      if (error instanceof Error) return error;
+    }
+    return new DOMException("The turn execution was stopped.", "AbortError");
+  };
+  const detachAbort = () => input.turnInput.signal?.removeEventListener("abort", abort);
+  const stop = (reason) => {
+    if (state.kind === "settled" || state.kind === "stopped") return;
+    const entered = state.kind === "entered" || state.kind === "entering";
+    state = { kind: "stopped", reason };
+    requests.withdraw();
+    lifetime.abort(reason);
+    detachAbort();
+    if (entered) input.retire();
+    else input.release();
+  };
+  const abort = () => {
+    let reason = new DOMException("The turn execution was aborted.", "AbortError");
+    try {
+      throwIfAgentOperationAborted(input.turnInput.signal);
+    } catch (error) {
+      if (error instanceof Error) reason = error;
+    }
+    stop(reason);
+  };
+  input.turnInput.signal?.addEventListener("abort", abort, { once: true });
+  const track = (operation) => {
+    nativeOperations.add(operation);
+    void operation.then(() => nativeOperations.delete(operation), () => nativeOperations.delete(operation));
+    return operation;
+  };
+  const join = async () => {
+    while (nativeOperations.size > 0 || input.inFlightOperations.size > 0) {
+      await Promise.allSettled([...nativeOperations, ...input.inFlightOperations]);
+    }
+    if (source?.return) await source.return();
+  };
+  const requireAnswerable = () => {
+    input.requireUsable();
+    if (state.kind !== "entered" || input.isTerminal()) {
+      fail("request_resolution_mismatch", "Request no longer belongs to an answerable turn execution.");
+    }
+  };
+  const resolveRequest = async (requestInput) => {
+    requireAnswerable();
+    throwIfAgentOperationAborted(requestInput.signal);
+    const resolution = parseAgentRequestResolution(requestInput.resolution);
+    const pending = input.pendingRequests.get(resolution.requestId);
+    if (!pending || pending.turnId !== input.turnInput.turnId) {
+      return fail("request_resolution_mismatch", "Resolution does not identify an answerable request in this execution.");
+    }
+    try {
+      parseAgentRequestResolutionFor(pending.request, resolution);
+    } catch {
+      return fail("request_resolution_mismatch", "Resolution does not match the opened request.");
+    }
+    if (pending.request.expiresAt !== void 0 && Date.parse(pending.request.expiresAt) <= Date.now() && resolution.disposition !== "canceled") {
+      return fail("request_resolution_mismatch", "Resolution identifies an expired request.");
+    }
+    if (state.kind !== "entered") return fail("request_resolution_mismatch", "Turn execution is no longer live.");
+    const candidate = state.candidate;
+    const restore = requests.claim(resolution.requestId, pending);
+    let settle;
+    const settlement = new Promise((resolve) => {
+      settle = resolve;
+    });
+    input.inFlightOperations.add(settlement);
+    try {
+      try {
+        requestInput.onProviderExecutionStarted?.();
+        throwIfAgentOperationAborted(requestInput.signal);
+        throwIfAgentOperationAborted(lifetime.signal);
+        requireAnswerable();
+      } catch (error) {
+        restore();
+        throw error;
+      }
+      let result;
+      try {
+        const signal = requestInput.signal === void 0 ? lifetime.signal : AbortSignal.any([lifetime.signal, requestInput.signal]);
+        result = validateAgentRequestResolutionResult(await candidate.resolveRequest({ resolution, signal }), input.providerKey);
+      } catch (error) {
+        input.retire();
+        throw new AgentProviderDelegatedOperationError(input.providerKey, "resolve_request", error);
+      }
+      if (result.status === "rejected" && result.requestState === "pending") restore();
+      if (result.status === "delivery_uncertain") input.retire();
+      return result;
+    } finally {
+      input.inFlightOperations.delete(settlement);
+      settle();
+    }
+  };
+  const next = async () => {
+    if (state.kind === "stopped") throw state.reason;
+    if (state.kind === "settled") return { done: true, value: void 0 };
+    if (pulling) return fail("concurrent_turn", "Turn output permits only one outstanding pull.");
+    pulling = true;
+    let removeAbort = () => {
+    };
+    try {
+      if (state.kind === "reserved") input.requireUsable();
+      throwIfAgentOperationAborted(lifetime.signal);
+      if (state.kind === "reserved") {
+        try {
+          input.turnInput.onProviderExecutionStarted?.();
+        } catch (error) {
+          state = { kind: "settled" };
+          detachAbort();
+          input.release();
+          throw error;
+        }
+        throwIfAgentOperationAborted(lifetime.signal);
+        input.requireUsable();
+        const { onProviderExecutionStarted: _observer, ...turnInput } = input.turnInput;
+        state = { kind: "entering" };
+        try {
+          const candidate = input.start({ ...turnInput, signal: lifetime.signal });
+          if (candidate === null || typeof candidate !== "object" || candidate.turnId !== turnInput.turnId || !hasExactOwnKeys(candidate, ["turnId", "outputs", "resolveRequest"]) || typeof candidate.resolveRequest !== "function" || !candidate.outputs || typeof candidate.outputs[Symbol.asyncIterator] !== "function") {
+            return fail("invalid_operation_result", "Provider returned an invalid turn execution.");
+          }
+          source = candidate.outputs[Symbol.asyncIterator]();
+          throwIfAgentOperationAborted(lifetime.signal);
+          state = { kind: "entered", candidate, iterator: source };
+        } catch (error) {
+          stop(error instanceof Error ? error : new Error("Provider turn entry failed.", { cause: error }));
+          throw error;
+        }
+      }
+      if (state.kind !== "entered") throw abortError();
+      const nativePull = track(Promise.resolve().then(() => state.kind === "entered" ? state.iterator.next() : Promise.reject(abortError())));
+      const stopped = new Promise((_, reject) => {
+        const onAbort = () => reject(abortError());
+        lifetime.signal.addEventListener("abort", onAbort, { once: true });
+        removeAbort = () => lifetime.signal.removeEventListener("abort", onAbort);
+      });
+      const result = await Promise.race([nativePull, stopped]);
+      throwIfAgentOperationAborted(lifetime.signal);
+      if (!result.done) {
+        const output = input.observe(result.value);
+        if (output.kind === "event" && output.event.type === "request.opened") requests.observeRequest();
+        return { done: false, value: output };
+      }
+      while (input.inFlightOperations.size > 0) {
+        await Promise.race([Promise.all(input.inFlightOperations), stopped]);
+      }
+      throwIfAgentOperationAborted(lifetime.signal);
+      input.assertCompleted();
+      state = { kind: "settled" };
+      detachAbort();
+      input.release();
+      return { done: true, value: void 0 };
+    } catch (error) {
+      if (state.kind === "entered" || state.kind === "entering") stop(error instanceof Error ? error : new Error("Provider output failed.", { cause: error }));
+      throw error;
+    } finally {
+      removeAbort();
+      pulling = false;
+    }
+  };
+  const iterator = {
+    next,
+    return() {
+      if (returnPromise) return returnPromise;
+      if (state.kind === "settled") return Promise.resolve({ done: true, value: void 0 });
+      const entered = state.kind === "entered" || source !== void 0;
+      stop(new DOMException("The turn output consumer returned.", "AbortError"));
+      returnPromise = (entered ? input.abandon() : Promise.resolve()).then(() => ({ done: true, value: void 0 }));
+      return returnPromise;
+    }
+  };
+  const outputs = Object.freeze({
+    [Symbol.asyncIterator]() {
+      if (acquired) return fail("concurrent_turn", "Turn output has exactly one consumer.");
+      acquired = true;
+      return iterator;
+    }
+  });
+  return {
+    execution: Object.freeze({ turnId: input.turnInput.turnId, outputs, resolveRequest }),
+    hasEntered: () => state.kind === "entering" || state.kind === "entered",
+    stop,
+    join,
+    suspendRequests: requests.suspend
+  };
+}
+export {
+  createValidatedAgentTurnExecution
+};

package/dist/turnExecution/receipts.d.ts

@@ -0,0 +1,6 @@
+import { type AgentProviderKey } from "@agen-ai/agent-protocol";
+import { type AgentProviderOutputValidationContext } from "../outputValidation.js";
+import type { AgentProviderTurnInterruptionResult, AgentRequestResolutionResult } from "../sessions.js";
+export declare function validateAgentProviderTurnInterruptionResult(candidate: AgentProviderTurnInterruptionResult, context: AgentProviderOutputValidationContext): AgentProviderTurnInterruptionResult;
+export declare function validateAgentRequestResolutionResult(candidate: unknown, providerKey: AgentProviderKey): AgentRequestResolutionResult;
+//# sourceMappingURL=receipts.d.ts.map

package/dist/turnExecution/receipts.js

@@ -0,0 +1,39 @@
+import { parseAgentError } from "@agen-ai/agent-protocol";
+import { throwAgentProviderContractError } from "../contractErrors.js";
+import { hasExactOwnKeys } from "../internal/objectShape.js";
+import { validateAgentProviderOperationResult } from "../outputValidation.js";
+function validateAgentProviderTurnInterruptionResult(candidate, context) {
+  if (candidate === null || typeof candidate !== "object" || !hasExactOwnKeys(candidate, candidate.status === "failed" ? ["status", "error"] : ["status"])) {
+    return throwAgentProviderContractError(
+      context.providerKey,
+      "invalid_operation_result",
+      "Provider interruption must return an output-free operation receipt."
+    );
+  }
+  const result = validateAgentProviderOperationResult(candidate, context);
+  return Object.freeze({ status: result.status, ...result.error === void 0 ? {} : { error: result.error } });
+}
+function validateAgentRequestResolutionResult(candidate, providerKey) {
+  const invalid = () => throwAgentProviderContractError(
+    providerKey,
+    "invalid_operation_result",
+    "Provider returned an invalid request delivery receipt."
+  );
+  if (candidate === null || typeof candidate !== "object" || !("status" in candidate)) return invalid();
+  if (candidate.status === "delivered" && hasExactOwnKeys(candidate, ["status"])) {
+    return Object.freeze({ status: "delivered" });
+  }
+  if (!("error" in candidate)) return invalid();
+  const error = parseAgentError(candidate.error);
+  if (candidate.status === "delivery_uncertain" && hasExactOwnKeys(candidate, ["status", "error"])) {
+    return Object.freeze({ status: "delivery_uncertain", error });
+  }
+  if (candidate.status === "rejected" && hasExactOwnKeys(candidate, ["status", "requestState", "error"]) && "requestState" in candidate && (candidate.requestState === "pending" || candidate.requestState === "unavailable")) {
+    return Object.freeze({ status: "rejected", requestState: candidate.requestState, error });
+  }
+  return invalid();
+}
+export {
+  validateAgentProviderTurnInterruptionResult,
+  validateAgentRequestResolutionResult
+};