@saadnvd1/agent-os 0.3.597 → 0.3.600

package/lib/orchestrator/act.ts

@@ -35,10 +35,11 @@ import { treeOrder } from "../stacks/tree";
 import type { StackItemView } from "../stacks/types";
 import { doneSession } from "../done";
 import { archiveChecked } from "../done/archive";
-import { amendBrief, amendmentsOf } from "./amendments";
+import { amendBrief, scopeChangesOf } from "./amendments";
 import { db, type Session } from "../db";
 import { resurrectSession } from "../resurrect";
 import { resolveEnded } from "../resurrect/find";
+import { findPiece, pieceLabel, workspacePieces } from "../plans/claim";
 import { approvePlanNow } from "../models/plan-step";
 import { braked } from "./brakes";
 import { getOrchestrator } from "./home";
@@ -96,7 +97,7 @@ export async function send(
     amendBrief(workspaceId, to.id, message);
     // In the decision log, so Saad sees every change of scope it records.
     addNote(workspaceId, `Scope change for ${to.name}: ${message}`);
-    amended = ` Recorded as scope change ${amendmentsOf(to.id).length} on its brief: reviews from now on judge against it (call review with fresh to judge the current head again).`;
+    amended = ` Recorded as scope change ${scopeChangesOf(to.id).length} on its brief: reviews from now on judge against it (call review with fresh to judge the current head again).`;
   }
   const { delivery } = await sendMessage({
     fromId: orchestratorId(workspaceId),
@@ -127,7 +128,7 @@ async function sendToQueued(
   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.`;
+    amended = ` Recorded as scope change ${scopeChangesOf(queued.id).length} on its brief: reviews judge against it once it has a PR.`;
   }
   const sent = await sendMessage({
     fromId: orchestratorId(workspaceId),
@@ -161,6 +162,7 @@ export async function startTask(
     machine?: "mac" | "any";
     now?: boolean;
     nowReason?: string;
+    piece?: string;
   } = {}
 ): Promise<string> {
   if (opts.planOnly && opts.plan === false)
@@ -170,6 +172,9 @@ export async function startTask(
   const project = workspaceProject(workspaceId, projectRef);
   const model = parseOverride(opts.model) ?? undefined;
   const startedBy = orchestratorId(workspaceId);
+  const pieceId = opts.piece
+    ? findPiece(workspacePieces(workspaceId, project.id), opts.piece).id
+    : undefined;
   // Its brakes read this machine's usage, not the other machine's account.
   if (isRemoteHost(project.host_id))
     throw new Error(
@@ -190,6 +195,9 @@ export async function startTask(
       planOnly: opts.planOnly,
       planReason: opts.planReason,
       startedBy,
+      parentSessionId: startedBy,
+      startedVia: "orchestrator",
+      pieceId,
       baseBranch: opts.base || undefined,
       after: opts.after,
       originWorkspaceId: workspaceId,
@@ -213,13 +221,17 @@ export async function startTask(
             planOnly: opts.planOnly,
             planReason: opts.planReason,
             startedBy,
+            parentSessionId: startedBy,
+            startedVia: "orchestrator",
+            pieceId,
           }),
         (s) => s.id
       )
   );
   if ("queued" in out) {
     const { queued } = out;
-    return `Queued (position ${queued.position}) task "${queued.name}" (id ${queued.id.slice(0, 8)}) in ${project.name}${queued.after ? `, after ${queued.after}` : ""}. It starts by itself; you'll get an event when it does.`;
+    const builds = pieceId ? ` It builds ${pieceLabel(pieceId)}.` : "";
+    return `Queued (position ${queued.position}) task "${queued.name}" (id ${queued.id.slice(0, 8)}) in ${project.name}${queued.after ? `, after ${queued.after}` : ""}.${builds} It starts by itself; you'll get an event when it does.`;
   }
   const task = out.started;
   if (opts.priority) stampPriority(task.id, opts.priority);
@@ -236,7 +248,7 @@ export async function startTask(
     opts.plan && !opts.planOnly && task.plan_phase !== "planning"
       ? ` Plan step skipped: ${view === "terminal" ? "a terminal task has none" : "planning and implementation use the same model"}.`
       : "";
-  return `Started task "${task.name}" (id ${task.id.slice(0, 8)}, ${view}) in ${project.name} on ${task.branch_name} (from ${task.base_branch}). It ends in a PR; you'll get an event when it opens.${skipped}${planOnlyNote}${past ? " Started past the running-task limit." : ""}`;
+  return `Started task "${task.name}" (id ${task.id.slice(0, 8)}, ${view}) in ${project.name} on ${task.branch_name} (from ${task.base_branch}). It ends in a PR; you'll get an event when it opens.${pieceId ? ` It builds ${pieceLabel(pieceId)}.` : ""}${skipped}${planOnlyNote}${past ? " Started past the running-task limit." : ""}`;
 }
 
 // Starts a queued task now, past the running-task limit and its `after`.
@@ -276,10 +288,10 @@ export async function approveTaskPlan(
   task: Session,
   message?: string
 ): Promise<string> {
-  const out = await approvePlanNow(task.id, message);
+  const out = await approvePlanNow(task.id, message, "orchestrator");
   const amended = message
     ? ` Recorded as scope change ${out.amendments} on its brief: its review judges against it.`
-    : "";
+    : " Recorded the approval on its brief.";
   return `Approved the plan of ${task.name}: implementing on ${out.ref}.${amended}`;
 }
 
@@ -312,6 +324,8 @@ export async function startSession(
               access: "full",
               model,
               startedBy,
+              parentSessionId: startedBy,
+              startedVia: "orchestrator",
             })
           ).session
         : spawnSession({
@@ -320,6 +334,7 @@ export async function startSession(
             name: opts.name,
             model,
             startedBy,
+            parentSessionId: startedBy,
           }),
     (s) => s.id
   );

package/lib/orchestrator/amendments.ts

@@ -10,19 +10,22 @@ export interface Amendment {
   session_id: string;
   workspace_id: string;
   text: string;
+  // scope: a change to what the task builds; approval: a plan approved as written.
+  kind: "scope" | "approval";
   created_at: string;
 }
 
 export function amendBrief(
   workspaceId: string,
   taskId: string,
-  text: string
+  text: string,
+  kind: Amendment["kind"] = "scope"
 ): Amendment {
   const { lastInsertRowid } = db
     .prepare(
-      `INSERT INTO brief_amendments (session_id, workspace_id, text) VALUES (?, ?, ?)`
+      `INSERT INTO brief_amendments (session_id, workspace_id, text, kind) VALUES (?, ?, ?, ?)`
     )
-    .run(taskId, workspaceId, text.trim());
+    .run(taskId, workspaceId, text.trim(), kind);
   return db
     .prepare(`SELECT * FROM brief_amendments WHERE id = ?`)
     .get(Number(lastInsertRowid)) as Amendment;
@@ -34,3 +37,7 @@ export function amendmentsOf(taskId: string): Amendment[] {
     .prepare(`SELECT * FROM brief_amendments WHERE session_id = ? ORDER BY id`)
     .all(taskId) as Amendment[];
 }
+
+// Only the changes of scope: an approval as written changes nothing.
+export const scopeChangesOf = (taskId: string): Amendment[] =>
+  amendmentsOf(taskId).filter((a) => a.kind === "scope");

package/lib/orchestrator/serve.ts

@@ -145,6 +145,7 @@ export async function runTool(
         machine: a.machine,
         now: a.now,
         nowReason: a.now_reason,
+        piece: a.piece,
       });
     }
     case "start_now": {

package/lib/orchestrator/testing.ts

@@ -76,3 +76,11 @@ export function seedWorkspace(name = `ws-${randomUUID().slice(0, 6)}`) {
   });
   return { workspace, app, api, chat, task };
 }
+
+// An orchestrator session with this id, for rows that name it as started_by.
+export function seedOrchestrator(id: string): void {
+  db.prepare(
+    `INSERT OR IGNORE INTO sessions (id, name, tmux_name, working_directory, role)
+     VALUES (?, ?, ?, '/tmp', 'orchestrator')`
+  ).run(id, `orchestrator ${id}`, `claude-${id}`);
+}

package/lib/orchestrator/tool-schemas.ts

@@ -141,6 +141,15 @@ export const TOOL_SHAPES = {
       .max(300)
       .optional()
       .describe("With now: why it can't wait for a slot; logged for Saad"),
+    piece: z
+      .string()
+      .trim()
+      .min(1)
+      .max(120)
+      .optional()
+      .describe(
+        "The waiting plan piece this task builds (its name or number, or feature/piece): it is claimed so AgentOS won't start it again"
+      ),
     model: modelOverride,
     plan: z
       .boolean()

package/lib/orchestrator/tools.ts

@@ -62,7 +62,7 @@ const DESCRIPTIONS: Record<ToolName, string> = {
   message_orchestrator:
     "Message another workspace's orchestrator, by workspace name; never any other session there. It arrives as its next prompt, marked as from you and fenced as untrusted.",
   start_task:
-    'Start a task: an agent in its own worktree that ends in a PR. It runs as a chat unless view is terminal (only for a job that needs a TUI). priority (urgent, blocking, normal, background) says where it stands in the queue; machine "mac" pins work that needs this Mac. A busy machine holds a start and the result says why. With after (a task\'s id or name, or "any"), or over the workspace\'s running task limit, it\'s queued and starts by itself; the result says Queued (position N). Its models follow the role settings (planning, implementation, review, scope); give model only when Saad asks for one. Always state plan (true or false) and plan_reason (plan_only true plans, then stops and waits for approve_plan instead of implementing): plan true for a big, unclear or cross-cutting job, false for a small, clear one whose steps you write into the prompt. now true (with now_reason) starts it at once past the running-task limit instead of queueing for a slot, logged; not with after. Refused while a brake holds.',
+    'Start a task: an agent in its own worktree that ends in a PR. It runs as a chat unless view is terminal (only for a job that needs a TUI). priority (urgent, blocking, normal, background) says where it stands in the queue; machine "mac" pins work that needs this Mac. A busy machine holds a start and the result says why. With after (a task\'s id or name, or "any"), or over the workspace\'s running task limit, it\'s queued and starts by itself; the result says Queued (position N). Its models follow the role settings (planning, implementation, review, scope); give model only when Saad asks for one. Always state plan (true or false) and plan_reason (plan_only true plans, then stops and waits for approve_plan instead of implementing): plan true for a big, unclear or cross-cutting job, false for a small, clear one whose steps you write into the prompt. now true (with now_reason) starts it at once past the running-task limit instead of queueing for a slot, logged; not with after. piece names the waiting piece of a plan this task builds, so it is claimed and not started a second time. Refused while a brake holds.',
   set_task_model:
     'Resume a paused task on another model ("provider/model", or a map of role to one), keeping its conversation and worktree; it\'s told to carry on (or message). Refused mid-turn.',
   start_session:

package/lib/plans/claim.ts

@@ -0,0 +1,131 @@
+// A task that builds a waiting piece of a plan claims it, so the release
+// sweep never starts that piece a second time.
+
+import { db } from "../db";
+import { getProject } from "../projects";
+import type { FeaturePiece } from "./features";
+
+export interface WaitingPiece extends FeaturePiece {
+  feature_name: string;
+}
+
+const COLUMNS = `fp.*, f.name AS feature_name`;
+
+// Waiting pieces in `projectId` of the plans the caller belongs to: the plan
+// it wrote, or the one whose piece it is building.
+export function waitingPiecesFor(
+  callerId: string,
+  projectId: string
+): WaitingPiece[] {
+  return db
+    .prepare(
+      `SELECT ${COLUMNS} FROM feature_pieces fp JOIN features f ON f.id = fp.feature_id
+       WHERE f.status = 'building' AND fp.status = 'waiting' AND fp.project_id = ?
+         AND (f.plan_session_id = ?
+              OR EXISTS (SELECT 1 FROM feature_pieces o
+                         WHERE o.feature_id = f.id AND o.session_id = ?))
+       ORDER BY f.created_at, fp.position`
+    )
+    .all(projectId, callerId, callerId) as WaitingPiece[];
+}
+
+// The orchestrator's view: waiting pieces of its workspace's plans.
+export function workspacePieces(
+  workspaceId: string,
+  projectId: string
+): WaitingPiece[] {
+  return db
+    .prepare(
+      `SELECT ${COLUMNS} FROM feature_pieces fp JOIN features f ON f.id = fp.feature_id
+       WHERE f.status = 'building' AND fp.status = 'waiting' AND fp.project_id = ?
+         AND f.workspace_id = ?
+       ORDER BY f.created_at, fp.position`
+    )
+    .all(projectId, workspaceId) as WaitingPiece[];
+}
+
+export const listPieces = (waiting: WaitingPiece[]) =>
+  waiting.map((p) => `${p.position} ${p.name}`).join(", ");
+
+// `name`, `position`, or `feature/name`; an error that lists what's waiting
+// when nothing, or more than one, matches.
+export function findPiece(waiting: WaitingPiece[], ref: string): WaitingPiece {
+  const want = ref.trim().toLowerCase();
+  const slash = want.indexOf("/");
+  const only = slash > 0 ? want.slice(0, slash) : null;
+  const piece = slash > 0 ? want.slice(slash + 1) : want;
+  const hits = waiting.filter(
+    (p) =>
+      (!only || p.feature_name.toLowerCase() === only) &&
+      (p.name.toLowerCase() === piece || String(p.position) === piece)
+  );
+  if (hits.length === 1) return hits[0];
+  const names = waiting
+    .map((p) =>
+      waiting.some((o) => o.feature_id !== p.feature_id)
+        ? `${p.feature_name}/${p.name}`
+        : `${p.position} ${p.name}`
+    )
+    .join(", ");
+  if (hits.length > 1)
+    throw new Error(
+      `"${ref}" matches more than one waiting piece: ${names}. Name it as feature/piece.`
+    );
+  throw new Error(
+    waiting.length
+      ? `No waiting piece "${ref}". Waiting pieces: ${names}.`
+      : `No waiting piece "${ref}": nothing in your plan is waiting in this project.`
+  );
+}
+
+export function pieceRefusal(
+  waiting: WaitingPiece[],
+  projectId: string
+): string {
+  const where = getProject(projectId)?.name ?? "this project";
+  return `Your plan "${waiting[0].feature_name}" has pieces waiting in ${where}: ${listPieces(waiting)}. Name the one this task builds with --piece <name>; AgentOS starts the others itself when they are due.`;
+}
+
+export function pieceStatus(id: number): string | undefined {
+  return (
+    db.prepare(`SELECT status FROM feature_pieces WHERE id = ?`).get(id) as
+      | { status: string }
+      | undefined
+  )?.status;
+}
+
+export function claimable(id: number): void {
+  const status = pieceStatus(id);
+  if (status !== "waiting")
+    throw new Error(`That piece is ${status ?? "gone"}, not waiting`);
+}
+
+// Synchronous, so nothing runs between the check and the write.
+export function claimPiece(id: number, sessionId: string): void {
+  const changed = db
+    .prepare(
+      `UPDATE feature_pieces SET status = 'building', session_id = ?, note = NULL
+       WHERE id = ? AND status = 'waiting'`
+    )
+    .run(sessionId, id).changes;
+  if (!changed)
+    throw new Error(`That piece is ${pieceStatus(id) ?? "gone"}, not waiting`);
+}
+
+// Gives a claim back when the session it was made for never came to be.
+export function releaseClaim(id: number, sessionId: string): void {
+  db.prepare(
+    `UPDATE feature_pieces SET status = 'waiting', session_id = NULL
+     WHERE id = ? AND session_id = ? AND status = 'building'`
+  ).run(id, sessionId);
+}
+
+export function pieceLabel(id: number): string {
+  const r = db
+    .prepare(
+      `SELECT fp.position, fp.name, f.name AS feature FROM feature_pieces fp
+       JOIN features f ON f.id = fp.feature_id WHERE fp.id = ?`
+    )
+    .get(id) as { position: number; name: string; feature: string } | undefined;
+  return r ? `piece ${r.position} ${r.name} of "${r.feature}"` : "a piece";
+}

package/lib/plans/release.ts

@@ -9,7 +9,7 @@ import { createTask } from "../tasks";
 import { startOrQueue } from "../tasks/queue";
 import { braked, BrakeRefused } from "../orchestrator/brakes";
 import { queueEvent, queueEventOnce } from "../orchestrator/events";
-import { amendBrief, amendmentsOf } from "../orchestrator/amendments";
+import { amendBrief, scopeChangesOf } from "../orchestrator/amendments";
 import { usageRows } from "../session-logs/gather";
 import { pieceBrief } from "./pieces";
 import {
@@ -122,6 +122,9 @@ export const realDeps: ReleaseDeps = {
       // A retry under the same id clears what a failed attempt left behind.
       reclaim: true,
       startedBy: plan?.started_by ?? null,
+      parentSessionId: feature.plan_session_id,
+      startedVia: "plan" as const,
+      startedByDevice: plan?.started_by_device ?? null,
       originWorkspaceId: feature.workspace_id,
     };
     // A queued task keeps its queue id as its session id once it starts.
@@ -173,7 +176,7 @@ function creditParentMerge(feature: Feature, all: FeaturePiece[]): void {
     )
   )
     return;
-  if (amendmentsOf(parent.id).length) return;
+  if (scopeChangesOf(parent.id).length) return;
   const covered = all.filter(
     (p) => p.status === "waiting" && p.project_id === parent.project_id
   );

package/lib/recipes/run.ts

@@ -152,6 +152,8 @@ export async function startRun(
           access: "full",
           model: typeof model === "string" ? model : null,
           startedBy,
+          parentSessionId: startedBy,
+          startedVia: byOrchestrator ? "orchestrator" : "recipe",
         }).then((l) => ({ ...l, id: l.session.id }))
       );
       settleStart(run.id, "running", { sessionId: session.id });
@@ -167,6 +169,8 @@ export async function startRun(
         plan: false,
         planReason: "recipe run",
         startedBy,
+        parentSessionId: startedBy,
+        startedVia: byOrchestrator ? "orchestrator" : "recipe",
         originWorkspaceId: byOrchestrator ? ws : undefined,
       },
       () =>
@@ -181,6 +185,8 @@ export async function startRun(
             plan: false,
             planReason: "recipe run",
             startedBy,
+            parentSessionId: startedBy,
+            startedVia: byOrchestrator ? "orchestrator" : "recipe",
           })
         )
     );

package/lib/schedules/start.ts

@@ -37,6 +37,7 @@ async function startTask(
     projectId: projectOf(schedule).id,
     prompt: schedule.prompt,
     name: schedule.name,
+    startedVia: "schedule",
     onCreated: onSession,
   });
   return session.id;

package/lib/sessions/fork.ts

@@ -0,0 +1,10 @@
+// A fork continues its parent's conversation: it has a parent but wasn't
+// started by anyone and isn't a task. A task or session started from another
+// session also records that parent, and is not a fork.
+export const isFork = (s: {
+  parent_session_id?: string | null;
+  started_by?: string | null;
+  started_via?: string | null;
+  task_prompt?: string | null;
+}): boolean =>
+  !!s.parent_session_id && !s.started_by && !s.started_via && !s.task_prompt;

package/lib/sessions/launch.ts

@@ -3,6 +3,7 @@
  * then (for a worktree) the setup in the background, then the first message.
  */
 
+import type { StartVia } from "../tasks/starter";
 import fs from "fs";
 import os from "os";
 import path from "path";
@@ -74,6 +75,7 @@ export interface LaunchInput {
   // The orchestrator session that starts it: it runs on the implementation
   // role's model (or `model`), not the interactive one's.
   startedBy?: string | null;
+  startedVia?: StartVia;
   groupPath?: string;
   systemPrompt?: string | null;
 }
@@ -277,12 +279,14 @@ async function launch(input: LaunchInput, id: string): Promise<Launched> {
       runOn
     );
   db.prepare(
-    `UPDATE sessions SET view = ?, name_source = ?, setup_status = ?, started_by = ? WHERE id = ?`
+    `UPDATE sessions SET view = ?, name_source = ?, setup_status = ?, started_by = ?,
+       started_via = ? WHERE id = ?`
   ).run(
     view,
     naming.source,
     useWorktree ? "running" : null,
     input.startedBy ?? null,
+    input.startedVia ?? (input.startedBy ? "orchestrator" : null),
     id
   );
   if (interactive) setSessionModel(id, interactive);

package/lib/stacks/start.ts

@@ -119,6 +119,7 @@ export async function startItem(
       prompt: promptFromCard(card),
       name: card.title,
       cardId: card.id,
+      startedVia: "stack",
       base,
       onCreated: (sessionId) =>
         q.updateItem(db, item.id, {

package/lib/tasks/held-remote.ts

@@ -16,6 +16,7 @@ import {
 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}`;
@@ -23,11 +24,12 @@ const path = (id: string, leaf: string) =>
 /**
  * A task its orchestrator put on a linked machine, whether by moving it or
  * by the queue placing it there: the one test every relayed call goes by.
- * (held-replies.ts reads the same rule in SQL: started_by IS NOT NULL.)
+ * (held-replies.ts reads the same rule in SQL: started_by is an orchestrator.)
  */
 export const isHeldRemote = (
   s: Pick<Session, "started_by" | "task_prompt" | "host_id">
-): boolean => !!s.started_by && !!s.task_prompt && !!hostLink(s.host_id);
+): boolean =>
+  !!s.task_prompt && !!hostLink(s.host_id) && !!orchestratorOf(s.started_by);
 
 type Held = Pick<
   Session,

package/lib/tasks/held-replies.ts

@@ -27,18 +27,21 @@ interface Pulled {
   body: string;
 }
 
+// Held means an orchestrator started it, as isHeldRemote reads it.
+const HELD_BY = `started_by IN (SELECT id FROM sessions WHERE role = 'orchestrator')`;
+
 const heldMirror = (hostId: string, id: string) =>
   db
     .prepare(
       `SELECT * FROM sessions WHERE id = ? AND host_id = ?
-         AND started_by IS NOT NULL AND task_status IN ('running', 'moving')`
+         AND ${HELD_BY} AND task_status IN ('running', 'moving')`
     )
     .get(id, hostId) as Session | undefined;
 
 export function hasHeldMirrors(hostId: string): boolean {
   return !!db
     .prepare(
-      `SELECT 1 FROM sessions WHERE host_id = ? AND started_by IS NOT NULL
+      `SELECT 1 FROM sessions WHERE host_id = ? AND ${HELD_BY}
          AND task_prompt IS NOT NULL AND task_status IN ('running', 'moving')`
     )
     .get(hostId);

package/lib/tasks/held.ts

@@ -5,6 +5,7 @@
  * a green CI, past the gates its orchestrator judges it by.
  */
 
+import { orchestratorOf } from "./starter";
 import os from "os";
 import { db, type Session } from "../db";
 import type { OrchestratedBundle } from "./move-bundle";
@@ -102,7 +103,7 @@ type Holdable = Pick<
 export function mayHold(s: Holdable, device: string): boolean {
   if (!s.task_prompt || s.task_status !== "running") return false;
   if (s.host_id && s.host_id !== "local") return false;
-  if (s.started_by || s.held_by_device) return false;
+  if (orchestratorOf(s.started_by) || s.held_by_device) return false;
   return (
     s.started_by_device === device || s.started_by_device === UNRECORDED_STARTER
   );