@saadnvd1/agent-os 0.3.578 → 0.3.580

package/app/api/tasks/[id]/hold/route.ts

@@ -0,0 +1,28 @@
+import { NextRequest, NextResponse } from "next/server";
+import { callingDevice } from "@/lib/security/device-me";
+import { holdExisting } from "@/lib/tasks/held";
+import { validateOrchestrated } from "@/lib/tasks/move-bundle";
+
+// POST /api/tasks/:id/hold - the paired device whose orchestrator started a
+// task here asks to hold it, as a move would have: for a queue-placed task
+// started before holding existed. It never starts a task.
+export async function POST(
+  request: NextRequest,
+  ctx: { params: Promise<{ id: string }> }
+) {
+  const id = (await ctx.params).id;
+  const device = callingDevice(request);
+  if (!device)
+    return NextResponse.json(
+      { error: "An orchestrator's task comes only from a paired machine" },
+      { status: 403 }
+    );
+  try {
+    const { orchestrated } = await request.json();
+    const held = holdExisting(id, device, validateOrchestrated(orchestrated));
+    return NextResponse.json({ held }, { status: held ? 200 : 404 });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return NextResponse.json({ error: message }, { status: 400 });
+  }
+}

package/app/api/tasks/route.ts

@@ -5,7 +5,12 @@ import { stampPriority, startOrQueue } from "@/lib/tasks/queue";
 import { isPriority } from "@/lib/tasks/schedule-types";
 import { TASK_CAPABILITIES } from "@/lib/tasks/remote";
 import { ensureProject, type ProjectRef } from "@/lib/tasks/project-ref";
-import { isSessionId, statusFor } from "@/lib/tasks/move-bundle";
+import { callingDevice } from "@/lib/security/device-me";
+import {
+  isSessionId,
+  statusFor,
+  validateOrchestrated,
+} from "@/lib/tasks/move-bundle";
 import { startView } from "@/lib/sessions/launch";
 import { isValidAgentType } from "@/lib/providers";
 import { isAgentModelName } from "@/lib/providers/registry";
@@ -43,6 +48,7 @@ export async function POST(request: NextRequest) {
       plan_only,
       priority,
       machine,
+      orchestrated,
     } = await request.json();
     if (id !== undefined && !isSessionId(id)) throw new Error("Bad task id");
     const pid =
@@ -81,7 +87,26 @@ export async function POST(request: NextRequest) {
       view: startView(view),
     };
     if (id !== undefined) {
-      const session = await createTask({ id, ...opts });
+      // An orchestrator's task is held for the paired device that sent it,
+      // as a moved one is (lib/tasks/held.ts).
+      const device = callingDevice(request);
+      let held;
+      if (orchestrated !== undefined) {
+        if (!device)
+          return NextResponse.json(
+            {
+              error: "An orchestrator's task comes only from a paired machine",
+            },
+            { status: 403 }
+          );
+        held = { device, orchestrated: validateOrchestrated(orchestrated) };
+      }
+      const session = await createTask({
+        id,
+        ...opts,
+        held,
+        startedByDevice: device ?? undefined,
+      });
       return NextResponse.json({ session }, { status: 201 });
     }
     const out = await startOrQueue(

package/lib/bus/index.ts

@@ -14,9 +14,14 @@ import { previousNames } from "../session-names";
 import { deliverToPane, type Delivery } from "./delivery";
 import { resolveRef, wasNames, type Candidate } from "./resolve";
 import { tmuxPane } from "./tmux-pane";
-import { hostLink } from "../hosts/remote-api";
 import { pauseHoldOf, pausedNote } from "../tasks/pause-hold";
-import { relayToHeldTask } from "../tasks/held-remote";
+import { isHeldRemote, relayToHeldTask } from "../tasks/held-remote";
+import {
+  assertTakesMessages,
+  findQueuedTarget,
+  heldQueuedNote,
+  type QueuedTarget,
+} from "../tasks/queue-held";
 import { heldOrchestrator, heldTarget } from "./held-reply";
 import { HUMAN, overRateLimit, wakeLine, type BusMessageView } from "./format";
 
@@ -115,13 +120,29 @@ export function resolveTarget(ref: string): {
   session: Session;
   note?: string;
 } {
+  const found = tryResolveTarget(ref);
+  if (!found.ok) throw new Error(found.error);
+  return found;
+}
+
+function tryResolveTarget(
+  ref: string
+):
+  | { ok: true; session: Session; note?: string }
+  | { ok: false; none: boolean; error: string } {
   const sessions = liveSessions();
   const r = resolveRef(ref, candidates(sessions));
   if (!r.ok)
-    throw new Error(
-      r.reason === "none" ? `${r.error}. Run: aos peers` : r.error
-    );
-  return { session: sessions.find((s) => s.id === r.id)!, note: r.note };
+    return {
+      ok: false,
+      none: r.reason === "none",
+      error: r.reason === "none" ? `${r.error}. Run: aos peers` : r.error,
+    };
+  return {
+    ok: true,
+    session: sessions.find((s) => s.id === r.id)!,
+    note: r.note,
+  };
 }
 
 export function resolveSession(ref: string): Session {
@@ -188,7 +209,7 @@ export async function deliver(
 ): Promise<Delivery> {
   // A task this machine's orchestrator moved to a linked machine: that
   // machine's AgentOS delivers it, labelled as the orchestrator's (held.ts).
-  if (to.task_prompt && to.started_by && hostLink(to.host_id))
+  if (isHeldRemote(to))
     return relayToHeldTask(to, line, from.name, from.messageId);
   // A linked machine's own session: an agent's message would reach it as
   // the user's (see runner.ts), so none is relayed yet.
@@ -252,7 +273,13 @@ export async function sendMessage(opts: {
   // A message pulled from a linked machine, by its key there: one already
   // stored is not stored or delivered again.
   relayKey?: string;
-}): Promise<{ message: BusMessageView; delivery: Delivery; note?: string }> {
+}): Promise<{
+  message: BusMessageView;
+  delivery: Delivery;
+  note?: string;
+  // The task it was held for, when that task is still in the start queue.
+  heldForQueued?: boolean;
+}> {
   const body = opts.body.trim();
   if (!body) throw new Error("Message is empty");
   const from = sessionById(opts.fromId);
@@ -260,7 +287,14 @@ export async function sendMessage(opts: {
   // A held task's message to its orchestrator is kept for the holder to pull.
   const held = heldTarget(from, opts.to);
   if (from && held) return storeForHolder(from, held, body);
-  const { session: to, note } = resolveTarget(opts.to);
+  const target = tryResolveTarget(opts.to);
+  if (!target.ok) {
+    // A task still in the start queue has no session yet: hold it.
+    const queued = target.none ? findQueuedTarget(opts.to) : null;
+    if (!queued) throw new Error(target.error);
+    return storeForQueued(from, opts.fromLabel, queued, body, opts.relayKey);
+  }
+  const { session: to, note } = target;
   if (from && from.id === to.id)
     throw new Error("A session can't message itself");
   if (from && overRateLimit(pairTimestamps(from.id, to.id))) {
@@ -355,6 +389,45 @@ function storeForHolder(
   };
 }
 
+// A message for a task that hasn't started: kept with the queued task and
+// delivered in its first prompt. A schedule's `line` is only a wake line;
+// the body is what's held.
+function storeForQueued(
+  from: Session | undefined,
+  fromLabel: string | undefined,
+  to: QueuedTarget,
+  body: string,
+  relayKey?: string
+) {
+  assertTakesMessages(to);
+  if (from && overRateLimit(pairTimestamps(from.id, to.id)))
+    throw new Error(
+      `Too many messages between ${from.name} and ${to.name}; wait a few minutes`
+    );
+  const { lastInsertRowid } = db
+    .prepare(
+      `INSERT INTO bus_messages (from_id, from_name, to_id, to_name, body, relay_key, held_queued)
+       VALUES (?, ?, ?, ?, ?, ?, 1)`
+    )
+    .run(
+      from?.id ?? null,
+      from?.name ?? fromLabel ?? HUMAN,
+      to.id,
+      to.name,
+      body,
+      relayKey ?? null
+    );
+  const message = toView(
+    db.prepare(`${SELECT} WHERE m.id = ?`).get(Number(lastInsertRowid)) as Row
+  );
+  return {
+    message,
+    delivery: { state: "queued" as const },
+    note: heldQueuedNote(to.name),
+    heldForQueued: true,
+  };
+}
+
 // Unread messages for a session, marked read as they're returned.
 export function readInbox(sessionId: string): BusMessageView[] {
   const rows = db

package/lib/db/migrations.ts

@@ -2242,6 +2242,61 @@ export const migrations: Migration[] = [
       `);
     },
   },
+  {
+    key: "20261014T1235_placed_mirror_started_by",
+    up: (db) => {
+      // A task the queue started on a linked machine kept no record of the
+      // orchestrator that queued it, so it couldn't be read, messaged or
+      // stopped from there. Fills the mirror from the queue row; additive,
+      // only where the mirror has none.
+      db.exec(`
+        UPDATE sessions SET
+          started_by = (SELECT q.started_by FROM task_queue q WHERE q.id = sessions.id),
+          task_since = COALESCE(task_since, created_at)
+        WHERE started_by IS NULL AND task_prompt IS NOT NULL
+          AND host_id IS NOT NULL AND host_id != 'local'
+          AND (SELECT q.started_by FROM task_queue q WHERE q.id = sessions.id) IS NOT NULL
+      `);
+    },
+  },
+  {
+    key: "20261014T1600_queued_task_messages",
+    up: (db) => {
+      // A message for a task still in the start queue, held (addressed to
+      // the queue id, which is the session id it starts as) until its
+      // first prompt. Additive.
+      const has = (
+        db.prepare(`PRAGMA table_info(bus_messages)`).all() as {
+          name: string;
+        }[]
+      ).some((c) => c.name === "held_queued");
+      if (!has)
+        db.exec(`ALTER TABLE bus_messages ADD COLUMN held_queued INTEGER`);
+      db.exec(
+        `CREATE INDEX IF NOT EXISTS idx_bus_messages_held_queued
+           ON bus_messages(to_id) WHERE held_queued = 1`
+      );
+    },
+  },
+  {
+    key: "20261014T1800_task_starter_device",
+    up: (db) => {
+      // The paired device that started a task over the API: the only one
+      // that may later hold it. Tasks already running have no record, so
+      // they're marked unrecorded. Additive.
+      const has = (
+        db.prepare(`PRAGMA table_info(sessions)`).all() as { name: string }[]
+      ).some((c) => c.name === "started_by_device");
+      if (!has)
+        db.exec(`ALTER TABLE sessions ADD COLUMN started_by_device TEXT`);
+      db.exec(`
+        UPDATE sessions SET started_by_device = 'unrecorded'
+        WHERE started_by_device IS NULL AND started_by IS NULL
+          AND held_by_device IS NULL AND task_status = 'running'
+          AND task_prompt IS NOT NULL AND (host_id IS NULL OR host_id = 'local')
+      `);
+    },
+  },
 ];
 
 // `upTo`: stop after this legacy id or timestamp key, inclusive (tests that

package/lib/db/types.ts

@@ -146,6 +146,8 @@ export interface Session {
   // The device and machine of the orchestrator that moved this task here.
   held_by_device?: string | null;
   held_from?: string | null;
+  // The paired device that started this task here over the API.
+  started_by_device?: string | null;
   held_for?: string | null;
   held_for_name?: string | null;
   // A held task's "plan written" line, for its orchestrator to read.

package/lib/done/index.ts

@@ -31,7 +31,7 @@ import { releasePorts } from "../ports";
 import { dropSessionDatabase } from "../project-config/database";
 import { doneOnPeer, peerSessionLink } from "../hosts/peer-actions";
 import { hostLink } from "../hosts/remote-api";
-import { doneHeldTask } from "../tasks/held-remote";
+import { doneHeldTask, isHeldRemote } from "../tasks/held-remote";
 import { captureMergedTask } from "../session-logs";
 import { sessionEnded } from "../experiments/hooks";
 import { pushMerged } from "../notify/push/events";
@@ -175,7 +175,7 @@ export async function doneSession(
     await stopAgent(s);
     // The sign-off's cleanup has already settled it; this reads the result.
     worktree = await settleWorktree(s, { prHead: m.sha });
-  } else if (s.started_by && s.task_prompt && hostLink(s.host_id)) {
+  } else if (isHeldRemote(s)) {
     // Moved to a linked machine by its orchestrator: that machine stops the
     // agent and removes the worktree, which is where they are.
     await doneHeldTask(s);

package/lib/orchestrator/act.ts

@@ -40,6 +40,12 @@ import { braked } from "./brakes";
 import { getOrchestrator } from "./home";
 import { addNote } from "./notes";
 import { findWorkspaceSession } from "./read";
+import {
+  assertTakesMessages,
+  findQueuedTarget,
+  heldQueuedNote,
+  type QueuedTarget,
+} from "../tasks/queue-held";
 import { workspaceProject, workspaceStack, workspaceTask } from "./targets";
 import { setPriority, stampPriority } from "../tasks/queue";
 import {
@@ -68,7 +74,15 @@ export async function send(
   message: string,
   opts: { scopeChange?: boolean } = {}
 ): Promise<string> {
-  const to = findWorkspaceSession(workspaceId, ref);
+  let to;
+  try {
+    to = findWorkspaceSession(workspaceId, ref);
+  } catch (error) {
+    // A task still in the queue has no session: it holds the message.
+    const queued = findQueuedTarget(ref, { workspaceId });
+    if (!queued) throw error;
+    return sendToQueued(workspaceId, queued, message, opts);
+  }
   let amended = "";
   if (opts.scopeChange) {
     if (to.task_status !== "running")
@@ -96,6 +110,32 @@ export async function send(
     : `Delivered to ${to.name}.${amended}`;
 }
 
+// A queued task's id is the session id it starts as, so the amendment
+// recorded under it is already the running task's.
+async function sendToQueued(
+  workspaceId: string,
+  queued: QueuedTarget,
+  message: string,
+  opts: { scopeChange?: boolean }
+): Promise<string> {
+  assertTakesMessages(queued);
+  let amended = "";
+  if (opts.scopeChange) {
+    amendBrief(workspaceId, queued.id, message);
+    addNote(workspaceId, `Scope change for ${queued.name}: ${message}`);
+    amended = ` Recorded as scope change ${amendmentsOf(queued.id).length} on its brief: reviews judge against it once it has a PR.`;
+  }
+  const sent = await sendMessage({
+    fromId: orchestratorId(workspaceId),
+    to: queued.id,
+    body: message,
+  });
+  // It may have started in between: then it was delivered as to any task.
+  return sent.heldForQueued
+    ? `${heldQueuedNote(queued.name)}${amended}`
+    : `Delivered to ${queued.name}.${amended}`;
+}
+
 // What the orchestrator starts opens as a chat, as a new session in the UI
 // does (one default, in launch.ts); terminal is for a job that needs a TUI.
 export { DEFAULT_START_VIEW, type StartView };

package/lib/orchestrator/digest.ts

@@ -218,6 +218,8 @@ function queueSection(workspaceId: string): Section {
   const rows = db
     .prepare(
       `SELECT q.id, q.name, q.prompt, q.status, q.after_task, q.after_any, q.priority, q.note,
+         (SELECT COUNT(*) FROM bus_messages b WHERE b.to_id = q.id
+            AND b.held_queued = 1 AND b.delivered_at IS NULL AND b.read_at IS NULL) AS held,
          p.name AS project, a.name AS after_name
        FROM task_queue q JOIN projects p ON p.id = q.project_id
        LEFT JOIN sessions a ON a.id = q.after_task
@@ -235,6 +237,7 @@ function queueSection(workspaceId: string): Section {
     after_name: string | null;
     priority: string;
     note: string | null;
+    held: number;
   }[];
   return {
     title: "Queued tasks, in line order",
@@ -246,8 +249,11 @@ function queueSection(workspaceId: string): Section {
           : "";
       const status = r.status === "queued" ? "" : ` | ${r.status}`;
       const priority = r.priority === "normal" ? "" : ` | ${r.priority}`;
+      const held = r.held
+        ? ` | ${r.held} held message${r.held === 1 ? "" : "s"}`
+        : "";
       const why = r.note ? ` | ${clip(r.note, 100)}` : "";
-      return `- ${i + 1}. ${clip(r.name ?? r.prompt, 80)} (${r.project}, id ${shortId(r.id)})${after}${priority}${status}${why}`;
+      return `- ${i + 1}. ${clip(r.name ?? r.prompt, 80)} (${r.project}, id ${shortId(r.id)})${after}${priority}${status}${held}${why}`;
     }),
     more: "the sessions tool",
   };

package/lib/orchestrator/read.ts

@@ -10,7 +10,7 @@ import { hostLink } from "../hosts/remote-api";
 import { peerPane } from "../hosts/peer-sessions";
 import { workspaceSessions } from "./facts";
 import { untrusted } from "./untrusted";
-import { heldChatTail } from "../tasks/held-remote";
+import { heldChatTail, isHeldRemote } from "../tasks/held-remote";
 import {
   findExternalSession,
   knownExternalSession,
@@ -130,7 +130,7 @@ export async function readSession(
   const link = hostLink(s.host_id);
   if (s.view === "chat" && link) {
     // Its orchestrator's task is read through the machine that holds it.
-    const text = s.started_by ? await heldChatTail(s, n) : null;
+    const text = isHeldRemote(s) ? await heldChatTail(s, n) : null;
     return text
       ? `${s.name} (chat on ${link.hostName}), last ${n} lines:\n${untrusted(s.name, text)}`
       : `${s.name} (chat on ${link.hostName}): its messages are on that machine; open it to read them.`;

package/lib/orchestrator/task-state.ts

@@ -9,7 +9,7 @@ import { blockedReason } from "../tasks/state";
 import { checkWaitingPatterns, statusDetector } from "../status-detector";
 import { getCheck, putCheck } from "./checks";
 import { cleanRemoteText, hostLink, type HostLink } from "../hosts/remote-api";
-import { heldChatFacts } from "../tasks/held-remote";
+import { heldChatFacts, isHeldRemote } from "../tasks/held-remote";
 import { hostTasks } from "../tasks/remote";
 import { peerPane } from "../hosts/peer-sessions";
 import { untrusted } from "./untrusted";
@@ -88,7 +88,7 @@ async function peerChatWaiting(
   };
   // A task its orchestrator moved is asked about directly: the whole task
   // list is slow, and a miss there reads as unread.
-  const facts = task.started_by ? await heldChatFacts(task) : null;
+  const facts = isHeldRemote(task) ? await heldChatFacts(task) : null;
   if (facts) {
     const { turn } = facts;
     return {

package/lib/orchestrator/tools.ts

@@ -56,7 +56,7 @@ const DESCRIPTIONS: Record<ToolName, string> = {
   read: "The end of one session's terminal or chat, or an external session's screen, as plain text (capped at about 4k tokens).",
   cards: "Cards on this workspace's linked LumifyHub boards, by list.",
   logs: "Session logs AgentOS wrote when tasks merged: the last N headers (task, PR, cost, duration) of the workspace or one project, or one log in full (brief, plan, timeline, usage, outcome). Read straight from the database; nothing is summarised.",
-  send: "Message a session in this workspace over the bus. It arrives as its next prompt. When Saad changes a running task's scope, tell it with scope_change set, so its review judges the PR against the brief as amended.",
+  send: "Message a session in this workspace over the bus. It arrives as its next prompt. When Saad changes a running task's scope, tell it with scope_change set, so its review judges the PR against the brief as amended. A task still in the queue (by id or name) takes messages too: they are held and reach it with its first prompt; scope_change on one records the change on its brief at once.",
   orchestrators:
     "Every workspace, and whether it has an orchestrator you can message.",
   message_orchestrator:

package/lib/sessions/stop.ts

@@ -2,7 +2,7 @@ import { endTmuxSession } from "../tmux/end";
 import { hostLink } from "../hosts/remote-api";
 import { stopChatTurn } from "../chat/stop";
 import type { Session } from "../db";
-import { stopHeldTask } from "../tasks/held-remote";
+import { isHeldRemote, stopHeldTask } from "../tasks/held-remote";
 import { releaseOnEnd } from "../simulator";
 import { forgetPlanWait } from "../models/plan-step";
 
@@ -21,12 +21,12 @@ export async function stopSession(
     | "tmux_name"
     | "started_by"
     | "task_prompt"
+    | "task_since"
   >
 ): Promise<string> {
   // A task its orchestrator moved to a linked machine stops through that
   // machine's AgentOS, chat or terminal.
-  if (s.started_by && s.task_prompt && hostLink(s.host_id))
-    return stopHeldTask(s);
+  if (isHeldRemote(s)) return stopHeldTask(s);
   if (s.view === "chat") {
     if (hostLink(s.host_id))
       throw new Error(

package/lib/sidebar/queued.ts

@@ -78,7 +78,13 @@ export function queuedSubtitle(item: QueuedTaskView): {
   if (item.after) return { lead: "After", after: item.after };
   const priority =
     item.priority === "normal" ? "" : ` · ${PRIORITY_LABEL[item.priority]}`;
-  return { lead: `#${item.rank} of ${item.of}${priority}`, after: null };
+  const held = item.held
+    ? ` · ${item.held} message${item.held === 1 ? "" : "s"} held`
+    : "";
+  return {
+    lead: `#${item.rank} of ${item.of}${priority}${held}`,
+    after: null,
+  };
 }
 
 // The priority choices for a waiting task's menu, the current one marked.