@saadnvd1/agent-os 0.3.658 → 0.3.660

package/lib/agents/launch.ts

@@ -10,6 +10,7 @@ import { runInBackground } from "../async-operations";
 import { trustPromptKeys } from "../tasks/state";
 import { BUS_BRIEF } from "./brief";
 import { selfUrl } from "./self-env";
+import { sessionPath } from "./tool-path";
 import { autoCompactEnv } from "../chat/refresh";
 import { subagentEnv } from "../models/subagents";
 import { COMPACT_BRIEF } from "../chat/working-state";
@@ -43,7 +44,7 @@ export function agentEnv(sessionId: string): Record<string, string> {
     ...subagentEnv(),
     AGENTOS_SESSION_ID: sessionId,
     AGENTOS_URL: selfUrl(),
-    PATH: `${AOS_BIN_DIR}:${process.env.PATH ?? ""}`,
+    PATH: `${AOS_BIN_DIR}:${sessionPath()}`,
   };
 }
 

package/lib/agents/tool-path.ts

@@ -0,0 +1,61 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+// Where Saad's language version managers and user-level tools put their
+// binaries, in the order they should win. A shell's rc files normally add
+// these; a session AgentOS starts doesn't read them, so `bin/rails` would
+// find the system Ruby. Built in code so it is fast and the same on the Mac
+// and the Linux box (missing dirs are skipped).
+const USER_TOOL_DIRS = [
+  ".rbenv/shims",
+  ".local/share/mise/shims",
+  ".asdf/shims",
+  ".pyenv/shims",
+  ".local/bin",
+  ".bun/bin",
+  ".cargo/bin",
+];
+const SYSTEM_TOOL_DIRS = ["/opt/homebrew/bin", "/opt/homebrew/sbin"];
+
+function isDir(p: string): boolean {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// `npm run` puts every node_modules/.bin from the server's directory upward on
+// PATH; for a session in another repo those would shadow the project's tools.
+function serverBinDirs(cwd: string): Set<string> {
+  const dirs = new Set<string>();
+  for (let d = path.resolve(cwd); ; d = path.dirname(d)) {
+    dirs.add(path.join(d, "node_modules", ".bin"));
+    if (path.dirname(d) === d) break;
+  }
+  return dirs;
+}
+
+export function sessionPath(
+  inherited: string | undefined = process.env.PATH,
+  home: string = os.homedir(),
+  cwd: string = process.cwd()
+): string {
+  const drop = serverBinDirs(cwd);
+  const out: string[] = [];
+  const seen = new Set<string>();
+  const add = (dir: string) => {
+    if (!dir || seen.has(dir)) return;
+    seen.add(dir);
+    out.push(dir);
+  };
+  for (const d of [
+    ...USER_TOOL_DIRS.map((d) => path.join(home, d)),
+    ...SYSTEM_TOOL_DIRS,
+  ])
+    if (isDir(d)) add(d);
+  for (const d of (inherited ?? "").split(path.delimiter))
+    if (!drop.has(d)) add(d);
+  return out.join(path.delimiter);
+}

package/lib/orchestrator/external-gates.ts

@@ -10,6 +10,7 @@
  * does carry is held to the same rules as a task's.
  */
 
+import { hasUiEvidence } from "../tasks/ui-change";
 import { MERGED_AS, mergePolicy } from "../tasks/merge-policy";
 import { mergePR } from "../tasks/merge-pr";
 import { attributionIn, codeReviewGate } from "../tasks/code-review";
@@ -171,7 +172,11 @@ export async function reviewExternal(
       goal: `${ext.title}\n\n${ext.body}`.slice(0, GOAL_CAP),
       repo: ext.repo,
       refs: refsOf(ext),
-      pr: { number: ext.number, url: ext.url },
+      pr: {
+        number: ext.number,
+        url: ext.url,
+        uiEvidence: hasUiEvidence(ext.body),
+      },
     },
     ext.pr.head,
     opts

package/lib/orchestrator/review-prompt.ts

@@ -7,7 +7,7 @@ import type { ChangedFile } from "./diff";
 
 export const REVIEW_SYSTEM = `You are an independent code reviewer. You did not write this change and you owe its author nothing. You review one pull request at one exact commit, checked out read-only in your working directory. You can read the checkout's files; you cannot edit anything or run commands.
 
-Look for what would be wrong if this merged: bugs, broken behaviour, missing error handling on real paths, security problems (secrets, injection, unsafe shell or SQL), data loss, and changes that don't do what the task asked. Style and taste are never blocking.
+Look for what would be wrong if this merged: bugs, broken behaviour, missing error handling on real paths, security problems (secrets, injection, unsafe shell or SQL), data loss, and changes that don't do what the task asked. Style and taste are never blocking, and neither is a missing screenshot or browser or simulator check: AgentOS notes that itself.
 
 A change that games a gate instead of passing it is always blocking: tests deleted, skipped or weakened, assertions loosened or changed to match wrong output, checks, lint rules or CI steps disabled or bypassed, or anything else that makes a failure stop showing rather than stop happening. Name what was weakened, at its file and line.
 

package/lib/orchestrator/review.ts

@@ -11,6 +11,7 @@
  * the orchestrator hears the verdict as an event.
  */
 
+import { uiEvidenceNote, withUiEvidenceNote } from "../tasks/ui-change";
 import { reviewGoal } from "../plans/features";
 import { pushReviewBlocked, pushReviewReady } from "../notify/push/events";
 import { db, type Session } from "../db";
@@ -89,7 +90,7 @@ export interface ReviewTarget {
   goal: string;
   repo: string;
   refs: Pick<Session, "base_branch" | "branch_name">;
-  pr: Pick<TaskPR, "number" | "url" | "scopeChange">;
+  pr: Pick<TaskPR, "number" | "url" | "scopeChange" | "uiEvidence">;
   task?: Session;
 }
 
@@ -192,7 +193,10 @@ async function reviewJob(
     const done = putCheck({
       ...row,
       kind: "review",
-      ...combineVerdicts(verdicts),
+      ...withUiEvidenceNote(
+        combineVerdicts(verdicts),
+        uiEvidenceNote(files, pr.uiEvidence)
+      ),
     });
     if (task?.lh_card_id)
       await checkScope({

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

@@ -142,6 +142,31 @@
         "port": {
           "type": "string",
           "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+        },
+        "viewports": {
+          "minItems": 1,
+          "maxItems": 4,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^\\d{3,4}x\\d{3,4}$"
+          }
+        },
+        "nav": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 40
+          },
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          }
+        },
+        "verify": {
+          "type": "boolean"
         }
       },
       "additionalProperties": false

package/lib/project-config/brief.ts

@@ -50,6 +50,20 @@ export function runningBrief(
     lines.push(
       `- \`${browse.map}\` maps every page to its URL: navigate by URL, don't explore.`
     );
+  const pages = Object.entries(browse?.nav ?? {});
+  if (pages.length)
+    lines.push(
+      `- Pages: ${pages
+        .map(([name, to]) => {
+          const url = /^https?:\/\//.test(to)
+            ? to
+            : port
+              ? `http://localhost:${port}${to.startsWith("/") ? "" : "/"}${to}`
+              : to;
+          return `${name} \`${withPorts(url, ports)}\``;
+        })
+        .join(", ")}.`
+    );
   if (browse)
     lines.push(
       "- Check state with the browser's text snapshot, not screenshots. Screenshot only the final changed screen, and just the changed element (its uid) rather than the full page where the tool allows; every image stays in your context."

package/lib/project-config/index.ts

@@ -200,3 +200,9 @@ export function projectEnv(
     env[name] = String(port);
   return env;
 }
+
+export const DEFAULT_VIEWPORTS = ["1440x900", "390x844"];
+
+// The sizes a UI change is checked at: the project's, else desktop and phone.
+export const viewportsOf = (browse: ProjectConfig["browse"]): string[] =>
+  browse?.viewports?.length ? browse.viewports : DEFAULT_VIEWPORTS;

package/lib/project-config/schema.ts

@@ -67,6 +67,27 @@ const browse = z.strictObject({
   login: z.string().min(1).optional(),
   map: projectPath.optional(),
   port: envName.optional(),
+  // Screen sizes a UI change is checked at, "WIDTHxHEIGHT".
+  viewports: z
+    .array(
+      z
+        .string()
+        .regex(/^\d{3,4}x\d{3,4}$/, "must be WIDTHxHEIGHT, like 390x844")
+    )
+    .min(1)
+    .max(4)
+    .optional(),
+  // A short page name to path map, for the pages worth knowing by heart.
+  nav: z
+    .record(z.string().min(1).max(40), z.string().min(1).max(200))
+    .refine(
+      (n) => Object.keys(n).length <= 15,
+      "at most 15 pages; use map for more"
+    )
+    .optional(),
+  // Force the browser-check section of a task's brief on or off; otherwise
+  // the project's files decide (lib/tasks/ui-brief.ts).
+  verify: z.boolean().optional(),
 });
 
 // An iOS simulator tasks may drive on a Mac (lib/simulator). `start` runs in

package/lib/resurrect/index.ts

@@ -33,7 +33,7 @@ import {
   transcriptPath,
   writeTranscript,
 } from "../tasks/transcript";
-import { buildTaskBrief, declaredTest } from "../tasks/brief";
+import { buildTaskBrief, briefFacts } from "../tasks/brief";
 import { syncTaskCardInBackground } from "../lumifyhub/task-cards";
 import { allocatePorts } from "../ports";
 import { loadProjectConfig, portBases } from "../project-config";
@@ -440,7 +440,7 @@ async function relaunch(s: Session, cwd: string): Promise<void> {
       ? buildTaskBrief({
           branch: s.branch_name,
           baseBranch: s.base_branch ?? "main",
-          test: declaredTest(cwd),
+          ...briefFacts(cwd),
         })
       : undefined,
   });

package/lib/tasks/brief.ts

@@ -1,4 +1,5 @@
-import { loadProjectConfig } from "../project-config";
+import { loadProjectConfig, type ProjectConfig } from "../project-config";
+import { uiKindOf, uiVerifyBrief, type UiKind } from "./ui-brief";
 
 // A task stacked on another task's unmerged branch.
 export interface StackedOn {
@@ -21,9 +22,18 @@ function stackedLines(baseBranch: string, stack: StackedOn): string {
 - Never merge or rebase onto the default branch yourself. When the parent merges, AgentOS rebases your branch and retargets your PR, then tells you; re-run your checks when it does. AgentOS reviews your PR itself; a review of your head still counts for the head its restack left, and a push after that gets a new one.${also}`;
 }
 
-// The project's declared test command, read from the checkout the task runs in.
-export function declaredTest(cwd: string): string | undefined {
-  return loadProjectConfig(cwd).config.test || undefined;
+// What a brief needs from the checkout's config, from one read.
+export function briefFacts(cwd: string): {
+  test?: string;
+  ui: UiKind | null;
+  browse: ProjectConfig["browse"];
+} {
+  const { config } = loadProjectConfig(cwd);
+  return {
+    test: config.test || undefined,
+    ui: uiKindOf(cwd, config),
+    browse: config.browse,
+  };
 }
 
 function checksLine(test?: string): string {
@@ -40,8 +50,11 @@ export function buildTaskBrief(opts: {
   stack?: StackedOn;
   // The project's `test` from agentos.json, when it declares one.
   test?: string;
+  // Whether the project has a UI to check, and how it is browsed.
+  ui?: UiKind | null;
+  browse?: ProjectConfig["browse"];
 }): string {
-  return `You are running as an AgentOS background task, alone, in an isolated git worktree.
+  const base = `You are running as an AgentOS background task, alone, in an isolated git worktree.
 
 - Branch: ${opts.branch} (based on ${opts.baseBranch}). Stay in this directory and on this branch.
 - Do the task fully. ${checksLine(opts.test)}
@@ -51,4 +64,6 @@ export function buildTaskBrief(opts: {
 - Write scratch files (PR bodies, review notes, logs, test output) outside the worktree, in your scratchpad or \$TMPDIR. Anything uncommitted left in the worktree keeps it from being removed when the task is done.
 - Do not add any AI or assistant attribution to commits or the pull request.
 - If you are blocked or need a decision only a human can make, print one line starting with "BLOCKED:" that says what you need, then stop and wait.`;
+  const ui = uiVerifyBrief(opts.ui ?? null, opts.browse);
+  return ui ? `${base}\n\n${ui}` : base;
 }

package/lib/tasks/gh.ts

@@ -1,4 +1,5 @@
 import { execFile } from "child_process";
+import { hasUiEvidence } from "./ui-change";
 import { promisify } from "util";
 import { git } from "../git-exec";
 import { attributionIn } from "./code-review";
@@ -118,6 +119,7 @@ export async function toTaskPR(repoDir: string, pr: ListedPR): Promise<TaskPR> {
     attribution:
       pr.body === undefined ? undefined : (attributionIn(pr.body) ?? null),
     scopeChange: parseScopeChange(pr.body),
+    ...(pr.body !== undefined && { uiEvidence: hasUiEvidence(pr.body) }),
     ...(pr.mergeable && { mergeable: pr.mergeable }),
     ...(pr.baseRefName && { base: pr.baseRefName }),
   };

package/lib/tasks/import.ts

@@ -23,7 +23,7 @@ import { resolveModelForAgent } from "../model-catalog";
 import { providerFor } from "../models/resolve";
 import { preparePlanDir, PLAN_FILE } from "../models/plan-step";
 import { carryTaskState } from "./move-carry";
-import { buildTaskBrief, declaredTest } from "./brief";
+import { buildTaskBrief, briefFacts } from "./brief";
 import { expandHome } from "./session";
 import { ensureProject } from "./project-ref";
 import { checkoutBranchWorktree } from "./branch-worktree";
@@ -141,7 +141,7 @@ async function arrive(
   const brief = buildTaskBrief({
     branch: bundle.branch,
     baseBranch,
-    test: declaredTest(worktreePath),
+    ...briefFacts(worktreePath),
   });
   // Checked and written with no await between, so two can't both pass.
   db.transaction(() => {

package/lib/tasks/index.ts

@@ -33,7 +33,7 @@ import { agentLabel } from "../agent-options";
 import { supportsChat } from "../chat/capabilities";
 import { AGENT_DEFAULT_MODEL } from "../providers/registry";
 import { statusDetector } from "../status-detector";
-import { buildTaskBrief, declaredTest, type StackedOn } from "./brief";
+import { buildTaskBrief, briefFacts, type StackedOn } from "./brief";
 import {
   attachTaskCard,
   inBackground,
@@ -382,7 +382,7 @@ async function startTask(
         branch: wt.branchName,
         baseBranch,
         stack: opts.base?.stack,
-        test: declaredTest(wt.worktreePath),
+        ...briefFacts(wt.worktreePath),
       }),
       task_status: "running",
       model_overrides: routing.override

package/lib/tasks/move.ts

@@ -13,7 +13,7 @@ import { db, type Session } from "../db";
 import { getProject } from "../projects";
 import { endTmuxSession } from "../tmux/end";
 import { launchClaude } from "../agents/launch";
-import { buildTaskBrief, declaredTest } from "./brief";
+import { buildTaskBrief, briefFacts } from "./brief";
 import { git as runGit } from "../git-exec";
 import { getTaskSession, isoUTC } from "./session";
 import { projectRef } from "./project-ref";
@@ -309,7 +309,7 @@ async function relaunch(session: Session, note?: string): Promise<void> {
       ? buildTaskBrief({
           branch: session.branch_name,
           baseBranch: session.base_branch ?? "main",
-          test: declaredTest(session.working_directory),
+          ...briefFacts(session.working_directory),
         })
       : undefined,
   });

package/lib/tasks/state.ts

@@ -27,6 +27,9 @@ export interface TaskPR {
   attribution?: AttributionKind | null;
   // The body's "Scope change" note (tasks/scope-change.ts), when it has one.
   scopeChange?: string | null;
+  // Whether the body shows a browser or simulator check (tasks/ui-change.ts);
+  // undefined when the body wasn't read.
+  uiEvidence?: boolean;
   // GitHub's word on merging it into its base: CONFLICTING once the base
   // moved under it (UNKNOWN while GitHub works it out).
   mergeable?: "MERGEABLE" | "CONFLICTING" | "UNKNOWN";

package/lib/tasks/ui-brief.ts

@@ -0,0 +1,85 @@
+// The browser-check section of a task's brief, ported from dispatch's
+// browser_brief. A project's files decide whether a task gets it, not the
+// prompt: the PRs that skipped a check were ones whose prompt never said UI.
+
+import * as fs from "fs";
+import * as path from "path";
+import { viewportsOf } from "../project-config";
+import type { ProjectConfig } from "../project-config";
+
+export type UiKind = "web" | "simulator";
+
+const WEB_DEPS = [
+  "react",
+  "next",
+  "vue",
+  "nuxt",
+  "svelte",
+  "@sveltejs/kit",
+  "astro",
+  "solid-js",
+  "preact",
+  "@angular/core",
+];
+const NATIVE_DEPS = ["react-native", "expo"];
+
+function deps(cwd: string): Set<string> {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(cwd, "package.json"), "utf8")
+    );
+    return new Set([
+      ...Object.keys(pkg.dependencies ?? {}),
+      ...Object.keys(pkg.devDependencies ?? {}),
+    ]);
+  } catch {
+    return new Set();
+  }
+}
+
+function isRailsApp(cwd: string): boolean {
+  try {
+    return (
+      /^\s*gem\s+["']rails["']/m.test(
+        fs.readFileSync(path.join(cwd, "Gemfile"), "utf8")
+      ) && fs.statSync(path.join(cwd, "app", "views")).isDirectory()
+    );
+  } catch {
+    return false;
+  }
+}
+
+// Deterministic and cheap: the config, then two small file reads.
+export function uiKindOf(cwd: string, config: ProjectConfig): UiKind | null {
+  if (config.browse?.verify === false) return null;
+  if (config.simulator) return "simulator";
+  if (config.browse) return "web";
+  const have = deps(cwd);
+  if (NATIVE_DEPS.some((d) => have.has(d))) return null;
+  if (WEB_DEPS.some((d) => have.has(d)) || isRailsApp(cwd)) return "web";
+  return null;
+}
+
+export const SCREENSHOT_DIR = ".agentos/screenshots";
+
+export function uiVerifyBrief(
+  kind: UiKind | null,
+  browse?: ProjectConfig["browse"]
+): string {
+  if (!kind) return "";
+  if (kind === "simulator")
+    return `## Checking UI changes
+
+If your diff changes what a user sees, check the changed screens in the iOS simulator, as "Running this project" describes, before calling it done. Fix anything visibly off. Add a **Simulator check** section to the PR body: the screens you checked, what you looked for, and the screenshot names. If you didn't check, say why in one line.`;
+  const sizes = viewportsOf(browse).join(" and ");
+  return `## Checking UI changes
+
+If your diff changes what a user sees, run the app and look at every changed screen in a real browser before calling it done, at ${sizes} (\`resize_page\` between them). Do it cheaply:
+
+- The browser is the **\`chrome-devtools\`** MCP server. Load \`mcp__chrome-devtools__new_page\`, \`navigate_page\`, \`resize_page\`, \`take_snapshot\`, \`take_screenshot\` and \`evaluate_script\` with ToolSearch. Don't load or call \`mcp__claude-in-chrome__*\`: it isn't configured here and its first call hangs for 30 seconds. If no \`chrome-devtools\` server is available, say so in the PR and describe what you checked instead.
+- Log in and go to pages by URL, from the login, pages and map under "Running this project" when they are there. Exploring the UI to find a page is the most expensive thing a session does.
+- One snapshot to find a uid, then act. Verify with a screenshot of the one element or a small \`evaluate_script\` returning the one value you need, not another full snapshot.
+- Verify the thing that would be wrong, not the thing that is easy to see: a page that rendered proves it rendered. Fix anything visibly off (gaps, clipping, overlap, horizontal scroll, stray bands, misalignment; measure rects with \`evaluate_script\` and report numbers) and read the console for errors.
+- Save screenshots of the final changed screens with \`filePath\` under \`${SCREENSHOT_DIR}/\`, after \`mkdir -p ${SCREENSHOT_DIR} && printf '*\\n' > .agentos/.gitignore\`. That folder is inside the browser's allowed root and git ignores it; a path in /tmp is refused.
+- Add a **Browser check** section to the PR body: the pages and widths you checked, what you fixed, and the screenshot file names. If you didn't check (no visible change, or no browser), say why in one line.`;
+}

package/lib/tasks/ui-change.ts

@@ -0,0 +1,57 @@
+// Whether a change touches what a user sees, and whether its PR body shows
+// anyone looked. The note it makes is for the reviewer's detail only: UI
+// screenshots are not a merge gate, so it can never change a verdict.
+
+import type { ChangedFile } from "../orchestrator/diff";
+import type { CheckStatus } from "../orchestrator/checks";
+import { renderedLines } from "./code-review";
+
+const UI_EXT =
+  /\.(tsx|jsx|vue|svelte|astro|css|scss|sass|less|html|erb|haml|slim)$/i;
+const UI_DIR = /(^|\/)(app\/views|app\/components)\//;
+const SWIFT_VIEW = /(^|\/)(Views?\/.*|\w*Views?)\.swift$/;
+const NOT_UI = /(\.(test|spec|stories)\.|(^|\/)(__tests__|spec|tests?|e2e)\/)/;
+
+export function isUiPath(file: string): boolean {
+  if (NOT_UI.test(file)) return false;
+  return UI_EXT.test(file) || UI_DIR.test(file) || SWIFT_VIEW.test(file);
+}
+
+export function uiFilesIn(files: ChangedFile[]): string[] {
+  return files
+    .filter((f) => f.status !== "D" && isUiPath(f.path))
+    .map((f) => f.path);
+}
+
+const IMAGE =
+  /!\[|<img\b|\.(png|jpe?g|webp|gif)\b|user-images|githubusercontent/i;
+const DESCRIBED =
+  /browser check|simulator check|screenshot|chrome-devtools|viewports?\b|\b\d{3,4}\s*[x×]\s*\d{3,4}\b|in (a|the) (real )?browser|in the (ios )?simulator/i;
+
+// Lenient on purpose: a nudge, not a gate. Undefined when the body wasn't read.
+export function hasUiEvidence(
+  body: string | null | undefined
+): boolean | undefined {
+  if (body === null || body === undefined) return undefined;
+  return renderedLines(body).some((l) => IMAGE.test(l) || DESCRIBED.test(l));
+}
+
+export function uiEvidenceNote(
+  files: ChangedFile[],
+  evidence: boolean | undefined
+): string | null {
+  const ui = uiFilesIn(files);
+  if (!ui.length || evidence !== false) return null;
+  const shown = ui.slice(0, 3).join(", ");
+  const more = ui.length > 3 ? `, +${ui.length - 3} more` : "";
+  return `[minor] ${shown}${more}: this changes UI files and the PR body has no browser or simulator evidence (screenshots or a described check). Not a merge gate; add a Browser check section if you checked.`;
+}
+
+export function withUiEvidenceNote(
+  verdict: { status: CheckStatus; detail: string },
+  note: string | null
+): { status: CheckStatus; detail: string } {
+  return note
+    ? { status: verdict.status, detail: `${verdict.detail}\n- ${note}`.trim() }
+    : verdict;
+}

package/package.json

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