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

package/dist/coordinator/admission.js

@@ -0,0 +1,189 @@
+import { admittedTarget, effectiveChoices, readCeiling, sameTarget } from "../execution/authority.js";
+import { assertCompletionPolicy } from "../delivery/setup.js";
+import { steerRun } from "../execution/control.js";
+import { assertAccepting, schedule } from "../execution/scheduler.js";
+import { sameScopeIdentity } from "../execution/state.js";
+import { createDelegationId, delegationInputDigest } from "../shared/identity.js";
+import { failDelegation } from "../shared/operational-errors.js";
+import { parseSendTaskInput, parseSpawnTaskInput } from "./parse.js";
+async function priorOperation(state, binding, operationId, digest, kind) {
+  const read = await state.options.store.read({ kind: "operation", parent: binding.scope, operationId });
+  if (read.kind !== "operation" || !read.operation) return void 0;
+  if (read.operation.inputDigest !== digest || read.operation.kind !== kind) failDelegation("operation_conflict", "The operation identity already has different retained input.");
+  const { task } = await state.task(read.operation.taskId);
+  state.options.host.assertResultAccess({ scope: binding.scope, task });
+  return read.operation;
+}
+async function admissionReceipt(state, operation, duplicate) {
+  const run = await state.run(operation.taskId, operation.runId);
+  return {
+    storeId: state.options.store.storeId,
+    operationId: operation.operationId,
+    taskId: operation.taskId,
+    runId: operation.runId,
+    target: run.admittedTarget,
+    revision: operation.receipt.taskRevision,
+    status: "queued",
+    duplicate
+  };
+}
+function createAdmissionClient(state, binding) {
+  return {
+    async spawn(raw) {
+      const input = parseSpawnTaskInput(raw, state.options.limits);
+      state.options.host.assertResultAccess({ scope: binding.scope });
+      const normalized = {
+        kind: "spawn",
+        target: input.target,
+        expectedPolicyRevision: input.expectedPolicyRevision,
+        input: input.input,
+        completionPolicy: input.completionPolicy ?? "collect",
+        timeoutMs: input.timeoutMs ?? state.options.limits.runTimeoutMs
+      };
+      const digest = delegationInputDigest(normalized);
+      const receipt = await state.gate(async () => {
+        const prior = await priorOperation(state, binding, input.operationId, digest, "admit");
+        if (prior) return admissionReceipt(state, prior, true);
+        assertAccepting(state);
+        assertCompletionPolicy(state, normalized.completionPolicy);
+        const choices = await effectiveChoices(state, binding);
+        const target = admittedTarget(choices, input.target, input.expectedPolicyRevision);
+        const depth = binding.depth ?? 1;
+        if (depth > state.options.limits.maxDepth) failDelegation("capacity_exceeded", "The managed descendant depth is exhausted.");
+        const created = Date.now();
+        const taskId = createDelegationId();
+        const runId = createDelegationId();
+        const commit = await state.commit({
+          owner: state.owner,
+          operationId: input.operationId,
+          inputDigest: digest,
+          taskId,
+          expectedTaskRevision: 0,
+          kind: "admit",
+          admission: {
+            parent: binding.scope,
+            ...binding.ancestor ? { ancestorTaskId: binding.ancestor.taskId } : {},
+            depth,
+            policyCeiling: choices.ceiling,
+            completionPolicy: normalized.completionPolicy,
+            runId,
+            target: target.reference,
+            policyRevision: choices.resolved.policyRevision,
+            originPolicyRevision: choices.originPolicyRevision,
+            input: input.input,
+            createdAt: new Date(created).toISOString(),
+            deadlineAt: new Date(created + normalized.timeoutMs).toISOString(),
+            queuedStartDeadlineAt: new Date(created + state.options.limits.queuedStartTimeoutMs).toISOString()
+          }
+        });
+        return {
+          storeId: state.options.store.storeId,
+          operationId: input.operationId,
+          taskId,
+          runId,
+          target: target.reference,
+          revision: commit.taskRevision,
+          status: "queued",
+          duplicate: false
+        };
+      });
+      schedule(state);
+      return receipt;
+    },
+    async send(raw) {
+      const input = parseSendTaskInput(raw, state.options.limits);
+      const { task } = await state.task(input.taskId);
+      if (!sameScopeIdentity(binding.scope, task.parent)) failDelegation("request_unavailable", "The managed task does not belong to this parent scope.");
+      state.options.host.assertResultAccess({ scope: binding.scope, task });
+      const { operationId: _operationId, ...semantic } = input;
+      const digest = delegationInputDigest({ kind: "send", ...semantic });
+      const prior = await priorOperation(state, binding, input.operationId, digest, input.mode === "steer" ? "steer" : "admit");
+      if (prior) {
+        if (prior.kind === "admit") return { status: "queued", admission: await admissionReceipt(state, prior, true), duplicate: true };
+        const pending = state.live.get(prior.runId)?.pendingOperations.get(input.operationId);
+        if (pending) return pending.promise.then((receipt2) => ({ ...receipt2, duplicate: true }));
+        return {
+          status: prior.disposition === "delivered" ? "delivered" : prior.disposition === "rejected" ? "rejected" : "delivery_uncertain",
+          taskId: prior.taskId,
+          runId: prior.runId,
+          operationId: input.operationId,
+          duplicate: true
+        };
+      }
+      assertAccepting(state);
+      assertCompletionPolicy(state, task.completionPolicy);
+      state.options.host.assertControl({ scope: binding.scope, task });
+      if (task.state === "recovery_required" || task.state === "retired") failDelegation("recovery_required", "This managed task requires explicit recovery retirement.");
+      const choices = await effectiveChoices(state, binding);
+      const ceiling = await readCeiling(state, task.policyCeilingRef);
+      const target = admittedTarget({ ...choices, targets: choices.targets.filter((entry) => ceiling.targets.some((ref) => sameTarget(ref, entry.reference))) }, input.target, input.expectedPolicyRevision);
+      if (input.mode === "steer") {
+        const live = [...state.live.values()].find((entry) => entry.taskId === task.taskId && entry.stream);
+        if (!live) failDelegation("unsupported_operation", "This managed child has no active steerable turn.");
+        return steerRun(state, live, input, digest, choices.originPolicyRevision);
+      }
+      const continuationMode = input.mode;
+      const receipt = await state.gate(async () => {
+        const retry = await priorOperation(state, binding, input.operationId, digest, "admit");
+        if (retry) return admissionReceipt(state, retry, true);
+        const current = await state.task(task.taskId);
+        const previous = await state.run(task.taskId, current.task.latestRunId);
+        if (current.runs.items.some((run) => run.phase === "queued")) failDelegation("capacity_exceeded", "This managed task already has its queued next turn.");
+        const live = state.live.get(previous.runId);
+        const continuation = state.continuations.get(task.taskId);
+        if (input.mode === "next_turn") {
+          if (previous.phase !== "running" || !live?.resources?.continuation || !live.session) failDelegation("unsupported_operation", "A queued next turn requires an active safely resumable conversation.");
+          if (!sameTarget(live.target.reference, target.reference) && !live.resources.continuation.allowTargetChange) failDelegation("unsupported_operation", "This conversation does not authorize a target change.");
+        } else if (previous.phase !== "settled" || !previous.outcome || previous.outcome.kind === "recovery_required" || !continuation) {
+          failDelegation("unsupported_operation", "A follow-up requires a definitive settled conversation with exact resume authority.");
+        }
+        const previousTarget = live?.target ?? continuation?.target;
+        if (!previousTarget || previousTarget.instanceId !== target.instanceId || previousTarget.providerKey !== target.providerKey) failDelegation("unsupported_operation", "A continuation must retain its exact provider instance.");
+        const created = Date.now();
+        const runId = createDelegationId();
+        const commit = await state.commit({
+          owner: state.owner,
+          operationId: input.operationId,
+          inputDigest: digest,
+          taskId: task.taskId,
+          expectedTaskRevision: current.task.revision,
+          runId: previous.runId,
+          expectedRunRevision: previous.revision,
+          kind: "admit",
+          admission: {
+            parent: task.parent,
+            ...task.ancestorTaskId ? { ancestorTaskId: task.ancestorTaskId } : {},
+            depth: task.depth,
+            policyCeiling: ceiling,
+            completionPolicy: task.completionPolicy,
+            runId,
+            previousRunId: previous.runId,
+            continuationMode,
+            target: target.reference,
+            policyRevision: choices.resolved.policyRevision,
+            originPolicyRevision: choices.originPolicyRevision,
+            input: input.input,
+            createdAt: new Date(created).toISOString(),
+            deadlineAt: new Date(created + state.options.limits.runTimeoutMs).toISOString(),
+            queuedStartDeadlineAt: new Date(created + state.options.limits.queuedStartTimeoutMs).toISOString()
+          }
+        });
+        return {
+          storeId: state.options.store.storeId,
+          operationId: input.operationId,
+          taskId: task.taskId,
+          runId,
+          target: target.reference,
+          revision: commit.taskRevision,
+          status: "queued",
+          duplicate: false
+        };
+      });
+      schedule(state);
+      return { status: "queued", admission: receipt, duplicate: receipt.duplicate };
+    }
+  };
+}
+export {
+  createAdmissionClient
+};

package/dist/coordinator/cancel.d.ts

@@ -0,0 +1,7 @@
+import { type CoordinatorState, type ParentBinding } from "../execution/state.js";
+import type { DelegationCancelReceipt } from "./types.js";
+export declare function createCancelClient(state: CoordinatorState, binding: ParentBinding): (input: Readonly<{
+    operationId: string;
+    taskId: string;
+}>) => Promise<DelegationCancelReceipt>;
+//# sourceMappingURL=cancel.d.ts.map

package/dist/coordinator/cancel.js

@@ -0,0 +1,111 @@
+import { cancelLive } from "../execution/control.js";
+import { schedule } from "../execution/scheduler.js";
+import { sameScopeIdentity, now } from "../execution/state.js";
+import { delegationInputDigest, delegationSubordinateId } from "../shared/identity.js";
+import { failDelegation } from "../shared/operational-errors.js";
+import { parseOperationId, parseTaskId } from "./parse.js";
+async function canonicalCancel(state, taskId, runId) {
+  let cursor;
+  do {
+    const page = await state.options.store.read({ kind: "operations", taskId, runId, limit: state.options.limits.maxPageRecords, ...cursor ? { cursor } : {} });
+    if (page.kind !== "operations") failDelegation("store_failed", "The operation page does not match its query.");
+    const cancel = page.page.items.find((operation) => operation.kind === "cancel");
+    if (cancel) return cancel;
+    cursor = page.page.cursor;
+  } while (cursor);
+  return void 0;
+}
+async function includesRun(state, operation, rootOrdinal, run) {
+  if (run.ordinal < rootOrdinal) return false;
+  if (run.ordinal === rootOrdinal) return true;
+  const admission = await state.options.store.read({ kind: "operation", parent: operation.parent, operationId: run.admissionOperationId });
+  if (admission.kind !== "operation" || !admission.operation || admission.operation.kind !== "admit") failDelegation("store_failed", "The cancellation admission history is unavailable.");
+  return admission.operation.receipt.taskRevision <= operation.receipt.taskRevision;
+}
+async function retainedReceipt(state, operation, duplicate) {
+  const root = await state.run(operation.taskId, operation.runId);
+  let status = "confirmed";
+  let cursor;
+  do {
+    const page = await state.options.store.read({ kind: "task", taskId: operation.taskId, limit: state.options.limits.maxPageRecords, ...cursor ? { cursor } : {} });
+    if (page.kind !== "task" || !page.view) failDelegation("store_failed", "The cancellation task history is unavailable.");
+    for (const run of page.view.runs.items) {
+      if (!await includesRun(state, operation, root.ordinal, run)) continue;
+      if (run.outcome?.kind === "recovery_required") status = "recovery_required";
+      else if (run.phase !== "settled" && status !== "recovery_required") status = "requested";
+    }
+    cursor = page.view.runs.cursor;
+  } while (cursor);
+  return { status, operationId: operation.operationId, taskId: operation.taskId, duplicate };
+}
+function createCancelClient(state, binding) {
+  return async (input) => {
+    const operationId = parseOperationId(input.operationId);
+    const taskId = parseTaskId(input.taskId);
+    const digest = delegationInputDigest({ kind: "cancel", taskId });
+    const captured = await state.gate(async () => {
+      const first = await state.task(taskId);
+      if (!sameScopeIdentity(binding.scope, first.task.parent)) failDelegation("request_unavailable", "The managed task does not belong to this parent scope.");
+      state.options.host.assertResultAccess({ scope: binding.scope, task: first.task });
+      state.options.host.assertControl({ scope: binding.scope, task: first.task });
+      const liveRuns = /* @__PURE__ */ new Set();
+      const prior = await state.options.store.read({ kind: "operation", parent: binding.scope, operationId });
+      let canonical;
+      if (prior.kind === "operation" && prior.operation) {
+        if (prior.operation.kind !== "cancel" || prior.operation.inputDigest !== digest || prior.operation.taskId !== taskId) failDelegation("operation_conflict", "The operation identity already has different retained input.");
+        canonical = prior.operation;
+      }
+      let rootOrdinal = canonical ? (await state.run(taskId, canonical.runId)).ordinal : 0;
+      let duplicate = canonical !== void 0;
+      let cursor;
+      do {
+        const page = cursor === void 0 ? first : await state.options.store.read({ kind: "task", taskId, cursor, limit: state.options.limits.maxPageRecords }).then((read) => {
+          if (read.kind !== "task" || !read.view) return failDelegation("request_unavailable", "The managed task is unavailable.");
+          return read.view;
+        });
+        state.options.host.assertControl({ scope: binding.scope, task: page.task });
+        for (const run of page.runs.items) {
+          if (canonical) {
+            if (!await includesRun(state, canonical, rootOrdinal, run)) continue;
+          } else if (run.phase === "settled" && (page.task.state === "active" || run.runId !== page.task.latestRunId)) continue;
+          const existing = await canonicalCancel(state, taskId, run.runId);
+          if (existing && !canonical) failDelegation("operation_conflict", `Cancellation is already recorded; retry operationId ${existing.operationId}.`);
+          if (!existing) {
+            const id = canonical ? delegationSubordinateId(run.runId, `cancel:${canonical.operationId}`) : operationId;
+            const [{ task }, current] = await Promise.all([state.task(taskId), state.run(taskId, run.runId)]);
+            const receipt = await state.commit({
+              owner: state.owner,
+              operationId: id,
+              inputDigest: digest,
+              taskId,
+              expectedTaskRevision: task.revision,
+              runId: run.runId,
+              expectedRunRevision: current.revision,
+              kind: "cancel",
+              at: now(),
+              reason: "user_requested"
+            });
+            if (!canonical) {
+              const recorded = await state.options.store.read({ kind: "operation", parent: binding.scope, operationId: receipt.operationId ?? id });
+              if (recorded.kind !== "operation" || !recorded.operation) failDelegation("store_failed", "The canonical cancellation receipt is unavailable.");
+              canonical = recorded.operation;
+              rootOrdinal = run.ordinal;
+            }
+            duplicate ||= receipt.duplicate;
+          }
+          const live = state.live.get(run.runId);
+          if (live) liveRuns.add(live);
+        }
+        cursor = page.runs.cursor;
+      } while (cursor);
+      if (!canonical) failDelegation("store_failed", "The canonical cancellation receipt is unavailable.");
+      return { operation: canonical, duplicate, liveRuns };
+    });
+    await Promise.all([...captured.liveRuns].map((live) => cancelLive(state, live, "user_requested")));
+    schedule(state);
+    return retainedReceipt(state, captured.operation, captured.duplicate);
+  };
+}
+export {
+  createCancelClient
+};

package/dist/coordinator/create.d.ts

@@ -0,0 +1,3 @@
+import type { CreateDelegationCoordinatorOptions, DelegationCoordinator } from "./types.js";
+export declare function createDelegationCoordinator(options: CreateDelegationCoordinatorOptions): Promise<DelegationCoordinator>;
+//# sourceMappingURL=create.d.ts.map

package/dist/coordinator/create.js

@@ -0,0 +1,87 @@
+import { bindingCeiling } from "../execution/authority.js";
+import { assertRetainedDeliverySetup, validateDeliverySetup } from "../delivery/setup.js";
+import { installDeliveryScheduler } from "../delivery/scheduler.js";
+import { recoverNotificationClaims } from "../delivery/recovery.js";
+import { cancelLive, resolveLiveRequest } from "../execution/control.js";
+import { CoordinatorState, now } from "../execution/state.js";
+import { schedule } from "../execution/scheduler.js";
+import { delegationInputDigest } from "../shared/identity.js";
+import { parseDelegationLimits } from "../shared/limits.js";
+import { failDelegation } from "../shared/operational-errors.js";
+import { parseDelegationParentScope } from "../tasks/parse.js";
+import { createAdmissionClient } from "./admission.js";
+import { createCancelClient } from "./cancel.js";
+import { parseOperationId, parseTaskId } from "./parse.js";
+import { createReadClient } from "./read.js";
+import { recoverRuns } from "./recovery.js";
+import { shutdown } from "./shutdown.js";
+async function createDelegationCoordinator(options) {
+  const limits = parseDelegationLimits(options.limits);
+  if (options.store.contractVersion !== 3 || delegationInputDigest(limits) !== delegationInputDigest(options.store.limits)) {
+    failDelegation("store_failed", "The coordinator requires the exact store contract and limits.");
+  }
+  validateDeliverySetup(options);
+  const owner = await options.store.acquireOwner();
+  const state = new CoordinatorState({ ...options, limits }, owner);
+  state.onFailure = () => {
+    for (const live of state.live.values()) {
+      live.uncertain = "storage_failed";
+      live.lifetime.abort(new DOMException("Managed storage ownership failed.", "AbortError"));
+      void cancelLive(state, live, "storage_failed").catch(() => void 0);
+    }
+  };
+  try {
+    await assertRetainedDeliverySetup(state);
+    let cursor;
+    do {
+      cursor = (await recoverRuns(state, limits.maxPageRecords, cursor, false)).cursor;
+    } while (cursor);
+    await recoverNotificationClaims(state);
+  } catch (error) {
+    await options.store.releaseOwner(owner);
+    throw error;
+  }
+  schedule(state);
+  installDeliveryScheduler(state);
+  state.wakeDelivery?.();
+  return Object.freeze({
+    async bindParent(input) {
+      const scope = parseDelegationParentScope(input.scope);
+      options.host.assertResultAccess({ scope });
+      const initial = { scope, ...input.ancestor ? { ancestor: { taskId: parseTaskId(input.ancestor.taskId), runId: parseTaskId(input.ancestor.runId) } } : {} };
+      const ceiling = await bindingCeiling(state, initial);
+      const depth = initial.ancestor ? (await state.task(initial.ancestor.taskId)).task.depth + 1 : 1;
+      const binding = { ...initial, ...ceiling ? { ceiling } : {}, depth };
+      return Object.freeze({ ...createReadClient(state, binding), ...createAdmissionClient(state, binding), cancel: createCancelClient(state, binding) });
+    },
+    resolveRequest: (input) => resolveLiveRequest(state, input),
+    recover: (input) => recoverRuns(state, input.limit, input.cursor),
+    async retireRecoveryTask(input) {
+      const operationId = parseOperationId(input.operationId);
+      const taskId = parseTaskId(input.taskId);
+      if (typeof input.reason !== "string" || input.reason.length < 1 || input.reason.length > 512) failDelegation("capacity_exceeded", "Recovery retirement requires a bounded reason.");
+      const { task } = await state.task(taskId);
+      options.host.assertResultAccess({ scope: task.parent, task });
+      options.host.assertControl({ scope: task.parent, task });
+      if ([...state.live.values()].some((live) => live.taskId === taskId)) failDelegation("recovery_required", "Retained execution resources must quiesce before retirement.");
+      await state.gate(async () => {
+        const current = await state.task(taskId);
+        await state.commit({
+          owner,
+          operationId,
+          inputDigest: delegationInputDigest({ kind: "retire_recovery", taskId, reason: input.reason }),
+          taskId,
+          expectedTaskRevision: current.task.revision,
+          kind: "retire_recovery",
+          reason: input.reason,
+          at: now()
+        });
+      });
+      return state.task(taskId);
+    },
+    dispose: (input) => shutdown(state, input)
+  });
+}
+export {
+  createDelegationCoordinator
+};

package/dist/coordinator/parse.d.ts

@@ -0,0 +1,11 @@
+import type { AgentRequestResolution } from "@agen-ai/agent-protocol";
+import { z } from "zod/v4";
+import type { DelegationLimits } from "../shared/limits.js";
+import type { DelegationSendTaskInput, DelegationSpawnTaskInput } from "./types.js";
+export declare function parseCoordinatorInput<Value>(schema: z.ZodType<Value>, input: unknown): Value;
+export declare function parseSpawnTaskInput(input: unknown, limits: DelegationLimits): DelegationSpawnTaskInput;
+export declare function parseSendTaskInput(input: unknown, limits: DelegationLimits): DelegationSendTaskInput;
+export declare const parseOperationId: (input: unknown) => string;
+export declare const parseTaskId: (input: unknown) => string;
+export declare const parseRequestResolution: (input: unknown) => AgentRequestResolution;
+//# sourceMappingURL=parse.d.ts.map

package/dist/coordinator/parse.js

@@ -0,0 +1,60 @@
+import { AgentRequestResolutionSchema, AgentTurnInputContentSchema } from "@agen-ai/agent-protocol/zod";
+import { z } from "zod/v4";
+import { copyBoundedDelegationData } from "../shared/bounds.js";
+import { delegationSchemaError } from "../shared/errors.js";
+import { delegationDataBytes } from "../shared/identity.js";
+import { failDelegation } from "../shared/operational-errors.js";
+import { CompletionPolicySchema, TargetReferenceSchema } from "../tasks/schemas.js";
+const operation = z.uuid();
+const revision = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+const timeout = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+const spawn = z.strictObject({
+  operationId: operation,
+  target: TargetReferenceSchema,
+  expectedPolicyRevision: revision,
+  input: AgentTurnInputContentSchema,
+  completionPolicy: CompletionPolicySchema.optional(),
+  timeoutMs: timeout.optional()
+});
+const send = z.strictObject({
+  operationId: operation,
+  taskId: z.uuid(),
+  mode: z.enum(["steer", "next_turn", "follow_up"]),
+  input: AgentTurnInputContentSchema,
+  target: TargetReferenceSchema,
+  expectedPolicyRevision: revision
+});
+function parseCoordinatorInput(schema, input) {
+  const captured = copyBoundedDelegationData(input);
+  const parsed = schema.safeParse(captured);
+  if (!parsed.success) return delegationSchemaError(parsed.error, captured);
+  return parsed.data;
+}
+function inputLimit(input, limits) {
+  const characters = input.parts.reduce((count, part) => count + (part.type === "text" ? part.text.length : 0), input.summary?.length ?? 0);
+  if (delegationDataBytes(input) > limits.maxInputBytes || characters > limits.maxInputTextCharacters) {
+    failDelegation("capacity_exceeded", "Managed task input exceeds its configured content limit.");
+  }
+}
+function parseSpawnTaskInput(input, limits) {
+  const parsed = parseCoordinatorInput(spawn, input);
+  inputLimit(parsed.input, limits);
+  if (parsed.timeoutMs !== void 0 && parsed.timeoutMs > limits.runTimeoutMs) failDelegation("capacity_exceeded", "Task timeout exceeds the configured run deadline.");
+  return parsed;
+}
+function parseSendTaskInput(input, limits) {
+  const parsed = parseCoordinatorInput(send, input);
+  inputLimit(parsed.input, limits);
+  return parsed;
+}
+const parseOperationId = (input) => parseCoordinatorInput(operation, input);
+const parseTaskId = (input) => parseCoordinatorInput(z.uuid(), input);
+const parseRequestResolution = (input) => parseCoordinatorInput(AgentRequestResolutionSchema, input);
+export {
+  parseCoordinatorInput,
+  parseOperationId,
+  parseRequestResolution,
+  parseSendTaskInput,
+  parseSpawnTaskInput,
+  parseTaskId
+};

package/dist/coordinator/read.d.ts

@@ -0,0 +1,4 @@
+import { type CoordinatorState, type ParentBinding } from "../execution/state.js";
+import type { DelegationClient } from "./types.js";
+export declare function createReadClient(state: CoordinatorState, binding: ParentBinding): Pick<DelegationClient, "bindingSnapshot" | "targets" | "inspect" | "observe" | "wait">;
+//# sourceMappingURL=read.d.ts.map