@agen-ai/agent-runtime 0.4.0 → 0.4.1

package/dist/sessionInteractions/lifetime.js

@@ -0,0 +1,251 @@
+import { AgentProviderContractError, AgentProviderSessionCleanupError } from "../contractErrors.js";
+import { SessionInteractionRequest } from "./request.js";
+import {
+  captureSessionInteractionCandidate,
+  interactionContractError,
+  validateSessionInteractionCandidate,
+  validateSessionInteractionContext
+} from "./validation.js";
+function sessionInteractionError(code, message, uncertain = false) {
+  return Object.freeze({
+    category: uncertain ? "unknown" : "invalid_request",
+    code,
+    message,
+    recovery: Object.freeze({ kind: uncertain ? "unknown" : "none" })
+  });
+}
+function waitForInteractionWork(work, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error("Session interaction cleanup did not finish before its deadline.")), timeoutMs);
+    work.then((result) => {
+      clearTimeout(timer);
+      resolve(result);
+    }, (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+class SessionInteractionOwner {
+  constructor(providerKey, sessionId, context, signal) {
+    this.providerKey = providerKey;
+    this.sessionId = sessionId;
+    try {
+      this.context = validateSessionInteractionContext(context);
+    } catch (cause) {
+      throw new AgentProviderContractError(
+        providerKey,
+        "invalid_session_interaction",
+        "Session interaction context is invalid.",
+        { cause }
+      );
+    }
+    this.limits = this.context.limits;
+    this.openingSignal = this.controller.signal;
+    this.failure = new Promise((resolve) => {
+      this.resolveFailure = resolve;
+    });
+    this.facade = Object.freeze({ limits: this.limits, onRequest: (candidate) => this.offer(candidate) });
+    if (signal) {
+      const aborted = () => this.fail(signal.reason ?? new DOMException("Session opening was aborted.", "AbortError"));
+      signal.addEventListener("abort", aborted, { once: true });
+      this.removeOpeningAbort = () => signal.removeEventListener("abort", aborted);
+      if (signal.aborted) aborted();
+    }
+  }
+  facade;
+  openingSignal;
+  limits;
+  failure;
+  controller = new AbortController();
+  requests = /* @__PURE__ */ new Map();
+  work = /* @__PURE__ */ new Set();
+  state = "opening";
+  retainedBytes = 0;
+  fatal;
+  fenceCause;
+  resolveFailure;
+  removeOpeningAbort = () => {
+  };
+  automaticClose;
+  cleanupAttempt = null;
+  cleanupDeadline = 0;
+  cleanupComplete = false;
+  cleanupFailure;
+  adopted = false;
+  context;
+  track(promise) {
+    this.work.add(promise);
+    void promise.then(() => this.work.delete(promise), () => this.work.delete(promise));
+    return promise;
+  }
+  get accepting() {
+    return this.state === "opening" || this.state === "open";
+  }
+  requireUsable() {
+    if (this.fatal) throw this.fatal.cause;
+    if (!this.accepting) throw this.fenceCause ?? new AgentProviderContractError(
+      this.providerKey,
+      this.state === "closed" ? "session_closed" : "session_unusable",
+      "Session interactions no longer permit provider mutation."
+    );
+  }
+  offer(candidate) {
+    let captured;
+    try {
+      captured = captureSessionInteractionCandidate(candidate, (terminal) => {
+        this.track(terminal);
+      });
+      const validated = validateSessionInteractionCandidate(captured, this.sessionId, this.limits.requestTimeoutMs);
+      this.requireUsable();
+      if (validated.signal.aborted) throw interactionContractError(this.providerKey, "Provider offered an unavailable session interaction.");
+      const bytes = Buffer.byteLength(JSON.stringify(validated.request), "utf8");
+      if (this.requests.has(validated.request.requestId) || this.requests.size >= this.limits.maxRetainedRequests || this.retainedBytes + bytes > this.limits.maxRetainedBytes) {
+        throw interactionContractError(this.providerKey, "Session interaction identity or retained capacity is unavailable.");
+      }
+      const request = new SessionInteractionRequest(this, validated, () => {
+        this.requests.delete(validated.request.requestId);
+        this.retainedBytes -= bytes;
+      });
+      this.requests.set(validated.request.requestId, request);
+      this.retainedBytes += bytes;
+      request.observe();
+      let callback;
+      try {
+        callback = Promise.resolve(this.context.onRequest(request.handle));
+      } catch (cause) {
+        callback = Promise.reject(cause);
+      }
+      request.setCallback(callback);
+      this.track(callback);
+      void callback.catch((cause) => this.fail(cause));
+      return callback;
+    } catch (cause) {
+      const failure = cause instanceof AgentProviderContractError ? cause : new AgentProviderContractError(
+        this.providerKey,
+        "invalid_session_interaction",
+        "Provider offered an invalid session interaction.",
+        { cause }
+      );
+      this.fail(failure);
+      const rejected = Promise.reject(failure);
+      void rejected.catch(() => {
+      });
+      return rejected;
+    }
+  }
+  installClose(close) {
+    this.automaticClose = close;
+  }
+  adopt() {
+    this.requireUsable();
+    this.removeOpeningAbort();
+    this.state = "open";
+    this.adopted = true;
+  }
+  fence(cause, source) {
+    if (!this.accepting) return;
+    this.fenceCause = new AgentProviderContractError(
+      this.providerKey,
+      "session_unusable",
+      "Provider session cannot be reused after uncertain session interaction delivery.",
+      { cause }
+    );
+    this.state = "mutation-fenced";
+    if (!this.adopted) {
+      this.resolveFailure(this.fenceCause);
+      this.controller.abort(new DOMException("Session opening lost confirmed interaction delivery.", "AbortError"));
+    }
+    const terminal = Object.freeze({ kind: "failed", error: sessionInteractionError(
+      "session_interaction_delivery_uncertain",
+      "A session interaction response could not be confirmed.",
+      true
+    ) });
+    for (const request of this.requests.values()) if (request !== source) request.stop(terminal, false);
+  }
+  fail(cause) {
+    if (!this.fatal) {
+      this.fatal = { cause, observed: false };
+      this.resolveFailure(cause);
+    }
+    this.stop(Object.freeze({ kind: "failed", error: sessionInteractionError(
+      "session_interaction_failed",
+      "The session interaction owner failed."
+    ) }));
+    if (this.adopted && this.automaticClose) {
+      void this.automaticClose().catch(() => {
+      });
+    }
+  }
+  stop(terminal = Object.freeze({ kind: "session_closed" })) {
+    if (this.state !== "closed" && this.state !== "cleanup-pending") this.state = "stopping";
+    this.removeOpeningAbort();
+    this.controller.abort(new DOMException("The session interaction owner was stopped.", "AbortError"));
+    for (const request of this.requests.values()) request.stop(terminal);
+  }
+  async join() {
+    while (this.work.size > 0) await Promise.allSettled([...this.work]);
+    await Promise.all([...this.requests.values()].map((request) => request.join()));
+  }
+  close(cleanup, explicit) {
+    this.stop();
+    if (!this.cleanupComplete && !this.cleanupAttempt) {
+      this.state = "cleanup-pending";
+      this.cleanupDeadline = Date.now() + this.limits.cleanupTimeoutMs;
+      const attempt = Promise.resolve().then(cleanup).then(() => {
+        this.cleanupComplete = true;
+        this.state = "closed";
+      });
+      this.cleanupAttempt = attempt;
+      void attempt.then(
+        () => {
+          if (this.cleanupAttempt === attempt) this.cleanupAttempt = null;
+        },
+        (cause) => {
+          this.cleanupFailure = { cause };
+          if (this.cleanupAttempt === attempt) this.cleanupAttempt = null;
+        }
+      );
+    }
+    const actual = this.cleanupAttempt ?? Promise.resolve();
+    return waitForInteractionWork(actual, this.cleanupComplete ? this.limits.cleanupTimeoutMs : Math.max(0, this.cleanupDeadline - Date.now())).then(() => {
+      if (explicit && this.fatal && !this.fatal.observed) {
+        this.fatal.observed = true;
+        if (this.cleanupFailure) throw new AggregateError(
+          [this.fatal.cause, this.cleanupFailure.cause],
+          "Session interactions failed; retained cleanup subsequently completed."
+        );
+        throw this.fatal.cause;
+      }
+      if (explicit) this.cleanupFailure = void 0;
+    }, (cleanupError) => {
+      const causes = [cleanupError];
+      if (explicit && this.fatal && !this.fatal.observed) {
+        this.fatal.observed = true;
+        causes.unshift(this.fatal.cause);
+      }
+      throw new AgentProviderSessionCleanupError({
+        providerKey: this.providerKey,
+        errors: causes,
+        retryCleanup: () => this.close(cleanup, true)
+      });
+    });
+  }
+}
+function createSessionInteractionOwner(input) {
+  if (input.context === void 0) return void 0;
+  if (input.support.kind === "unsupported" || !input.support.openingOperations.includes(input.operation)) {
+    throw new AgentProviderContractError(
+      input.providerKey,
+      "session_interactions_unsupported",
+      "Provider does not support session interactions for this opening operation."
+    );
+  }
+  return new SessionInteractionOwner(input.providerKey, input.sessionId, input.context, input.signal);
+}
+export {
+  SessionInteractionOwner,
+  createSessionInteractionOwner,
+  sessionInteractionError,
+  waitForInteractionWork
+};

package/dist/sessionInteractions/request.d.ts

@@ -0,0 +1,42 @@
+import { type SessionInteractionOwner } from "./lifetime.js";
+import type { AgentSessionInteraction, AgentSessionInteractionTerminal } from "./types.js";
+import { type CapturedSessionInteractionCandidate } from "./validation.js";
+type Candidate = CapturedSessionInteractionCandidate & Pick<AgentSessionInteraction, "request">;
+export declare class SessionInteractionRequest {
+    private readonly owner;
+    private readonly candidate;
+    private readonly retire;
+    readonly handle: AgentSessionInteraction;
+    private state;
+    private readonly presentation;
+    private resolveTerminal;
+    private callback;
+    private callbackSettled;
+    private responseWork;
+    private rawTerminalSettled;
+    private nativeTerminal;
+    private lastAttempt;
+    private stopped;
+    private unavailable;
+    private retired;
+    private expiryTimer;
+    private terminalTimer;
+    private readonly nativeAborted;
+    constructor(owner: SessionInteractionOwner, candidate: Candidate, retire: () => void);
+    observe(): void;
+    setCallback(callback: Promise<void>): void;
+    private expire;
+    private protocolFailure;
+    private observeTerminal;
+    private expectTerminal;
+    private finalize;
+    stop(terminal: AgentSessionInteractionTerminal, nativeRetirementExpected?: boolean): void;
+    private refusal;
+    private uncertain;
+    private receiptContradiction;
+    private respond;
+    private maybeRetire;
+    join(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=request.d.ts.map

package/dist/sessionInteractions/request.js

@@ -0,0 +1,308 @@
+import { parseAgentSessionDecisionResponseFor } from "@agen-ai/agent-protocol";
+import { throwIfAgentOperationAborted } from "../foundation.js";
+import { AgentProviderContractError } from "../contractErrors.js";
+import { hasExactOwnKeys } from "../internal/objectShape.js";
+import { validateAgentRequestResolutionResult } from "../turnExecution/receipts.js";
+import { sessionInteractionError } from "./lifetime.js";
+import { interactionContractError, validateSessionInteractionTerminal } from "./validation.js";
+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,
+      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 });
+    this.expiryTimer = setTimeout(() => this.expire(), Math.max(0, Date.parse(this.handle.request.expiresAt) - Date.now()));
+    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();
+  }
+  setCallback(callback) {
+    this.callback = callback;
+    void callback.then(
+      () => {
+        this.callbackSettled = true;
+        this.maybeRetire();
+      },
+      () => {
+        this.callbackSettled = true;
+        this.maybeRetire();
+      }
+    );
+  }
+  expire() {
+    if (this.state.kind === "terminal") return;
+    this.stop(Object.freeze({ kind: "expired" }));
+    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"));
+    }
+    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 || terminal.choiceId !== attempt.choiceId || 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 === "pending") 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);
+    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 terminal.choiceId !== attempt.choiceId || result.status !== "delivered";
+    if (result.status === "delivered") return true;
+    if (terminal.kind === "delivery_uncertain") return true;
+    return result.requestState === "pending" && terminal.kind === "rejected";
+  }
+  async respond(input) {
+    if (input === null || typeof input !== "object" || !hasExactOwnKeys(input, Object.hasOwn(input, "signal") ? ["choiceId", "signal"] : ["choiceId"])) {
+      throw new TypeError("Session interaction response must contain a choice and an optional AbortSignal.");
+    }
+    const responseSignal = input.signal;
+    if (responseSignal !== void 0 && !(responseSignal instanceof AbortSignal)) {
+      throw new TypeError("Session interaction response signal must be an AbortSignal.");
+    }
+    const response = parseAgentSessionDecisionResponseFor(this.handle.request, { choiceId: input.choiceId });
+    throwIfAgentOperationAborted(responseSignal);
+    const deadline = new AbortController();
+    const signal = AbortSignal.any([this.presentation.signal, deadline.signal, ...responseSignal ? [responseSignal] : []]);
+    if (Date.parse(this.handle.request.expiresAt) <= 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 = { choiceId: response.choiceId, deadline: Date.now() + this.owner.limits.responseTimeoutMs };
+    this.lastAttempt = attempt;
+    this.state = { kind: "answering", attempt };
+    this.responseWork += 1;
+    let entered;
+    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);
+      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) => {
+      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) {
+      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);
+    } else if (result.status === "delivered") {
+      this.finalize(Object.freeze({ kind: "answered", choiceId: attempt.choiceId }), 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) {
+      result = this.refusal();
+      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] : []]);
+  }
+}
+export {
+  SessionInteractionRequest
+};

package/dist/sessionInteractions/types.d.ts

@@ -0,0 +1,54 @@
+import type { AgentError, AgentSessionDecisionChoiceId, AgentSessionDecisionRequest, AgentSessionDecisionResponse } from "@agen-ai/agent-protocol";
+import type { MaybePromise } from "../foundation.js";
+import type { AgentRequestResolutionResult } from "../sessions.js";
+export type AgentSessionInteractionOpeningOperation = "create" | "resume" | "branch";
+export type AgentSessionInteractionSupport = Readonly<{
+    kind: "unsupported";
+}> | Readonly<{
+    kind: "supported";
+    openingOperations: readonly [AgentSessionInteractionOpeningOperation, ...AgentSessionInteractionOpeningOperation[]];
+    requestKinds: readonly ["decision"];
+    producerOwnership: "exclusive";
+}>;
+export interface AgentSessionInteractionLimits {
+    readonly maxRetainedRequests: number;
+    readonly maxRetainedBytes: number;
+    readonly requestTimeoutMs: number;
+    readonly responseTimeoutMs: number;
+    readonly cleanupTimeoutMs: number;
+}
+export interface AgentSessionDecisionResponseInput extends AgentSessionDecisionResponse {
+    readonly signal?: AbortSignal;
+}
+export type AgentSessionInteractionTerminal = Readonly<{
+    kind: "answered";
+    choiceId: AgentSessionDecisionChoiceId;
+}> | Readonly<{
+    kind: "rejected";
+    error: AgentError;
+}> | Readonly<{
+    kind: "delivery_uncertain";
+    error: AgentError;
+}> | Readonly<{
+    kind: "withdrawn";
+}> | Readonly<{
+    kind: "expired";
+}> | Readonly<{
+    kind: "session_closed";
+}> | Readonly<{
+    kind: "failed";
+    error: AgentError;
+}>;
+export interface AgentSessionInteraction {
+    readonly request: AgentSessionDecisionRequest;
+    readonly signal: AbortSignal;
+    readonly terminal: Promise<AgentSessionInteractionTerminal>;
+    readonly respond: (input: AgentSessionDecisionResponseInput) => Promise<AgentRequestResolutionResult>;
+}
+export type AgentSessionInteractionHandler = (interaction: AgentSessionInteraction) => MaybePromise<void>;
+export interface AgentSessionInteractionContext {
+    readonly onRequest: AgentSessionInteractionHandler;
+    readonly limits?: Partial<AgentSessionInteractionLimits>;
+}
+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,21 @@
+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 AgentSessionInteraction, type AgentSessionInteractionContext, type AgentSessionInteractionLimits, type AgentSessionInteractionSupport, type AgentSessionInteractionTerminal } from "./types.js";
+export declare function interactionContractError(providerKey: AgentProviderKey, message: string): AgentProviderContractError;
+export declare function validateSessionInteractionSupport(capabilities: AgentCapabilities, adapter: AgentProviderAdapter): AgentSessionInteractionSupport;
+export interface ValidatedSessionInteractionContext {
+    readonly onRequest: AgentSessionInteractionContext["onRequest"];
+    readonly limits: Readonly<AgentSessionInteractionLimits>;
+}
+export declare function validateSessionInteractionContext(input: AgentSessionInteractionContext): ValidatedSessionInteractionContext;
+export interface CapturedSessionInteractionCandidate {
+    readonly request: unknown;
+    readonly signal: AbortSignal;
+    readonly terminal: Promise<unknown>;
+    readonly respond: AgentSessionInteraction["respond"];
+}
+export declare function captureSessionInteractionCandidate(input: AgentSessionInteraction, observe: (terminal: Promise<unknown>) => void): CapturedSessionInteractionCandidate;
+export declare function validateSessionInteractionCandidate(input: CapturedSessionInteractionCandidate, sessionId: AgentSessionId, requestTimeoutMs: number): CapturedSessionInteractionCandidate & Pick<AgentSessionInteraction, "request">;
+export declare function validateSessionInteractionTerminal(input: unknown): AgentSessionInteractionTerminal;
+//# sourceMappingURL=validation.d.ts.map