@agen-ai/agent-runtime 0.3.1 → 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

@@ -1,19 +1,32 @@
-import { type AgentCapabilities, type AgentSessionBinding, type AgentSessionId } from "@agen-ai/agent-protocol";
+import { type AgentCapabilities, type AgentProviderKey, type AgentSessionBinding, type AgentSessionId } from "@agen-ai/agent-protocol";
+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;
     readonly candidate: AgentProviderSession;
     readonly expectedBinding?: AgentSessionBinding;
     readonly sourceBinding?: AgentSessionBinding;
+    readonly hostBindingLease?: AgentHostBindingLease;
+    readonly sessionInteractionOwner?: SessionInteractionOwner;
 }): AgentProviderSession;
-export declare function closeRejectedAgentProviderSession(session: AgentProviderSession | null, error: unknown): Promise<never>;
+export declare function closeRejectedAgentProviderSession(session: AgentProviderSession | null, error: unknown, hostBinding?: Readonly<{
+    providerKey: AgentProviderKey;
+    lease: AgentHostBindingLease;
+}>, opening?: Readonly<{
+    providerKey: AgentProviderKey;
+    input: object;
+}>, interactions?: SessionInteractionOwner): Promise<never>;
 export declare function openIdentityCreatingAgentProviderSession(input: {
     readonly capabilities: AgentCapabilities;
     readonly sessionId: AgentSessionId;
     readonly observer: AgentSessionBindingCreatedObserver;
     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