@agen-ai/agent-runtime 0.4.2 → 0.4.4

package/dist/turnExecution/execution.js

@@ -5,8 +5,11 @@ import {
 import { AgentProviderContractError, AgentProviderDelegatedOperationError, throwAgentProviderContractError } from "../contractErrors.js";
 import { throwIfAgentOperationAborted } from "../foundation.js";
 import { hasExactOwnKeys } from "../internal/objectShape.js";
+import { validateAgentExecutionInputPort } from "../executionInput/validation.js";
+import { createExecutionInputOwner } from "../executionInput/lifetime.js";
 import { validateAgentRequestResolutionResult } from "./receipts.js";
 import { createAgentTurnRequestAdmission } from "./requests.js";
+import { createAgentTurnTerminalBuffer } from "./terminalBuffer.js";
 function createValidatedAgentTurnExecution(input) {
   return createExecution(input, { kind: "caller", input: input.turnInput, start: input.start });
 }
@@ -17,14 +20,17 @@ 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();
+  let inputOwner;
   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") {
+    if (candidate === null || typeof candidate !== "object" || candidate.turnId !== turnId || !hasExactOwnKeys(candidate, ["turnId", "outputs", "resolveRequest", ...Object.hasOwn(candidate, "input") ? ["input"] : []]) || 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."
       );
     }
+    const port = validateAgentExecutionInputPort(candidate.input, input.executionInputSupport, input.providerKey);
+    if (port?.kind === "supported") inputOwner?.attach(port);
     return candidate;
   };
   let state;
@@ -54,6 +60,8 @@ function createExecution(input, origin) {
     resolveDisposition = resolve;
   });
   let source;
+  let sourceExhausted = false;
+  let terminalTail;
   const requests = createAgentTurnRequestAdmission({
     providerKey: input.providerKey,
     sessionAdmission: input.sessionAdmission,
@@ -61,6 +69,40 @@ function createExecution(input, origin) {
     canRestore: () => state.kind === "entered" && !input.isTerminal(),
     canRestoreRequest: input.canRestoreRequest
   });
+  let resolvingRequests = 0;
+  if (origin.kind === "caller" && input.executionInputSupport?.kind === "supported") {
+    inputOwner = createExecutionInputOwner({
+      providerKey: input.providerKey,
+      turnId,
+      support: input.executionInputSupport,
+      census: input.executionInputCensus,
+      signal: lifetime.signal,
+      fence: input.retire,
+      requireAdmission() {
+        input.requireUsable();
+        if (state.kind !== "entered" || !input.ownsExecution() || input.isTerminal()) {
+          throwAgentProviderContractError(
+            input.providerKey,
+            "active_turn_mismatch",
+            "Execution input does not identify the exact active entered execution."
+          );
+        }
+        if (input.structuredOutputBound) throwAgentProviderContractError(
+          input.providerKey,
+          "structured_output_unsupported",
+          "Schema-bound execution cannot admit additional input."
+        );
+        input.requireInputContext();
+        if (requests.hasUnclaimedRequest() || resolvingRequests > 0) {
+          throwAgentProviderContractError(
+            input.providerKey,
+            "request_pending",
+            "Execution input cannot enter while a human request or its response remains unsettled."
+          );
+        }
+      }
+    });
+  }
   let acquired = false;
   let pulling = false;
   let returnPromise;
@@ -75,8 +117,11 @@ function createExecution(input, origin) {
     return new DOMException("The turn execution was stopped.", "AbortError");
   };
   const detachAbort = () => callerSignal?.removeEventListener("abort", abort);
-  const stop = (reason) => {
+  const stop = (reason, inputReason = "native_failed") => {
     if (state.kind === "settled" || state.kind === "stopped") return;
+    inputOwner?.closeAdmission(inputReason);
+    terminalTail?.clear();
+    terminalTail = void 0;
     const entered = dispatched || state.kind === "entered" || state.kind === "entering";
     state = { kind: "stopped", reason };
     requests.withdraw();
@@ -97,7 +142,7 @@ function createExecution(input, origin) {
     } catch (error) {
       if (error instanceof Error) reason = error;
     }
-    stop(reason);
+    stop(reason, "interrupted");
   };
   callerSignal?.addEventListener("abort", abort, { once: true });
   const track = (operation) => {
@@ -105,6 +150,7 @@ function createExecution(input, origin) {
     void operation.then(() => nativeOperations.delete(operation), () => nativeOperations.delete(operation));
     return operation;
   };
+  const pullNative = () => track(Promise.resolve().then(() => state.kind === "entered" ? sourceExhausted ? { done: true, value: void 0 } : state.iterator.next() : origin.kind === "native" && state.kind === "settled" ? { done: true, value: void 0 } : Promise.reject(abortError())));
   let joinPromise;
   const join = () => {
     if (joinPromise) return joinPromise;
@@ -113,6 +159,7 @@ function createExecution(input, origin) {
         await Promise.allSettled([...nativeOperations, ...input.inFlightOperations]);
       }
       if (source?.return) await source.return();
+      await inputOwner?.join();
     })();
     joinPromise = attempt;
     void attempt.catch(() => {
@@ -150,6 +197,7 @@ function createExecution(input, origin) {
       settle = resolve;
     });
     input.inFlightOperations.add(settlement);
+    resolvingRequests += 1;
     try {
       try {
         requestInput.onProviderExecutionStarted?.();
@@ -174,6 +222,7 @@ function createExecution(input, origin) {
       if (result.status === "delivery_uncertain") input.retire();
       return result;
     } finally {
+      resolvingRequests -= 1;
       input.inFlightOperations.delete(settlement);
       settle();
     }
@@ -186,6 +235,12 @@ function createExecution(input, origin) {
     let removeAbort = () => {
     };
     try {
+      if (terminalTail) {
+        throwIfAgentOperationAborted(lifetime.signal);
+        const trailing = terminalTail.take();
+        if (trailing !== void 0) return { done: false, value: trailing };
+        terminalTail = void 0;
+      }
       if (state.kind === "parked") {
         ready();
         await dispatch;
@@ -224,7 +279,7 @@ function createExecution(input, origin) {
         }
       }
       if (state.kind !== "entered") throw 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 nativePull = pullNative();
       const stopped = new Promise((_, reject) => {
         const onAbort = () => reject(abortError());
         lifetime.signal.addEventListener("abort", onAbort, { once: true });
@@ -236,6 +291,24 @@ function createExecution(input, origin) {
         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);
+        if (inputOwner && output.kind === "event" && output.event.type === "turn.completed") {
+          inputOwner.closeAdmission();
+          const buffer = createAgentTurnTerminalBuffer(input.providerKey, output);
+          const exhaustSource = (async () => {
+            for (; ; ) {
+              const trailing = await Promise.race([pullNative(), stopped]);
+              throwIfAgentOperationAborted(lifetime.signal);
+              if (trailing.done) {
+                sourceExhausted = true;
+                return;
+              }
+              buffer.append(input.observe(trailing.value, requests));
+            }
+          })();
+          await Promise.race([inputOwner.drain(exhaustSource), stopped]);
+          throwIfAgentOperationAborted(lifetime.signal);
+          terminalTail = buffer;
+        }
         return { done: false, value: output };
       }
       while (input.inFlightOperations.size > 0) {
@@ -247,7 +320,7 @@ function createExecution(input, origin) {
       requests.withdraw();
       state = { kind: "settled" };
       detachAbort();
-      input.release();
+      if (!inputOwner?.retainsOwnership) input.release();
       complete();
       return { done: true, value: void 0 };
     } catch (error) {
@@ -256,6 +329,8 @@ function createExecution(input, origin) {
         void input.abandon().catch(() => {
         });
       }
+      if (inputOwner?.failed) void input.abandon().catch(() => {
+      });
       throw error;
     } finally {
       removeAbort();
@@ -268,7 +343,7 @@ function createExecution(input, origin) {
       if (returnPromise) return returnPromise;
       if (state.kind === "settled") return Promise.resolve({ done: true, value: void 0 });
       const entered = dispatched || state.kind === "entered" || source !== void 0;
-      stop(new DOMException("The turn output consumer returned.", "AbortError"));
+      stop(new DOMException("The turn output consumer returned.", "AbortError"), "closed");
       if (entered && origin.kind === "native") {
         void input.abandon().catch(() => {
         });
@@ -285,10 +360,16 @@ function createExecution(input, origin) {
     }
   });
   return {
-    execution: Object.freeze({ turnId, outputs, resolveRequest }),
+    execution: Object.freeze({
+      turnId,
+      outputs,
+      resolveRequest,
+      ...inputOwner === void 0 ? origin.kind === "native" && input.executionInputSupport?.kind === "supported" ? { input: Object.freeze({ kind: "unsupported" }) } : {} : { input: inputOwner.port }
+    }),
     hasEntered: () => dispatched && state.kind === "parked" || state.kind === "entering" || state.kind === "entered",
     stop,
     join,
+    closeInputAdmission: () => inputOwner?.closeAdmission(),
     suspendRequests: requests.suspend,
     completed,
     readerReady,

package/dist/turnExecution/terminalBuffer.d.ts

@@ -0,0 +1,9 @@
+import type { AgentProviderKey } from "@agen-ai/agent-protocol";
+import type { AgentProviderOutput } from "../outputs.js";
+/** Holds validated observations in native order until the terminal and its input ownership can publish. */
+export declare function createAgentTurnTerminalBuffer(providerKey: AgentProviderKey, terminal: AgentProviderOutput): {
+    append(output: AgentProviderOutput): void;
+    take(): AgentProviderOutput | undefined;
+    clear(): void;
+};
+//# sourceMappingURL=terminalBuffer.d.ts.map

package/dist/turnExecution/terminalBuffer.js

@@ -0,0 +1,38 @@
+import { throwAgentProviderContractError } from "../contractErrors.js";
+const MAX_TRAILING_OUTPUTS = 32;
+const MAX_RETAINED_BYTES = 16 * 1024 * 1024;
+function retainedOutputBytes(output) {
+  if (output.kind === "artifact" && output.candidate.source.kind === "bytes") {
+    const metadata = { ...output, candidate: { ...output.candidate, source: { kind: "bytes" } } };
+    return output.candidate.source.bytes.byteLength + Buffer.byteLength(JSON.stringify(metadata), "utf8");
+  }
+  return Buffer.byteLength(JSON.stringify(output), "utf8");
+}
+function createAgentTurnTerminalBuffer(providerKey, terminal) {
+  const trailing = [];
+  let retainedBytes = retainedOutputBytes(terminal);
+  return {
+    append(output) {
+      const bytes = retainedOutputBytes(output);
+      if (trailing.length >= MAX_TRAILING_OUTPUTS || retainedBytes + bytes > MAX_RETAINED_BYTES) {
+        throwAgentProviderContractError(
+          providerKey,
+          "invalid_operation_result",
+          "Provider exceeded bounded terminal output capacity."
+        );
+      }
+      trailing.push(output);
+      retainedBytes += bytes;
+    },
+    take() {
+      return trailing.shift();
+    },
+    clear() {
+      trailing.length = 0;
+      retainedBytes = 0;
+    }
+  };
+}
+export {
+  createAgentTurnTerminalBuffer
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agen-ai/agent-runtime",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "private": false,
   "description": "Provider-neutral driver, instance, adapter, session, output, and conformance contracts for coding-agent runtimes.",
   "type": "module",
@@ -28,10 +28,14 @@
     "./environment": {
       "types": "./dist/environment/index.d.ts",
       "import": "./dist/environment/index.js"
+    },
+    "./generation": {
+      "types": "./dist/generation/index.d.ts",
+      "import": "./dist/generation/index.js"
     }
   },
   "dependencies": {
-    "@agen-ai/agent-protocol": "^0.4.2"
+    "@agen-ai/agent-protocol": "^0.4.4"
   },
   "devDependencies": {
     "tsup": "^8.5.0"