@agen-ai/agent-runtime 0.2.0 → 0.2.2

package/README.md

@@ -43,10 +43,20 @@ Approval continuations are refusal-first. Before delegating to the candidate ada
 validated session proves that the request is still pending and unexpired and that a selected
 `optionId` was offered by that exact request. Provider-emitted approval requests must correlate to
 a live item or exact proposed-plan artifact, and every option must fit an advertised
-persistence/scope mode.
+persistence/scope mode. Item identities are monotonic throughout a turn, including every request
+continuation: an adapter cannot restart an observed identity, change its kind, erase prior progress
+through an unknown-status update, regress it from in-progress to pending, or revive it after a
+terminal event or status. An `item.completed` event must carry `completed`, `failed`, or `canceled`
+status. Completion-only snapshots remain valid when no earlier lifecycle event was observed.
 
 The host should serialize mutating operations for a given session. Separate session objects may
 run concurrently, so provider implementations must isolate their conversation-local state.
+
+Materialization-scoped context usage remains monotonic only within one native provider process. A
+provider that replaces that process emits a `process.started` lifecycle output as the explicit
+boundary before reporting usage from the replacement. Validation then clears only the
+`materialization` occupancy, cumulative counters, and compaction allowance; logical `session`
+measurements remain continuous.
 `runTurn` and `resolveRequest` both preserve consumer backpressure: the provider does not resume
 until the consumer requests the next output. Each stream must end at a completed turn or exactly
 one newly pending request. If a consumer abandons a stream, a provider throws, or either stream
@@ -136,7 +146,7 @@ turn/request ordering, request resolution, steering, interruption, configuration
 close, and idempotent disposal. Unsupported operations must remain explicit discriminants and
 must not expose handlers.
 
-The package is at `0.2.0` while the public SPI is being proven with external adapters. Minor
+The package is at `0.2.2` while the public SPI is being proven with external adapters. Minor
 releases may include breaking changes during this beta period, and those changes will be called out
 in the release notes.
 

package/dist/outputValidation.js

@@ -84,7 +84,7 @@ function isEventCapabilitySupported(capabilities, event) {
     case "item.completed": {
       if (event.payload.itemKind === "context_compaction") {
         const compaction = capabilities.context.compaction;
-        return compaction.kind === "supported" && compaction.triggers.includes(event.payload.details.trigger);
+        return compaction.kind === "supported" && (event.payload.details.trigger === "unknown" || compaction.triggers.includes(event.payload.details.trigger));
       }
       return isItemKindCapabilitySupported(capabilities, event.payload.itemKind);
     }

package/dist/sessionValidation.js

@@ -64,8 +64,53 @@ const FINAL_DIFF_TRAILING_EVENT_TYPES = [
   "runtime.warning",
   "turn.completed"
 ];
+const TERMINAL_ITEM_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "canceled"
+]);
+function observeItemLifecycle(input) {
+  const { event, providerKey, state } = input;
+  const previous = state.observedItems.get(event.payload.itemId);
+  if (event.type === "item.completed" && !TERMINAL_ITEM_STATUSES.has(event.payload.status)) {
+    invalidTurnSequence(
+      providerKey,
+      "Provider completed an item without a terminal item status."
+    );
+  }
+  if (previous?.terminal) {
+    invalidTurnSequence(
+      providerKey,
+      "Provider emitted an item lifecycle event after the item became terminal."
+    );
+  }
+  if (previous?.itemKind !== void 0 && previous.itemKind !== event.payload.itemKind) {
+    invalidTurnSequence(
+      providerKey,
+      "Provider changed the kind of an existing item identity."
+    );
+  }
+  if (previous !== void 0 && event.type === "item.started") {
+    invalidTurnSequence(
+      providerKey,
+      "Provider started an item identity more than once."
+    );
+  }
+  if (previous?.inProgressObserved && event.payload.status === "pending") {
+    invalidTurnSequence(
+      providerKey,
+      "Provider regressed an in-progress item to pending."
+    );
+  }
+  state.observedItems.set(event.payload.itemId, {
+    itemKind: event.payload.itemKind,
+    status: event.payload.status,
+    inProgressObserved: previous?.inProgressObserved === true || event.payload.status === "in_progress",
+    terminal: event.type === "item.completed" || TERMINAL_ITEM_STATUSES.has(event.payload.status)
+  });
+}
 function assertApprovalSubjectCorrelation(input) {
-  const request = input.event.payload.request;
+  const { request } = input;
   if (request.requestKind !== "approval") return;
   if (request.subject.kind === "plan") {
     if (input.state.proposedPlans.get(request.subject.artifactId) !== request.requestId) {
@@ -76,14 +121,24 @@ function assertApprovalSubjectCorrelation(input) {
     }
     return;
   }
-  const status = input.state.observedItems.get(request.subject.itemId);
-  if (status !== "pending" && status !== "in_progress") {
+  const item = input.state.observedItems.get(request.subject.itemId);
+  const itemIsLive = item !== void 0 && !item.terminal && (item.status === "pending" || item.status === "in_progress" || item.status === "unknown" && item.inProgressObserved);
+  if (!itemIsLive) {
     invalidTurnSequence(
       input.providerKey,
       "Provider approval request does not identify a live item from this turn."
     );
   }
 }
+function assertPendingApprovalSubjectCorrelations(input) {
+  for (const pending of input.pendingRequests.values()) {
+    assertApprovalSubjectCorrelation({
+      providerKey: input.providerKey,
+      request: pending.request,
+      state: input.state
+    });
+  }
+}
 function observeContextUsage(input) {
   const previous = input.state.latestByScope.get(input.usage.measurementScope);
   if (previous !== void 0) {
@@ -93,15 +148,6 @@ function observeContextUsage(input) {
         "Provider emitted a duplicate context usage sample."
       );
     }
-    for (const [field, value] of Object.entries(input.usage.cumulative ?? {})) {
-      const previousValue = previous.cumulative?.[field];
-      if (previousValue !== void 0 && value < previousValue) {
-        invalidTurnSequence(
-          input.providerKey,
-          "Provider context cumulative counters cannot decrease."
-        );
-      }
-    }
     if (input.usage.usedTokens < previous.usedTokens && !input.state.compactionReadyScopes.has(input.usage.measurementScope)) {
       invalidTurnSequence(
         input.providerKey,
@@ -109,9 +155,34 @@ function observeContextUsage(input) {
       );
     }
   }
+  const cumulative = input.usage.cumulative;
+  if (cumulative !== void 0) {
+    const previousCumulative = input.state.cumulativeByScope.get(
+      input.usage.measurementScope
+    );
+    for (const field of Object.keys(cumulative)) {
+      const value = cumulative[field];
+      const previousValue = previousCumulative?.[field];
+      if (value !== void 0 && previousValue !== void 0 && value < previousValue) {
+        invalidTurnSequence(
+          input.providerKey,
+          "Provider context cumulative counters cannot decrease."
+        );
+      }
+    }
+    input.state.cumulativeByScope.set(input.usage.measurementScope, {
+      ...previousCumulative,
+      ...cumulative
+    });
+  }
   input.state.latestByScope.set(input.usage.measurementScope, input.usage);
   input.state.compactionReadyScopes.delete(input.usage.measurementScope);
 }
+function observeContextMaterializationBoundary(state) {
+  state.latestByScope.delete("materialization");
+  state.cumulativeByScope.delete("materialization");
+  state.compactionReadyScopes.delete("materialization");
+}
 function observeTurnEvent(input) {
   const {
     contextUsageState,
@@ -164,7 +235,12 @@ function observeTurnEvent(input) {
     }
   }
   if (event.type === "item.started" || event.type === "item.updated" || event.type === "item.completed") {
-    state.observedItems.set(event.payload.itemId, event.payload.status);
+    observeItemLifecycle({ providerKey, event, state });
+    assertPendingApprovalSubjectCorrelations({
+      providerKey,
+      pendingRequests,
+      state
+    });
     if (event.payload.itemKind === "context_compaction" && event.type === "item.completed" && event.payload.status === "completed") {
       for (const scope of ["session", "materialization"]) {
         contextUsageState.compactionReadyScopes.add(scope);
@@ -173,6 +249,11 @@ function observeTurnEvent(input) {
   }
   if (event.type === "turn.plan.proposed") {
     state.proposedPlans.set(event.payload.artifactId, event.payload.requestId);
+    assertPendingApprovalSubjectCorrelations({
+      providerKey,
+      pendingRequests,
+      state
+    });
   }
   if (event.type === "context.usage.updated") {
     observeContextUsage({
@@ -195,7 +276,11 @@ function observeTurnEvent(input) {
         "Provider reused a request ID within a session."
       );
     }
-    assertApprovalSubjectCorrelation({ providerKey, event, state });
+    assertApprovalSubjectCorrelation({
+      providerKey,
+      request: event.payload.request,
+      state
+    });
     openedRequestIds.add(requestId);
     pendingRequests.set(requestId, {
       request: event.payload.request,
@@ -215,6 +300,20 @@ function observeTurnEvent(input) {
     completeTurnSequence({ providerKey, state, pendingRequests });
   }
 }
+function observeTurnOutput(input) {
+  if (input.output.kind === "lifecycle" && input.output.lifecycle.type === "process.started") {
+    observeContextMaterializationBoundary(input.contextUsageState);
+  }
+  if (input.output.kind !== "event") return;
+  observeTurnEvent({
+    providerKey: input.providerKey,
+    event: input.output.event,
+    state: input.state,
+    pendingRequests: input.pendingRequests,
+    openedRequestIds: input.openedRequestIds,
+    contextUsageState: input.contextUsageState
+  });
+}
 function assertStableTurnBoundary(input) {
   const terminal = input.state.terminal && !input.state.waiting;
   const waiting = !input.state.terminal && input.state.waiting && input.pendingRequests.size === 1;
@@ -250,10 +349,9 @@ function interruptionTerminalizesTurn(input) {
 }
 function observeTurnOperationOutputs(input) {
   for (const output of input.outputs ?? []) {
-    if (output.kind !== "event") continue;
-    observeTurnEvent({
+    observeTurnOutput({
       providerKey: input.providerKey,
-      event: output.event,
+      output,
       state: input.state,
       pendingRequests: input.pendingRequests,
       openedRequestIds: input.openedRequestIds,
@@ -267,17 +365,9 @@ function reconstructWaitingTurn(input) {
       ([, pending]) => pending.turnId === input.turnId
     )
   );
-  if (targetedPendingRequests.size === 0) return null;
+  if (targetedPendingRequests.size === 0 || input.state === void 0 || input.state.terminal || !input.state.waiting) return null;
   return {
-    state: {
-      fileChangeMode: input.fileChangeMode,
-      observedItems: /* @__PURE__ */ new Map(),
-      proposedPlans: /* @__PURE__ */ new Map(),
-      started: true,
-      terminal: false,
-      waiting: true,
-      finalDiffObserved: false
-    },
+    state: input.state,
     pendingRequests: targetedPendingRequests
   };
 }
@@ -365,9 +455,11 @@ function validateAgentProviderSession(input) {
   }
   validateSessionPorts(capabilities, input.candidate);
   const pendingRequests = /* @__PURE__ */ new Map();
+  const waitingTurnStates = /* @__PURE__ */ new Map();
   const openedRequestIds = /* @__PURE__ */ new Set();
   const contextUsageState = {
     latestByScope: /* @__PURE__ */ new Map(),
+    cumulativeByScope: /* @__PURE__ */ new Map(),
     compactionReadyScopes: /* @__PURE__ */ new Set()
   };
   let activeTurn = null;
@@ -471,16 +563,14 @@ function validateAgentProviderSession(input) {
           candidate,
           outputContext(parsedInput.turnId)
         );
-        if (output.kind === "event") {
-          observeTurnEvent({
-            providerKey,
-            event: output.event,
-            state: currentTurn.state,
-            pendingRequests: currentTurn.pendingRequests,
-            openedRequestIds,
-            contextUsageState
-          });
-        }
+        observeTurnOutput({
+          providerKey,
+          output,
+          state: currentTurn.state,
+          pendingRequests: currentTurn.pendingRequests,
+          openedRequestIds,
+          contextUsageState
+        });
         yield output;
       }
       while (currentTurn.inFlightOperations.size > 0) {
@@ -499,6 +589,9 @@ function validateAgentProviderSession(input) {
       });
       if (currentTurn.state.waiting) {
         replacePendingRequests(pendingRequests, currentTurn.pendingRequests);
+        waitingTurnStates.set(currentTurn.turnId, currentTurn.state);
+      } else {
+        waitingTurnStates.delete(currentTurn.turnId);
       }
       reachedStableBoundary = true;
     } finally {
@@ -527,7 +620,7 @@ function validateAgentProviderSession(input) {
         "Provider request resolution does not match the opened request."
       );
     }
-    if (pending.request.expiresAt !== void 0 && Date.parse(pending.request.expiresAt) <= Date.now()) {
+    if (pending.request.expiresAt !== void 0 && Date.parse(pending.request.expiresAt) <= Date.now() && resolution.disposition !== "canceled") {
       throwAgentProviderContractError(
         providerKey,
         "request_resolution_mismatch",
@@ -543,18 +636,19 @@ function validateAgentProviderSession(input) {
         "Provider session already has an active turn."
       );
     }
+    const waitingTurnState = waitingTurnStates.get(pending.turnId);
+    if (waitingTurnState === void 0 || waitingTurnState.terminal || !waitingTurnState.waiting) {
+      throwAgentProviderContractError(
+        providerKey,
+        "request_resolution_mismatch",
+        "Provider request resolution does not identify a waiting turn."
+      );
+    }
+    waitingTurnState.waiting = false;
     const currentTurn = {
       turnId: pending.turnId,
       pendingRequests: nextPendingRequests,
-      state: {
-        fileChangeMode: capabilities.output.fileChanges,
-        observedItems: /* @__PURE__ */ new Map(),
-        proposedPlans: /* @__PURE__ */ new Map(),
-        started: true,
-        terminal: false,
-        waiting: false,
-        finalDiffObserved: false
-      },
+      state: waitingTurnState,
       inFlightOperations: /* @__PURE__ */ new Set()
     };
     let reachedStableBoundary = false;
@@ -568,16 +662,14 @@ function validateAgentProviderSession(input) {
           candidate,
           outputContext(pending.turnId)
         );
-        if (output.kind === "event") {
-          observeTurnEvent({
-            providerKey,
-            event: output.event,
-            state: currentTurn.state,
-            pendingRequests: currentTurn.pendingRequests,
-            openedRequestIds,
-            contextUsageState
-          });
-        }
+        observeTurnOutput({
+          providerKey,
+          output,
+          state: currentTurn.state,
+          pendingRequests: currentTurn.pendingRequests,
+          openedRequestIds,
+          contextUsageState
+        });
         yield output;
       }
       while (currentTurn.inFlightOperations.size > 0) {
@@ -589,6 +681,11 @@ function validateAgentProviderSession(input) {
         pendingRequests: currentTurn.pendingRequests
       });
       replacePendingRequests(pendingRequests, currentTurn.pendingRequests);
+      if (currentTurn.state.waiting) {
+        waitingTurnStates.set(currentTurn.turnId, currentTurn.state);
+      } else {
+        waitingTurnStates.delete(currentTurn.turnId);
+      }
       reachedStableBoundary = true;
     } finally {
       if (!reachedStableBoundary) unusable = true;
@@ -610,7 +707,7 @@ function validateAgentProviderSession(input) {
       const targetedWaitingTurn = targetedActiveTurn === null ? reconstructWaitingTurn({
         pendingRequests,
         turnId: parsed.turnId,
-        fileChangeMode: capabilities.output.fileChanges
+        state: waitingTurnStates.get(parsed.turnId)
       }) : null;
       const targetedTurn = targetedActiveTurn ?? targetedWaitingTurn;
       if (targetedTurn === null) {
@@ -642,6 +739,7 @@ function validateAgentProviderSession(input) {
             parsed.turnId
           );
           targetedTurn.state.waiting = false;
+          waitingTurnStates.delete(parsed.turnId);
         }
         try {
           observeTurnOperationOutputs({

package/package.json

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