@saadnvd1/agent-os 0.3.584 → 0.3.585

package/lib/orchestrator/act.ts

@@ -26,7 +26,9 @@ import {
   findQueued,
   queuedLabel,
   removeQueued,
+  slotState,
   startOrQueue,
+  startQueuedForOrchestrator,
 } from "../tasks/queue";
 import { getStack, previewStack, startStack } from "../stacks";
 import { treeOrder } from "../stacks/tree";
@@ -155,10 +157,14 @@ export async function startTask(
     planReason?: string;
     priority?: Priority;
     machine?: "mac" | "any";
+    now?: boolean;
+    nowReason?: string;
   } = {}
 ): Promise<string> {
   if (opts.planOnly && opts.plan === false)
     throw new Error("plan_only implies plan; pass plan true");
+  if (opts.now && !opts.nowReason)
+    throw new Error("now needs now_reason: say why it can't wait for a slot");
   const project = workspaceProject(workspaceId, projectRef);
   const model = parseOverride(opts.model) ?? undefined;
   const startedBy = orchestratorId(workspaceId);
@@ -168,6 +174,7 @@ export async function startTask(
       `${project.name} runs on another machine; the orchestrator starts tasks on this one only for now`
     );
   const view = opts.view ?? DEFAULT_START_VIEW;
+  const slots = slotState(project.id);
   // Held for a slot or its `after`, it starts by itself through the brakes;
   // you get an event when it does.
   const out = await startOrQueue(
@@ -186,6 +193,7 @@ export async function startTask(
       originWorkspaceId: workspaceId,
       priority: opts.priority,
       machine: opts.machine,
+      now: opts.now,
     },
     () =>
       braked(
@@ -213,6 +221,12 @@ export async function startTask(
   }
   const task = out.started;
   if (opts.priority) stampPriority(task.id, opts.priority);
+  const past = opts.now && slots.full && !opts.planOnly;
+  if (past)
+    addNote(
+      workspaceId,
+      `Started "${task.name}" past the running-task limit (${slots.running} of ${slots.limit} running): ${opts.nowReason}`
+    );
   const planOnlyNote = opts.planOnly
     ? " Plan only: it stops after the plan and waits; approve_plan continues it, drop rejects it."
     : "";
@@ -220,7 +234,39 @@ 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}`;
+  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." : ""}`;
+}
+
+// Starts a queued task now, past the running-task limit and its `after`.
+// Pause, the brakes and a machine need still hold it.
+export async function startNow(
+  workspaceId: string,
+  ref: string,
+  reason: string
+): Promise<string> {
+  const queued = findQueued(workspaceId, ref, { byName: true });
+  if (!queued) {
+    const running = workspaceTask(workspaceId, ref);
+    throw new Error(`${running.name} is already started, not queued`);
+  }
+  const name = queuedLabel(queued);
+  const out = await startQueuedForOrchestrator(workspaceId, queued.id);
+  if (out.outcome === "held")
+    return `Not started: ${out.text}. ${name} stays in the queue.`;
+  if (out.outcome === "failed") return `Could not start ${name}: ${out.text}.`;
+  const skipped = [
+    out.wasFull
+      ? `past the running-task limit (${out.running} of ${out.limit} running)`
+      : "",
+    out.skippedAfter ? "without waiting for its after" : "",
+  ]
+    .filter(Boolean)
+    .join(", ");
+  addNote(
+    workspaceId,
+    `Started queued ${name} now${skipped ? `, ${skipped}` : ""}: ${reason}`
+  );
+  return `Started ${name} (id ${queued.id.slice(0, 8)}) now${skipped ? `, ${skipped}` : ""}. You'll get an event when its PR opens.`;
 }
 
 // The orchestrator approves a plan-only task's plan; a message amends it.

package/lib/orchestrator/brief.ts

@@ -119,7 +119,7 @@ Reading:
 Acting:
 - \`${TOOL_NAMES.send}\` (session, message, scope_change?): message a session; it arrives as its next prompt. scope_change records it on the task's brief for its review.
 - \`${TOOL_NAMES.message_orchestrator}\` (workspace, message): message another workspace's orchestrator, the only thing you reach outside this workspace. Use it to hand over a bug or ask for something in its projects; it decides what to do there.
-- \`${TOOL_NAMES.start_task}\` (project, prompt, base?, name?, view?, after?, priority?, machine?, model?, plan, plan_only?, plan_reason): a task in its own worktree that ends in a PR. priority (urgent, blocking, normal, background) sets where it stands in the queue; machine mac pins work that needs this Mac. A busy or loaded machine holds a queued start and says why; don't retry it. Write the prompt as a full brief; name it in 2-6 words, or it's named from the prompt. It runs as a chat; pass view terminal only when the job needs a TUI. Pass after (a task's id or name, or "any") to hold it until that task finishes, instead of remembering it in your notes. Over the workspace's running task limit it's queued too: the result says "Queued (position N)", it starts by itself, and you get an event when it does. Its models follow the role settings (it plans on the planning model, then implements on the implementation one); State plan and plan_reason for every task (see "Triage every job"). Pass model ("provider/model", or a map of role to one) only when Saad asks for one, or to put implementation on Opus when the work needs deep reasoning (say why in plan_reason or a note); another provider than anthropic only when Saad asks.
+- \`${TOOL_NAMES.start_task}\` (project, prompt, base?, name?, view?, after?, priority?, machine?, now?, now_reason?, model?, plan, plan_only?, plan_reason): a task in its own worktree that ends in a PR. priority (urgent, blocking, normal, background) sets where it stands in the queue; machine mac pins work that needs this Mac. A busy or loaded machine holds a queued start and says why; don't retry it. Write the prompt as a full brief; name it in 2-6 words, or it's named from the prompt. It runs as a chat; pass view terminal only when the job needs a TUI. Pass after (a task's id or name, or "any") to hold it until that task finishes, instead of remembering it in your notes. Over the workspace's running task limit it's queued too: the result says "Queued (position N)", it starts by itself, and you get an event when it does. now true (with now_reason, not with after) starts it at once past the limit instead; it's logged for Saad, so use it only when it can't wait. Its models follow the role settings (it plans on the planning model, then implements on the implementation one); State plan and plan_reason for every task (see "Triage every job"). Pass model ("provider/model", or a map of role to one) only when Saad asks for one, or to put implementation on Opus when the work needs deep reasoning (say why in plan_reason or a note); another provider than anthropic only when Saad asks.
 - \`${TOOL_NAMES.plan_pieces}\` (task, merge?, drop?): when a plan split into pieces (the plan-done event names them), list them; merge or drop edits the ones still waiting. A piece starts by itself once what it waits on has merged (or deployed); you don't start it.
 - \`${TOOL_NAMES.approve_plan}\` (task, message?): continue a plan_only task whose plan is ready; it implements on the implementation model, once. message amends the plan and is recorded on the task's brief as a scope change. Reject a plan with drop.
 - \`${TOOL_NAMES.set_task_model}\` (task, model, message?): move a paused task to another model and carry on in the same conversation and worktree; it keeps that model from then on. Only when Saad asks.
@@ -135,6 +135,7 @@ Acting:
 - \`${TOOL_NAMES.move}\` (task, machine): carry a running task to a linked machine (heavy test or build work), or back with machine "here". It keeps its branch, conversation and plan, and everything you do with a task works the same there: its events come to you, read, send, stop, done and drop reach it, and the gates judge its PR at its head. The machine it lands on holds it for you and can't merge it. It runs in the background; an event says when it lands. Refused while paused, and for a task waiting on Saad.
 - \`${TOOL_NAMES.drop}\` (task, reason): close a task's PR and remove its worktree (on whichever machine holds it).
 - \`${TOOL_NAMES.set_priority}\` (task, priority): re-rank a queued task (urgent, blocking, normal, background), or tag a running one. Urgent is a bug Saad hit; background starts last.
+- \`${TOOL_NAMES.start_now}\` (task, reason): start a queued task now, past the running-task limit and its after. Still refused while paused or braked, and a Mac-only task stays queued. Use it sparingly, when Saad asks or it unblocks others; the reason is logged for Saad.
 - \`${TOOL_NAMES.pause_task}\` (task, for, now?, reason): pause a running task for 1h, 2h, until tomorrow 9 AM or until resumed. Its agent ends at the end of its step (now interrupts the step); its worktree and conversation stay and its slot frees for the next queued task. It resumes by itself, ahead of new arrivals, with what was held (CI and review notes, messages) in one prompt. Use it to make room for urgent work or to wait out a loaded machine. Refused for a task that is merging, moving, setting up or waiting on Saad.
 - \`${TOOL_NAMES.resume_task}\` (task): resume a pause you set now. A pause Saad set is his to lift.
 - \`${TOOL_NAMES.stop}\` (session): stop a session's agent, keeping its work.

package/lib/orchestrator/serve.ts

@@ -12,6 +12,7 @@ import {
   stackStatus,
   startSession,
   startTask,
+  startNow,
   setTaskPriority,
   pauseTask,
   resumeTask,
@@ -67,6 +68,7 @@ const ACTING = new Set<ToolName>([
   "approve_plan",
   "plan_pieces",
   "set_priority",
+  "start_now",
   "pause_task",
   "resume_task",
   "stop",
@@ -139,8 +141,14 @@ export async function runTool(
         planReason: a.plan_reason,
         priority: a.priority,
         machine: a.machine,
+        now: a.now,
+        nowReason: a.now_reason,
       });
     }
+    case "start_now": {
+      const a = p(tool, raw);
+      return startNow(w, a.task, a.reason);
+    }
     case "set_priority": {
       const a = p(tool, raw);
       return setTaskPriority(w, a.task, a.priority);

package/lib/orchestrator/tool-names.ts

@@ -30,6 +30,7 @@ export const TOOL_NAMES = {
   drop: name("drop"),
   move: name("move"),
   set_priority: name("set_priority"),
+  start_now: name("start_now"),
   pause_task: name("pause_task"),
   resume_task: name("resume_task"),
   stop: name("stop"),

package/lib/orchestrator/tool-schemas.ts

@@ -128,6 +128,19 @@ export const TOOL_SHAPES = {
       .describe(
         'Where it may run: "mac" for work that needs this Mac (Xcode, a simulator); "any" if no machine need applies. Unset: the project\'s setting, else decided from its files'
       ),
+    now: z
+      .boolean()
+      .optional()
+      .describe(
+        "Start it at once, past the workspace's running-task limit, instead of queueing for a slot. Needs now_reason; not with after"
+      ),
+    now_reason: z
+      .string()
+      .trim()
+      .min(1)
+      .max(300)
+      .optional()
+      .describe("With now: why it can't wait for a slot; logged for Saad"),
     model: modelOverride,
     plan: z
       .boolean()
@@ -250,6 +263,15 @@ export const TOOL_SHAPES = {
     task: ref("A queued or running task: name, project/name or id"),
     priority: z.enum(PRIORITIES),
   },
+  start_now: {
+    task: ref("A queued task: name, project/name or id"),
+    reason: z
+      .string()
+      .trim()
+      .min(1)
+      .max(300)
+      .describe("Why it can't wait for a slot; logged for Saad"),
+  },
   pause_task: {
     task,
     for: z

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. 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. 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:
@@ -83,6 +83,8 @@ const DESCRIPTIONS: Record<ToolName, string> = {
   move: 'Carry a running task to a linked machine, or back with "here": for heavy test or build work. It keeps its branch, conversation and plan; the gates, events, read, send, stop, done and drop work the same wherever it runs, and the machine it lands on can\'t merge it. Takes a few minutes and runs in the background; an event says when it lands. Refused while paused, for a task waiting on Saad (an escalation or open ask), and for card and stacked tasks.',
   set_priority:
     "Change the priority of a queued task (it re-ranks the line at once) or a running one (it only matters if it is paused and waits to resume). urgent starts first even on a busy machine; background starts last.",
+  start_now:
+    "Start a queued task now, past the workspace's running-task limit and its after, when it can't wait for a slot (Saad asked, or it unblocks others). Still refused while paused or braked, and a task that needs a Mac stays queued. Give a reason: it goes in the decision log. Says whether it started, is still held and why, or failed.",
   pause_task:
     "Pause a running task for a set time: its agent ends at the end of its current step (now true interrupts the step), its worktree and conversation stay, and it frees its slot so the next queued task can start. It resumes by itself at the time, ahead of new arrivals of the same priority, with whatever was held (CI and review notes, messages) in one continue prompt. Refused for a task that is merging, moving, setting up or waiting on Saad. Give a reason; it is shown with the pause.",
   resume_task:

package/lib/tasks/queue.ts

@@ -312,6 +312,26 @@ export interface QueueRequest {
   priority?: Priority;
   // "mac" pins it to a Mac; "any" says it needs nothing in particular.
   machine?: "any" | "mac";
+  // Start at once, past the running-task limit, instead of queueing for a
+  // slot. Still needs the machine it needs, and an orchestrator's start
+  // still passes its brakes.
+  now?: boolean;
+}
+
+// How full the workspace's running-task limit is for this project.
+export function slotState(projectId: string): {
+  running: number;
+  limit: number | null;
+  full: boolean;
+} {
+  const workspaceId = workspaceOf(projectId);
+  const limit = limitOf(workspaceId);
+  if (!workspaceId || limit === null)
+    return { running: 0, limit: null, full: false };
+  const running =
+    runningIn({ workspaceId, projectId }, true).length +
+    startingIn(workspaceId);
+  return { running, limit, full: running >= limit };
 }
 
 const waitingIn = (workspaceId: string) =>
@@ -349,8 +369,11 @@ export function queueIfNeeded(req: QueueRequest): QueuedTaskView | null {
     }
   } else if (after)
     afterTask = resolveAfter(after, req.originWorkspaceId ?? workspaceId).id;
+  if (req.now && waits)
+    throw new Error("now and after don't go together: now starts it at once");
   const full =
     !req.planOnly &&
+    !req.now &&
     limit !== null &&
     !!workspaceId &&
     (runningIn({ workspaceId, projectId: project.id }, true).length +
@@ -364,9 +387,18 @@ export function queueIfNeeded(req: QueueRequest): QueuedTaskView | null {
     throw new Error(`Machine is "any" or "mac"`);
   // The orchestrator's own starts wait out a loaded machine; a person's
   // direct start goes ahead, as "start now" always has.
+  if (
+    req.now &&
+    !req.planOnly &&
+    needsUnmetHere(project.id, req.prompt, setting)
+  )
+    throw new Error(
+      `Can't start now: this task needs a Mac, and this machine isn't one. Queue it without now.`
+    );
   const loaded =
     !waits &&
     !full &&
+    !req.now &&
     !req.planOnly &&
     !!req.originWorkspaceId &&
     loadHeldStart(project.id, req.prompt, setting);
@@ -426,7 +458,8 @@ export async function startOrQueue<T>(
   const queued = queueIfNeeded(req);
   if (queued) return { queued };
   const workspaceId = workspaceOf(req.projectId);
-  if (!workspaceId) return { started: await start() };
+  // A plan-only start never holds a slot, as its queue row doesn't.
+  if (!workspaceId || req.planOnly) return { started: await start() };
   reserved.set(workspaceId, (reserved.get(workspaceId) ?? 0) + 1);
   try {
     return { started: await start() };
@@ -539,6 +572,33 @@ function autoHold(workspaceId: string | null, planOnly = false): Hold | null {
   return window ? { code: "window", text: `Waiting: ${window}` } : null;
 }
 
+const requestNeeds = (
+  projectId: string,
+  workingDirectory: string,
+  prompt: string,
+  setting: Need[] | null
+): Need[] =>
+  setting ??
+  needsOf({
+    projectId,
+    projectPath: expandHome(workingDirectory),
+    prompt,
+  }).needs;
+
+// Whether the task needs something this machine lacks (a Mac).
+function needsUnmetHere(
+  projectId: string,
+  prompt: string,
+  setting: Need[] | null
+): boolean {
+  const project = getProject(projectId);
+  if (!project || isRemoteHost(project.host_id)) return false;
+  return !meetsNeeds(
+    requestNeeds(projectId, project.working_directory, prompt, setting),
+    machineCapabilities()
+  );
+}
+
 // Whether this machine's load rules out starting a task for this project now.
 function loadHeldStart(
   projectId: string,
@@ -547,13 +607,12 @@ function loadHeldStart(
 ): boolean {
   const project = getProject(projectId);
   if (!project || isRemoteHost(project.host_id)) return false;
-  const needs =
-    setting ??
-    needsOf({
-      projectId,
-      projectPath: expandHome(project.working_directory),
-      prompt,
-    }).needs;
+  const needs = requestNeeds(
+    projectId,
+    project.working_directory,
+    prompt,
+    setting
+  );
   const hold = machineHold(
     {
       heavy: heavyNeeds(needs),
@@ -593,6 +652,8 @@ interface StartOpts {
   // Start on this linked machine instead of the project's.
   placement?: Placement | null;
   heavy?: boolean;
+  // Pass this workspace's brakes even for a row no orchestrator queued.
+  brakeAs?: string;
 }
 
 async function startRow(
@@ -683,9 +744,10 @@ async function startRow(
   try {
     // The orchestrator's queued starts pass its brakes when they start,
     // a person's "start now" included: it skips only the limit and `after`.
-    const session = origin
+    const brakeWs = origin ?? opts.brakeAs;
+    const session = brakeWs
       ? await braked(
-          origin,
+          brakeWs,
           "task",
           () => createTask(task),
           (s) => s.id,
@@ -1090,6 +1152,67 @@ export async function startQueuedNow(id: string): Promise<StartOutcome> {
   return startRow(r, { force: true });
 }
 
+export interface ForcedStart {
+  outcome: "started" | "held" | "failed";
+  // Why it is held, or what failed; empty when it started.
+  text: string;
+  // The running-task limit was full when it started.
+  wasFull: boolean;
+  running: number;
+  limit: number | null;
+  // It skipped an `after`.
+  skippedAfter: boolean;
+}
+
+// The orchestrator's start now: past the limit and `after`, never past
+// Pause, its brakes or a machine need. A held task stays queued.
+export async function startQueuedForOrchestrator(
+  workspaceId: string,
+  id: string
+): Promise<ForcedStart> {
+  const r = row(id);
+  const project = r ? getProject(r.project_id) : null;
+  if (!r || r.status !== "queued" || project?.workspace_id !== workspaceId)
+    throw new Error("That task isn't waiting in the queue");
+  const slots = slotState(r.project_id);
+  const base = {
+    wasFull: slots.full,
+    running: slots.running,
+    limit: slots.limit,
+    skippedAfter: !!(r.after_task || r.after_any),
+  };
+  const held = (text: string): ForcedStart => ({
+    ...base,
+    outcome: "held",
+    text,
+  });
+  if (isPaused(workspaceId)) return held("the orchestrator is paused by Saad");
+  if (isRemoteHost(r.host_id ?? project.host_id))
+    return held(
+      "it runs on another machine, and the orchestrator starts tasks on this one only"
+    );
+  if (
+    !meetsNeeds(
+      parseNeeds(r.machine_needs) ??
+        requestNeeds(project.id, project.working_directory, r.prompt, null),
+      machineCapabilities()
+    )
+  )
+    return held("it needs a Mac, and this machine isn't one");
+  try {
+    const outcome = await startRow(r, { force: true, brakeAs: workspaceId });
+    if (outcome === "started") return { ...base, outcome, text: "" };
+    return held("it could not be claimed just now; try again");
+  } catch (error) {
+    if (error instanceof BrakeRefused) return held(error.reason);
+    return {
+      ...base,
+      outcome: "failed",
+      text: row(id)?.error ?? String(error),
+    };
+  }
+}
+
 // A task still waiting in the line (or failed to start) by id, an id prefix
 // of 4+ characters or, when asked, its name; in one workspace.
 export function findQueued(

package/package.json

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