@agen-ai/agent-runtime 0.2.3 → 0.2.4

package/README.md

@@ -101,8 +101,13 @@ receipt rule: stale or malformed input fails before provider delegation, while a
 the candidate reports execution start is wrapped as `AgentProviderDelegatedOperationError` and
 makes the session unusable. The start boundary commits only after the host observer returns
 successfully; an observer failure remains a pre-delegation error and leaves the session reusable.
-Operation, collaboration, and generated-resource observations also
-enforce correlation, immutable identity, declared bounds, and forward-only lifecycle transitions.
+Operation invocation also carries a caller-owned `observationTurnId` and an optional `onOutput`
+sink. An adapter must await that sink for every operation observation. The validated runtime
+admits only operation-scoped progress, context, compaction, operation, resource, warning, error,
+and diagnostic events; it enforces the exact session/observation-turn correlation, immutable
+identity, declared bounds, forward-only lifecycle transitions, and per-output backpressure before
+the operation result may settle. Collaboration and generated-resource observations retain the
+same correlation and lifecycle validation at their respective ports.
 
 ## Minimal driver
 
@@ -163,7 +168,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.3` while the public SPI is being proven with external adapters. Pre-1.0
+The package is at `0.2.4` while the public SPI is being proven with external adapters. Pre-1.0
 releases may include breaking changes during this beta period, and those changes are called out in
 the release notes.
 

package/dist/sessionValidation.js

@@ -507,6 +507,45 @@ function observeTurnOutput(input) {
     contextUsageState: input.contextUsageState
   });
 }
+const SESSION_OPERATION_OBSERVATION_EVENT_TYPES = /* @__PURE__ */ new Set([
+  "item.started",
+  "item.updated",
+  "item.completed",
+  "progress.updated",
+  "context.usage.updated",
+  "operation.updated",
+  "resource.updated",
+  "runtime.warning",
+  "runtime.error",
+  "provider.diagnostic"
+]);
+function observeSessionOperationOutput(input) {
+  if (input.output.kind === "event") {
+    const event = input.output.event;
+    if (!SESSION_OPERATION_OBSERVATION_EVENT_TYPES.has(event.type)) {
+      invalidTurnSequence(
+        input.providerKey,
+        "Provider emitted turn-owned output from a session operation."
+      );
+    }
+    if ((event.type === "item.started" || event.type === "item.updated" || event.type === "item.completed") && event.payload.itemKind !== "context_compaction") {
+      invalidTurnSequence(
+        input.providerKey,
+        "Provider emitted a non-compaction item from a session operation."
+      );
+    }
+  }
+  observeTurnOutput({
+    capabilities: input.capabilities,
+    providerKey: input.providerKey,
+    output: input.output,
+    state: input.state,
+    pendingRequests: /* @__PURE__ */ new Map(),
+    openedRequestIds: /* @__PURE__ */ new Set(),
+    contextUsageState: input.contextUsageState,
+    interactionState: input.interactionState
+  });
+}
 function assertStableTurnBoundary(input) {
   const terminal = input.state.terminal && !input.state.waiting;
   const waiting = !input.state.terminal && input.state.waiting && input.pendingRequests.size === 1;
@@ -718,8 +757,18 @@ function validateAgentProviderSession(input) {
       input2.observer?.();
       executionStarted = true;
     };
+    const onOutput = async (candidate) => {
+      if (!executionStarted) {
+        throwAgentProviderContractError(
+          providerKey,
+          "invalid_operation_result",
+          "Provider emitted operation output before reporting execution start."
+        );
+      }
+      await input2.observeOutput?.(candidate);
+    };
     try {
-      const candidate = await input2.invoke(onProviderExecutionStarted);
+      const candidate = await input2.invoke(onProviderExecutionStarted, onOutput);
       if (!executionStarted) {
         throwAgentProviderContractError(
           providerKey,
@@ -1129,8 +1178,12 @@ function validateAgentProviderSession(input) {
       requireUsable();
       throwIfAgentOperationAborted(operationInput.signal);
       let invocation;
+      let observationTurnId;
       try {
         invocation = parseAgentOperationInvocation(operationInput.invocation);
+        observationTurnId = parseAgentTurnId(
+          operationInput.observationTurnId
+        );
       } catch {
         return throwAgentProviderContractError(
           providerKey,
@@ -1189,6 +1242,16 @@ function validateAgentProviderSession(input) {
       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,
+        waiting: false,
+        finalDiffObserved: false
+      };
       interactionState.operationInvocations.set(
         invocation.invocationId,
         trackedInvocation
@@ -1197,11 +1260,31 @@ function validateAgentProviderSession(input) {
         const result = await delegateProviderMutation({
           operation: "invoke_operation",
           observer: operationInput.onProviderExecutionStarted,
-          invoke: (onProviderExecutionStarted) => declaredOperations.invokeOperation({
+          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,

package/dist/sessions.d.ts

@@ -20,6 +20,7 @@ export interface AgentProviderBranchSessionInput extends AgentProviderSessionCon
     readonly onBindingCreated: AgentSessionBindingCreatedObserver;
 }
 export type AgentProviderExecutionStartedObserver = () => void;
+export type AgentProviderOutputObserver = (output: AgentProviderOutput) => MaybePromise<void>;
 export interface AgentProviderRunTurnInput {
     readonly turnId: AgentTurnId;
     readonly interactionMode: AgentTurnInteractionMode;
@@ -49,8 +50,10 @@ export interface AgentProviderApplyConfigurationSelectionInput {
 }
 export interface AgentProviderInvokeOperationInput {
     readonly invocation: AgentOperationInvocation;
+    readonly observationTurnId: AgentTurnId;
     readonly signal?: AbortSignal;
     readonly onProviderExecutionStarted?: AgentProviderExecutionStartedObserver;
+    readonly onOutput?: AgentProviderOutputObserver;
 }
 export interface AgentProviderSpawnCollaborationInput {
     readonly spawn: AgentCollaborationSpawnInput;

package/dist/testing/conformance.js

@@ -1,6 +1,7 @@
 import {
   matchesAgentSessionBinding,
-  parseAgentRequestResolutionFor
+  parseAgentRequestResolutionFor,
+  parseAgentTurnId
 } from "@agen-ai/agent-protocol";
 import { isAgentOperationAbortError } from "../foundation.js";
 import {
@@ -330,6 +331,9 @@ async function runAgentProviderConformance(scenario) {
       let executionStarted = 0;
       const result = await created.operations.invokeOperation({
         invocation: scenario.operationInvocation,
+        observationTurnId: parseAgentTurnId(
+          scenario.operationInvocation.invocationId
+        ),
         onProviderExecutionStarted: () => {
           executionStarted += 1;
         }

package/package.json

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