@saadnvd1/agent-os 0.3.520 → 0.3.523

package/README.md

@@ -213,6 +213,17 @@ its WSL note, and Windows reached it at both `localhost:3011` and
 `wslview`/`explorer.exe`, mirrored networking, `agent-os enable` under
 systemd, the idle-timeout settings above, and Debian or other distros.
 
+### First run
+
+On a fresh install (no sessions, no projects of your own) the web app opens a
+short setup at `/?welcome`: it shows each agent CLI as ready, needing a
+sign-in, or missing, installs or signs one in from an embedded terminal, adds
+a first project (a folder, a clone or an empty one), then opens a session in
+it. Every step after the first can be skipped. It is remembered on the server,
+so a phone you pair later doesn't see it, and an install that already has work
+never does. Reopen it from Settings → Setup (**Run setup again**) or at
+`/welcome`; `AGENTOS_SKIP_WELCOME=1` turns it off.
+
 ### Supported agents
 
 | Agent       | Chat | Resume | Fork | Auto-approve                                 |

package/app/api/welcome/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { demoMode } from "@/lib/security/demo";
+import { completeWelcome, readWelcomeGate } from "@/lib/welcome";
+
+// Whether the first-run welcome should open on this server. An install
+// already in use is marked done here, so emptying it later doesn't bring it back.
+export async function GET() {
+  return NextResponse.json(readWelcomeGate(demoMode()));
+}
+
+// { action: "complete" }: setup finished or skipped.
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    if (body?.action !== "complete") throw new Error("Unknown action");
+    completeWelcome(new Date().toISOString(), undefined, true);
+    return NextResponse.json(readWelcomeGate(demoMode()));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return NextResponse.json({ error: message }, { status: 400 });
+  }
+}

package/app/page.tsx

@@ -78,6 +78,11 @@ const SettingsDialog = dynamic(
     ),
   { ssr: false }
 );
+const WelcomeDialog = dynamic(
+  () =>
+    import("@/components/Welcome/WelcomeDialog").then((m) => m.WelcomeDialog),
+  { ssr: false }
+);
 const MessagesDialog = dynamic(
   () => import("@/components/Bus/MessagesDialog").then((m) => m.MessagesDialog),
   { ssr: false }
@@ -122,6 +127,7 @@ const AppDialogs = memo(function AppDialogs() {
   return (
     <>
       <TasksDialog />
+      <WelcomeDialog />
       <AddProjectDialog />
       <MessagesDialog />
       <ArchivedDialog />

package/app/welcome/page.tsx

@@ -0,0 +1,6 @@
+import { redirect } from "next/navigation";
+
+// Reopens the first-run welcome.
+export default function WelcomePage() {
+  redirect("/?welcome=agents");
+}

package/components/Chat/BackgroundTasks.tsx

@@ -13,6 +13,7 @@ import {
   X,
 } from "lucide-react";
 import type { ChatItem } from "@/lib/chat/events";
+import { outputTail } from "@/lib/chat/background";
 import { formatElapsed } from "@/lib/chat/elapsed";
 import { cn } from "@/lib/utils";
 import { useNow } from "./useNow";
@@ -22,6 +23,8 @@ type Task = Extract<ChatItem, { kind: "task" }>;
 // Finished tasks stay listed this long, then the chip clears.
 const RECENT_MS = 5 * 60 * 1000;
 const POLL_MS = 2000;
+// Running tasks whose last line of output is followed while the tray is open.
+const TAILED = 5;
 
 function TaskIcon({ task }: { task: Task }) {
   if (task.status === "running")
@@ -49,16 +52,23 @@ function TaskRow({
   task,
   now,
   output,
+  tail,
+  highlight,
   onStop,
   onLoadOutput,
 }: {
   task: Task;
   now: number;
   output: string | null | undefined;
+  // Follows its output for the line under its name.
+  tail: boolean;
+  // Brought here from the call it came from.
+  highlight: boolean;
   onStop: () => void;
   onLoadOutput: (taskId: string) => void;
 }) {
-  const [open, setOpen] = useState(false);
+  const [open, setOpen] = useState(highlight);
+  const rowRef = useRef<HTMLDivElement>(null);
   const running = task.status === "running";
   const { taskId } = task;
   const outputRef = useRef<HTMLPreElement>(null);
@@ -69,18 +79,32 @@ function TaskRow({
     if (el) el.scrollTop = el.scrollHeight;
   }, [output]);
 
-  // While open, keep the output fresh for as long as the task runs.
   useEffect(() => {
-    if (!open) return;
+    if (!highlight) return;
+    setOpen(true);
+    rowRef.current?.scrollIntoView({ block: "nearest", behavior: "smooth" });
+  }, [highlight]);
+
+  // While open (or tailed), keep the output fresh for as long as it runs.
+  useEffect(() => {
+    if (!open && !(tail && running)) return;
     onLoadOutput(taskId);
     if (!running) return;
     const t = setInterval(() => onLoadOutput(taskId), POLL_MS);
     return () => clearInterval(t);
-  }, [open, running, taskId, onLoadOutput]);
+  }, [open, tail, running, taskId, onLoadOutput]);
 
   const took = formatElapsed((task.endedAt ?? now) - task.createdAt);
+  const line =
+    running && !open ? (outputTail(output) ?? task.lastToolName) : null;
   return (
-    <div className="rounded-lg">
+    <div
+      ref={rowRef}
+      className={cn(
+        "rounded-lg transition-colors duration-700",
+        highlight && "bg-foreground/[0.05]"
+      )}
+    >
       <div className="flex min-h-11 items-center gap-2 px-1.5 md:min-h-9">
         <button
           type="button"
@@ -113,6 +137,11 @@ function TaskRow({
           </button>
         )}
       </div>
+      {line && (
+        <p className="text-muted-foreground truncate pr-2 pb-1.5 pl-9 font-mono text-[11px]">
+          {line}
+        </p>
+      )}
       {open && (
         <div className="space-y-1 pb-2 pl-7">
           {task.summary && task.summary !== task.description && (
@@ -143,16 +172,24 @@ function TaskRow({
 export function BackgroundTasks({
   items,
   outputs,
+  reveal,
   onStop,
   onLoadOutput,
 }: {
   items: ChatItem[];
+  // A task to open the tray on, from the call that became it.
+  reveal?: { taskId: string; at: number } | null;
   outputs: Record<string, string | null>;
   onStop: (taskId: string) => void;
   onLoadOutput: (taskId: string) => void;
 }) {
   const [open, setOpen] = useState(false);
-  const tasks = items.filter((i): i is Task => i.kind === "task");
+  const [pulse, setPulse] = useState(false);
+  const [lit, setLit] = useState<string | null>(null);
+  // One still blocking its call isn't in the background yet.
+  const tasks = items.filter(
+    (i): i is Task => i.kind === "task" && i.backgrounded !== false
+  );
   const running = tasks.filter((t) => t.status === "running" && !t.ambient);
   const now = useNow(running.length > 0);
   const shown = tasks
@@ -162,6 +199,29 @@ export function BackgroundTasks({
         Number(b.status === "running") - Number(a.status === "running") ||
         b.createdAt - a.createdAt
     );
+  const failed = shown.filter((t) => t.status === "failed").length;
+
+  // A task arriving gives the chip one soft pulse.
+  const count = running.length;
+  const seen = useRef(count);
+  useEffect(() => {
+    const more = count > seen.current;
+    seen.current = count;
+    if (!more) return;
+    setPulse(true);
+    const t = setTimeout(() => setPulse(false), 700);
+    return () => clearTimeout(t);
+  }, [count]);
+
+  // Asked to show a task: open the tray on it for a moment.
+  useEffect(() => {
+    if (!reveal) return;
+    setOpen(true);
+    setLit(reveal.taskId);
+    const t = setTimeout(() => setLit(null), 1200);
+    return () => clearTimeout(t);
+  }, [reveal]);
+
   if (!shown.length) return null;
 
   return (
@@ -170,24 +230,30 @@ export function BackgroundTasks({
         type="button"
         onClick={() => setOpen(!open)}
         className={cn(
-          "text-muted-foreground hover:text-foreground hover:bg-foreground/[0.05] flex h-9 items-center gap-1.5 rounded-lg px-2 text-xs md:h-7",
-          running.length && "text-primary"
+          "text-muted-foreground hover:text-foreground hover:bg-foreground/[0.05] flex h-9 items-center gap-1.5 rounded-lg px-2 text-xs transition-colors duration-500 md:h-7",
+          running.length && "text-primary",
+          !running.length && failed > 0 && "text-destructive",
+          pulse && "bg-foreground/[0.08]"
         )}
       >
         <Layers className="h-3.5 w-3.5" />
         {running.length
           ? `${running.length} running in background`
-          : `${shown.length} background task${shown.length === 1 ? "" : "s"}`}
+          : failed
+            ? `${failed} failed in background`
+            : `${shown.length} finished in background`}
         <ChevronRight
           className={cn("h-3 w-3 transition-transform", open && "rotate-90")}
         />
       </button>
       {open && (
         <div className="bg-foreground/[0.025] mt-1 max-h-80 overflow-y-auto rounded-xl px-1 py-1">
-          {shown.map((t) => (
+          {shown.map((t, i) => (
             <TaskRow
               key={t.id}
               task={t}
+              tail={i < TAILED}
+              highlight={lit === t.taskId}
               now={now}
               output={outputs[t.taskId]}
               onStop={() => onStop(t.taskId)}

package/components/Chat/ChatPanel.tsx

@@ -42,6 +42,8 @@ import { useFreshStartQuery } from "@/data/fresh-start";
 import { QuoteButton } from "./QuoteButton";
 import { ToolBodies, ToolGroup } from "./Tools";
 import { RowState, RowStore } from "./rowState";
+import { Background, type BackgroundValue } from "./background";
+import { backgroundKey } from "@/lib/chat/background";
 import { FindBar } from "./FindBar";
 import { FIND_EVENT, isFindKey, useFind } from "./useFind";
 import { McpServers } from "./McpServers";
@@ -253,6 +255,9 @@ export function ChatPanel({
     undoPreview,
     clearUndo,
     stopTask,
+    canBackground,
+    backgroundTask,
+    movingToBackground,
     loadTaskOutput,
     taskOutputs,
     queue,
@@ -380,6 +385,54 @@ export function ChatPanel({
     }),
     [toolBodies, requestToolBody, pinToolBody, connected]
   );
+  // The calls that block the turn and can be moved to the background.
+  const [reveal, setReveal] = useState<{ taskId: string; at: number } | null>(
+    null
+  );
+  const foregroundTasks = useMemo(() => {
+    const byTool = new Map<string, Extract<ChatItem, { kind: "task" }>>();
+    const byId = new Map<string, Extract<ChatItem, { kind: "task" }>>();
+    for (const i of tasks)
+      if (i.kind === "task") {
+        byId.set(i.taskId, i);
+        if (i.toolUseId) byTool.set(i.toolUseId, i);
+      }
+    return { byTool, byId };
+  }, [tasks]);
+  const background = useMemo<BackgroundValue>(
+    () => ({
+      supported: canBackground,
+      taskOfTool: (id) => foregroundTasks.byTool.get(id),
+      taskById: (id) => foregroundTasks.byId.get(id),
+      moving: movingToBackground,
+      send: backgroundTask,
+      reveal: (taskId) => setReveal({ taskId, at: Date.now() }),
+    }),
+    [canBackground, foregroundTasks, movingToBackground, backgroundTask]
+  );
+  // Ctrl+B moves every call that blocks the turn, from anywhere in this panel.
+  const canMove = useMemo(
+    () =>
+      canBackground &&
+      [...foregroundTasks.byId.values()].some(
+        (t) => t.status === "running" && t.backgrounded === false
+      ),
+    [canBackground, foregroundTasks]
+  );
+  const moveRef = useRef({ canMove, backgroundTask });
+  useEffect(() => {
+    moveRef.current = { canMove, backgroundTask };
+  });
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (!rootRef.current?.contains(e.target as Node)) return;
+      if (!backgroundKey(e, moveRef.current.canMove)) return;
+      e.preventDefault();
+      moveRef.current.backgroundTask();
+    };
+    window.addEventListener("keydown", onKey, true);
+    return () => window.removeEventListener("keydown", onKey, true);
+  }, []);
   const itemsById = useMemo(
     () => new Map(items.map((i) => [i.id, i])),
     [items]
@@ -482,41 +535,43 @@ export function ChatPanel({
       {orchestratorOf && <OrchestratorBar workspaceId={orchestratorOf} />}
       <div ref={scrollRef} className="relative min-h-0 flex-1">
         <RowState.Provider value={rowState}>
-          <ToolBodies.Provider value={bodies}>
-            <div
-              // A new conversation starts over, scrolled to the end.
-              key={sessionId}
-              ref={listRef}
-              onScroll={onListScroll}
-              onCopy={onCopy}
-              className="h-full overflow-y-auto overscroll-y-contain"
-            >
-              <div className="mx-auto flex w-full max-w-3xl flex-col gap-4 px-4 pt-5 pb-4">
-                {hasMore && (
-                  <div className="text-muted-foreground flex min-h-11 items-center justify-center text-xs">
-                    {loadingOlder ? (
-                      <Loader2 className="h-4 w-4 animate-spin" />
-                    ) : (
-                      <button
-                        type="button"
-                        onClick={loadOlder}
-                        className="hover:text-foreground min-h-11 px-3"
-                      >
-                        Show earlier messages
-                      </button>
-                    )}
-                  </div>
-                )}
-                <SetupCard sessionId={sessionId} />
-                {blocks.length === 0 && !queue.length && (
-                  <p className="text-muted-foreground py-16 text-center text-sm">
-                    Ask anything to start.
-                  </p>
-                )}
+          <Background.Provider value={background}>
+            <ToolBodies.Provider value={bodies}>
+              <div
+                // A new conversation starts over, scrolled to the end.
+                key={sessionId}
+                ref={listRef}
+                onScroll={onListScroll}
+                onCopy={onCopy}
+                className="h-full overflow-y-auto overscroll-y-contain"
+              >
+                <div className="mx-auto flex w-full max-w-3xl flex-col gap-4 px-4 pt-5 pb-4">
+                  {hasMore && (
+                    <div className="text-muted-foreground flex min-h-11 items-center justify-center text-xs">
+                      {loadingOlder ? (
+                        <Loader2 className="h-4 w-4 animate-spin" />
+                      ) : (
+                        <button
+                          type="button"
+                          onClick={loadOlder}
+                          className="hover:text-foreground min-h-11 px-3"
+                        >
+                          Show earlier messages
+                        </button>
+                      )}
+                    </div>
+                  )}
+                  <SetupCard sessionId={sessionId} />
+                  {blocks.length === 0 && !queue.length && (
+                    <p className="text-muted-foreground py-16 text-center text-sm">
+                      Ask anything to start.
+                    </p>
+                  )}
+                </div>
+                <TimelineRows blocks={blocks} actions={actions} />
               </div>
-              <TimelineRows blocks={blocks} actions={actions} />
-            </div>
-          </ToolBodies.Provider>
+            </ToolBodies.Provider>
+          </Background.Provider>
         </RowState.Provider>
         {find.open && (
           <FindBar
@@ -551,6 +606,7 @@ export function ChatPanel({
         />
         <BackgroundTasks
           items={tasks}
+          reveal={reveal}
           outputs={taskOutputs}
           onStop={stopTask}
           onLoadOutput={loadTaskOutput}

package/components/Chat/Subagent.tsx

@@ -4,7 +4,8 @@ import { Bot, ChevronRight } from "lucide-react";
 import type { ToolItem } from "@/lib/chat/group";
 import { cn } from "@/lib/utils";
 import { Markdown } from "./Markdown";
-import { StatusIcon, useToolBody } from "./Tools";
+import { ToolIcon, useToolBody } from "./Tools";
+import { BackgroundButton, BackgroundState } from "./background";
 import { useRowState } from "./rowState";
 
 // Its report, loaded when the card opens if the page left it out.
@@ -23,26 +24,30 @@ export function SubagentCard({ item }: { item: ToolItem }) {
   };
   return (
     <div className="bg-foreground/[0.025] rounded-xl px-2 py-1">
-      <button
-        type="button"
-        onClick={() => setOpen(!open)}
-        className="flex min-h-10 w-full items-center gap-2 px-1.5 text-left text-xs md:min-h-8"
-      >
-        <ChevronRight
-          className={cn(
-            "text-muted-foreground h-3 w-3 shrink-0 transition-transform",
-            open && "rotate-90"
+      <div className="flex items-center gap-1">
+        <button
+          type="button"
+          onClick={() => setOpen(!open)}
+          className="flex min-h-10 min-w-0 flex-1 items-center gap-2 px-1.5 text-left text-xs md:min-h-8"
+        >
+          <ChevronRight
+            className={cn(
+              "text-muted-foreground h-3 w-3 shrink-0 transition-transform",
+              open && "rotate-90"
+            )}
+          />
+          <Bot className="text-primary h-3.5 w-3.5 shrink-0" />
+          <span className="min-w-0 flex-1 truncate">{item.title}</span>
+          {input.subagent_type && (
+            <span className="text-muted-foreground hidden font-mono sm:inline">
+              {input.subagent_type}
+            </span>
           )}
-        />
-        <Bot className="text-primary h-3.5 w-3.5 shrink-0" />
-        <span className="min-w-0 flex-1 truncate">{item.title}</span>
-        {input.subagent_type && (
-          <span className="text-muted-foreground hidden font-mono sm:inline">
-            {input.subagent_type}
-          </span>
-        )}
-        <StatusIcon status={item.status} />
-      </button>
+          {item.backgroundTaskId ? <BackgroundState tool={item} /> : null}
+          <ToolIcon tool={item} />
+        </button>
+        <BackgroundButton tool={item} />
+      </div>
       {open && (
         <div className="space-y-3 px-1.5 pt-1 pb-2 pl-7">
           {input.prompt && (

package/components/Chat/Tools.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { createContext, useContext, useEffect } from "react";
-import { Check, ChevronRight, Loader2, Square, X } from "lucide-react";
+import { Check, ChevronRight, Layers, Loader2, Square, X } from "lucide-react";
 import type { FileDiff, ToolBody } from "@/lib/chat/events";
 import type { ToolItem } from "@/lib/chat/group";
 import { lineDiff, shortPath, type DiffLine } from "@/lib/chat/diff";
@@ -9,6 +9,7 @@ import { needsBody } from "@/lib/chat/bodyCache";
 import { cn } from "@/lib/utils";
 import { formatElapsed } from "@/lib/chat/elapsed";
 import { Highlighted } from "./Code";
+import { BackgroundButton, BackgroundState, useBackground } from "./background";
 import { useNow } from "./useNow";
 import { useRowState } from "./rowState";
 
@@ -48,6 +49,18 @@ export function StatusIcon({ status }: { status: ToolItem["status"] }) {
   return <Check className="text-muted-foreground/70 h-3.5 w-3.5 shrink-0" />;
 }
 
+// The status of a call; one moved to the background and still running there
+// shows as handed off instead of done.
+export function ToolIcon({ tool }: { tool: ToolItem }) {
+  const bg = useBackground();
+  const task = tool.backgroundTaskId
+    ? bg.taskById(tool.backgroundTaskId)
+    : undefined;
+  if (tool.backgroundTaskId && (!task || task.status === "running"))
+    return <Layers className="text-muted-foreground h-3.5 w-3.5 shrink-0" />;
+  return <StatusIcon status={tool.status} />;
+}
+
 const TONE: Record<DiffLine["op"], string> = {
   " ": "text-muted-foreground",
   "-": "bg-red-500/10 text-red-700 dark:text-red-300",
@@ -139,17 +152,24 @@ function ToolRow({ tool }: { tool: ToolItem }) {
   );
   return (
     <div data-item={tool.id}>
-      <button
-        type="button"
-        onClick={() => setOpen(!open)}
-        className="hover:bg-foreground/[0.04] flex min-h-9 w-full items-center gap-2 rounded-lg px-1.5 text-left md:min-h-7"
-      >
-        <StatusIcon status={tool.status} />
-        <span className="min-w-0 flex-1 truncate font-mono text-xs">
-          {tool.title}
-        </span>
-        <Elapsed tool={tool} />
-      </button>
+      <div className="hover:bg-foreground/[0.04] flex items-center gap-1 rounded-lg pr-1">
+        <button
+          type="button"
+          onClick={() => setOpen(!open)}
+          className="flex min-h-9 min-w-0 flex-1 items-center gap-2 px-1.5 text-left md:min-h-7"
+        >
+          <ToolIcon tool={tool} />
+          <span className="min-w-0 flex-1 truncate font-mono text-xs">
+            {tool.title}
+          </span>
+          {tool.backgroundTaskId ? (
+            <BackgroundState tool={tool} />
+          ) : (
+            <Elapsed tool={tool} />
+          )}
+        </button>
+        <BackgroundButton tool={tool} />
+      </div>
       {open && <ToolDetail tool={tool} />}
     </div>
   );
@@ -161,39 +181,50 @@ export function ToolGroup({ tools }: { tools: ToolItem[] }) {
   const failed = tools.filter((t) => t.status === "error").length;
   const stopped = tools.filter((t) => t.status === "stopped").length;
   const edits = tools.filter((t) => t.diff || t.hasDiff).length;
+  const moved = tools.filter((t) => t.backgroundTaskId).length;
   const [open, setOpen] = useRowState(`steps:${tools[0].id}`, false);
   const latest =
     tools.findLast((t) => t.status === "running") ?? tools[tools.length - 1];
   return (
     <div className="bg-foreground/[0.025] rounded-xl px-2 py-1">
-      <button
-        type="button"
-        onClick={() => setOpen(!open)}
-        className="text-muted-foreground hover:text-foreground flex min-h-10 w-full items-center gap-2 px-1.5 text-left text-xs md:min-h-8"
-      >
-        <ChevronRight
-          className={cn(
-            "h-3 w-3 shrink-0 transition-transform",
-            open && "rotate-90"
+      <div className="flex items-center gap-1">
+        <button
+          type="button"
+          onClick={() => setOpen(!open)}
+          className="text-muted-foreground hover:text-foreground flex min-h-10 min-w-0 flex-1 items-center gap-2 px-1.5 text-left text-xs md:min-h-8"
+        >
+          <ChevronRight
+            className={cn(
+              "h-3 w-3 shrink-0 transition-transform",
+              open && "rotate-90"
+            )}
+          />
+          {running ? (
+            <Loader2 className="text-primary h-3.5 w-3.5 shrink-0 animate-spin" />
+          ) : null}
+          <span className="min-w-0 flex-1 truncate">
+            {running
+              ? latest.title
+              : `${tools.length} step${tools.length === 1 ? "" : "s"}`}
+            {!running &&
+              edits > 0 &&
+              ` · ${edits} edit${edits === 1 ? "" : "s"}`}
+          </span>
+          {running && <Elapsed tool={latest} />}
+          {failed > 0 && (
+            <span className="text-destructive">{failed} failed</span>
           )}
-        />
-        {running ? (
-          <Loader2 className="text-primary h-3.5 w-3.5 shrink-0 animate-spin" />
-        ) : null}
-        <span className="min-w-0 flex-1 truncate">
-          {running
-            ? latest.title
-            : `${tools.length} step${tools.length === 1 ? "" : "s"}`}
-          {!running && edits > 0 && ` · ${edits} edit${edits === 1 ? "" : "s"}`}
-        </span>
-        {running && <Elapsed tool={latest} />}
-        {failed > 0 && (
-          <span className="text-destructive">{failed} failed</span>
-        )}
-        {stopped > 0 && failed === 0 && (
-          <span className="text-muted-foreground/70">stopped</span>
-        )}
-      </button>
+          {stopped > 0 && failed === 0 && (
+            <span className="text-muted-foreground/70">stopped</span>
+          )}
+          {!running && moved > 0 && (
+            <span className="text-muted-foreground/70">
+              {moved} in background
+            </span>
+          )}
+        </button>
+        {running && <BackgroundButton tool={latest} />}
+      </div>
       {open && (
         <div className="pb-1">
           {tools.map((t) => (