@saadnvd1/agent-os 0.3.523 → 0.3.527

package/lib/chat/turns.ts

@@ -0,0 +1,111 @@
+import type { ChatItem, ChatOrigin } from "./events";
+import { eventParts, originOf } from "./origin";
+
+type UserItem = Extract<ChatItem, { kind: "user" }>;
+
+// What the orchestrator's reply to an event ends up as in the timeline.
+export interface EventTurn {
+  // The event's own item id.
+  id: string;
+  user: UserItem;
+  origin: ChatOrigin;
+  // Everything after the event up to the end of the turn.
+  replies: ChatItem[];
+  // The start of the reply (or of the event, before it has one).
+  summary: string;
+  // The task or source it is about.
+  task: string;
+  at: number;
+  // Still being answered.
+  live: boolean;
+  // The reply opened a question for the reader.
+  hasQuestion: boolean;
+}
+
+const FOLDED_KINDS = new Set(["event", "peer", "schedule", "system"]);
+
+// The origin of a user item when it is activity (an event, a task's message,
+// a schedule) rather than something the reader said or decided. Items
+// without a recorded origin are read by their text only if they predate it
+// (originOf).
+export function activityOrigin(item: UserItem): ChatOrigin | null {
+  const origin = originOf(item);
+  if (!origin || !FOLDED_KINDS.has(origin.kind)) return null;
+  // A batch carrying the reader's own answers: the reply is to them.
+  if (origin.decided?.length) return null;
+  return origin;
+}
+
+export const isQuestionTool = (item: ChatItem): boolean =>
+  item.kind === "tool" && /(^|__)question$/.test(item.name);
+
+export function plainSummary(text: string, max = 140): string {
+  const line =
+    text
+      .split("\n")
+      .map((l) => l.trim())
+      .find(Boolean) ?? "";
+  const plain = line
+    .replace(/^(#{1,6}\s+|>\s*|[-*+]\s+|\d+[.)]\s+)+/, "")
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/[*_`~]+/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return plain.length > max ? `${plain.slice(0, max - 1)}…` : plain;
+}
+
+function taskName(origin: ChatOrigin): string {
+  const names = origin.subjects?.map((s) => s.name) ?? [];
+  if (!names.length) return origin.label;
+  return names.length > 1 ? `${names[0]} +${names.length - 1}` : names[0];
+}
+
+// The turn an activity item starts, or null when it should render in full:
+// anything that needs the reader's eyes (a pending approval, a plan, an
+// error) stays out of the fold. `limit` is where a turn must stop (the next
+// undone range).
+export function eventTurnAt(
+  items: ChatItem[],
+  start: number,
+  limit = items.length
+): { turn: EventTurn; end: number } | null {
+  const user = items[start];
+  if (user.kind !== "user") return null;
+  const origin = activityOrigin(user);
+  if (!origin) return null;
+  let end = start + 1;
+  let ended = false;
+  while (end < limit) {
+    const item = items[end];
+    if (item.kind === "user" || item.kind === "undo") break;
+    end++;
+    if (item.kind === "turn_end") {
+      ended = true;
+      break;
+    }
+  }
+  const replies = items.slice(start + 1, end);
+  const needsReader = replies.some(
+    (i) =>
+      i.kind === "plan" ||
+      i.kind === "error" ||
+      (i.kind === "approval" && i.status === "pending")
+  );
+  if (needsReader) return null;
+  const reply = replies.find((i) => i.kind === "assistant" && i.text.trim());
+  const body = eventParts(user, origin).body;
+  return {
+    end,
+    turn: {
+      id: user.id,
+      user,
+      origin,
+      replies,
+      summary: plainSummary(reply?.kind === "assistant" ? reply.text : body),
+      task: taskName(origin),
+      at: user.createdAt,
+      live: !ended && end >= items.length,
+      hasQuestion: replies.some(isQuestionTool),
+    },
+  };
+}

package/lib/db/changes.ts

@@ -29,12 +29,18 @@ export const TABLES_WATCHED_56 = ["orchestrator_rules"] as const;
 
 export const TABLES_WATCHED_58 = ["away_periods"] as const;
 
+export const TABLES_WATCHED_78 = [
+  "orchestrator_questions",
+  "needs_you_dismissed",
+] as const;
+
 // Every table any migration watches, for the browser's topic map to cover.
 export const WATCHED_TABLES: readonly string[] = [
   ...TABLES_WATCHED_45,
   ...TABLES_WATCHED_50,
   ...TABLES_WATCHED_56,
   ...TABLES_WATCHED_58,
+  ...TABLES_WATCHED_78,
 ];
 
 export function installChangeTriggers(

package/lib/db/migrations.ts

@@ -4,6 +4,7 @@ import {
   TABLES_WATCHED_50,
   TABLES_WATCHED_56,
   TABLES_WATCHED_58,
+  TABLES_WATCHED_78,
 } from "./changes";
 import type Database from "better-sqlite3";
 
@@ -1768,6 +1769,56 @@ const migrations: Migration[] = [
       );
     },
   },
+  {
+    id: 77,
+    name: "simulator_leases",
+    up: (db) => {
+      // One iOS simulator a task holds (lib/simulator): the device AgentOS
+      // made for it, and where it is in coming up.
+      db.exec(
+        `CREATE TABLE IF NOT EXISTS simulator_leases (
+           session_id TEXT PRIMARY KEY,
+           udid TEXT,
+           name TEXT NOT NULL,
+           state TEXT NOT NULL,
+           error TEXT,
+           created_at INTEGER NOT NULL,
+           last_used_at INTEGER NOT NULL
+         )`
+      );
+    },
+  },
+  {
+    id: 78,
+    name: "orchestrator_questions",
+    up: (db) => {
+      // A question the orchestrator put to Saad in chat, open until he
+      // answers it or the orchestrator clears it. needs_you_dismissed: items
+      // he hid from the Needs-you strip (an ask's or question's key); hiding
+      // never resolves anything.
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS orchestrator_questions (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          workspace_id TEXT NOT NULL,
+          text TEXT NOT NULL,
+          task TEXT,
+          status TEXT NOT NULL DEFAULT 'open',
+          resolved_by TEXT,
+          created_at TEXT NOT NULL DEFAULT (datetime('now')),
+          resolved_at TEXT
+        );
+        CREATE INDEX IF NOT EXISTS idx_orchestrator_questions_open
+          ON orchestrator_questions(workspace_id, status);
+        CREATE TABLE IF NOT EXISTS needs_you_dismissed (
+          workspace_id TEXT NOT NULL,
+          key TEXT NOT NULL,
+          dismissed_at TEXT NOT NULL DEFAULT (datetime('now')),
+          PRIMARY KEY (workspace_id, key)
+        );
+      `);
+      installChangeTriggers(db, TABLES_WATCHED_78);
+    },
+  },
 ];
 
 // `upTo`: stop after this id (tests that start from an older database).

package/lib/doctor/checks.ts

@@ -0,0 +1,222 @@
+/**
+ * Is this machine ready to run AgentOS? Node, git, tmux, ripgrep, lsof and at
+ * least one agent CLI, each with what to do when it is not. Read-only: it runs
+ * each tool's version and nothing else.
+ */
+
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { probeAgents, type AgentProbe } from "../agents/probe";
+import { getAllProviderDefinitions } from "../providers/registry";
+
+// The oldest Node major AgentOS runs on; scripts/lib/prerequisites.sh must agree
+// (lib/doctor/drift.test.ts fails when they don't).
+export const MIN_NODE_MAJOR = 20;
+
+const TOOL_MS = 5_000;
+const CACHE_MS = 60 * 1000;
+
+export type CheckStatus = "ok" | "warn" | "fail";
+
+export interface DoctorCheck {
+  id: string;
+  label: string;
+  status: CheckStatus;
+  detail: string;
+  // The line to run, or what to do, when the check is not ok.
+  fix?: string;
+}
+
+export type ExecFn = (
+  file: string,
+  args: string[],
+  options: { timeout: number }
+) => Promise<{ stdout: string; stderr: string }>;
+
+export interface DoctorDeps {
+  exec: ExecFn;
+  probe: (fresh: boolean) => Promise<Record<string, AgentProbe>>;
+  nodeVersion: string;
+}
+
+const defaultDeps: DoctorDeps = {
+  exec: promisify(execFile) as ExecFn,
+  probe: probeAgents,
+  nodeVersion: process.versions.node,
+};
+
+const INSTALL = {
+  mac: "brew install",
+  linux: "sudo apt-get install -y",
+};
+const installLine = (pkg: string) =>
+  process.platform === "darwin"
+    ? `${INSTALL.mac} ${pkg}`
+    : `${INSTALL.linux} ${pkg}`;
+
+interface Tool {
+  id: string;
+  label: string;
+  bin: string;
+  args: string[];
+  pkg: string;
+  // Missing is a fail for what AgentOS cannot run without, a warn otherwise.
+  required: boolean;
+  why: string;
+}
+
+const TOOLS: Tool[] = [
+  {
+    id: "git",
+    label: "git",
+    bin: "git",
+    args: ["--version"],
+    pkg: "git",
+    required: true,
+    why: "Sessions work in git worktrees.",
+  },
+  {
+    id: "tmux",
+    label: "tmux",
+    bin: "tmux",
+    args: ["-V"],
+    pkg: "tmux",
+    required: true,
+    why: "Terminal sessions run inside tmux.",
+  },
+  {
+    id: "ripgrep",
+    label: "ripgrep",
+    bin: "rg",
+    args: ["--version"],
+    pkg: "ripgrep",
+    required: false,
+    why: "File search is slower without it.",
+  },
+  {
+    id: "lsof",
+    label: "lsof",
+    bin: "lsof",
+    args: ["-v"],
+    pkg: "lsof",
+    required: false,
+    why: "Finding what holds a port needs it.",
+  },
+];
+
+const firstLine = (s: string) =>
+  s
+    .split("\n")
+    .find((l) => l.trim())
+    ?.trim();
+
+export function checkNode(version: string): DoctorCheck {
+  const major = Number.parseInt(version.split(".")[0], 10);
+  const ok = major >= MIN_NODE_MAJOR;
+  return {
+    id: "node",
+    label: "Node.js",
+    status: ok ? "ok" : "fail",
+    detail: ok
+      ? `v${version}`
+      : `v${version}; AgentOS needs ${MIN_NODE_MAJOR} or newer`,
+    ...(ok
+      ? {}
+      : { fix: `Install Node.js ${MIN_NODE_MAJOR}+ from nodejs.org` }),
+  };
+}
+
+async function checkTool(tool: Tool, exec: ExecFn): Promise<DoctorCheck> {
+  const base = { id: tool.id, label: tool.label };
+  try {
+    const { stdout, stderr } = await exec(tool.bin, tool.args, {
+      timeout: TOOL_MS,
+    });
+    return {
+      ...base,
+      status: "ok",
+      detail: firstLine(`${stdout}\n${stderr}`) ?? "installed",
+    };
+  } catch (error) {
+    const timedOut = (error as { killed?: boolean }).killed;
+    // lsof -v exits non-zero on some builds while printing its version; a
+    // tool that ran is installed, only one that could not start is missing.
+    const e = error as { code?: unknown; stdout?: string; stderr?: string };
+    const ran = typeof e.code === "number" && !timedOut;
+    if (tool.id === "lsof" && ran)
+      return { ...base, status: "ok", detail: "installed" };
+    return {
+      ...base,
+      status: tool.required ? "fail" : "warn",
+      detail: timedOut
+        ? `${tool.bin} did not answer`
+        : `Not found. ${tool.why}`,
+      fix: installLine(tool.pkg),
+    };
+  }
+}
+
+export function checkAgents(probes: Record<string, AgentProbe>): DoctorCheck {
+  const clis = getAllProviderDefinitions().filter((d) => d.cli);
+  const names = new Map(clis.map((d) => [d.id, d.name]));
+  // Providers without a CLI (a plain terminal) are always "installed".
+  const found = Object.entries(probes).filter(
+    ([id, p]) => names.has(id as never) && p.installed
+  );
+  const ready = found.filter(([, p]) => p.auth !== "needs-login");
+  const list = (rows: typeof found) =>
+    rows.map(([id]) => names.get(id as never) ?? id).join(", ");
+  if (ready.length > 0)
+    return {
+      id: "agents",
+      label: "Agent CLI",
+      status: "ok",
+      detail: `${list(ready)} ready`,
+    };
+  if (found.length > 0)
+    return {
+      id: "agents",
+      label: "Agent CLI",
+      status: "warn",
+      detail: `${list(found)} installed but needs sign-in`,
+      fix: "Sign in below",
+    };
+  return {
+    id: "agents",
+    label: "Agent CLI",
+    status: "fail",
+    detail: "No agent CLI installed",
+    fix: "Install one below",
+  };
+}
+
+let cache: { at: number; checks: Promise<DoctorCheck[]> } | null = null;
+
+/** Every check, in parallel, cached for a minute. `fresh` runs them again. */
+export function runDoctor(
+  fresh = false,
+  deps: Partial<DoctorDeps> = {}
+): Promise<DoctorCheck[]> {
+  const custom = Object.keys(deps).length > 0;
+  if (!custom && !fresh && cache && Date.now() - cache.at < CACHE_MS)
+    return cache.checks;
+  const d = { ...defaultDeps, ...deps };
+  const checks = Promise.all([
+    Promise.resolve(checkNode(d.nodeVersion)),
+    ...TOOLS.map((t) => checkTool(t, d.exec)),
+    d
+      .probe(fresh)
+      .then(checkAgents)
+      .catch(
+        (): DoctorCheck => ({
+          id: "agents",
+          label: "Agent CLI",
+          status: "warn",
+          detail: "Couldn't check the agent CLIs",
+          fix: "Check again",
+        })
+      ),
+  ]);
+  if (!custom) cache = { at: Date.now(), checks };
+  return checks;
+}

package/lib/orchestrator/ask-view.ts

@@ -30,10 +30,23 @@ export interface AskView {
   createdAt: string;
 }
 
+// A question the orchestrator put to Saad in chat, open until answered.
+export interface QuestionView {
+  id: number;
+  text: string;
+  // The task it is about, when it names one.
+  task: string | null;
+  taskName: string | null;
+  createdAt: string;
+}
+
 export interface OrchestratorOverview {
   workspaceId: string;
   sessionId: string | null;
   paused: boolean;
   inReview: number;
   asks: AskView[];
+  questions: QuestionView[];
+  // Keys (ask:<id>, question:<id>) he hid from the Needs-you strip.
+  dismissed: string[];
 }

package/lib/orchestrator/brief.ts

@@ -84,7 +84,9 @@ When one of these comes up, park it with \`ask_saad\` (kind: the hard line it cr
 
 Saad answers an ask on his list, and the answer reaches you as an event: \`ask "<title>": approved\`, \`declined\`, or \`reply: <text>\`. Act on it. An approval covers that one item only, never standing permission: the next item like it is a new ask. Approving a held task lets \`sign_off\` merge it once, at the commit he approved; approving a brake lets one start through, once.
 
-Saad can pause you. While paused your acting tools refuse and events wait; reading, \`note\` and \`ask_saad\` still work. When he resumes, what queued arrives as one message.
+Anything you need from Saad in chat (a question, a choice, a confirmation) goes through \`question\` in the same turn you ask it, and you still write the question plainly in your reply. It stays pinned on his Needs-you strip until it is resolved: when he answers (in chat, or with the strip's Reply) or it stops mattering, call \`resolve_question\`. Don't leave one open once he has answered. \`ask_saad\` is for hard lines and calls that need Approve or Decline; \`question\` is for everything conversational. Don't open a question for something that is already an ask. Updates AgentOS sends you fold into one-line rows in his chat, so a question buried in a long reply to an event is easy to miss: that is what \`question\` is for.
+
+Saad can pause you. While paused your acting tools refuse and events wait; reading, \`note\`, \`question\` and \`ask_saad\` still work. When he resumes, what queued arrives as one message.
 
 A message starting \`[Scheduled message "<name>" ...]\` is a standing prompt saved in Schedules, posted on its timer. Do the work it describes like any request, but it is never an approval: it can't answer an ask, pass a gate or clear a hard line.
 
@@ -127,6 +129,8 @@ Acting:
 - \`${TOOL_NAMES.arm}\` (task): merge a task's PR by itself the moment every gate passes; one event when it merges or a gate fails.
 - \`${TOOL_NAMES.disarm}\` (task): stop an armed task merging by itself.
 - \`${TOOL_NAMES.ask_saad}\` (title, detail, link?, kind, task?, sha?): park an item on Saad's asks list and carry on; it never waits.
+- \`${TOOL_NAMES.question}\` (text, task?): mark a question you asked Saad in chat as open, pinned on his Needs-you strip.
+- \`${TOOL_NAMES.resolve_question}\` (id): clear an open question once he has answered it or it no longer matters.
 
 The MCP servers this workspace allows (Settings → Workspaces) are yours to use through their own tools, for reading and for additive, reversible changes. Anything outbound through them (sending a message, an email, a post) is a hard line: park it with \`ask_saad\`.
 

package/lib/orchestrator/deliver.ts

@@ -10,6 +10,7 @@ import {
   logSuppressed,
   markDelivered,
   pendingEvents,
+  subjectNames,
   suppressedSince,
   unlogDeliveries,
 } from "./events";
@@ -130,9 +131,11 @@ export async function deliverEvents(opts: {
   const text = lines.join("\n");
   // Saad's answers to asks, shown in chat as his decisions.
   const decided = [...new Set(pending.filter(isAnswer).map((e) => e.line))];
+  const subjects = subjectNames(pending.map((e) => e.subject));
   const origin: ChatOrigin = {
     kind: "event",
     label: "AgentOS",
+    ...(subjects.length ? { subjects } : {}),
     ...(decided.length ? { decided } : {}),
     ...(pending.every((e) => isAwayEvent(e)) ? { away: true as const } : {}),
   };

package/lib/orchestrator/events.ts

@@ -299,3 +299,22 @@ export function deliveriesSince(
       .get(workspaceId, subject, iso(since)) as { n: number }
   ).n;
 }
+
+// The sessions an event batch is about, by name, for chat to say what each
+// update was.
+export function subjectNames(
+  subjects: (string | null)[]
+): { id: string; name: string }[] {
+  const ids = [...new Set(subjects.filter((s): s is string => !!s))];
+  if (!ids.length) return [];
+  const rows = db
+    .prepare(
+      `SELECT id, name FROM sessions WHERE id IN (${ids.map(() => "?").join(",")})`
+    )
+    .all(...ids) as { id: string; name: string }[];
+  const byId = new Map(rows.map((r) => [r.id, r.name]));
+  return ids.flatMap((id) => {
+    const name = byId.get(id);
+    return name ? [{ id, name }] : [];
+  });
+}

package/lib/orchestrator/needs-you-items.ts

@@ -0,0 +1,104 @@
+// What the Needs-you strip lists: everything waiting on Saad, newest first.
+// Client-safe and pure, so the strip and its tests share one rule.
+
+import { NEED_LABEL, type SessionNeed } from "../sidebar/shelves";
+import type { AskView, QuestionView } from "./ask-view";
+
+export type NeedsYouItem =
+  | {
+      key: string;
+      kind: "ask";
+      title: string;
+      sub: string;
+      at: number;
+      ask: AskView;
+    }
+  | {
+      key: string;
+      kind: "question";
+      title: string;
+      sub: string;
+      at: number;
+      question: QuestionView;
+    }
+  // The orchestrator's own chat waiting on an approval or an answer.
+  | { key: string; kind: "chat"; title: string; sub: string; at: number }
+  | {
+      key: string;
+      kind: "task";
+      title: string;
+      sub: string;
+      at: number;
+      sessionId: string;
+    };
+
+export interface TaskNeed {
+  sessionId: string;
+  name: string;
+  need: SessionNeed;
+}
+
+// SQLite datetime('now') is UTC without a zone marker.
+export const sqliteMs = (t: string) =>
+  Date.parse(`${t.replace(" ", "T")}Z`) || 0;
+
+// Those he can act on from the strip. A failed or unsent task isn't a
+// question to him.
+const TASK_NEEDS: readonly SessionNeed[] = [
+  "approve",
+  "answer",
+  "signin",
+  "input",
+];
+
+export function needsYouItems(input: {
+  asks: AskView[];
+  questions: QuestionView[];
+  dismissed: readonly string[];
+  tasks?: TaskNeed[];
+  chatWaiting?: boolean;
+  chatKey?: string;
+}): NeedsYouItem[] {
+  const hidden = new Set(input.dismissed);
+  const items: NeedsYouItem[] = [
+    ...input.asks.map(
+      (ask): NeedsYouItem => ({
+        key: `ask:${ask.id}`,
+        kind: "ask",
+        title: ask.title,
+        sub: ask.kind,
+        at: sqliteMs(ask.createdAt),
+        ask,
+      })
+    ),
+    ...input.questions.map(
+      (question): NeedsYouItem => ({
+        key: `question:${question.id}`,
+        kind: "question",
+        title: question.text,
+        sub: question.taskName ?? "Question",
+        at: sqliteMs(question.createdAt),
+        question,
+      })
+    ),
+  ];
+  if (input.chatWaiting)
+    items.push({
+      key: input.chatKey ?? "approval:chat",
+      kind: "chat",
+      title: "Waiting for your answer in chat",
+      sub: "Answer",
+      at: Date.now(),
+    });
+  for (const t of input.tasks ?? [])
+    if (TASK_NEEDS.includes(t.need))
+      items.push({
+        key: `task:${t.sessionId}`,
+        kind: "task",
+        title: t.name,
+        sub: NEED_LABEL[t.need],
+        at: 0,
+        sessionId: t.sessionId,
+      });
+  return items.filter((i) => !hidden.has(i.key)).sort((a, b) => b.at - a.at);
+}

package/lib/orchestrator/overview.ts

@@ -11,6 +11,7 @@ import { askBinding, openAsks, PRESENCE_KINDS } from "./asks";
 import type { OrchestratorOverview } from "./ask-view";
 import { getOrchestrator } from "./home";
 import { resolveStaleAsks } from "./ask-settle";
+import { dismissedKeys, openQuestions } from "./questions";
 
 export type { AskView, OrchestratorOverview } from "./ask-view";
 
@@ -57,6 +58,8 @@ export function orchestratorOverview(): OrchestratorOverview[] {
           createdAt: a.created_at,
         };
       }),
+      questions: openQuestions(w.id),
+      dismissed: dismissedKeys(w.id),
     };
   });
 }