@agen-ai/agent-runtime 0.1.0

package/dist/evidence.d.ts

@@ -0,0 +1,50 @@
+import { type AgentJsonValue } from "@agen-ai/agent-protocol";
+export declare const AGENT_PROVIDER_EVIDENCE_BYTES_LIMIT = 24576;
+export declare const AGENT_PROVIDER_REQUEST_CONTEXT_BYTES_LIMIT = 16384;
+export declare const AGENT_PROVIDER_DATA_BYTES_LIMIT_MAX = 32768;
+export type AgentProviderDataTruncationReason = "byte_limit_exceeded" | "structural_limit_exceeded" | "byte_and_structural_limits_exceeded";
+interface BoundedAgentProviderDataBase {
+    readonly data: AgentJsonValue;
+    readonly dataBytes: number;
+    readonly redacted: true;
+}
+export type BoundedAgentProviderData = BoundedAgentProviderDataBase & Readonly<{
+    originalDataBytes: number;
+    truncated: false;
+    truncationReason: null;
+} | {
+    originalDataBytes: number;
+    truncated: true;
+    truncationReason: "byte_limit_exceeded";
+} | {
+    originalDataBytes: null;
+    truncated: true;
+    truncationReason: "structural_limit_exceeded" | "byte_and_structural_limits_exceeded";
+}>;
+export type AgentProviderEvidenceCategory = "provider_event" | "provider_request" | "diagnostic";
+export type AgentProviderEvidence = BoundedAgentProviderData & Readonly<{
+    readonly category: AgentProviderEvidenceCategory;
+    readonly source: string;
+}>;
+export type AgentProviderRequestContext = BoundedAgentProviderData & Readonly<{
+    readonly truncated: false;
+    readonly truncationReason: null;
+    readonly originalDataBytes: number;
+}>;
+export interface CreateAgentProviderEvidenceInput<Category extends AgentProviderEvidenceCategory = AgentProviderEvidenceCategory> {
+    readonly category: Category;
+    readonly source: string;
+    readonly data: unknown;
+    readonly bytesLimit?: number;
+}
+export declare function redactAgentProviderData(value: unknown): AgentJsonValue;
+export declare function createBoundedAgentProviderData(value: unknown, bytesLimit?: number): BoundedAgentProviderData;
+export declare function validateBoundedAgentProviderData(input: BoundedAgentProviderData): BoundedAgentProviderData;
+export declare function createAgentProviderRequestContext(value: unknown): AgentProviderRequestContext;
+export declare function validateAgentProviderRequestContext(input: AgentProviderRequestContext): AgentProviderRequestContext;
+export declare function createAgentProviderEvidence<Category extends AgentProviderEvidenceCategory>(input: CreateAgentProviderEvidenceInput<Category>): AgentProviderEvidence & Readonly<{
+    category: Category;
+}>;
+export declare function validateAgentProviderEvidence(input: AgentProviderEvidence): AgentProviderEvidence;
+export {};
+//# sourceMappingURL=evidence.d.ts.map

package/dist/evidence.js

@@ -0,0 +1,368 @@
+import { isDeepStrictEqual } from "node:util";
+import {
+  AGENT_PROTOCOL_JSON_BYTES_LIMIT,
+  AGENT_PROTOCOL_JSON_KEY_MAX_LENGTH,
+  agentProtocolSerializedJsonBytes,
+  parseAgentJsonValue
+} from "@agen-ai/agent-protocol";
+import { parseAgentBoundedText } from "./foundation.js";
+import { containsAgentControlCharacter } from "./internal/controlCharacters.js";
+import { serializedAgentJsonValueBytes } from "./internal/serializedJsonBytes.js";
+const AGENT_PROVIDER_EVIDENCE_BYTES_LIMIT = 24576;
+const AGENT_PROVIDER_REQUEST_CONTEXT_BYTES_LIMIT = 16384;
+const AGENT_PROVIDER_DATA_BYTES_LIMIT_MAX = AGENT_PROTOCOL_JSON_BYTES_LIMIT;
+const AGENT_PROVIDER_DATA_DEPTH_LIMIT = 8;
+const AGENT_PROVIDER_DATA_COLLECTION_LIMIT = 100;
+const AGENT_PROVIDER_DATA_REDACTION_REPLACEMENT = "[REDACTED]";
+const AGENT_PROVIDER_DATA_PROTOTYPE_KEYS = /* @__PURE__ */ new Set([
+  "__proto__",
+  "constructor",
+  "prototype"
+]);
+const SENSITIVE_KEY_PATTERN = /token|secret|password|private[_-]?key|credential|authorization|api[_-]?key/iu;
+function isPortableAgentProviderDataKey(key) {
+  return key.length > 0 && key.length <= AGENT_PROTOCOL_JSON_KEY_MAX_LENGTH && !AGENT_PROVIDER_DATA_PROTOTYPE_KEYS.has(key);
+}
+function normalizedObjectKey(key, index, preservedKeys, usedKeys) {
+  if (isPortableAgentProviderDataKey(key) && !usedKeys.has(key)) {
+    return { key, rewritten: false };
+  }
+  let collision = 0;
+  let candidate;
+  do {
+    candidate = `truncated_key_${index}${collision === 0 ? "" : `_${collision}`}`;
+    collision += 1;
+  } while (preservedKeys.has(candidate) || usedKeys.has(candidate));
+  return { key: candidate, rewritten: true };
+}
+function normalizedProviderValue(value, ancestors, depth, truncation) {
+  if (depth > AGENT_PROVIDER_DATA_DEPTH_LIMIT) {
+    truncation.structurallyTruncated = true;
+    return "[MaxDepth]";
+  }
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    if (Number.isFinite(value)) return value;
+    truncation.structurallyTruncated = true;
+    return "[NonFiniteNumber]";
+  }
+  if (typeof value !== "object") {
+    truncation.structurallyTruncated = true;
+    return `[Unsupported:${typeof value}]`;
+  }
+  if (ancestors.has(value)) {
+    truncation.structurallyTruncated = true;
+    return "[Circular]";
+  }
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      if (value.length > AGENT_PROVIDER_DATA_COLLECTION_LIMIT) {
+        truncation.structurallyTruncated = true;
+      }
+      for (const key of Reflect.ownKeys(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor?.enumerable !== true) continue;
+        const index = typeof key === "string" ? Number(key) : Number.NaN;
+        if (!Number.isInteger(index) || index < 0 || String(index) !== key || index >= value.length) {
+          truncation.structurallyTruncated = true;
+        }
+      }
+      const normalized2 = [];
+      const length = Math.min(
+        value.length,
+        AGENT_PROVIDER_DATA_COLLECTION_LIMIT
+      );
+      for (let index = 0; index < length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, index);
+        if (!descriptor) {
+          normalized2.push(null);
+        } else if (!("value" in descriptor)) {
+          truncation.structurallyTruncated = true;
+          normalized2.push("[Accessor]");
+        } else {
+          normalized2.push(
+            normalizedProviderValue(
+              descriptor.value,
+              ancestors,
+              depth + 1,
+              truncation
+            )
+          );
+        }
+      }
+      return normalized2;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      truncation.structurallyTruncated = true;
+      const constructorDescriptor = Object.getOwnPropertyDescriptor(
+        prototype,
+        "constructor"
+      );
+      const constructorName = constructorDescriptor && "value" in constructorDescriptor && typeof constructorDescriptor.value === "function" ? constructorDescriptor.value.name || "Object" : "Object";
+      return `[Unsupported:${constructorName}]`;
+    }
+    const normalized = /* @__PURE__ */ Object.create(null);
+    const keys = [];
+    let enumerablePropertyCount = 0;
+    for (const key of Reflect.ownKeys(value)) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (descriptor?.enumerable !== true) continue;
+      enumerablePropertyCount += 1;
+      if (typeof key === "string") {
+        keys.push(key);
+      } else {
+        truncation.structurallyTruncated = true;
+      }
+    }
+    if (enumerablePropertyCount > AGENT_PROVIDER_DATA_COLLECTION_LIMIT) {
+      truncation.structurallyTruncated = true;
+    }
+    const selectedKeys = keys.slice(0, AGENT_PROVIDER_DATA_COLLECTION_LIMIT);
+    const preservedKeys = new Set(
+      selectedKeys.filter(isPortableAgentProviderDataKey)
+    );
+    const usedKeys = /* @__PURE__ */ new Set();
+    selectedKeys.forEach((key, index) => {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor) return;
+      const normalizedKey = normalizedObjectKey(
+        key,
+        index,
+        preservedKeys,
+        usedKeys
+      );
+      usedKeys.add(normalizedKey.key);
+      if (normalizedKey.rewritten) truncation.structurallyTruncated = true;
+      if (!("value" in descriptor)) {
+        truncation.structurallyTruncated = true;
+        normalized[normalizedKey.key] = "[Accessor]";
+        return;
+      }
+      normalized[normalizedKey.key] = SENSITIVE_KEY_PATTERN.test(key) ? AGENT_PROVIDER_DATA_REDACTION_REPLACEMENT : normalizedProviderValue(
+        descriptor.value,
+        ancestors,
+        depth + 1,
+        truncation
+      );
+    });
+    return normalized;
+  } catch {
+    truncation.structurallyTruncated = true;
+    return "[Uninspectable]";
+  } finally {
+    ancestors.delete(value);
+  }
+}
+function normalizeAgentProviderData(value) {
+  const truncation = {
+    structurallyTruncated: false
+  };
+  return {
+    data: normalizedProviderValue(
+      value,
+      /* @__PURE__ */ new WeakSet(),
+      0,
+      truncation
+    ),
+    structurallyTruncated: truncation.structurallyTruncated
+  };
+}
+function validatedBytesLimit(limit) {
+  if (!Number.isSafeInteger(limit) || limit < 256 || limit > AGENT_PROVIDER_DATA_BYTES_LIMIT_MAX) {
+    throw new RangeError(
+      `Provider data byte limits must be an integer from 256 through ${AGENT_PROVIDER_DATA_BYTES_LIMIT_MAX}.`
+    );
+  }
+  return limit;
+}
+function redactAgentProviderData(value) {
+  return parseAgentJsonValue(normalizeAgentProviderData(value).data);
+}
+function createBoundedAgentProviderData(value, bytesLimit = AGENT_PROVIDER_EVIDENCE_BYTES_LIMIT) {
+  const validatedLimit = validatedBytesLimit(bytesLimit);
+  const normalized = normalizeAgentProviderData(value);
+  const normalizedDataBytes = serializedAgentJsonValueBytes(normalized.data);
+  if (normalizedDataBytes <= validatedLimit) {
+    const data = parseAgentJsonValue(normalized.data);
+    if (normalized.structurallyTruncated) {
+      return Object.freeze({
+        data,
+        dataBytes: normalizedDataBytes,
+        originalDataBytes: null,
+        truncated: true,
+        truncationReason: "structural_limit_exceeded",
+        redacted: true
+      });
+    }
+    return Object.freeze({
+      data,
+      dataBytes: normalizedDataBytes,
+      originalDataBytes: normalizedDataBytes,
+      truncated: false,
+      truncationReason: null,
+      redacted: true
+    });
+  }
+  if (normalized.structurallyTruncated) {
+    const truncatedData2 = parseAgentJsonValue({
+      truncated: true,
+      reason: "byte_and_structural_limits_exceeded",
+      originalDataBytes: null
+    });
+    return Object.freeze({
+      data: truncatedData2,
+      dataBytes: agentProtocolSerializedJsonBytes(truncatedData2),
+      originalDataBytes: null,
+      truncated: true,
+      truncationReason: "byte_and_structural_limits_exceeded",
+      redacted: true
+    });
+  }
+  const truncatedData = parseAgentJsonValue({
+    truncated: true,
+    reason: "byte_limit_exceeded",
+    originalDataBytes: normalizedDataBytes
+  });
+  return Object.freeze({
+    data: truncatedData,
+    dataBytes: agentProtocolSerializedJsonBytes(truncatedData),
+    originalDataBytes: normalizedDataBytes,
+    truncated: true,
+    truncationReason: "byte_limit_exceeded",
+    redacted: true
+  });
+}
+function validateBoundedAgentProviderData(input) {
+  if (input === null || typeof input !== "object" || typeof input.dataBytes !== "number" || typeof input.truncated !== "boolean" || input.redacted !== true) {
+    throw new TypeError("Bounded provider data is invalid.");
+  }
+  const data = parseAgentJsonValue(input.data);
+  if (!isDeepStrictEqual(data, redactAgentProviderData(data))) {
+    throw new TypeError(
+      "Bounded provider data must be canonically normalized and redacted."
+    );
+  }
+  const dataBytes = agentProtocolSerializedJsonBytes(data);
+  if (input.dataBytes !== dataBytes) {
+    throw new TypeError("Bounded provider data byte accounting is invalid.");
+  }
+  if (!input.truncated) {
+    if (input.truncationReason !== null || !Number.isSafeInteger(input.originalDataBytes) || input.originalDataBytes !== dataBytes) {
+      throw new TypeError("Bounded provider data byte accounting is invalid.");
+    }
+    return Object.freeze({
+      data,
+      dataBytes,
+      originalDataBytes: input.originalDataBytes,
+      truncated: false,
+      truncationReason: null,
+      redacted: true
+    });
+  }
+  switch (input.truncationReason) {
+    case "byte_limit_exceeded":
+      if (!Number.isSafeInteger(input.originalDataBytes) || input.originalDataBytes <= dataBytes) {
+        throw new TypeError("Bounded provider data byte accounting is invalid.");
+      }
+      return Object.freeze({
+        data,
+        dataBytes,
+        originalDataBytes: input.originalDataBytes,
+        truncated: true,
+        truncationReason: input.truncationReason,
+        redacted: true
+      });
+    case "structural_limit_exceeded":
+    case "byte_and_structural_limits_exceeded":
+      if (input.originalDataBytes !== null) {
+        throw new TypeError(
+          "Bounded provider data truncation metadata is invalid."
+        );
+      }
+      return Object.freeze({
+        data,
+        dataBytes,
+        originalDataBytes: null,
+        truncated: true,
+        truncationReason: input.truncationReason,
+        redacted: true
+      });
+    default:
+      throw new TypeError(
+        "Bounded provider data truncation metadata is invalid."
+      );
+  }
+}
+function createAgentProviderRequestContext(value) {
+  const canonical = parseAgentJsonValue(value);
+  const bounded = createBoundedAgentProviderData(
+    canonical,
+    AGENT_PROVIDER_REQUEST_CONTEXT_BYTES_LIMIT
+  );
+  if (bounded.truncated) {
+    throw new RangeError(
+      "Provider request context exceeds its transport byte limit."
+    );
+  }
+  if (!isDeepStrictEqual(bounded.data, canonical)) {
+    throw new TypeError(
+      "Provider request context must be JSON-safe and require no redaction or structural truncation."
+    );
+  }
+  return bounded;
+}
+function validateAgentProviderRequestContext(input) {
+  const bounded = validateBoundedAgentProviderData(input);
+  if (bounded.truncated) {
+    throw new TypeError("Provider request context cannot be truncated.");
+  }
+  return createAgentProviderRequestContext(bounded.data);
+}
+function parseEvidenceSource(value) {
+  const source = parseAgentBoundedText(value, "Provider evidence source", 160);
+  if (source !== source.trim() || containsAgentControlCharacter(source)) {
+    throw new TypeError(
+      "Provider evidence source must be a canonical bounded string."
+    );
+  }
+  return source;
+}
+function createAgentProviderEvidence(input) {
+  const bounded = createBoundedAgentProviderData(
+    input.data,
+    input.bytesLimit
+  );
+  return Object.freeze({
+    category: input.category,
+    source: parseEvidenceSource(input.source),
+    ...bounded
+  });
+}
+function validateAgentProviderEvidence(input) {
+  if (input === null || typeof input !== "object" || !["provider_event", "provider_request", "diagnostic"].includes(
+    input.category
+  )) {
+    throw new TypeError("Provider evidence is invalid.");
+  }
+  return Object.freeze({
+    category: input.category,
+    source: parseEvidenceSource(input.source),
+    ...validateBoundedAgentProviderData(input)
+  });
+}
+export {
+  AGENT_PROVIDER_DATA_BYTES_LIMIT_MAX,
+  AGENT_PROVIDER_EVIDENCE_BYTES_LIMIT,
+  AGENT_PROVIDER_REQUEST_CONTEXT_BYTES_LIMIT,
+  createAgentProviderEvidence,
+  createAgentProviderRequestContext,
+  createBoundedAgentProviderData,
+  redactAgentProviderData,
+  validateAgentProviderEvidence,
+  validateAgentProviderRequestContext,
+  validateBoundedAgentProviderData
+};

package/dist/foundation.d.ts

@@ -0,0 +1,8 @@
+export declare const AGENT_RUNTIME_PACKAGE_NAME: "@agen-ai/agent-runtime";
+export type MaybePromise<Value> = Value | Promise<Value>;
+export declare function parseAgentBoundedText(value: unknown, field: string, maxLength: number): string;
+export declare function parseAgentCanonicalText(value: unknown, field: string, maxLength: number): string;
+export declare function parseAgentProviderTechnicalId(value: unknown, field?: string): string;
+export declare function throwIfAgentOperationAborted(signal?: AbortSignal): void;
+export declare function isAgentOperationAbortError(error: unknown): boolean;
+//# sourceMappingURL=foundation.d.ts.map

package/dist/foundation.js

@@ -0,0 +1,37 @@
+import { AGENT_PROTOCOL_ID_MAX_LENGTH } from "@agen-ai/agent-protocol";
+import { containsAgentControlCharacter } from "./internal/controlCharacters.js";
+const AGENT_RUNTIME_PACKAGE_NAME = "@agen-ai/agent-runtime";
+function parseAgentBoundedText(value, field, maxLength) {
+  if (!Number.isSafeInteger(maxLength) || maxLength < 1) {
+    throw new RangeError("Agent text maxLength must be a positive integer.");
+  }
+  if (typeof value !== "string" || value.length < 1 || value.length > maxLength) {
+    throw new TypeError(`${field} must be a bounded non-empty string.`);
+  }
+  return value;
+}
+function parseAgentCanonicalText(value, field, maxLength) {
+  const text = parseAgentBoundedText(value, field, maxLength);
+  if (text !== text.trim() || containsAgentControlCharacter(text)) {
+    throw new TypeError(`${field} must be canonical text.`);
+  }
+  return text;
+}
+function parseAgentProviderTechnicalId(value, field = "provider technical identifier") {
+  return parseAgentCanonicalText(value, field, AGENT_PROTOCOL_ID_MAX_LENGTH);
+}
+function throwIfAgentOperationAborted(signal) {
+  if (!signal?.aborted) return;
+  throw signal.reason instanceof Error ? signal.reason : new DOMException("The agent operation was aborted.", "AbortError");
+}
+function isAgentOperationAbortError(error) {
+  return error instanceof Error && error.name === "AbortError";
+}
+export {
+  AGENT_RUNTIME_PACKAGE_NAME,
+  isAgentOperationAbortError,
+  parseAgentBoundedText,
+  parseAgentCanonicalText,
+  parseAgentProviderTechnicalId,
+  throwIfAgentOperationAborted
+};

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./adapterValidation.js";
+export * from "./artifacts.js";
+export * from "./contractErrors.js";
+export * from "./evidence.js";
+export * from "./foundation.js";
+export * from "./outputs.js";
+export * from "./providerCatalog.js";
+export * from "./providerDriver.js";
+export * from "./providerInstanceRegistry.js";
+export * from "./readiness.js";
+export * from "./sessions.js";
+export * from "./text.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,12 @@
+export * from "./adapterValidation.js";
+export * from "./artifacts.js";
+export * from "./contractErrors.js";
+export * from "./evidence.js";
+export * from "./foundation.js";
+export * from "./outputs.js";
+export * from "./providerCatalog.js";
+export * from "./providerDriver.js";
+export * from "./providerInstanceRegistry.js";
+export * from "./readiness.js";
+export * from "./sessions.js";
+export * from "./text.js";

package/dist/internal/controlCharacters.d.ts

@@ -0,0 +1,2 @@
+export declare function containsAgentControlCharacter(value: string): boolean;
+//# sourceMappingURL=controlCharacters.d.ts.map

package/dist/internal/controlCharacters.js

@@ -0,0 +1,7 @@
+const AGENT_CONTROL_CHARACTER_PATTERN = /[\u0000-\u001F\u007F-\u009F]/u;
+function containsAgentControlCharacter(value) {
+  return AGENT_CONTROL_CHARACTER_PATTERN.test(value);
+}
+export {
+  containsAgentControlCharacter
+};

package/dist/internal/serializedJsonBytes.d.ts

@@ -0,0 +1,3 @@
+import type { AgentJsonValue } from "@agen-ai/agent-protocol";
+export declare function serializedAgentJsonValueBytes(value: AgentJsonValue): number;
+//# sourceMappingURL=serializedJsonBytes.d.ts.map

package/dist/internal/serializedJsonBytes.js

@@ -0,0 +1,57 @@
+function serializedJsonStringBytes(value) {
+  let bytes = 2;
+  for (let index = 0; index < value.length; index += 1) {
+    const codeUnit = value.charCodeAt(index);
+    if (codeUnit === 34 || codeUnit === 92) {
+      bytes += 2;
+      continue;
+    }
+    if (codeUnit === 8 || codeUnit === 9 || codeUnit === 10 || codeUnit === 12 || codeUnit === 13) {
+      bytes += 2;
+      continue;
+    }
+    if (codeUnit < 32) {
+      bytes += 6;
+      continue;
+    }
+    if (codeUnit < 128) {
+      bytes += 1;
+      continue;
+    }
+    if (codeUnit < 2048) {
+      bytes += 2;
+      continue;
+    }
+    if (codeUnit >= 55296 && codeUnit <= 56319) {
+      const nextCodeUnit = value.charCodeAt(index + 1);
+      if (nextCodeUnit >= 56320 && nextCodeUnit <= 57343) {
+        bytes += 4;
+        index += 1;
+      } else {
+        bytes += 6;
+      }
+      continue;
+    }
+    bytes += codeUnit >= 56320 && codeUnit <= 57343 ? 6 : 3;
+  }
+  return bytes;
+}
+function serializedAgentJsonValueBytes(value) {
+  if (value === null) return 4;
+  if (typeof value === "string") return serializedJsonStringBytes(value);
+  if (typeof value === "number") return String(value).length;
+  if (typeof value === "boolean") return value ? 4 : 5;
+  if (Array.isArray(value)) {
+    return value.reduce(
+      (bytes, item, index) => bytes + serializedAgentJsonValueBytes(item) + (index === 0 ? 0 : 1),
+      2
+    );
+  }
+  return Object.entries(value).reduce(
+    (bytes, [key, item], index) => bytes + serializedJsonStringBytes(key) + 1 + serializedAgentJsonValueBytes(item) + (index === 0 ? 0 : 1),
+    2
+  );
+}
+export {
+  serializedAgentJsonValueBytes
+};

package/dist/outputValidation.d.ts

@@ -0,0 +1,13 @@
+import { type AgentCapabilities, type AgentProviderKey, type AgentSessionId, type AgentTurnId } from "@agen-ai/agent-protocol";
+import { type AgentProviderOutput } from "./outputs.js";
+import type { AgentProviderOperationResult } from "./sessions.js";
+export interface AgentProviderOutputValidationContext {
+    readonly capabilities: AgentCapabilities;
+    readonly providerKey: AgentProviderKey;
+    readonly sessionId?: AgentSessionId;
+    readonly turnId?: AgentTurnId;
+    readonly authenticationAttemptId?: string;
+}
+export declare function validateAgentProviderOutputForContext(candidate: AgentProviderOutput, context: AgentProviderOutputValidationContext): AgentProviderOutput;
+export declare function validateAgentProviderOperationResult(candidate: AgentProviderOperationResult, context: AgentProviderOutputValidationContext): AgentProviderOperationResult;
+//# sourceMappingURL=outputValidation.d.ts.map