@agen-ai/agent-orchestration 0.0.0-stage → 0.4.0

package/dist/policy/schemas.js

@@ -0,0 +1,59 @@
+import { AgentProviderKeySchema } from "@agen-ai/agent-protocol/zod";
+import { z } from "zod/v4";
+import { TargetOptionSchema } from "../catalog/schemas.js";
+import { DELEGATION_ENTRIES } from "../shared/bounds.js";
+import { CanonicalIdSchema, ExecutionModeSchema, ReasoningSchema, RevisionSchema, requireUniqueValues } from "../shared/schemas.js";
+function targetIdentityKey(identity2) {
+  return JSON.stringify([identity2.catalogId, identity2.targetId]);
+}
+const exclusion = z.strictObject({
+  exclusionId: CanonicalIdSchema,
+  providerKey: AgentProviderKeySchema.optional(),
+  modelId: CanonicalIdSchema.optional(),
+  targetId: CanonicalIdSchema.optional(),
+  catalogId: CanonicalIdSchema.optional(),
+  reasoning: ReasoningSchema.optional(),
+  executionMode: ExecutionModeSchema.optional(),
+  options: z.array(TargetOptionSchema).min(1).max(100).optional()
+}).superRefine((value, context) => {
+  if ([value.providerKey, value.modelId, value.targetId, value.catalogId, value.reasoning, value.executionMode, value.options].every((criterion) => criterion === void 0)) {
+    context.addIssue({ code: "custom", path: [], message: "A developer exclusion requires at least one criterion." });
+  }
+  if ((value.modelId !== void 0 || value.options !== void 0) && value.providerKey === void 0) {
+    context.addIssue({ code: "custom", path: ["providerKey"], message: "Model and native option exclusions require a provider identity." });
+  }
+  if (value.targetId === void 0 !== (value.catalogId === void 0)) {
+    context.addIssue({ code: "custom", path: ["targetId"], message: "Exact target exclusions require both catalog and target identities." });
+  }
+  if (value.options) requireUniqueValues(value.options.map((option) => option.key), context, ["options"]);
+});
+const developer = z.strictObject({
+  enabled: z.boolean().default(true),
+  exclusions: z.array(exclusion).max(DELEGATION_ENTRIES).default([])
+}).superRefine((value, context) => {
+  requireUniqueValues(value.exclusions.map((entry) => entry.exclusionId), context, ["exclusions"]);
+});
+const identity = z.strictObject({ catalogId: CanonicalIdSchema, targetId: CanonicalIdSchema });
+const identities = z.array(identity).max(DELEGATION_ENTRIES).superRefine((value, context) => {
+  requireUniqueValues(value.map(targetIdentityKey), context, []);
+});
+const selection = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("all_available"), includeFast: z.boolean(), unknownModeTargets: identities }),
+  z.strictObject({ kind: z.literal("explicit"), targets: identities })
+]);
+const user = z.discriminatedUnion("enabled", [
+  z.strictObject({ enabled: z.literal(false) }),
+  z.strictObject({
+    enabled: z.literal(true),
+    selection: selection.default({ kind: "all_available", includeFast: false, unknownModeTargets: [] })
+  })
+]);
+const PolicySnapshotSchema = z.strictObject({
+  revision: RevisionSchema,
+  developer: developer.default({ enabled: true, exclusions: [] }),
+  user: user.default({ enabled: false })
+});
+export {
+  PolicySnapshotSchema,
+  targetIdentityKey
+};

package/dist/policy/types.d.ts

@@ -0,0 +1,60 @@
+import type { AgentProviderKey } from "@agen-ai/agent-protocol";
+import type { DelegationExecutionMode, DelegationReasoning, DelegationTarget, DelegationTargetOption, DelegationTargetReference } from "../catalog/types.js";
+export interface DelegationExclusion {
+    readonly exclusionId: string;
+    readonly providerKey?: AgentProviderKey;
+    readonly modelId?: string;
+    readonly targetId?: string;
+    readonly catalogId?: string;
+    readonly reasoning?: DelegationReasoning;
+    readonly executionMode?: DelegationExecutionMode;
+    readonly options?: readonly DelegationTargetOption[];
+}
+export interface DelegationDeveloperPolicy {
+    readonly enabled: boolean;
+    readonly exclusions: readonly DelegationExclusion[];
+}
+export type DelegationTargetIdentity = Readonly<{
+    catalogId: string;
+    targetId: string;
+}>;
+export type DelegationUserSelection = Readonly<{
+    kind: "all_available";
+    includeFast: boolean;
+    unknownModeTargets: readonly DelegationTargetIdentity[];
+}> | Readonly<{
+    kind: "explicit";
+    targets: readonly DelegationTargetIdentity[];
+}>;
+export type DelegationUserPolicy = Readonly<{
+    enabled: false;
+}> | Readonly<{
+    enabled: true;
+    selection?: DelegationUserSelection;
+}>;
+export interface DelegationPolicySnapshot {
+    readonly revision: number;
+    readonly developer: DelegationDeveloperPolicy;
+    readonly user: DelegationUserPolicy;
+}
+export type DelegationPolicyOutcome = "allowed" | "denied" | "unverifiable";
+export interface DelegationTargetDecision {
+    readonly reference: DelegationTargetReference;
+    readonly selected: boolean;
+    readonly outcome: DelegationPolicyOutcome;
+    readonly reasons: readonly Readonly<{
+        code: string;
+        exclusionId?: string;
+        message: string;
+    }>[];
+}
+export interface ResolvedDelegationPolicy {
+    readonly enabled: boolean;
+    readonly policyRevision: number;
+    readonly catalogId: string;
+    readonly catalogRevision: number;
+    readonly decisions: readonly DelegationTargetDecision[];
+    readonly allowedTargets: readonly DelegationTarget[];
+    readonly missingSelections: readonly DelegationTargetIdentity[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/bounds.d.ts

@@ -0,0 +1,6 @@
+export declare const DELEGATION_DOCUMENT_BYTES = 1048576;
+export declare const DELEGATION_TARGET_BYTES = 32768;
+export declare const DELEGATION_ENTRIES = 1000;
+export declare function captureDelegationRecord(input: unknown, path?: readonly (string | number)[]): Record<string, unknown>;
+export declare function copyBoundedDelegationData(input: unknown): unknown;
+//# sourceMappingURL=bounds.d.ts.map

package/dist/shared/bounds.js

@@ -0,0 +1,88 @@
+import { invalidDelegationData } from "./errors.js";
+const DELEGATION_DOCUMENT_BYTES = 1048576;
+const DELEGATION_TARGET_BYTES = 32768;
+const DELEGATION_ENTRIES = 1e3;
+function captureDelegationRecord(input, path = []) {
+  if (input === null || typeof input !== "object" || Array.isArray(input) || ![Object.prototype, null].includes(Object.getPrototypeOf(input))) {
+    return invalidDelegationData("invalid_data", path, "Delegation objects must be plain data records.");
+  }
+  const result = {};
+  const keys = Reflect.ownKeys(input);
+  if (keys.length > DELEGATION_ENTRIES) invalidDelegationData("entry_limit", path, "Delegation object has too many properties.");
+  for (const key of keys) {
+    if (typeof key !== "string" || ["__proto__", "constructor", "prototype"].includes(key)) {
+      invalidDelegationData("invalid_data", path, "Delegation property names must be safe strings.");
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+    if (!descriptor?.enumerable || !Object.hasOwn(descriptor, "value")) {
+      invalidDelegationData("invalid_data", [...path, key], "Delegation properties must be enumerable data properties.");
+    }
+    result[key] = descriptor.value;
+  }
+  return result;
+}
+function copyBoundedDelegationData(input) {
+  const ancestors = /* @__PURE__ */ new Set();
+  const encoder = new TextEncoder();
+  let bytes = 0;
+  const reserve = (count, path) => {
+    bytes += count;
+    if (bytes > DELEGATION_DOCUMENT_BYTES) invalidDelegationData("byte_limit", path, "Delegation data exceeds 1 MiB of serialized JSON.");
+  };
+  const visit = (value, path, depth) => {
+    if (depth > 16) invalidDelegationData("depth_limit", path, "Delegation data exceeds its nesting limit.");
+    if (typeof value === "string") {
+      if (value.length > DELEGATION_DOCUMENT_BYTES) invalidDelegationData("byte_limit", path, "Delegation string exceeds its byte limit.");
+      reserve(encoder.encode(JSON.stringify(value)).byteLength, path);
+      return value;
+    }
+    if (value === null || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) {
+      reserve(JSON.stringify(value).length, path);
+      return value;
+    }
+    if (typeof value !== "object") invalidDelegationData("invalid_data", path, "Delegation data must contain only finite JSON values.");
+    if (ancestors.has(value)) invalidDelegationData("invalid_data", path, "Delegation data cannot contain cycles.");
+    ancestors.add(value);
+    let result;
+    if (Array.isArray(value)) {
+      const keys = Reflect.ownKeys(value);
+      const length = Object.getOwnPropertyDescriptor(value, "length")?.value;
+      if (Object.getPrototypeOf(value) !== Array.prototype || length > DELEGATION_ENTRIES || keys.length !== length + 1) {
+        invalidDelegationData("invalid_data", path, "Delegation arrays must be dense, bounded and free of extra properties.");
+      }
+      const entries = new Array(length);
+      reserve(2 + Math.max(0, length - 1), path);
+      for (const key of keys) {
+        if (key === "length") continue;
+        if (typeof key !== "string" || !/^(?:0|[1-9][0-9]*)$/u.test(key) || Number(key) >= length) {
+          invalidDelegationData("invalid_data", path, "Delegation arrays cannot carry extra properties.");
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor?.enumerable || !Object.hasOwn(descriptor, "value")) {
+          invalidDelegationData("invalid_data", [...path, Number(key)], "Delegation array entries must be data properties.");
+        }
+        entries[Number(key)] = visit(descriptor.value, [...path, Number(key)], depth + 1);
+      }
+      result = entries;
+    } else {
+      const record = captureDelegationRecord(value, path);
+      const entries = Object.entries(record);
+      reserve(2 + Math.max(0, entries.length - 1), path);
+      for (const [key, child] of entries) {
+        reserve(encoder.encode(JSON.stringify(key)).byteLength + 1, path);
+        record[key] = visit(child, [...path, key], depth + 1);
+      }
+      result = record;
+    }
+    ancestors.delete(value);
+    return result;
+  };
+  return visit(input, [], 0);
+}
+export {
+  DELEGATION_DOCUMENT_BYTES,
+  DELEGATION_ENTRIES,
+  DELEGATION_TARGET_BYTES,
+  captureDelegationRecord,
+  copyBoundedDelegationData
+};

package/dist/shared/errors.d.ts

@@ -0,0 +1,9 @@
+import { type ValidationErrorInput, type ValidationIssue } from "@agen-ai/validation";
+export type DelegationValidationIssue = ValidationIssue;
+export declare class DelegationValidationError extends Error {
+    readonly issues: readonly DelegationValidationIssue[];
+    constructor(issues: readonly DelegationValidationIssue[]);
+}
+export declare function invalidDelegationData(code: string, path: readonly (string | number)[], message: string): never;
+export declare function delegationSchemaError(error: ValidationErrorInput, input: unknown): never;
+//# sourceMappingURL=errors.d.ts.map

package/dist/shared/errors.js

@@ -0,0 +1,27 @@
+import {
+  normalizeValidationError
+} from "@agen-ai/validation";
+import { freezeDelegationData } from "./immutable.js";
+class DelegationValidationError extends Error {
+  issues;
+  constructor(issues) {
+    super("Delegation data is invalid.");
+    this.name = "DelegationValidationError";
+    this.issues = freezeDelegationData(issues.slice(0, 100).map((issue) => ({
+      code: issue.code,
+      path: [...issue.path],
+      message: issue.message
+    })));
+  }
+}
+function invalidDelegationData(code, path, message) {
+  throw new DelegationValidationError([{ code, path, message }]);
+}
+function delegationSchemaError(error, input) {
+  throw new DelegationValidationError(normalizeValidationError(error, input));
+}
+export {
+  DelegationValidationError,
+  delegationSchemaError,
+  invalidDelegationData
+};

package/dist/shared/identity.d.ts

@@ -0,0 +1,6 @@
+export declare function delegationCanonicalJson(input: unknown): string;
+export declare function delegationDataBytes(input: unknown): number;
+export declare function delegationInputDigest(input: unknown): string;
+export declare function createDelegationId(): string;
+export declare function delegationSubordinateId(runId: string, kind: string): string;
+//# sourceMappingURL=identity.d.ts.map

package/dist/shared/identity.js

@@ -0,0 +1,32 @@
+import { createHash, randomUUID } from "node:crypto";
+import { copyBoundedDelegationData } from "./bounds.js";
+function delegationCanonicalJson(input) {
+  const canonicalize = (value) => {
+    if (Array.isArray(value)) return value.map(canonicalize);
+    if (value !== null && typeof value === "object") {
+      return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([key, child]) => [key, canonicalize(child)]));
+    }
+    return value;
+  };
+  return JSON.stringify(canonicalize(copyBoundedDelegationData(input)));
+}
+function delegationDataBytes(input) {
+  return new TextEncoder().encode(delegationCanonicalJson(input)).byteLength;
+}
+function delegationInputDigest(input) {
+  return createHash("sha256").update(delegationCanonicalJson(input)).digest("hex");
+}
+function createDelegationId() {
+  return randomUUID();
+}
+function delegationSubordinateId(runId, kind) {
+  const hex = delegationInputDigest({ runId, kind });
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+export {
+  createDelegationId,
+  delegationCanonicalJson,
+  delegationDataBytes,
+  delegationInputDigest,
+  delegationSubordinateId
+};

package/dist/shared/immutable.d.ts

@@ -0,0 +1,2 @@
+export declare function freezeDelegationData<Value>(value: Value): Value;
+//# sourceMappingURL=immutable.d.ts.map

package/dist/shared/immutable.js

@@ -0,0 +1,10 @@
+function freezeDelegationData(value) {
+  if (value !== null && typeof value === "object") {
+    for (const child of Object.values(value)) freezeDelegationData(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+export {
+  freezeDelegationData
+};

package/dist/shared/limits.d.ts

@@ -0,0 +1,32 @@
+export declare const DELEGATION_FINAL_RESERVATION_BYTES = 32768;
+export declare const DELEGATION_FAILURE_BYTES = 2048;
+export declare const DELEGATION_CRITICAL_SLOT_BYTES = 2048;
+export declare const DELEGATION_CRITICAL_SLOTS = 4;
+export declare const DELEGATION_RUN_RESERVATION_BYTES = 40960;
+export interface DelegationLimits {
+    readonly maxActiveRuns: number;
+    readonly maxQueuedRuns: number;
+    readonly maxDepth: number;
+    readonly maxTasks: number;
+    readonly maxRuns: number;
+    readonly maxRunsPerTask: number;
+    readonly maxInputBytes: number;
+    readonly maxInputTextCharacters: number;
+    readonly maxRetainedInputBytes: number;
+    readonly maxObservationBytes: number;
+    readonly maxRunObservationBytes: number;
+    readonly maxRunObservations: number;
+    readonly maxRetainedObservationBytes: number;
+    readonly maxOrdinaryOperationsPerRun: number;
+    readonly maxOrdinaryOperations: number;
+    readonly runTimeoutMs: number;
+    readonly queuedStartTimeoutMs: number;
+    readonly maxWaitMs: number;
+    readonly controlTimeoutMs: number;
+    readonly notificationTtlMs: number;
+    readonly maxPageRecords: number;
+    readonly maxPageBytes: number;
+}
+export declare const DEFAULT_DELEGATION_LIMITS: DelegationLimits;
+export declare function parseDelegationLimits(input?: unknown): DelegationLimits;
+//# sourceMappingURL=limits.d.ts.map

package/dist/shared/limits.js

@@ -0,0 +1,69 @@
+import { z } from "zod/v4";
+import { copyBoundedDelegationData } from "./bounds.js";
+import { delegationSchemaError } from "./errors.js";
+import { freezeDelegationData } from "./immutable.js";
+const DELEGATION_FINAL_RESERVATION_BYTES = 32768;
+const DELEGATION_FAILURE_BYTES = 2048;
+const DELEGATION_CRITICAL_SLOT_BYTES = 2048;
+const DELEGATION_CRITICAL_SLOTS = 4;
+const DELEGATION_RUN_RESERVATION_BYTES = 40960;
+const DEFAULT_DELEGATION_LIMITS = Object.freeze({
+  maxActiveRuns: 4,
+  maxQueuedRuns: 32,
+  maxDepth: 2,
+  maxTasks: 256,
+  maxRuns: 1024,
+  maxRunsPerTask: 8,
+  maxInputBytes: 24576,
+  maxInputTextCharacters: 16e3,
+  maxRetainedInputBytes: 16777216,
+  maxObservationBytes: 8192,
+  maxRunObservationBytes: 1048576,
+  maxRunObservations: 2048,
+  maxRetainedObservationBytes: 33554432,
+  maxOrdinaryOperationsPerRun: 32,
+  maxOrdinaryOperations: 8192,
+  runTimeoutMs: 18e5,
+  queuedStartTimeoutMs: 3e5,
+  maxWaitMs: 3e4,
+  controlTimeoutMs: 1e4,
+  notificationTtlMs: 864e5,
+  maxPageRecords: 100,
+  maxPageBytes: 65536
+});
+const finite = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+const schema = z.strictObject(Object.fromEntries(Object.entries(DEFAULT_DELEGATION_LIMITS).map(([key, value]) => [key, finite.default(value)]))).superRefine((value, context) => {
+  for (const [smaller, larger] of [
+    ["maxActiveRuns", "maxRuns"],
+    ["maxQueuedRuns", "maxRuns"],
+    ["maxTasks", "maxRuns"],
+    ["maxRunsPerTask", "maxRuns"],
+    ["maxInputBytes", "maxRetainedInputBytes"]
+  ]) {
+    if (value[smaller] > value[larger]) context.addIssue({ code: "custom", path: [smaller], message: `${smaller} exceeds ${larger}.` });
+  }
+  if (value.maxPageRecords > 100 || value.maxPageBytes > 65536 || value.maxInputBytes > 24576 || value.maxInputTextCharacters > 16e3 || value.maxObservationBytes > 8192) {
+    context.addIssue({ code: "custom", path: [], message: "Limits exceed the initial bounded record and page format." });
+  }
+  if (value.maxRuns > Math.floor(Number.MAX_SAFE_INTEGER / DELEGATION_RUN_RESERVATION_BYTES) || value.maxOrdinaryOperations > Math.floor(Number.MAX_SAFE_INTEGER / DELEGATION_CRITICAL_SLOT_BYTES) || value.maxRunObservations > Math.floor(Number.MAX_SAFE_INTEGER / value.maxObservationBytes)) {
+    context.addIssue({ code: "custom", path: [], message: "Derived store reservations must remain safe integers." });
+  }
+  for (const key of ["runTimeoutMs", "queuedStartTimeoutMs", "maxWaitMs", "controlTimeoutMs", "notificationTtlMs"]) {
+    if (value[key] > 2147483647) context.addIssue({ code: "custom", path: [key], message: "Durations must fit a referenced Node timer." });
+  }
+});
+function parseDelegationLimits(input = {}) {
+  const captured = copyBoundedDelegationData(input);
+  const parsed = schema.safeParse(captured);
+  if (!parsed.success) return delegationSchemaError(parsed.error, captured);
+  return freezeDelegationData(parsed.data);
+}
+export {
+  DEFAULT_DELEGATION_LIMITS,
+  DELEGATION_CRITICAL_SLOTS,
+  DELEGATION_CRITICAL_SLOT_BYTES,
+  DELEGATION_FAILURE_BYTES,
+  DELEGATION_FINAL_RESERVATION_BYTES,
+  DELEGATION_RUN_RESERVATION_BYTES,
+  parseDelegationLimits
+};

package/dist/shared/operational-errors.d.ts

@@ -0,0 +1,7 @@
+export type DelegationErrorCode = "delegation_disabled" | "policy_denied" | "target_unavailable" | "stale_target" | "unsupported_operation" | "capacity_exceeded" | "operation_conflict" | "stale_revision" | "owner_lost" | "request_unavailable" | "delivery_uncertain" | "recovery_required" | "store_failed";
+export declare class DelegationOperationError extends Error {
+    readonly code: DelegationErrorCode;
+    constructor(code: DelegationErrorCode, message: string);
+}
+export declare function failDelegation(code: DelegationErrorCode, message: string): never;
+//# sourceMappingURL=operational-errors.d.ts.map

package/dist/shared/operational-errors.js

@@ -0,0 +1,15 @@
+class DelegationOperationError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "DelegationOperationError";
+  }
+  code;
+}
+function failDelegation(code, message) {
+  throw new DelegationOperationError(code, message);
+}
+export {
+  DelegationOperationError,
+  failDelegation
+};

package/dist/shared/schemas.d.ts

@@ -0,0 +1,11 @@
+import { z } from "zod/v4";
+export declare const CanonicalIdSchema: z.ZodString;
+export declare const ReasoningSchema: z.ZodString;
+export declare const RevisionSchema: z.ZodNumber;
+export declare const ExecutionModeSchema: z.ZodEnum<{
+    standard: "standard";
+    fast: "fast";
+}>;
+export declare const ReasonTextSchema: z.ZodString;
+export declare function requireUniqueValues(values: readonly string[], context: z.RefinementCtx, path: readonly (string | number)[]): void;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/shared/schemas.js

@@ -0,0 +1,23 @@
+import { z } from "zod/v4";
+const canonicalPattern = /^(?![\s\S]*[\u0000-\u001F\u007F-\u009F])\S(?:[\s\S]*\S)?$/u;
+const canonicalMessage = "Delegation text must be canonical and contain no control or surrounding whitespace.";
+const CanonicalIdSchema = z.string().min(1).max(256).regex(canonicalPattern, canonicalMessage);
+const ReasoningSchema = z.string().min(1).max(128).regex(canonicalPattern, canonicalMessage);
+const RevisionSchema = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+const ExecutionModeSchema = z.enum(["standard", "fast"]);
+const ReasonTextSchema = z.string().min(1).max(2e3).regex(canonicalPattern, canonicalMessage);
+function requireUniqueValues(values, context, path) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, value] of values.entries()) {
+    if (seen.has(value)) context.addIssue({ code: "custom", path: [...path, index], message: "Delegation identities must be unique." });
+    seen.add(value);
+  }
+}
+export {
+  CanonicalIdSchema,
+  ExecutionModeSchema,
+  ReasonTextSchema,
+  ReasoningSchema,
+  RevisionSchema,
+  requireUniqueValues
+};

package/dist/shared/text.d.ts

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

package/dist/shared/text.js

@@ -0,0 +1,15 @@
+function fitDelegationText(text, fits) {
+  if (fits(text)) return text;
+  const characters = Array.from(text);
+  let low = 0;
+  let high = characters.length;
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2);
+    if (fits(characters.slice(0, middle).join(""))) low = middle;
+    else high = middle - 1;
+  }
+  return characters.slice(0, low).join("");
+}
+export {
+  fitDelegationText
+};

package/dist/store/memory.d.ts

@@ -0,0 +1,7 @@
+import { type DelegationLimits } from "../shared/limits.js";
+import type { DelegationStore } from "./types.js";
+export declare function createInMemoryDelegationStore(options?: {
+    readonly limits?: Partial<DelegationLimits>;
+    readonly storeId?: string;
+}): DelegationStore;
+//# sourceMappingURL=memory.d.ts.map