@agen-ai/agent-runtime 0.2.5 → 0.3.1

package/dist/environment/validation.js

@@ -0,0 +1,533 @@
+import path from "node:path";
+import {
+  AGENT_ENVIRONMENT_DOMAINS,
+  parseAgentEnvironmentId,
+  parseAgentEnvironmentInvalidation,
+  parseAgentEnvironmentSnapshot,
+  parseAgentSessionConfiguration
+} from "@agen-ai/agent-protocol";
+import { throwAgentProviderContractError } from "../contractErrors.js";
+import {
+  throwIfAgentOperationAborted
+} from "../foundation.js";
+import { containsAgentControlCharacter } from "../internal/controlCharacters.js";
+const AGENT_ENVIRONMENT_ITERATOR_CLEANUP_TIMEOUT_MS = 1e3;
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function exactKeys(value, expected) {
+  const actual = Reflect.ownKeys(value);
+  return actual.length === expected.length && actual.every((key) => typeof key === "string" && expected.includes(key)) && expected.every((key) => Object.prototype.hasOwnProperty.call(value, key));
+}
+function exactKeysWithOptional(value, required, optional) {
+  const actual = Reflect.ownKeys(value);
+  const allowed = [...required, ...optional];
+  return actual.length >= required.length && actual.length <= allowed.length && actual.every((key) => typeof key === "string" && allowed.includes(key)) && required.every((key) => Object.prototype.hasOwnProperty.call(value, key));
+}
+function assertSignal(value, field) {
+  if (!(value instanceof AbortSignal)) {
+    throw new TypeError(`Environment ${field} must be an AbortSignal.`);
+  }
+}
+function abortReason(signal) {
+  return signal.reason instanceof Error ? signal.reason : new DOMException("The agent operation was aborted.", "AbortError");
+}
+function environmentContractError(providerKey, detail) {
+  return throwAgentProviderContractError(
+    providerKey,
+    "capability_port_mismatch",
+    `Provider ${providerKey} returned an invalid environment ${detail}.`
+  );
+}
+function invalidEnvironmentMetadata(providerKey, detail) {
+  return throwAgentProviderContractError(
+    providerKey,
+    "invalid_inventory",
+    `Provider ${providerKey} returned invalid environment metadata: ${detail}.`
+  );
+}
+function sameDomains(actual, expected) {
+  return actual.length === expected.length && actual.every((domain, index) => domain === expected[index]);
+}
+function parsePortDomains(providerKey, value) {
+  if (!Array.isArray(value) || value.length < 1) {
+    return environmentContractError(providerKey, "port domains");
+  }
+  const domains = [];
+  for (const candidate of value) {
+    if (typeof candidate !== "string" || !AGENT_ENVIRONMENT_DOMAINS.includes(candidate) || domains.includes(candidate)) {
+      return environmentContractError(providerKey, "port domains");
+    }
+    domains.push(candidate);
+  }
+  return Object.freeze(domains);
+}
+function validateDeclaredPort(providerKey, capability, candidate) {
+  if (!isObject(candidate)) return environmentContractError(providerKey, "port");
+  const kind = candidate.kind;
+  if (kind === "unsupported") {
+    if (!exactKeys(candidate, ["kind"]) || capability.kind !== "unsupported") {
+      return environmentContractError(providerKey, "port");
+    }
+    return "unsupported";
+  }
+  if (kind !== "read" && kind !== "read_and_watch") {
+    return environmentContractError(providerKey, "port");
+  }
+  if (capability.kind === "unsupported" || capability.kind !== kind) {
+    return environmentContractError(providerKey, "port capability parity");
+  }
+  const expectedKeys = kind === "read" ? ["kind", "domains", "readEnvironment"] : ["kind", "domains", "readEnvironment", "watchEnvironment"];
+  if (!exactKeys(candidate, expectedKeys)) {
+    return environmentContractError(providerKey, "port shape");
+  }
+  const domains = parsePortDomains(
+    providerKey,
+    candidate.domains
+  );
+  if (!sameDomains(domains, capability.domains)) {
+    return environmentContractError(providerKey, "port capability domains");
+  }
+  if (typeof candidate.readEnvironment !== "function" || kind === "read_and_watch" && typeof candidate.watchEnvironment !== "function") {
+    return environmentContractError(providerKey, "port methods");
+  }
+  return kind;
+}
+function parseCanonicalWorkingDirectory(value) {
+  if (typeof value !== "string" || value.length < 1 || value.length > 4096 || !path.isAbsolute(value) || path.normalize(value) !== value || containsAgentControlCharacter(value)) {
+    throw new TypeError(
+      "Environment workingDirectory must be a canonical absolute path."
+    );
+  }
+  return value;
+}
+function parseDiscoveryInput(input) {
+  if (!isObject(input) || !exactKeysWithOptional(input, [
+    "signal",
+    "environmentId",
+    "workingDirectory",
+    "configuration"
+  ], ["onProviderExecutionStarted"])) {
+    throw new TypeError(
+      "Environment discovery input must contain signal, environmentId, workingDirectory, and configuration."
+    );
+  }
+  const candidate = input;
+  assertSignal(candidate.signal, "discovery signal");
+  if (candidate.onProviderExecutionStarted !== void 0 && typeof candidate.onProviderExecutionStarted !== "function") {
+    throw new TypeError(
+      "Environment discovery onProviderExecutionStarted must be callable."
+    );
+  }
+  return {
+    signal: candidate.signal,
+    environmentId: parseAgentEnvironmentId(candidate.environmentId),
+    workingDirectory: parseCanonicalWorkingDirectory(candidate.workingDirectory),
+    configuration: parseAgentSessionConfiguration(candidate.configuration),
+    ...candidate.onProviderExecutionStarted === void 0 ? {} : {
+      onProviderExecutionStarted: candidate.onProviderExecutionStarted
+    }
+  };
+}
+function parseDiscoveryWatchInput(input) {
+  if (!isObject(input) || !exactKeys(input, [
+    "signal",
+    "environmentId",
+    "workingDirectory",
+    "configuration"
+  ])) {
+    throw new TypeError(
+      "Environment discovery watch input must contain signal, environmentId, workingDirectory, and configuration."
+    );
+  }
+  const candidate = input;
+  assertSignal(candidate.signal, "discovery watch signal");
+  return {
+    signal: candidate.signal,
+    environmentId: parseAgentEnvironmentId(candidate.environmentId),
+    workingDirectory: parseCanonicalWorkingDirectory(candidate.workingDirectory),
+    configuration: parseAgentSessionConfiguration(candidate.configuration)
+  };
+}
+function parseObservationInput(input) {
+  if (!isObject(input) || !exactKeysWithOptional(
+    input,
+    ["signal", "environmentId"],
+    ["onProviderExecutionStarted"]
+  )) {
+    throw new TypeError(
+      "Environment observation input must contain signal and environmentId."
+    );
+  }
+  const candidate = input;
+  assertSignal(candidate.signal, "observation signal");
+  if (candidate.onProviderExecutionStarted !== void 0 && typeof candidate.onProviderExecutionStarted !== "function") {
+    throw new TypeError(
+      "Environment observation onProviderExecutionStarted must be callable."
+    );
+  }
+  return {
+    signal: candidate.signal,
+    environmentId: parseAgentEnvironmentId(candidate.environmentId),
+    ...candidate.onProviderExecutionStarted === void 0 ? {} : {
+      onProviderExecutionStarted: candidate.onProviderExecutionStarted
+    }
+  };
+}
+function parseObservationWatchInput(input) {
+  if (!isObject(input) || !exactKeys(input, ["signal", "environmentId"])) {
+    throw new TypeError(
+      "Environment observation watch input must contain signal and environmentId."
+    );
+  }
+  const candidate = input;
+  assertSignal(candidate.signal, "observation watch signal");
+  return {
+    signal: candidate.signal,
+    environmentId: parseAgentEnvironmentId(candidate.environmentId)
+  };
+}
+function validateSnapshotDomains(providerKey, snapshot, declaredDomains, maximumExtent) {
+  for (const domain of AGENT_ENVIRONMENT_DOMAINS) {
+    const result = snapshot[domain];
+    if (maximumExtent === "workspace_discovery" && result.kind === "available" && result.extent === "session") {
+      return invalidEnvironmentMetadata(
+        providerKey,
+        `instance discovery cannot claim session evidence for domain ${domain}`
+      );
+    }
+    if (!declaredDomains.includes(domain) && result.kind === "available") {
+      return invalidEnvironmentMetadata(
+        providerKey,
+        `domain ${domain} was marked available by an undeclared port domain`
+      );
+    }
+  }
+  return snapshot;
+}
+function validateSnapshot(providerKey, candidate, expectedEnvironmentId, declaredDomains, maximumExtent) {
+  let snapshot;
+  try {
+    snapshot = parseAgentEnvironmentSnapshot(candidate);
+  } catch {
+    return invalidEnvironmentMetadata(providerKey, "snapshot");
+  }
+  if (snapshot.environmentId !== expectedEnvironmentId) {
+    return invalidEnvironmentMetadata(providerKey, "snapshot environmentId does not echo the request");
+  }
+  return validateSnapshotDomains(providerKey, snapshot, declaredDomains, maximumExtent);
+}
+function validateInvalidation(providerKey, candidate, expectedEnvironmentId, declaredDomains) {
+  let invalidation;
+  try {
+    invalidation = parseAgentEnvironmentInvalidation(candidate);
+  } catch {
+    return invalidEnvironmentMetadata(providerKey, "invalidation");
+  }
+  if (invalidation.environmentId !== expectedEnvironmentId) {
+    return invalidEnvironmentMetadata(providerKey, "invalidation environmentId does not echo the request");
+  }
+  if (invalidation.domains.some((domain) => !declaredDomains.includes(domain))) {
+    return invalidEnvironmentMetadata(providerKey, "invalidation names an undeclared domain");
+  }
+  return invalidation;
+}
+function awaitCancellable(candidate, signal) {
+  const providerResult = Promise.resolve(candidate);
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const remove = () => signal.removeEventListener("abort", onAbort);
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      remove();
+      reject(abortReason(signal));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    providerResult.then(
+      (value) => {
+        if (settled) return;
+        settled = true;
+        remove();
+        resolve(value);
+      },
+      (error) => {
+        if (settled) return;
+        settled = true;
+        remove();
+        reject(error);
+      }
+    );
+    if (signal.aborted) onAbort();
+  });
+}
+function providerIterator(providerKey, iterable) {
+  if (!isObject(iterable)) return environmentContractError(providerKey, "watch result");
+  const factory = iterable[Symbol.asyncIterator];
+  if (typeof factory !== "function") {
+    return environmentContractError(providerKey, "watch iterator");
+  }
+  const iterator = factory.call(iterable);
+  if (!isObject(iterator)) return environmentContractError(providerKey, "watch iterator");
+  const next = iterator.next;
+  if (typeof next !== "function") {
+    return environmentContractError(providerKey, "watch iterator");
+  }
+  const returnMethod = iterator.return;
+  if (returnMethod !== void 0 && typeof returnMethod !== "function") {
+    return environmentContractError(providerKey, "watch iterator");
+  }
+  return {
+    iterator,
+    next,
+    returnMethod
+  };
+}
+function iteratorResult(value) {
+  if (!isObject(value)) return false;
+  const done = value.done;
+  return done === void 0 || typeof done === "boolean";
+}
+function boundedCleanup(result, providerKey) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(
+      `Provider ${providerKey} environment watch cleanup exceeded ${AGENT_ENVIRONMENT_ITERATOR_CLEANUP_TIMEOUT_MS}ms.`
+    )), AGENT_ENVIRONMENT_ITERATOR_CLEANUP_TIMEOUT_MS);
+  });
+  return Promise.race([Promise.resolve(result), timeout]).then(() => void 0).finally(() => {
+    if (timer !== void 0) clearTimeout(timer);
+  });
+}
+function beginCleanup(state) {
+  if (state.cleanupPromise !== void 0) return state.cleanupPromise;
+  const source = state.source;
+  if (source === void 0) return Promise.resolve();
+  if (source.returnMethod === void 0) {
+    state.cleanupPromise = Promise.resolve();
+  } else {
+    try {
+      state.cleanupPromise = boundedCleanup(
+        source.returnMethod.call(source.iterator),
+        state.providerKey
+      );
+    } catch (error) {
+      state.cleanupPromise = Promise.reject(error);
+    }
+  }
+  state.cleanupPromise.catch(() => void 0);
+  return state.cleanupPromise;
+}
+function closeState(state) {
+  if (state.closed) {
+    void beginCleanup(state);
+    return;
+  }
+  state.closed = true;
+  state.signal.removeEventListener("abort", state.onAbort);
+  if (!state.controller.signal.aborted) state.controller.abort();
+  void beginCleanup(state);
+}
+function createWatchIterator(providerKey, declaredWatch, receiver, lifetimeSignal, watchInput, declaredDomains) {
+  const controller = new AbortController();
+  const signal = AbortSignal.any([
+    lifetimeSignal,
+    watchInput.signal,
+    controller.signal
+  ]);
+  const state = {
+    providerKey,
+    controller,
+    signal,
+    onAbort: () => closeState(state),
+    declaredWatch,
+    receiver,
+    watchInput,
+    declaredDomains,
+    closed: false,
+    closedNormally: false,
+    pendingNext: false
+  };
+  if (signal.aborted) closeState(state);
+  else signal.addEventListener("abort", state.onAbort, { once: true });
+  const source = () => {
+    if (state.source !== void 0) return state.source;
+    throwIfAgentOperationAborted(signal);
+    const iterable = state.declaredWatch.call(state.receiver, {
+      ...state.watchInput,
+      signal
+    });
+    state.source = providerIterator(providerKey, iterable);
+    if (signal.aborted) closeState(state);
+    return state.source;
+  };
+  const next = async () => {
+    if (state.pendingNext) {
+      throw new TypeError("Concurrent environment watch next calls are not supported.");
+    }
+    if (state.closed) {
+      if (state.closedNormally || !signal.aborted) {
+        return { done: true, value: void 0 };
+      }
+      throwIfAgentOperationAborted(signal);
+    }
+    throwIfAgentOperationAborted(signal);
+    state.pendingNext = true;
+    try {
+      const iterator = source();
+      throwIfAgentOperationAborted(signal);
+      const result = await awaitCancellable(
+        iterator.next.call(iterator.iterator),
+        signal
+      );
+      throwIfAgentOperationAborted(signal);
+      if (!iteratorResult(result)) {
+        return environmentContractError(providerKey, "watch iterator result");
+      }
+      if (result.done === true) {
+        state.closedNormally = true;
+        closeState(state);
+        await beginCleanup(state);
+        return { done: true, value: void 0 };
+      }
+      return {
+        done: false,
+        value: validateInvalidation(
+          providerKey,
+          result.value,
+          state.watchInput.environmentId,
+          state.declaredDomains
+        )
+      };
+    } catch (error) {
+      closeState(state);
+      throw error;
+    } finally {
+      state.pendingNext = false;
+    }
+  };
+  const returnIterator = async (value) => {
+    state.closedNormally = true;
+    state.controller.abort();
+    closeState(state);
+    await beginCleanup(state);
+    return { done: true, value };
+  };
+  return { next, return: returnIterator };
+}
+function wrapRead(input) {
+  return async (rawInput) => {
+    const parsedInput = input.parseInput(rawInput);
+    const signal = AbortSignal.any([
+      input.lifetimeSignal,
+      parsedInput.signal
+    ]);
+    throwIfAgentOperationAborted(signal);
+    const {
+      onProviderExecutionStarted,
+      ...providerInput
+    } = parsedInput;
+    onProviderExecutionStarted?.();
+    const candidate = input.declaredRead.call(input.receiver, {
+      ...providerInput,
+      signal
+    });
+    const result = await awaitCancellable(candidate, signal);
+    throwIfAgentOperationAborted(signal);
+    return validateSnapshot(
+      input.providerKey,
+      result,
+      parsedInput.environmentId,
+      input.declaredDomains,
+      input.maximumExtent
+    );
+  };
+}
+function wrapWatch(input) {
+  return (rawInput) => {
+    const parsedInput = input.parseInput(rawInput);
+    return {
+      [Symbol.asyncIterator]() {
+        return createWatchIterator(
+          input.providerKey,
+          input.declaredWatch,
+          input.receiver,
+          input.lifetimeSignal,
+          parsedInput,
+          input.declaredDomains
+        );
+      }
+    };
+  };
+}
+function validateAgentEnvironmentDiscoveryPort(input) {
+  assertSignal(input.signal, "instance signal");
+  const kind = validateDeclaredPort(input.providerKey, input.capability, input.port);
+  if (kind === "unsupported") return Object.freeze({ kind: "unsupported" });
+  const declared = input.port;
+  const domains = Object.freeze([...declared.domains]);
+  const readEnvironment = wrapRead({
+    providerKey: input.providerKey,
+    declaredRead: declared.readEnvironment,
+    receiver: declared,
+    lifetimeSignal: input.signal,
+    parseInput: parseDiscoveryInput,
+    declaredDomains: domains,
+    maximumExtent: "workspace_discovery"
+  });
+  if (kind === "read") {
+    return Object.freeze({ kind: "read", domains, readEnvironment });
+  }
+  const watchEnvironment = wrapWatch({
+    providerKey: input.providerKey,
+    declaredWatch: declared.watchEnvironment,
+    receiver: declared,
+    lifetimeSignal: input.signal,
+    declaredDomains: domains,
+    parseInput: parseDiscoveryWatchInput
+  });
+  return Object.freeze({
+    kind: "read_and_watch",
+    domains,
+    readEnvironment,
+    watchEnvironment
+  });
+}
+function validateAgentEnvironmentObservationPort(input) {
+  assertSignal(input.signal, "session signal");
+  const kind = validateDeclaredPort(input.providerKey, input.capability, input.port);
+  if (kind === "unsupported") return Object.freeze({ kind: "unsupported" });
+  const declared = input.port;
+  const domains = Object.freeze([...declared.domains]);
+  const readEnvironment = wrapRead({
+    providerKey: input.providerKey,
+    declaredRead: declared.readEnvironment,
+    receiver: declared,
+    lifetimeSignal: input.signal,
+    parseInput: parseObservationInput,
+    declaredDomains: domains,
+    maximumExtent: "session"
+  });
+  if (kind === "read") {
+    return Object.freeze({ kind: "read", domains, readEnvironment });
+  }
+  const watchEnvironment = wrapWatch({
+    providerKey: input.providerKey,
+    declaredWatch: declared.watchEnvironment,
+    receiver: declared,
+    lifetimeSignal: input.signal,
+    declaredDomains: domains,
+    parseInput: parseObservationWatchInput
+  });
+  return Object.freeze({
+    kind: "read_and_watch",
+    domains,
+    readEnvironment,
+    watchEnvironment
+  });
+}
+export {
+  AGENT_ENVIRONMENT_ITERATOR_CLEANUP_TIMEOUT_MS,
+  validateAgentEnvironmentDiscoveryPort,
+  validateAgentEnvironmentObservationPort
+};

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./adapterValidation.js";
 export * from "./accountQuota/index.js";
+export * from "./environment/index.js";
 export * from "./artifacts.js";
 export * from "./contractErrors.js";
 export * from "./evidence.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from "./adapterValidation.js";
 export * from "./accountQuota/index.js";
+export * from "./environment/index.js";
 export * from "./artifacts.js";
 export * from "./contractErrors.js";
 export * from "./evidence.js";

package/dist/interactionValidation.js

@@ -77,9 +77,7 @@ function validateAgentIntegrationCatalogForCapabilities(capabilities, candidate)
   }
   const capability = capabilities.integrations;
   if (capability.kind !== "supported" || catalog.integrations.length > capability.maxIntegrations || catalog.integrations.some(
-    (integration) => !capability.integrationKinds.includes(integration.kind) || integration.servers.length > capability.maxServersPerIntegration || integration.servers.some(
-      (server) => server.tools.length > capability.maxToolsPerServer || server.resources.length > capability.maxResourcesPerServer
-    )
+    (integration) => !capability.integrationKinds.includes(integration.kind) || (integration.kind === "mcp" ? integration.servers.length > capability.maxServersPerIntegration || integration.servers.some((server) => server.tools.length > capability.maxToolsPerServer || server.resources.length > capability.maxResourcesPerServer) : (integration.tools?.length ?? 0) > capability.maxToolsPerServer)
   )) {
     return invalidInventory(
       capabilities.providerKey,

package/dist/providerDriver.d.ts

@@ -1,6 +1,7 @@
 import { type AgentCapabilities, type AgentInstanceId, type AgentProviderKey } from "@agen-ai/agent-protocol";
 import type { MaybePromise } from "./foundation.js";
 import type { AgentAccountQuotaPort } from "./accountQuota/types.js";
+import type { AgentEnvironmentDiscoveryPort } from "./environment/types.js";
 import type { AgentProviderReadiness } from "./readiness.js";
 import type { AgentProviderAdapter } from "./sessions.js";
 export interface AgentProviderInstanceDefinition {
@@ -16,6 +17,7 @@ export interface MaterializedAgentProviderInstance {
     readonly capabilities: AgentCapabilities;
     readonly adapter: AgentProviderAdapter;
     readonly accountQuota: AgentAccountQuotaPort;
+    readonly environment: AgentEnvironmentDiscoveryPort;
     readonly checkReadiness: (input?: AgentProviderReadinessCheckInput) => MaybePromise<AgentProviderReadiness>;
     readonly dispose: () => MaybePromise<void>;
 }

package/dist/providerInstanceRegistry.js

@@ -5,6 +5,7 @@ import {
 } from "@agen-ai/agent-protocol";
 import { validateAgentProviderAdapter } from "./adapterValidation.js";
 import { validateAgentAccountQuotaPort } from "./accountQuota/validation.js";
+import { validateAgentEnvironmentDiscoveryPort } from "./environment/validation.js";
 import {
   createAgentProviderCatalogEntries,
   createAgentProviderInstanceCatalogEntries
@@ -140,6 +141,7 @@ function managedInstance(rawInstance, providerKey) {
     disposePromise: null
   };
   const quotaLifetime = new AbortController();
+  const environmentLifetime = new AbortController();
   const instance = Object.freeze({
     instanceId: parseAgentInstanceId(rawInstance.instanceId),
     capabilities,
@@ -149,6 +151,12 @@ function managedInstance(rawInstance, providerKey) {
       port: rawInstance.accountQuota,
       signal: quotaLifetime.signal
     }),
+    environment: validateAgentEnvironmentDiscoveryPort({
+      providerKey,
+      capability: capabilities.environment.instance,
+      port: rawInstance.environment,
+      signal: environmentLifetime.signal
+    }),
     checkReadiness: async (input) => {
       const readiness = await checkReadiness(input);
       return validateAgentProviderReadiness(readiness);
@@ -158,6 +166,7 @@ function managedInstance(rawInstance, providerKey) {
       if (lifecycle.disposePromise) return lifecycle.disposePromise;
       lifecycle.status = "disposing";
       quotaLifetime.abort(new DOMException("The provider instance was disposed.", "AbortError"));
+      environmentLifetime.abort(new DOMException("The provider instance was disposed.", "AbortError"));
       lifecycle.disposePromise = Promise.resolve().then(() => dispose()).then(() => {
         lifecycle.status = "disposed";
       }).catch((error) => {