@saadnvd1/agent-os 0.3.631 → 0.3.639

package/lib/tasks/holds.ts

@@ -0,0 +1,281 @@
+/**
+ * Every reason a task waits, as one type and one ordered list. A hold is
+ * pure data: `holdsFor` turns a candidate and what we know of its machine
+ * into the holds that apply, always in HOLD_ORDER, and the first is the
+ * reason shown. The queue view, a queued row's note, a paused task's resume
+ * note and the start decision all read that list, so "why is this waiting"
+ * has one source. No database and no clock of its own: the checks that need
+ * either are in hold-checks.ts.
+ */
+
+import {
+  DEFAULT_PRIORITY,
+  type Priority,
+  type WaitCode,
+} from "./schedule-types";
+import type { Candidate } from "./schedule";
+
+// Out of red this long before automatic starts resume.
+export const LOAD_SETTLE_MS = 120_000;
+// On amber, only this priority and above start.
+export const AMBER_MIN_PRIORITY: Priority = "blocking";
+// Between automatic starts on one machine.
+export const START_GAP_MS = 60_000;
+// Between starts of tasks that boot a simulator.
+export const HEAVY_START_GAP_MS = 5 * 60_000;
+
+export const PRIORITY_POINTS: Record<Priority, number> = {
+  urgent: 400,
+  blocking: 300,
+  normal: 200,
+  background: 100,
+};
+const priorityRank = (p: Priority) => PRIORITY_POINTS[p] ?? 0;
+
+export type MachineLevel = "green" | "amber" | "red";
+
+// What the machine a candidate would start on looks like right now.
+export interface MachineView {
+  // Shown in hold texts, e.g. "this machine".
+  label: string;
+  // False: no load holds at all (AGENTOS_LOAD=off).
+  enabled: boolean;
+  // No sample read yet since AgentOS started.
+  reading: boolean;
+  level: MachineLevel;
+  // Not red, and calm for LOAD_SETTLE_MS since it last was.
+  settled: boolean;
+  // Seconds of calm still needed, when not settled and not red.
+  settleLeftMs: number;
+  booted: number;
+  maxBooted: number;
+  // Heavy tasks started within HEAVY_START_GAP_MS that hold no lease yet.
+  heavyStarting: number;
+  lastAutoStartAt: number | null;
+  lastHeavyStartAt: number | null;
+}
+
+export type MachineCode =
+  | "needs"
+  | "load_red"
+  | "load_amber"
+  | "heavy"
+  | "spacing";
+
+// A reason a task isn't starting. `code` is also what a queue row stores and
+// the client reads. A hold that rests on a machine says which one, and when
+// it knows, the time (ms) it lifts.
+export type Hold =
+  | { code: "after"; text: string }
+  | { code: "after_any"; text: string }
+  | { code: "orch_paused"; text: string }
+  | { code: "window"; text: string }
+  | {
+      code: MachineCode;
+      text: string;
+      machine: string;
+      until?: number;
+      // Why it waits here instead of starting on a linked machine.
+      stay?: string;
+    }
+  | { code: "slot"; text: string };
+
+// The order holds are reported in; the first that applies is the reason.
+export const HOLD_ORDER: readonly WaitCode[] = [
+  "after",
+  "after_any",
+  "orch_paused",
+  "window",
+  "needs",
+  "load_red",
+  "load_amber",
+  "heavy",
+  "spacing",
+  "slot",
+];
+
+// Whether the hold lifts without anyone acting. A Pause is lifted by a
+// person, and a task that needs a Mac never gets one by waiting.
+const CLEARS_BY_ITSELF: Record<WaitCode, boolean> = {
+  after: true,
+  after_any: true,
+  orch_paused: false,
+  window: true,
+  needs: false,
+  load_red: true,
+  load_amber: true,
+  heavy: true,
+  spacing: true,
+  slot: true,
+};
+
+export const clearsByItself = (h: Hold): boolean => CLEARS_BY_ITSELF[h.code];
+
+// The holds a linked machine could lift by taking the start.
+const PLACEABLE = new Set<WaitCode>([
+  "load_red",
+  "load_amber",
+  "heavy",
+  "needs",
+]);
+
+export const placeable = (h: Pick<Hold, "code">): boolean =>
+  PLACEABLE.has(h.code);
+
+// The text a person sees: the hold, and for a task that can't go elsewhere,
+// why it stays here.
+export function holdText(h: Hold): string {
+  return "stay" in h && h.stay ? `${h.text} (${h.stay})` : h.text;
+}
+
+// The same without the "Waiting: " lead, for a note that has its own.
+export const holdReason = (h: Hold): string =>
+  holdText(h).replace(/^Waiting: /, "");
+
+// What a row stores of its first hold: null code and text when none.
+export function queueNote(holds: readonly Hold[] | undefined): {
+  code: WaitCode | null;
+  text: string | null;
+} | null {
+  if (!holds) return null;
+  const head = holds[0];
+  return head
+    ? { code: head.code, text: holdText(head) }
+    : { code: null, text: null };
+}
+
+// What a timed resume waiting for its turn says on its task.
+export function resumeNote(
+  holds: readonly Hold[] | undefined,
+  slots: { running: number; limit: number | null }
+): string | null {
+  if (!holds) return null;
+  const head = holds[0];
+  if (head && head.code !== "slot") return `held: ${holdReason(head)}`;
+  return slots.limit === null
+    ? "resuming: waiting for its turn"
+    : `resuming: waiting for a slot, ${slots.running} of ${slots.limit} running`;
+}
+
+const seconds = (ms: number) => Math.max(1, Math.ceil(ms / 1000));
+
+export function slotText(rank: number, of: number, priority: Priority): string {
+  const word = priority === DEFAULT_PRIORITY ? "" : ` · ${priority}`;
+  return `#${rank} of ${of}${word}`;
+}
+
+type MachineAsk = Pick<
+  Candidate,
+  "heavy" | "needsUnmet" | "remote" | "priority"
+> &
+  Partial<Pick<Candidate, "planOnly">>;
+
+// The holds the machine puts on a start, in order. Empty: it may start here
+// now. A machine with no reading yet says only that; one with load checks
+// off says only what it lacks.
+export function machineHolds(
+  c: MachineAsk,
+  m: MachineView,
+  now: number
+): Hold[] {
+  if (c.remote || c.planOnly) return [];
+  const out: Hold[] = [];
+  const add = (code: MachineCode, text: string, until?: number): void => {
+    out.push({
+      code,
+      text: `Waiting: ${text}`,
+      machine: m.label,
+      ...(until === undefined ? {} : { until }),
+    });
+  };
+  if (c.needsUnmet) add("needs", "needs a Mac");
+  if (!m.enabled) return out;
+  if (m.reading) {
+    add("load_red", "reading machine load");
+    return out;
+  }
+  if (m.level === "red") add("load_red", `${m.label} load red`);
+  else if (!m.settled)
+    add(
+      "load_red",
+      `${m.label} load was red; calm for ${seconds(m.settleLeftMs)}s more`,
+      now + m.settleLeftMs
+    );
+  else if (
+    m.level === "amber" &&
+    priorityRank(c.priority) < priorityRank(AMBER_MIN_PRIORITY)
+  )
+    add(
+      "load_amber",
+      `${m.label} load amber; ${c.priority} work starts on green`
+    );
+  if (c.heavy && m.level !== "red") {
+    if (m.level !== "green")
+      add("heavy", `${m.label} load amber; simulator work starts on green`);
+    else if (m.heavyStarting > 0)
+      add("heavy", `a simulator is booting on ${m.label}`);
+    else if (m.booted >= m.maxBooted)
+      add("heavy", `${m.booted} of ${m.maxBooted} simulators in use`);
+    else if (
+      m.lastHeavyStartAt !== null &&
+      now - m.lastHeavyStartAt < HEAVY_START_GAP_MS
+    )
+      add(
+        "heavy",
+        `a simulator task just started on ${m.label} (next in ${seconds(HEAVY_START_GAP_MS - (now - m.lastHeavyStartAt))}s)`,
+        m.lastHeavyStartAt + HEAVY_START_GAP_MS
+      );
+  }
+  if (m.lastAutoStartAt !== null && now - m.lastAutoStartAt < START_GAP_MS)
+    add(
+      "spacing",
+      `spacing starts (next in ${seconds(START_GAP_MS - (now - m.lastAutoStartAt))}s)`,
+      m.lastAutoStartAt + START_GAP_MS
+    );
+  return out;
+}
+
+// The first machine hold, or null: the one every placement check asks.
+export const machineHold = (
+  c: MachineAsk,
+  m: MachineView,
+  now: number
+): Hold | null => machineHolds(c, m, now)[0] ?? null;
+
+export interface HoldContext {
+  machine: MachineView;
+  now: number;
+  // Finishes other waiters have already taken this look.
+  used: ReadonlySet<string>;
+  // Running tasks in its line, and the line's limit.
+  inFlight: number;
+  limit: number;
+  // Its place in the line's score order.
+  rank: number;
+  of: number;
+}
+
+// Every hold on a candidate, in HOLD_ORDER. The first is why it waits; none:
+// it starts.
+export function holdsFor(c: Candidate, ctx: HoldContext): Hold[] {
+  const out: Hold[] = [];
+  if (c.before) out.push(c.before);
+  if (c.any && !c.any.released) {
+    const free = c.any.finished.some((id) => !ctx.used.has(id));
+    const spent =
+      c.any.ids.length > 0 && c.any.finished.length === c.any.ids.length;
+    if (!free && !spent)
+      out.push({
+        code: "after_any",
+        text: `Waiting: after any running task (${c.any.label})`,
+      });
+  }
+  if (c.auto) out.push(...([] as Hold[]).concat(c.auto));
+  out.push(...machineHolds(c, ctx.machine, ctx.now));
+  if (!c.planOnly && ctx.inFlight >= ctx.limit)
+    out.push({
+      code: "slot",
+      text: slotText(ctx.rank, ctx.of, c.priority),
+    });
+  return out;
+}

package/lib/tasks/import.ts

@@ -38,6 +38,7 @@ import {
   validateBundle,
   type TaskBundle,
 } from "./move-bundle";
+import { setPlan, setTask } from "../db/session-parts";
 
 // Imports in flight in this process, by move id.
 const g = globalThis as unknown as { __agentosImporting?: Set<string> };
@@ -47,7 +48,7 @@ const importing = (g.__agentosImporting ??= new Set());
 export const arrived = (moveId: string) =>
   db
     .prepare(
-      `SELECT * FROM sessions WHERE moved_from = ? AND host_id = 'local'
+      `SELECT * FROM session_rows WHERE moved_from = ? AND host_id = 'local'
          AND task_status IN ('running', 'moving', 'moved', 'merged', 'done')`
     )
     .get(moveId) as Session | undefined;
@@ -56,7 +57,7 @@ export const arrived = (moveId: string) =>
 function refuseBusyBranch(projectId: string, branch: string): void {
   const busy = db
     .prepare(
-      `SELECT id FROM sessions WHERE project_id = ? AND branch_name = ?
+      `SELECT id FROM session_rows WHERE project_id = ? AND branch_name = ?
          AND task_status IN ('running', 'moving') AND host_id = 'local'`
     )
     .get(projectId, branch);
@@ -118,9 +119,10 @@ async function arrive(
   };
   stepProgress(bundle.moveId, "conversation");
   // The plan is never in git: it comes in the bundle.
-  if (orch?.planFile != null) {
+  const planFile = bundle.planWait?.file ?? orch?.planFile ?? null;
+  if (planFile != null) {
     preparePlanDir(worktreePath);
-    fs.writeFileSync(path.join(worktreePath, PLAN_FILE), orch.planFile);
+    fs.writeFileSync(path.join(worktreePath, PLAN_FILE), planFile);
   }
   if (claude && paths) {
     await writeTranscript(
@@ -165,22 +167,29 @@ async function arrive(
       .run(worktreePath, bundle.branch, baseBranch, null, id);
     // A chat's worker reads its brief from the row; a terminal's is passed.
     db.prepare(
-      `UPDATE sessions SET task_prompt = ?, task_brief = ?, task_status = 'running', name_source = 'user',
-         claude_session_id = ?, moved_from = ? WHERE id = ?`
-    ).run(bundle.prompt, brief, claude?.sessionId ?? null, bundle.moveId, id);
+      `UPDATE sessions SET name_source = 'user', claude_session_id = ? WHERE id = ?`
+    ).run(claude?.sessionId ?? null, id);
+    setTask(db, id, {
+      task_prompt: bundle.prompt,
+      task_brief: brief,
+      task_status: "running",
+      moved_from: bundle.moveId,
+    });
     if (bundle.chat) unpackChat(id, bundle.chat, paths);
+    if (bundle.planWait) setPlan(db, id, { plan_phase: "awaiting" });
     if (orch) {
-      db.prepare(
-        `UPDATE sessions SET plan_phase = ?, task_since = ? WHERE id = ?`
-      ).run(orch.planPhase, orch.since, id);
+      setPlan(db, id, { plan_phase: orch.planPhase });
+      setTask(db, id, { task_since: orch.since });
       // Held for the orchestrator's device. The orchestrator's own state
       // (started_by, its gates) never comes from the bundle: it stays on its
       // machine, and a task coming back takes it from the mirror's record.
       if (holder) {
         holdFor(id, holder, orch);
-        db.prepare(
-          `UPDATE sessions SET model_provider = ?, model_overrides = ? WHERE id = ?`
-        ).run(orch.modelProvider, orch.modelOverrides, id);
+        db.prepare(`UPDATE sessions SET model_provider = ? WHERE id = ?`).run(
+          orch.modelProvider,
+          id
+        );
+        setTask(db, id, { model_overrides: orch.modelOverrides });
       }
     }
     carryTaskState(bundle.moveId, id);
@@ -205,7 +214,10 @@ async function arrive(
     }
     const note = arrivalNote(bundle, worktreePath, os.hostname());
     const prompt = claude ? note : `${bundle.prompt}\n\n${note}`;
-    if (bundle.chat) {
+    if (bundle.planWait) {
+      // Waiting on its plan's approval: nothing runs until the message that
+      // implements it, which resumes the carried conversation.
+    } else if (bundle.chat) {
       // Its worker starts on the carried conversation, takes the note
       // first, then what was queued.
       await sendChat(id, {

package/lib/tasks/index.ts

@@ -59,12 +59,13 @@ import { finishTaskStart } from "./start";
 import { isRemoteHost } from "../hosts";
 import { DEFAULT_START_VIEW, type StartView } from "../sessions/launch";
 import { viewOf } from "./move-targets";
-import { isMirror, startRemoteTask } from "./remote";
-import { remoteTaskViews } from "./remote-views";
+import { isMirror, startRemoteTask } from "./contract/start";
+import { mirrorViews } from "./contract/views";
 import { chatStateNow } from "../chat/runner";
 import { saidSinceLastMessage } from "../chat/store";
 
 import { lastActiveOf } from "./last-active";
+import { setPlan, setTask } from "../db/session-parts";
 export * from "./state";
 export { codeReviewGate, codeReviewRefusal } from "./code-review";
 export { signOffTask, dropTask, signingOff, mergeSettled } from "./finish";
@@ -173,6 +174,9 @@ export async function createTask(opts: {
   held?: { device: string; orchestrated: OrchestratedBundle };
   // The paired device that sent this keyed start: the only one that may hold it later.
   startedByDevice?: string | null;
+  // Another machine placed this plan here and decides what follows it: the
+  // task plans, then waits for that machine (implies planOnly).
+  planWaits?: boolean;
 }): Promise<Session> {
   if (opts.id) {
     const existing = queries.getSession(db).get(opts.id) as Session | undefined;
@@ -244,12 +248,27 @@ async function startTask(
       throw new Error(`${agentLabel(agent)} tasks run on this machine for now`);
   }
   if (isRemoteHost(hostId)) {
-    if (opts.planOnly)
-      throw new Error("A plan-only task runs on this machine for now");
     if (opts.base || opts.cardId)
       throw new Error(
         "Stacked and card tasks run on this machine only for now"
       );
+    if (opts.planOnly && opts.plan === false)
+      throw new Error(
+        "planOnly implies plan; it can't be combined with plan false"
+      );
+    if (opts.planOnly && view !== "chat")
+      throw new Error("A plan-only task needs a chat, not a terminal");
+    // The plan step is this machine's to run and decide: it plans there,
+    // stops, and what follows is chosen here (contract/plan.ts).
+    const planned =
+      !!(opts.plan || opts.planOnly) &&
+      taskRouting(
+        project.workspace_id,
+        view,
+        opts.model,
+        opts.plan,
+        opts.planOnly
+      ).plan;
     const session = await startRemoteTask(hostId, project, {
       id,
       prompt,
@@ -258,8 +277,11 @@ async function startTask(
       baseBranch: opts.baseBranch,
       view,
       startedBy: opts.startedBy,
+      plan: planned
+        ? { only: !!opts.planOnly, reason: opts.planReason?.trim() || null }
+        : undefined,
     });
-    // The mirror's started_by stays orchestrator-only: a held-remote task is
+    // The mirror's started_by stays orchestrator-only: a held task on a linked machine is
     // relayed, stopped and answered through it. A plain calling task is its
     // parent and started_via only.
     recordStart(session.id, {
@@ -345,29 +367,41 @@ async function startTask(
       .run(wt.worktreePath, wt.branchName, baseBranch, null, id);
     // Everything the launch needs is on the row, so a restart can resume it.
     db.prepare(
-      `UPDATE sessions SET task_prompt = ?, task_brief = ?, task_status = 'running', setup_status = 'running', name_source = ?, view = ?,
-         model_provider = ?, model_overrides = ?, plan_phase = ?, plan_only = ?,
-         plan_decided = ?, plan_reason = ? WHERE id = ?`
+      `UPDATE sessions SET setup_status = 'running', name_source = ?, view = ?, model_provider = ? WHERE id = ?`
     ).run(
-      prompt,
-      buildTaskBrief({
-        branch: wt.branchName,
-        baseBranch,
-        stack: opts.base?.stack,
-        test: declaredTest(wt.worktreePath),
-      }),
       naming.source,
       view,
       routing.first.provider.id === ANTHROPIC
         ? null
         : routing.first.provider.id,
-      routing.override ? JSON.stringify(routing.override) : null,
-      routing.plan ? "planning" : null,
-      routing.planOnly ? 1 : null,
-      routing.planOnly ? 1 : opts.plan === undefined ? null : opts.plan ? 1 : 0,
-      opts.planReason?.trim() || null,
       id
     );
+    setTask(db, id, {
+      task_prompt: prompt,
+      task_brief: buildTaskBrief({
+        branch: wt.branchName,
+        baseBranch,
+        stack: opts.base?.stack,
+        test: declaredTest(wt.worktreePath),
+      }),
+      task_status: "running",
+      model_overrides: routing.override
+        ? JSON.stringify(routing.override)
+        : null,
+    });
+    setPlan(db, id, {
+      plan_phase: routing.plan ? "planning" : null,
+      plan_only: routing.planOnly ? 1 : null,
+      plan_decided: routing.planOnly
+        ? 1
+        : opts.plan === undefined
+          ? null
+          : opts.plan
+            ? 1
+            : 0,
+      plan_reason: opts.planReason?.trim() || null,
+      plan_waits_for_caller: routing.planOnly && opts.planWaits ? 1 : null,
+    });
     recordStart(id, {
       startedBy: opts.startedBy ?? null,
       parentSessionId: opts.parentSessionId ?? null,
@@ -510,7 +544,7 @@ export async function taskView(session: Session): Promise<TaskView> {
 export function movedTasks(): { id: string; movedTo: string | null }[] {
   return db
     .prepare(
-      `SELECT id, moved_to AS movedTo FROM sessions
+      `SELECT id, moved_to AS movedTo FROM session_rows
          WHERE task_status = 'moved' AND host_id = 'local'
          ORDER BY updated_at DESC LIMIT 500`
     )
@@ -522,7 +556,7 @@ export async function listTasks(): Promise<TaskView[]> {
   const sessions = taskSessions(false);
   const [local, remote] = await Promise.all([
     Promise.all(sessions.filter((s) => !isMirror(s)).map(taskView)),
-    remoteTaskViews(sessions.filter(isMirror)),
+    mirrorViews(sessions.filter(isMirror)),
   ]);
   const costs = taskCosts(local.map((t) => t.id));
   for (const t of local) {

package/lib/tasks/launch-gate.ts

@@ -9,7 +9,7 @@ import { db } from "../db";
 export function launchPending(sessionId: string): boolean {
   const row = db
     .prepare(
-      `SELECT 1 FROM sessions WHERE id = ? AND task_status = 'running'
+      `SELECT 1 FROM session_rows WHERE id = ? AND task_status = 'running'
          AND setup_status IN ('running', 'held')`
     )
     .get(sessionId);

package/lib/tasks/move-bundle.ts

@@ -57,6 +57,10 @@ export interface TaskBundle {
   // What a task started by an orchestrator carries besides its work; absent
   // for any other task, or from a machine that predates these moves.
   orchestrated?: OrchestratedBundle;
+  // A plan written and waiting for the machine that placed it (it is moving
+  // there to be built): the plan file, which is never in git. The arriving
+  // machine runs no turn; the approval that follows starts one.
+  planWait?: { file: string | null };
 }
 
 export interface OrchestratedBundle {
@@ -70,7 +74,7 @@ export interface OrchestratedBundle {
   // machine without that provider refuses the task rather than change it.
   modelProvider: string | null;
   modelOverrides: string | null;
-  planPhase: "planning" | "implementing" | null;
+  planPhase: "planning" | "awaiting" | "implementing" | null;
   // .agentos/plan.md, which is never in git.
   planFile: string | null;
   // The orchestrator that holds the task (its id and name on the machine
@@ -153,7 +157,7 @@ function validateChat(c: ChatBundle): ChatBundle {
   return { ...c, plan: !!c.plan };
 }
 
-const PHASES = ["planning", "implementing"];
+const PHASES = ["planning", "awaiting", "implementing"];
 
 export function validateOrchestrated(
   o: OrchestratedBundle
@@ -196,6 +200,16 @@ export function validateOrchestrated(
   };
 }
 
+function validatePlanWait(w: unknown): TaskBundle["planWait"] {
+  if (w === undefined || w === null) return undefined;
+  const file = (w as { file?: unknown }).file;
+  if (typeof w !== "object" || !(file === null || isStr(file)))
+    throw new Error("Bad plan");
+  if ((file?.length ?? 0) > MAX_PLAN_BYTES)
+    throw new Error("The plan is too large to move");
+  return { file };
+}
+
 export function validateBundle(b: TaskBundle): TaskBundle {
   if (!b || typeof b !== "object") throw new Error("No task to import");
   if (!isSessionId(b.moveId)) throw new Error("Bad move id");
@@ -228,6 +242,7 @@ export function validateBundle(b: TaskBundle): TaskBundle {
     orchestrated: b.orchestrated
       ? validateOrchestrated(b.orchestrated)
       : undefined,
+    planWait: validatePlanWait(b.planWait),
     chat: b.chat ? validateChat(b.chat) : undefined,
     name: b.name.slice(0, 200),
     from: String(b.from || "another machine")

package/lib/tasks/move-carry.ts

@@ -10,6 +10,7 @@
 import type Database from "better-sqlite3";
 import { db } from "../db";
 import { orchestratorOf } from "./starter";
+import { fillMissing } from "../db/session-parts";
 
 // table, column, and how the id sits in it: the whole value, `task:<id>`, or
 // the tail of a `<condition>:<id>` key.
@@ -100,15 +101,22 @@ export function carryTaskState(
         .run(fromId.length, toId, `%:${fromId}`);
   }
   const from = handle
-    .prepare(`SELECT * FROM sessions WHERE id = ?`)
+    .prepare(`SELECT * FROM session_rows WHERE id = ?`)
     .get(fromId) as Record<string, unknown> | undefined;
   if (!from) return;
-  const sets = [...CARRIED_COLUMNS, "task_since"]
-    .map((c) => `${c} = COALESCE(${c}, @${c})`)
-    .join(", ");
-  handle.prepare(`UPDATE sessions SET ${sets} WHERE id = @id`).run({
+  const carried = {
     ...orchestrationOf(from),
     task_since: (from.task_since as string | null) ?? from.created_at ?? null,
-    id: toId,
-  });
+  } as Record<string, string | number | null>;
+  handle
+    .prepare(
+      `UPDATE sessions SET started_by = COALESCE(started_by, @started_by),
+         model_provider = COALESCE(model_provider, @model_provider) WHERE id = @id`
+    )
+    .run({
+      started_by: carried.started_by,
+      model_provider: carried.model_provider,
+      id: toId,
+    });
+  fillMissing(handle, toId, carried);
 }