@agen-ai/agent-runtime 0.4.0 → 0.4.2

package/dist/sessionInteractions/lifetime.d.ts

@@ -0,0 +1,81 @@
+import type { AgentError, AgentProviderKey, AgentSessionId } from "@agen-ai/agent-protocol";
+import type { MaybePromise } from "../foundation.js";
+import type { AgentSessionAdmission } from "../sessionAdmission.js";
+import type { AgentSessionValidationOwner } from "../sessionValidation.js";
+import type { AgentNativeContinuationContext, AgentNativeContinuationSupport } from "../nativeContinuations/types.js";
+import type { AgentProviderSessionInteractionContext, AgentSessionInteractionContext, AgentSessionInteractionOpeningOperation, AgentSessionInteractionSupport, AgentSessionInteractionTerminal } from "./types.js";
+import { SessionInteractionRequest } from "./request.js";
+import { type ValidatedSessionInteractionContext } from "./validation.js";
+export declare function sessionInteractionError(code: string, message: string, uncertain?: boolean): AgentError;
+export declare function waitForInteractionWork<Result>(work: Promise<Result>, timeoutMs: number): Promise<Result>;
+export declare class SessionInteractionOwner {
+    readonly providerKey: AgentProviderKey;
+    readonly sessionId: AgentSessionId;
+    readonly validationOwner: AgentSessionValidationOwner;
+    readonly operation: AgentSessionInteractionOpeningOperation;
+    readonly support: AgentSessionInteractionSupport;
+    readonly nativeSupport: AgentNativeContinuationSupport;
+    readonly admission: AgentSessionAdmission;
+    readonly facade: AgentProviderSessionInteractionContext;
+    readonly openingSignal: AbortSignal;
+    readonly limits: ValidatedSessionInteractionContext["limits"];
+    readonly failure: Promise<unknown>;
+    private readonly controller;
+    private readonly requests;
+    private readonly work;
+    private state;
+    private retainedBytes;
+    private fatal;
+    private fenceCause;
+    private resolveFailure;
+    private removeOpeningAbort;
+    private automaticClose;
+    private cleanupAttempt;
+    private cleanupDeadline;
+    private cleanupComplete;
+    private retainedCleanup;
+    private cleanupFailure;
+    private adopted;
+    private bound;
+    private returned;
+    private readonly waiting;
+    private associationTimer;
+    private prebindingCount;
+    private prebindingBytes;
+    private readonly preparations;
+    private stoppedExecution;
+    readonly continuations: AgentNativeContinuationContext | undefined;
+    private readonly context;
+    constructor(providerKey: AgentProviderKey, sessionId: AgentSessionId, context: AgentSessionInteractionContext, validationOwner: AgentSessionValidationOwner, operation: AgentSessionInteractionOpeningOperation, support: AgentSessionInteractionSupport, nativeSupport: AgentNativeContinuationSupport, continuations?: AgentNativeContinuationContext, signal?: AbortSignal);
+    track<Result>(promise: Promise<Result>): Promise<Result>;
+    get accepting(): boolean;
+    requireUsable(): void;
+    private offer;
+    requireContinuation(kind: "form" | "plan_review"): void;
+    private canPresent;
+    bind(): void;
+    markReturned(): void;
+    private presentWaiting;
+    cleanupFailedPreparation(): Promise<void>;
+    quiesce(): void;
+    retainPreparation(cleanup: () => Promise<void>): () => void;
+    installClose(close: () => Promise<void>): void;
+    adopt(): void;
+    fence(cause: unknown, source: SessionInteractionRequest): void;
+    fail(cause: unknown): void;
+    stop(terminal?: AgentSessionInteractionTerminal): void;
+    join(): Promise<void>;
+    close(cleanup: () => MaybePromise<void>, explicit: boolean): Promise<void>;
+}
+export declare function createSessionInteractionOwner(input: Readonly<{
+    providerKey: AgentProviderKey;
+    sessionId: AgentSessionId;
+    operation: AgentSessionInteractionOpeningOperation;
+    support: AgentSessionInteractionSupport;
+    nativeSupport: AgentNativeContinuationSupport;
+    validationOwner: AgentSessionValidationOwner;
+    context?: AgentSessionInteractionContext;
+    continuations?: AgentNativeContinuationContext;
+    signal?: AbortSignal;
+}>): SessionInteractionOwner | undefined;
+//# sourceMappingURL=lifetime.d.ts.map

package/dist/sessionInteractions/lifetime.js

@@ -0,0 +1,383 @@
+import { AgentProviderContractError, AgentProviderSessionCleanupError } from "../contractErrors.js";
+import { SessionInteractionRequest } from "./request.js";
+import {
+  captureSessionInteractionCandidate,
+  interactionContractError,
+  validateSessionInteractionCandidate,
+  validateSessionInteractionContext,
+  validateNativeContinuationContext
+} 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, validationOwner, operation, support, nativeSupport, continuations, signal) {
+    this.providerKey = providerKey;
+    this.sessionId = sessionId;
+    this.validationOwner = validationOwner;
+    this.operation = operation;
+    this.support = support;
+    this.nativeSupport = nativeSupport;
+    this.admission = validationOwner.sessionAdmission;
+    this.continuations = validateNativeContinuationContext(continuations);
+    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;
+    });
+    const { requestTimeoutMs: _timeout, ...nonHumanLimits } = this.limits;
+    const onRequest = (candidate) => this.offer(candidate);
+    this.facade = this.context.humanWait === "bounded" ? Object.freeze({ humanWait: Object.freeze({ kind: "bounded" }), limits: this.limits, onRequest }) : Object.freeze({ humanWait: Object.freeze({ kind: "until_withdrawn_or_closed" }), limits: Object.freeze(nonHumanLimits), onRequest });
+    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();
+    }
+  }
+  admission;
+  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;
+  retainedCleanup;
+  cleanupFailure;
+  adopted = false;
+  bound = false;
+  returned = false;
+  waiting = /* @__PURE__ */ new Map();
+  associationTimer;
+  prebindingCount = 0;
+  prebindingBytes = 0;
+  preparations = /* @__PURE__ */ new Set();
+  stoppedExecution = null;
+  continuations;
+  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;
+    this.validationOwner.requireUsable();
+    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.context);
+      this.requireUsable();
+      if (this.support.kind !== "supported" || !this.support.mappings.some((entry) => entry.openingOperation === this.operation && entry.requestKind === validated.request.kind)) {
+        throw interactionContractError(this.providerKey, "Provider offered an undeclared session request kind.");
+      }
+      if (validated.kind === "prepared") this.requireContinuation(validated.request.kind);
+      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.");
+      }
+      this.admission.claimRequest(validated.request.requestId, "invalid_session_interaction");
+      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 resolveCallback;
+      let rejectCallback;
+      const callback = new Promise((resolve, reject) => {
+        resolveCallback = resolve;
+        rejectCallback = reject;
+      });
+      const present = () => {
+        this.waiting.delete(present);
+        if (!this.accepting || request.handle.signal.aborted) {
+          resolveCallback();
+          return;
+        }
+        try {
+          Promise.resolve(this.context.onRequest(request.handle)).then(resolveCallback, rejectCallback);
+        } catch (cause) {
+          rejectCallback(cause);
+        }
+      };
+      request.setCallback(callback);
+      this.track(callback);
+      void callback.catch((cause) => this.fail(cause));
+      if (validated.kind === "direct" || this.canPresent(validated.request.kind)) present();
+      else {
+        this.waiting.set(present, validated.request.kind);
+        if (!this.bound) {
+          this.prebindingCount += 1;
+          this.prebindingBytes += bytes;
+          if (this.prebindingCount > 16 || this.prebindingBytes > 1048576) throw new AgentProviderContractError(
+            this.providerKey,
+            "native_continuation_limit_exceeded",
+            "Prebinding association exceeded its retained material budget."
+          );
+          this.associationTimer ??= setTimeout(() => this.fail(new AgentProviderContractError(
+            this.providerKey,
+            "invalid_native_continuation",
+            "Prebinding association did not finish before its deadline."
+          )), 3e4);
+        }
+      }
+      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;
+    }
+  }
+  requireContinuation(kind) {
+    if (!this.continuations || this.nativeSupport.kind !== "supported" || !this.nativeSupport.mappings.some((entry) => entry.openingOperation === this.operation && entry.requestKind === kind)) {
+      throw new AgentProviderContractError(this.providerKey, "native_continuations_unsupported", "Provider native continuation requires its exact supported tuple and a host output handler.");
+    }
+  }
+  canPresent(kind) {
+    return this.bound && this.nativeSupport.kind === "supported" && this.nativeSupport.mappings.some((entry) => entry.openingOperation === this.operation && entry.requestKind === kind && (entry.timing !== "after_open_return" || this.returned));
+  }
+  bind() {
+    this.requireUsable();
+    this.bound = true;
+    if (this.associationTimer) clearTimeout(this.associationTimer);
+    this.prebindingCount = 0;
+    this.prebindingBytes = 0;
+    this.presentWaiting();
+  }
+  markReturned() {
+    this.returned = true;
+    this.presentWaiting();
+  }
+  presentWaiting() {
+    for (const [present, kind] of this.waiting) if (!this.accepting || this.canPresent(kind)) present();
+  }
+  async cleanupFailedPreparation() {
+    if (this.cleanupComplete) return;
+    if (this.retainedCleanup) return this.close(this.retainedCleanup, false);
+    if (this.automaticClose) return this.automaticClose();
+    throw new Error("Opening cleanup has not acquired its native session owner.");
+  }
+  quiesce() {
+    if (this.adopted && this.automaticClose) void this.automaticClose().catch(() => {
+    });
+  }
+  retainPreparation(cleanup) {
+    this.preparations.add(cleanup);
+    return () => {
+      this.preparations.delete(cleanup);
+    };
+  }
+  installClose(close) {
+    this.automaticClose = close;
+    this.validationOwner.installClose(close);
+  }
+  adopt() {
+    this.requireUsable();
+    this.removeOpeningAbort();
+    this.state = "open";
+    this.adopted = true;
+  }
+  fence(cause, source) {
+    if (!this.accepting) return;
+    this.validationOwner.fence();
+    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.stoppedExecution ??= this.validationOwner.activeTurn;
+    this.validationOwner.stop();
+    this.stoppedExecution?.owner.stop(new DOMException("The session interaction owner was stopped.", "AbortError"));
+    this.removeOpeningAbort();
+    if (this.associationTimer) clearTimeout(this.associationTimer);
+    this.presentWaiting();
+    this.controller.abort(new DOMException("The session interaction owner was stopped.", "AbortError"));
+    for (const request of this.requests.values()) request.stop(terminal);
+  }
+  async join() {
+    await Promise.all([...this.preparations].map((cleanup) => cleanup()));
+    while (this.work.size > 0) await Promise.allSettled([...this.work]);
+    await Promise.all([...this.requests.values()].map((request) => request.join()));
+    await this.stoppedExecution?.owner.join();
+  }
+  close(cleanup, explicit) {
+    this.retainedCleanup ??= cleanup;
+    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) {
+    if (input.continuations !== void 0) throw new AgentProviderContractError(input.providerKey, "native_continuations_unsupported", "Native continuations require session interaction handlers.");
+    return void 0;
+  }
+  if (input.support.kind === "unsupported" || !input.support.mappings.some((entry) => entry.openingOperation === input.operation)) {
+    throw new AgentProviderContractError(
+      input.providerKey,
+      "session_interactions_unsupported",
+      "Provider does not support session interactions for this opening operation."
+    );
+  }
+  let parsed;
+  try {
+    parsed = validateSessionInteractionContext(input.context);
+  } catch (cause) {
+    throw new AgentProviderContractError(input.providerKey, "invalid_session_interaction", "Session interaction context is invalid.", { cause });
+  }
+  if (!input.support.humanWait.includes(parsed.humanWait)) throw new AgentProviderContractError(
+    input.providerKey,
+    "session_interactions_unsupported",
+    "Provider does not support the selected human wait policy."
+  );
+  if (input.continuations !== void 0 && (input.nativeSupport.kind !== "supported" || !input.nativeSupport.mappings.some((entry) => entry.openingOperation === input.operation))) {
+    throw new AgentProviderContractError(input.providerKey, "native_continuations_unsupported", "Provider does not support continuations for this opening operation.");
+  }
+  return new SessionInteractionOwner(
+    input.providerKey,
+    input.sessionId,
+    input.context,
+    input.validationOwner,
+    input.operation,
+    input.support,
+    input.nativeSupport,
+    input.continuations,
+    input.signal
+  );
+}
+export {
+  SessionInteractionOwner,
+  createSessionInteractionOwner,
+  sessionInteractionError,
+  waitForInteractionWork
+};

package/dist/sessionInteractions/request.d.ts

@@ -0,0 +1,43 @@
+import { type SessionInteractionOwner } from "./lifetime.js";
+import type { AgentSessionInteraction, AgentSessionInteractionTerminal } from "./types.js";
+import { type ValidatedSessionInteractionCandidate } from "./validation.js";
+type Candidate = ValidatedSessionInteractionCandidate;
+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 scheduleExpiry;
+    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