@agen-ai/agent-runtime 0.4.0 → 0.4.1

package/dist/sessionInteractions/validation.js

@@ -0,0 +1,119 @@
+import path from "node:path";
+import {
+  parseAgentError,
+  parseAgentSessionDecisionChoiceId,
+  parseAgentSessionDecisionRequest
+} from "@agen-ai/agent-protocol";
+import { AgentProviderContractError } from "../contractErrors.js";
+import { hasExactOwnKeys } from "../internal/objectShape.js";
+import {
+  DEFAULT_AGENT_SESSION_INTERACTION_LIMITS
+} from "./types.js";
+function record(input) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) throw new TypeError("Expected an interaction object.");
+  return input;
+}
+function interactionContractError(providerKey, message) {
+  return new AgentProviderContractError(providerKey, "invalid_session_interaction", message);
+}
+function validateSessionInteractionSupport(capabilities, adapter) {
+  const input = adapter.sessionInteractions;
+  if (input === void 0) return Object.freeze({ kind: "unsupported" });
+  try {
+    const value = record(input);
+    if (value.kind === "unsupported" && hasExactOwnKeys(value, ["kind"])) return Object.freeze({ kind: "unsupported" });
+    if (!hasExactOwnKeys(value, ["kind", "openingOperations", "requestKinds", "producerOwnership"]) || value.kind !== "supported" || value.producerOwnership !== "exclusive" || !Array.isArray(value.openingOperations) || value.openingOperations.length === 0 || !Array.isArray(value.requestKinds) || value.requestKinds.length !== 1 || value.requestKinds[0] !== "decision") throw new TypeError();
+    const operations = [];
+    for (const operation of value.openingOperations) {
+      if (operation !== "create" && operation !== "resume" && operation !== "branch") throw new TypeError();
+      if (operations.includes(operation)) throw new TypeError();
+      if (operation === "resume" && (!capabilities.sessions.resume || adapter.resumption.kind !== "supported")) throw new TypeError();
+      if (operation === "branch" && (capabilities.sessions.branch.kind !== "through_turn" || adapter.branching.kind !== "through_turn")) throw new TypeError();
+      operations.push(operation);
+    }
+    const order = ["create", "resume", "branch"];
+    if (operations.some((operation, index) => index > 0 && order.indexOf(operation) < order.indexOf(operations[index - 1]))) throw new TypeError();
+    const [first, ...rest] = operations;
+    if (first === void 0) throw new TypeError();
+    return Object.freeze({
+      kind: "supported",
+      producerOwnership: "exclusive",
+      openingOperations: Object.freeze([first, ...rest]),
+      requestKinds: Object.freeze(["decision"])
+    });
+  } catch {
+    throw interactionContractError(capabilities.providerKey, "Provider declared invalid session interaction support.");
+  }
+}
+const limitRanges = {
+  maxRetainedRequests: [1, 32],
+  maxRetainedBytes: [65536, 2097152],
+  requestTimeoutMs: [1e3, 18e5],
+  responseTimeoutMs: [1e3, 12e4],
+  cleanupTimeoutMs: [1e3, 12e4]
+};
+function validateSessionInteractionContext(input) {
+  const value = record(input);
+  const onRequest = value.onRequest;
+  if (!hasExactOwnKeys(value, Object.hasOwn(value, "limits") ? ["onRequest", "limits"] : ["onRequest"]) || typeof onRequest !== "function") throw new TypeError("Session interactions require a callable handler and known fields.");
+  const supplied = value.limits === void 0 ? {} : record(value.limits);
+  if (Reflect.ownKeys(supplied).some((key) => typeof key !== "string" || !Object.hasOwn(limitRanges, key))) {
+    throw new TypeError("Session interaction limits contain an unknown field.");
+  }
+  const limits = { ...DEFAULT_AGENT_SESSION_INTERACTION_LIMITS };
+  for (const key of Object.keys(limitRanges)) {
+    const number = supplied[key];
+    if (number === void 0) continue;
+    const [minimum, maximum] = limitRanges[key];
+    if (typeof number !== "number" || !Number.isSafeInteger(number) || number < minimum || number > maximum) {
+      throw new RangeError(`Session interaction ${key} must be an integer between ${minimum} and ${maximum}.`);
+    }
+    limits[key] = number;
+  }
+  return Object.freeze({ onRequest: onRequest.bind(input), limits: Object.freeze(limits) });
+}
+function captureSessionInteractionCandidate(input, observe) {
+  const value = record(input);
+  const terminal = value.terminal;
+  const observation = Promise.resolve(terminal);
+  void observation.catch(() => {
+  });
+  observe(observation);
+  const request = value.request;
+  const signal = value.signal;
+  const respond = value.respond;
+  if (!hasExactOwnKeys(value, ["request", "signal", "terminal", "respond"]) || !(signal instanceof AbortSignal) || typeof respond !== "function" || !terminal || typeof record(terminal).then !== "function") throw new TypeError("Provider offered an invalid session interaction handle.");
+  return Object.freeze({
+    request,
+    signal,
+    terminal: observation,
+    respond: respond.bind(input)
+  });
+}
+function validateSessionInteractionCandidate(input, sessionId, requestTimeoutMs) {
+  const parsed = parseAgentSessionDecisionRequest(input.request);
+  if (parsed.sessionId !== sessionId || !path.isAbsolute(parsed.target.path) || path.normalize(parsed.target.path) !== parsed.target.path) {
+    throw new TypeError("Session interaction does not match its session or canonical workspace target.");
+  }
+  const expiry = Math.min(Date.parse(parsed.expiresAt), Date.now() + requestTimeoutMs);
+  if (expiry <= Date.now()) throw new TypeError("Provider offered an expired session interaction.");
+  const request = parseAgentSessionDecisionRequest({ ...parsed, expiresAt: new Date(expiry).toISOString() });
+  return Object.freeze({ ...input, request });
+}
+function validateSessionInteractionTerminal(input) {
+  const value = record(input);
+  if (value.kind === "answered" && hasExactOwnKeys(value, ["kind", "choiceId"])) {
+    return Object.freeze({ kind: "answered", choiceId: parseAgentSessionDecisionChoiceId(value.choiceId) });
+  }
+  if ((value.kind === "failed" || value.kind === "rejected" || value.kind === "delivery_uncertain") && hasExactOwnKeys(value, ["kind", "error"])) return Object.freeze({ kind: value.kind, error: parseAgentError(value.error) });
+  if ((value.kind === "withdrawn" || value.kind === "expired" || value.kind === "session_closed") && hasExactOwnKeys(value, ["kind"])) return Object.freeze({ kind: value.kind });
+  throw new TypeError("Provider returned an invalid session interaction terminal.");
+}
+export {
+  captureSessionInteractionCandidate,
+  interactionContractError,
+  validateSessionInteractionCandidate,
+  validateSessionInteractionContext,
+  validateSessionInteractionSupport,
+  validateSessionInteractionTerminal
+};

package/dist/sessionValidation.d.ts

@@ -2,6 +2,7 @@ import { type AgentCapabilities, type AgentProviderKey, type AgentSessionBinding
 import { type AgentHostBindingLease } from "./hostBindings/lifetime.js";
 import { type MaybePromise } from "./foundation.js";
 import type { AgentProviderSession, AgentSessionBindingCreatedObserver } from "./sessions.js";
+import type { SessionInteractionOwner } from "./sessionInteractions/lifetime.js";
 export declare function validateAgentProviderSession(input: {
     readonly capabilities: AgentCapabilities;
     readonly sessionId: AgentSessionId;
@@ -9,6 +10,7 @@ export declare function validateAgentProviderSession(input: {
     readonly expectedBinding?: AgentSessionBinding;
     readonly sourceBinding?: AgentSessionBinding;
     readonly hostBindingLease?: AgentHostBindingLease;
+    readonly sessionInteractionOwner?: SessionInteractionOwner;
 }): AgentProviderSession;
 export declare function closeRejectedAgentProviderSession(session: AgentProviderSession | null, error: unknown, hostBinding?: Readonly<{
     providerKey: AgentProviderKey;
@@ -16,7 +18,7 @@ export declare function closeRejectedAgentProviderSession(session: AgentProvider
 }>, opening?: Readonly<{
     providerKey: AgentProviderKey;
     input: object;
-}>): Promise<never>;
+}>, interactions?: SessionInteractionOwner): Promise<never>;
 export declare function openIdentityCreatingAgentProviderSession(input: {
     readonly capabilities: AgentCapabilities;
     readonly sessionId: AgentSessionId;
@@ -24,6 +26,7 @@ export declare function openIdentityCreatingAgentProviderSession(input: {
     readonly sourceBinding?: AgentSessionBinding;
     readonly hostBindingLease?: AgentHostBindingLease;
     readonly openingInput?: object;
+    readonly sessionInteractionOwner?: SessionInteractionOwner;
     readonly open: (observer: AgentSessionBindingCreatedObserver) => MaybePromise<AgentProviderSession>;
 }): Promise<AgentProviderSession>;
 //# sourceMappingURL=sessionValidation.d.ts.map

package/dist/sessionValidation.js

@@ -46,6 +46,11 @@ import {
 import { validateAgentTurnSteeringResult } from "./steeringValidation.js";
 import { createValidatedAgentTurnExecution } from "./turnExecution/execution.js";
 import { validateAgentProviderTurnInterruptionResult } from "./turnExecution/receipts.js";
+function validateCloseReason(reason) {
+  if (reason !== void 0 && !["idle", "shutdown", "replaced", "contract_rejected", "error", "other"].includes(reason)) {
+    throw new TypeError("Provider session close reason is unsupported.");
+  }
+}
 function validateSessionPorts(capabilities, session) {
   if (!hasExactOwnKeys(session, [
     "binding",
@@ -703,6 +708,7 @@ function validateAgentProviderSession(input) {
       );
   };
   const requireUsable = () => {
+    input.sessionInteractionOwner?.requireUsable();
     requireOpen();
     if (unusable) {
       throwAgentProviderContractError(
@@ -742,6 +748,7 @@ function validateAgentProviderSession(input) {
       await input2.observeOutput?.(candidate);
     };
     try {
+      requireUsable();
       const candidate = await input2.invoke(onProviderExecutionStarted, onOutput);
       if (!executionStarted) {
         throwAgentProviderContractError(
@@ -1386,39 +1393,34 @@ function validateAgentProviderSession(input) {
       return inspection;
     }
   });
-  const close = (closeInput) => {
-    if (closed) return Promise.resolve();
-    if (closePromise) return closePromise;
+  const closeOwned = (closeInput, explicit) => {
+    if (closed && !input.sessionInteractionOwner) return Promise.resolve();
+    if (!input.sessionInteractionOwner && closePromise) return closePromise;
     throwIfAgentOperationAborted(closeInput.signal);
-    if (closeInput.reason !== void 0 && ![
-      "idle",
-      "shutdown",
-      "replaced",
-      "contract_rejected",
-      "error",
-      "other"
-    ].includes(closeInput.reason)) {
-      throw new TypeError("Provider session close reason is unsupported.");
-    }
+    validateCloseReason(closeInput.reason);
     unusable = true;
     sessionLifetime.abort(new DOMException("The provider session was closed.", "AbortError"));
     input.hostBindingLease?.stop();
     const closingTurn = activeTurn;
     closingTurn?.owner.stop(new DOMException("The provider session was closed.", "AbortError"));
-    closePromise = Promise.resolve().then(async () => {
+    const cleanup = async () => {
       if (!providerClosed) {
         await input.candidate.close(closeInput);
         providerClosed = true;
       }
+      await input.sessionInteractionOwner?.join();
       await closingTurn?.owner.join();
       await input.hostBindingLease?.release();
-    }).then(() => {
       closed = true;
-    }).finally(() => {
+    };
+    if (input.sessionInteractionOwner) return input.sessionInteractionOwner.close(cleanup, explicit);
+    closePromise = Promise.resolve().then(cleanup).finally(() => {
       closePromise = null;
     });
     return closePromise;
   };
+  const close = (closeInput) => closeOwned(closeInput, true);
+  input.sessionInteractionOwner?.installClose(() => closeOwned({ reason: "error" }, false));
   return Object.freeze({
     binding,
     startTurn,
@@ -1433,9 +1435,10 @@ function validateAgentProviderSession(input) {
     close
   });
 }
-async function closeRejectedAgentProviderSession(session, error, hostBinding, opening) {
+async function closeRejectedAgentProviderSession(session, error, hostBinding, opening, interactions) {
   if (!session) throw error;
   hostBinding?.lease.stop();
+  interactions?.stop();
   let providerClosed = false;
   const cleanup = async () => {
     if (!providerClosed) {
@@ -1445,24 +1448,26 @@ async function closeRejectedAgentProviderSession(session, error, hostBinding, op
       await session.close({ reason: "contract_rejected" });
       providerClosed = true;
     }
+    await interactions?.join();
     await hostBinding?.lease.release();
   };
   try {
-    await cleanup();
+    if (interactions) await interactions.close(cleanup, false);
+    else await cleanup();
   } catch (cleanupError) {
     if (hostBinding) {
       const retained = createAgentHostBindingCleanupError({
         providerKey: hostBinding.providerKey,
         lease: hostBinding.lease,
         errors: [error, cleanupError],
-        retryCleanup: cleanup
+        retryCleanup: () => interactions ? interactions.close(cleanup, false) : cleanup()
       });
       throw opening ? associateAgentSessionCleanupError(retained, opening.input) : retained;
     }
     if (opening) throw associateAgentSessionCleanupError(new AgentProviderSessionCleanupError({
       providerKey: opening.providerKey,
       errors: [error, cleanupError],
-      retryCleanup: cleanup
+      retryCleanup: () => interactions ? interactions.close(cleanup, false) : cleanup()
     }), opening.input);
     throw new AggregateError(
       [error, cleanupError],
@@ -1533,10 +1538,12 @@ async function openIdentityCreatingAgentProviderSession(input) {
       capabilities: input.capabilities,
       sessionId: input.sessionId,
       candidate,
+      ...input.sessionInteractionOwner === void 0 ? {} : { sessionInteractionOwner: input.sessionInteractionOwner },
       ...input.hostBindingLease === void 0 ? {} : { hostBindingLease: input.hostBindingLease },
       ...input.sourceBinding === void 0 ? {} : { sourceBinding: input.sourceBinding }
     });
     tracker.requireMatch(session.binding);
+    input.sessionInteractionOwner?.adopt();
     return session;
   } catch (error) {
     return closeRejectedAgentProviderSession(
@@ -1546,7 +1553,8 @@ async function openIdentityCreatingAgentProviderSession(input) {
         providerKey: input.capabilities.providerKey,
         lease: input.hostBindingLease
       },
-      input.openingInput === void 0 ? void 0 : { providerKey: input.capabilities.providerKey, input: input.openingInput }
+      input.openingInput === void 0 ? void 0 : { providerKey: input.capabilities.providerKey, input: input.openingInput },
+      input.sessionInteractionOwner
     );
   }
 }

package/dist/sessions.d.ts

@@ -3,6 +3,7 @@ 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 { AgentSessionInteractionContext, AgentSessionInteractionSupport } from "./sessionInteractions/types.js";
 import type { AgentEnvironmentObservationPort } from "./environment/types.js";
 export interface AgentProviderSessionContext {
     readonly sessionId: AgentSessionId;
@@ -10,6 +11,7 @@ export interface AgentProviderSessionContext {
     readonly configuration: AgentSessionConfiguration;
     readonly signal?: AbortSignal;
     readonly hostBinding?: AgentSessionHostBinding;
+    readonly interactions?: AgentSessionInteractionContext;
 }
 export type AgentSessionBindingCreatedObserver = (binding: AgentSessionBinding) => void;
 export interface AgentProviderCreateSessionInput extends AgentProviderSessionContext {
@@ -212,6 +214,7 @@ export type AgentProviderAuthentication = Readonly<{
     cancel: (input: AgentProviderAuthenticationCancelInput) => MaybePromise<AgentProviderOperationResult>;
 }>;
 export interface AgentProviderAdapter {
+    readonly sessionInteractions?: AgentSessionInteractionSupport;
     readonly hostBinding?: AgentSessionHostBindingSupport;
     readonly createSession: (input: AgentProviderCreateSessionInput) => MaybePromise<AgentProviderSession>;
     readonly resumption: AgentSessionResumption;

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);

package/dist/testing/fakeProvider.js

@@ -44,7 +44,7 @@ function defaultCapabilities(providerKey) {
     }
   };
   return parseAgentCapabilities({
-    protocolVersion: 10,
+    protocolVersion: 11,
     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: 11, 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/requests.js

@@ -25,7 +25,7 @@ function createAgentTurnRequestAdmission(input) {
   };
   const suspend = () => {
     const suspendedGeneration = generation;
-    const suspension = /* @__PURE__ */ Symbol("interruption");
+    const suspension = Symbol("interruption");
     suspendedGeneration.suspensions.add(suspension);
     for (const [requestId, pending] of input.pendingRequests) {
       suspendedGeneration.withheldRequests.set(requestId, pending);

package/package.json

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