@saadnvd1/agent-os 0.3.631 → 0.3.637

package/lib/tasks/remote-plan-path.ts

@@ -0,0 +1,7 @@
+import path from "path";
+import { plansDir } from "../plans/features";
+
+// A plan written on a linked machine, copied here so this machine's
+// orchestrator and plan view can read it (remote-plan.ts).
+export const remotePlanPath = (sessionId: string) =>
+  path.join(plansDir(), "remote", `${sessionId}.md`);

package/lib/tasks/remote-plan.ts

@@ -0,0 +1,308 @@
+/**
+ * A plan placed on a linked machine (queue placement, remote.ts). Planning
+ * only reads code, so it runs wherever there is room; what follows the plan
+ * is decided here, on the machine whose scheduler, needs and workspace apply.
+ * The other machine plans, stops, and waits. This machine then copies the
+ * plan, says it is written, and either approves it there (the task is built
+ * where it planned) or moves the task here once this machine can take it
+ * (it needs a Mac, or its plan is split into pieces, which register here).
+ * Moving the task reuses the ordinary move (move-flow.ts).
+ */
+
+import fs from "fs";
+import path from "path";
+import { db, type Session } from "../db";
+import { isRemoteHost } from "../hosts";
+import { peerSource } from "../hosts/peer-load";
+import { hostApi, hostLink, requireHostLink } from "../hosts/remote-api";
+import { LOCAL, machineCapabilities } from "../load/machines";
+import { noApprovalsOn, recordAutoApproval } from "../approvals/no-approvals";
+import { implementArrived, planNoteFor } from "../models/plan-step";
+import { sessionWorkspace } from "../models/resolve";
+import { queueEvent } from "../orchestrator/events";
+import { brakesOn } from "../orchestrator/brakes";
+import { isPaused } from "../orchestrator/pause";
+import { getProject } from "../projects";
+import { planFor, splitOf } from "../plans/features";
+import { forgetHostTasks, hostTasks } from "./remote";
+import { moveTask } from "./move-flow";
+import { meetsNeeds, needsOf } from "./placement";
+import { remotePlanPath } from "./remote-plan-path";
+import { DEFAULT_PRIORITY, isPriority } from "./schedule-types";
+import { localHolds } from "./hold-checks";
+import { expandHome } from "./session";
+import { orchestratorOf } from "./starter";
+
+export { remotePlanPath };
+
+const getSession = (id: string) =>
+  db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(id) as
+    | Session
+    | undefined;
+
+function readCopy(id: string): string | null {
+  try {
+    return fs.readFileSync(remotePlanPath(id), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function checkedSplit(s: Session, text: string | null) {
+  try {
+    return text ? splitOf(s, text) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Where a written plan is built: "there" (approved on the machine that
+ * planned it) or "home" (moved here first). Pieces are checked against this
+ * machine's projects, and work that needs a Mac can't be built on a machine
+ * without one, so those come home; everything else stays where it is, since
+ * the machine that planned it is the one with room.
+ */
+export function implementTarget(
+  s: Session,
+  split: ReturnType<typeof splitOf>
+): "there" | "home" {
+  const project = s.project_id ? getProject(s.project_id) : null;
+  // The project lives there: nothing here to build it in.
+  if (!project || isRemoteHost(project.host_id)) return "there";
+  if (split) return "home";
+  const { needs } = needsOf({
+    projectId: project.id,
+    projectPath: expandHome(project.working_directory),
+    prompt: s.task_prompt ?? "",
+  });
+  const caps = peerSource(s.host_id!, Date.now()).capabilities;
+  if (meetsNeeds(needs, caps)) return "there";
+  return meetsNeeds(needs, machineCapabilities()) ? "home" : "there";
+}
+
+// One look at a mirror that is planning: if its plan is written there, copy
+// it, say so, and carry on for a plan-first task.
+async function planWritten(s: Session): Promise<void> {
+  const link = hostLink(s.host_id);
+  if (!link) return;
+  const view = await hostTasks(link)
+    .then(({ tasks }) => tasks.find((t) => t?.id === s.id))
+    .catch(() => undefined);
+  if (!view?.planReady) return;
+  const { text } = await hostApi<{ text: string | null }>(
+    link,
+    `/api/tasks/${encodeURIComponent(s.id)}/plan`,
+    { timeout: 30000 }
+  );
+  const claimed = db
+    .prepare(
+      `UPDATE sessions SET plan_phase = 'awaiting' WHERE id = ? AND plan_phase = 'planning'`
+    )
+    .run(s.id).changes;
+  if (!claimed) return;
+  if (text !== null) {
+    fs.mkdirSync(path.dirname(remotePlanPath(s.id)), { recursive: true });
+    fs.writeFileSync(remotePlanPath(s.id), text);
+  }
+  const fresh = getSession(s.id)!;
+  const split = checkedSplit(fresh, text);
+  const errors = split?.errors ?? [];
+  // As for a task planned here: a plan-first task goes on by itself, a
+  // plan-only one waits unless no-approvals is on, and pieces that couldn't
+  // be registered always hold it.
+  const auto = !!fresh.plan_only && noApprovalsOn();
+  const goOn = (!fresh.plan_only || auto) && !errors.length;
+  const target = goOn ? implementTarget(fresh, split) : null;
+  const next =
+    target === "there"
+      ? `implementing on ${hostLink(s.host_id)?.hostName ?? "that machine"}`
+      : target === "home"
+        ? "moving here to implement once this machine is free"
+        : "waiting for approval, not implementing (approve_plan to go ahead, drop to reject)";
+  const note = planNoteFor(fresh, remotePlanPath(s.id), next);
+  db.prepare(`UPDATE sessions SET plan_note = ? WHERE id = ?`).run(note, s.id);
+  const workspaceId = sessionWorkspace(fresh);
+  if (orchestratorOf(fresh.started_by) && workspaceId) {
+    queueEvent(workspaceId, `plan-done:${s.id}`, s.id, note);
+    if (errors.length)
+      queueEvent(
+        workspaceId,
+        `plan-pieces:${s.id}`,
+        s.id,
+        `Plan of "${s.name}": couldn't register its pieces: ${errors.join("; ")}. It is held, not building. Message the task to fix the plan, or approve_plan to build it as one piece.`
+      );
+  }
+  if (!goOn) {
+    try {
+      const planned = text ? planFor(fresh, text) : null;
+      (await import("../notify/push/events")).pushPlanAwaiting(
+        s.id,
+        s.name,
+        planned?.pieces.length ?? 1
+      );
+    } catch (e) {
+      console.error("plan push failed:", e);
+    }
+    return;
+  }
+  await continueRemotePlan(fresh);
+  if (auto)
+    recordAutoApproval({
+      source: "plan",
+      workspaceId,
+      sessionId: s.id,
+      subject: `plan for ${s.name}`,
+      detail: "implementing without waiting for approve_plan",
+    });
+}
+
+/**
+ * Carries a written plan on: approves it on the machine that planned it, or
+ * hands it to the move home. Returns what it will implement on.
+ */
+export async function continueRemotePlan(
+  s: Session,
+  message?: string
+): Promise<string> {
+  const link = requireHostLink(s.host_id!);
+  const split = checkedSplit(s, readCopy(s.id));
+  if (implementTarget(s, split) === "there") {
+    const out = await hostApi<{ model?: string }>(
+      link,
+      `/api/tasks/${encodeURIComponent(s.id)}/approve-plan`,
+      { body: message ? { message } : {}, timeout: 60000 }
+    );
+    db.prepare(
+      `UPDATE sessions SET plan_phase = 'implementing' WHERE id = ? AND plan_phase = 'awaiting'`
+    ).run(s.id);
+    forgetHostTasks(link.hostId);
+    return out.model ?? link.hostName;
+  }
+  db.prepare(
+    `UPDATE sessions SET plan_phase = 'handoff', plan_handoff_message = ?
+     WHERE id = ? AND plan_phase = 'awaiting'`
+  ).run(message ?? null, s.id);
+  const workspaceId = sessionWorkspace(s);
+  if (orchestratorOf(s.started_by) && workspaceId)
+    queueEvent(
+      workspaceId,
+      `plan-handoff:${s.id}`,
+      s.id,
+      `Task "${s.name}": plan approved; it moves here to be built once this machine is free (${split ? "its plan is in pieces" : "it needs this machine"}).`
+    );
+  void handoffHome(s.id).catch((e) =>
+    console.error(`Moving ${s.id} here failed:`, e)
+  );
+  return "this machine, once it is free";
+}
+
+const handingOff = new Set<string>();
+
+async function finishArrival(id: string, message?: string): Promise<boolean> {
+  await implementArrived(id, message || undefined);
+  db.prepare(
+    `UPDATE sessions SET plan_handoff_message = NULL WHERE id = ?`
+  ).run(id);
+  return true;
+}
+
+// Fired, not awaited: a move takes minutes and the queue tick must not wait.
+function fire(id: string, run: () => Promise<unknown>) {
+  if (handingOff.has(id)) return;
+  void run().catch((e) => console.error(`Moving ${id} here failed:`, e));
+}
+
+/**
+ * Moves an approved plan's task here, when this machine can take it, and
+ * starts implementing. False while the machine is loaded (tried again on the
+ * next look) or another call has it.
+ */
+export async function handoffHome(
+  id: string,
+  now = Date.now()
+): Promise<boolean> {
+  const s = getSession(id);
+  if (!s || s.plan_phase !== "handoff" || !isRemoteHost(s.host_id))
+    return false;
+  if (handingOff.has(id)) return false;
+  const project = s.project_id ? getProject(s.project_id) : null;
+  if (!project) return false;
+  // What an orchestrator started stays under its Pause and brakes.
+  const workspaceId = sessionWorkspace(s);
+  if (workspaceId && orchestratorOf(s.started_by)) {
+    if (isPaused(workspaceId)) return false;
+    if ((await brakesOn(workspaceId)).length) return false;
+  }
+  const { needs } = needsOf({
+    projectId: project.id,
+    projectPath: expandHome(project.working_directory),
+    prompt: s.task_prompt ?? "",
+  });
+  const holds = localHolds(
+    {
+      needs,
+      priority: isPriority(s.priority) ? s.priority : DEFAULT_PRIORITY,
+    },
+    now
+  );
+  if (holds.length) return false;
+  handingOff.add(id);
+  try {
+    const message = s.plan_handoff_message ?? undefined;
+    const edits = s.plan_edits ?? null;
+    const arrived = await moveTask(id, LOCAL);
+    // The arrived row keeps the pending hand-off until implementing has
+    // started, so a restart in between is picked up by syncRemotePlans.
+    db.prepare(
+      `UPDATE sessions SET plan_edits = COALESCE(?, plan_edits), plan_handoff_message = ? WHERE id = ?`
+    ).run(edits, message ?? "", arrived.id);
+    handingOff.add(arrived.id);
+    try {
+      return await finishArrival(arrived.id, message);
+    } finally {
+      handingOff.delete(arrived.id);
+    }
+  } finally {
+    handingOff.delete(id);
+  }
+}
+
+/** Every mirror whose plan is being written, or approved and coming here. */
+export async function syncRemotePlans(): Promise<void> {
+  const rows = db
+    .prepare(
+      `SELECT * FROM sessions
+       WHERE plan_waits_for_caller = 1 AND plan_phase IN ('planning', 'handoff')
+         AND task_status = 'running' AND archived_at IS NULL`
+    )
+    .all() as Session[];
+  for (const s of rows) {
+    if (!isRemoteHost(s.host_id)) continue;
+    try {
+      if (s.plan_phase === "planning") await planWritten(s);
+      else fire(s.id, () => handoffHome(s.id));
+    } catch (e) {
+      console.error(`Plan on ${s.host_id} for ${s.id} failed:`, e);
+    }
+  }
+  // A task that arrived but never began implementing (a restart between).
+  const arrived = db
+    .prepare(
+      `SELECT id, plan_handoff_message FROM sessions
+       WHERE plan_phase = 'awaiting' AND plan_handoff_message IS NOT NULL
+         AND task_status = 'running' AND archived_at IS NULL AND peer_mirror IS NOT 1`
+    )
+    .all() as { id: string; plan_handoff_message: string }[];
+  for (const a of arrived) {
+    if (isRemoteHost(getSession(a.id)?.host_id)) continue;
+    fire(a.id, async () => {
+      handingOff.add(a.id);
+      try {
+        await finishArrival(a.id, a.plan_handoff_message);
+      } finally {
+        handingOff.delete(a.id);
+      }
+    });
+  }
+}

package/lib/tasks/remote.ts

@@ -38,6 +38,9 @@ export const TASK_CAPABILITIES = [
   // A keyed start that carries an orchestrator's description holds the task
   // for the device that sent it, as a move does (lib/tasks/held.ts).
   "held-start",
+  // A plan placed here by another machine stops at the plan for that machine
+  // to decide what follows (lib/tasks/remote-plan.ts).
+  "remote-plan",
 ] as const;
 
 export interface HostTasks {
@@ -138,10 +141,12 @@ export async function startRemoteTask(
     view?: "chat" | "terminal";
     // The orchestrator that started it: that machine holds the task for it.
     startedBy?: string | null;
+    // It plans first: there it plans, stops, and waits for this machine.
+    plan?: { only: boolean; reason: string | null };
   }
 ): Promise<Session> {
   const link = requireHostLink(hostId);
-  const { startedBy: by, ...rest } = opts;
+  const { startedBy: by, plan, ...rest } = opts;
   const startedBy = orchestratorOf(by);
   if (startedBy)
     await requireCapability(
@@ -150,17 +155,29 @@ export async function startRemoteTask(
       "an orchestrator's task",
       "hold"
     );
+  if (plan) await requireCapability(link, "remote-plan", "a plan step", "plan");
   const { session } = await postIdempotent<{ session: Session }>(
     link,
     "/api/tasks",
     {
       project: await projectRef(project),
       ...rest,
+      ...(plan && {
+        plan: true,
+        plan_only: true,
+        plan_waits: true,
+        plan_reason: plan.reason ?? undefined,
+      }),
       orchestrated: startedBy ? orchestratedStart(startedBy) : undefined,
     },
     180000
   );
   mirrorTask(hostId, project.id, session, startedBy);
+  if (plan)
+    db.prepare(
+      `UPDATE sessions SET plan_phase = 'planning', plan_only = ?, plan_decided = 1,
+         plan_reason = ?, plan_waits_for_caller = 1 WHERE id = ?`
+    ).run(plan.only ? 1 : null, plan.reason, session.id);
   forgetHostTasks(hostId);
   return db
     .prepare(`SELECT * FROM sessions WHERE id = ?`)

package/lib/tasks/schedule.ts

@@ -13,59 +13,33 @@ import {
   PRIORITY_LABEL,
   type Priority,
   type QueueExplainView,
-  type WaitCode,
 } from "./schedule-types";
+import {
+  PRIORITY_POINTS,
+  holdsFor,
+  type Hold,
+  type MachineView,
+} from "./holds";
 
 export { PRIORITIES, DEFAULT_PRIORITY } from "./schedule-types";
 export type { Priority, WaitCode } from "./schedule-types";
+export {
+  AMBER_MIN_PRIORITY,
+  HEAVY_START_GAP_MS,
+  LOAD_SETTLE_MS,
+  PRIORITY_POINTS,
+  START_GAP_MS,
+  machineHold,
+  slotText,
+  type Hold,
+  type MachineLevel,
+  type MachineView,
+} from "./holds";
 
-export const PRIORITY_POINTS: Record<Priority, number> = {
-  urgent: 400,
-  blocking: 300,
-  normal: 200,
-  background: 100,
-};
 export const AGE_POINTS_PER_MIN = 0.5;
 // Reached after five hours of waiting.
 export const AGE_CAP = 150;
 export const RESUME_BONUS = 150;
-// 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 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 interface Hold {
-  code: WaitCode;
-  text: string;
-}
-
 export interface Candidate {
   id: string;
   kind: "start" | "resume";
@@ -88,7 +62,7 @@ export interface Candidate {
   // `after X` hold, from the caller (it needs the database).
   before: Hold | null;
   // Orchestrator Pause and the usage window, which hold after `after`.
-  auto: Hold | null;
+  auto: Hold | readonly Hold[] | null;
   // "After any": its set, the ones that have finished, the ones other waiters
   // already used, and whether it was already released (a retry).
   any: {
@@ -110,6 +84,8 @@ export interface Plan {
   // The finish an "after any" waiter takes, by candidate id (null: none left).
   consume: Map<string, string | null>;
   explain: Map<string, QueueExplainView>;
+  // Every hold on each candidate, in order (empty: it starts).
+  holds: Map<string, Hold[]>;
 }
 
 export function scoreParts(
@@ -124,75 +100,6 @@ export function scoreParts(
   return { priority, age, resume, score: priority + age + resume };
 }
 
-const priorityRank = (p: Priority) => PRIORITY_POINTS[p] ?? 0;
-
-const seconds = (ms: number) => Math.max(1, Math.ceil(ms / 1000));
-
-// The machine holds, in order. Null: it may start here now.
-export function machineHold(
-  c: Pick<Candidate, "heavy" | "needsUnmet" | "remote" | "priority"> &
-    Partial<Pick<Candidate, "planOnly">>,
-  m: MachineView,
-  now: number
-): Hold | null {
-  if (c.remote || c.planOnly) return null;
-  if (c.needsUnmet) return { code: "needs", text: `Waiting: needs a Mac` };
-  if (!m.enabled) return null;
-  if (m.reading)
-    return { code: "load_red", text: "Waiting: reading machine load" };
-  if (m.level === "red")
-    return { code: "load_red", text: `Waiting: ${m.label} load red` };
-  if (!m.settled)
-    return {
-      code: "load_red",
-      text: `Waiting: ${m.label} load was red; calm for ${seconds(m.settleLeftMs)}s more`,
-    };
-  if (
-    m.level === "amber" &&
-    priorityRank(c.priority) < priorityRank(AMBER_MIN_PRIORITY)
-  )
-    return {
-      code: "load_amber",
-      text: `Waiting: ${m.label} load amber; ${c.priority} work starts on green`,
-    };
-  if (c.heavy) {
-    if (m.level !== "green")
-      return {
-        code: "heavy",
-        text: `Waiting: ${m.label} load amber; simulator work starts on green`,
-      };
-    if (m.heavyStarting > 0)
-      return {
-        code: "heavy",
-        text: `Waiting: a simulator is booting on ${m.label}`,
-      };
-    if (m.booted >= m.maxBooted)
-      return {
-        code: "heavy",
-        text: `Waiting: ${m.booted} of ${m.maxBooted} simulators in use`,
-      };
-    if (
-      m.lastHeavyStartAt !== null &&
-      now - m.lastHeavyStartAt < HEAVY_START_GAP_MS
-    )
-      return {
-        code: "heavy",
-        text: `Waiting: a simulator task just started on ${m.label} (next in ${seconds(HEAVY_START_GAP_MS - (now - m.lastHeavyStartAt))}s)`,
-      };
-  }
-  if (m.lastAutoStartAt !== null && now - m.lastAutoStartAt < START_GAP_MS)
-    return {
-      code: "spacing",
-      text: `Waiting: spacing starts (next in ${seconds(START_GAP_MS - (now - m.lastAutoStartAt))}s)`,
-    };
-  return null;
-}
-
-export function slotText(rank: number, of: number, priority: Priority): string {
-  const word = priority === DEFAULT_PRIORITY ? "" : ` · ${priority}`;
-  return `#${rank} of ${of}${word}`;
-}
-
 export function priorityWord(priority: Priority): string {
   return PRIORITY_LABEL[priority];
 }
@@ -204,7 +111,12 @@ export function planStarts(
   machine: MachineView,
   now: number
 ): Plan {
-  const plan: Plan = { start: [], consume: new Map(), explain: new Map() };
+  const plan: Plan = {
+    start: [],
+    consume: new Map(),
+    explain: new Map(),
+    holds: new Map(),
+  };
   const m: MachineView = { ...machine };
   const byGroup = new Map<string, Candidate[]>();
   for (const c of candidates)
@@ -218,26 +130,27 @@ export function planStarts(
     const scored = list
       .map((c) => ({ c, ...scoreParts(c, now) }))
       .sort((a, b) => b.score - a.score || a.c.position - b.c.position);
-    scored.forEach(({ c, score, priority: _p }, index) => {
-      const rank = index + 1;
-      const hold = holdOf(c);
-      const view = (h: Hold | null): QueueExplainView => ({
-        code: h?.code ?? null,
-        text: h?.text ?? null,
+    scored.forEach(({ c, score }, index) => {
+      const holds = holdsFor(c, {
+        machine: m,
+        now,
+        used,
+        inFlight,
+        limit: group.limit,
+        rank: index + 1,
+        of: scored.length,
+      });
+      const hold = holds[0] ?? null;
+      plan.holds.set(c.id, holds);
+      plan.explain.set(c.id, {
+        code: hold?.code ?? null,
+        text: hold?.text ?? null,
         score: Math.round(score * 10) / 10,
-        rank,
+        rank: index + 1,
         of: scored.length,
         priority: c.priority,
       });
-      if (hold) return void plan.explain.set(c.id, view(hold));
-      if (!c.planOnly && inFlight >= group.limit)
-        return void plan.explain.set(
-          c.id,
-          view({
-            code: "slot",
-            text: slotText(rank, scored.length, c.priority),
-          })
-        );
+      if (hold) return;
       // Passed every hold: it starts.
       if (c.any && !c.any.released) {
         const free = c.any.finished.find((id) => !used.has(id)) ?? null;
@@ -253,23 +166,7 @@ export function planStarts(
         }
       }
       plan.start.push(c.id);
-      plan.explain.set(c.id, view(null));
     });
   }
   return plan;
-
-  function holdOf(c: Candidate): Hold | null {
-    if (c.before) return c.before;
-    if (c.any && !c.any.released) {
-      const free = c.any.finished.some((id) => !used.has(id));
-      const spent =
-        c.any.ids.length > 0 && c.any.finished.length === c.any.ids.length;
-      if (!free && !spent)
-        return {
-          code: "after_any",
-          text: `Waiting: after any running task (${c.any.label})`,
-        };
-    }
-    return c.auto ?? machineHold(c, m, now);
-  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.631",
+  "version": "0.3.637",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"