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

package/dist/coordinator/read.js

@@ -0,0 +1,267 @@
+import { z } from "zod/v4";
+import { effectiveChoices } from "../execution/authority.js";
+import { sameScopeIdentity } from "../execution/state.js";
+import { captureDelegationRecord } from "../shared/bounds.js";
+import { invalidDelegationData } from "../shared/errors.js";
+import { freezeDelegationData } from "../shared/immutable.js";
+import { failDelegation } from "../shared/operational-errors.js";
+import { delegationCursorPrefix, pageDelegationRows } from "../store/pages.js";
+import { parseCoordinatorInput } from "./parse.js";
+const cursor = z.string().min(1).max(512);
+const limit = z.number().int().positive().max(100);
+const taskId = z.uuid();
+const targetQuery = z.strictObject({ cursor: cursor.optional(), limit: limit.optional() });
+const inspectQuery = z.strictObject({ taskId, runsCursor: cursor.optional(), limit: limit.optional() });
+const observeQuery = z.strictObject({ taskId, after: cursor.optional() });
+const waitQuery = z.strictObject({ taskId, timeoutMs: z.number().int().positive().max(2147483647) });
+function withSignal(schema, input) {
+  const { signal, ...data } = captureDelegationRecord(input);
+  if (signal !== void 0 && !(signal instanceof AbortSignal)) {
+    return invalidDelegationData("invalid_data", ["signal"], "A subscription signal must be an AbortSignal.");
+  }
+  return { ...parseCoordinatorInput(schema, data), ...signal === void 0 ? {} : { signal } };
+}
+function assertAccess(state, binding, task) {
+  if (task && !sameScopeIdentity(task.parent, binding.scope)) {
+    failDelegation("policy_denied", "The task does not belong to this parent scope.");
+  }
+  state.options.host.assertResultAccess({ scope: binding.scope, ...task === void 0 ? {} : { task } });
+}
+async function inspect(state, binding, input) {
+  assertAccess(state, binding);
+  const result = await state.options.store.read({
+    kind: "task",
+    taskId: input.taskId,
+    ...input.runsCursor === void 0 ? {} : { cursor: input.runsCursor },
+    ...input.limit === void 0 ? {} : { limit: input.limit }
+  });
+  if (result.kind !== "task" || !result.view) return failDelegation("request_unavailable", "The managed task is unavailable.");
+  assertAccess(state, binding, result.view.task);
+  return freezeDelegationData(result.view);
+}
+function watch(state, signal, timeoutMs) {
+  let resolve;
+  const promise = new Promise((done) => {
+    resolve = done;
+  });
+  const wake = () => resolve();
+  state.waiters.add(wake);
+  signal?.addEventListener("abort", wake, { once: true });
+  const timer = setTimeout(wake, timeoutMs);
+  if (signal?.aborted) wake();
+  return { promise, dispose() {
+    clearTimeout(timer);
+    state.waiters.delete(wake);
+    signal?.removeEventListener("abort", wake);
+  } };
+}
+function observationCursor(state, task, run, index) {
+  return `observation:${state.options.store.storeId}:${task}:${run}:${index}`;
+}
+async function observeFromCursor(state, task, after) {
+  if (after === void 0) return void 0;
+  const parts = after.split(":");
+  if (parts.length !== 5 || parts[0] !== "observation" || parts[1] !== state.options.store.storeId || parts[2] !== task || !z.uuid().safeParse(parts[3]).success || !/^(?:0|[1-9][0-9]*)$/u.test(parts[4])) {
+    return failDelegation("stale_revision", "The observation cursor belongs to a different task or store.");
+  }
+  const run = await state.run(task, parts[3]);
+  const index = Number(parts[4]);
+  if (!Number.isSafeInteger(index) || index > run.observationIndex) {
+    return failDelegation("stale_revision", "The observation cursor is beyond the retained run.");
+  }
+  return { runId: run.runId, index, ordinal: run.ordinal };
+}
+async function* observations(state, binding, input) {
+  assertAccess(state, binding);
+  let position = await observeFromCursor(state, input.taskId, input.after);
+  for (; ; ) {
+    input.signal.throwIfAborted();
+    const update = watch(state, input.signal, state.options.limits.maxWaitMs);
+    try {
+      let runsCursor;
+      let view;
+      let hasUnsettledRuns = false;
+      let currentRunActive = false;
+      do {
+        view = await inspect(state, binding, {
+          taskId: input.taskId,
+          ...runsCursor === void 0 ? {} : { runsCursor }
+        });
+        for (const run of view.runs.items) {
+          if (run.phase !== "settled") hasUnsettledRuns = true;
+          if (position && run.ordinal < position.ordinal) continue;
+          if (!position || position.runId !== run.runId) position = { runId: run.runId, index: 0, ordinal: run.ordinal };
+          let more;
+          do {
+            input.signal.throwIfAborted();
+            assertAccess(state, binding, view.task);
+            const prefix = delegationCursorPrefix(
+              state.options.store.storeId,
+              { kind: "observations", taskId: input.taskId, runId: run.runId }
+            );
+            const page = await state.options.store.read({
+              kind: "observations",
+              taskId: input.taskId,
+              runId: run.runId,
+              ...position.index === 0 ? {} : { cursor: `${prefix}${String(position.index).padStart(16, "0")}` }
+            });
+            if (page.kind !== "observations") return failDelegation("store_failed", "The store returned a mismatched observation page.");
+            assertAccess(state, binding, view.task);
+            for (const observation of page.page.items) {
+              input.signal.throwIfAborted();
+              assertAccess(state, binding, view.task);
+              if (observation.index > position.index + 1) {
+                position.index = observation.index - 1;
+                yield freezeDelegationData({
+                  kind: "gap",
+                  storeId: state.options.store.storeId,
+                  taskId: input.taskId,
+                  runId: run.runId,
+                  cursor: observationCursor(state, input.taskId, run.runId, position.index)
+                });
+                input.signal.throwIfAborted();
+                assertAccess(state, binding, view.task);
+              }
+              position.index = observation.index;
+              yield freezeDelegationData({ ...observation, cursor: observationCursor(state, input.taskId, run.runId, position.index) });
+            }
+            more = page.page.cursor;
+            if (more === void 0 && page.latestIndex > position.index) {
+              position.index = page.latestIndex;
+              input.signal.throwIfAborted();
+              assertAccess(state, binding, view.task);
+              yield freezeDelegationData({
+                kind: "gap",
+                storeId: state.options.store.storeId,
+                taskId: input.taskId,
+                runId: run.runId,
+                cursor: observationCursor(state, input.taskId, run.runId, position.index)
+              });
+            }
+          } while (more !== void 0);
+          if (run.phase !== "settled") {
+            currentRunActive = true;
+            break;
+          }
+        }
+        runsCursor = currentRunActive ? void 0 : view.runs.cursor;
+      } while (runsCursor !== void 0);
+      if (view.task.state === "settled" || view.task.state === "retired") return;
+      if (view.task.state === "recovery_required" && !hasUnsettledRuns) return;
+      if (state.failed || state.released) failDelegation("owner_lost", "The managed executor is unavailable; inspect its retained history.");
+      await update.promise;
+    } finally {
+      update.dispose();
+    }
+  }
+}
+function subscription(state, binding, input) {
+  return { [Symbol.asyncIterator]() {
+    const lifetime = new AbortController();
+    const signal = input.signal ? AbortSignal.any([input.signal, lifetime.signal]) : lifetime.signal;
+    const iterator = observations(state, binding, { ...input, signal });
+    let pulling = false;
+    return {
+      async next() {
+        if (pulling) return failDelegation("unsupported_operation", "An observation subscription permits one pending read.");
+        pulling = true;
+        try {
+          return await iterator.next();
+        } finally {
+          pulling = false;
+        }
+      },
+      async return() {
+        lifetime.abort(new DOMException("Observation subscription closed.", "AbortError"));
+        await iterator.return(void 0);
+        return { done: true, value: void 0 };
+      }
+    };
+  } };
+}
+function createReadClient(state, binding) {
+  return {
+    async bindingSnapshot() {
+      assertAccess(state, binding);
+      const choices = await effectiveChoices(state, binding);
+      assertAccess(state, binding);
+      const { maxInputBytes, maxInputTextCharacters, maxWaitMs, runTimeoutMs, maxPageRecords } = state.options.limits;
+      return freezeDelegationData({
+        enabled: choices.enabled,
+        policyRevision: choices.resolved.policyRevision,
+        completionPolicies: state.options.parentDelivery ? ["collect", "next_turn", "automatic"] : ["collect"],
+        limits: { maxInputBytes, maxInputTextCharacters, maxWaitMs, runTimeoutMs, maxPageRecords }
+      });
+    },
+    async targets(input = {}) {
+      const query = parseCoordinatorInput(targetQuery, input);
+      assertAccess(state, binding);
+      const choices = await effectiveChoices(state, binding);
+      assertAccess(state, binding);
+      const page = pageDelegationRows({
+        storeId: state.options.store.storeId,
+        query: {
+          kind: "targets",
+          scope: binding.scope,
+          policyRevision: choices.resolved.policyRevision,
+          originPolicyRevision: choices.originPolicyRevision,
+          ceilingId: choices.ceiling.ceilingId
+        },
+        rows: choices.targets.map((target, index) => ({ target, index })),
+        key: ({ index }) => String(index).padStart(4, "0"),
+        limits: state.options.limits,
+        ...query,
+        envelopeBytes: 64
+      });
+      return freezeDelegationData({
+        policyRevision: choices.resolved.policyRevision,
+        targets: page.items.map(({ target }) => target),
+        ...page.cursor === void 0 ? {} : { cursor: page.cursor },
+        ...choices.targets.length === 0 ? { emptyReason: choices.enabled ? "no_permitted_targets" : "delegation_disabled" } : {}
+      });
+    },
+    inspect(input) {
+      return inspect(state, binding, parseCoordinatorInput(inspectQuery, input));
+    },
+    observe(input) {
+      return subscription(state, binding, withSignal(observeQuery, input));
+    },
+    async wait(input) {
+      const query = withSignal(waitQuery, input);
+      if (query.timeoutMs > state.options.limits.maxWaitMs) failDelegation("capacity_exceeded", "The wait exceeds the configured subscription deadline.");
+      const deadline = Date.now() + query.timeoutMs;
+      for (; ; ) {
+        query.signal?.throwIfAborted();
+        const update = watch(state, query.signal, Math.max(1, deadline - Date.now()));
+        try {
+          const view = await inspect(state, binding, { taskId: query.taskId });
+          query.signal?.throwIfAborted();
+          if (view.task.state === "settled" || view.task.state === "retired") {
+            return freezeDelegationData({ status: "settled", task: view });
+          }
+          if (view.task.state === "recovery_required") {
+            let page = view;
+            let active = false;
+            let changed = false;
+            for (; ; ) {
+              active ||= page.runs.items.some((run) => run.phase !== "settled");
+              changed ||= page.task.revision !== view.task.revision;
+              if (!page.runs.cursor || active || changed) break;
+              page = await inspect(state, binding, { taskId: query.taskId, runsCursor: page.runs.cursor });
+            }
+            query.signal?.throwIfAborted();
+            if (!active && !changed) return freezeDelegationData({ status: "settled", task: view });
+          }
+          if (Date.now() >= deadline) return freezeDelegationData({ status: "timeout", task: view });
+          if (state.failed || state.released) failDelegation("owner_lost", "The managed executor is unavailable; inspect its retained history.");
+          await update.promise;
+        } finally {
+          update.dispose();
+        }
+      }
+    }
+  };
+}
+export {
+  createReadClient
+};

package/dist/coordinator/recovery.d.ts

@@ -0,0 +1,4 @@
+import { type CoordinatorState } from "../execution/state.js";
+import type { DelegationRecoveryPage } from "./types.js";
+export declare function recoverRuns(state: CoordinatorState, limit: number, cursor?: string, start?: boolean): Promise<DelegationRecoveryPage>;
+//# sourceMappingURL=recovery.d.ts.map

package/dist/coordinator/recovery.js

@@ -0,0 +1,24 @@
+import { settleRun } from "../execution/finish.js";
+import { schedule } from "../execution/scheduler.js";
+import { now } from "../execution/state.js";
+import { failDelegation } from "../shared/operational-errors.js";
+async function recoverRuns(state, limit, cursor, start = true) {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > state.options.limits.maxPageRecords) failDelegation("capacity_exceeded", "Recovery page size exceeds its bound.");
+  const page = await state.options.store.scan({ kind: "recoverable_runs", at: now(), limit, ...cursor ? { cursor } : {} });
+  if (page.kind !== "recoverable_runs") return { recovered: [] };
+  const recovered = [];
+  for (const run of page.page.items) {
+    if (run.ownerEpoch === state.owner.epoch || run.phase === "settled") continue;
+    if (run.phase === "queued" && run.preparation === "none" && run.dispatch === "none") {
+      recovered.push({ taskId: run.taskId, runId: run.runId, disposition: "queued" });
+    } else {
+      await settleRun(state, run, { kind: "recovery_required", reason: run.pendingRequest ? "request_executor_lost" : "executor_lost" });
+      recovered.push({ taskId: run.taskId, runId: run.runId, disposition: "recovery_required" });
+    }
+  }
+  if (start) schedule(state);
+  return { recovered, ...page.page.cursor ? { cursor: page.page.cursor } : {} };
+}
+export {
+  recoverRuns
+};

package/dist/coordinator/shutdown.d.ts

@@ -0,0 +1,7 @@
+import { type CoordinatorState } from "../execution/state.js";
+import type { DelegationShutdownReceipt } from "./types.js";
+export declare function shutdown(state: CoordinatorState, input: Readonly<{
+    mode: "drain" | "cancel";
+    timeoutMs: number;
+}>): Promise<DelegationShutdownReceipt>;
+//# sourceMappingURL=shutdown.d.ts.map

package/dist/coordinator/shutdown.js

@@ -0,0 +1,66 @@
+import { cancelLive } from "../execution/control.js";
+import { now } from "../execution/state.js";
+import { schedule } from "../execution/scheduler.js";
+import { delegationInputDigest, delegationSubordinateId } from "../shared/identity.js";
+import { failDelegation } from "../shared/operational-errors.js";
+async function cancelQueued(state) {
+  let cursor;
+  do {
+    const page = await state.options.store.scan({ kind: "queued", at: now(), limit: state.options.limits.maxPageRecords, ...cursor ? { cursor } : {} });
+    if (page.kind !== "queued") return;
+    for (const run of page.page.items) await state.mutate(
+      run.taskId,
+      run.runId,
+      delegationSubordinateId(run.runId, "shutdown_cancel"),
+      delegationInputDigest({ runId: run.runId, kind: "shutdown_cancel" }),
+      (fence) => ({ ...fence, kind: "cancel", at: now(), reason: "shutdown" })
+    );
+    cursor = page.page.cursor;
+  } while (cursor);
+}
+async function shutdown(state, input) {
+  if (!["drain", "cancel"].includes(input.mode) || !Number.isSafeInteger(input.timeoutMs) || input.timeoutMs < 1 || input.timeoutMs > state.options.limits.maxWaitMs) failDelegation("capacity_exceeded", "Shutdown exceeds its configured wait bound.");
+  if (state.released) return { status: "closed", retainedTaskIds: [] };
+  state.closing = true;
+  state.stopDelivery?.(input.mode === "cancel");
+  state.draining = input.mode === "drain";
+  if (!state.draining && state.queueTimer) {
+    clearTimeout(state.queueTimer);
+    state.queueTimer = void 0;
+  }
+  const actions = input.mode === "cancel" ? Promise.allSettled([cancelQueued(state), ...[...state.live.values()].map((live) => cancelLive(state, live, "shutdown"))]) : Promise.resolve();
+  state.track(Promise.resolve(actions).then(() => void 0));
+  if (state.draining) schedule(state);
+  const end = Date.now() + input.timeoutMs;
+  while ((state.producers.size > 0 || state.live.size > 0) && Date.now() < end) {
+    let timer;
+    let wake;
+    await new Promise((resolve) => {
+      wake = resolve;
+      state.waiters.add(resolve);
+      timer = setTimeout(resolve, Math.max(1, end - Date.now()));
+    });
+    if (timer) clearTimeout(timer);
+    if (wake) state.waiters.delete(wake);
+  }
+  const queuedTaskIds = [];
+  let cursor;
+  do {
+    const queued = await state.options.store.scan({ kind: "queued", at: now(), limit: state.options.limits.maxPageRecords, ...cursor ? { cursor } : {} });
+    if (queued.kind !== "queued") failDelegation("store_failed", "The queued scan does not match its query.");
+    queuedTaskIds.push(...queued.page.items.map((run) => run.taskId));
+    cursor = queued.page.cursor;
+  } while (cursor);
+  if (state.live.size > 0 || state.producers.size > 0 || state.failed || queuedTaskIds.length > 0) return { status: "recovery_required", retainedTaskIds: [...new Set([...state.live.values()].map((live) => live.taskId).concat(queuedTaskIds, [...state.deliveryCalls.values()].map((call) => call.taskId)))].sort() };
+  await state.options.store.releaseOwner(state.owner);
+  if (state.queueTimer) {
+    clearTimeout(state.queueTimer);
+    state.queueTimer = void 0;
+  }
+  state.released = true;
+  state.changed();
+  return { status: "closed", retainedTaskIds: [] };
+}
+export {
+  shutdown
+};

package/dist/coordinator/types.d.ts

@@ -0,0 +1,154 @@
+import type { AgentRequestResolution, AgentTurnInputContent } from "@agen-ai/agent-protocol";
+import type { DelegationTarget, DelegationTargetReference } from "../catalog/types.js";
+import type { DelegationParentDeliveryPort } from "../delivery/types.js";
+import type { DelegationHost, DelegationHostRequestHandle } from "../host/types.js";
+import type { DelegationLimits } from "../shared/limits.js";
+import type { DelegationStore } from "../store/types.js";
+import type { DelegationCompletionPolicy, DelegationObservationGap, DelegationObservedTaskObservation, DelegationParentScope, DelegationTaskView } from "../tasks/types.js";
+export interface DelegationTargetPage {
+    readonly policyRevision: number;
+    readonly targets: readonly DelegationTarget[];
+    readonly cursor?: string;
+    readonly emptyReason?: "delegation_disabled" | "no_permitted_targets";
+}
+export interface DelegationBindingSnapshot {
+    readonly enabled: boolean;
+    readonly policyRevision: number;
+    readonly completionPolicies: readonly DelegationCompletionPolicy[];
+    readonly limits: Readonly<Pick<DelegationLimits, "maxInputBytes" | "maxInputTextCharacters" | "maxWaitMs" | "runTimeoutMs" | "maxPageRecords">>;
+}
+export interface DelegationSpawnTaskInput {
+    readonly operationId: string;
+    readonly target: DelegationTargetReference;
+    readonly expectedPolicyRevision: number;
+    readonly input: AgentTurnInputContent;
+    readonly completionPolicy?: DelegationCompletionPolicy;
+    readonly timeoutMs?: number;
+}
+export interface DelegationSendTaskInput {
+    readonly operationId: string;
+    readonly taskId: string;
+    readonly mode: "steer" | "next_turn" | "follow_up";
+    readonly input: AgentTurnInputContent;
+    readonly target: DelegationTargetReference;
+    readonly expectedPolicyRevision: number;
+}
+export interface DelegationAdmissionReceipt {
+    readonly storeId: string;
+    readonly operationId: string;
+    readonly taskId: string;
+    readonly runId: string;
+    readonly target: DelegationTargetReference;
+    readonly revision: number;
+    readonly status: "queued" | "preparing";
+    readonly duplicate: boolean;
+}
+export type DelegationSendReceipt = Readonly<{
+    status: "queued";
+    admission: DelegationAdmissionReceipt;
+    duplicate: boolean;
+}> | Readonly<{
+    status: "delivered" | "rejected" | "delivery_uncertain";
+    operationId: string;
+    taskId: string;
+    runId: string;
+    duplicate: boolean;
+}>;
+export interface DelegationCancelReceipt {
+    readonly status: "requested" | "confirmed" | "recovery_required";
+    readonly operationId: string;
+    readonly taskId: string;
+    readonly duplicate: boolean;
+}
+export interface DelegationResolveHostRequestInput {
+    readonly handle: DelegationHostRequestHandle;
+    readonly operationId: string;
+    readonly resolution: AgentRequestResolution;
+}
+interface DelegationRequestReceiptIdentity {
+    readonly taskId: string;
+    readonly runId: string;
+    readonly operationId: string;
+    readonly duplicate: boolean;
+}
+export type DelegationRequestReceipt = DelegationRequestReceiptIdentity & (Readonly<{
+    status: "delivered" | "delivery_uncertain";
+}> | Readonly<{
+    status: "rejected";
+    requestState: "pending" | "unavailable";
+}>);
+export type DelegationWaitReceipt = Readonly<{
+    status: "settled" | "timeout";
+    task: DelegationTaskView;
+}>;
+export interface DelegationRecoveryPage {
+    readonly recovered: readonly Readonly<{
+        taskId: string;
+        runId: string;
+        disposition: "queued" | "recovery_required";
+    }>[];
+    readonly cursor?: string;
+}
+export interface DelegationShutdownReceipt {
+    readonly status: "closed" | "recovery_required";
+    readonly retainedTaskIds: readonly string[];
+}
+export interface DelegationClient {
+    bindingSnapshot(): Promise<DelegationBindingSnapshot>;
+    targets(input?: Readonly<{
+        cursor?: string;
+        limit?: number;
+    }>): Promise<DelegationTargetPage>;
+    spawn(input: DelegationSpawnTaskInput): Promise<DelegationAdmissionReceipt>;
+    inspect(input: Readonly<{
+        taskId: string;
+        runsCursor?: string;
+        limit?: number;
+    }>): Promise<DelegationTaskView>;
+    observe(input: Readonly<{
+        taskId: string;
+        after?: string;
+        signal?: AbortSignal;
+    }>): AsyncIterable<DelegationObservedTaskObservation | DelegationObservationGap>;
+    wait(input: Readonly<{
+        taskId: string;
+        timeoutMs: number;
+        signal?: AbortSignal;
+    }>): Promise<DelegationWaitReceipt>;
+    send(input: DelegationSendTaskInput): Promise<DelegationSendReceipt>;
+    cancel(input: Readonly<{
+        operationId: string;
+        taskId: string;
+    }>): Promise<DelegationCancelReceipt>;
+}
+export interface DelegationCoordinator {
+    bindParent(input: Readonly<{
+        scope: DelegationParentScope;
+        ancestor?: Readonly<{
+            taskId: string;
+            runId: string;
+        }>;
+    }>): Promise<DelegationClient>;
+    resolveRequest(input: DelegationResolveHostRequestInput): Promise<DelegationRequestReceipt>;
+    recover(input: Readonly<{
+        limit: number;
+        cursor?: string;
+    }>): Promise<DelegationRecoveryPage>;
+    retireRecoveryTask(input: Readonly<{
+        operationId: string;
+        taskId: string;
+        reason: string;
+    }>): Promise<DelegationTaskView>;
+    dispose(input: Readonly<{
+        mode: "drain" | "cancel";
+        timeoutMs: number;
+    }>): Promise<DelegationShutdownReceipt>;
+}
+export interface CreateDelegationCoordinatorOptions {
+    readonly host: DelegationHost;
+    readonly store: DelegationStore;
+    readonly limits: DelegationLimits;
+    readonly parentDelivery?: DelegationParentDeliveryPort;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/delivery/calls.d.ts

@@ -0,0 +1,4 @@
+import type { CoordinatorState } from "../execution/state.js";
+import type { DelegationNotificationRecord } from "../tasks/types.js";
+export declare function callInbox<Value>(state: CoordinatorState, notification: DelegationNotificationRecord, kind: "accept" | "inspect", stopped: () => boolean, invoke: (signal: AbortSignal, deadlineAt: string) => Promise<Value>): Promise<Value | undefined>;
+//# sourceMappingURL=calls.d.ts.map

package/dist/delivery/calls.js

@@ -0,0 +1,34 @@
+async function callInbox(state, notification, kind, stopped, invoke) {
+  const unavailable = () => stopped() || state.failed || state.released || kind === "accept" && Date.parse(notification.envelope.expiresAt) <= Date.now();
+  if (unavailable()) return void 0;
+  const controller = new AbortController();
+  const deadline = Math.min(
+    Date.now() + state.options.limits.controlTimeoutMs,
+    kind === "accept" ? Date.parse(notification.envelope.expiresAt) : Infinity
+  );
+  const id = notification.envelope.notificationId;
+  const promise = Promise.resolve().then(() => {
+    if (unavailable()) return void 0;
+    return invoke(controller.signal, new Date(deadline).toISOString());
+  }).finally(() => {
+    state.deliveryCalls.delete(id);
+    state.changed();
+    if (!stopped()) state.wakeDelivery?.();
+  });
+  state.deliveryCalls.set(id, { controller, taskId: notification.envelope.taskId, promise });
+  state.track(promise);
+  let timer;
+  try {
+    return await Promise.race([promise, new Promise((resolve) => {
+      timer = setTimeout(() => {
+        controller.abort(new DOMException("Parent inbox deadline expired.", "AbortError"));
+        resolve(void 0);
+      }, Math.max(1, deadline - Date.now()));
+    })]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+export {
+  callInbox
+};

package/dist/delivery/journal.d.ts

@@ -0,0 +1,7 @@
+import { type CoordinatorState } from "../execution/state.js";
+import type { DelegationDeliveryResult } from "../store/types.js";
+import type { DelegationNotificationRecord } from "../tasks/types.js";
+export declare function readNotification(state: CoordinatorState, notificationId: string): Promise<DelegationNotificationRecord>;
+export declare function claimNotification(state: CoordinatorState, notification: DelegationNotificationRecord): Promise<DelegationNotificationRecord>;
+export declare function receiptNotification(state: CoordinatorState, notification: DelegationNotificationRecord, result: DelegationDeliveryResult): Promise<DelegationNotificationRecord>;
+//# sourceMappingURL=journal.d.ts.map

package/dist/delivery/journal.js

@@ -0,0 +1,57 @@
+import { now } from "../execution/state.js";
+import { delegationInputDigest } from "../shared/identity.js";
+import { failDelegation } from "../shared/operational-errors.js";
+import { deliveryAttemptIdentity } from "../store-adapter/delivery.js";
+import { parseDelegationNotificationRecord } from "../tasks/parse.js";
+async function readNotification(state, notificationId) {
+  const page = await state.options.store.read({ kind: "notification", notificationId });
+  if (page.kind !== "notification" || !page.notification) return failDelegation("store_failed", "A retained completion notification is unavailable.");
+  return parseDelegationNotificationRecord(page.notification);
+}
+async function claimNotification(state, notification) {
+  const identity = deliveryAttemptIdentity(notification.envelope.notificationId, notification.attempts + 1);
+  const command = {
+    kind: "delivery_claim",
+    notificationId: notification.envelope.notificationId,
+    expectedNotificationRevision: notification.revision,
+    attemptId: identity.attemptId,
+    at: now()
+  };
+  await state.mutate(
+    notification.envelope.taskId,
+    notification.envelope.runId,
+    identity.claimOperationId,
+    delegationInputDigest(command),
+    (fence) => ({ ...fence, ...command })
+  );
+  return readNotification(state, notification.envelope.notificationId);
+}
+async function receiptNotification(state, notification, result) {
+  const identity = deliveryAttemptIdentity(notification.envelope.notificationId, notification.attempts);
+  const at = now();
+  const boundedResult = result.status === "blocked" || result.status === "uncertain" ? {
+    ...result,
+    retryAt: new Date(Math.max(Date.parse(at) + 1e3, Math.min(Date.parse(at) + 3e4, Date.parse(result.retryAt)))).toISOString()
+  } : result;
+  const command = {
+    kind: "delivery_receipt",
+    notificationId: notification.envelope.notificationId,
+    expectedNotificationRevision: notification.revision,
+    attemptId: identity.attemptId,
+    result: boundedResult,
+    at
+  };
+  await state.mutate(
+    notification.envelope.taskId,
+    notification.envelope.runId,
+    identity.receiptOperationId,
+    delegationInputDigest(command),
+    (fence) => ({ ...fence, ...command })
+  );
+  return readNotification(state, notification.envelope.notificationId);
+}
+export {
+  claimNotification,
+  readNotification,
+  receiptNotification
+};

package/dist/delivery/parse.d.ts

@@ -0,0 +1,4 @@
+import type { DelegationInboxAcceptance, DelegationInboxInspection } from "./types.js";
+export declare const parseDelegationInboxAcceptance: (input: unknown) => DelegationInboxAcceptance;
+export declare const parseDelegationInboxInspection: (input: unknown) => DelegationInboxInspection;
+//# sourceMappingURL=parse.d.ts.map