@agen-ai/agent-runtime 0.3.1 → 0.4.1

package/dist/hostBindings/opening.js

@@ -0,0 +1,82 @@
+import { AgentProviderSessionCleanupError } from "../contractErrors.js";
+import { associateAgentSessionCleanupError, isAgentProviderSessionCleanupErrorFor } from "../sessionCleanup.js";
+import { createAgentHostBindingCleanupError } from "./lifetime.js";
+async function invokeAgentSessionOpening(input) {
+  if (input.interactions) return invokeInteractiveSessionOpening({ ...input, interactions: input.interactions });
+  try {
+    return await input.open(input.candidateInput);
+  } catch (error) {
+    if (!isAgentProviderSessionCleanupErrorFor(error, input.candidateInput) || error.providerKey !== input.providerKey) throw error;
+    input.lease?.stop();
+    const ownership = {
+      providerKey: input.providerKey,
+      errors: [error],
+      async retryCleanup() {
+        await error.retryCleanup();
+        await input.lease?.release();
+      }
+    };
+    const retained = input.lease ? createAgentHostBindingCleanupError({ ...ownership, lease: input.lease }) : new AgentProviderSessionCleanupError(ownership);
+    throw associateAgentSessionCleanupError(retained, input.openingInput);
+  }
+}
+async function invokeInteractiveSessionOpening(input) {
+  let actual;
+  try {
+    input.interactions.requireUsable();
+    actual = Promise.resolve(input.open(input.candidateInput));
+  } catch (cause) {
+    actual = Promise.reject(cause);
+  }
+  void actual.catch(() => {
+  });
+  try {
+    const candidate = await Promise.race([actual, input.interactions.failure.then((cause) => {
+      throw cause;
+    })]);
+    input.interactions.requireUsable();
+    return candidate;
+  } catch (error) {
+    input.interactions.stop();
+    input.lease?.stop();
+    let providerClosed = false;
+    let nativeCleanup;
+    let nativeCleanupRetained = false;
+    const cleanup = async () => {
+      let candidate;
+      try {
+        candidate = await actual;
+      } catch (cause) {
+        if (isAgentProviderSessionCleanupErrorFor(cause, input.candidateInput) && cause.providerKey === input.providerKey) {
+          nativeCleanup = cause;
+          if (!nativeCleanupRetained) {
+            nativeCleanupRetained = true;
+            throw cause;
+          }
+        }
+      }
+      if (!providerClosed) {
+        if (nativeCleanup) await nativeCleanup.retryCleanup();
+        else if (candidate) await candidate.close({ reason: "contract_rejected" });
+        providerClosed = true;
+      }
+      await input.interactions.join();
+      await input.lease?.release();
+    };
+    try {
+      await input.interactions.close(cleanup, false);
+    } catch (cleanupError) {
+      const ownership = {
+        providerKey: input.providerKey,
+        errors: [error, cleanupError],
+        retryCleanup: () => input.interactions.close(cleanup, false)
+      };
+      const retained = input.lease ? createAgentHostBindingCleanupError({ ...ownership, lease: input.lease }) : new AgentProviderSessionCleanupError(ownership);
+      throw associateAgentSessionCleanupError(retained, input.openingInput);
+    }
+    throw error;
+  }
+}
+export {
+  invokeAgentSessionOpening
+};

package/dist/hostBindings/schema.d.ts

@@ -0,0 +1,9 @@
+import { type AgentJsonValue } from "@agen-ai/agent-protocol";
+import type { AgentHostToolInputSchema, AgentHostToolSchema } from "./types.js";
+export declare const AGENT_HOST_TOOL_SCHEMA_DIALECT: "https://json-schema.org/draft/2020-12/schema";
+export declare function dataRecord(value: unknown): Record<string, unknown>;
+export declare function dataArray(value: unknown, maximum: number): readonly unknown[];
+export declare function exactKeys(value: Record<string, unknown>, allowed: readonly string[], required?: readonly string[]): void;
+export declare function parseAgentHostToolInputSchema(input: unknown): AgentHostToolInputSchema;
+export declare function matchesAgentHostToolSchema(schema: AgentHostToolSchema, value: AgentJsonValue): boolean;
+//# sourceMappingURL=schema.d.ts.map

package/dist/hostBindings/schema.js

@@ -0,0 +1,169 @@
+import { agentProtocolSerializedJsonBytes } from "@agen-ai/agent-protocol";
+const AGENT_HOST_TOOL_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+function dataRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+    throw new TypeError("Host binding data must be a plain object.");
+  }
+  const keys = Reflect.ownKeys(value);
+  if (keys.length > 100) throw new TypeError("Host binding objects cannot exceed 100 properties.");
+  const result = /* @__PURE__ */ Object.create(null);
+  for (const key of keys) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (typeof key !== "string" || !descriptor || !("value" in descriptor) || !descriptor.enumerable || ["__proto__", "constructor", "prototype"].includes(key)) {
+      throw new TypeError("Host binding data must contain only ordinary data properties.");
+    }
+    result[key] = descriptor.value;
+  }
+  return result;
+}
+function dataArray(value, maximum) {
+  if (!Array.isArray(value) || value.length > maximum || Reflect.ownKeys(value).length !== value.length + 1) {
+    throw new TypeError("Host binding arrays must be bounded and dense.");
+  }
+  const result = [];
+  for (let index = 0; index < value.length; index += 1) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
+      throw new TypeError("Host binding arrays must contain ordinary data values.");
+    }
+    result.push(descriptor.value);
+  }
+  return result;
+}
+function exactKeys(value, allowed, required = []) {
+  if (Object.keys(value).some((key) => !allowed.includes(key)) || required.some((key) => !Object.hasOwn(value, key))) {
+    throw new TypeError("Host binding data has unexpected or missing fields.");
+  }
+}
+function integerBound(value, maximum) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > maximum) {
+    throw new TypeError("Tool schema limits must be bounded nonnegative integers.");
+  }
+  return value;
+}
+function parseAgentHostToolInputSchema(input) {
+  let nodes = 0;
+  const active = /* @__PURE__ */ new WeakSet();
+  const visit = (value, depth) => {
+    if (++nodes > 256 || depth > 8 || !value || typeof value !== "object" || active.has(value)) {
+      throw new TypeError("Tool schemas must be bounded and acyclic.");
+    }
+    active.add(value);
+    try {
+      const source = dataRecord(value);
+      if (depth === 0 && (source.$schema !== AGENT_HOST_TOOL_SCHEMA_DIALECT || source.type !== "object")) {
+        throw new TypeError("Tool inputs require an object schema using JSON Schema 2020-12.");
+      }
+      const keys = ["type", "description", ...depth === 0 ? ["$schema"] : []];
+      const result = { type: source.type };
+      if (depth === 0) result.$schema = AGENT_HOST_TOOL_SCHEMA_DIALECT;
+      if (source.description !== void 0) {
+        if (typeof source.description !== "string" || source.description.length > 2e3) {
+          throw new TypeError("Tool schema descriptions must be bounded strings.");
+        }
+        result.description = source.description;
+      }
+      switch (source.type) {
+        case "object": {
+          exactKeys(source, [...keys, "properties", "required", "additionalProperties"], ["properties", "additionalProperties"]);
+          if (source.additionalProperties !== false) throw new TypeError("Tool objects must reject additional properties.");
+          const properties = dataRecord(source.properties);
+          if (Object.keys(properties).length > 100) throw new TypeError("Tool objects have too many properties.");
+          const parsedProperties = /* @__PURE__ */ Object.create(null);
+          for (const [key, property] of Object.entries(properties)) {
+            if (key.length < 1 || key.length > 128) throw new TypeError("Tool property names must be bounded.");
+            parsedProperties[key] = visit(property, depth + 1);
+          }
+          result.properties = Object.freeze(parsedProperties);
+          result.additionalProperties = false;
+          if (source.required !== void 0) {
+            const required = dataArray(source.required, 100);
+            if (new Set(required).size !== required.length || required.some((key) => typeof key !== "string" || !Object.hasOwn(properties, key))) {
+              throw new TypeError("Required tool properties must be unique declared keys.");
+            }
+            result.required = Object.freeze([...required]);
+          }
+          break;
+        }
+        case "array": {
+          exactKeys(source, [...keys, "items", "minItems", "maxItems"], ["items", "maxItems"]);
+          const maximum = integerBound(source.maxItems, 100);
+          result.maxItems = maximum;
+          if (source.minItems !== void 0) result.minItems = integerBound(source.minItems, maximum);
+          result.items = visit(source.items, depth + 1);
+          break;
+        }
+        case "string": {
+          exactKeys(source, [...keys, "enum", "minLength", "maxLength"], ["maxLength"]);
+          const maximum = integerBound(source.maxLength, 16e3);
+          const minimum = source.minLength === void 0 ? 0 : integerBound(source.minLength, maximum);
+          result.maxLength = maximum;
+          if (source.minLength !== void 0) result.minLength = minimum;
+          if (source.enum !== void 0) {
+            const values = dataArray(source.enum, 100);
+            if (values.length === 0 || new Set(values).size !== values.length || values.some((entry) => typeof entry !== "string" || [...entry].length < minimum || [...entry].length > maximum)) {
+              throw new TypeError("Tool string enums must contain unique strings within their limits.");
+            }
+            result.enum = Object.freeze([...values]);
+          }
+          break;
+        }
+        case "integer":
+        case "number": {
+          exactKeys(source, [...keys, "minimum", "maximum"]);
+          for (const key of ["minimum", "maximum"]) {
+            const bound = source[key];
+            if (bound === void 0) continue;
+            if (typeof bound !== "number" || !Number.isFinite(bound) || source.type === "integer" && !Number.isSafeInteger(bound)) {
+              throw new TypeError("Tool numeric limits must be finite and type-correct.");
+            }
+            result[key] = bound;
+          }
+          if (typeof source.minimum === "number" && typeof source.maximum === "number" && source.minimum > source.maximum) {
+            throw new TypeError("Tool numeric limits must be ordered.");
+          }
+          break;
+        }
+        case "boolean":
+        case "null":
+          exactKeys(source, keys);
+          break;
+        default:
+          throw new TypeError("Tool schema type is unsupported.");
+      }
+      return Object.freeze(result);
+    } finally {
+      active.delete(value);
+    }
+  };
+  const schema = visit(input, 0);
+  if (agentProtocolSerializedJsonBytes(schema) > 8192) {
+    throw new TypeError("Tool schemas cannot exceed 8 KiB.");
+  }
+  return schema;
+}
+function matchesAgentHostToolSchema(schema, value) {
+  switch (schema.type) {
+    case "object":
+      return value !== null && typeof value === "object" && !Array.isArray(value) && (schema.required ?? []).every((key) => Object.hasOwn(value, key)) && Object.entries(value).every(([key, entry]) => Object.hasOwn(schema.properties, key) && matchesAgentHostToolSchema(schema.properties[key], entry));
+    case "array":
+      return Array.isArray(value) && value.length >= (schema.minItems ?? 0) && value.length <= schema.maxItems && value.every((entry) => matchesAgentHostToolSchema(schema.items, entry));
+    case "string":
+      return typeof value === "string" && [...value].length >= (schema.minLength ?? 0) && [...value].length <= schema.maxLength && (schema.enum === void 0 || schema.enum.includes(value));
+    case "number":
+    case "integer":
+      return typeof value === "number" && Number.isFinite(value) && (schema.type !== "integer" || Number.isSafeInteger(value)) && (schema.minimum === void 0 || value >= schema.minimum) && (schema.maximum === void 0 || value <= schema.maximum);
+    case "boolean":
+      return typeof value === "boolean";
+    case "null":
+      return value === null;
+  }
+}
+export {
+  AGENT_HOST_TOOL_SCHEMA_DIALECT,
+  dataArray,
+  dataRecord,
+  exactKeys,
+  matchesAgentHostToolSchema,
+  parseAgentHostToolInputSchema
+};

package/dist/hostBindings/types.d.ts

@@ -0,0 +1,71 @@
+import type { AgentError, AgentJsonValue } from "@agen-ai/agent-protocol";
+import type { MaybePromise } from "../foundation.js";
+export type AgentHostInstructionPlacement = "system" | "developer" | "tool_context";
+export type AgentSessionHostBindingSupport = Readonly<{
+    kind: "unsupported";
+}> | Readonly<{
+    kind: "supported";
+    toolTransport: "callback" | "mcp";
+    instructionPlacements: readonly AgentHostInstructionPlacement[];
+}>;
+interface AgentHostToolSchemaDescription {
+    readonly description?: string;
+}
+export interface AgentHostToolObjectSchema extends AgentHostToolSchemaDescription {
+    readonly type: "object";
+    readonly properties: Readonly<Record<string, AgentHostToolSchema>>;
+    readonly required?: readonly string[];
+    readonly additionalProperties: false;
+}
+export interface AgentHostToolInputSchema extends AgentHostToolObjectSchema {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+}
+export type AgentHostToolSchema = AgentHostToolSchemaDescription & (AgentHostToolObjectSchema | Readonly<{
+    type: "array";
+    items: AgentHostToolSchema;
+    minItems?: number;
+    maxItems: number;
+}> | Readonly<{
+    type: "string";
+    enum?: readonly string[];
+    minLength?: number;
+    maxLength: number;
+}> | Readonly<{
+    type: "integer" | "number";
+    minimum?: number;
+    maximum?: number;
+}> | Readonly<{
+    type: "boolean";
+}> | Readonly<{
+    type: "null";
+}>);
+export interface AgentHostToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: AgentHostToolInputSchema;
+}
+export type AgentHostToolResult = Readonly<{
+    kind: "success";
+    value: AgentJsonValue;
+}> | Readonly<{
+    kind: "error";
+    error: AgentError;
+}>;
+export interface AgentHostToolInvocation {
+    readonly invocationId: string;
+    readonly toolName: string;
+    readonly arguments: Readonly<Record<string, AgentJsonValue>>;
+    readonly signal?: AbortSignal;
+}
+export interface AgentSessionHostBinding {
+    readonly bindingId: string;
+    readonly tools: readonly AgentHostToolDefinition[];
+    readonly instructions?: Readonly<{
+        placement: AgentHostInstructionPlacement;
+        text: string;
+    }>;
+    readonly invoke: (input: AgentHostToolInvocation) => MaybePromise<AgentHostToolResult>;
+    readonly release: () => MaybePromise<void>;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/hostBindings/validation.d.ts

@@ -0,0 +1,14 @@
+import type { AgentHostToolInvocation, AgentHostToolResult, AgentSessionHostBinding, AgentSessionHostBindingSupport } from "./types.js";
+export declare function validateAgentSessionHostBindingSupport(value: unknown): AgentSessionHostBindingSupport;
+export declare function hostBindingEnvelope(value: unknown): AgentSessionHostBinding;
+export declare function validateAgentSessionHostBinding(input: Readonly<{
+    binding: AgentSessionHostBinding;
+    support: AgentSessionHostBindingSupport;
+}>): AgentSessionHostBinding;
+/** Validate transport data against an already validated binding without claiming its lifetime. */
+export declare function validateAgentHostToolInvocation(input: Readonly<{
+    binding: Pick<AgentSessionHostBinding, "tools">;
+    invocation: AgentHostToolInvocation;
+}>): AgentHostToolInvocation;
+export declare function validateAgentHostToolResult(value: unknown): AgentHostToolResult;
+//# sourceMappingURL=validation.d.ts.map

package/dist/hostBindings/validation.js

@@ -0,0 +1,107 @@
+import { agentProtocolSerializedJsonBytes, parseAgentError, parseAgentJsonValue } from "@agen-ai/agent-protocol";
+import { parseAgentBoundedText, parseAgentProviderTechnicalId } from "../foundation.js";
+import { dataArray, dataRecord, exactKeys, matchesAgentHostToolSchema, parseAgentHostToolInputSchema } from "./schema.js";
+const placements = ["system", "developer", "tool_context"];
+function validateAgentSessionHostBindingSupport(value) {
+  if (value === void 0) return Object.freeze({ kind: "unsupported" });
+  const source = dataRecord(value);
+  if (source.kind === "unsupported") {
+    exactKeys(source, ["kind"]);
+    return Object.freeze({ kind: "unsupported" });
+  }
+  exactKeys(source, ["kind", "toolTransport", "instructionPlacements"], ["kind", "toolTransport", "instructionPlacements"]);
+  const instructions = dataArray(source.instructionPlacements, 3);
+  if (source.kind !== "supported" || !["callback", "mcp"].includes(source.toolTransport) || new Set(instructions).size !== instructions.length || instructions.some((placement) => !placements.includes(placement))) {
+    throw new TypeError("Host binding support has an invalid declaration.");
+  }
+  return Object.freeze({
+    kind: "supported",
+    toolTransport: source.toolTransport,
+    instructionPlacements: Object.freeze([...instructions])
+  });
+}
+function hostBindingEnvelope(value) {
+  const source = dataRecord(value);
+  parseAgentProviderTechnicalId(source.bindingId, "host binding ID");
+  if (typeof source.invoke !== "function" || typeof source.release !== "function") {
+    throw new TypeError("Host bindings require invocation and release callbacks.");
+  }
+  return value;
+}
+function validateAgentSessionHostBinding(input) {
+  const binding = hostBindingEnvelope(input.binding);
+  const source = dataRecord(binding);
+  exactKeys(source, ["bindingId", "tools", "instructions", "invoke", "release"], ["bindingId", "tools", "invoke", "release"]);
+  const support = validateAgentSessionHostBindingSupport(input.support);
+  if (support.kind === "unsupported") throw new TypeError("Session host bindings are unsupported.");
+  const names = /* @__PURE__ */ new Set();
+  const tools = dataArray(source.tools, 32).map((value) => {
+    const tool = dataRecord(value);
+    exactKeys(tool, ["name", "description", "inputSchema"], ["name", "description", "inputSchema"]);
+    if (typeof tool.name !== "string" || !/^[A-Za-z][A-Za-z0-9_]{0,63}$/u.test(tool.name) || names.has(tool.name)) {
+      throw new TypeError("Tool names must be unique canonical identifiers.");
+    }
+    names.add(tool.name);
+    return Object.freeze({
+      name: tool.name,
+      description: parseAgentBoundedText(tool.description, "tool description", 2e3),
+      inputSchema: parseAgentHostToolInputSchema(tool.inputSchema)
+    });
+  });
+  if (tools.length === 0) throw new TypeError("Host bindings require at least one tool.");
+  let instructions;
+  if (source.instructions !== void 0) {
+    const instruction = dataRecord(source.instructions);
+    exactKeys(instruction, ["placement", "text"], ["placement", "text"]);
+    if (!support.instructionPlacements.includes(instruction.placement)) {
+      throw new TypeError("Host instruction placement is unsupported.");
+    }
+    const text = parseAgentBoundedText(instruction.text, "host instructions", 16e3);
+    if (new TextEncoder().encode(text).byteLength > 16384) throw new TypeError("Host instructions exceed 16 KiB.");
+    instructions = Object.freeze({ placement: instruction.placement, text });
+  }
+  const metadata = {
+    bindingId: binding.bindingId,
+    tools: Object.freeze(tools),
+    ...instructions === void 0 ? {} : { instructions }
+  };
+  if (agentProtocolSerializedJsonBytes(metadata) > 65536) {
+    throw new TypeError("Host binding metadata exceeds 64 KiB.");
+  }
+  return Object.freeze({ ...metadata, invoke: binding.invoke.bind(binding), release: binding.release.bind(binding) });
+}
+function validateAgentHostToolInvocation(input) {
+  const call = dataRecord(input.invocation);
+  exactKeys(call, ["invocationId", "toolName", "arguments", "signal"], ["invocationId", "toolName", "arguments"]);
+  if (call.signal !== void 0 && !(call.signal instanceof AbortSignal)) throw new TypeError("Tool cancellation requires an AbortSignal.");
+  const invocationId = parseAgentProviderTechnicalId(call.invocationId, "host tool invocation ID");
+  const tool = input.binding.tools.find((entry) => entry.name === call.toolName);
+  const args = parseAgentJsonValue(call.arguments);
+  if (!tool || !matchesAgentHostToolSchema(tool.inputSchema, args)) throw new TypeError("Tool arguments do not match its schema.");
+  return Object.freeze({
+    invocationId,
+    toolName: tool.name,
+    arguments: args,
+    ...call.signal === void 0 ? {} : { signal: call.signal }
+  });
+}
+function validateAgentHostToolResult(value) {
+  const parsed = parseAgentJsonValue(value);
+  const source = dataRecord(parsed);
+  if (source.kind === "success") {
+    exactKeys(source, ["kind", "value"], ["kind", "value"]);
+    return Object.freeze({ kind: "success", value: source.value });
+  }
+  if (source.kind === "error") {
+    exactKeys(source, ["kind", "error"], ["kind", "error"]);
+    return Object.freeze({ kind: "error", error: parseAgentError(source.error) });
+  }
+  throw new TypeError("Host tool results require success or error disposition.");
+}
+export {
+  hostBindingEnvelope,
+  validateAgentHostToolInvocation,
+  validateAgentHostToolResult,
+  validateAgentSessionHostBinding,
+  validateAgentSessionHostBindingSupport
+};

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from "./artifacts.js";
 export * from "./contractErrors.js";
 export * from "./evidence.js";
 export * from "./foundation.js";
+export * from "./hostBindings/index.js";
 export * from "./interactionValidation.js";
 export * from "./outputs.js";
 export * from "./providerCatalog.js";
@@ -12,5 +13,7 @@ export * from "./providerDriver.js";
 export * from "./providerInstanceRegistry.js";
 export * from "./readiness.js";
 export * from "./sessions.js";
+export * from "./sessionInteractions/index.js";
+export { createAgentProviderSessionCleanupError, isAgentProviderSessionCleanupErrorFor } from "./sessionCleanup.js";
 export * from "./text.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -5,6 +5,7 @@ export * from "./artifacts.js";
 export * from "./contractErrors.js";
 export * from "./evidence.js";
 export * from "./foundation.js";
+export * from "./hostBindings/index.js";
 export * from "./interactionValidation.js";
 export * from "./outputs.js";
 export * from "./providerCatalog.js";
@@ -12,4 +13,10 @@ export * from "./providerDriver.js";
 export * from "./providerInstanceRegistry.js";
 export * from "./readiness.js";
 export * from "./sessions.js";
+export * from "./sessionInteractions/index.js";
+import { createAgentProviderSessionCleanupError, isAgentProviderSessionCleanupErrorFor } from "./sessionCleanup.js";
 export * from "./text.js";
+export {
+  createAgentProviderSessionCleanupError,
+  isAgentProviderSessionCleanupErrorFor
+};

package/dist/internal/objectShape.d.ts

@@ -0,0 +1,2 @@
+export declare function hasExactOwnKeys(candidate: object, expectedKeys: readonly string[]): boolean;
+//# sourceMappingURL=objectShape.d.ts.map

package/dist/internal/objectShape.js

@@ -0,0 +1,7 @@
+function hasExactOwnKeys(candidate, expectedKeys) {
+  const ownKeys = Reflect.ownKeys(candidate);
+  return ownKeys.length === expectedKeys.length && ownKeys.every((key) => typeof key === "string" && expectedKeys.includes(key));
+}
+export {
+  hasExactOwnKeys
+};

package/dist/outputValidation.js

@@ -56,8 +56,8 @@ function isApprovalRequestCapabilitySupported(capabilities, event) {
   if (request.requestKind !== "approval") return false;
   const capability = capabilities.requests.approval;
   return capability.kind === "supported" && request.options.every(
-    (option) => capability.modes.some(
-      (mode) => mode.persistence === option.persistence && mode.scopeKinds.includes(option.scope.kind)
+    ({ consequence }) => consequence.kind === "provider_managed_remembrance" ? capability.providerManagedRemembrance : capability.modes.some(
+      (mode) => mode.persistence === consequence.persistence && mode.scopeKinds.includes(consequence.scope.kind)
     )
   );
 }
@@ -123,6 +123,7 @@ function isEventCapabilitySupported(capabilities, event) {
     case "turn.state_changed":
     case "turn.completed":
     case "progress.updated":
+    case "runtime.retrying":
     case "runtime.warning":
     case "runtime.error":
     case "provider.diagnostic":

package/dist/providerDriver.js

@@ -11,7 +11,6 @@ class AgentProviderConfigurationError extends Error {
     this.providerKey = providerKey;
     this.name = "AgentProviderConfigurationError";
   }
-  providerKey;
 }
 function defineAgentProviderDriver(definition) {
   const providerKey = parseAgentProviderKey(definition.providerKey);

package/dist/providerInstanceRegistry.js

@@ -213,7 +213,8 @@ async function materializeInstances(input) {
         providerKey: definition.providerKey,
         instanceId: definition.instanceId,
         cleanupFailureInstanceIds,
-        message: error instanceof AgentProviderConfigurationError ? `Agent provider configuration is invalid for ${definition.instanceId}.` : `Agent provider instance ${definition.instanceId} could not be materialized.`
+        message: error instanceof AgentProviderConfigurationError ? `Agent provider configuration is invalid for ${definition.instanceId}.` : `Agent provider instance ${definition.instanceId} could not be materialized.`,
+        cause: error
       });
     }
     let managed;

package/dist/sessionCleanup.d.ts

@@ -0,0 +1,9 @@
+import { AgentProviderSessionCleanupError } from "./contractErrors.js";
+import type { AgentProviderSessionContext } from "./sessions.js";
+/** Retain provider cleanup for the exact input received by a create/resume/branch port. */
+export declare function createAgentProviderSessionCleanupError(input: ConstructorParameters<typeof AgentProviderSessionCleanupError>[0] & Readonly<{
+    openingInput: AgentProviderSessionContext;
+}>): AgentProviderSessionCleanupError;
+export declare function associateAgentSessionCleanupError<Error extends AgentProviderSessionCleanupError>(error: Error, openingInput: object): Error;
+export declare function isAgentProviderSessionCleanupErrorFor(error: unknown, openingInput: object): error is AgentProviderSessionCleanupError;
+//# sourceMappingURL=sessionCleanup.d.ts.map

package/dist/sessionCleanup.js

@@ -0,0 +1,17 @@
+import { AgentProviderSessionCleanupError } from "./contractErrors.js";
+const openingOwners = /* @__PURE__ */ new WeakMap();
+function createAgentProviderSessionCleanupError(input) {
+  return associateAgentSessionCleanupError(new AgentProviderSessionCleanupError(input), input.openingInput);
+}
+function associateAgentSessionCleanupError(error, openingInput) {
+  openingOwners.set(error, openingInput);
+  return error;
+}
+function isAgentProviderSessionCleanupErrorFor(error, openingInput) {
+  return error instanceof AgentProviderSessionCleanupError && openingOwners.get(error) === openingInput;
+}
+export {
+  associateAgentSessionCleanupError,
+  createAgentProviderSessionCleanupError,
+  isAgentProviderSessionCleanupErrorFor
+};

package/dist/sessionInteractions/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/sessionInteractions/index.js

@@ -0,0 +1 @@
+export * from "./types.js";

package/dist/sessionInteractions/lifetime.d.ts

@@ -0,0 +1,52 @@
+import type { AgentError, AgentProviderKey, AgentSessionId } from "@agen-ai/agent-protocol";
+import type { MaybePromise } from "../foundation.js";
+import type { 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 facade: AgentSessionInteractionContext;
+    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 cleanupFailure;
+    private adopted;
+    private readonly context;
+    constructor(providerKey: AgentProviderKey, sessionId: AgentSessionId, context: AgentSessionInteractionContext, signal?: AbortSignal);
+    track<Result>(promise: Promise<Result>): Promise<Result>;
+    get accepting(): boolean;
+    requireUsable(): void;
+    private offer;
+    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;
+    context?: AgentSessionInteractionContext;
+    signal?: AbortSignal;
+}>): SessionInteractionOwner | undefined;
+//# sourceMappingURL=lifetime.d.ts.map