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

package/dist/execution/control.js

@@ -0,0 +1,231 @@
+import { AgentProviderDelegatedOperationError } from "@agen-ai/agent-runtime";
+import { parseAgentRequestResolutionFor } from "@agen-ai/agent-protocol";
+import { parseOperationId, parseRequestResolution } from "../coordinator/parse.js";
+import { delegationInputDigest } from "../shared/identity.js";
+import { failDelegation } from "../shared/operational-errors.js";
+import { assertRunDispatch, sameTarget } from "./authority.js";
+import { finishRun } from "./finish.js";
+import { dispatchIntent, operationIdentity, operationReceipt } from "./journal.js";
+import { now } from "./state.js";
+import { markRequest } from "./stream.js";
+function serializeControl(live, invoke) {
+  const control = live.controlTail.then(invoke, invoke);
+  live.controlTail = control.then(() => void 0, () => void 0);
+  return control;
+}
+async function boundedControl(state, live, invoke, cancellable = true) {
+  const controller = new AbortController();
+  let timer;
+  const signal = cancellable ? AbortSignal.any([controller.signal, live.controlAbort.signal]) : controller.signal;
+  const work = state.track(Promise.resolve().then(() => invoke(signal)), live);
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => {
+      const error = new DOMException("The managed control deadline expired.", "AbortError");
+      controller.abort(error);
+      reject(error);
+    }, state.options.limits.controlTimeoutMs);
+  });
+  try {
+    return await Promise.race([work, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+function cancelLive(state, live, reason) {
+  if (live.cancellation) return live.cancellation;
+  live.controlAbort.abort(new DOMException("The managed run's controls were canceled.", "AbortError"));
+  live.cancellation = serializeControl(live, async () => {
+    const run = await state.run(live.taskId, live.runId);
+    if (run.phase === "settled") return;
+    if (!run.cancelRequested) {
+      const identity2 = operationIdentity(live, "cancel");
+      await state.mutate(
+        live.taskId,
+        live.runId,
+        identity2.operationId,
+        identity2.inputDigest,
+        (fence) => ({ ...fence, kind: "cancel", at: now(), reason })
+      );
+    }
+    if (!live.session || run.phase === "preparing") {
+      live.lifetime.abort(new DOMException("Managed execution was canceled during preparation.", "AbortError"));
+      return;
+    }
+    const identity = operationIdentity(live, "interrupt");
+    await dispatchIntent(state, live, "interrupt", identity);
+    if (live.session.interruption.kind !== "supported") {
+      live.uncertain = "cancellation_uncertain";
+      await operationReceipt(state, live, "uncertain", identity);
+      live.lifetime.abort();
+    } else {
+      const interruption = live.session.interruption;
+      try {
+        const result = await boundedControl(state, live, (signal) => interruption.interruptTurn({
+          turnId: live.turnId,
+          reason: reason === "timeout" ? "timeout" : reason === "shutdown" ? "shutdown" : "user_requested",
+          requestedAt: now(),
+          signal
+        }), false);
+        await operationReceipt(state, live, ["accepted", "completed"].includes(result.status) ? "interruption_requested" : "uncertain", identity);
+        if (!["accepted", "completed"].includes(result.status)) live.uncertain = "cancellation_uncertain";
+      } catch {
+        live.uncertain = "cancellation_uncertain";
+        await operationReceipt(state, live, "uncertain", identity);
+      }
+    }
+    if (!live.stream) {
+      if (!live.terminal) {
+        live.uncertain = "cancellation_uncertain";
+        void finishRun(state, live, { kind: "recovery_required", reason: "cancellation_uncertain" }).catch(() => void 0);
+      }
+    } else if (!live.finishing) {
+      if (live.deadline) clearTimeout(live.deadline);
+      live.deadline = setTimeout(() => {
+        live.uncertain = "cancellation_uncertain";
+        live.lifetime.abort(new DOMException("Interruption did not settle the managed output producer.", "AbortError"));
+      }, state.options.limits.controlTimeoutMs);
+    }
+  });
+  return state.track(live.cancellation, live);
+}
+async function deliverSteering(state, live, input, digest, originPolicyRevision) {
+  const run = await state.run(live.taskId, live.runId);
+  const { task } = await state.task(live.taskId);
+  if (live.uncertain) failDelegation("recovery_required", "An earlier control operation has an uncertain outcome.");
+  if (live.cancellation || run.cancelRequested) failDelegation("unsupported_operation", "The managed turn no longer accepts steering after cancellation.");
+  if (!live.session || live.session.steering.kind !== "supported" || run.phase !== "running" || !live.stream || live.finishing) {
+    failDelegation("unsupported_operation", "This managed child does not have a steerable active turn.");
+  }
+  if (!run.appliedTarget || !sameTarget(run.appliedTarget, input.target)) failDelegation("stale_target", "Steering must preserve the exact applied target.");
+  const identity = { operationId: input.operationId, inputDigest: digest };
+  await dispatchIntent(state, live, "steer", identity);
+  const steering = live.session.steering;
+  let status;
+  try {
+    const result = await boundedControl(state, live, (signal) => {
+      if (live.uncertain || live.cancellation) failDelegation("recovery_required", "The managed turn no longer accepts new execution input.");
+      state.options.host.assertControl({ scope: live.scope, task });
+      assertRunDispatch(state, live, input.expectedPolicyRevision, originPolicyRevision);
+      return steering.steerTurn({ turnId: live.turnId, ...input.input, signal });
+    });
+    status = result.status;
+  } catch (error) {
+    status = error instanceof AgentProviderDelegatedOperationError || error instanceof DOMException && error.name === "AbortError" ? "delivery_uncertain" : "rejected";
+  }
+  if (status === "delivery_uncertain") live.uncertain = "steering_uncertain";
+  await operationReceipt(state, live, status === "delivery_uncertain" ? "uncertain" : status, identity);
+  return { status, taskId: live.taskId, runId: live.runId, operationId: input.operationId, duplicate: false };
+}
+function steerRun(state, live, input, digest, originPolicyRevision) {
+  const prior = live.pendingOperations.get(input.operationId);
+  if (prior) {
+    if (prior.digest !== digest) failDelegation("operation_conflict", "The operation identity has different in-flight input.");
+    return prior.promise.then((receipt) => ({ ...receipt, duplicate: true }));
+  }
+  const work = state.track(serializeControl(live, () => deliverSteering(state, live, input, digest, originPolicyRevision)), live);
+  live.pendingOperations.set(input.operationId, { digest, promise: work });
+  void work.finally(() => live.pendingOperations.delete(input.operationId)).catch(() => void 0);
+  return work;
+}
+function requestReceipt(live, operationId, disposition, requestState, duplicate = false) {
+  const identity = { taskId: live.taskId, runId: live.runId, operationId, duplicate };
+  if (disposition === "delivered") return { ...identity, status: "delivered" };
+  if (disposition === "rejected" && requestState) return { ...identity, status: "rejected", requestState };
+  return { ...identity, status: "delivery_uncertain" };
+}
+async function continueRequest(state, input) {
+  const operationId = parseOperationId(input.operationId);
+  const resolution = parseRequestResolution(input.resolution);
+  const pending = state.requests.get(input.handle);
+  if (!pending) failDelegation("request_unavailable", "The live host request handle is unavailable.");
+  const { live, request } = pending;
+  parseAgentRequestResolutionFor(request, resolution);
+  const identity = { operationId, inputDigest: delegationInputDigest({ kind: "request_resolution", taskId: live.taskId, runId: live.runId, requestId: request.requestId, resolution }) };
+  return serializeControl(live, async () => {
+    const [{ task }, run] = await Promise.all([state.task(live.taskId), state.run(live.taskId, live.runId)]);
+    state.options.host.assertResultAccess({ scope: live.scope, task });
+    state.options.host.assertRequestAccess({ handle: input.handle, task, run, request });
+    live.execution?.assertCurrent();
+    const existing = await state.options.store.read({ kind: "operation", parent: live.scope, operationId });
+    if (existing.kind === "operation" && existing.operation) {
+      if (existing.operation.kind !== "request_resolution" || existing.operation.inputDigest !== identity.inputDigest || existing.operation.taskId !== live.taskId || existing.operation.runId !== live.runId) {
+        failDelegation("operation_conflict", "The operation identity already has different input or ownership.");
+      }
+      return requestReceipt(live, operationId, existing.operation.disposition, existing.operation.requestState, true);
+    }
+    if (live.request !== pending || !live.stream || live.finishing || !live.turn || !live.requestHistory || live.uncertain || live.cancellation || run.phase !== "waiting" || live.execution?.signal.aborted || live.lifetime.signal.aborted) {
+      failDelegation("request_unavailable", "The exact waiting request no longer has a live executor.");
+    }
+    const history = live.requestHistory;
+    await markRequest(state, live, "resolution_intended", { ...history, state: "resolution_intended" }, identity);
+    live.request = void 0;
+    let disposition;
+    let requestState;
+    let localFailure;
+    let entered = false;
+    try {
+      const turn = live.turn;
+      const result = await boundedControl(state, live, (signal) => turn.resolveRequest({
+        resolution,
+        signal: AbortSignal.any([signal, live.lifetime.signal]),
+        onProviderExecutionStarted() {
+          state.options.host.assertRequestAccess({ handle: input.handle, task, run, request });
+          live.execution?.assertCurrent();
+          entered = true;
+        }
+      }));
+      disposition = result.status === "delivery_uncertain" ? "uncertain" : result.status;
+      if (result.status === "rejected") requestState = result.requestState;
+    } catch (error) {
+      if (error instanceof AgentProviderDelegatedOperationError || entered && error instanceof DOMException && error.name === "AbortError") {
+        disposition = "uncertain";
+      } else {
+        disposition = "rejected";
+        requestState = live.lifetime.signal.aborted || live.cancellation ? "unavailable" : "pending";
+        localFailure = { error };
+      }
+    }
+    if (disposition === "uncertain") live.uncertain = "request_executor_lost";
+    try {
+      await state.mutate(
+        live.taskId,
+        live.runId,
+        operationId,
+        identity.inputDigest,
+        (fence) => ({ ...fence, kind: "operation_receipt", disposition, at: now(), ...requestState ? { requestState } : {} })
+      );
+    } catch (error) {
+      live.uncertain = "storage_failed";
+      void finishRun(state, live, { kind: "recovery_required", reason: "storage_failed" }).catch(() => void 0);
+      throw error;
+    }
+    if (requestState === "pending" && !live.lifetime.signal.aborted && !live.cancellation) live.request = pending;
+    if (live.uncertain) void finishRun(state, live, { kind: "recovery_required", reason: live.uncertain }).catch(() => void 0);
+    if (localFailure) throw localFailure.error;
+    return requestReceipt(live, operationId, disposition, requestState);
+  });
+}
+function resolveLiveRequest(state, input) {
+  const pending = state.requests.get(input.handle);
+  if (!pending) return state.track(continueRequest(state, input));
+  const operationId = parseOperationId(input.operationId);
+  const resolution = parseRequestResolution(input.resolution);
+  parseAgentRequestResolutionFor(pending.request, resolution);
+  const digest = delegationInputDigest({ kind: "request_resolution", taskId: pending.live.taskId, runId: pending.live.runId, requestId: pending.request.requestId, resolution });
+  const prior = pending.live.pendingOperations.get(operationId);
+  if (prior && prior.digest !== digest) failDelegation("operation_conflict", "The operation identity has different in-flight input.");
+  if (prior) return state.track(prior.promise.then((receipt) => ({ ...receipt, duplicate: true })), pending.live);
+  const work = state.track(continueRequest(state, input), pending.live);
+  pending.live.pendingOperations.set(operationId, { digest, promise: work });
+  pending.live.requestResolution = work;
+  void work.finally(() => {
+    pending.live.pendingOperations.delete(operationId);
+    if (pending.live.requestResolution === work) pending.live.requestResolution = void 0;
+  }).catch(() => void 0);
+  return work;
+}
+export {
+  cancelLive,
+  resolveLiveRequest,
+  steerRun
+};

package/dist/execution/finish.d.ts

@@ -0,0 +1,6 @@
+import type { DelegationRunOutcome } from "../tasks/types.js";
+import { type CoordinatorState, type LiveRun } from "./state.js";
+export declare function settleRun(state: CoordinatorState, live: Pick<LiveRun, "taskId" | "runId">, outcome: DelegationRunOutcome): Promise<void>;
+export declare function settleQueuedRun(state: CoordinatorState, live: Pick<LiveRun, "taskId" | "runId">, outcome: DelegationRunOutcome): Promise<void>;
+export declare function finishRun(state: CoordinatorState, live: LiveRun, outcome: DelegationRunOutcome): Promise<void>;
+//# sourceMappingURL=finish.d.ts.map

package/dist/execution/finish.js

@@ -0,0 +1,49 @@
+import { delegationInputDigest, delegationSubordinateId } from "../shared/identity.js";
+import { cleanupRun } from "./cleanup.js";
+import { now } from "./state.js";
+async function settle(state, live, outcome, queuedOnly) {
+  const identity = { operationId: delegationSubordinateId(live.runId, "settle"), inputDigest: delegationInputDigest({ runId: live.runId, outcome }) };
+  await state.mutate(
+    live.taskId,
+    live.runId,
+    identity.operationId,
+    identity.inputDigest,
+    (fence, _task, run) => queuedOnly && run.phase !== "queued" ? void 0 : { ...fence, kind: "settle", outcome, at: now() }
+  );
+}
+function settleRun(state, live, outcome) {
+  return settle(state, live, outcome, false);
+}
+function settleQueuedRun(state, live, outcome) {
+  return settle(state, live, outcome, true);
+}
+function finishRun(state, live, outcome) {
+  if (live.finishing) return live.finishing;
+  live.finishing = (async () => {
+    const closed = await cleanupRun(state, live);
+    const truth = outcome.kind === "succeeded" ? {
+      kind: "succeeded",
+      result: { text: live.summary, truncated: live.truncated, references: [...live.references] }
+    } : outcome;
+    const sticky = live.uncertain && !(live.uncertain === "cancellation_uncertain" && (truth.kind === "succeeded" || truth.kind === "canceled"));
+    const final = sticky ? { kind: "recovery_required", reason: live.uncertain } : !closed ? { kind: "recovery_required", reason: "cancellation_uncertain" } : truth;
+    try {
+      await settleRun(state, live, final);
+      if (closed) {
+        if ((final.kind === "succeeded" || final.kind === "failed" || final.kind === "canceled") && live.session && live.resources?.continuation?.kind === "resume") {
+          state.continuations.set(live.taskId, { runId: live.runId, binding: live.session.binding, target: live.target });
+        } else state.continuations.delete(live.taskId);
+        state.live.delete(live.runId);
+      }
+    } finally {
+      state.changed();
+      live.schedule?.();
+    }
+  })();
+  return state.track(live.finishing);
+}
+export {
+  finishRun,
+  settleQueuedRun,
+  settleRun
+};

package/dist/execution/journal.d.ts

@@ -0,0 +1,19 @@
+import type { DelegationTargetReference } from "../catalog/types.js";
+import type { DelegationOperationDisposition, DelegationOperationKind } from "../store/types.js";
+import { type CoordinatorState, type LiveRun } from "./state.js";
+export declare function operationIdentity(live: LiveRun, kind: string): {
+    operationId: string;
+    inputDigest: string;
+};
+export declare function dispatchIntent(state: CoordinatorState, live: LiveRun, kind: Exclude<DelegationOperationKind, "admit" | "cancel">, identity?: {
+    operationId: string;
+    inputDigest: string;
+}, extra?: Readonly<{
+    appliedTarget?: DelegationTargetReference;
+    attempt?: 1 | 2;
+}>): Promise<import("../index.js").DelegationCommitReceipt | undefined>;
+export declare function operationReceipt(state: CoordinatorState, live: LiveRun, disposition: Exclude<DelegationOperationDisposition, "intent">, identity: Readonly<{
+    operationId: string;
+    inputDigest: string;
+}>): Promise<import("../index.js").DelegationCommitReceipt | undefined>;
+//# sourceMappingURL=journal.d.ts.map

package/dist/execution/journal.js

@@ -0,0 +1,28 @@
+import { delegationInputDigest, delegationSubordinateId } from "../shared/identity.js";
+import { now } from "./state.js";
+function operationIdentity(live, kind) {
+  return { operationId: delegationSubordinateId(live.runId, kind), inputDigest: delegationInputDigest({ runId: live.runId, kind }) };
+}
+async function dispatchIntent(state, live, kind, identity = operationIdentity(live, kind), extra = {}) {
+  return state.mutate(
+    live.taskId,
+    live.runId,
+    identity.operationId,
+    identity.inputDigest,
+    (fence, _task, run) => kind === "prepare" && run.phase !== "queued" ? void 0 : { ...fence, kind: "dispatch_intent", operationKind: kind, at: now(), ...extra }
+  );
+}
+async function operationReceipt(state, live, disposition, identity) {
+  return state.mutate(
+    live.taskId,
+    live.runId,
+    identity.operationId,
+    identity.inputDigest,
+    (fence) => ({ ...fence, kind: "operation_receipt", disposition, at: now() })
+  );
+}
+export {
+  dispatchIntent,
+  operationIdentity,
+  operationReceipt
+};

package/dist/execution/prepare.d.ts

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

package/dist/execution/prepare.js

@@ -0,0 +1,153 @@
+import { parseAgentConfigurationSelectionFor } from "@agen-ai/agent-protocol";
+import { isAgentProviderSessionCleanupErrorFor } from "@agen-ai/agent-runtime";
+import { delegationCanonicalJson } from "../shared/identity.js";
+import { failDelegation } from "../shared/operational-errors.js";
+import { assertRunDispatch, sameTarget } from "./authority.js";
+import { finishRun } from "./finish.js";
+import { dispatchIntent, operationIdentity, operationReceipt } from "./journal.js";
+import { consumeTurn } from "./stream.js";
+async function prepareRun(state, live, revoke) {
+  const run = await state.run(live.taskId, live.runId);
+  const { task } = await state.task(live.taskId);
+  const prepare = operationIdentity(live, "prepare");
+  const gate = () => assertRunDispatch(state, live, run.admittedPolicyRevision, run.admittedOriginPolicyRevision);
+  let preparationCompleted = false;
+  let openingInput;
+  try {
+    if (run.cancelRequested) failDelegation("recovery_required", "The run was canceled before preparation acquired execution authority.");
+    gate();
+    live.execution = await state.options.host.acquireExecution({
+      scope: live.scope,
+      task,
+      run,
+      target: live.target,
+      signal: live.lifetime.signal
+    });
+    const revoked = () => {
+      revoke();
+    };
+    live.execution.signal.addEventListener("abort", revoked, { once: true });
+    live.removeRevocation = () => live.execution?.signal.removeEventListener("abort", revoked);
+    if (live.execution.signal.aborted) revoke();
+    gate();
+    const continuation = run.previousRunId ? state.continuations.get(live.taskId) : void 0;
+    if (run.previousRunId && (!continuation || continuation.runId !== run.previousRunId)) {
+      failDelegation("unsupported_operation", "The exact previous conversation is unavailable for continuation.");
+    }
+    live.resources = await state.options.host.acquireChildResources({
+      scope: live.scope,
+      task,
+      run,
+      target: live.target,
+      ...continuation ? { continuation } : {},
+      signal: live.lifetime.signal
+    });
+    gate();
+    if (continuation && (live.resources.continuation?.kind !== "resume" || !sameTarget(continuation.target.reference, live.target.reference) && !live.resources.continuation.allowTargetChange || continuation.target.instanceId !== live.target.instanceId || continuation.target.providerKey !== live.target.providerKey)) {
+      failDelegation("unsupported_operation", "The host has not authorized this exact conversation continuation.");
+    }
+    const instance = state.options.host.registry.requireInstance(live.target.instanceId);
+    if (instance.capabilities.providerKey !== live.target.providerKey) failDelegation("stale_target", "The registered provider does not match the admitted target.");
+    const readiness = await state.options.host.registry.checkReadiness(live.target.instanceId, { signal: live.lifetime.signal });
+    if (readiness.status !== "ready") failDelegation("target_unavailable", "The selected provider is not ready.");
+    gate();
+    if (state.options.host.registry.requireInstance(live.target.instanceId) !== instance) failDelegation("target_unavailable", "The prepared provider instance is no longer registered.");
+    const context = {
+      sessionId: live.sessionId,
+      workingDirectory: live.resources.workingDirectory.path,
+      configuration: live.target.application.configuration,
+      signal: live.lifetime.signal,
+      ...live.resources.hostBinding ? { hostBinding: live.resources.hostBinding } : {}
+    };
+    if (continuation) {
+      if (instance.adapter.resumption.kind !== "supported") failDelegation("unsupported_operation", "The registered provider cannot resume this conversation.");
+      const input = { ...context, binding: continuation.binding };
+      openingInput = input;
+      live.session = await instance.adapter.resumption.resumeSession(input);
+    } else {
+      const input = { ...context, onBindingCreated: () => void 0 };
+      openingInput = input;
+      live.session = await instance.adapter.createSession(input);
+    }
+    gate();
+    const configuration = live.session.configuration;
+    let observedConfiguration;
+    if (configuration.kind === "selectable") observedConfiguration = await configuration.listConfiguration({ signal: live.lifetime.signal });
+    for (const [index, selection] of live.target.application.beforeFirstTurn.entries()) {
+      if (configuration.kind !== "selectable" || !observedConfiguration) failDelegation("unsupported_operation", "The admitted configuration is not selectable on this session.");
+      parseAgentConfigurationSelectionFor(observedConfiguration, selection);
+      const field = observedConfiguration.fields.find((entry) => entry.key === selection.key);
+      if (!field?.mutable || field.scope !== "session" || field.applicationTiming !== "immediate") {
+        failDelegation("unsupported_operation", "Managed child configuration must be immediate and local to its owned session.");
+      }
+      const identity = operationIdentity(live, `configure:${index}`);
+      await dispatchIntent(state, live, "configure", identity);
+      gate();
+      let invoked = false;
+      try {
+        const result = await configuration.applyConfigurationSelection({
+          selection,
+          signal: live.lifetime.signal,
+          onProviderExecutionStarted() {
+            gate();
+            invoked = true;
+          }
+        });
+        await operationReceipt(state, live, result.status === "completed" ? "completed" : "uncertain", identity);
+        if (result.status !== "completed") failDelegation("recovery_required", "Configuration application did not complete definitively.");
+      } catch (error) {
+        if (invoked) live.uncertain = "dispatch_uncertain";
+        else await operationReceipt(state, live, "rejected", identity);
+        throw error;
+      }
+      gate();
+      observedConfiguration = await configuration.listConfiguration({ signal: live.lifetime.signal });
+    }
+    gate();
+    const applied = await state.options.host.verifyAppliedConfiguration({
+      task,
+      run,
+      target: live.target,
+      session: live.session,
+      ...observedConfiguration ? { observedConfiguration } : {},
+      signal: live.lifetime.signal
+    });
+    if (!sameTarget(applied.target, live.target.reference) || delegationCanonicalJson(applied.configuration) !== delegationCanonicalJson(live.target.application.configuration)) {
+      failDelegation("stale_target", "The host did not attest the exact admitted configuration and source.");
+    }
+    gate();
+    await operationReceipt(state, live, "completed", prepare);
+    preparationCompleted = true;
+    await dispatchIntent(state, live, "turn", operationIdentity(live, "turn"), { appliedTarget: live.target.reference });
+    gate();
+    live.turn = live.session.startTurn({
+      turnId: live.turnId,
+      interactionMode: "default",
+      ...run.input,
+      deadlineAt: run.deadlineAt,
+      signal: live.lifetime.signal,
+      onProviderExecutionStarted() {
+        gate();
+        live.observedStart = true;
+      }
+    });
+    const stream = consumeTurn(state, live, live.turn.outputs);
+    live.stream = stream;
+    await stream;
+  } catch (error) {
+    if (openingInput && isAgentProviderSessionCleanupErrorFor(error, openingInput)) {
+      live.rejectedOpening = error;
+    }
+    if (!preparationCompleted) {
+      try {
+        await operationReceipt(state, live, live.rejectedOpening || live.uncertain ? "uncertain" : "rejected", prepare);
+      } catch {
+        live.uncertain = "storage_failed";
+      }
+    }
+    await finishRun(state, live, live.observedStart || live.rejectedOpening || live.uncertain ? { kind: "recovery_required", reason: live.uncertain ?? "dispatch_uncertain" } : { kind: "failed", error: { category: "unknown", code: "preparation_rejected", message: "The managed child could not start under its admitted authority.", recovery: { kind: "unknown" } } });
+  }
+}
+export {
+  prepareRun
+};

package/dist/execution/scheduler.d.ts

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

package/dist/execution/scheduler.js

@@ -0,0 +1,136 @@
+import { parseAgentSessionId, parseAgentTurnId } from "@agen-ai/agent-protocol";
+import { resolveDelegationPolicy } from "../policy/resolve.js";
+import { assertCompletionPolicy } from "../delivery/setup.js";
+import { createDelegationId } from "../shared/identity.js";
+import { DelegationOperationError, failDelegation } from "../shared/operational-errors.js";
+import { assertRunDispatch, readCeiling, sameTarget } from "./authority.js";
+import { cancelLive } from "./control.js";
+import { settleQueuedRun } from "./finish.js";
+import { dispatchIntent } from "./journal.js";
+import { prepareRun } from "./prepare.js";
+import { now } from "./state.js";
+async function pump(state) {
+  if (state.released) return;
+  if (state.queueTimer) {
+    clearTimeout(state.queueTimer);
+    state.queueTimer = void 0;
+  }
+  let earliest = Infinity;
+  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) {
+      if (state.closing && !state.draining || state.failed || state.released) return;
+      const expiry = Math.min(Date.parse(run.queuedStartDeadlineAt), Date.parse(run.deadlineAt));
+      if (expiry <= Date.now()) {
+        await settleQueuedRun(state, run, { kind: "failed", error: { category: "unknown", code: "queued_deadline_expired", message: "The managed task expired before its execution slot became available.", recovery: { kind: "unknown" } } });
+        continue;
+      }
+      if (run.previousRunId) {
+        const predecessor = await state.run(run.taskId, run.previousRunId);
+        if (predecessor.phase === "settled" && (predecessor.outcome?.kind === "recovery_required" || run.continuationMode === "next_turn" && (predecessor.cancelRequested || predecessor.outcome?.kind === "canceled"))) {
+          await settleQueuedRun(state, run, { kind: "failed", error: { category: "unknown", code: "continuation_rejected", message: "The previous run cannot authorize this queued automatic continuation.", recovery: { kind: "unknown" } } });
+          continue;
+        }
+        if (predecessor.phase !== "settled") {
+          earliest = Math.min(earliest, expiry);
+          continue;
+        }
+      }
+      if (state.live.size >= state.options.limits.maxActiveRuns || [...state.live.values()].some((live2) => live2.taskId === run.taskId)) {
+        earliest = Math.min(earliest, expiry);
+        continue;
+      }
+      const { task } = await state.task(run.taskId);
+      assertCompletionPolicy(state, task.completionPolicy);
+      const ceiling = await readCeiling(state, task.policyCeilingRef);
+      const snapshot = state.options.host.currentPolicy(task.parent);
+      const resolved = resolveDelegationPolicy({ catalog: snapshot.catalog, policy: snapshot.policy });
+      const target = resolved.allowedTargets.find((candidate) => sameTarget(candidate.reference, run.admittedTarget));
+      if (!target || Date.parse(run.queuedStartDeadlineAt) <= Date.now() || Date.parse(run.deadlineAt) <= Date.now()) {
+        await settleQueuedRun(state, run, { kind: "failed", error: { category: "unknown", code: "admission_expired", message: "Current authority or the queued start deadline no longer permits this task.", recovery: { kind: "unknown" } } });
+        continue;
+      }
+      const live = {
+        taskId: run.taskId,
+        runId: run.runId,
+        scope: task.parent,
+        target,
+        ceiling,
+        lifetime: new AbortController(),
+        controlAbort: new AbortController(),
+        sessionId: parseAgentSessionId(createDelegationId()),
+        turnId: parseAgentTurnId(createDelegationId()),
+        controls: /* @__PURE__ */ new Set(),
+        pendingOperations: /* @__PURE__ */ new Map(),
+        observedStart: false,
+        recordedStart: false,
+        controlTail: Promise.resolve(),
+        summary: "",
+        truncated: false,
+        references: [],
+        runtimeCleanupAttempts: 0,
+        resourceReleaseAttempts: 0,
+        executionReleaseAttempts: 0,
+        runtimeClosed: false,
+        resourcesReleased: false,
+        executionReleased: false,
+        schedule: () => schedule(state)
+      };
+      try {
+        assertRunDispatch(state, live, run.admittedPolicyRevision, run.admittedOriginPolicyRevision);
+        if (!await dispatchIntent(state, live, "prepare")) continue;
+      } catch (error) {
+        await settleQueuedRun(state, run, { kind: "failed", error: { category: "unknown", code: error instanceof DelegationOperationError ? error.code : "admission_rejected", message: "The queued admission is no longer current.", recovery: { kind: "unknown" } } });
+        continue;
+      }
+      state.live.set(live.runId, live);
+      const revoke = () => {
+        void cancelLive(state, live, "authority_revoked").catch(() => void 0);
+      };
+      live.deadline = setTimeout(() => {
+        void cancelLive(state, live, "timeout").catch(() => void 0);
+      }, Math.max(1, Date.parse(run.deadlineAt) - Date.now()));
+      live.ready = prepareRun(state, live, revoke);
+      state.track(live.ready);
+      void live.ready.catch(() => state.fail());
+    }
+    cursor = page.page.cursor;
+  } while (cursor && (!state.closing || state.draining) && !state.released);
+  if (Number.isFinite(earliest) && (!state.closing || state.draining) && !state.failed && !state.released) {
+    state.queueTimer = setTimeout(() => {
+      state.queueTimer = void 0;
+      schedule(state);
+    }, Math.max(1, earliest - Date.now()));
+  }
+}
+function schedule(state) {
+  if (state.closing && !state.draining || state.failed || state.released) return;
+  if (state.pump) {
+    state.schedulePending = true;
+    return;
+  }
+  const work = Promise.resolve().then(() => pump(state)).catch(() => state.fail()).finally(() => {
+    state.pump = void 0;
+    state.changed();
+    if (state.schedulePending) {
+      state.schedulePending = false;
+      schedule(state);
+    }
+  });
+  state.pump = work;
+  state.track(work);
+}
+function assertAccepting(state) {
+  if (state.closing || state.failed || state.released) failDelegation("owner_lost", "The coordinator no longer admits new managed work.");
+}
+export {
+  assertAccepting,
+  schedule
+};