@agen-ai/agent-runtime 0.4.0 → 0.4.2

package/dist/sessionInteractions/request.js

@@ -0,0 +1,381 @@
+import { parseAgentSessionResponseFor } from "@agen-ai/agent-protocol";
+import { throwIfAgentOperationAborted } from "../foundation.js";
+import { AgentProviderContractError } from "../contractErrors.js";
+import { validateAgentRequestResolutionResult } from "../turnExecution/receipts.js";
+import { sessionInteractionError } from "./lifetime.js";
+import { dispatchPreparedSessionResponse, mintSessionResponseAttemptId } from "../nativeContinuations/admission.js";
+import { interactionContractError, validateSessionInteractionTerminal } from "./validation.js";
+const MAX_EXPIRY_TIMER_DELAY_MS = 2147483647;
+class SessionInteractionRequest {
+  constructor(owner, candidate, retire) {
+    this.owner = owner;
+    this.candidate = candidate;
+    this.retire = retire;
+    const terminal = new Promise((resolve) => {
+      this.resolveTerminal = resolve;
+    });
+    this.handle = Object.freeze({
+      request: candidate.request,
+      deadline: candidate.deadline,
+      signal: this.presentation.signal,
+      terminal,
+      respond: (input) => this.respond(input)
+    });
+  }
+  handle;
+  state = { kind: "pending" };
+  presentation = new AbortController();
+  resolveTerminal;
+  callback;
+  callbackSettled = false;
+  responseWork = 0;
+  rawTerminalSettled = false;
+  nativeTerminal;
+  lastAttempt;
+  stopped;
+  unavailable = false;
+  retired = false;
+  expiryTimer;
+  terminalTimer;
+  nativeAborted = () => {
+    this.unavailable = true;
+    this.presentation.abort(new DOMException("The provider interaction was stopped.", "AbortError"));
+    this.expectTerminal();
+  };
+  observe() {
+    this.candidate.signal.addEventListener("abort", this.nativeAborted, { once: true });
+    void this.candidate.terminal.then((candidate) => {
+      this.rawTerminalSettled = true;
+      if (this.terminalTimer) clearTimeout(this.terminalTimer);
+      try {
+        this.nativeTerminal = validateSessionInteractionTerminal(candidate);
+        this.observeTerminal();
+      } catch (cause) {
+        this.protocolFailure(cause);
+      }
+      this.maybeRetire();
+    }, (cause) => {
+      this.rawTerminalSettled = true;
+      if (this.terminalTimer) clearTimeout(this.terminalTimer);
+      this.protocolFailure(cause);
+      this.maybeRetire();
+    });
+    if (this.candidate.signal.aborted) this.nativeAborted();
+    this.scheduleExpiry();
+  }
+  setCallback(callback) {
+    this.callback = callback;
+    void callback.then(
+      () => {
+        this.callbackSettled = true;
+        this.maybeRetire();
+      },
+      () => {
+        this.callbackSettled = true;
+        this.maybeRetire();
+      }
+    );
+  }
+  scheduleExpiry() {
+    if (this.candidate.deadlineAt === void 0 || this.state.kind === "terminal") return;
+    const remainingMs = this.candidate.deadlineAt - Date.now();
+    if (remainingMs <= 0) {
+      this.expire();
+      return;
+    }
+    this.expiryTimer = setTimeout(() => {
+      this.expiryTimer = void 0;
+      this.scheduleExpiry();
+    }, Math.min(remainingMs, MAX_EXPIRY_TIMER_DELAY_MS));
+  }
+  expire() {
+    if (this.state.kind === "terminal") return;
+    this.stop(Object.freeze({ kind: "expired", source: this.candidate.deadline.kind === "deadline" ? this.candidate.deadline.source : "provider" }));
+    this.owner.fail(interactionContractError(this.owner.providerKey, "Session interaction expired before final delivery."));
+  }
+  protocolFailure(cause) {
+    const error = sessionInteractionError("session_interaction_failed", "Provider session interaction protocol failed.");
+    this.stop(Object.freeze({ kind: "failed", error }));
+    this.owner.fail(cause instanceof AgentProviderContractError ? cause : new AgentProviderContractError(
+      this.owner.providerKey,
+      "invalid_session_interaction",
+      "Provider session interaction protocol failed.",
+      { cause }
+    ));
+  }
+  observeTerminal() {
+    const terminal = this.nativeTerminal;
+    if (!terminal) return;
+    if (terminal.kind === "failed") {
+      this.stop(terminal);
+      this.owner.fail(interactionContractError(this.owner.providerKey, "Provider session interaction producer failed."));
+      return;
+    }
+    if (terminal.kind === "expired") {
+      this.stop(terminal);
+      this.owner.fail(interactionContractError(this.owner.providerKey, "Provider session interaction expired."));
+      return;
+    }
+    if (terminal.kind === "delivery_uncertain") this.owner.fence(terminal.error, this);
+    const attempt = this.lastAttempt;
+    if (terminal.kind !== "answered" && this.state.kind !== "terminal") {
+      this.stopped ??= terminal;
+      this.unavailable = true;
+      this.presentation.abort(new DOMException("The provider interaction is no longer answerable.", "AbortError"));
+      this.finalize(this.stopped, attempt);
+    }
+    if (attempt && !attempt.actualReceipt) return;
+    if (attempt?.actualReceipt && this.receiptContradiction(attempt, attempt.actualReceipt)) {
+      throw interactionContractError(
+        this.owner.providerKey,
+        "Provider session interaction terminal contradicts its response delivery receipt."
+      );
+    }
+    if (terminal.kind === "answered") {
+      if (!attempt || JSON.stringify(terminal.response) !== JSON.stringify(attempt.response) || attempt.actualReceipt?.status !== "delivered") {
+        throw interactionContractError(this.owner.providerKey, "Provider interaction acceptance disagrees with its delivery receipt.");
+      }
+      this.finalize(terminal, attempt);
+      return;
+    }
+    if (this.state.kind === "terminal") return;
+    this.finalize(this.stopped ?? terminal, attempt);
+  }
+  expectTerminal(deadline = Date.now() + this.owner.limits.responseTimeoutMs) {
+    if (this.rawTerminalSettled || this.terminalTimer) return;
+    const active = this.state.kind === "answering" ? this.state.attempt.deadline : this.state.kind === "terminal" && this.state.attempt ? this.state.attempt.deadline : deadline;
+    this.terminalTimer = setTimeout(() => {
+      this.terminalTimer = void 0;
+      if (!this.rawTerminalSettled) this.protocolFailure(interactionContractError(
+        this.owner.providerKey,
+        "Provider did not settle its stopped session interaction terminal."
+      ));
+    }, Math.max(0, Math.min(active, deadline) - Date.now()));
+  }
+  finalize(terminal, attempt, nativeRetirementExpected = true) {
+    if (this.state.kind === "terminal") return;
+    this.state = { kind: "terminal", terminal, ...attempt === void 0 ? {} : { attempt } };
+    this.unavailable = true;
+    if (this.expiryTimer) clearTimeout(this.expiryTimer);
+    this.presentation.abort(new DOMException("The session interaction is no longer answerable.", "AbortError"));
+    this.resolveTerminal(terminal);
+    if (nativeRetirementExpected && (!attempt || attempt.actualReceipt || this.responseWork === 0)) this.expectTerminal();
+    this.maybeRetire();
+  }
+  stop(terminal, nativeRetirementExpected = true) {
+    this.stopped ??= terminal;
+    this.unavailable = true;
+    this.presentation.abort(new DOMException("The session interaction was stopped.", "AbortError"));
+    if (this.state.kind !== "terminal") this.finalize(this.stopped, void 0, nativeRetirementExpected);
+    if (nativeRetirementExpected) this.expectTerminal();
+  }
+  refusal(active = false) {
+    return Object.freeze({
+      status: "rejected",
+      requestState: active ? "pending" : "unavailable",
+      error: sessionInteractionError(
+        active ? "session_interaction_response_active" : "session_interaction_unavailable",
+        active ? "A session interaction response is already active." : "The session interaction is no longer available."
+      )
+    });
+  }
+  uncertain(attempt, cause) {
+    const error = sessionInteractionError(
+      "session_interaction_delivery_uncertain",
+      "Session interaction response delivery could not be confirmed.",
+      true
+    );
+    const receipt = Object.freeze({ status: "delivery_uncertain", error });
+    attempt.receipt ??= receipt;
+    this.finalize(Object.freeze({ kind: "delivery_uncertain", error }), attempt);
+    this.owner.fence(cause === void 0 ? error : new AgentProviderContractError(
+      this.owner.providerKey,
+      "invalid_session_interaction",
+      "Session interaction response delivery failed after provider entry.",
+      { cause }
+    ), this);
+    if (this.candidate.kind === "prepared") this.owner.quiesce();
+    return receipt;
+  }
+  receiptContradiction(attempt, result) {
+    const terminal = this.nativeTerminal;
+    if (!terminal) return false;
+    if (result.status === "delivery_uncertain") return terminal.kind === "rejected";
+    if (terminal.kind === "answered") return JSON.stringify(terminal.response) !== JSON.stringify(attempt.response) || result.status !== "delivered";
+    if (result.status === "delivered") return terminal.kind === "rejected" || terminal.kind === "delivery_uncertain";
+    if (terminal.kind === "delivery_uncertain") return true;
+    return result.requestState === "pending" && terminal.kind === "rejected";
+  }
+  async respond(input) {
+    if (input === null || typeof input !== "object" || Array.isArray(input)) throw new TypeError("Session response must be an object.");
+    const { signal: responseSignal, ...rawResponse } = input;
+    if (responseSignal !== void 0 && !(responseSignal instanceof AbortSignal)) throw new TypeError("Session interaction response signal must be an AbortSignal.");
+    const response = parseAgentSessionResponseFor(this.handle.request, rawResponse);
+    throwIfAgentOperationAborted(responseSignal);
+    const deadline = new AbortController();
+    const signal = AbortSignal.any([this.presentation.signal, deadline.signal, ...responseSignal ? [responseSignal] : []]);
+    if (this.candidate.deadlineAt !== void 0 && this.candidate.deadlineAt <= Date.now()) this.expire();
+    if (this.unavailable || !this.owner.accepting || this.state.kind === "terminal") return this.refusal();
+    if (this.state.kind === "answering") return this.refusal(true);
+    const attempt = { response: projectResponse(response), deadline: Date.now() + this.owner.limits.responseTimeoutMs, entered: false };
+    this.lastAttempt = attempt;
+    this.state = { kind: "answering", attempt };
+    this.responseWork += 1;
+    let entered;
+    const requireCurrent = () => {
+      if (this.state.kind !== "answering" || this.state.attempt !== attempt || this.unavailable) throw new DOMException("Session response is no longer eligible.", "AbortError");
+      if (this.candidate.deadlineAt !== void 0 && this.candidate.deadlineAt <= Date.now()) {
+        this.expire();
+        throw new DOMException("Session response expired before entry.", "AbortError");
+      }
+    };
+    if (this.candidate.kind === "prepared") {
+      entered = dispatchPreparedSessionResponse({
+        owner: this.owner,
+        candidate: this.candidate,
+        response,
+        attemptId: mintSessionResponseAttemptId(),
+        signal,
+        requireCurrent,
+        onDispatch: (deadlineAt) => {
+          attempt.entered = true;
+          attempt.deadline = deadlineAt;
+        },
+        observeActualReceipt: (work) => {
+          this.responseWork += 1;
+          const actual2 = this.owner.track(work.then((result2) => {
+            attempt.actualReceipt = result2;
+            try {
+              this.observeTerminal();
+            } catch (cause) {
+              this.protocolFailure(cause);
+            }
+          }));
+          void actual2.then(
+            () => {
+              this.responseWork -= 1;
+              this.maybeRetire();
+            },
+            () => {
+              this.responseWork -= 1;
+              this.maybeRetire();
+            }
+          );
+        }
+      });
+    } else {
+      attempt.entered = true;
+      try {
+        entered = Promise.resolve(this.candidate.respond({ ...response, signal }));
+      } catch (cause) {
+        entered = Promise.reject(cause);
+      }
+    }
+    const actual = this.owner.track(entered.then((candidate) => {
+      const result2 = validateAgentRequestResolutionResult(candidate, this.owner.providerKey);
+      if (this.candidate.kind === "direct") attempt.actualReceipt = result2;
+      if (this.state.kind === "terminal") {
+        try {
+          this.observeTerminal();
+        } catch (cause) {
+          this.protocolFailure(cause);
+        }
+        this.expectTerminal(attempt.deadline);
+      }
+      return result2;
+    }));
+    void actual.then(
+      () => {
+        this.responseWork -= 1;
+        this.maybeRetire();
+      },
+      () => {
+        this.responseWork -= 1;
+        this.maybeRetire();
+      }
+    );
+    let timer;
+    const timeout = new Promise((resolve) => {
+      if (this.candidate.kind === "prepared") return;
+      timer = setTimeout(
+        () => {
+          deadline.abort(new DOMException("Session interaction response timed out.", "TimeoutError"));
+          resolve(null);
+        },
+        Math.max(0, attempt.deadline - Date.now())
+      );
+    });
+    let result;
+    let responseFailure;
+    try {
+      result = await Promise.race([actual, timeout]);
+    } catch (cause) {
+      if (!attempt.entered) {
+        if (this.state.kind === "answering" && this.state.attempt === attempt) this.state = { kind: "pending" };
+        this.lastAttempt = void 0;
+        throw cause;
+      }
+      responseFailure = cause;
+      result = null;
+    }
+    if (timer) clearTimeout(timer);
+    if (result === null) return this.uncertain(attempt, responseFailure);
+    if (this.receiptContradiction(attempt, result)) {
+      const uncertain = this.uncertain(attempt);
+      this.protocolFailure(interactionContractError(
+        this.owner.providerKey,
+        "Provider session interaction terminal contradicts its response delivery receipt."
+      ));
+      return uncertain;
+    }
+    attempt.receipt = result;
+    if (result.status === "delivery_uncertain") {
+      this.finalize(Object.freeze({ kind: "delivery_uncertain", error: result.error }), attempt);
+      this.owner.fence(result.error, this);
+      if (this.candidate.kind === "prepared") this.owner.quiesce();
+    } else if (result.status === "delivered") {
+      this.finalize(this.stopped ?? Object.freeze({ kind: "answered", response: attempt.response }), attempt);
+    } else if (result.requestState === "unavailable") {
+      this.finalize(this.stopped ?? Object.freeze({ kind: "rejected", error: result.error }), attempt);
+    } else if (this.stopped || this.unavailable || !this.owner.accepting) {
+      if (this.stopped || !this.owner.accepting) this.finalize(this.stopped ?? Object.freeze({ kind: "session_closed" }), attempt);
+      else {
+        this.state = { kind: "pending" };
+        this.expectTerminal(attempt.deadline);
+      }
+    } else {
+      this.state = { kind: "pending" };
+    }
+    try {
+      this.observeTerminal();
+    } catch (cause) {
+      this.protocolFailure(cause);
+    }
+    return result;
+  }
+  maybeRetire() {
+    if (this.retired || this.state.kind !== "terminal" || !this.callbackSettled || this.responseWork !== 0 || !this.rawTerminalSettled) return;
+    this.retired = true;
+    if (this.expiryTimer) clearTimeout(this.expiryTimer);
+    if (this.terminalTimer) clearTimeout(this.terminalTimer);
+    this.candidate.signal.removeEventListener("abort", this.nativeAborted);
+    this.retire();
+  }
+  async join() {
+    await Promise.allSettled([this.candidate.terminal, ...this.callback ? [this.callback] : []]);
+  }
+}
+function projectResponse(response) {
+  if (response.kind === "form") return Object.freeze({ kind: "form", action: response.action, choiceId: response.choiceId });
+  if (response.kind === "plan_review") return Object.freeze({
+    kind: "plan_review",
+    action: response.action,
+    choiceId: response.choiceId,
+    planId: response.planId,
+    revision: response.revision
+  });
+  return response;
+}
+export {
+  SessionInteractionRequest
+};

package/dist/sessionInteractions/types.d.ts

@@ -0,0 +1,110 @@
+import type { AgentError, AgentSessionAcceptedResponse, AgentSessionDecisionResponse, AgentSessionRequest, AgentSessionRequestKind, AgentSessionResponse, AgentSessionFormRequest, AgentSessionPlanReviewRequest } from "@agen-ai/agent-protocol";
+import type { MaybePromise } from "../foundation.js";
+import type { AgentRequestResolutionResult } from "../sessions.js";
+import type { AgentPreparedSessionResponse, AgentSessionResponseAttemptId } from "../nativeContinuations/types.js";
+export type AgentSessionInteractionOpeningOperation = "create" | "resume" | "branch";
+export type AgentSessionHumanWaitKind = "bounded" | "until_withdrawn_or_closed";
+export type AgentSessionHumanWaitPolicy = Readonly<{
+    kind: "bounded";
+}> | Readonly<{
+    kind: "until_withdrawn_or_closed";
+}>;
+export interface AgentSessionInteractionMapping {
+    readonly openingOperation: AgentSessionInteractionOpeningOperation;
+    readonly requestKind: AgentSessionRequestKind;
+}
+export type AgentSessionInteractionSupport = Readonly<{
+    kind: "unsupported";
+}> | Readonly<{
+    kind: "supported";
+    mappings: readonly [AgentSessionInteractionMapping, ...AgentSessionInteractionMapping[]];
+    producerOwnership: "exclusive";
+    humanWait: readonly [AgentSessionHumanWaitKind, ...AgentSessionHumanWaitKind[]];
+}>;
+export interface AgentSessionInteractionLimits {
+    readonly maxRetainedRequests: number;
+    readonly maxRetainedBytes: number;
+    readonly requestTimeoutMs: number;
+    readonly responseTimeoutMs: number;
+    readonly cleanupTimeoutMs: number;
+}
+export type AgentSessionInteractionOptions = Readonly<{
+    humanWait?: Readonly<{
+        kind: "bounded";
+    }>;
+    limits?: Partial<AgentSessionInteractionLimits>;
+}> | Readonly<{
+    humanWait: Readonly<{
+        kind: "until_withdrawn_or_closed";
+    }>;
+    limits?: Partial<Omit<AgentSessionInteractionLimits, "requestTimeoutMs">>;
+}>;
+export type AgentSessionInteractionDeadline = Readonly<{
+    kind: "no_deadline";
+}> | Readonly<{
+    kind: "deadline";
+    expiresAt: import("@agen-ai/agent-protocol").AgentIsoDateTime;
+    source: "provider" | "host_policy";
+}>;
+export type AgentSessionResponseInput = AgentSessionResponse & Readonly<{
+    signal?: AbortSignal;
+}>;
+export type AgentSessionDecisionResponseInput = AgentSessionDecisionResponse & Readonly<{
+    signal?: AbortSignal;
+}>;
+export type AgentSessionInteractionTerminal = Readonly<{
+    kind: "answered";
+    response: AgentSessionAcceptedResponse;
+}> | Readonly<{
+    kind: "rejected";
+    error: AgentError;
+}> | Readonly<{
+    kind: "delivery_uncertain";
+    error: AgentError;
+}> | Readonly<{
+    kind: "withdrawn";
+}> | Readonly<{
+    kind: "expired";
+    source: "provider" | "host_policy";
+}> | Readonly<{
+    kind: "session_closed";
+}> | Readonly<{
+    kind: "failed";
+    error: AgentError;
+}>;
+export interface AgentSessionInteraction {
+    readonly request: AgentSessionRequest;
+    readonly deadline: AgentSessionInteractionDeadline;
+    readonly signal: AbortSignal;
+    readonly terminal: Promise<AgentSessionInteractionTerminal>;
+    readonly respond: (input: AgentSessionResponseInput) => Promise<AgentRequestResolutionResult>;
+}
+export type AgentSessionInteractionHandler = (interaction: AgentSessionInteraction) => MaybePromise<void>;
+export type AgentSessionInteractionContext = AgentSessionInteractionOptions & Readonly<{
+    onRequest: AgentSessionInteractionHandler;
+}>;
+export interface AgentProviderDirectSessionInteraction {
+    readonly kind: "direct";
+    readonly request: AgentSessionRequest;
+    readonly signal: AbortSignal;
+    readonly terminal: Promise<AgentSessionInteractionTerminal>;
+    readonly respond: (input: AgentSessionResponseInput) => Promise<AgentRequestResolutionResult>;
+}
+export interface AgentProviderPrepareSessionResponseInput {
+    readonly response: AgentSessionResponse;
+    readonly responseAttemptId: AgentSessionResponseAttemptId;
+    readonly signal: AbortSignal;
+}
+export interface AgentProviderPreparedSessionInteraction {
+    readonly kind: "prepared";
+    readonly request: AgentSessionFormRequest | AgentSessionPlanReviewRequest;
+    readonly signal: AbortSignal;
+    readonly terminal: Promise<AgentSessionInteractionTerminal>;
+    readonly prepareResponse: (input: AgentProviderPrepareSessionResponseInput) => MaybePromise<AgentPreparedSessionResponse>;
+}
+export type AgentProviderSessionInteraction = AgentProviderDirectSessionInteraction | AgentProviderPreparedSessionInteraction;
+export type AgentProviderSessionInteractionContext = AgentSessionInteractionOptions & Readonly<{
+    onRequest: (interaction: AgentProviderSessionInteraction) => MaybePromise<void>;
+}>;
+export declare const DEFAULT_AGENT_SESSION_INTERACTION_LIMITS: Readonly<AgentSessionInteractionLimits>;
+//# sourceMappingURL=types.d.ts.map

package/dist/sessionInteractions/types.js

@@ -0,0 +1,10 @@
+const DEFAULT_AGENT_SESSION_INTERACTION_LIMITS = Object.freeze({
+  maxRetainedRequests: 8,
+  maxRetainedBytes: 524288,
+  requestTimeoutMs: 3e5,
+  responseTimeoutMs: 3e4,
+  cleanupTimeoutMs: 3e4
+});
+export {
+  DEFAULT_AGENT_SESSION_INTERACTION_LIMITS
+};

package/dist/sessionInteractions/validation.d.ts

@@ -0,0 +1,25 @@
+import { type AgentCapabilities, type AgentProviderKey, type AgentSessionId } from "@agen-ai/agent-protocol";
+import { AgentProviderContractError } from "../contractErrors.js";
+import type { AgentProviderAdapter } from "../sessions.js";
+import type { AgentNativeContinuationSupport, AgentNativeContinuationContext } from "../nativeContinuations/types.js";
+import { type AgentSessionInteractionContext, type AgentSessionInteractionLimits, type AgentSessionInteractionSupport, type AgentSessionInteractionTerminal, type AgentSessionHumanWaitKind, type AgentProviderSessionInteraction, type AgentSessionInteractionDeadline } from "./types.js";
+export declare function interactionRecord(input: unknown): Record<string, unknown>;
+export declare function interactionContractError(providerKey: AgentProviderKey, message: string): AgentProviderContractError;
+export declare function validateSessionInteractionSupport(capabilities: AgentCapabilities, adapter: AgentProviderAdapter): AgentSessionInteractionSupport;
+export declare function validateNativeContinuationSupport(capabilities: AgentCapabilities, adapter: AgentProviderAdapter, interactions: AgentSessionInteractionSupport): AgentNativeContinuationSupport;
+export interface ValidatedSessionInteractionContext {
+    readonly onRequest: AgentSessionInteractionContext["onRequest"];
+    readonly humanWait: AgentSessionHumanWaitKind;
+    readonly limits: Readonly<AgentSessionInteractionLimits>;
+}
+export declare function validateSessionInteractionContext(input: AgentSessionInteractionContext): ValidatedSessionInteractionContext;
+export declare function validateNativeContinuationContext(input: AgentNativeContinuationContext | undefined): AgentNativeContinuationContext | undefined;
+export type CapturedSessionInteractionCandidate = AgentProviderSessionInteraction;
+export declare function captureSessionInteractionCandidate(input: AgentProviderSessionInteraction, observe: (terminal: Promise<unknown>) => void): CapturedSessionInteractionCandidate;
+export type ValidatedSessionInteractionCandidate = CapturedSessionInteractionCandidate & Readonly<{
+    deadline: AgentSessionInteractionDeadline;
+    deadlineAt?: number;
+}>;
+export declare function validateSessionInteractionCandidate(input: CapturedSessionInteractionCandidate, sessionId: AgentSessionId, context: ValidatedSessionInteractionContext): ValidatedSessionInteractionCandidate;
+export declare function validateSessionInteractionTerminal(input: unknown): AgentSessionInteractionTerminal;
+//# sourceMappingURL=validation.d.ts.map