@agen-ai/agent-runtime 0.1.0 → 0.2.1

package/README.md

@@ -9,6 +9,7 @@ its binding and conversation-local operations.
 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,
 leases, or storage policy. A host must authorize and select an instance before calling this SPI.
+The current coordinated deployment tuple is Agent Protocol V7, private host V15/catalog V9, and Workspaces event V9.
 
 ## Entrypoints
 
@@ -38,6 +39,12 @@ exactly once before returning the matching session. Capability-dependent operati
 `supported`/`unsupported` discriminants, and the runtime rejects handlers that disagree with the
 instance capability declaration.
 
+Approval continuations are refusal-first. Before delegating to the candidate adapter, the
+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.
+
 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.
 `runTurn` and `resolveRequest` both preserve consumer backpressure: the provider does not resume
@@ -53,6 +60,12 @@ turn terminalized; unless the result also carries a terminal event, the validate
 unusable and must be closed and rematerialized. A close failure makes the session unusable while
 leaving close itself retryable.
 
+When context usage is advertised, the validated session enforces the declared measurement scopes
+and cumulative fields across turns. Identical consecutive samples and decreasing cumulative
+counters are rejected. Occupancy may decrease only after a completed advertised compaction item;
+the next accepted sample consumes that allowance. Context output remains subject to the same
+per-output backpressure and terminal ordering as every other provider event.
+
 When `capabilities.turns.steer` is true, the session exposes `steering.steerTurn`. Steering accepts
 the existing turn ID plus the same canonical `parts` and optional `summary` used to start a turn.
 It does not create or own an output stream: model output continues on the original `runTurn`
@@ -123,12 +136,13 @@ 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.1.0` while the public SPI is being proven with external adapters. Minor
+The package is at `0.2.1` 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.
 
-The current version tuple is Agent Protocol V6, private host V14/catalog V8, and Workspaces event V8.
-The runtime package version remains independent of Agent Protocol V6.
+The public runtime implements Agent Protocol V7. Its package version remains independent of private
+host, catalog, persistence, and member-projection versions. Version `0.2.0` directly replaces the
+V6/`0.1.0` API; see the repository `MIGRATING-TO-0.2.md` guide.
 
 Run the clean packed-consumer proof before any release:
 

package/dist/outputValidation.js

@@ -51,12 +51,43 @@ function isContentStreamCapabilitySupported(capabilities, streamKind) {
   }
   return unsupportedCapabilitySemantic(streamKind);
 }
+function isApprovalRequestCapabilitySupported(capabilities, event) {
+  const request = event.payload.request;
+  if (request.requestKind !== "approval") return false;
+  const capability = capabilities.requests.approval;
+  return capability.kind === "supported" && request.options.every(
+    (option) => capability.modes.some(
+      (mode) => mode.persistence === option.persistence && mode.scopeKinds.includes(option.scope.kind)
+    )
+  );
+}
+function isContextUsageCapabilitySupported(capabilities, event) {
+  const capability = capabilities.context.usage;
+  if (capability.kind !== "supported" || !capability.measurementScopes.includes(
+    event.payload.measurementScope
+  )) {
+    return false;
+  }
+  if (event.payload.cumulative !== void 0 && Object.keys(event.payload.cumulative).some(
+    (field) => !capability.cumulativeFields.includes(
+      field
+    )
+  )) {
+    return false;
+  }
+  return event.payload.compaction === void 0 || capabilities.context.compaction.kind === "supported";
+}
 function isEventCapabilitySupported(capabilities, event) {
   switch (event.type) {
     case "item.started":
     case "item.updated":
-    case "item.completed":
+    case "item.completed": {
+      if (event.payload.itemKind === "context_compaction") {
+        const compaction = capabilities.context.compaction;
+        return compaction.kind === "supported" && (event.payload.details.trigger === "unknown" || compaction.triggers.includes(event.payload.details.trigger));
+      }
       return isItemKindCapabilitySupported(capabilities, event.payload.itemKind);
+    }
     case "content.delta":
       return capabilities.output.streaming && isContentStreamCapabilitySupported(
         capabilities,
@@ -72,9 +103,11 @@ function isEventCapabilitySupported(capabilities, event) {
         event.payload.artifact.kind
       );
     case "request.opened":
-      return event.payload.request.requestKind === "approval" ? capabilities.requests.approval : capabilities.requests.elicitation.kind === "structured" || capabilities.requests.elicitation.kind === "text" && event.payload.request.fields.every(
+      return event.payload.request.requestKind === "approval" ? isApprovalRequestCapabilitySupported(capabilities, event) : capabilities.requests.elicitation.kind === "structured" || capabilities.requests.elicitation.kind === "text" && event.payload.request.fields.every(
         (field) => field.kind === "text"
       );
+    case "context.usage.updated":
+      return isContextUsageCapabilitySupported(capabilities, event);
     case "turn.started":
     case "turn.state_changed":
     case "turn.completed":

package/dist/sessionValidation.js

@@ -64,8 +64,74 @@ const FINAL_DIFF_TRAILING_EVENT_TYPES = [
   "runtime.warning",
   "turn.completed"
 ];
+function assertApprovalSubjectCorrelation(input) {
+  const request = input.event.payload.request;
+  if (request.requestKind !== "approval") return;
+  if (request.subject.kind === "plan") {
+    if (input.state.proposedPlans.get(request.subject.artifactId) !== request.requestId) {
+      invalidTurnSequence(
+        input.providerKey,
+        "Provider approval request does not identify a proposed plan from this turn."
+      );
+    }
+    return;
+  }
+  const status = input.state.observedItems.get(request.subject.itemId);
+  if (status !== "pending" && status !== "in_progress") {
+    invalidTurnSequence(
+      input.providerKey,
+      "Provider approval request does not identify a live item from this turn."
+    );
+  }
+}
+function observeContextUsage(input) {
+  const previous = input.state.latestByScope.get(input.usage.measurementScope);
+  if (previous !== void 0) {
+    if (JSON.stringify(previous) === JSON.stringify(input.usage)) {
+      invalidTurnSequence(
+        input.providerKey,
+        "Provider emitted a duplicate context usage sample."
+      );
+    }
+    if (input.usage.usedTokens < previous.usedTokens && !input.state.compactionReadyScopes.has(input.usage.measurementScope)) {
+      invalidTurnSequence(
+        input.providerKey,
+        "Provider context occupancy cannot decrease without completed compaction."
+      );
+    }
+  }
+  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 observeTurnEvent(input) {
-  const { event, openedRequestIds, pendingRequests, providerKey, state } = input;
+  const {
+    contextUsageState,
+    event,
+    openedRequestIds,
+    pendingRequests,
+    providerKey,
+    state
+  } = input;
   if (state.terminal) {
     invalidTurnSequence(
       providerKey,
@@ -108,6 +174,24 @@ 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);
+    if (event.payload.itemKind === "context_compaction" && event.type === "item.completed" && event.payload.status === "completed") {
+      for (const scope of ["session", "materialization"]) {
+        contextUsageState.compactionReadyScopes.add(scope);
+      }
+    }
+  }
+  if (event.type === "turn.plan.proposed") {
+    state.proposedPlans.set(event.payload.artifactId, event.payload.requestId);
+  }
+  if (event.type === "context.usage.updated") {
+    observeContextUsage({
+      providerKey,
+      usage: event.payload,
+      state: contextUsageState
+    });
+  }
   if (event.type === "request.opened") {
     if (pendingRequests.size > 0) {
       invalidTurnSequence(
@@ -122,6 +206,7 @@ function observeTurnEvent(input) {
         "Provider reused a request ID within a session."
       );
     }
+    assertApprovalSubjectCorrelation({ providerKey, event, state });
     openedRequestIds.add(requestId);
     pendingRequests.set(requestId, {
       request: event.payload.request,
@@ -182,7 +267,8 @@ function observeTurnOperationOutputs(input) {
       event: output.event,
       state: input.state,
       pendingRequests: input.pendingRequests,
-      openedRequestIds: input.openedRequestIds
+      openedRequestIds: input.openedRequestIds,
+      contextUsageState: input.contextUsageState
     });
   }
 }
@@ -196,6 +282,8 @@ function reconstructWaitingTurn(input) {
   return {
     state: {
       fileChangeMode: input.fileChangeMode,
+      observedItems: /* @__PURE__ */ new Map(),
+      proposedPlans: /* @__PURE__ */ new Map(),
       started: true,
       terminal: false,
       waiting: true,
@@ -289,6 +377,11 @@ function validateAgentProviderSession(input) {
   validateSessionPorts(capabilities, input.candidate);
   const pendingRequests = /* @__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;
   let closePromise = null;
   let closed = false;
@@ -370,6 +463,8 @@ function validateAgentProviderSession(input) {
       pendingRequests: /* @__PURE__ */ new Map(),
       state: {
         fileChangeMode: capabilities.output.fileChanges,
+        observedItems: /* @__PURE__ */ new Map(),
+        proposedPlans: /* @__PURE__ */ new Map(),
         started: false,
         terminal: false,
         waiting: false,
@@ -394,7 +489,8 @@ function validateAgentProviderSession(input) {
             event: output.event,
             state: currentTurn.state,
             pendingRequests: currentTurn.pendingRequests,
-            openedRequestIds
+            openedRequestIds,
+            contextUsageState
           });
         }
         yield output;
@@ -443,6 +539,13 @@ 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() && resolution.disposition !== "canceled") {
+      throwAgentProviderContractError(
+        providerKey,
+        "request_resolution_mismatch",
+        "Provider request resolution identifies an expired request."
+      );
+    }
     const nextPendingRequests = new Map(pendingRequests);
     nextPendingRequests.delete(resolution.requestId);
     if (activeTurn !== null) {
@@ -457,6 +560,8 @@ function validateAgentProviderSession(input) {
       pendingRequests: nextPendingRequests,
       state: {
         fileChangeMode: capabilities.output.fileChanges,
+        observedItems: /* @__PURE__ */ new Map(),
+        proposedPlans: /* @__PURE__ */ new Map(),
         started: true,
         terminal: false,
         waiting: false,
@@ -481,7 +586,8 @@ function validateAgentProviderSession(input) {
             event: output.event,
             state: currentTurn.state,
             pendingRequests: currentTurn.pendingRequests,
-            openedRequestIds
+            openedRequestIds,
+            contextUsageState
           });
         }
         yield output;
@@ -555,7 +661,8 @@ function validateAgentProviderSession(input) {
             outputs: result.outputs,
             state: targetedTurn.state,
             pendingRequests: targetedTurn.pendingRequests,
-            openedRequestIds
+            openedRequestIds,
+            contextUsageState
           });
           if (terminalized && !targetedTurn.state.terminal) {
             completeTurnSequence({

package/dist/testing/fakeProvider.js

@@ -2,6 +2,8 @@ import {
   parseAgentCapabilities,
   parseAgentInstanceId,
   parseAgentIsoDateTime,
+  parseAgentItemId,
+  parseAgentApprovalOptionId,
   parseAgentProviderConversationId,
   parseAgentProviderHistoryAnchor,
   parseAgentProviderKey,
@@ -33,7 +35,7 @@ function defaultCapabilities(providerKey) {
     }
   };
   return parseAgentCapabilities({
-    protocolVersion: 6,
+    protocolVersion: 7,
     providerKey,
     sessions: { create: true, resume: true, branch: { kind: "through_turn" } },
     turns: {
@@ -41,7 +43,17 @@ function defaultCapabilities(providerKey) {
       interrupt: true,
       steer: { kind: "supported", input }
     },
-    requests: { approval: true, elicitation: { kind: "structured" } },
+    requests: {
+      approval: {
+        kind: "supported",
+        modes: [{ persistence: "once", scopeKinds: ["exact_action"] }]
+      },
+      elicitation: { kind: "structured" }
+    },
+    context: {
+      usage: { kind: "unsupported" },
+      compaction: { kind: "unsupported" }
+    },
     input,
     output: {
       streaming: true,
@@ -81,14 +93,34 @@ function sessionBinding(state, sessionId) {
   };
 }
 function eventBase(sessionId, turnId, occurredAt) {
-  return { protocolVersion: 6, sessionId, turnId, occurredAt };
+  return { protocolVersion: 7, sessionId, turnId, occurredAt };
 }
 function requestForTurn(turnId) {
   return {
     requestKind: "approval",
     requestId: parseAgentRequestId(`fake-request:${turnId}`),
     prompt: "Approve the deterministic fake operation?",
-    subject: { kind: "other", title: "Fake provider operation" }
+    subject: {
+      kind: "other",
+      title: "Fake provider operation",
+      itemId: parseAgentItemId(`fake-item:${turnId}`)
+    },
+    options: [
+      {
+        optionId: parseAgentApprovalOptionId("approval:allow-once"),
+        label: "Allow once",
+        decision: "approved",
+        persistence: "once",
+        scope: { kind: "exact_action" }
+      },
+      {
+        optionId: parseAgentApprovalOptionId("approval:deny-once"),
+        label: "Deny",
+        decision: "denied",
+        persistence: "once",
+        scope: { kind: "exact_action" }
+      }
+    ]
   };
 }
 function completedResult(outputs = []) {
@@ -109,6 +141,15 @@ function fakeSession(input) {
       type: "turn.started",
       payload: { message: "Fake provider turn started." }
     });
+    yield createAgentEventOutput({
+      ...eventBase(input.context.sessionId, turnInput.turnId, occurredAt),
+      type: "item.started",
+      payload: {
+        itemId: parseAgentItemId(`fake-item:${turnInput.turnId}`),
+        itemKind: "assistant_message",
+        status: "in_progress"
+      }
+    });
     if (input.capabilities.output.streaming) {
       yield createAgentEventOutput({
         ...eventBase(input.context.sessionId, turnInput.turnId, occurredAt),
@@ -120,7 +161,7 @@ function fakeSession(input) {
         }
       });
     }
-    if (input.capabilities.requests.approval) {
+    if (input.capabilities.requests.approval.kind === "supported") {
       const request = requestForTurn(turnInput.turnId);
       pendingRequests.set(request.requestId, {
         request,

package/package.json

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