@agen-ai/agent-runtime 0.4.2 → 0.4.3

package/README.md

@@ -9,7 +9,7 @@ sessions; each returned session owns its binding and conversation-local operatio
 The runtime depends only on `@agen-ai/agent-protocol`. It has no concept of tenants, SaaS
 workspaces, assigned users, database rows, persistence sequence, visibility, billing, host boots,
 distributed leases, or storage policy. A host must authorize and select an instance before calling this SPI.
-This unpublished source candidate implements Agent Protocol V12 at coordinated SDK version `0.4.2`,
+This package implements Agent Protocol V12 at coordinated SDK version `0.4.3`,
 including tagged decision responses and exact turn request unavailability. Published `0.4.1`
 retains V11 and its qualification evidence; the earlier `0.4.0` release retains V10.
 The runtime also provides neutral session forms, plan reviews, staged native continuations and
@@ -157,10 +157,11 @@ reopen an older request. A host must cancel human decisions when their execution
 those tasks during cleanup. Keep the session or exact opening-cleanup receipt if cleanup fails;
 disposing its registry or host resources before quiescence would lose the retained owner.
 
-`runtime.retrying` reports a retry already owned by the provider on the active turn. It preserves
+`runtime.retrying` reports a retry already owned by the provider on the active turn or operation. It preserves
 turn ownership, pending requests, and per-output backpressure; it neither starts another execution
 nor completes the turn. It is rejected before `turn.started`, after `turn.completed`, after a
-`final_diff` terminal materialization, and from session-operation observations. The event's neutral
+`final_diff` terminal materialization on a turn. Current source also admits it through an owned
+session operation's awaited `onOutput`, with the exact `observationTurnId` and no `turn.started`. The event's neutral
 failure category and recovery hint describe the observed condition. A recovery hint never authorizes
 replaying work or changes an uncertain execution outcome. Contract failures, delegated-operation
 started evidence, and retained cleanup responsibilities remain separate from those failure values.
@@ -188,6 +189,23 @@ provider-delegated steering failures throw `AgentProviderDelegatedOperationError
 cause and explicit started-execution evidence so a host can retire the unusable session. Platform
 scheduling and provider-native queue modes are intentionally outside this SPI.
 
+Current source reserves the shared execution slot for `idle_session`/`immediate` operations after
+descriptor validation, through native settlement and awaited output acceptance. Caller turns and
+native continuations cannot overlap that reservation. Exact cached idempotent results are returned
+before reserving another execution. Close stops admission and initiates native quiescence before
+joining entered operation work; failed cleanup retains its stopped owner for retry. This lifecycle
+correction and operation retry observations are included in `0.4.3`, using the existing
+Agent Protocol V12 and operation SPI.
+
+Discover the operation through `session.operations` and its offered descriptor, using an exact
+application-configured ID. Pass the descriptor revision as `expectedRevision`, its exact fields,
+a fresh invocation ID and an independent observation correlation; the catalog revision is a
+different value. Confirmation is host-owned. A completed result proves command completion, while
+an accepted completed `context_compaction` item proves an observed compaction effect. Do not infer
+effects from English output text, manufacture token savings, or replay an uncertain operation.
+The exported repository's `examples/operations.ts` demonstrates these cases against public APIs
+and is compiled and executed in the isolated packed-consumer gate.
+
 Configuration selection, operation invocation, and collaboration mutation use the same execution
 receipt rule: stale or malformed input fails before provider delegation, while any failure after
 the candidate reports execution start is wrapped as `AgentProviderDelegatedOperationError` and
@@ -533,13 +551,14 @@ close before joining its reader and actual callback tasks; failure also starts c
 failures and cleanup failures remain observable. A callback that ignores cancellation
 remains owned until its actual promise settles.
 
-The coordinated SDK release is `0.4.1` and implements Agent Protocol V11.
+The coordinated SDK release is `0.4.3` and implements Agent Protocol V12.
+The earlier `0.4.1` release retains V11.
 The earlier `0.4.0` release retains V10.
 The earlier public `0.3.0` and `0.3.1` releases implemented V9 and remain historical.
 Keep installed packages in the seven-package SDK release family on the coordinated version; the
 orchestration and ACP packages remain optional. Every materialized instance requires `environment` and
 `accountQuota`; every session requires `environment`. The former standalone `integrations`
-observation port is removed. The public runtime implements Agent Protocol V11 with one current
+observation port is removed. The public runtime implements Agent Protocol V12 with one current
 adapter/session surface. Package versions remain independent of private transport and product
 persistence versions.
 

package/dist/sessionAdmission.d.ts

@@ -1,5 +1,7 @@
 import type { AgentProviderKey, AgentRequestId } from "@agen-ai/agent-protocol";
 export declare function createAgentSessionAdmission<Execution = unknown>(providerKey: AgentProviderKey): {
+    trackOperation(): () => void;
+    joinOperations(): Promise<void>;
     reserveExecution(): object;
     installExecution(token: object, execution: Execution): void;
     releaseExecution(token: object): void;

package/dist/sessionAdmission.js

@@ -6,7 +6,20 @@ function createAgentSessionAdmission(providerKey) {
   let requestIdBytes = 0;
   let slot;
   let stopped = false;
+  const operations = /* @__PURE__ */ new Set();
   return {
+    trackOperation() {
+      if (stopped) throwAgentProviderContractError(providerKey, "session_unusable", "Session admission is stopped.");
+      const completion = Promise.withResolvers();
+      operations.add(completion.promise);
+      return () => {
+        operations.delete(completion.promise);
+        completion.resolve();
+      };
+    },
+    async joinOperations() {
+      await Promise.all(operations);
+    },
     reserveExecution() {
       if (stopped) throwAgentProviderContractError(providerKey, "session_unusable", "Session admission is stopped.");
       if (slot) throwAgentProviderContractError(providerKey, "concurrent_turn", "Provider session already owns an execution.");

package/dist/sessionValidation.d.ts

@@ -49,6 +49,8 @@ interface ActiveAgentTurn {
 }
 export declare function createAgentSessionValidationOwner(capabilities: AgentCapabilities, sessionId: AgentSessionId): {
     sessionAdmission: {
+        trackOperation(): () => void;
+        joinOperations(): Promise<void>;
         reserveExecution(): object;
         installExecution(token: object, execution: ActiveAgentTurn): void;
         releaseExecution(token: object): void;

package/dist/sessionValidation.js

@@ -499,6 +499,7 @@ const SESSION_OPERATION_OBSERVATION_EVENT_TYPES = /* @__PURE__ */ new Set([
   "resource.updated",
   "runtime.warning",
   "runtime.error",
+  "runtime.retrying",
   "provider.diagnostic"
 ]);
 function observeSessionOperationOutput(input) {
@@ -1048,142 +1049,154 @@ function validateAgentProviderSession(input) {
     invokeOperation: async (operationInput) => {
       requireUsable();
       throwIfAgentOperationAborted(operationInput.signal);
-      let invocation;
-      let observationTurnId;
+      const settle = validationOwner.sessionAdmission.trackOperation();
+      const signal = operationInput.signal === void 0 ? sessionLifetime.signal : AbortSignal.any([operationInput.signal, sessionLifetime.signal]);
+      operationInput = { ...operationInput, signal };
       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
+        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 }
+          )
         );
-      } catch {
-        return throwAgentProviderContractError(
-          providerKey,
-          "input_operation_mismatch",
-          "Operation invocation is stale or outside the offered descriptor."
+        const descriptor = catalog.operations.find(
+          (operation) => operation.operationId === invocation.operationId
         );
-      }
-      const existing = interactionState.operationInvocations.get(
-        invocation.invocationId
-      );
-      if (existing !== void 0) {
-        if (JSON.stringify(existing.invocation) !== JSON.stringify(invocation)) {
+        if (descriptor === void 0) {
           return throwAgentProviderContractError(
             providerKey,
             "input_operation_mismatch",
-            "Operation invocation ID was reused with conflicting input."
+            "Operation invocation does not identify an offered operation."
           );
         }
-        if (descriptor.idempotency === "required" && existing.result !== void 0) {
-          return existing.result;
+        try {
+          invocation = parseAgentOperationInvocationFor(
+            descriptor,
+            invocation
+          );
+        } catch {
+          return throwAgentProviderContractError(
+            providerKey,
+            "input_operation_mismatch",
+            "Operation invocation is stale or outside the offered descriptor."
+          );
         }
-        return throwAgentProviderContractError(
-          providerKey,
-          "input_operation_mismatch",
-          "Operation invocation ID is already active or is not replayable."
+        const existing = interactionState.operationInvocations.get(
+          invocation.invocationId
         );
-      }
-      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,
-        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({
+        if (existing !== void 0) {
+          if (JSON.stringify(existing.invocation) !== JSON.stringify(invocation)) {
+            return throwAgentProviderContractError(
               providerKey,
-              candidate: validateAgentOperationResultForInvocation(
-                providerKey,
-                descriptor,
-                invocation,
-                candidate
-              ),
-              previous: interactionState.operationResults.get(
-                invocation.invocationId
-              )
-            });
-            interactionState.operationResults.set(
-              result2.invocationId,
-              result2
+              "input_operation_mismatch",
+              "Operation invocation ID was reused with conflicting input."
             );
-            return result2;
           }
-        });
-        trackedInvocation.result = result;
-        return result;
-      } catch (error) {
-        if (!(error instanceof AgentProviderDelegatedOperationError)) {
-          interactionState.operationInvocations.delete(
-            invocation.invocationId
+          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."
           );
         }
-        throw error;
+        requireUsable();
+        signal.throwIfAborted();
+        const reservation = descriptor.timing === "idle_session" && descriptor.executionMode === "immediate" ? validationOwner.reserveExecution() : void 0;
+        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,
+          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;
+        } finally {
+          if (reservation !== void 0) validationOwner.releaseExecution(reservation);
+        }
+      } finally {
+        settle();
       }
     }
   });
@@ -1450,6 +1463,7 @@ function validateAgentProviderSession(input) {
       }
       await input.sessionInteractionOwner?.join();
       await closingTurn?.owner.join();
+      await validationOwner.sessionAdmission.joinOperations();
       await input.hostBindingLease?.release();
       validationOwner.completeClose();
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agen-ai/agent-runtime",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "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.2"
+    "@agen-ai/agent-protocol": "^0.4.3"
   },
   "devDependencies": {
     "tsup": "^8.5.0"