@saadnvd1/agent-os 0.3.592 → 0.3.595

package/lib/hover-tip.ts

@@ -0,0 +1,161 @@
+// One hover tooltip for the whole app. An element opts in with data-tip
+// (plain text) or data-tip-key ("session:<id>", resolved when it opens by
+// whoever registered that prefix). Rows carry an attribute and nothing
+// else: one element and a few passive document listeners do the rest, and
+// a touch screen attaches none. It opens after resting on something, and
+// once one is open the next opens at once, so a list can be scanned.
+
+export interface TipContent {
+  title: string;
+  lines: [label: string, value: string][];
+}
+export type TipValue = string | TipContent | null | undefined;
+
+export const OPEN_DELAY_MS = 600;
+export const WARM_MS = 400;
+const SELECTOR = "[data-tip],[data-tip-key]";
+const TIP_ID = "hover-tip";
+
+const resolvers = new Map<string, (id: string) => TipValue>();
+
+export function registerTip(
+  prefix: string,
+  resolve: (id: string) => TipValue
+): () => void {
+  resolvers.set(prefix, resolve);
+  return () => {
+    if (resolvers.get(prefix) === resolve) resolvers.delete(prefix);
+  };
+}
+
+export function resolveTip(el: Element): TipValue {
+  const key = el.getAttribute("data-tip-key");
+  if (key) {
+    const at = key.indexOf(":");
+    const value = resolvers.get(key.slice(0, at))?.(key.slice(at + 1));
+    if (value) return value;
+  }
+  return el.getAttribute("data-tip");
+}
+
+// Text only: names are user text and never parsed as HTML.
+function fill(el: HTMLElement, value: string | TipContent) {
+  if (typeof value === "string") {
+    el.textContent = value;
+    return;
+  }
+  const doc = el.ownerDocument;
+  const title = doc.createElement("div");
+  title.className = "font-medium";
+  title.textContent = value.title;
+  const rows = value.lines.map(([label, text]) => {
+    const line = doc.createElement("div");
+    const k = doc.createElement("span");
+    k.className = "text-muted-foreground";
+    k.textContent = `${label} `;
+    line.append(k, text);
+    return line;
+  });
+  el.replaceChildren(title, ...rows);
+}
+
+// Beside the target (a sidebar row's tip opens over the page, not the
+// list), flipped or dropped below when there's no room. One measure.
+function place(el: HTMLElement, target: Element, win: Window) {
+  const r = target.getBoundingClientRect();
+  const w = el.offsetWidth;
+  const h = el.offsetHeight;
+  const gap = 8;
+  let x = r.right + gap;
+  let y = r.top;
+  if (x + w > win.innerWidth - gap) x = r.left - w - gap;
+  if (x < gap) {
+    x = Math.min(Math.max(gap, r.left), win.innerWidth - w - gap);
+    y = r.bottom + gap;
+  }
+  y = Math.max(gap, Math.min(y, win.innerHeight - h - gap));
+  el.style.transform = `translate(${Math.round(x)}px, ${Math.round(y)}px)`;
+}
+
+// Works across documents (tests, frames), unlike instanceof Element.
+const isElement = (node: EventTarget | null): node is Element =>
+  !!node && typeof (node as Element).closest === "function";
+
+export function installHoverTip(win: Window = window): () => void {
+  if (!win.matchMedia?.("(hover: hover) and (pointer: fine)").matches)
+    return () => {};
+  const doc = win.document;
+  const el = doc.createElement("div");
+  el.id = TIP_ID;
+  el.setAttribute("role", "tooltip");
+  el.className =
+    "popover-surface text-popover-foreground pointer-events-none fixed top-0 left-0 z-[60] max-w-72 rounded-lg px-2.5 py-1.5 text-xs leading-relaxed whitespace-pre-line";
+  el.hidden = true;
+  doc.body.append(el);
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let pending: Element | null = null;
+  let shown: Element | null = null;
+  let warmUntil = 0;
+
+  const hide = () => {
+    clearTimeout(timer);
+    timer = undefined;
+    pending = null;
+    if (shown) {
+      shown.removeAttribute("aria-describedby");
+      warmUntil = Date.now() + WARM_MS;
+      shown = null;
+    }
+    el.hidden = true;
+  };
+  const show = (target: Element) => {
+    timer = undefined;
+    if (!target.isConnected) return;
+    const value = resolveTip(target);
+    if (!value) return;
+    fill(el, value);
+    el.hidden = false;
+    place(el, target, win);
+    target.setAttribute("aria-describedby", TIP_ID);
+    shown = target;
+  };
+  const arm = (target: Element | null) => {
+    if (target && (target === pending || target === shown)) return;
+    hide();
+    if (!target) return;
+    pending = target;
+    if (Date.now() < warmUntil) show(target);
+    else timer = setTimeout(() => show(target), OPEN_DELAY_MS);
+  };
+  const tipOf = (node: EventTarget | null) =>
+    isElement(node) ? node.closest(SELECTOR) : null;
+
+  const onOver = (e: Event) => arm(tipOf(e.target));
+  const onOut = (e: Event) => {
+    if (!(e as PointerEvent).relatedTarget) hide();
+  };
+  const onFocusIn = (e: Event) => {
+    const t = e.target;
+    if (isElement(t) && t.matches(SELECTOR) && t.matches(":focus-visible"))
+      arm(t);
+  };
+  const passive = { passive: true } as const;
+  const listeners: [string, (e: Event) => void, AddEventListenerOptions][] = [
+    ["pointerover", onOver, passive],
+    ["pointerout", onOut, passive],
+    ["pointerdown", hide, passive],
+    ["keydown", hide, passive],
+    ["focusin", onFocusIn, passive],
+    ["focusout", hide, passive],
+    ["scroll", hide, { passive: true, capture: true }],
+  ];
+  for (const [type, fn, opts] of listeners)
+    doc.addEventListener(type, fn, opts);
+  return () => {
+    hide();
+    for (const [type, fn, opts] of listeners)
+      doc.removeEventListener(type, fn, opts);
+    el.remove();
+  };
+}

package/lib/orchestrator/act.ts

@@ -36,7 +36,9 @@ import type { StackItemView } from "../stacks/types";
 import { doneSession } from "../done";
 import { archiveChecked } from "../done/archive";
 import { amendBrief, amendmentsOf } from "./amendments";
-import type { Session } from "../db";
+import { db, type Session } from "../db";
+import { resurrectSession } from "../resurrect";
+import { resolveEnded } from "../resurrect/find";
 import { approvePlanNow } from "../models/plan-step";
 import { braked } from "./brakes";
 import { getOrchestrator } from "./home";
@@ -54,7 +56,7 @@ import {
   PauseRefused,
   activePause,
   requestPause,
-  requestResume,
+  resumeNow,
 } from "../tasks/pause";
 import { pauseUntil, type PausePreset } from "../sidebar/snooze";
 import type { Priority } from "../tasks/schedule-types";
@@ -411,6 +413,30 @@ export async function archive(
   return `Archived ${s.name}: out of the sidebar, in Archived.`;
 }
 
+// Brings a dropped, done or archived session back, same id and conversation.
+// A task takes a running slot again, so it goes through the brakes like a
+// start; an unarchive or reopen starts nothing.
+export async function resurrect(
+  workspaceId: string,
+  ref: string,
+  reason: string
+): Promise<string> {
+  if (!reason.trim()) throw new Error("Say why it's restored");
+  const id = resolveEnded(ref, { workspaceId });
+  const row = db
+    .prepare(`SELECT task_status, archived_at FROM sessions WHERE id = ?`)
+    .get(id) as { task_status: string | null; archived_at: string | null };
+  const task =
+    row.task_status === "dropped" ||
+    (row.task_status === "done" && !row.archived_at);
+  const go = () => resurrectSession(id);
+  const out = task
+    ? await braked(workspaceId, "task", go, (o) => o.id)
+    : await go();
+  addNote(workspaceId, `Restored ${out.name}: ${reason.trim()}`);
+  return out.text;
+}
+
 // Stops the agent and keeps everything else: a chat's turn is interrupted,
 // a terminal's tmux session ends. Its worktree and branch stay.
 export async function stop(workspaceId: string, ref: string): Promise<string> {
@@ -507,14 +533,27 @@ export function pauseTask(
   return `Pausing ${task.name} ${now ? "now" : "at the end of its step"}. Its slot frees once it has stopped; an event says when.`;
 }
 
-export function resumeTask(workspaceId: string, ref: string): string {
+export async function resumeTask(
+  workspaceId: string,
+  ref: string
+): Promise<string> {
   const task = workspaceTask(workspaceId, ref);
   if (!activePause(task.id)) throw new Error(`${task.name} isn't paused`);
+  const slots = task.project_id ? slotState(task.project_id) : null;
+  let out;
   try {
-    requestResume(task.id, "orchestrator");
+    out = await resumeNow(task.id, "orchestrator");
   } catch (error) {
     if (error instanceof PauseRefused) throw new Error(error.message);
     throw error;
   }
-  return `${task.name} will resume as soon as it has a slot.`;
+  if (out.outcome === "held")
+    return `${task.name} is ${out.note}. It resumes by itself when that clears.`;
+  if (out.outcome === "cancelled")
+    return `${task.name} keeps running: its pause was cancelled.`;
+  const past = slots?.full
+    ? ` past the running-task limit (${slots.running} of ${slots.limit} running)`
+    : "";
+  addNote(workspaceId, `Resumed ${task.name} now${past}.`);
+  return `Resumed ${task.name} now${past}. It carries on with what was held for it.`;
 }

package/lib/orchestrator/brief.ts

@@ -137,10 +137,11 @@ Acting:
 - \`${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.resume_task}\` (task): resume a pause you set now, past the running-task limit unless the machine load holds it. A pause Saad set is his to lift.
 - \`${TOOL_NAMES.stop}\` (session): stop a session's agent, keeping its work.
 - \`${TOOL_NAMES.done}\` (session): finish a session whose work is complete. A task with an open PR merges through the same gates as sign_off first (refused naming the gate otherwise); then the agent stops, the worktree goes only if nothing in it would be lost, and the session lands on the sidebar's Done shelf (it is not archived). Not a rejection: use drop for that.
 - \`${TOOL_NAMES.archive}\` (session): put a session away, out of the sidebar, when Saad asks. Nothing is merged or cleaned up; refused while it works or has an open PR.
+- \`${TOOL_NAMES.resurrect}\` (session, reason): bring a dropped, done or archived session back with its conversation and worktree, in the state it had (a plan-only task waits for approval again). Use it when a drop or done was a mistake, or when Saad asks; refused for a merged PR, a missing conversation or a removed project. A restored task counts against the running limit and the brakes like a start.
 - \`${TOOL_NAMES.add_project}\` (path, name?): make a git repository on this machine a project of this workspace, or move the project already at that path in when it's in no workspace. Use it rather than sending Saad steps. It refuses a folder that isn't a git repository or holds secrets, and a project another workspace has: moving that is Saad's call, so ask_saad.
 - \`${TOOL_NAMES.note}\` (text): a line in this workspace's decision log, shown in your chat. Note each decision that matters, with why.
 - \`${TOOL_NAMES.rule_add}\` (text): keep a standing rule for this workspace, in your brief on every start. Saad sees and edits them in Settings → Workspaces.

package/lib/orchestrator/digest.ts

@@ -58,6 +58,7 @@ interface TaskRow {
   armed_at: string | null;
   pause_state: string | null;
   paused_until: string | null;
+  pause_note: string | null;
   placed_note: string | null;
 }
 
@@ -165,7 +166,7 @@ function tasksSection(
   const tasks = db
     .prepare(
       `SELECT s.id, s.name, p.name AS project, s.pr_number, s.pr_status, s.view,
-         s.merge_armed_at AS armed_at, s.pause_state, s.paused_until, s.placed_note
+         s.merge_armed_at AS armed_at, s.pause_state, s.paused_until, s.pause_note, s.placed_note
        FROM sessions s JOIN projects p ON p.id = s.project_id
        WHERE p.workspace_id = ? AND s.role IS NULL AND s.archived_at IS NULL
          AND s.task_status = 'running'
@@ -181,7 +182,7 @@ function tasksSection(
       const gates = gateState(checks.get(t.id), failures.get(t.id));
       const arm = t.armed_at ? " | armed to merge" : "";
       const paused = t.pause_state
-        ? ` | ${t.pause_state}${t.paused_until ? ` until ${t.paused_until} UTC` : t.pause_state === "paused" ? " until resumed" : ""}`
+        ? ` | ${t.pause_state}${t.paused_until ? ` until ${t.paused_until} UTC` : t.pause_state === "paused" ? " until resumed" : ""}${t.pause_note ? ` (${t.pause_note})` : ""}`
         : "";
       const placed = t.placed_note ? ` | ${t.placed_note}` : "";
       return `- ${clip(t.name, 80)} (${t.project ?? "?"}, ${t.view}, id ${shortId(t.id)}): ${pr}${arm}${paused}${placed}${gates ? ` | ${gates}` : ""}`;

package/lib/orchestrator/serve.ts

@@ -6,6 +6,7 @@ import {
   archive,
   done,
   drop,
+  resurrect,
   moveTaskTo,
   send,
   stack,
@@ -64,6 +65,7 @@ const ACTING = new Set<ToolName>([
   "stack",
   "land",
   "drop",
+  "resurrect",
   "move",
   "approve_plan",
   "plan_pieces",
@@ -219,6 +221,10 @@ export async function runTool(
       return done(w, p(tool, raw).session);
     case "archive":
       return archive(w, p(tool, raw).session);
+    case "resurrect": {
+      const a = p(tool, raw);
+      return resurrect(w, a.session, a.reason);
+    }
     case "add_project": {
       const a = p(tool, raw);
       return addProject(w, a.path, a.name);

package/lib/orchestrator/shell-guard.ts

@@ -211,7 +211,7 @@ const PULL_MERGE = /(^|\/)pulls\/[^/?\s]+\/merge\/?(\?|$)/;
 
 const MERGE_MSG = `Refused: a PR merges only through the gates: ${T.sign_off} (or ${T.arm}) for a task's or an external PR, ${T.land} for a stack. Nothing merges, closes or retargets a PR from the shell.`;
 
-// aos move, done, archive, stop and drop reach a session by name, past the tools'
+// aos move, done, archive, resurrect, stop and drop reach a session by name, past the tools'
 // Pause check and logging; the tools do the same work.
 function aosRefusal(args: string[]): string | null {
   const [sub] = positionals(args);
@@ -219,6 +219,7 @@ function aosRefusal(args: string[]): string | null {
     move: T.move,
     done: T.done,
     archive: T.archive,
+    resurrect: T.resurrect,
     stop: T.stop,
   };
   if (sub && tool[sub])

package/lib/orchestrator/tool-names.ts

@@ -36,6 +36,7 @@ export const TOOL_NAMES = {
   stop: name("stop"),
   done: name("done"),
   archive: name("archive"),
+  resurrect: name("resurrect"),
   add_project: name("add_project"),
   note: name("note"),
   question: name("question"),

package/lib/orchestrator/tool-schemas.ts

@@ -291,6 +291,12 @@ export const TOOL_SHAPES = {
   stop: { session },
   done: { session },
   archive: { session },
+  resurrect: {
+    session: ref(
+      "A dropped, done or archived session: its name, project/name or id (from the decision log, or as Saad named it)"
+    ),
+    reason: z.string().trim().min(1).max(2000),
+  },
   add_project: {
     path: z
       .string()

package/lib/orchestrator/tools.ts

@@ -88,11 +88,13 @@ const DESCRIPTIONS: Record<ToolName, string> = {
   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:
-    "Resume a task you paused (or the scheduler did) now. A pause Saad set is his to lift: this refuses and says so.",
+    "Resume a task you paused (or the scheduler did) now: it starts at once, past the running-task limit, unless the machine load holds it (the answer says so). A pause Saad set is his to lift: this refuses and says so.",
   stop: "Stop a session's agent mid-turn, even while it's thinking, keeping its conversation, worktree and branch; your next message runs as its next turn.",
   done: "Finish a session whose work is complete: a task's open PR merges through the sign-off gates first (refused naming the failing gate), then its agent stops, its worktree is removed if nothing would be lost, and it lands on the sidebar's Done shelf; it no longer archives (use archive for that). Not a rejection.",
   archive:
     "Put a finished session away, out of the sidebar (it stays in Archived, and Saad can unarchive it). Nothing is merged or cleaned up: refused while the session is working or has an open PR; done first for finished work.",
+  resurrect:
+    "Bring a dropped, done or archived session back: the same session and conversation, its worktree (with its uncommitted files and plan) back from what was saved or from its branch, its status as it was (a plan-only task waits for approval again, one with a PR is idle), and a PR a drop closed reopened. Archived sessions just unarchive. Held by Pause and braked like a start. Refused when its conversation is gone, its PR was merged, its project was removed or its branch is in use. Give a reason; it goes in the decision log.",
   add_project:
     "Make a git repository on this machine a project of this workspace, by its absolute path, or move the project already at that path into this workspace when it's in no workspace. Says its default branch, detected from git. Refuses a folder that isn't a git repository or that holds secrets, and a project another workspace has.",
   note: "Add a line to this workspace's decision log; it shows in your chat.",

package/lib/resurrect/find.ts

@@ -0,0 +1,111 @@
+/** Sessions that ended (dropped, done, archived) and can be asked for back. */
+
+import { db } from "../db";
+import { resolveRef } from "../bus/resolve";
+
+export type EndedKind = "dropped" | "done" | "archived" | "settled";
+
+export interface EndedSession {
+  id: string;
+  name: string;
+  projectId: string | null;
+  projectName: string | null;
+  kind: EndedKind;
+  taskStatus: string | null;
+  // A plan-only task whose plan was written and never approved.
+  planWaiting: boolean;
+  endedAt: string;
+}
+
+// A workspace's, or one project's, or everyone's (a person's own shell).
+export type EndedScope = { workspaceId: string } | { projectId: string } | null;
+
+interface Row {
+  id: string;
+  name: string;
+  tmux_name: string;
+  project_id: string | null;
+  project_name: string | null;
+  task_status: string | null;
+  archived_at: string | null;
+  plan_phase: string | null;
+  ended_at: string;
+}
+
+function kindOf(r: Row): EndedKind {
+  if (r.task_status === "dropped") return "dropped";
+  if (r.archived_at) return "archived";
+  return r.task_status === "done" ? "done" : "settled";
+}
+
+function rows(scope: EndedScope, limit: number, kind?: EndedKind): Row[] {
+  const where = [
+    "s.role IS NULL",
+    "s.peer_mirror = 0",
+    "s.held_by_device IS NULL",
+  ];
+  const args: (string | number)[] = [];
+  if (scope && "workspaceId" in scope) {
+    where.push("p.workspace_id = ?");
+    args.push(scope.workspaceId);
+  } else if (scope) {
+    where.push("s.project_id = ?");
+    args.push(scope.projectId);
+  }
+  where.push(
+    `(s.archived_at IS NOT NULL OR s.task_status IN ('dropped', 'done')
+       OR (s.task_status IS NULL AND s.settled_at IS NOT NULL))`
+  );
+  if (kind === "dropped") where.push("s.task_status = 'dropped'");
+  if (kind === "archived") where.push("s.archived_at IS NOT NULL");
+  if (kind === "done")
+    where.push("s.task_status = 'done' AND s.archived_at IS NULL");
+  return db
+    .prepare(
+      `SELECT s.id, s.name, s.tmux_name, s.project_id, p.name AS project_name,
+         s.task_status, s.archived_at, s.plan_phase,
+         COALESCE(s.task_ended_at, s.archived_at, s.settled_at, s.updated_at) AS ended_at
+       FROM sessions s LEFT JOIN projects p ON p.id = s.project_id
+       WHERE ${where.join(" AND ")}
+       ORDER BY ended_at DESC LIMIT ?`
+    )
+    .all(...args, limit) as Row[];
+}
+
+export function endedSessions(
+  scope: EndedScope,
+  opts: { limit?: number; kind?: EndedKind } = {}
+): EndedSession[] {
+  return rows(scope, opts.limit ?? 50, opts.kind).map((r) => ({
+    id: r.id,
+    name: r.name,
+    projectId: r.project_id,
+    projectName: r.project_name,
+    kind: kindOf(r),
+    taskStatus: r.task_status,
+    planWaiting: r.plan_phase === "awaiting",
+    endedAt: r.ended_at,
+  }));
+}
+
+/** An ended session by name, project/name, id or id prefix, within the scope. */
+export function resolveEnded(ref: string, scope: EndedScope): string {
+  const all = rows(scope, 500);
+  const r = resolveRef(
+    ref,
+    all.map((s) => ({
+      id: s.id,
+      name: s.name,
+      projectName: s.project_name,
+      tmuxName: s.tmux_name,
+      previousNames: [],
+    }))
+  );
+  if (!r.ok)
+    throw new Error(
+      r.reason === "none"
+        ? `No dropped, done or archived session "${ref}"${scope ? " here" : ""}.`
+        : r.error
+    );
+  return r.id;
+}