Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

29.5 KB
Raw Blame
import { LOOP_ICON_ERROR, validLoopIcon } from "../../loops/loop-store.ts";
import { boundLoopCron } from "../../loops/authority.ts";
import { unattendedGrantRefusal } from "../../cron/authority.ts";
import type { AdvisoryLock } from "../../persistence/advisory-lock.ts";
import type { Loop, LoopState, LoopTriageConfig } from "../../types.ts";
import { scopeId, type ScopeId } from "../../types.ts";
import type { CapabilityClaims } from "../../auth/capability-token.ts";
import type { LoopStore, CreateLoopInput, LoopPatch } from "../../loops/loop-store.ts";
import { DECISION_LEASE_MS, type LoopItemLedger } from "../../loops/item-ledger.ts";
import type { LoopOutputStore } from "../../loops/output-store.ts";
import type { ShipGrantStore } from "../../loops/ship-grant-store.ts";
import type { LoopFireService } from "../../loops/loop-fire.ts";
import { collectVitals } from "../../loops/governor.ts";
import { buildShipGrant } from "../../loops/ship-gate.ts";
import { agentSourcePayload, consolidates, sortLedgerItems } from "../../loops/ledger-view.ts";
import { settleGroup } from "../../loops/triage.ts";
import type { CronStore } from "../../cron/cron-store.ts";
import { DEFAULT_CRON_TIMEZONE, userScheduleFromBody, validateUserSchedule } from "../../cron/schedule.ts";
import type { ScopedConfigStore } from "../../resolution/config-store.ts";
import { errMessage, swallow } from "../../util/errors.ts";
import { sendJson } from "../http.ts";
import { isObj, resolveCapabilityDestination } from "./shared.ts";
import { withActor, type ApiCtx, type Route } from "./route.ts";

export interface LoopServiceDeps {
  lock?: AdvisoryLock;
  store: LoopStore;
  items: LoopItemLedger;
  outputs: LoopOutputStore;
  grants: ShipGrantStore;
  fire?: LoopFireService;
  crons?: CronStore;
  config: ScopedConfigStore;
}

export function loopDeps(ctx: ApiCtx): LoopServiceDeps | null {
  return ctx.deps.loops ?? null;
}

interface ActingPrincipal {
  actorId: string;
  scopeId?: ScopeId;
  capability?: CapabilityClaims;
  liveHuman: boolean;
}

export function actingPrincipal(ctx: ApiCtx): ActingPrincipal | null {
  if (ctx.capability) {
    return {
      actorId: ctx.capability.actorId,
      scopeId: ctx.capability.scopeId as ScopeId,
      capability: ctx.capability,
      liveHuman: ctx.actor?.p !== undefined || ctx.capability.liveActor === true,
    };
  }
  if (ctx.actor?.p) return { actorId: ctx.actor.p, liveHuman: true };
  const principalId = (ctx.url.searchParams.get("principalId") ?? "").trim();
  if (principalId) return { actorId: principalId, liveHuman: false };
  sendJson(ctx.res, 403, { error: "forbidden", message: "loops need an agent capability or a principalId" });
  return null;
}

function requireLiveHuman(ctx: ApiCtx, acting: ActingPrincipal): boolean {
  if (acting.liveHuman) return true;
  sendJson(ctx.res, 403, { error: "human_required", message: "this action requires a live human actor" });
  return false;
}

export async function canAdministerLoop(ctx: ApiCtx, loop: Loop, acting: ActingPrincipal): Promise<boolean> {
  const { app } = ctx;
  if (await app.membershipControlsScope(loop.ownerScopeId)) {
    return app.managesScope(acting.actorId, loop.ownerScopeId);
  }
  if (await app.samePerson(loop.owner, acting.actorId)) return true;
  return app.managesScope(acting.actorId, loop.ownerScopeId);
}

export async function loadAdministrable(
  ctx: ApiCtx,
): Promise<{ deps: LoopServiceDeps; loop: Loop; acting: ActingPrincipal } | null> {
  const deps = loopDeps(ctx);
  if (!deps) {
    sendJson(ctx.res, 404, { error: "not_found", message: "loops are not wired on this deployment" });
    return null;
  }
  const acting = actingPrincipal(ctx);
  if (!acting) return null;
  const loop = await deps.store.get(ctx.params.id ?? "");
  if (!loop) {
    sendJson(ctx.res, 404, { error: "not_found", message: "no such loop" });
    return null;
  }
  if (!(await canAdministerLoop(ctx, loop, acting))) {
    sendJson(ctx.res, 403, { error: "forbidden", message: "you may not administer this loop" });
    return null;
  }
  return { deps, loop, acting };
}

export async function requireLoopAuthority(ctx: ApiCtx, deps: LoopServiceDeps, loop: Loop): Promise<boolean> {
  let cron;
  try {
    cron = await boundLoopCron(loop, deps.crons);
  } catch (e) {
    sendJson(ctx.res, 409, { error: "authority_mismatch", message: errMessage(e) });
    return false;
  }
  if (!cron?.unattendedGrants?.length) return true;
  const principal = ctx.capability ?? (ctx.actor?.p ? { actorId: ctx.actor.p, liveActor: true } : undefined);
  const refusal = principal
    ? await unattendedGrantRefusal(ctx.app, ctx.deps.admin, cron, principal)
    : { message: "a privileged loop requires a live turn started by its owner" };
  if (!refusal) return true;
  sendJson(ctx.res, 403, { error: "forbidden", message: refusal.message });
  return false;
}

const GATES = new Set(["auto", "hold"]);

function shipActionsFromBody(value: unknown): Loop["shipActions"] | null {
  if (value === undefined) return [];
  if (!Array.isArray(value)) return null;
  const out: Loop["shipActions"] = [];
  for (const entry of value) {
    if (!isObj(entry) || typeof entry.action !== "string" || !entry.action.trim()) return null;
    const gate = entry.gate ?? "hold";
    if (typeof gate !== "string" || !GATES.has(gate)) return null;
    out.push({ action: entry.action.trim(), gate: gate as "auto" | "hold" });
  }
  return out;
}

type NumericBody<T> = { value?: T; invalidField?: string };

function governorFromBody(value: unknown): NumericBody<Loop["governor"]> {
  if (value === undefined) return {};
  if (!isObj(value)) return { invalidField: "governor" };
  const counts = ["maxConsecutiveFailedFires", "returnRateMinDecisions", "maxQueueDepth"] as const;
  const governor: NonNullable<Loop["governor"]> = {};
  for (const key of counts) {
    const raw = value[key];
    if (raw === undefined) continue;
    if (typeof raw !== "number" || !Number.isFinite(raw) || !Number.isInteger(raw) || raw < 1)
      return { invalidField: key };
    governor[key] = raw;
  }
  for (const key of ["maxQueueAgeMs", "staleFireMs"] as const) {
    const raw = value[key];
    if (raw === undefined) continue;
    if (typeof raw !== "number" || !Number.isFinite(raw) || !Number.isInteger(raw) || raw < 1)
      return { invalidField: key };
    governor[key] = raw;
  }
  const maxReturnRate = value.maxReturnRate;
  if (maxReturnRate !== undefined) {
    if (typeof maxReturnRate !== "number" || !Number.isFinite(maxReturnRate) || maxReturnRate <= 0 || maxReturnRate > 1)
      return { invalidField: "maxReturnRate" };
    governor.maxReturnRate = maxReturnRate;
  }
  return { value: governor };
}

function capsFromBody(value: unknown): NumericBody<Loop["caps"]> {
  if (value === undefined) return {};
  if (!isObj(value)) return { invalidField: "caps" };
  const numbers = ["maxItemsPerFire", "maxConcurrentItems", "maxOpenOutputs", "maxItemAttempts"] as const;
  const caps: NonNullable<Loop["caps"]> = {};
  for (const key of numbers) {
    const raw = value[key];
    if (raw === undefined) continue;
    if (typeof raw !== "number" || !Number.isFinite(raw) || !Number.isInteger(raw) || raw < 1)
      return { invalidField: key };
    caps[key] = raw;
  }
  return { value: caps };
}

const TRIAGE_INSTRUCTIONS_MAX = 4000;

function triageFromBody(value: unknown): LoopTriageConfig | null | undefined {
  if (value === undefined) return undefined;
  if (!isObj(value)) return null;
  const config: LoopTriageConfig = {};
  for (const key of ["prioritize", "consolidate"] as const) {
    const raw = value[key];
    if (raw === undefined) continue;
    if (!isObj(raw) || typeof raw.enabled !== "boolean") return null;
    if (raw.instructions !== undefined && typeof raw.instructions !== "string") return null;
    const instructions = typeof raw.instructions === "string" ? raw.instructions.trim() : undefined;
    if (instructions !== undefined && instructions.length > TRIAGE_INSTRUCTIONS_MAX) return null;
    config[key] = { enabled: raw.enabled, ...(instructions !== undefined ? { instructions } : {}) };
  }
  return config;
}

async function createLoop(ctx: ApiCtx): Promise<void> {
  const deps = loopDeps(ctx);
  if (!deps) return sendJson(ctx.res, 404, { error: "not_found", message: "loops are not wired on this deployment" });
  const acting = actingPrincipal(ctx);
  if (!acting) return;
  const b = isObj(ctx.body) ? ctx.body : {};
  if (b.icon !== undefined && !validLoopIcon(b.icon))
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message: LOOP_ICON_ERROR,
    });
  if (typeof b.name !== "string" || !b.name.trim())
    return sendJson(ctx.res, 400, { error: "bad_request", message: "name required" });
  if (typeof b.playbook !== "string" || !b.playbook.trim())
    return sendJson(ctx.res, 400, { error: "bad_request", message: "playbook required" });
  if (typeof b.successCondition !== "string" || !b.successCondition.trim())
    return sendJson(ctx.res, 400, { error: "bad_request", message: "successCondition required" });
  const shipActions = shipActionsFromBody(b.shipActions);
  if (shipActions === null)
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message: 'shipActions must be [{action, gate: "auto"|"hold"}]',
    });
  if (shipActions.some((policy) => policy.gate === "auto") && !requireLiveHuman(ctx, acting)) return;
  const capsResult = capsFromBody(b.caps);
  if (capsResult.invalidField)
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message: `${capsResult.invalidField} must be a finite positive integer`,
    });
  const caps = capsResult.value;
  const governorResult = governorFromBody(b.governor);
  if (governorResult.invalidField)
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message: `${governorResult.invalidField} has an invalid operational value`,
    });
  const governor = governorResult.value;
  let schedule;
  if (b.schedule !== undefined) {
    const defaultTimezone =
      typeof ctx.capability?.timezone === "string" && ctx.capability.timezone.trim()
        ? ctx.capability.timezone
        : DEFAULT_CRON_TIMEZONE;
    schedule = userScheduleFromBody(b.schedule, defaultTimezone);
    if (!schedule)
      return sendJson(ctx.res, 400, { error: "bad_request", message: "schedule must be a valid schedule object" });
    try {
      validateUserSchedule(schedule);
    } catch (e) {
      return sendJson(ctx.res, 400, { error: "bad_request", message: errMessage(e) });
    }
  }
  let destination;
  if (b.destinationKey !== undefined) {
    if (typeof b.destinationKey !== "string")
      return sendJson(ctx.res, 400, { error: "bad_request", message: "destinationKey must be a string" });
    if (!ctx.capability)
      return sendJson(ctx.res, 400, { error: "bad_request", message: "destinationKey requires an agent capability" });
    const resolved = resolveCapabilityDestination(ctx.capability, b.destinationKey);
    if (!resolved.ok || !resolved.destination)
      return sendJson(ctx.res, 400, { error: "bad_request", message: "destinationKey is not available" });
    if (!requireLiveHuman(ctx, acting)) return;
    destination = resolved.destination;
  }
  const ownerScopeId: ScopeId = scopeId("personal", acting.actorId);
  const input: CreateLoopInput = {
    owner: acting.actorId,
    createdBy: acting.actorId,
    ownerScopeId,
    name: b.name,
    ...(b.icon !== undefined ? { icon: b.icon as string | null } : {}),
    playbook: b.playbook,
    successCondition: b.successCondition,
    shipActions,
    ...(typeof b.purpose === "string" && b.purpose.trim() ? { purpose: b.purpose.trim() } : {}),
    ...(Array.isArray(b.successChecks)
      ? { successChecks: b.successChecks.filter((c): c is string => typeof c === "string" && c.trim() !== "") }
      : {}),
    ...(caps && Object.keys(caps).length > 0 ? { caps } : {}),
    ...(governor && Object.keys(governor).length > 0 ? { governor } : {}),
    ...(schedule ? { schedule } : {}),
    ...(destination ? { destination } : {}),
  };
  let loop: Loop;
  let created: boolean;
  try {
    ({ loop, created } = await deps.store.create(input));
  } catch (e) {
    return sendJson(ctx.res, 400, { error: "loop_create_failed", message: errMessage(e) });
  }
  if (created && schedule && deps.crons) {
    let cronId: string | undefined;
    try {
      const cron = await deps.crons.create({
        owner: loop.owner,
        createdBy: loop.createdBy,
        ownerScopeId: loop.ownerScopeId,
        schedule,
        title: `Loop: ${loop.name}`,
        action: `fire loop ${loop.id}`,
        loopId: loop.id,
        ownerConsentedAt: Date.now(),
      });
      cronId = cron.id;
      loop = (await deps.store.update(loop.id, { cronId: cron.id })) ?? loop;
    } catch (e) {
      if (cronId) await deps.crons.delete(cronId).catch((error: unknown) => swallow("loop cron rollback", error));
      await deps.store.delete(loop.id);
      return sendJson(ctx.res, 400, { error: "loop_schedule_failed", message: errMessage(e) });
    }
  }
  return sendJson(ctx.res, 200, { loop, created });
}

async function listLoops(ctx: ApiCtx): Promise<void> {
  const deps = loopDeps(ctx);
  if (!deps) return sendJson(ctx.res, 404, { error: "not_found", message: "loops are not wired on this deployment" });
  const acting = actingPrincipal(ctx);
  if (!acting) return;
  const all = await deps.store.list();
  const visible: Loop[] = [];
  for (const loop of all) {
    if (await canAdministerLoop(ctx, loop, acting)) visible.push(loop);
  }
  return sendJson(ctx.res, 200, { loops: visible });
}

async function triageAvailable(ctx: ApiCtx, loop: Loop): Promise<boolean> {
  return (await ctx.deps.featureFlags?.enabled("loop_triage", scopeId("personal", loop.owner))) === true;
}

async function getLoop(ctx: ApiCtx): Promise<void> {
  const loaded = await loadAdministrable(ctx);
  if (!loaded) return;
  const { deps, loop } = loaded;
  const [items, outputs, grants, vitals, triage] = await Promise.all([
    deps.items.byLoop(loop.id),
    deps.outputs.byLoop(loop.id),
    deps.grants.byLoop(loop.id),
    collectVitals(loop, { items: deps.items, outputs: deps.outputs }, Date.now()),
    triageAvailable(ctx, loop),
  ]);
  return sendJson(ctx.res, 200, {
    loop,
    items: sortLedgerItems(items, loop).map((item) =>
      ctx.capability
        ? {
            ...item,
            ...(item.sourcePayload ? { sourcePayload: agentSourcePayload(item.sourcePayload, item.source) } : {}),
            ...(item.inboxPreview
              ? {
                  inboxPreview: agentSourcePayload(
                    item.inboxPreview,
                    item.source ?? String(item.sourcePayload?.source ?? ""),
                  ),
                }
              : {}),
          }
        : item,
    ),
    outputs,
    grants,
    vitals,
    triageAvailable: triage,
  });
}

const STATES = new Set<LoopState>(["enabled", "paused", "quarantined", "archived"]);

async function patchLoop(ctx: ApiCtx): Promise<void> {
  const loaded = await loadAdministrable(ctx);
  if (!loaded) return;
  const { deps, loop, acting } = loaded;
  if (!(await requireLoopAuthority(ctx, deps, loop))) return;
  const b = isObj(ctx.body) ? ctx.body : {};
  if (b.icon !== undefined && !validLoopIcon(b.icon))
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message: LOOP_ICON_ERROR,
    });
  const patch: LoopPatch = {};
  if (typeof b.playbook === "string" && b.playbook.trim()) {
    patch.playbookEdit = {
      playbook: b.playbook,
      by: acting.actorId,
      ...(typeof b.note === "string" && b.note.trim() ? { note: b.note.trim() } : {}),
    };
  } else if (b.playbook !== undefined) {
    return sendJson(ctx.res, 400, { error: "bad_request", message: "playbook must be a non-empty string" });
  }
  if (typeof b.state === "string") {
    if (!STATES.has(b.state as LoopState))
      return sendJson(ctx.res, 400, {
        error: "bad_request",
        message: "state must be enabled|paused|quarantined|archived",
      });
    patch.state = b.state as LoopState;
    if (patch.state === "enabled" && (loop.state === "quarantined" || loop.state === "archived")) {
      if (!requireLiveHuman(ctx, acting)) return;
      if (loop.state === "quarantined") {
        patch.quarantineClearedBy = acting.actorId;
        patch.quarantineClearedAt = Date.now();
      }
    }
  } else if (b.state !== undefined) {
    return sendJson(ctx.res, 400, { error: "bad_request", message: "state must be a string" });
  }
  Object.assign(patch, {
    ...(b.icon !== undefined ? { icon: b.icon } : {}),
    ...(typeof b.name === "string" && b.name.trim() ? { name: b.name } : {}),
    ...(typeof b.purpose === "string" ? { purpose: b.purpose } : {}),
    ...(typeof b.successCondition === "string" && b.successCondition.trim()
      ? { successCondition: b.successCondition }
      : {}),
    ...(Array.isArray(b.successChecks)
      ? { successChecks: b.successChecks.filter((c): c is string => typeof c === "string") }
      : {}),
  });
  const governorResult = governorFromBody(b.governor);
  if (governorResult.invalidField)
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message: `${governorResult.invalidField} has an invalid operational value`,
    });
  const governorPatch = governorResult.value;
  if (governorPatch !== undefined) patch.governor = governorPatch;
  const shipActions = b.shipActions === undefined ? [] : shipActionsFromBody(b.shipActions);
  if (shipActions === null)
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message: 'shipActions must be [{action, gate: "auto"|"hold"}]',
    });
  const existingGates = new Map(loop.shipActions.map((policy) => [policy.action, policy.gate]));
  if (
    shipActions.some((policy) => policy.gate === "auto" && existingGates.get(policy.action) !== "auto") &&
    !requireLiveHuman(ctx, acting)
  )
    return;
  if (b.shipActions !== undefined) patch.shipActions = shipActions;
  const capsResult = capsFromBody(b.caps);
  if (capsResult.invalidField)
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message: `${capsResult.invalidField} must be a finite positive integer`,
    });
  const caps = capsResult.value;
  if (caps !== undefined) patch.caps = caps;
  const triage = triageFromBody(b.triage);
  if (triage === null)
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message: `triage must be {prioritize?, consolidate?: {enabled: boolean, instructions?: string up to ${TRIAGE_INSTRUCTIONS_MAX} chars}}`,
    });
  if (triage !== undefined) {
    const enabling = Object.values(triage).some((setting) => setting?.enabled === true);
    if (enabling && !(await triageAvailable(ctx, loop)))
      return sendJson(ctx.res, 403, {
        error: "forbidden",
        message: "loop triage is not enabled for this loop's owner",
      });
    if (!requireLiveHuman(ctx, acting)) return;
    patch.triage = triage;
  }
  if (b.destinationKey !== undefined) {
    if (b.destinationKey !== null && typeof b.destinationKey !== "string")
      return sendJson(ctx.res, 400, { error: "bad_request", message: "destinationKey must be a string or null" });
    if (!ctx.capability)
      return sendJson(ctx.res, 400, { error: "bad_request", message: "destinationKey requires an agent capability" });
    if (!requireLiveHuman(ctx, acting)) return;
    if (b.destinationKey === null) {
      patch.destination = null;
    } else {
      const resolved = resolveCapabilityDestination(ctx.capability, b.destinationKey);
      if (!resolved.ok || !resolved.destination)
        return sendJson(ctx.res, 400, { error: "bad_request", message: "destinationKey is not available" });
      patch.destination = resolved.destination;
    }
  }
  const updated = Object.keys(patch).length > 0 ? await deps.store.update(loop.id, patch) : loop;
  if (!updated) return sendJson(ctx.res, 404, { error: "not_found", message: "no such loop" });
  if (patch.state !== undefined && loop.cronId && deps.crons) {
    try {
      await deps.crons.setEnabled(loop.cronId, patch.state === "enabled");
    } catch (e) {
      await deps.store.update(loop.id, { restore: loop });
      return sendJson(ctx.res, 502, { error: "loop_schedule_failed", message: errMessage(e) });
    }
  }
  return sendJson(ctx.res, 200, { loop: updated ?? (await deps.store.get(loop.id)) });
}

async function deleteLoop(ctx: ApiCtx): Promise<void> {
  const loaded = await loadAdministrable(ctx);
  if (!loaded) return;
  const { deps, loop } = loaded;
  if (loop.cronId && deps.crons)
    await deps.crons.delete(loop.cronId).catch((e: unknown) => swallow("loop cron delete", e));
  await deps.grants.deleteByLoop(loop.id);
  await deps.items.deleteByLoop(loop.id);
  await deps.outputs.deleteByLoop(loop.id);
  await deps.store.delete(loop.id);
  return sendJson(ctx.res, 200, { ok: true });
}

async function previewLoopTriage(ctx: ApiCtx): Promise<void> {
  const loaded = await loadAdministrable(ctx);
  if (!loaded) return;
  const { deps, loop, acting } = loaded;
  if (!(await requireLoopAuthority(ctx, deps, loop))) return;
  if (!deps.fire || !(await triageAvailable(ctx, loop)))
    return sendJson(ctx.res, 404, { error: "not_found", message: "loop triage is not available" });
  const triage = triageFromBody(isObj(ctx.body) ? ctx.body.triage : undefined);
  if (!triage)
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message: `triage must be {prioritize?, consolidate?: {enabled: boolean, instructions?: string up to ${TRIAGE_INSTRUCTIONS_MAX} chars}}`,
    });
  if (!requireLiveHuman(ctx, acting)) return;
  try {
    const items = await deps.fire.previewTriage(loop, { ...loop.triage, ...triage });
    return sendJson(ctx.res, 200, { items });
  } catch (e) {
    return sendJson(ctx.res, 502, { error: "preview_failed", message: errMessage(e) });
  }
}

async function fireLoopNow(ctx: ApiCtx): Promise<void> {
  const loaded = await loadAdministrable(ctx);
  if (!loaded) return;
  const { deps, loop } = loaded;
  if (!(await requireLoopAuthority(ctx, deps, loop))) return;
  if (!deps.fire) return sendJson(ctx.res, 404, { error: "not_found", message: "loop firing is not wired" });
  const fireKey = `loop:${loop.id}:manual:${Date.now()}`;
  void deps.fire.fire(loop.id, fireKey).catch((e: unknown) => swallow(`manual fire of loop ${loop.id}`, e));
  return sendJson(ctx.res, 200, { ok: true, fireKey });
}

async function decideOutput(ctx: ApiCtx): Promise<void> {
  const lock = loopDeps(ctx)?.lock;
  if (lock && !ctx.capability)
    return lock.withLock(`loop-lifecycle:${ctx.params.id ?? ""}`, () => decideOutputLocked(ctx));
  return decideOutputLocked(ctx);
}

async function decideOutputLocked(ctx: ApiCtx): Promise<void> {
  const loaded = await loadAdministrable(ctx);
  if (!loaded) return;
  const { deps, loop, acting } = loaded;
  if (!(await requireLoopAuthority(ctx, deps, loop))) return;
  if (!requireLiveHuman(ctx, acting)) return;
  if (!deps.fire) return sendJson(ctx.res, 404, { error: "not_found", message: "loop firing is not wired" });
  const b = isObj(ctx.body) ? ctx.body : {};
  const outputId = ctx.params.outputId ?? "";
  const note = typeof b.note === "string" && b.note.trim() ? b.note.trim() : undefined;
  const decisionMissing = async () => {
    const output = await deps.outputs.get(outputId);
    const item = output ? await deps.items.get(output.itemId) : null;
    if (item?.decisionToken && (item.decisionAt ?? 0) + DECISION_LEASE_MS > Date.now())
      return sendJson(ctx.res, 409, { error: "decision_in_progress" });
    return sendJson(ctx.res, 404, { error: "not_found", message: "no such ready output" });
  };
  if (b.decision === "ship" || b.decision === "shipped") {
    try {
      const shipped = await deps.fire.shipOutput(loop.id, outputId, acting.actorId, note);
      if (!shipped) return decisionMissing();
      const item = await deps.items.get(shipped.itemId);
      if (item && consolidates(loop))
        await settleGroup(deps.items, item).catch((e: unknown) => swallow("loop group settle", e));
      return sendJson(ctx.res, 200, { output: shipped });
    } catch (e) {
      return sendJson(ctx.res, 502, { error: "ship_failed", message: errMessage(e) });
    }
  }
  if (b.decision === "return" || b.decision === "returned") {
    if (!note)
      return sendJson(ctx.res, 400, { error: "bad_request", message: "a return needs a note for the next attempt" });
    const returned = await deps.fire.returnOutput(loop.id, outputId, acting.actorId, note);
    if (!returned) return decisionMissing();
    return sendJson(ctx.res, 200, { output: returned });
  }
  return sendJson(ctx.res, 400, { error: "bad_request", message: 'decision must be "shipped" or "returned"' });
}

async function graduateShipAction(ctx: ApiCtx): Promise<void> {
  const loaded = await loadAdministrable(ctx);
  if (!loaded) return;
  const { deps, loop, acting } = loaded;
  if (!(await requireLoopAuthority(ctx, deps, loop))) return;
  if (!requireLiveHuman(ctx, acting)) return;
  const b = isObj(ctx.body) ? ctx.body : {};
  if (typeof b.shipAction !== "string" || !b.shipAction.trim())
    return sendJson(ctx.res, 400, { error: "bad_request", message: "shipAction required" });
  if (!loop.shipActions.some((policy) => policy.action === b.shipAction))
    return sendJson(ctx.res, 400, { error: "bad_request", message: "shipAction is not declared by this loop" });
  try {
    const modes = await deps.config.getApprovalGrantModesDurable(loop.ownerScopeId);
    const grant = await deps.grants.put(
      buildShipGrant({
        loopId: loop.id,
        shipAction: b.shipAction.trim(),
        actorId: acting.actorId,
        policyVersion: loop.policyVersion ?? 1,
        modes,
        ...(typeof b.label === "string" && b.label.trim() ? { label: b.label.trim() } : {}),
      }),
    );
    return sendJson(ctx.res, 200, { grant });
  } catch (e) {
    return sendJson(ctx.res, 403, { error: "grant_refused", message: errMessage(e) });
  }
}

async function setAutopilot(ctx: ApiCtx): Promise<void> {
  const loaded = await loadAdministrable(ctx);
  if (!loaded) return;
  const { deps, loop, acting } = loaded;
  if (!(await requireLoopAuthority(ctx, deps, loop))) return;
  const b = isObj(ctx.body) ? ctx.body : {};
  if (typeof b.enabled !== "boolean")
    return sendJson(ctx.res, 400, { error: "bad_request", message: "enabled must be a boolean" });
  if (b.enabled) {
    if (!requireLiveHuman(ctx, acting)) return;
    if (loop.state === "quarantined" || loop.state === "archived")
      return sendJson(ctx.res, 409, {
        error: "conflict",
        message: `cannot enable autopilot while loop is ${loop.state}`,
      });
    try {
      const modes = await deps.config.getApprovalGrantModesDurable(loop.ownerScopeId);
      const gatesChange = loop.shipActions.some((policy) => policy.gate !== "auto");
      const policyVersion = (loop.policyVersion ?? 1) + (gatesChange ? 1 : 0);
      const desiredGrants = loop.shipActions.map((policy) =>
        buildShipGrant({
          loopId: loop.id,
          shipAction: policy.action,
          actorId: acting.actorId,
          policyVersion,
          modes,
        }),
      );

      const existing = await deps.grants.byLoop(loop.id);
      for (const grant of desiredGrants) {
        if (!existing.some((candidate) => candidate.id === grant.id && candidate.revokedAt === undefined))
          await deps.grants.put(grant);
      }
      const updated = !gatesChange
        ? loop
        : ((await deps.store.update(loop.id, {
            shipActions: loop.shipActions.map((policy) => ({ ...policy, gate: "auto" })),
          })) ?? loop);
      return sendJson(ctx.res, 200, { loop: updated, grants: await deps.grants.byLoop(loop.id) });
    } catch (e) {
      return sendJson(ctx.res, 403, { error: "grant_refused", message: errMessage(e) });
    }
  }
  const updated = loop.shipActions.every((policy) => policy.gate === "hold")
    ? loop
    : ((await deps.store.update(loop.id, {
        shipActions: loop.shipActions.map((policy) => ({ ...policy, gate: "hold" })),
      })) ?? loop);
  const grants = await deps.grants.byLoop(loop.id);
  for (const grant of grants) {
    if (grant.revokedAt === undefined) await deps.grants.revoke(grant.id, acting.actorId);
  }
  return sendJson(ctx.res, 200, { loop: updated, grants: await deps.grants.byLoop(loop.id) });
}

async function revokeShipGrant(ctx: ApiCtx): Promise<void> {
  const loaded = await loadAdministrable(ctx);
  if (!loaded) return;
  const { deps, loop, acting } = loaded;
  if (!requireLiveHuman(ctx, acting)) return;
  const grantId = ctx.params.grantId ?? "";
  const grant = await deps.grants.get(grantId);
  if (!grant || grant.loopId !== loop.id)
    return sendJson(ctx.res, 404, { error: "not_found", message: "no such ship grant" });
  const revoked = await deps.grants.revoke(grantId, acting.actorId);
  return sendJson(ctx.res, 200, { grant: revoked });
}

export const loopRoutes: ReadonlyArray<Route<ApiCtx>> = [
  { method: "POST", path: "/v1/loops/:id/triage/preview", auth: "source", handle: previewLoopTriage },
  ...withActor("query.principalId", [
    { method: "POST", path: "/v1/loops", auth: "either", handle: createLoop },
    { method: "GET", path: "/v1/loops", auth: "either", handle: listLoops },
    { method: "GET", path: "/v1/loops/:id", auth: "either", handle: getLoop },
    { method: "PATCH", path: "/v1/loops/:id", auth: "either", handle: patchLoop },
    { method: "DELETE", path: "/v1/loops/:id", auth: "either", handle: deleteLoop },
    { method: "POST", path: "/v1/loops/:id/fire", auth: "either", handle: fireLoopNow },
    { method: "POST", path: "/v1/loops/:id/outputs/:outputId/decide", auth: "either", handle: decideOutput },
    { method: "POST", path: "/v1/loops/:id/grants", auth: "either", handle: graduateShipAction },
    { method: "POST", path: "/v1/loops/:id/autopilot", auth: "either", handle: setAutopilot },
    { method: "DELETE", path: "/v1/loops/:id/grants/:grantId", auth: "either", handle: revokeShipGrant },
  ]),
];