@agen-ai/agent-runtime 0.1.0

package/dist/providerInstanceRegistry.js

@@ -0,0 +1,322 @@
+import {
+  parseAgentCapabilities,
+  parseAgentInstanceId,
+  parseAgentProviderKey
+} from "@agen-ai/agent-protocol";
+import { validateAgentProviderAdapter } from "./adapterValidation.js";
+import {
+  createAgentProviderCatalogEntries,
+  createAgentProviderInstanceCatalogEntries
+} from "./providerCatalog.js";
+import {
+  AgentProviderConfigurationError
+} from "./providerDriver.js";
+import {
+  validateAgentProviderReadiness
+} from "./readiness.js";
+const AGENT_PROVIDER_REGISTRY_ERROR_CODES = [
+  "invalid_driver",
+  "duplicate_provider",
+  "duplicate_instance",
+  "provider_not_registered",
+  "multiple_instances_unsupported",
+  "invalid_instance_configuration",
+  "instance_materialization_failed",
+  "instance_contract_mismatch",
+  "instance_not_found",
+  "instance_disposed",
+  "instance_cleanup_failed",
+  "registry_disposed"
+];
+class AgentProviderRegistryError extends Error {
+  code;
+  providerKey;
+  instanceId;
+  cleanupFailureInstanceIds;
+  constructor(input) {
+    super(
+      input.message,
+      input.cause === void 0 ? void 0 : { cause: input.cause }
+    );
+    this.name = "AgentProviderRegistryError";
+    this.code = input.code;
+    this.providerKey = input.providerKey;
+    this.instanceId = input.instanceId;
+    this.cleanupFailureInstanceIds = Object.freeze([
+      ...input.cleanupFailureInstanceIds ?? []
+    ]);
+  }
+}
+function validateDrivers(drivers) {
+  const driverMap = /* @__PURE__ */ new Map();
+  for (const candidate of drivers) {
+    let providerKey;
+    try {
+      providerKey = parseAgentProviderKey(candidate?.providerKey);
+    } catch (cause) {
+      throw new AgentProviderRegistryError({
+        code: "invalid_driver",
+        message: "Agent provider driver has an invalid provider key.",
+        cause
+      });
+    }
+    const supportsMultipleInstances = candidate.supportsMultipleInstances;
+    const materialize = candidate.materialize;
+    if (typeof supportsMultipleInstances !== "boolean" || typeof materialize !== "function") {
+      throw new AgentProviderRegistryError({
+        code: "invalid_driver",
+        providerKey,
+        message: `Agent provider driver ${providerKey} has an invalid runtime contract.`
+      });
+    }
+    if (driverMap.has(providerKey)) {
+      throw new AgentProviderRegistryError({
+        code: "duplicate_provider",
+        providerKey,
+        message: `Duplicate agent provider driver registered for ${providerKey}.`
+      });
+    }
+    driverMap.set(
+      providerKey,
+      Object.freeze({
+        providerKey,
+        supportsMultipleInstances,
+        materialize: (definition) => materialize.call(candidate, definition)
+      })
+    );
+  }
+  return driverMap;
+}
+function validateDefinitions(input) {
+  const instanceIds = /* @__PURE__ */ new Set();
+  const providerCounts = /* @__PURE__ */ new Map();
+  for (const definition of input.definitions) {
+    const instanceId = parseAgentInstanceId(definition.instanceId);
+    const providerKey = parseAgentProviderKey(definition.providerKey);
+    if (instanceIds.has(instanceId)) {
+      throw new AgentProviderRegistryError({
+        code: "duplicate_instance",
+        providerKey,
+        instanceId,
+        message: `Duplicate agent provider instance ${instanceId}.`
+      });
+    }
+    instanceIds.add(instanceId);
+    const driver = input.drivers.get(providerKey);
+    if (!driver) {
+      throw new AgentProviderRegistryError({
+        code: "provider_not_registered",
+        providerKey,
+        instanceId,
+        message: `No agent provider driver is registered for ${providerKey}.`
+      });
+    }
+    const providerCount = (providerCounts.get(driver.providerKey) ?? 0) + 1;
+    providerCounts.set(driver.providerKey, providerCount);
+    if (!driver.supportsMultipleInstances && providerCount > 1) {
+      throw new AgentProviderRegistryError({
+        code: "multiple_instances_unsupported",
+        providerKey: driver.providerKey,
+        instanceId,
+        message: `Agent provider ${driver.providerKey} does not support multiple instances.`
+      });
+    }
+  }
+}
+function managedInstance(rawInstance, providerKey) {
+  if (!rawInstance || typeof rawInstance !== "object" || typeof rawInstance.checkReadiness !== "function" || typeof rawInstance.dispose !== "function") {
+    throw new AgentProviderRegistryError({
+      code: "instance_contract_mismatch",
+      providerKey,
+      message: "Materialized instance must expose callable readiness and disposal ports."
+    });
+  }
+  const capabilities = parseAgentCapabilities(rawInstance.capabilities);
+  const checkReadiness = rawInstance.checkReadiness.bind(rawInstance);
+  const dispose = rawInstance.dispose.bind(rawInstance);
+  const lifecycle = {
+    status: "active",
+    disposePromise: null
+  };
+  const instance = Object.freeze({
+    instanceId: parseAgentInstanceId(rawInstance.instanceId),
+    capabilities,
+    adapter: validateAgentProviderAdapter(capabilities, rawInstance.adapter),
+    checkReadiness: async (input) => {
+      const readiness = await checkReadiness(input);
+      return validateAgentProviderReadiness(readiness);
+    },
+    dispose: () => {
+      if (lifecycle.status === "disposed") return Promise.resolve();
+      if (lifecycle.disposePromise) return lifecycle.disposePromise;
+      lifecycle.status = "disposing";
+      lifecycle.disposePromise = Promise.resolve().then(() => dispose()).then(() => {
+        lifecycle.status = "disposed";
+      }).catch((error) => {
+        lifecycle.status = "dispose_failed";
+        throw error;
+      }).finally(() => {
+        lifecycle.disposePromise = null;
+      });
+      return lifecycle.disposePromise;
+    }
+  });
+  if (capabilities.providerKey !== providerKey) {
+    throw new AgentProviderRegistryError({
+      code: "instance_contract_mismatch",
+      providerKey,
+      instanceId: instance.instanceId,
+      message: "Materialized instance capabilities identify another provider."
+    });
+  }
+  return { instance, lifecycle };
+}
+async function disposeInstances(instances) {
+  const failures = [];
+  for (const { instance } of [...instances].reverse()) {
+    try {
+      await instance.dispose();
+    } catch {
+      failures.push(instance.instanceId);
+    }
+  }
+  return failures;
+}
+async function materializeInstances(input) {
+  const instances = [];
+  for (const definition of input.definitions) {
+    const driver = input.drivers.get(definition.providerKey);
+    let rawInstance;
+    try {
+      rawInstance = await driver.materialize(definition);
+    } catch (error) {
+      const cleanupFailureInstanceIds = await disposeInstances(instances);
+      throw new AgentProviderRegistryError({
+        code: error instanceof AgentProviderConfigurationError ? "invalid_instance_configuration" : "instance_materialization_failed",
+        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.`
+      });
+    }
+    let managed;
+    try {
+      managed = managedInstance(rawInstance, definition.providerKey);
+      if (managed.instance.instanceId !== definition.instanceId) {
+        throw new AgentProviderRegistryError({
+          code: "instance_contract_mismatch",
+          providerKey: definition.providerKey,
+          instanceId: definition.instanceId,
+          message: "Materialized instance returned another instanceId."
+        });
+      }
+    } catch (error) {
+      let currentCleanupError;
+      try {
+        await rawInstance.dispose();
+      } catch (cleanupError) {
+        currentCleanupError = cleanupError;
+      }
+      const priorCleanupFailureIds = await disposeInstances(instances);
+      const cleanupFailureInstanceIds = [
+        ...currentCleanupError === void 0 ? [] : [definition.instanceId],
+        ...priorCleanupFailureIds
+      ];
+      throw new AgentProviderRegistryError({
+        code: "instance_contract_mismatch",
+        providerKey: definition.providerKey,
+        instanceId: definition.instanceId,
+        cleanupFailureInstanceIds,
+        message: error instanceof AgentProviderRegistryError ? error.message : `Materialized instance ${definition.instanceId} violates the provider contract.`,
+        cause: currentCleanupError === void 0 ? error : new AggregateError(
+          [error, currentCleanupError],
+          "Materialized instance contract validation and cleanup failed."
+        )
+      });
+    }
+    instances.push(managed);
+  }
+  return instances;
+}
+async function createAgentProviderRegistry(input) {
+  const drivers = validateDrivers(input.drivers);
+  validateDefinitions({ definitions: input.definitions, drivers });
+  const managedInstances = await materializeInstances({
+    definitions: input.definitions,
+    drivers
+  });
+  const instanceMap = new Map(
+    managedInstances.map((managed) => [managed.instance.instanceId, managed])
+  );
+  const providerCatalog = createAgentProviderCatalogEntries(drivers.values());
+  let registryStatus = "active";
+  let registryDisposePromise = null;
+  const getInstance = (instanceIdInput) => {
+    if (registryStatus !== "active") return null;
+    const instanceId = parseAgentInstanceId(instanceIdInput);
+    const managed = instanceMap.get(instanceId);
+    return managed?.lifecycle.status === "active" ? managed.instance : null;
+  };
+  const lookupError = (instanceId) => {
+    if (registryStatus !== "active") {
+      return new AgentProviderRegistryError({
+        code: "registry_disposed",
+        instanceId,
+        message: "Agent provider registry is disposed."
+      });
+    }
+    const managed = instanceMap.get(instanceId);
+    return new AgentProviderRegistryError({
+      code: managed ? "instance_disposed" : "instance_not_found",
+      instanceId,
+      providerKey: managed?.instance.capabilities.providerKey,
+      message: managed ? `Agent provider instance ${instanceId} is disposed.` : `Agent provider instance ${instanceId} is not registered.`
+    });
+  };
+  const requireInstance = (instanceId) => {
+    const instance = getInstance(instanceId);
+    if (!instance) throw lookupError(instanceId);
+    return instance;
+  };
+  const dispose = () => {
+    if (registryStatus === "disposed") return Promise.resolve();
+    if (registryDisposePromise) return registryDisposePromise;
+    registryStatus = "disposing";
+    registryDisposePromise = disposeInstances(managedInstances).then((cleanupFailureInstanceIds) => {
+      if (cleanupFailureInstanceIds.length > 0) {
+        throw new AgentProviderRegistryError({
+          code: "instance_cleanup_failed",
+          instanceId: cleanupFailureInstanceIds[0],
+          cleanupFailureInstanceIds,
+          message: `${cleanupFailureInstanceIds.length} agent provider cleanup operation(s) failed.`
+        });
+      }
+      registryStatus = "disposed";
+    }).catch((error) => {
+      registryStatus = "dispose_failed";
+      throw error;
+    }).finally(() => {
+      registryDisposePromise = null;
+    });
+    return registryDisposePromise;
+  };
+  return Object.freeze({
+    listProviderCatalogEntries: () => registryStatus === "active" ? providerCatalog : [],
+    listInstanceCatalogEntries: () => registryStatus === "active" ? createAgentProviderInstanceCatalogEntries(
+      managedInstances.filter(({ lifecycle }) => lifecycle.status === "active").map(({ instance }) => instance)
+    ) : [],
+    listInstances: () => registryStatus === "active" ? managedInstances.filter(({ lifecycle }) => lifecycle.status === "active").map(({ instance }) => instance) : [],
+    getInstance,
+    hasInstance: (instanceId) => getInstance(instanceId) !== null,
+    requireInstance,
+    checkReadiness: async (instanceId, readinessInput) => {
+      return requireInstance(instanceId).checkReadiness(readinessInput);
+    },
+    dispose
+  });
+}
+export {
+  AGENT_PROVIDER_REGISTRY_ERROR_CODES,
+  AgentProviderRegistryError,
+  createAgentProviderRegistry
+};

package/dist/readiness.d.ts

@@ -0,0 +1,22 @@
+import { type AgentError, type AgentIsoDateTime } from "@agen-ai/agent-protocol";
+import { type BoundedAgentProviderData } from "./evidence.js";
+export declare const AGENT_PROVIDER_READINESS_STATUSES: readonly ["ready", "missing_executable", "missing_credentials", "unsupported_version", "unavailable"];
+export type AgentProviderReadinessStatus = (typeof AGENT_PROVIDER_READINESS_STATUSES)[number];
+export interface AgentProviderReadiness {
+    readonly status: AgentProviderReadinessStatus;
+    readonly checkedAt: AgentIsoDateTime;
+    readonly version?: string;
+    readonly reason?: AgentError;
+    readonly diagnostics: BoundedAgentProviderData;
+}
+export interface CreateAgentProviderReadinessInput {
+    readonly status: AgentProviderReadinessStatus;
+    readonly checkedAt: string;
+    readonly version?: string;
+    readonly reason?: AgentError;
+    readonly diagnostics?: unknown;
+    readonly diagnosticsBytesLimit?: number;
+}
+export declare function createAgentProviderReadiness(input: CreateAgentProviderReadinessInput): AgentProviderReadiness;
+export declare function validateAgentProviderReadiness(input: AgentProviderReadiness): AgentProviderReadiness;
+//# sourceMappingURL=readiness.d.ts.map

package/dist/readiness.js

@@ -0,0 +1,58 @@
+import {
+  parseAgentError,
+  parseAgentIsoDateTime
+} from "@agen-ai/agent-protocol";
+import {
+  createBoundedAgentProviderData,
+  validateBoundedAgentProviderData
+} from "./evidence.js";
+import { parseAgentCanonicalText } from "./foundation.js";
+const AGENT_PROVIDER_READINESS_STATUSES = [
+  "ready",
+  "missing_executable",
+  "missing_credentials",
+  "unsupported_version",
+  "unavailable"
+];
+function validatedReadinessReason(status, reason) {
+  if (status === "ready" && reason !== void 0) {
+    throw new TypeError("Ready providers cannot report a failure reason.");
+  }
+  return reason === void 0 ? void 0 : parseAgentError(reason);
+}
+function createAgentProviderReadiness(input) {
+  if (!AGENT_PROVIDER_READINESS_STATUSES.includes(input.status)) {
+    throw new TypeError("Provider readiness status is unsupported.");
+  }
+  const version = input.version === void 0 ? void 0 : parseAgentCanonicalText(input.version, "Provider version", 160);
+  const reason = validatedReadinessReason(input.status, input.reason);
+  return Object.freeze({
+    status: input.status,
+    checkedAt: parseAgentIsoDateTime(input.checkedAt),
+    ...version === void 0 ? {} : { version },
+    ...reason === void 0 ? {} : { reason },
+    diagnostics: createBoundedAgentProviderData(
+      input.diagnostics ?? {},
+      input.diagnosticsBytesLimit
+    )
+  });
+}
+function validateAgentProviderReadiness(input) {
+  if (input === null || typeof input !== "object" || !AGENT_PROVIDER_READINESS_STATUSES.includes(input.status)) {
+    throw new TypeError("Provider readiness is invalid.");
+  }
+  const version = input.version === void 0 ? void 0 : parseAgentCanonicalText(input.version, "Provider version", 160);
+  const reason = validatedReadinessReason(input.status, input.reason);
+  return Object.freeze({
+    status: input.status,
+    checkedAt: parseAgentIsoDateTime(input.checkedAt),
+    ...version === void 0 ? {} : { version },
+    ...reason === void 0 ? {} : { reason },
+    diagnostics: validateBoundedAgentProviderData(input.diagnostics)
+  });
+}
+export {
+  AGENT_PROVIDER_READINESS_STATUSES,
+  createAgentProviderReadiness,
+  validateAgentProviderReadiness
+};

package/dist/sessionValidation.d.ts

@@ -0,0 +1,19 @@
+import { type AgentCapabilities, type AgentSessionBinding, type AgentSessionId } from "@agen-ai/agent-protocol";
+import { type MaybePromise } from "./foundation.js";
+import type { AgentProviderSession, AgentSessionBindingCreatedObserver } from "./sessions.js";
+export declare function validateAgentProviderSession(input: {
+    readonly capabilities: AgentCapabilities;
+    readonly sessionId: AgentSessionId;
+    readonly candidate: AgentProviderSession;
+    readonly expectedBinding?: AgentSessionBinding;
+    readonly sourceBinding?: AgentSessionBinding;
+}): AgentProviderSession;
+export declare function closeRejectedAgentProviderSession(session: AgentProviderSession | null, error: unknown): Promise<never>;
+export declare function openIdentityCreatingAgentProviderSession(input: {
+    readonly capabilities: AgentCapabilities;
+    readonly sessionId: AgentSessionId;
+    readonly observer: AgentSessionBindingCreatedObserver;
+    readonly sourceBinding?: AgentSessionBinding;
+    readonly open: (observer: AgentSessionBindingCreatedObserver) => MaybePromise<AgentProviderSession>;
+}): Promise<AgentProviderSession>;
+//# sourceMappingURL=sessionValidation.d.ts.map