@saadnvd1/agent-os 0.3.523 → 0.3.527

package/lib/orchestrator/questions.ts

@@ -0,0 +1,120 @@
+/**
+ * Questions the orchestrator puts to Saad in chat. Marking one open pins it
+ * on his Needs-you strip until he answers it (the strip's Reply) or the
+ * orchestrator clears it. Unlike an ask it has no Approve or Decline: it is
+ * just words that need an answer. Dismissing an item from the strip only
+ * hides it, for asks and questions alike.
+ */
+
+import { db } from "../db";
+import type { QuestionView } from "./ask-view";
+import { workspaceTask } from "./targets";
+
+export const MAX_OPEN_QUESTIONS = 10;
+
+interface QuestionRow {
+  id: number;
+  text: string;
+  task: string | null;
+  task_name: string | null;
+  created_at: string;
+}
+
+export function openQuestions(workspaceId: string): QuestionView[] {
+  settleQuestions(workspaceId);
+  return (
+    db
+      .prepare(
+        `SELECT q.id, q.text, q.task, s.name AS task_name, q.created_at
+         FROM orchestrator_questions q LEFT JOIN sessions s ON s.id = q.task
+         WHERE q.workspace_id = ? AND q.status = 'open'
+         ORDER BY q.id DESC`
+      )
+      .all(workspaceId) as QuestionRow[]
+  ).map((r) => ({
+    id: r.id,
+    text: r.text,
+    task: r.task,
+    taskName: r.task_name,
+    createdAt: r.created_at,
+  }));
+}
+
+// A question about work that has finished no longer needs an answer.
+function settleQuestions(workspaceId: string): void {
+  db.prepare(
+    `UPDATE orchestrator_questions
+     SET status = 'cleared', resolved_by = 'orchestrator', resolved_at = datetime('now')
+     WHERE workspace_id = ? AND status = 'open' AND task IN (
+       SELECT id FROM sessions WHERE task_status IN ('merged', 'dropped', 'done'))`
+  ).run(workspaceId);
+}
+
+// The same words while open are the same question.
+export function askQuestion(
+  workspaceId: string,
+  text: string,
+  taskRef?: string
+): string {
+  const task = taskRef ? workspaceTask(workspaceId, taskRef).id : null;
+  const open = db
+    .prepare(
+      `SELECT id FROM orchestrator_questions
+       WHERE workspace_id = ? AND status = 'open' AND text = ?`
+    )
+    .get(workspaceId, text) as { id: number } | undefined;
+  if (open) return `Question ${open.id} is already open; left as it is.`;
+  const count = (
+    db
+      .prepare(
+        `SELECT COUNT(*) AS n FROM orchestrator_questions
+         WHERE workspace_id = ? AND status = 'open'`
+      )
+      .get(workspaceId) as { n: number }
+  ).n;
+  if (count >= MAX_OPEN_QUESTIONS)
+    return `Not opened: ${count} questions are already open. Clear the ones that no longer matter with resolve_question first.`;
+  const { lastInsertRowid } = db
+    .prepare(
+      `INSERT INTO orchestrator_questions (workspace_id, text, task) VALUES (?, ?, ?)`
+    )
+    .run(workspaceId, text, task);
+  return `Question ${lastInsertRowid} is open on Saad's Needs-you strip. Call resolve_question ${lastInsertRowid} once he has answered or it no longer matters.`;
+}
+
+export function resolveQuestion(
+  workspaceId: string,
+  id: number,
+  by: "saad" | "orchestrator"
+): boolean {
+  return (
+    db
+      .prepare(
+        `UPDATE orchestrator_questions
+         SET status = ?, resolved_by = ?, resolved_at = datetime('now')
+         WHERE id = ? AND workspace_id = ? AND status = 'open'`
+      )
+      .run(by === "saad" ? "answered" : "cleared", by, id, workspaceId)
+      .changes > 0
+  );
+}
+
+export function dismissItem(workspaceId: string, key: string): void {
+  db.prepare(
+    `INSERT OR IGNORE INTO needs_you_dismissed (workspace_id, key) VALUES (?, ?)`
+  ).run(workspaceId, key);
+}
+
+export function undismissItem(workspaceId: string, key: string): void {
+  db.prepare(
+    `DELETE FROM needs_you_dismissed WHERE workspace_id = ? AND key = ?`
+  ).run(workspaceId, key);
+}
+
+export function dismissedKeys(workspaceId: string): string[] {
+  return (
+    db
+      .prepare(`SELECT key FROM needs_you_dismissed WHERE workspace_id = ?`)
+      .all(workspaceId) as { key: string }[]
+  ).map((r) => r.key);
+}

package/lib/orchestrator/serve.ts

@@ -23,6 +23,7 @@ import { addNote } from "./notes";
 import { addProject } from "./add-project";
 import { addRule, removeRule } from "./rules";
 import { askSaad } from "./ask-tool";
+import { askQuestion, resolveQuestion } from "./questions";
 import { listOrchestratorPeers, messageOrchestrator } from "./cross";
 import { PAUSED_REFUSAL } from "./pause";
 import { readSession } from "./read";
@@ -211,5 +212,15 @@ export async function runTool(
       return disarm(w, p(tool, raw).task);
     case "ask_saad":
       return askSaad(w, p(tool, raw));
+    case "question": {
+      const a = p(tool, raw);
+      return askQuestion(w, a.text, a.task);
+    }
+    case "resolve_question": {
+      const id = p(tool, raw).id;
+      return resolveQuestion(w, id, "orchestrator")
+        ? `Question ${id} cleared.`
+        : `No open question ${id}.`;
+    }
   }
 }

package/lib/orchestrator/tool-names.ts

@@ -29,6 +29,8 @@ export const TOOL_NAMES = {
   done: name("done"),
   add_project: name("add_project"),
   note: name("note"),
+  question: name("question"),
+  resolve_question: name("resolve_question"),
   rule_add: name("rule_add"),
   rule_remove: name("rule_remove"),
   review: name("review"),

package/lib/orchestrator/tool-schemas.ts

@@ -239,6 +239,18 @@ export const TOOL_SHAPES = {
       .describe("A new project's name (default: the folder's)"),
   },
   note: { text: z.string().trim().min(1).max(2000) },
+  question: {
+    text: z
+      .string()
+      .trim()
+      .min(1)
+      .max(300)
+      .describe("The question as you asked it in chat, one or two sentences"),
+    task: ref("The task it is about, when it names one").optional(),
+  },
+  resolve_question: {
+    id: z.number().int().positive().describe("The question's id"),
+  },
   rule_add: {
     text: z
       .string()

package/lib/orchestrator/tools.ts

@@ -101,6 +101,10 @@ const DESCRIPTIONS: Record<ToolName, string> = {
   arm: "Arm a task's PR to merge: AgentOS merges it, through the same gates as sign_off, the moment they all pass at its head, and tells you with one event. A gate failure comes as one event and it stays armed for the fix; one that goes to Saad disarms it. Survives restarts. Use it instead of calling sign_off until it passes.",
   disarm:
     "Disarm a task armed to merge: it merges only through sign_off again.",
+  question:
+    "Mark a question you asked Saad in chat as open: it stays pinned on his Needs-you strip until he answers or you clear it. Use it for anything you need from him that isn't an ask_saad item. The same text while open is the same question.",
+  resolve_question:
+    "Clear an open question once Saad has answered it in chat, or it no longer matters.",
   ask_saad:
     "Park an item on Saad's asks list (a decision, or anything crossing a hard line) and carry on; it never waits. One open ask per title. His answer reaches you as an event. To ask whether to merge a PR the gates refuse, give task and sha (its head): his approval lets sign_off merge it once, at that commit.",
 };

package/lib/project-config/agentos.schema.json

@@ -132,6 +132,25 @@
       },
       "additionalProperties": false
     },
+    "simulator": {
+      "type": "object",
+      "properties": {
+        "start": {
+          "type": "string",
+          "minLength": 1
+        },
+        "app": {
+          "type": "string",
+          "minLength": 1
+        },
+        "device": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": ["start"],
+      "additionalProperties": false
+    },
     "database": {
       "type": "object",
       "properties": {

package/lib/project-config/brief.ts

@@ -13,6 +13,7 @@ import {
   type ProjectConfig,
 } from "./index";
 import { databaseBrief, type SessionDatabase } from "./database";
+import { simulatorBrief } from "../simulator/brief";
 
 export function runningBrief(
   config: ProjectConfig,
@@ -49,6 +50,8 @@ export function runningBrief(
     lines.push(
       `- \`${browse.map}\` maps every page to its URL: navigate by URL, don't explore.`
     );
+  const sim = simulatorBrief(config.simulator);
+  if (sim) lines.push(sim);
   for (const note of notesOf(config.notes))
     lines.push(`- ${withPorts(note, ports)}`);
   return lines.length ? `## Running this project\n\n${lines.join("\n")}` : "";

package/lib/project-config/schema.ts

@@ -60,6 +60,15 @@ const browse = z.strictObject({
   port: envName.optional(),
 });
 
+// An iOS simulator tasks may drive on a Mac (lib/simulator). `start` runs in
+// the task's worktree with SIMULATOR_UDID set, builds and installs the app
+// on that device and exits 0 once it is up.
+const simulator = z.strictObject({
+  start: z.string().min(1),
+  app: z.string().min(1).optional(),
+  device: z.string().min(1).optional(),
+});
+
 const database = z.strictObject({
   from: z.string().min(1),
   env: projectEnvName.optional(),
@@ -109,6 +118,7 @@ const shape = {
   test: z.string().min(1).optional(),
   notes: notes.optional(),
   browse: browse.optional(),
+  simulator: simulator.optional(),
   database: database.optional(),
   mcp: z.array(z.string().min(1)).optional(),
   model: z.string().min(1).optional(),

package/lib/sessions/end.ts

@@ -2,6 +2,7 @@ import type { Session } from "../db";
 import { stopChat } from "../chat/runner";
 import { waitForExit } from "../chat/worker/client";
 import { endTmuxSession } from "../tmux/end";
+import { releaseOnEnd } from "../simulator";
 
 type Agent = Pick<Session, "id" | "host_id" | "tmux_name">;
 
@@ -10,6 +11,8 @@ type Agent = Pick<Session, "id" | "host_id" | "tmux_name">;
 // finish share.
 export async function endSessionAgent(s: Agent): Promise<void> {
   stopChat(s.id);
+  // The task's simulator goes with it; no row, no work.
+  releaseOnEnd(s.id, { remove: true });
   void waitForExit(s.id).catch(() => {});
   await endTmuxSession(s.host_id, s.tmux_name);
 }

package/lib/sessions/stop.ts

@@ -3,6 +3,7 @@ import { hostLink } from "../hosts/remote-api";
 import { stopChatTurn } from "../chat/stop";
 import type { Session } from "../db";
 import { stopHeldTask } from "../tasks/held-remote";
+import { releaseOnEnd } from "../simulator";
 
 // Stops a session's agent and keeps everything else, the same for every
 // caller (the orchestrator's stop tool, `aos stop`): a chat's turn ends
@@ -33,10 +34,12 @@ export async function stopSession(
     const out = await stopChatTurn(s.id);
     if (!out.stopped)
       throw new Error(`Couldn't stop ${s.name}: ${out.reason}.`);
+    releaseOnEnd(s.id, { remove: false });
     return out.killed
       ? `Stopped ${s.name}: its agent didn't answer the interrupt, so it was ended. Its conversation and worktree are kept; your next message runs as its next turn.`
       : `Stopped ${s.name}'s turn. Your next message runs as its next turn.`;
   }
   await endTmuxSession(s.host_id, s.tmux_name);
+  releaseOnEnd(s.id, { remove: false });
   return `Stopped ${s.name}: its agent is ended, its worktree and branch are kept.`;
 }

package/lib/simulator/agent-device.ts

@@ -0,0 +1,258 @@
+/**
+ * Driving a simulator: the `agent-device` CLI (an XCTest runner behind an
+ * accessibility-tree snapshot with element refs), pinned and installed on
+ * first use. The task never names a device or session: they are injected
+ * here, so it can only drive its own simulator.
+ */
+
+import { execFile } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { promisify } from "util";
+
+const execFileAsync = promisify(execFile);
+
+export const AGENT_DEVICE_VERSION = "0.21.27";
+
+const root = () => path.join(os.homedir(), ".agent-os");
+export const toolDir = () =>
+  path.join(root(), "tools", `agent-device-${AGENT_DEVICE_VERSION}`);
+export const toolBin = () =>
+  path.join(toolDir(), "node_modules/.bin/agent-device");
+// Its daemon, device claims and XCTest runner cache stay apart from any other
+// copy of the tool on this Mac.
+export const stateDir = () => path.join(root(), "agent-device");
+export const simulatorDir = (sessionId: string) =>
+  path.join(root(), "simulators", sessionId);
+export const shotsDir = (sessionId: string) =>
+  path.join(simulatorDir(sessionId), "shots");
+
+export const ALLOWED = new Set([
+  "snapshot",
+  "click",
+  "press",
+  "longpress",
+  "fill",
+  "type",
+  "scroll",
+  "swipe",
+  "back",
+  "home",
+  "find",
+  "get",
+  "wait",
+  "screenshot",
+  "apps",
+  "relaunch",
+]);
+
+// Flags that pick a device, a session or where the tool keeps its state.
+const REFUSED = new Set([
+  "--udid",
+  "--device",
+  "--serial",
+  "--session",
+  "--state-dir",
+  "--platform",
+  "--ios-simulator-device-set",
+  "--ios-xctest-derived-data-path",
+]);
+
+export interface Target {
+  udid: string;
+  sessionId: string;
+  app?: string | null;
+  // The task's worktree: with the shots dir, the only place a screenshot may
+  // be written. Relative paths are taken from here.
+  cwd?: string | null;
+}
+
+// The tool's session on the task's device, attached to the app.
+export function openArgs(target: Target): string[] {
+  return [
+    "open",
+    target.app ?? "",
+    "--platform",
+    "ios",
+    "--udid",
+    target.udid,
+    "--session",
+    agentSession(target.sessionId),
+  ];
+}
+
+export const agentSession = (sessionId: string) =>
+  `aos-${sessionId.replace(/-/g, "").slice(0, 8)}`;
+
+// The argv for one call, or why it is refused.
+export function buildArgs(
+  args: string[],
+  target: Target,
+  now = () => Date.now()
+): string[] {
+  const [sub, ...rest] = args;
+  if (!sub || !ALLOWED.has(sub))
+    throw new Error(
+      `aos sim ${sub ?? ""}: not allowed. Use: ${[...ALLOWED].join(", ")}`
+    );
+  for (const a of rest) {
+    const flag = a.split("=")[0];
+    if (REFUSED.has(flag))
+      throw new Error(
+        `${flag} is set for you: the simulator is this task's own`
+      );
+  }
+  // `aos sim open` is AgentOS's own; the tool's `open` is how a session is
+  // attached to the app, which bring-up does and `relaunch` repeats.
+  const out =
+    sub === "relaunch"
+      ? ["open", ...(target.app ? [target.app] : []), "--relaunch", ...rest]
+      : [sub, ...rest];
+  if (sub === "screenshot") {
+    const at = shotArg(out);
+    if (!at) out.push(path.join(shotsDir(target.sessionId), `${now()}.png`));
+    else
+      out[at.index] =
+        at.prefix + safeShotPath(out[at.index].slice(at.prefix.length), target);
+  }
+  return [
+    ...out,
+    "--platform",
+    "ios",
+    "--udid",
+    target.udid,
+    "--session",
+    agentSession(target.sessionId),
+  ];
+}
+
+const within = (dir: string, file: string) => {
+  const rel = path.relative(dir, file);
+  return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+};
+
+// Resolves through symlinks as far as the path exists, so a link inside the
+// worktree can't lead the write elsewhere.
+function realish(file: string): string {
+  const rest: string[] = [];
+  let dir = file;
+  for (;;) {
+    try {
+      return path.join(fs.realpathSync(dir), ...rest.reverse());
+    } catch {
+      const up = path.dirname(dir);
+      if (up === dir) return file;
+      rest.push(path.basename(dir));
+      dir = up;
+    }
+  }
+}
+
+// A screenshot goes under the session's shots dir or the task's worktree, as
+// a .png; anything else is refused.
+function safeShotPath(given: string, target: Target): string {
+  const base = target.cwd ?? shotsDir(target.sessionId);
+  const full = realish(path.resolve(base, given));
+  const roots = [shotsDir(target.sessionId), target.cwd].flatMap((r) =>
+    r ? [realish(r)] : []
+  );
+  if (!full.endsWith(".png") || !roots.some((r) => within(r, full)))
+    throw new Error(
+      "screenshot: the path must be a .png under this task's worktree or its simulator shots folder"
+    );
+  return full;
+}
+
+const VALUE_FLAGS = new Set(["--crop-on", "--pixel-density", "--scale"]);
+
+// Where a screenshot argv names its file: a positional path or --out.
+function shotArg(argv: string[]): { index: number; prefix: string } | null {
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--out")
+      return argv[i + 1] === undefined ? null : { index: i + 1, prefix: "" };
+    if (a.startsWith("--out=")) return { index: i, prefix: "--out=" };
+    if (VALUE_FLAGS.has(a)) i++;
+    else if (!a.startsWith("-")) return { index: i, prefix: "" };
+  }
+  return null;
+}
+
+// The screenshot path a built argv will write, if it is one.
+export const screenshotPath = (argv: string[]): string | null => {
+  if (argv[0] !== "screenshot") return null;
+  const at = shotArg(argv);
+  return at ? argv[at.index].slice(at.prefix.length) : null;
+};
+
+// What the tool and its install get: no tokens or project secrets from the
+// server's environment, only what it needs to find Xcode and a home.
+const ENV_KEYS = ["PATH", "HOME", "TMPDIR", "LANG", "DEVELOPER_DIR"];
+export const toolEnv = (): NodeJS.ProcessEnv =>
+  ({
+    ...Object.fromEntries(
+      ENV_KEYS.filter((k) => process.env[k]).map((k) => [k, process.env[k]])
+    ),
+    AGENT_DEVICE_STATE_DIR: stateDir(),
+  }) as unknown as NodeJS.ProcessEnv;
+
+let installing: Promise<void> | null = null;
+
+export function ensureInstalled(): Promise<void> {
+  if (fs.existsSync(toolBin())) return Promise.resolve();
+  installing ??= (async () => {
+    fs.mkdirSync(toolDir(), { recursive: true });
+    await execFileAsync(
+      "npm",
+      [
+        "install",
+        "--prefix",
+        toolDir(),
+        "--no-audit",
+        "--no-fund",
+        // agent-device has no install scripts; none are run for it or its deps.
+        "--ignore-scripts",
+        `agent-device@${AGENT_DEVICE_VERSION}`,
+      ],
+      { timeout: 300_000, env: toolEnv() }
+    );
+  })().finally(() => {
+    installing = null;
+  });
+  return installing;
+}
+
+export interface CallResult {
+  stdout: string;
+  stderr: string;
+  code: number;
+}
+
+export async function callTool(
+  argv: string[],
+  timeoutMs = 120_000
+): Promise<CallResult> {
+  await ensureInstalled();
+  fs.mkdirSync(stateDir(), { recursive: true });
+  try {
+    const { stdout, stderr } = await execFileAsync(toolBin(), argv, {
+      env: toolEnv(),
+      timeout: timeoutMs,
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    return { stdout, stderr, code: 0 };
+  } catch (error) {
+    const e = error as {
+      stdout?: string;
+      stderr?: string;
+      code?: number | string;
+      message: string;
+    };
+    return {
+      stdout: e.stdout ?? "",
+      stderr: e.stderr || e.message,
+      code: typeof e.code === "number" ? e.code : 1,
+    };
+  }
+}

package/lib/simulator/available.ts

@@ -0,0 +1,5 @@
+import fs from "fs";
+
+// xcrun only exists on a Mac with Xcode.
+export const simulatorAvailable = (): boolean =>
+  process.platform === "darwin" && fs.existsSync("/usr/bin/xcrun");

package/lib/simulator/brief.ts

@@ -0,0 +1,18 @@
+import type { ProjectConfig } from "../project-config/schema";
+import { simulatorAvailable } from "./available";
+
+// What a task is told about the simulator: nothing when the project declares
+// none, one line when this machine can't run one.
+export function simulatorBrief(
+  sim: ProjectConfig["simulator"],
+  available = simulatorAvailable()
+): string {
+  if (!sim) return "";
+  if (!available)
+    return "- The iOS simulator tools are not available on this machine; skip simulator checks and say so in the PR.";
+  return [
+    "- iOS simulator (optional; it never gates a PR or a build, and a failure is reported, not a blocker): `aos sim open` makes your own simulator and installs this worktree's build (run it with run_in_background, a cold build takes minutes; `aos sim status` shows where it is).",
+    '  Then `aos sim snapshot -i` (accessibility tree with @refs), `aos sim click @e3`, `aos sim fill @e5 "text"`, `aos sim screenshot` (prints a PNG path; read it), `aos sim logs --last 2m`. Refs are only valid from the latest snapshot.',
+    "  Screenshots are written outside the worktree: don't put them in commits or the PR body unless they belong there. `aos sim close` when you're done; it is closed for you when the task ends.",
+  ].join("\n");
+}

package/lib/simulator/http.ts

@@ -0,0 +1,16 @@
+import { NextResponse } from "next/server";
+import { SimulatorError } from "./index";
+
+// A simulator call's failure as a response: its own errors carry their status.
+export function simulatorFailure(error: unknown) {
+  if (error instanceof SimulatorError)
+    return NextResponse.json(
+      { error: error.message },
+      { status: error.status }
+    );
+  console.error("[simulator]", error);
+  return NextResponse.json(
+    { error: error instanceof Error ? error.message : String(error) },
+    { status: 500 }
+  );
+}