@agen-ai/agent-runtime 0.4.0 → 0.4.2

package/dist/turnExecution/execution.js

@@ -2,22 +2,68 @@ import {
   parseAgentRequestResolution,
   parseAgentRequestResolutionFor
 } from "@agen-ai/agent-protocol";
-import { AgentProviderDelegatedOperationError, throwAgentProviderContractError } from "../contractErrors.js";
+import { AgentProviderContractError, 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" };
+  return createExecution(input, { kind: "caller", input: input.turnInput, start: input.start });
+}
+function adoptValidatedAgentTurnExecution(input) {
+  return createExecution(input, { kind: "native", turnId: input.turnId, createCandidate: input.createCandidate });
+}
+function createExecution(input, origin) {
+  const turnId = origin.kind === "caller" ? origin.input.turnId : origin.turnId;
+  const callerSignal = origin.kind === "caller" ? origin.input.signal : void 0;
+  const lifetime = new AbortController();
+  const validateCandidate = (candidate) => {
+    if (candidate === null || typeof candidate !== "object" || candidate.turnId !== turnId || !hasExactOwnKeys(candidate, ["turnId", "outputs", "resolveRequest"]) || typeof candidate.resolveRequest !== "function" || !candidate.outputs || typeof candidate.outputs[Symbol.asyncIterator] !== "function") {
+      throwAgentProviderContractError(
+        input.providerKey,
+        origin.kind === "native" ? "invalid_native_continuation" : "invalid_operation_result",
+        "Provider returned an invalid turn execution."
+      );
+    }
+    return candidate;
+  };
+  let state;
+  try {
+    state = origin.kind === "native" ? { kind: "parked", candidate: validateCandidate(origin.createCandidate(lifetime.signal)) } : { kind: "reserved" };
+  } catch (cause) {
+    lifetime.abort(cause);
+    throw cause;
+  }
+  let ready;
+  const readerReady = new Promise((resolve) => {
+    ready = resolve;
+  });
+  let allowDispatch;
+  const dispatch = new Promise((resolve) => {
+    allowDispatch = resolve;
+  });
+  let complete;
+  const completed = new Promise((resolve) => {
+    complete = resolve;
+  });
+  const currentState = () => state;
+  let dispatched = false;
+  let observedOutput = false;
+  let resolveDisposition;
+  const disposition = new Promise((resolve) => {
+    resolveDisposition = resolve;
+  });
   let source;
   const requests = createAgentTurnRequestAdmission({
+    providerKey: input.providerKey,
+    sessionAdmission: input.sessionAdmission,
     pendingRequests: input.pendingRequests,
-    canRestore: () => state.kind === "entered" && !input.isTerminal()
+    canRestore: () => state.kind === "entered" && !input.isTerminal(),
+    canRestoreRequest: input.canRestoreRequest
   });
   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 = () => {
@@ -28,37 +74,51 @@ function createValidatedAgentTurnExecution(input) {
     }
     return new DOMException("The turn execution was stopped.", "AbortError");
   };
-  const detachAbort = () => input.turnInput.signal?.removeEventListener("abort", abort);
+  const detachAbort = () => callerSignal?.removeEventListener("abort", abort);
   const stop = (reason) => {
     if (state.kind === "settled" || state.kind === "stopped") return;
-    const entered = state.kind === "entered" || state.kind === "entering";
+    const entered = dispatched || state.kind === "entered" || state.kind === "entering";
     state = { kind: "stopped", reason };
     requests.withdraw();
     lifetime.abort(reason);
     detachAbort();
     if (entered) input.retire();
-    else input.release();
+    else if (origin.kind === "caller") {
+      input.release();
+      complete();
+    }
+    allowDispatch();
+    complete();
   };
   const abort = () => {
     let reason = new DOMException("The turn execution was aborted.", "AbortError");
     try {
-      throwIfAgentOperationAborted(input.turnInput.signal);
+      throwIfAgentOperationAborted(callerSignal);
     } catch (error) {
       if (error instanceof Error) reason = error;
     }
     stop(reason);
   };
-  input.turnInput.signal?.addEventListener("abort", abort, { once: true });
+  callerSignal?.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();
+  let joinPromise;
+  const join = () => {
+    if (joinPromise) return joinPromise;
+    const attempt = (async () => {
+      while (nativeOperations.size > 0 || input.inFlightOperations.size > 0) {
+        await Promise.allSettled([...nativeOperations, ...input.inFlightOperations]);
+      }
+      if (source?.return) await source.return();
+    })();
+    joinPromise = attempt;
+    void attempt.catch(() => {
+      if (joinPromise === attempt) joinPromise = void 0;
+    });
+    return attempt;
   };
   const requireAnswerable = () => {
     input.requireUsable();
@@ -71,7 +131,7 @@ function createValidatedAgentTurnExecution(input) {
     throwIfAgentOperationAborted(requestInput.signal);
     const resolution = parseAgentRequestResolution(requestInput.resolution);
     const pending = input.pendingRequests.get(resolution.requestId);
-    if (!pending || pending.turnId !== input.turnInput.turnId) {
+    if (!pending || pending.turnId !== turnId) {
       return fail("request_resolution_mismatch", "Resolution does not identify an answerable request in this execution.");
     }
     try {
@@ -84,7 +144,7 @@ function createValidatedAgentTurnExecution(input) {
     }
     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);
+    const attempt = requests.claim(resolution.requestId, pending);
     let settle;
     const settlement = new Promise((resolve) => {
       settle = resolve;
@@ -97,7 +157,7 @@ function createValidatedAgentTurnExecution(input) {
         throwIfAgentOperationAborted(lifetime.signal);
         requireAnswerable();
       } catch (error) {
-        restore();
+        attempt.restore();
         throw error;
       }
       let result;
@@ -105,10 +165,12 @@ function createValidatedAgentTurnExecution(input) {
         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) {
+        attempt.retire();
         input.retire();
         throw new AgentProviderDelegatedOperationError(input.providerKey, "resolve_request", error);
       }
-      if (result.status === "rejected" && result.requestState === "pending") restore();
+      if (result.status === "rejected" && result.requestState === "pending") attempt.restore();
+      else attempt.retire();
       if (result.status === "delivery_uncertain") input.retire();
       return result;
     } finally {
@@ -124,26 +186,35 @@ function createValidatedAgentTurnExecution(input) {
     let removeAbort = () => {
     };
     try {
+      if (state.kind === "parked") {
+        ready();
+        await dispatch;
+        if (currentState().kind === "settled") return { done: true, value: void 0 };
+        throwIfAgentOperationAborted(lifetime.signal);
+        if (state.kind !== "parked") throw abortError();
+        const candidate = state.candidate;
+        source = candidate.outputs[Symbol.asyncIterator]();
+        state = { kind: "entered", candidate, iterator: source };
+      }
       if (state.kind === "reserved") input.requireUsable();
       throwIfAgentOperationAborted(lifetime.signal);
       if (state.kind === "reserved") {
         try {
-          input.turnInput.onProviderExecutionStarted?.();
+          if (origin.kind === "caller") origin.input.onProviderExecutionStarted?.();
         } catch (error) {
           state = { kind: "settled" };
           detachAbort();
           input.release();
+          complete();
           throw error;
         }
         throwIfAgentOperationAborted(lifetime.signal);
         input.requireUsable();
-        const { onProviderExecutionStarted: _observer, ...turnInput } = input.turnInput;
+        if (origin.kind !== "caller") throw new Error("Only caller executions enter through startTurn.");
+        const { onProviderExecutionStarted: _observer, ...turnInput } = origin.input;
         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.");
-          }
+          const candidate = validateCandidate(origin.start({ ...turnInput, signal: lifetime.signal }));
           source = candidate.outputs[Symbol.asyncIterator]();
           throwIfAgentOperationAborted(lifetime.signal);
           state = { kind: "entered", candidate, iterator: source };
@@ -153,7 +224,7 @@ function createValidatedAgentTurnExecution(input) {
         }
       }
       if (state.kind !== "entered") throw abortError();
-      const nativePull = track(Promise.resolve().then(() => state.kind === "entered" ? state.iterator.next() : Promise.reject(abortError())));
+      const nativePull = track(Promise.resolve().then(() => state.kind === "entered" ? state.iterator.next() : origin.kind === "native" && state.kind === "settled" ? { done: true, value: void 0 } : Promise.reject(abortError())));
       const stopped = new Promise((_, reject) => {
         const onAbort = () => reject(abortError());
         lifetime.signal.addEventListener("abort", onAbort, { once: true });
@@ -162,21 +233,29 @@ function createValidatedAgentTurnExecution(input) {
       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();
+        if (origin.kind === "native" && currentState().kind === "settled") throwAgentProviderContractError(input.providerKey, "invalid_native_continuation", "A no-work execution emitted native output.");
+        observedOutput = true;
+        const output = input.observe(result.value, requests);
         return { done: false, value: output };
       }
       while (input.inFlightOperations.size > 0) {
         await Promise.race([Promise.all(input.inFlightOperations), stopped]);
       }
       throwIfAgentOperationAborted(lifetime.signal);
+      if (origin.kind === "native" && await Promise.race([disposition, stopped]) === "not_started") return { done: true, value: void 0 };
       input.assertCompleted();
+      requests.withdraw();
       state = { kind: "settled" };
       detachAbort();
       input.release();
+      complete();
       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 }));
+      if (error instanceof AgentProviderContractError && error.code === "request_identity_limit_exceeded") {
+        void input.abandon().catch(() => {
+        });
+      }
       throw error;
     } finally {
       removeAbort();
@@ -188,9 +267,13 @@ function createValidatedAgentTurnExecution(input) {
     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;
+      const entered = dispatched || 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 }));
+      if (entered && origin.kind === "native") {
+        void input.abandon().catch(() => {
+        });
+        returnPromise = Promise.resolve({ done: true, value: void 0 });
+      } else returnPromise = (entered ? input.abandon() : Promise.resolve()).then(() => ({ done: true, value: void 0 }));
       return returnPromise;
     }
   };
@@ -202,13 +285,34 @@ function createValidatedAgentTurnExecution(input) {
     }
   });
   return {
-    execution: Object.freeze({ turnId: input.turnInput.turnId, outputs, resolveRequest }),
-    hasEntered: () => state.kind === "entering" || state.kind === "entered",
+    execution: Object.freeze({ turnId, outputs, resolveRequest }),
+    hasEntered: () => dispatched && state.kind === "parked" || state.kind === "entering" || state.kind === "entered",
     stop,
     join,
-    suspendRequests: requests.suspend
+    suspendRequests: requests.suspend,
+    completed,
+    readerReady,
+    admitDispatch() {
+      if (state.kind !== "parked") throwAgentProviderContractError(input.providerKey, "invalid_native_continuation", "Prepared execution is no longer dispatchable.");
+      dispatched = true;
+      allowDispatch();
+    },
+    markStarted() {
+      resolveDisposition("started");
+    },
+    settleNoWork() {
+      if (observedOutput) {
+        throwAgentProviderContractError(input.providerKey, "invalid_native_continuation", "No-work outcome conflicts with entered output.");
+      }
+      state = { kind: "settled" };
+      resolveDisposition("not_started");
+      detachAbort();
+      allowDispatch();
+      complete();
+    }
   };
 }
 export {
+  adoptValidatedAgentTurnExecution,
   createValidatedAgentTurnExecution
 };

package/dist/turnExecution/requests.d.ts

@@ -1,4 +1,5 @@
-import type { AgentRequest, AgentTurnId } from "@agen-ai/agent-protocol";
+import type { AgentProviderKey, AgentRequest, AgentTurnId } from "@agen-ai/agent-protocol";
+import type { AgentSessionAdmission } from "../sessionAdmission.js";
 export interface PendingAgentRequest {
     readonly request: AgentRequest;
     readonly turnId: AgentTurnId;
@@ -8,12 +9,23 @@ export interface SuspendedAgentTurnRequests {
     readonly withdraw: () => void;
 }
 export declare function createAgentTurnRequestAdmission(input: Readonly<{
+    providerKey: AgentProviderKey;
+    sessionAdmission: AgentSessionAdmission;
     pendingRequests: Map<string, PendingAgentRequest>;
     canRestore: () => boolean;
+    canRestoreRequest: (pending: PendingAgentRequest) => boolean;
 }>): {
-    claim: (requestId: string, pending: PendingAgentRequest) => (() => void);
+    claim: (requestId: string, pending: PendingAgentRequest) => {
+        restore(): void;
+        retire(): void;
+    };
     suspend: () => SuspendedAgentTurnRequests;
     withdraw: () => void;
-    observeRequest(): void;
+    open(pending: PendingAgentRequest): void;
+    unavailable(requestId: string): void;
+    unclaimedRequests(): Iterable<PendingAgentRequest>;
+    hasUnclaimedRequest(): boolean;
+    hasOpened(requestId: string): boolean;
 };
+export type AgentTurnRequestAdmission = ReturnType<typeof createAgentTurnRequestAdmission>;
 //# sourceMappingURL=requests.d.ts.map

package/dist/turnExecution/requests.js

@@ -1,44 +1,79 @@
-function createRequestAdmissionGeneration() {
-  return { suspensions: /* @__PURE__ */ new Set(), withheldRequests: /* @__PURE__ */ new Map() };
-}
+import { throwAgentProviderContractError } from "../contractErrors.js";
 function createAgentTurnRequestAdmission(input) {
-  let generation = createRequestAdmissionGeneration();
-  const withdraw = () => {
-    generation = createRequestAdmissionGeneration();
-    input.pendingRequests.clear();
+  const requests = /* @__PURE__ */ new Map();
+  const invalidSequence = (message) => throwAgentProviderContractError(input.providerKey, "invalid_turn_sequence", message);
+  const retire = (requestId, entry) => {
+    entry.eligibility = { kind: "retired" };
+    entry.suspensions.clear();
+    input.pendingRequests.delete(requestId);
   };
-  const restoreReadyRequests = (requestGeneration) => {
-    if (requestGeneration !== generation || !input.canRestore() || requestGeneration.suspensions.size > 0 || input.pendingRequests.size > 0) return;
-    for (const [requestId, pending] of requestGeneration.withheldRequests) {
+  const restoreReadyRequest = () => {
+    if (!input.canRestore() || input.pendingRequests.size > 0) return;
+    for (const [requestId, entry] of requests) {
+      if (entry.eligibility.kind !== "withheld" || entry.suspensions.size > 0) continue;
+      const pending = entry.eligibility.pending;
+      if (!input.canRestoreRequest(pending)) {
+        retire(requestId, entry);
+        continue;
+      }
+      entry.eligibility = { kind: "pending", pending };
       input.pendingRequests.set(requestId, pending);
+      return;
     }
-    requestGeneration.withheldRequests.clear();
+  };
+  const withdraw = () => {
+    for (const [requestId, entry] of requests) retire(requestId, entry);
   };
   const claim = (requestId, pending) => {
-    const claimedGeneration = generation;
+    const entry = requests.get(requestId);
+    if (!entry || entry.eligibility.kind !== "pending" || entry.eligibility.pending !== pending) {
+      return throwAgentProviderContractError(
+        input.providerKey,
+        "request_resolution_mismatch",
+        "Resolution does not identify an answerable request in this execution."
+      );
+    }
+    const attempt = Symbol("request response");
+    entry.eligibility = { kind: "claimed", pending, attempt };
     input.pendingRequests.delete(requestId);
-    return () => {
-      if (claimedGeneration !== generation || !input.canRestore()) return;
-      claimedGeneration.withheldRequests.set(requestId, pending);
-      restoreReadyRequests(claimedGeneration);
+    restoreReadyRequest();
+    return {
+      restore() {
+        if (entry.eligibility.kind !== "claimed" || entry.eligibility.attempt !== attempt || !input.canRestore()) return;
+        entry.eligibility = { kind: "withheld", pending };
+        restoreReadyRequest();
+      },
+      retire() {
+        if (entry.eligibility.kind !== "claimed" || entry.eligibility.attempt !== attempt) return;
+        retire(requestId, entry);
+        restoreReadyRequest();
+      }
     };
   };
   const suspend = () => {
-    const suspendedGeneration = generation;
-    const suspension = /* @__PURE__ */ Symbol("interruption");
-    suspendedGeneration.suspensions.add(suspension);
-    for (const [requestId, pending] of input.pendingRequests) {
-      suspendedGeneration.withheldRequests.set(requestId, pending);
+    const token = Symbol("interruption");
+    const affected = [];
+    for (const [requestId, entry] of requests) {
+      if (entry.eligibility.kind === "retired") continue;
+      affected.push(entry);
+      entry.suspensions.add(token);
+      if (entry.eligibility.kind === "pending") {
+        entry.eligibility = { kind: "withheld", pending: entry.eligibility.pending };
+        input.pendingRequests.delete(requestId);
+      }
     }
-    input.pendingRequests.clear();
+    let settled = false;
     return {
       restore() {
-        if (!suspendedGeneration.suspensions.delete(suspension)) return;
-        restoreReadyRequests(suspendedGeneration);
+        if (settled) return;
+        settled = true;
+        for (const entry of affected) entry.suspensions.delete(token);
+        restoreReadyRequest();
       },
       withdraw() {
-        if (!suspendedGeneration.suspensions.delete(suspension)) return;
-        if (suspendedGeneration === generation) withdraw();
+        if (settled) return;
+        settled = true;
+        withdraw();
       }
     };
   };
@@ -46,8 +81,38 @@ function createAgentTurnRequestAdmission(input) {
     claim,
     suspend,
     withdraw,
-    observeRequest() {
-      generation = createRequestAdmissionGeneration();
+    open(pending) {
+      if (input.pendingRequests.size > 0) invalidSequence("Provider opened more than one pending request for a session.");
+      const requestId = pending.request.requestId;
+      input.sessionAdmission.claimRequest(requestId, "invalid_turn_sequence");
+      requests.set(requestId, {
+        eligibility: { kind: "pending", pending },
+        canonicalRetirementObserved: false,
+        suspensions: /* @__PURE__ */ new Set()
+      });
+      input.pendingRequests.set(requestId, pending);
+    },
+    unavailable(requestId) {
+      const entry = requests.get(requestId);
+      if (!entry) return invalidSequence("Provider retired a request not opened in this execution.");
+      if (entry.canonicalRetirementObserved) return invalidSequence("Provider retired the same request more than once.");
+      entry.canonicalRetirementObserved = true;
+      retire(requestId, entry);
+      restoreReadyRequest();
+    },
+    *unclaimedRequests() {
+      for (const entry of requests.values()) {
+        if (entry.eligibility.kind === "pending" || entry.eligibility.kind === "withheld") yield entry.eligibility.pending;
+      }
+    },
+    hasUnclaimedRequest() {
+      for (const entry of requests.values()) {
+        if (entry.eligibility.kind === "pending" || entry.eligibility.kind === "withheld") return true;
+      }
+      return false;
+    },
+    hasOpened(requestId) {
+      return requests.has(requestId);
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agen-ai/agent-runtime",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "private": false,
   "description": "Provider-neutral driver, instance, adapter, session, output, and conformance contracts for coding-agent runtimes.",
   "type": "module",
@@ -31,7 +31,7 @@
     }
   },
   "dependencies": {
-    "@agen-ai/agent-protocol": "^0.4.0"
+    "@agen-ai/agent-protocol": "^0.4.2"
   },
   "devDependencies": {
     "tsup": "^8.5.0"