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

package/dist/delivery/parse.js

@@ -0,0 +1,31 @@
+import { z } from "zod/v4";
+import { copyBoundedDelegationData } from "../shared/bounds.js";
+import { delegationSchemaError } from "../shared/errors.js";
+import { delegationDataBytes } from "../shared/identity.js";
+import { freezeDelegationData } from "../shared/immutable.js";
+import { AtSchema, OpaqueIdSchema } from "../tasks/schemas.js";
+const accepted = z.strictObject({ status: z.literal("accepted"), inboxId: OpaqueIdSchema, acceptedAt: AtSchema });
+const rejected = z.strictObject({ status: z.literal("rejected"), reason: z.enum(["revoked", "parent_retired", "expired", "dismissed"]) });
+const acceptance = z.discriminatedUnion("status", [
+  accepted,
+  rejected,
+  z.strictObject({ status: z.literal("blocked"), reason: z.enum(["busy", "authority_unavailable", "capacity"]), retryAt: AtSchema }),
+  z.strictObject({ status: z.literal("uncertain") })
+]).refine((value) => delegationDataBytes(value) <= 2048, "Inbox result exceeds its bounded receipt.");
+const inspection = z.discriminatedUnion("status", [
+  accepted,
+  rejected,
+  z.strictObject({ status: z.literal("absent") })
+]).refine((value) => delegationDataBytes(value) <= 2048, "Inbox inspection exceeds its bounded receipt.");
+function parse(schema, input) {
+  const captured = copyBoundedDelegationData(input);
+  const result = schema.safeParse(captured);
+  if (!result.success) return delegationSchemaError(result.error, captured);
+  return freezeDelegationData(result.data);
+}
+const parseDelegationInboxAcceptance = (input) => parse(acceptance, input);
+const parseDelegationInboxInspection = (input) => parse(inspection, input);
+export {
+  parseDelegationInboxAcceptance,
+  parseDelegationInboxInspection
+};

package/dist/delivery/recovery.d.ts

@@ -0,0 +1,3 @@
+import { type CoordinatorState } from "../execution/state.js";
+export declare function recoverNotificationClaims(state: CoordinatorState): Promise<void>;
+//# sourceMappingURL=recovery.d.ts.map

package/dist/delivery/recovery.js

@@ -0,0 +1,18 @@
+import { now } from "../execution/state.js";
+import { readNotification, receiptNotification } from "./journal.js";
+async function recoverNotificationClaims(state) {
+  let cursor;
+  do {
+    const page = await state.options.store.scan({ kind: "eligible_notifications", at: now(), limit: state.options.limits.maxPageRecords, ...cursor ? { cursor } : {} });
+    if (page.kind !== "eligible_notifications") return;
+    for (const scanned of page.page.items) {
+      const notification = await readNotification(state, scanned.envelope.notificationId);
+      if (notification.state !== "claimed" || notification.claim?.ownerEpoch === state.owner.epoch) continue;
+      await receiptNotification(state, notification, { status: "uncertain", retryAt: new Date(Date.now() + 1e3).toISOString() });
+    }
+    cursor = page.page.cursor;
+  } while (cursor);
+}
+export {
+  recoverNotificationClaims
+};

package/dist/delivery/scheduler.d.ts

@@ -0,0 +1,3 @@
+import { type CoordinatorState } from "../execution/state.js";
+export declare function installDeliveryScheduler(state: CoordinatorState): void;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/delivery/scheduler.js

@@ -0,0 +1,123 @@
+import { now } from "../execution/state.js";
+import { DelegationOperationError } from "../shared/operational-errors.js";
+import { callInbox } from "./calls.js";
+import { claimNotification, readNotification, receiptNotification } from "./journal.js";
+import { parseDelegationInboxAcceptance, parseDelegationInboxInspection } from "./parse.js";
+function retryTime(attempt) {
+  return new Date(Date.now() + Math.min(3e4, 1e3 * 2 ** Math.min(5, Math.max(0, attempt - 1)))).toISOString();
+}
+function eligibleAt(notification) {
+  const retry = notification.retryAt ? Date.parse(notification.retryAt) : 0;
+  return notification.reason === "uncertain" ? retry : Math.min(Date.parse(notification.envelope.expiresAt), retry);
+}
+function deliveryResult(value, attempt) {
+  if (value.status === "accepted") return value;
+  if (value.status === "uncertain") return { status: "uncertain", retryAt: retryTime(attempt) };
+  if (value.status === "blocked") return { ...value, retryAt: new Date(Math.max(Date.now() + 1e3, Math.min(Date.now() + 3e4, Date.parse(value.retryAt)))).toISOString() };
+  return { status: value.reason === "expired" || value.reason === "dismissed" ? value.reason : "rejected", reason: value.reason };
+}
+function installDeliveryScheduler(state) {
+  const port = state.options.parentDelivery;
+  let stopped = false;
+  let pump;
+  let pending = false;
+  let timer;
+  const isStopped = () => stopped || state.failed || state.released;
+  async function deliver(notification) {
+    if (notification.state === "claimed") {
+      return receiptNotification(state, notification, { status: "uncertain", retryAt: retryTime(notification.attempts) });
+    }
+    const claimed = await claimNotification(state, notification);
+    if (claimed.state !== "claimed") return claimed;
+    let result = { status: "uncertain", retryAt: retryTime(claimed.attempts) };
+    try {
+      let inspection = { status: "absent" };
+      if (claimed.attempts > 1) {
+        const raw = await callInbox(state, claimed, "inspect", isStopped, (signal, deadlineAt) => port.inspect({
+          storeId: claimed.envelope.storeId,
+          notificationId: claimed.envelope.notificationId,
+          parent: claimed.envelope.parent,
+          signal,
+          deadlineAt
+        }));
+        if (raw === void 0) return receiptNotification(state, claimed, { status: "uncertain", retryAt: retryTime(claimed.attempts) });
+        inspection = parseDelegationInboxInspection(raw);
+      }
+      if (inspection.status !== "absent") result = deliveryResult(inspection, claimed.attempts);
+      else if (Date.parse(claimed.envelope.expiresAt) <= Date.now()) result = { status: "expired", reason: "expired" };
+      else if (!isStopped() && state.deliveryCalls.size === 0) {
+        const raw = await callInbox(state, claimed, "accept", isStopped, (signal, deadlineAt) => port.accept({ envelope: claimed.envelope, signal, deadlineAt }));
+        result = raw === void 0 ? { status: "uncertain", retryAt: retryTime(claimed.attempts) } : deliveryResult(parseDelegationInboxAcceptance(raw), claimed.attempts);
+      }
+    } catch {
+      result = { status: "uncertain", retryAt: retryTime(claimed.attempts) };
+    }
+    return receiptNotification(state, claimed, result);
+  }
+  async function run() {
+    if (timer) {
+      clearTimeout(timer);
+      timer = void 0;
+    }
+    let earliest = Infinity;
+    let cursor;
+    do {
+      const page = await state.options.store.scan({ kind: "eligible_notifications", at: now(), limit: state.options.limits.maxPageRecords, ...cursor ? { cursor } : {} });
+      if (page.kind !== "eligible_notifications") return;
+      for (const scanned of page.page.items) {
+        if (isStopped() || state.deliveryCalls.size > 0) return;
+        let notification = await readNotification(state, scanned.envelope.notificationId);
+        if (notification.envelope.policy === "collect" || !["pending", "claimed"].includes(notification.state)) continue;
+        if (notification.state === "claimed" && notification.claim?.ownerEpoch === state.owner.epoch) continue;
+        const eligible = eligibleAt(notification);
+        if (notification.state === "pending" && eligible > Date.now()) {
+          earliest = Math.min(earliest, eligible);
+          continue;
+        }
+        try {
+          notification = await deliver(notification);
+        } catch (error) {
+          if (!(error instanceof DelegationOperationError) || error.code !== "stale_revision") throw error;
+          notification = await readNotification(state, scanned.envelope.notificationId);
+        }
+        if (notification.state === "pending") earliest = Math.min(earliest, eligibleAt(notification));
+      }
+      cursor = page.page.cursor;
+    } while (cursor && !isStopped());
+    if (Number.isFinite(earliest) && !isStopped() && state.deliveryCalls.size === 0) {
+      timer = setTimeout(() => {
+        timer = void 0;
+        schedule();
+      }, Math.max(1, earliest - Date.now()));
+    }
+  }
+  function schedule() {
+    if (!port || isStopped()) return;
+    if (pump) {
+      pending = true;
+      return;
+    }
+    const work = Promise.resolve().then(run).catch(() => state.fail()).finally(() => {
+      pump = void 0;
+      state.changed();
+      if (pending) {
+        pending = false;
+        schedule();
+      }
+    });
+    pump = work;
+    state.track(work);
+  }
+  state.wakeDelivery = schedule;
+  state.stopDelivery = (abort) => {
+    stopped = true;
+    if (timer) {
+      clearTimeout(timer);
+      timer = void 0;
+    }
+    if (abort) for (const call of state.deliveryCalls.values()) call.controller.abort(new DOMException("Parent inbox delivery stopped.", "AbortError"));
+  };
+}
+export {
+  installDeliveryScheduler
+};

package/dist/delivery/setup.d.ts

@@ -0,0 +1,7 @@
+import type { CreateDelegationCoordinatorOptions } from "../coordinator/types.js";
+import type { CoordinatorState } from "../execution/state.js";
+import type { DelegationCompletionPolicy } from "../tasks/types.js";
+export declare function validateDeliverySetup(options: CreateDelegationCoordinatorOptions): void;
+export declare function assertCompletionPolicy(state: CoordinatorState, policy: DelegationCompletionPolicy): void;
+export declare function assertRetainedDeliverySetup(state: CoordinatorState): Promise<void>;
+//# sourceMappingURL=setup.d.ts.map

package/dist/delivery/setup.js

@@ -0,0 +1,37 @@
+import { now } from "../execution/state.js";
+import { failDelegation } from "../shared/operational-errors.js";
+function validateDeliverySetup(options) {
+  const port = options.parentDelivery;
+  if (port === void 0) return;
+  if (!port || typeof port !== "object" || !["volatile", "durable"].includes(port.persistence) || typeof port.accept !== "function" || typeof port.inspect !== "function") {
+    failDelegation("unsupported_operation", "Completion delivery requires a declared bounded inbox port.");
+  }
+  if (options.store.persistence === "durable" && port.persistence !== "durable") {
+    failDelegation("unsupported_operation", "A durable task store requires durable parent inbox acceptance.");
+  }
+}
+function assertCompletionPolicy(state, policy) {
+  if (policy !== "collect" && !state.options.parentDelivery) {
+    failDelegation("unsupported_operation", "This completion policy requires an explicit compatible parent inbox port.");
+  }
+}
+async function assertRetainedDeliverySetup(state) {
+  if (state.options.parentDelivery) return;
+  for (const kind of ["queued", "recoverable_runs", "eligible_notifications"]) {
+    let cursor;
+    do {
+      const page = await state.options.store.scan({ kind, at: now(), limit: state.options.limits.maxPageRecords, ...cursor ? { cursor } : {} });
+      if (page.kind === "eligible_notifications") {
+        for (const notification of page.page.items) assertCompletionPolicy(state, notification.envelope.policy);
+      } else {
+        for (const run of page.page.items) assertCompletionPolicy(state, (await state.task(run.taskId)).task.completionPolicy);
+      }
+      cursor = page.page.cursor;
+    } while (cursor);
+  }
+}
+export {
+  assertCompletionPolicy,
+  assertRetainedDeliverySetup,
+  validateDeliverySetup
+};

package/dist/delivery/types.d.ts

@@ -0,0 +1,36 @@
+import type { DelegationCompletionEnvelope, DelegationParentScope, DelegationPersistence } from "../tasks/types.js";
+export type DelegationInboxAcceptance = Readonly<{
+    status: "accepted";
+    inboxId: string;
+    acceptedAt: string;
+}> | Readonly<{
+    status: "blocked";
+    reason: "busy" | "authority_unavailable" | "capacity";
+    retryAt: string;
+}> | Readonly<{
+    status: "rejected";
+    reason: "revoked" | "parent_retired" | "expired" | "dismissed";
+}> | Readonly<{
+    status: "uncertain";
+}>;
+export type DelegationInboxInspection = Readonly<{
+    status: "absent";
+}> | Extract<DelegationInboxAcceptance, {
+    status: "accepted" | "rejected";
+}>;
+export interface DelegationParentDeliveryPort {
+    readonly persistence: DelegationPersistence;
+    accept(input: Readonly<{
+        envelope: DelegationCompletionEnvelope;
+        signal: AbortSignal;
+        deadlineAt: string;
+    }>): Promise<DelegationInboxAcceptance>;
+    inspect(input: Readonly<{
+        storeId: string;
+        notificationId: string;
+        parent: DelegationParentScope;
+        signal: AbortSignal;
+        deadlineAt: string;
+    }>): Promise<DelegationInboxInspection>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/execution/authority.d.ts

@@ -0,0 +1,16 @@
+import type { DelegationTarget, DelegationTargetReference } from "../catalog/types.js";
+import type { DelegationPolicyCeiling } from "../tasks/types.js";
+import type { CoordinatorState, LiveRun, ParentBinding } from "./state.js";
+export declare function sameTarget(left: DelegationTargetReference, right: DelegationTargetReference): boolean;
+export declare function readCeiling(state: CoordinatorState, ceilingId: string): Promise<DelegationPolicyCeiling>;
+export declare function bindingCeiling(state: CoordinatorState, binding: ParentBinding): Promise<DelegationPolicyCeiling | undefined>;
+export declare function effectiveChoices(state: CoordinatorState, binding: ParentBinding): Promise<{
+    resolved: import("../index.js").ResolvedDelegationPolicy;
+    targets: DelegationTarget[];
+    ceiling: DelegationPolicyCeiling;
+    originPolicyRevision: number;
+    enabled: boolean;
+}>;
+export declare function admittedTarget(choices: Awaited<ReturnType<typeof effectiveChoices>>, reference: DelegationTargetReference, revision: number): DelegationTarget;
+export declare function assertRunDispatch(state: CoordinatorState, live: LiveRun, policyRevision: number, originPolicyRevision: number): void;
+//# sourceMappingURL=authority.d.ts.map

package/dist/execution/authority.js

@@ -0,0 +1,86 @@
+import { resolveDelegationPolicy } from "../policy/resolve.js";
+import { delegationCanonicalJson } from "../shared/identity.js";
+import { failDelegation } from "../shared/operational-errors.js";
+import { createDelegationPolicyCeiling, parseDelegationParentScope } from "../tasks/parse.js";
+function sameTarget(left, right) {
+  return delegationCanonicalJson(left) === delegationCanonicalJson(right);
+}
+function current(state, scope) {
+  const snapshot = state.options.host.currentPolicy(scope);
+  const actual = parseDelegationParentScope(snapshot.scope);
+  if (actual.parentId !== scope.parentId || actual.scopeId !== scope.scopeId || actual.revision !== scope.revision) {
+    failDelegation("stale_revision", "The parent scope grant is no longer current.");
+  }
+  return resolveDelegationPolicy({ catalog: snapshot.catalog, policy: snapshot.policy });
+}
+async function readCeiling(state, ceilingId) {
+  const targets = [];
+  let origin;
+  let cursor;
+  do {
+    const page = await state.options.store.read({ kind: "ceiling", ceilingId, ...cursor === void 0 ? {} : { cursor }, limit: state.options.limits.maxPageRecords });
+    if (page.kind !== "ceiling" || !page.origin) return failDelegation("owner_lost", "The originating policy ceiling is unavailable.");
+    origin = page.origin;
+    targets.push(...page.page.items);
+    if (targets.length > 1e3) failDelegation("capacity_exceeded", "The originating policy ceiling exceeds its bound.");
+    cursor = page.page.cursor;
+  } while (cursor !== void 0);
+  if (!origin) return failDelegation("owner_lost", "The originating policy ceiling is unavailable.");
+  const ceiling = createDelegationPolicyCeiling({ origin, targets });
+  if (ceiling.ceilingId !== ceilingId) failDelegation("owner_lost", "The stored policy ceiling is inconsistent.");
+  return ceiling;
+}
+async function bindingCeiling(state, binding) {
+  if (binding.ceiling) return binding.ceiling;
+  if (!binding.ancestor) return void 0;
+  const [{ task }, run] = await Promise.all([state.task(binding.ancestor.taskId), state.run(binding.ancestor.taskId, binding.ancestor.runId)]);
+  if (task.parent.scopeId !== binding.scope.scopeId || run.ownerEpoch !== state.owner.epoch || !["preparing", "running", "waiting"].includes(run.phase) || !state.live.has(run.runId)) {
+    failDelegation("owner_lost", "The descendant binding does not belong to a live owned ancestor run.");
+  }
+  return readCeiling(state, task.policyCeilingRef);
+}
+async function effectiveChoices(state, binding) {
+  const inherited = await bindingCeiling(state, binding);
+  const resolved = current(state, binding.scope);
+  const origin = inherited === void 0 ? resolved : current(state, inherited.origin);
+  const inheritedKeys = inherited === void 0 ? void 0 : new Set(inherited.targets.map(delegationCanonicalJson));
+  const originKeys = new Set(origin.allowedTargets.map((target) => delegationCanonicalJson(target.reference)));
+  const targets = resolved.allowedTargets.filter((target) => originKeys.has(delegationCanonicalJson(target.reference)) && (inheritedKeys === void 0 || inheritedKeys.has(delegationCanonicalJson(target.reference))));
+  const ceiling = inherited ?? createDelegationPolicyCeiling({ origin: binding.scope, targets: targets.map((target) => target.reference) });
+  return { resolved, targets, ceiling, originPolicyRevision: origin.policyRevision, enabled: resolved.enabled && origin.enabled };
+}
+function admittedTarget(choices, reference, revision) {
+  if (choices.resolved.policyRevision !== revision) failDelegation("stale_revision", "The selected managed policy revision is stale.");
+  if (!choices.resolved.enabled) failDelegation("delegation_disabled", "Managed delegation is disabled.");
+  const decision = choices.resolved.decisions.find((entry) => entry.reference.targetId === reference.targetId && entry.reference.catalogId === reference.catalogId);
+  if (!decision || !sameTarget(decision.reference, reference)) failDelegation("stale_target", "The exact selected target or source revision is stale.");
+  const target = choices.targets.find((entry) => sameTarget(entry.reference, reference));
+  if (!target) {
+    if (decision.reasons.some((reason) => reason.code === "target_unavailable")) failDelegation("target_unavailable", "The selected target is unavailable.");
+    failDelegation("policy_denied", "Current policy or the originating ceiling denies this target.");
+  }
+  return target;
+}
+function assertRunDispatch(state, live, policyRevision, originPolicyRevision) {
+  if (state.closing && !state.draining || state.failed || state.released) failDelegation("owner_lost", "The coordinator is closed to new execution input.");
+  if (live.lifetime.signal.aborted) failDelegation("recovery_required", "The run no longer accepts execution input.");
+  const resolved = current(state, live.scope);
+  const origin = current(state, live.ceiling.origin);
+  if (resolved.policyRevision !== policyRevision || origin.policyRevision !== originPolicyRevision) {
+    failDelegation("stale_revision", "Managed policy changed before provider execution.");
+  }
+  if (!resolved.enabled || !origin.enabled) failDelegation("delegation_disabled", "Managed delegation is disabled.");
+  const exact = (target) => sameTarget(target.reference, live.target.reference);
+  if (!live.ceiling.targets.some((reference) => sameTarget(reference, live.target.reference)) || !resolved.allowedTargets.some(exact) || !origin.allowedTargets.some(exact)) {
+    failDelegation("policy_denied", "Current policy or the originating ceiling no longer permits the exact target.");
+  }
+  live.execution?.assertCurrent();
+}
+export {
+  admittedTarget,
+  assertRunDispatch,
+  bindingCeiling,
+  effectiveChoices,
+  readCeiling,
+  sameTarget
+};

package/dist/execution/cleanup.d.ts

@@ -0,0 +1,3 @@
+import type { CoordinatorState, LiveRun } from "./state.js";
+export declare function cleanupRun(state: CoordinatorState, live: LiveRun): Promise<boolean>;
+//# sourceMappingURL=cleanup.d.ts.map

package/dist/execution/cleanup.js

@@ -0,0 +1,75 @@
+import { dispatchIntent, operationIdentity, operationReceipt } from "./journal.js";
+async function record(state, action) {
+  try {
+    await action();
+  } catch {
+    state.fail();
+  }
+}
+async function runtimeCleanup(state, live) {
+  const close = operationIdentity(live, "session_close");
+  const binding = operationIdentity(live, "binding_cleanup");
+  if (live.rejectedOpening && live.runtimeCleanupAttempts === 0) {
+    live.runtimeCleanupAttempts = 1;
+    await record(state, () => dispatchIntent(state, live, "session_close", close, { attempt: 1 }));
+    await record(state, () => dispatchIntent(state, live, "binding_cleanup", binding, { attempt: 1 }));
+    await record(state, () => operationReceipt(state, live, "uncertain", close));
+    await record(state, () => operationReceipt(state, live, "uncertain", binding));
+  }
+  while (!live.runtimeClosed && live.runtimeCleanupAttempts < 2) {
+    live.runtimeCleanupAttempts += 1;
+    const attempt = live.runtimeCleanupAttempts;
+    await record(state, () => dispatchIntent(state, live, "session_close", close, { attempt }));
+    await record(state, () => dispatchIntent(state, live, "binding_cleanup", binding, { attempt }));
+    try {
+      if (live.rejectedOpening) await live.rejectedOpening.retryCleanup();
+      else if (live.session) await live.session.close({ reason: state.closing ? "shutdown" : "idle" });
+      live.runtimeClosed = true;
+    } catch {
+      await record(state, () => operationReceipt(state, live, "uncertain", close));
+      await record(state, () => operationReceipt(state, live, "uncertain", binding));
+    }
+  }
+  return live.runtimeClosed;
+}
+function cleanupRun(state, live) {
+  if (live.cleanup) return live.cleanup;
+  live.cleanup = (async () => {
+    live.removeRevocation?.();
+    if (live.deadline) clearTimeout(live.deadline);
+    if (live.request) {
+      state.requests.delete(live.request.handle);
+      live.request = void 0;
+    }
+    const reason = new DOMException("The managed run is closing.", "AbortError");
+    live.controlAbort.abort(reason);
+    const runtimeClosing = runtimeCleanup(state, live);
+    live.lifetime.abort(reason);
+    while (live.controls.size > 0) await Promise.allSettled(live.controls);
+    if (!await runtimeClosing) return false;
+    while (!live.resourcesReleased && live.resourceReleaseAttempts < 2) {
+      live.resourceReleaseAttempts += 1;
+      try {
+        await live.resources?.release();
+        live.resourcesReleased = true;
+      } catch {
+      }
+    }
+    if (!live.resourcesReleased) return false;
+    await record(state, () => operationReceipt(state, live, "completed", operationIdentity(live, "session_close")));
+    await record(state, () => operationReceipt(state, live, "completed", operationIdentity(live, "binding_cleanup")));
+    while (!live.executionReleased && live.executionReleaseAttempts < 2) {
+      live.executionReleaseAttempts += 1;
+      try {
+        await live.execution?.release();
+        live.executionReleased = true;
+      } catch {
+      }
+    }
+    return live.executionReleased;
+  })();
+  return live.cleanup;
+}
+export {
+  cleanupRun
+};

package/dist/execution/control.d.ts

@@ -0,0 +1,6 @@
+import type { DelegationRequestReceipt, DelegationResolveHostRequestInput, DelegationSendReceipt, DelegationSendTaskInput } from "../coordinator/types.js";
+import { type CoordinatorState, type LiveRun } from "./state.js";
+export declare function cancelLive(state: CoordinatorState, live: LiveRun, reason: string): Promise<unknown>;
+export declare function steerRun(state: CoordinatorState, live: LiveRun, input: DelegationSendTaskInput, digest: string, originPolicyRevision: number): Promise<DelegationSendReceipt>;
+export declare function resolveLiveRequest(state: CoordinatorState, input: DelegationResolveHostRequestInput): Promise<DelegationRequestReceipt>;
+//# sourceMappingURL=control.d.ts.map