@saadnvd1/agent-os 0.3.631 → 0.3.639

package/lib/tasks/{held-remote.ts → contract/held-calls.ts}

@@ -1,25 +1,22 @@
 /**
- * An orchestrator's calls on a task it moved to a linked machine, which that
- * machine's AgentOS answers for the device that sent the task (held.ts). The
- * orchestrator polls and calls; the other machine never reaches back.
+ * An orchestrator's calls on a task it put on a linked machine, which that
+ * machine's AgentOS answers for the device that sent the task (held.ts). A
+ * machine that doesn't hold the task yet is asked to, once, and the call
+ * repeated. The orchestrator polls and calls; the other machine never reaches
+ * back.
  */
 
-import { db, type Session } from "../db";
+import { db, type Session } from "../../db";
 import {
   HostApiError,
-  cleanRemoteBlock,
-  cleanRemoteText,
-  hostApi,
   hostLink,
   requireHostLink,
-} from "../hosts/remote-api";
-import type { Delivery } from "../bus/delivery";
-import { wakeLine } from "../bus/format";
-import { orchestratedStart } from "./held";
-import { orchestratorOf } from "./starter";
-
-const path = (id: string, leaf: string) =>
-  `/api/tasks/${encodeURIComponent(id)}/${leaf}`;
+} from "../../hosts/remote-api";
+import type { Delivery } from "../../bus/delivery";
+import { wakeLine } from "../../bus/format";
+import { orchestratedStart } from "../held";
+import { orchestratorOf } from "../starter";
+import * as client from "./client";
 
 /**
  * A task its orchestrator put on a linked machine, whether by moving it or
@@ -54,16 +51,11 @@ async function adoptHeld(task: Held): Promise<boolean> {
   if (adopted.has(task.id)) return false;
   adopted.set(task.id, now);
   try {
-    const link = requireHostLink(task.host_id);
-    await hostApi(link, path(task.id, "hold"), {
-      body: {
-        orchestrated: orchestratedStart(
-          task.started_by!,
-          task.task_since ?? null
-        ),
-      },
-      timeout: 20000,
-    });
+    await client.hold(
+      requireHostLink(task.host_id),
+      task.id,
+      orchestratedStart(task.started_by!, task.task_since ?? null)
+    );
   } catch {
     return false;
   }
@@ -72,6 +64,8 @@ async function adoptHeld(task: Held): Promise<boolean> {
   return true;
 }
 
+// compat: task-contract-1. A task the queue placed before machines held them
+// is unheld there; drop this heal once every linked machine holds on start.
 /** The call, held first if that machine says it isn't, once. */
 async function withHold<T>(task: Held, call: () => Promise<T>): Promise<T> {
   try {
@@ -142,16 +136,13 @@ export async function relayToHeldTask(
   try {
     const link = requireHostLink(to.host_id);
     const send = () =>
-      hostApi<{ state?: unknown }>(link, path(to.id, "message"), {
-        body: {
-          id: messageId ? `bus-${messageId}` : undefined,
-          line,
-          from: fromName,
-        },
-        timeout: 20000,
+      client.message(link, to.id, {
+        id: messageId ? `bus-${messageId}` : undefined,
+        line,
+        from: fromName,
       });
-    const { state } = await (heal ? withHold(to, send) : send());
-    return { state: state === "queued" ? "queued" : "delivered" };
+    const state = await (heal ? withHold(to, send) : send());
+    return { state };
   } catch (error) {
     const why = error instanceof Error ? error.message : String(error);
     return { state: "failed", why: why.slice(0, 300) };
@@ -164,15 +155,9 @@ export async function heldChatTail(
   lines: number
 ): Promise<string | null> {
   const link = requireHostLink(task.host_id);
-  const { text } = await withHold(task, () =>
-    hostApi<{ text?: unknown }>(
-      link,
-      `${path(task.id, "chat-tail")}?lines=${lines}`,
-      { timeout: 10000 }
-    )
-  ).catch(() => ({ text: undefined }));
-  // Whole lines, as a local read has them (read.ts caps and trims them).
-  return typeof text === "string" ? cleanRemoteBlock(text, 16000) : null;
+  return withHold(task, () => client.chatTail(link, task.id, lines)).catch(
+    () => null
+  );
 }
 
 /**
@@ -184,38 +169,22 @@ export async function heldChatFacts(
   task: Held
 ): Promise<{ blocked: string | null; turn: string | null } | null> {
   const link = requireHostLink(task.host_id);
-  const res = await withHold(task, () =>
-    hostApi<{ blocked?: unknown; turn?: unknown }>(
-      link,
-      path(task.id, "chat-facts"),
-      { timeout: 10000 }
-    )
-  ).catch(() => null);
-  if (!res || (res.blocked !== null && typeof res.blocked !== "string"))
-    return null;
-  if (res.turn !== null && typeof res.turn !== "string") return null;
-  return {
-    blocked: res.blocked ? cleanRemoteBlock(res.blocked, 2000) : null,
-    turn: res.turn,
-  };
+  return withHold(task, () => client.chatFacts(link, task.id)).catch(
+    () => null
+  );
 }
 
 /** Stops its agent there; its conversation and worktree are kept. */
 export async function stopHeldTask(task: Held): Promise<string> {
   const link = requireHostLink(task.host_id);
-  const { text } = await withHold(task, () =>
-    hostApi<{ text?: unknown }>(link, path(task.id, "stop"), {
-      body: {},
-      timeout: 30000,
-    })
+  return (
+    (await withHold(task, () => client.stop(link, task.id))) ||
+    `Stopped ${task.name}.`
   );
-  return cleanRemoteText(text) || `Stopped ${task.name}.`;
 }
 
 /** Done there: its agent stops and its worktree goes. Never a merge. */
 export async function doneHeldTask(task: Held): Promise<void> {
   const link = requireHostLink(task.host_id);
-  await withHold(task, () =>
-    hostApi(link, path(task.id, "done"), { body: {}, timeout: 120000 })
-  );
+  await withHold(task, () => client.done(link, task.id));
 }

package/lib/tasks/contract/index.ts

@@ -0,0 +1,28 @@
+/**
+ * How a task runs on a linked machine: one client for its API
+ * (client.ts), one authorization rule per route (authorize.ts), one loop that
+ * keeps mirrors current (sync.ts). Local code paths call these through the
+ * entry points they already had (signOff, dropTask, deliver, ...).
+ */
+
+export * as taskClient from "./client";
+export { TASK_CAPABILITIES, type HostTasks } from "./types";
+export {
+  isMirror,
+  mirrorTask,
+  startRemoteTask,
+  setMirrorStatus,
+} from "./start";
+export { mergeThere, dropThere } from "./actions";
+export { mirrorViews } from "./views";
+export { syncMirrors } from "./sync";
+export { taskRoute, refuse, callerRefusal, type Rule } from "./authorize";
+export {
+  isHeldRemote,
+  relayToHeldTask,
+  heldChatTail,
+  heldChatFacts,
+  stopHeldTask,
+  doneHeldTask,
+  flushUndelivered,
+} from "./held-calls";

package/lib/tasks/contract/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 (contract/plan.ts).
+export const remotePlanPath = (sessionId: string) =>
+  path.join(plansDir(), "remote", `${sessionId}.md`);

package/lib/tasks/contract/plan.ts

@@ -0,0 +1,274 @@
+/**
+ * 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/promises";
+import path from "path";
+import { db, type Session } from "../../db";
+import { isRemoteHost } from "../../hosts";
+import { peerSource } from "../../hosts/peer-load";
+import { 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 { moveTask } from "../move-flow";
+import * as client from "./client";
+import { meetsNeeds, needsOf } from "../placement";
+import { remotePlanPath } from "./plan-path";
+import { DEFAULT_PRIORITY, isPriority } from "../schedule-types";
+import { localHolds } from "../hold-checks";
+import { expandHome } from "../session";
+import { orchestratorOf } from "../starter";
+import { setPlan } from "../../db/session-parts";
+
+export { remotePlanPath };
+
+const getSession = (id: string) =>
+  db.prepare(`SELECT * FROM session_rows WHERE id = ?`).get(id) as
+    | Session
+    | undefined;
+
+async function readCopy(id: string): Promise<string | null> {
+  try {
+    return await fs.readFile(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";
+}
+
+/**
+ * A mirror that is planning, its machine's listing of it in hand: if its plan
+ * is written there, copy it, say so, and carry on for a plan-first task.
+ */
+export async function planWritten(
+  s: Session,
+  view: { planReady?: boolean } | undefined
+): Promise<void> {
+  const link = hostLink(s.host_id);
+  if (!link || !view?.planReady) return;
+  const text = await client.plan(link, s.id);
+  const claimed = setPlan(
+    db,
+    s.id,
+    { plan_phase: "awaiting" },
+    { plan_phase: "planning" }
+  );
+  if (!claimed) return;
+  if (text !== null) {
+    await fs.mkdir(path.dirname(remotePlanPath(s.id)), { recursive: true });
+    await fs.writeFile(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);
+  setPlan(db, s.id, { plan_note: note });
+  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 continuePlanThere(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 continuePlanThere(
+  s: Session,
+  message?: string
+): Promise<string> {
+  const link = requireHostLink(s.host_id!);
+  const split = checkedSplit(s, await readCopy(s.id));
+  if (implementTarget(s, split) === "there") {
+    const out = await client.approvePlan(link, s.id, message);
+    setPlan(
+      db,
+      s.id,
+      { plan_phase: "implementing" },
+      { plan_phase: "awaiting" }
+    );
+    client.forget(link.hostId);
+    return out.model ?? link.hostName;
+  }
+  setPlan(
+    db,
+    s.id,
+    { plan_phase: "handoff", plan_handoff_message: message ?? null },
+    { plan_phase: "awaiting" }
+  );
+  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";
+}
+
+export const handingOff = new Set<string>();
+
+export async function finishArrival(
+  id: string,
+  message?: string
+): Promise<boolean> {
+  await implementArrived(id, message || undefined);
+  setPlan(db, id, { plan_handoff_message: null });
+  return true;
+}
+
+// Fired, not awaited: a move takes minutes and the queue tick must not wait.
+export 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 syncMirrors.
+    setPlan(db, arrived.id, {
+      plan_edits: edits ?? undefined,
+      plan_handoff_message: message ?? "",
+    });
+    handingOff.add(arrived.id);
+    try {
+      return await finishArrival(arrived.id, message);
+    } finally {
+      handingOff.delete(arrived.id);
+    }
+  } finally {
+    handingOff.delete(id);
+  }
+}

package/lib/tasks/contract/routes.ts

@@ -0,0 +1,26 @@
+/** The task routes a linked machine's AgentOS answers, and how long to wait for each. */
+
+export const taskPath = (id: string, leaf: string) =>
+  `/api/tasks/${encodeURIComponent(id)}/${leaf}`;
+
+export const LIST = "/api/tasks";
+export const IMPORT = "/api/tasks/import";
+export const HELD_REPLIES = "/api/tasks/held-replies";
+export const arrivedPath = (from: string) =>
+  `/api/tasks/arrived?from=${encodeURIComponent(from)}`;
+
+export const TIMEOUT = {
+  list: 8000,
+  start: 180000,
+  plan: 30000,
+  approvePlan: 60000,
+  message: 20000,
+  hold: 20000,
+  chat: 10000,
+  stop: 30000,
+  done: 120000,
+  merge: 300000,
+  replies: 8000,
+  exportOut: 300000,
+  importBundle: 600000,
+} as const;

package/lib/tasks/contract/start.ts

@@ -0,0 +1,122 @@
+/**
+ * Tasks that run on another machine's AgentOS. That machine schedules them;
+ * this one keeps a mirror row (same id, the host's id) so the sidebar lists
+ * them and the terminal attaches through that machine's AgentOS.
+ */
+
+import { db, type Project, type Session } from "../../db";
+import { isRemoteHost } from "../../hosts";
+import { requireHostLink } from "../../hosts/remote-api";
+import { orchestratedStart } from "../held";
+import { projectRef } from "../project-ref";
+import { orchestratorOf } from "../starter";
+import type { TaskStatus } from "../state";
+import * as client from "./client";
+import { setPlan, setTask, startTaskClock } from "../../db/session-parts";
+
+export function isMirror(session: Session): boolean {
+  return isRemoteHost(session.host_id);
+}
+
+export function mirrorTask(
+  hostId: string,
+  projectId: string | null,
+  remote: Session,
+  startedBy?: string | null
+): void {
+  db.transaction(() => {
+    const inserted = db
+      .prepare(
+        `INSERT INTO sessions (id, name, tmux_name, working_directory, model, group_path,
+           agent_type, auto_approve, project_id, host_id, worktree_path, branch_name,
+           base_branch, name_source, view)
+         VALUES (?, ?, ?, ?, ?, 'sessions', 'claude', 1, ?, ?, ?, ?, ?, 'user', ?)
+         ON CONFLICT(id) DO NOTHING`
+      )
+      .run(
+        remote.id,
+        remote.name,
+        remote.tmux_name,
+        remote.working_directory,
+        remote.model,
+        projectId,
+        hostId,
+        remote.worktree_path,
+        remote.branch_name,
+        remote.base_branch,
+        // As that machine runs it: one that predates chat tasks says terminal.
+        remote.view === "chat" ? "chat" : "terminal"
+      );
+    if (inserted.changes)
+      setTask(db, remote.id, {
+        task_prompt: remote.task_prompt,
+        task_status: "running",
+      });
+    // What carryTaskState gives a moved task's mirror: the orchestrator that
+    // holds it, and when it began (so its PR is judged from then).
+    if (startedBy) {
+      db.prepare(
+        `UPDATE sessions SET started_by = COALESCE(started_by, ?) WHERE id = ?`
+      ).run(startedBy, remote.id);
+      startTaskClock(db, remote.id);
+    }
+  })();
+}
+
+export async function startRemoteTask(
+  hostId: string,
+  project: Project,
+  opts: {
+    id: string;
+    prompt: string;
+    name?: string;
+    model?: string;
+    baseBranch?: string;
+    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, plan, ...rest } = opts;
+  const startedBy = orchestratorOf(by);
+  if (startedBy)
+    await client.requireCapability(
+      link,
+      "held-start",
+      "an orchestrator's task",
+      "hold"
+    );
+  if (plan)
+    await client.requireCapability(link, "remote-plan", "a plan step", "plan");
+  const { session } = await client.start(link, {
+    project: await projectRef(project),
+    ...rest,
+    ...(plan && {
+      plan: true,
+      plan_only: true,
+      plan_waits: true,
+      plan_reason: plan.reason ?? undefined,
+    }),
+    orchestrated: startedBy ? orchestratedStart(startedBy) : undefined,
+  });
+  mirrorTask(hostId, project.id, session, startedBy);
+  if (plan)
+    setPlan(db, session.id, {
+      plan_phase: "planning",
+      plan_only: plan.only ? 1 : null,
+      plan_decided: 1,
+      plan_reason: plan.reason,
+      plan_waits_for_caller: 1,
+    });
+  client.forget(hostId);
+  return db
+    .prepare(`SELECT * FROM session_rows WHERE id = ?`)
+    .get(session.id) as Session;
+}
+
+export function setMirrorStatus(id: string, status: TaskStatus): void {
+  setTask(db, id, { task_status: status }, { task_status: "running" });
+}