@agen-ai/agent-runtime 0.4.0 → 0.4.2

package/dist/sessions.d.ts

@@ -1,8 +1,10 @@
 import type { AgentAuthenticationFlow, AgentCollaborationControlInput, AgentCollaborationNode, AgentCollaborationSpawnInput, AgentConfigurationCatalog, AgentConfigurationSelectionInput, AgentError, AgentGeneratedResourceDescriptor, AgentGeneratedResourceId, AgentManagedContentCatalog, AgentOperationCatalog, AgentOperationInvocation, AgentOperationResult, AgentRequestResolution, AgentSessionBinding, AgentSessionBranchSource, AgentSessionConfiguration, AgentSessionId, AgentTurnId, AgentTurnInputContent, AgentTurnInteractionMode, AgentTurnInputPart, AgentTurnInterruptionReason } from "@agen-ai/agent-protocol";
+import type { AgentNativeContinuationContext, AgentNativeContinuationSupport } from "./nativeContinuations/types.js";
 import type { MaybePromise } from "./foundation.js";
 import type { AgentSessionHostBinding, AgentSessionHostBindingSupport } from "./hostBindings/types.js";
 import type { AgentProviderOutput } from "./outputs.js";
 import type { AgentArtifactCandidate } from "./artifacts.js";
+import type { AgentProviderSessionInteractionContext, AgentSessionInteractionContext, AgentSessionInteractionSupport } from "./sessionInteractions/types.js";
 import type { AgentEnvironmentObservationPort } from "./environment/types.js";
 export interface AgentProviderSessionContext {
     readonly sessionId: AgentSessionId;
@@ -10,6 +12,7 @@ export interface AgentProviderSessionContext {
     readonly configuration: AgentSessionConfiguration;
     readonly signal?: AbortSignal;
     readonly hostBinding?: AgentSessionHostBinding;
+    readonly interactions?: AgentProviderSessionInteractionContext;
 }
 export type AgentSessionBindingCreatedObserver = (binding: AgentSessionBinding) => void;
 export interface AgentProviderCreateSessionInput extends AgentProviderSessionContext {
@@ -212,10 +215,41 @@ export type AgentProviderAuthentication = Readonly<{
     cancel: (input: AgentProviderAuthenticationCancelInput) => MaybePromise<AgentProviderOperationResult>;
 }>;
 export interface AgentProviderAdapter {
+    readonly sessionInteractions?: AgentSessionInteractionSupport;
     readonly hostBinding?: AgentSessionHostBindingSupport;
+    readonly nativeContinuations?: AgentNativeContinuationSupport;
     readonly createSession: (input: AgentProviderCreateSessionInput) => MaybePromise<AgentProviderSession>;
     readonly resumption: AgentSessionResumption;
     readonly branching: AgentSessionBranching;
     readonly authentication: AgentProviderAuthentication;
 }
+export type AgentSessionOpenContext = Omit<AgentProviderSessionContext, "interactions"> & Readonly<{
+    interactions?: AgentSessionInteractionContext;
+    nativeContinuations?: AgentNativeContinuationContext;
+}>;
+export type AgentCreateSessionInput = AgentSessionOpenContext & Readonly<{
+    onBindingCreated: AgentSessionBindingCreatedObserver;
+}>;
+export type AgentResumeSessionInput = AgentSessionOpenContext & Readonly<{
+    binding: AgentSessionBinding;
+}>;
+export type AgentBranchSessionInput = AgentSessionOpenContext & Readonly<{
+    source: AgentSessionBranchSource;
+    onBindingCreated: AgentSessionBindingCreatedObserver;
+}>;
+export type AgentValidatedProviderAdapter = Omit<AgentProviderAdapter, "createSession" | "resumption" | "branching"> & Readonly<{
+    createSession: (input: AgentCreateSessionInput) => MaybePromise<AgentProviderSession>;
+    resumption: Readonly<{
+        kind: "unsupported";
+    }> | Readonly<{
+        kind: "supported";
+        resumeSession: (input: AgentResumeSessionInput) => MaybePromise<AgentProviderSession>;
+    }>;
+    branching: Readonly<{
+        kind: "unsupported";
+    }> | Readonly<{
+        kind: "through_turn";
+        branchSession: (input: AgentBranchSessionInput) => MaybePromise<AgentProviderSession>;
+    }>;
+}>;
 //# sourceMappingURL=sessions.d.ts.map

package/dist/testing/conformance.d.ts

@@ -18,7 +18,9 @@ export interface AgentProviderConformanceScenario {
     readonly interruptionSessionId: AgentSessionId;
     readonly turn: AgentProviderStartTurnInput;
     readonly interruptionTurn: AgentProviderStartTurnInput;
-    readonly resolutionFor: (request: AgentRequest) => AgentRequestResolution;
+    readonly resolutionFor: (request: AgentRequest, context: Readonly<{
+        signal: AbortSignal;
+    }>) => AgentRequestResolution | undefined | Promise<AgentRequestResolution | undefined>;
     readonly branchSource?: (binding: AgentSessionBinding, turnId: AgentTurnId) => AgentSessionBranchSource;
     readonly steeringInput?: AgentTurnInputContent;
 }

package/dist/testing/conformance.js

@@ -15,7 +15,6 @@ class AgentProviderConformanceError extends Error {
     this.check = check;
     this.name = "AgentProviderConformanceError";
   }
-  check;
 }
 function requireCheck(condition, check, message) {
   if (!condition) throw new AgentProviderConformanceError(check, message);
@@ -51,25 +50,104 @@ async function advanceToStartedTurn(session, input) {
       );
       outputs.push(next.value);
       if (next.value.kind === "event" && next.value.event.type === "turn.started") {
-        return { execution, iterator, outputs };
+        return { session, execution, iterator, outputs };
       }
     }
   } catch (error) {
-    await iterator.return?.();
+    const closing = session.close({ reason: "contract_rejected" });
+    const settled = await Promise.allSettled([closing, iterator.return?.()]);
+    const failures = settled.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+    if (failures.length > 0) throw new AggregateError([error, ...failures], "Conformance opening and cleanup failed.", { cause: error });
     throw error;
   }
 }
-async function collectRemainingOutputs(started, resolutionFor) {
-  for (; ; ) {
-    const next = await started.iterator.next();
-    if (next.done) return started.outputs;
-    started.outputs.push(next.value);
-    if (next.value.kind === "event" && next.value.event.type === "request.opened" && resolutionFor) {
-      const request = next.value.event.payload.request;
-      const receipt = await started.execution.resolveRequest({ resolution: parseAgentRequestResolutionFor(request, resolutionFor(request)) });
-      requireCheck(receipt.status === "delivered", "request_resolution", "Matching request answer was not accepted by the provider handler.");
+async function collectRemainingOutputs(started, resolutionFor, beforeClose) {
+  const requests = /* @__PURE__ */ new Map();
+  const tasks = [];
+  let acceptingRequests = true;
+  let deliveredRequests = 0;
+  let failTask;
+  const taskFailure = new Promise((_resolve, reject) => {
+    failTask = reject;
+  });
+  const abortRequests = () => {
+    for (const controller of requests.values()) {
+      controller.abort(new DOMException("Conformance request is no longer answerable.", "AbortError"));
+    }
+  };
+  const resolve = async (request, signal) => {
+    if (!resolutionFor) return;
+    let resolution;
+    try {
+      resolution = await resolutionFor(request, { signal });
+    } catch (error) {
+      if (signal.aborted && isAgentOperationAbortError(error)) return;
+      throw error;
     }
+    if (resolution === void 0 || signal.aborted) return;
+    const receipt = await started.execution.resolveRequest({
+      resolution: parseAgentRequestResolutionFor(request, resolution)
+    });
+    requireCheck(
+      receipt.status === "delivered",
+      "request_resolution",
+      "Matching request answer was not accepted by the provider handler."
+    );
+    deliveredRequests += 1;
+  };
+  const reader = (async () => {
+    for (; ; ) {
+      const next = await started.iterator.next();
+      if (next.done || !acceptingRequests) return;
+      started.outputs.push(next.value);
+      if (next.value.kind !== "event") continue;
+      const event = next.value.event;
+      if (event.type === "request.opened" && resolutionFor) {
+        const request = event.payload.request;
+        const controller = new AbortController();
+        requests.set(request.requestId, controller);
+        const task = resolve(request, controller.signal);
+        tasks.push(task);
+        void task.catch((error) => {
+          acceptingRequests = false;
+          failTask(error);
+        });
+      } else if (event.type === "request.unavailable") {
+        requests.get(event.payload.requestId)?.abort(
+          new DOMException("The provider retired this conformance request.", "AbortError")
+        );
+        requests.delete(event.payload.requestId);
+      } else if (event.type === "turn.completed") {
+        abortRequests();
+        return;
+      }
+    }
+  })();
+  const checked = reader.then(async () => {
+    if (acceptingRequests) await beforeClose?.();
+  });
+  const failures = /* @__PURE__ */ new Set();
+  try {
+    await Promise.race([checked, taskFailure]);
+  } catch (error) {
+    failures.add(error);
+  }
+  acceptingRequests = false;
+  abortRequests();
+  const closing = started.session.close({ reason: failures.size > 0 ? "contract_rejected" : "idle" });
+  const [closed, read, inspected, returned] = await Promise.allSettled([closing, reader, checked, started.iterator.return?.()]);
+  if (closed?.status === "rejected") failures.add(closed.reason);
+  for (const result of [read, inspected]) {
+    if (result?.status === "rejected" && !(failures.size > 0 && isAgentOperationAbortError(result.reason))) failures.add(result.reason);
   }
+  if (returned?.status === "rejected") failures.add(returned.reason);
+  const joined = await Promise.allSettled(tasks);
+  for (const result of joined) {
+    if (result.status === "rejected") failures.add(result.reason);
+  }
+  if (failures.size === 1) throw failures.values().next().value;
+  if (failures.size > 1) throw new AggregateError(failures, "Conformance and owned cleanup failed.", { cause: failures.values().next().value });
+  return { outputs: started.outputs, deliveredRequests };
 }
 function requireOperationStatus(result, statuses, check, message) {
   requireCheck(statuses.includes(result.status), check, message);
@@ -111,6 +189,7 @@ async function runAgentProviderConformance(scenario) {
   });
   let disposed = false;
   let createdSession = null;
+  let failure;
   try {
     const instance = registry.requireInstance(scenario.definition.instanceId);
     requireCheck(
@@ -277,55 +356,7 @@ async function runAgentProviderConformance(scenario) {
       );
       checks.push("abort");
     }
-    const startedTurn = await advanceToStartedTurn(created, scenario.turn);
-    let turnOutputs;
-    try {
-      if (instance.capabilities.turns.steer.kind === "supported") {
-        requireCheck(
-          created.steering.kind === "supported",
-          "steering",
-          "Steering capability has no handler."
-        );
-        const result = await created.steering.steerTurn({
-          turnId: scenario.turn.turnId,
-          ...scenario.steeringInput ?? {
-            parts: [
-              { type: "text", text: "Additional conformance input." }
-            ]
-          }
-        });
-        requireCheck(
-          result.status === "delivered",
-          "steering",
-          "Steering did not deliver to the live turn."
-        );
-      } else {
-        requireCheck(
-          created.steering.kind === "unsupported",
-          "steering",
-          "Unsupported steering exposed a handler."
-        );
-      }
-      turnOutputs = await collectRemainingOutputs(startedTurn, scenario.resolutionFor);
-    } catch (error) {
-      await startedTurn.iterator.return?.();
-      await created.close({ reason: "contract_rejected" });
-      throw error;
-    }
-    const events = semanticEvents(turnOutputs);
-    requireCheck(
-      events[0]?.type === "turn.started",
-      "turn_order",
-      "Turn did not start first."
-    );
-    requireCheck(
-      hasStableTurnBoundary(events),
-      "turn_order",
-      "Turn did not terminate or enter a waiting state."
-    );
-    checks.push("turn_order");
-    if (events.some((event) => event.type === "request.opened")) checks.push("request_resolution");
-    checks.push("steering");
+    const turnChecksIndex = checks.length;
     if (instance.capabilities.turns.interrupt) {
       let interruptedBindingCount = 0;
       const interrupted = await instance.adapter.createSession({
@@ -363,15 +394,15 @@ async function runAgentProviderConformance(scenario) {
           "interruption",
           "Live turn interruption did not succeed."
         );
-        const outputs = await collectRemainingOutputs(liveTurn);
+        const { outputs } = await collectRemainingOutputs(liveTurn);
         requireCheck(
           semanticEvents(outputs).some((event) => event.type === "turn.completed"),
           "interruption",
           "Interrupted turn did not produce native terminal output."
         );
       } finally {
-        await liveTurn?.iterator.return?.();
-        await interrupted.close({ reason: "other" });
+        const closing = interrupted.close({ reason: "other" });
+        await Promise.all([closing, liveTurn?.iterator.return?.()]);
       }
     } else {
       requireCheck(
@@ -527,28 +558,83 @@ async function runAgentProviderConformance(scenario) {
       );
     }
     checks.push("collaboration");
-    if (instance.capabilities.generatedResources.kind === "supported") {
-      requireCheck(
-        created.generatedResources.kind === "supported" && scenario.generatedResourceId !== void 0,
-        "generated_resources",
-        "Supported generated resources require an access port and fixture."
-      );
-      const resource = await created.generatedResources.getGeneratedResource({
-        resourceId: scenario.generatedResourceId
+    const turnChecks = [];
+    const startedTurn = await advanceToStartedTurn(created, scenario.turn);
+    let turnResult;
+    try {
+      if (instance.capabilities.turns.steer.kind === "supported") {
+        requireCheck(
+          created.steering.kind === "supported",
+          "steering",
+          "Steering capability has no handler."
+        );
+        const result = await created.steering.steerTurn({
+          turnId: scenario.turn.turnId,
+          ...scenario.steeringInput ?? {
+            parts: [
+              { type: "text", text: "Additional conformance input." }
+            ]
+          }
+        });
+        requireCheck(
+          result.status === "delivered",
+          "steering",
+          "Steering did not deliver to the live turn."
+        );
+      } else {
+        requireCheck(
+          created.steering.kind === "unsupported",
+          "steering",
+          "Unsupported steering exposed a handler."
+        );
+      }
+      turnResult = await collectRemainingOutputs(startedTurn, scenario.resolutionFor, async () => {
+        if (instance.capabilities.generatedResources.kind === "supported") {
+          requireCheck(
+            created.generatedResources.kind === "supported" && scenario.generatedResourceId !== void 0,
+            "generated_resources",
+            "Supported generated resources require an access port and fixture."
+          );
+          const resource = await created.generatedResources.getGeneratedResource({
+            resourceId: scenario.generatedResourceId
+          });
+          requireCheck(
+            resource.descriptor.resourceId === scenario.generatedResourceId,
+            "generated_resources",
+            "Generated resource access returned another resource."
+          );
+        } else {
+          requireCheck(
+            created.generatedResources.kind === "unsupported",
+            "generated_resources",
+            "Unsupported generated resources exposed an access port."
+          );
+        }
+        checks.push("generated_resources");
       });
-      requireCheck(
-        resource.descriptor.resourceId === scenario.generatedResourceId,
-        "generated_resources",
-        "Generated resource access returned another resource."
-      );
-    } else {
-      requireCheck(
-        created.generatedResources.kind === "unsupported",
-        "generated_resources",
-        "Unsupported generated resources exposed an access port."
-      );
+    } catch (error) {
+      const closing = created.close({ reason: "contract_rejected" });
+      const settled = await Promise.allSettled([closing, startedTurn.iterator.return?.()]);
+      const failures = settled.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+      if (failures.length > 0) throw new AggregateError([error, ...failures], "Conformance turn and cleanup failed.", { cause: error });
+      throw error;
     }
-    checks.push("generated_resources");
+    const events = semanticEvents(turnResult.outputs);
+    requireCheck(
+      events[0]?.type === "turn.started",
+      "turn_order",
+      "Turn did not start first."
+    );
+    requireCheck(
+      hasStableTurnBoundary(events),
+      "turn_order",
+      "Turn did not terminate or enter a waiting state."
+    );
+    turnChecks.push("turn_order");
+    if (turnResult.deliveredRequests > 0) turnChecks.push("request_resolution");
+    if (events.some((event) => event.type === "request.unavailable")) turnChecks.push("request_unavailability");
+    turnChecks.push("steering");
+    checks.splice(turnChecksIndex, 0, ...turnChecks);
     await created.close({ reason: "idle" });
     await created.close({ reason: "idle" });
     checks.push("idempotent_session_close");
@@ -621,9 +707,17 @@ async function runAgentProviderConformance(scenario) {
       providerKey: scenario.definition.providerKey,
       checks: Object.freeze(checks)
     });
+  } catch (error) {
+    failure = { error };
+    throw error;
   } finally {
-    await createdSession?.close({ reason: "contract_rejected" });
-    if (!disposed) await registry.dispose();
+    try {
+      await createdSession?.close({ reason: "contract_rejected" });
+      if (!disposed) await registry.dispose();
+    } catch (error) {
+      if (failure) throw new AggregateError([failure.error, error], "Conformance and final cleanup failed.", { cause: failure.error });
+      throw error;
+    }
   }
 }
 export {

package/dist/testing/fakeProvider.js

@@ -44,7 +44,7 @@ function defaultCapabilities(providerKey) {
     }
   };
   return parseAgentCapabilities({
-    protocolVersion: 10,
+    protocolVersion: 12,
     providerKey,
     sessions: { create: true, resume: true, branch: { kind: "through_turn" } },
     turns: {
@@ -55,6 +55,7 @@ function defaultCapabilities(providerKey) {
     requests: {
       approval: {
         kind: "supported",
+        providerManagedRemembrance: false,
         modes: [{ persistence: "once", scopeKinds: ["exact_action"] }]
       },
       elicitation: {
@@ -165,7 +166,7 @@ function sessionBinding(state, sessionId) {
   };
 }
 function eventBase(sessionId, turnId, occurredAt) {
-  return { protocolVersion: 10, sessionId, turnId, occurredAt };
+  return { protocolVersion: 12, sessionId, turnId, occurredAt };
 }
 function fakeEnvironmentSnapshot(environmentId) {
   return parseAgentEnvironmentSnapshot({
@@ -251,15 +252,13 @@ function requestForTurn(turnId) {
         optionId: parseAgentApprovalOptionId("approval:allow-once"),
         label: "Allow once",
         decision: "approved",
-        persistence: "once",
-        scope: { kind: "exact_action" }
+        consequence: { kind: "scoped", persistence: "once", scope: { kind: "exact_action" } }
       },
       {
         optionId: parseAgentApprovalOptionId("approval:deny-once"),
         label: "Deny",
         decision: "denied",
-        persistence: "once",
-        scope: { kind: "exact_action" }
+        consequence: { kind: "scoped", persistence: "once", scope: { kind: "exact_action" } }
       }
     ]
   };

package/dist/turnExecution/execution.d.ts

@@ -1,26 +1,43 @@
-import { type AgentProviderKey } from "@agen-ai/agent-protocol";
+import { type AgentProviderKey, type AgentTurnId } from "@agen-ai/agent-protocol";
 import type { AgentProviderOutput } from "../outputs.js";
+import type { AgentSessionAdmission } from "../sessionAdmission.js";
 import type { AgentProviderStartTurnInput, AgentProviderTurnExecution } from "../sessions.js";
-import { type PendingAgentRequest, type SuspendedAgentTurnRequests } from "./requests.js";
+import { type AgentTurnRequestAdmission, type PendingAgentRequest, type SuspendedAgentTurnRequests } from "./requests.js";
 export interface ValidatedAgentTurnExecution {
     readonly execution: AgentProviderTurnExecution;
     readonly hasEntered: () => boolean;
     readonly stop: (reason: Error) => void;
     readonly join: () => Promise<void>;
     readonly suspendRequests: () => SuspendedAgentTurnRequests;
+    readonly completed: Promise<void>;
 }
-export declare function createValidatedAgentTurnExecution(input: Readonly<{
+type ExecutionOptions = Readonly<{
     providerKey: AgentProviderKey;
-    turnInput: AgentProviderStartTurnInput;
     pendingRequests: Map<string, PendingAgentRequest>;
+    sessionAdmission: AgentSessionAdmission;
     inFlightOperations: Set<Promise<void>>;
-    start: (input: AgentProviderStartTurnInput) => AgentProviderTurnExecution;
     requireUsable: () => void;
     isTerminal: () => boolean;
-    observe: (output: AgentProviderOutput) => AgentProviderOutput;
+    canRestoreRequest: (pending: PendingAgentRequest) => boolean;
+    observe: (output: AgentProviderOutput, requests: AgentTurnRequestAdmission) => AgentProviderOutput;
     assertCompleted: () => void;
     release: () => void;
     retire: () => void;
     abandon: () => Promise<void>;
+}>;
+export declare function createValidatedAgentTurnExecution(input: ExecutionOptions & Readonly<{
+    turnInput: AgentProviderStartTurnInput;
+    start: (input: AgentProviderStartTurnInput) => AgentProviderTurnExecution;
 }>): ValidatedAgentTurnExecution;
+export interface AdoptedAgentTurnExecution extends ValidatedAgentTurnExecution {
+    readonly readerReady: Promise<void>;
+    readonly admitDispatch: () => void;
+    readonly settleNoWork: () => void;
+    readonly markStarted: () => void;
+}
+export declare function adoptValidatedAgentTurnExecution(input: ExecutionOptions & Readonly<{
+    turnId: AgentTurnId;
+    createCandidate: (signal: AbortSignal) => AgentProviderTurnExecution;
+}>): AdoptedAgentTurnExecution;
+export {};
 //# sourceMappingURL=execution.d.ts.map