@saadnvd1/agent-os 0.3.519 → 0.3.521

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                                 |
@@ -539,6 +550,21 @@ and **Usage → Compare** splits cost into planned and not. When the plan step
 finishes, the orchestrator gets one event with the plan file's path and a
 3-5 line summary; the handoff to implementation stays automatic.
 
+**Plan only.** A task started with `plan_only` (`start_task`'s `plan_only`,
+`aos task --plan-only`, or `plan_only: true` on `POST /api/tasks`) writes its
+plan on the planning model and then stops: no model switch, no implement
+prompt, even when one model does every role. It sits in a **Plan ready**
+state (`plan_phase` `awaiting`, stored on the task, so it survives a restart)
+that isn't blocked, doesn't count as needing you, and holds no agent process
+(its worker is released; the conversation resumes on approval). The
+orchestrator gets one event with the plan's path, a summary and that the task
+is waiting. **Approve** on the task row (plan viewable there), `POST
+/api/tasks/<id>/approve-plan`, or the orchestrator's `approve_plan(task,
+message?)` continues it on the implementation model, once; a message amends
+the plan and is recorded on the task's brief as a scope change, so the review
+judges against it. Reject with **Drop**. A chat task on this machine only; it
+can't move until approved.
+
 **Per task.** The task draft has a **Model** chip ("Routed by role", or one
 model); `POST /api/tasks` and the orchestrator's `start_task` take `model`, as
 `"provider/model"` for the task's own roles or a map such as

package/app/api/bus/spawn/route.ts

@@ -29,12 +29,15 @@ export async function POST(request: NextRequest) {
       on,
       after,
       view,
+      planOnly,
       from,
     } = await request.json();
     const startedBy = orchestratorFrom(from);
     const given = typeof name === "string" ? name : undefined;
     if (after !== undefined && mode !== "task")
       throw new Error("--after works for tasks only");
+    if (planOnly !== undefined && mode !== "task")
+      throw new Error("--plan-only works for tasks only");
     if (mode === "task") {
       const task = {
         projectId: findProject(String(project ?? "")).id,
@@ -43,6 +46,7 @@ export async function POST(request: NextRequest) {
         model,
         hostId: on ? hostIdNamed(String(on)) : undefined,
         view: startView(view),
+        planOnly: planOnly === true ? true : undefined,
         startedBy,
       };
       const out = await startOrQueue(

package/app/api/tasks/[id]/approve-plan/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { approvePlanNow } from "@/lib/models/plan-step";
+
+// Approves a plan-only task's plan: it continues on the implementation
+// model. An optional message amends the plan (recorded as a scope change).
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const body = await request.json().catch(() => ({}));
+    const message =
+      typeof body?.message === "string" && body.message.trim()
+        ? body.message.trim().slice(0, 8000)
+        : undefined;
+    const out = await approvePlanNow((await params).id, message);
+    return NextResponse.json({ success: true, model: out.ref });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return NextResponse.json({ error: message }, { status: 409 });
+  }
+}

package/app/api/tasks/route.ts

@@ -36,6 +36,7 @@ export async function POST(request: NextRequest) {
       view,
       plan,
       plan_reason,
+      plan_only,
     } = await request.json();
     if (id !== undefined && !isSessionId(id)) throw new Error("Bad task id");
     const pid =
@@ -48,6 +49,7 @@ export async function POST(request: NextRequest) {
       // Checked now, so a queued task can't fail on it later.
       model: parseOverride(model) ?? undefined,
       plan: typeof plan === "boolean" ? plan : undefined,
+      planOnly: plan_only === true ? true : undefined,
       planReason:
         typeof plan_reason === "string" && plan_reason.trim()
           ? plan_reason.trim().slice(0, 200)

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/Projects/AddProject/AddProjectDialog.tsx

@@ -29,8 +29,8 @@ export function AddProjectDialog() {
   const { open } = useSnapshot(addProjectUi);
   const hostNames = useHostNames();
   const done = (projectId: string) => {
-    addProjectActions.close();
-    newDraft({ kind: "project", projectId });
+    if (!addProjectActions.finish(projectId))
+      newDraft({ kind: "project", projectId });
   };
 
   return (

package/components/Settings/SettingsDialog.tsx

@@ -11,6 +11,7 @@ import {
   Cpu,
   GitMerge,
   LayoutGrid,
+  ListChecks,
   Smartphone,
   X,
   type LucideIcon,
@@ -34,6 +35,7 @@ import { SETTINGS_SECTIONS, type SettingsSection } from "@/lib/settings-url";
 import { cn } from "@/lib/utils";
 import { schedulesUiActions } from "@/stores/schedulesUi";
 import { settingsUi, settingsUiActions } from "@/stores/settingsUi";
+import { SetupSection } from "./SetupSection";
 import {
   NotificationsSection,
   type BrowserNotifications,
@@ -78,6 +80,11 @@ export const SECTION_INFO: Record<
     hint: "Where sessions spent tokens and repeated work",
     icon: ClipboardList,
   },
+  setup: {
+    label: "Setup",
+    hint: "Agents on this machine, first-run setup",
+    icon: ListChecks,
+  },
 };
 
 function SectionBody({
@@ -102,6 +109,8 @@ function SectionBody({
       return <SchedulesPanel />;
     case "audits":
       return <AuditsPanel />;
+    case "setup":
+      return <SetupSection />;
   }
 }
 

package/components/Settings/SetupSection.tsx

@@ -0,0 +1,37 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import { AgentList } from "@/components/Welcome/AgentList";
+import { settingsUiActions } from "@/stores/settingsUi";
+import { welcomeUiActions } from "@/stores/welcomeUi";
+
+// What this machine has for running agents, and the first-run setup again.
+export function SetupSection() {
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="bg-muted/40 flex items-center gap-3 rounded-lg px-3 py-2.5">
+        <div className="min-w-0 flex-1">
+          <p className="text-sm font-medium">First-run setup</p>
+          <p className="text-muted-foreground text-xs">
+            Agents, your first project, and a first session.
+          </p>
+        </div>
+        <Button
+          size="sm"
+          variant="outline"
+          className="min-h-11 sm:min-h-8"
+          onClick={() => {
+            settingsUiActions.close();
+            welcomeUiActions.open("agents");
+          }}
+        >
+          Run setup again
+        </Button>
+      </div>
+      <div className="flex flex-col gap-2">
+        <h3 className="text-sm font-medium">Agents on this machine</h3>
+        <AgentList />
+      </div>
+    </div>
+  );
+}

package/components/Tasks/TaskRow.tsx

@@ -10,7 +10,13 @@ import {
 import { Button } from "@/components/ui/button";
 import type { TaskView } from "@/lib/tasks";
 import { isFinished } from "@/lib/tasks/state";
-import { useArmTask, useDropTask, useSignOffTask } from "@/data/tasks";
+import {
+  useApprovePlan,
+  useArmTask,
+  useDropTask,
+  useSignOffTask,
+} from "@/data/tasks";
+import { Markdown } from "@/components/Chat/Markdown";
 import { tmuxAttachActions } from "@/stores/tmuxAttach";
 import { tasksUiActions } from "@/stores/tasksUi";
 import { cn } from "@/lib/utils";
@@ -23,6 +29,8 @@ export function TaskRow({ task }: { task: TaskView }) {
   const signOff = useSignOffTask();
   const drop = useDropTask();
   const arm = useArmTask();
+  const approve = useApprovePlan();
+  const [showPlan, setShowPlan] = useState(false);
   const [confirmDrop, setConfirmDrop] = useState(false);
   const [moveError, setMoveError] = useState<string | null>(null);
   const live = !isFinished(task.state);
@@ -30,6 +38,7 @@ export function TaskRow({ task }: { task: TaskView }) {
     signOff.error?.message ||
     drop.error?.message ||
     arm.error?.message ||
+    approve.error?.message ||
     moveError ||
     task.hostError;
   const settingUp = live && task.setup?.status === "running";
@@ -148,6 +157,26 @@ export function TaskRow({ task }: { task: TaskView }) {
               {task.armed ? "Armed" : "Arm merge"}
             </Button>
           )}
+          {task.state === "plan-ready" && (
+            <>
+              <Button
+                size="sm"
+                variant="outline"
+                aria-expanded={showPlan}
+                onClick={() => setShowPlan((v) => !v)}
+              >
+                {showPlan ? "Hide plan" : "View plan"}
+              </Button>
+              <Button
+                size="sm"
+                className="h-11 md:h-8"
+                disabled={approve.isPending}
+                onClick={() => approve.mutate({ id: task.id })}
+              >
+                {approve.isPending ? "Approving..." : "Approve"}
+              </Button>
+            </>
+          )}
           {task.state === "review" && (
             <Button
               size="sm"
@@ -159,6 +188,22 @@ export function TaskRow({ task }: { task: TaskView }) {
           )}
         </div>
       )}
+      {live && task.state === "plan-ready" && showPlan && (
+        <div className="bg-foreground/[0.04] max-h-80 overflow-y-auto rounded-lg p-3 text-sm">
+          {task.plan?.text ? (
+            <Markdown text={task.plan.text} />
+          ) : (
+            <p className="text-muted-foreground text-xs">
+              No plan file was written.
+            </p>
+          )}
+          {task.plan?.truncated && (
+            <p className="text-muted-foreground mt-2 font-mono text-[11px]">
+              Shortened; the whole plan is {task.plan.path} in the worktree.
+            </p>
+          )}
+        </div>
+      )}
       {error && <p className="text-destructive text-xs">{error}</p>}
     </div>
   );

package/components/Tasks/task-state-labels.ts

@@ -8,6 +8,7 @@ export const TASK_STATE: Record<TaskState, { label: string; tone: string }> = {
     tone: "text-amber-600 dark:text-amber-400",
   },
   blocked: { label: "Blocked", tone: "text-amber-600 dark:text-amber-400" },
+  "plan-ready": { label: "Plan ready", tone: "text-primary" },
   review: { label: "Ready for review", tone: "text-primary" },
   "checks-failing": { label: "Checks failing", tone: "text-destructive" },
   exited: { label: "Agent exited", tone: "text-amber-600 dark:text-amber-400" },

package/components/Welcome/AgentList.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { RefreshCw } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { useAgentStatusQuery, useRecheckAgents } from "@/data/agents";
+import { FEATURED_AGENTS } from "@/lib/agents/setup-commands";
+import { getAllProviderDefinitions } from "@/lib/providers/registry";
+import { AgentRow, type AgentRun } from "./AgentRow";
+import { SetupTerminal } from "./SetupTerminal";
+
+/**
+ * Every agent CLI on this machine with what it needs, and an embedded
+ * terminal to install or sign one in. Checks again when it opens and when a
+ * terminal is closed, never on a timer.
+ */
+export function AgentList() {
+  const { data: agents } = useAgentStatusQuery();
+  const recheck = useRecheckAgents();
+  const [run, setRun] = useState<(AgentRun & { key: number }) | null>(null);
+  const [all, setAll] = useState(false);
+  const { mutate } = recheck;
+
+  useEffect(() => mutate(), [mutate]);
+
+  const providers = getAllProviderDefinitions().filter((p) => p.cli);
+  const shown = providers.filter((p) => all || FEATURED_AGENTS.includes(p.id));
+  const hidden = providers.length - shown.length;
+
+  return (
+    <div className="flex flex-col gap-3">
+      <ul className="flex flex-col gap-2">
+        {shown.map((p) => (
+          <AgentRow
+            key={p.id}
+            provider={p}
+            probe={agents?.[p.id]}
+            onRun={(r) => setRun({ ...r, key: Date.now() })}
+          />
+        ))}
+      </ul>
+      {run && (
+        <SetupTerminal
+          key={run.key}
+          title={run.title}
+          command={run.command}
+          onDone={() => {
+            setRun(null);
+            mutate();
+          }}
+        />
+      )}
+      <div className="flex items-center justify-between gap-2">
+        {hidden > 0 ? (
+          <Button size="sm" variant="ghost" onClick={() => setAll(true)}>
+            Show {hidden} more
+          </Button>
+        ) : (
+          <span />
+        )}
+        <Button
+          size="sm"
+          variant="ghost"
+          disabled={recheck.isPending}
+          onClick={() => mutate()}
+        >
+          <RefreshCw className={recheck.isPending ? "animate-spin" : ""} />
+          Check again
+        </Button>
+      </div>
+    </div>
+  );
+}

package/components/Welcome/AgentRow.tsx

@@ -0,0 +1,102 @@
+"use client";
+
+import { Check, Download, LogIn } from "lucide-react";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import type { AgentProbe } from "@/lib/agents/probe";
+import { agentState, SETUP_COMMANDS } from "@/lib/agents/setup-commands";
+import type { ProviderDefinition } from "@/lib/providers/registry";
+
+const LABEL = {
+  missing: "Not installed",
+  "needs-login": "Needs sign-in",
+  ready: "Ready",
+  installed: "Installed",
+} as const;
+
+export type AgentRun = { title: string; command: string };
+
+/** One agent CLI: its state, and the install or sign-in it needs. */
+export function AgentRow({
+  provider,
+  probe,
+  onRun,
+}: {
+  provider: ProviderDefinition;
+  probe: AgentProbe | undefined;
+  onRun: (run: AgentRun) => void;
+}) {
+  const state = probe ? agentState(probe) : null;
+  const commands = SETUP_COMMANDS[provider.id];
+  return (
+    <li className="bg-muted/40 flex min-h-11 items-center gap-3 rounded-lg px-3 py-2">
+      <div className="min-w-0 flex-1">
+        <p className="truncate text-sm font-medium">{provider.name}</p>
+        <p className="text-muted-foreground truncate text-xs">
+          {probe?.version
+            ? `v${probe.version}`
+            : (probe?.hint ?? provider.description)}
+        </p>
+      </div>
+      {!state && <Badge variant="outline">Checking</Badge>}
+      {state === "ready" && (
+        <Badge variant="success">
+          <Check className="mr-1 size-3" />
+          {LABEL.ready}
+        </Badge>
+      )}
+      {state === "installed" && <Badge variant="outline">{LABEL[state]}</Badge>}
+      {state === "needs-login" && (
+        <>
+          <Badge variant="secondary">{LABEL[state]}</Badge>
+          {commands?.signIn && (
+            <Button
+              size="sm"
+              variant="outline"
+              className="min-h-11 sm:min-h-8"
+              onClick={() =>
+                onRun({
+                  title: `Sign in to ${provider.name}`,
+                  command: commands.signIn!,
+                })
+              }
+            >
+              <LogIn />
+              Sign in
+            </Button>
+          )}
+        </>
+      )}
+      {state === "missing" &&
+        (commands?.install ? (
+          <Button
+            size="sm"
+            variant="outline"
+            className="min-h-11 sm:min-h-8"
+            onClick={() =>
+              onRun({
+                title: `Install ${provider.name}`,
+                command: commands.install!,
+              })
+            }
+          >
+            <Download />
+            Install
+          </Button>
+        ) : commands?.docs ? (
+          <Button
+            size="sm"
+            variant="outline"
+            className="min-h-11 sm:min-h-8"
+            asChild
+          >
+            <a href={commands.docs} target="_blank" rel="noreferrer">
+              How to install
+            </a>
+          </Button>
+        ) : (
+          <Badge variant="outline">{LABEL.missing}</Badge>
+        ))}
+    </li>
+  );
+}

package/components/Welcome/ProjectStep.tsx

@@ -0,0 +1,100 @@
+"use client";
+
+import { FolderGit2, FolderOpen, FolderPlus, Check } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { useProjectsQuery } from "@/data/projects/queries";
+import { cn } from "@/lib/utils";
+import { addProjectActions, type AddProjectKind } from "@/stores/addProject";
+import { welcomeUi, welcomeUiActions } from "@/stores/welcomeUi";
+import { useSnapshot } from "valtio";
+
+const WAYS: {
+  kind: AddProjectKind;
+  title: string;
+  hint: string;
+  icon: typeof FolderOpen;
+}[] = [
+  {
+    kind: "folder",
+    title: "Open a folder",
+    hint: "A project already on this machine",
+    icon: FolderOpen,
+  },
+  {
+    kind: "clone",
+    title: "Clone a repo",
+    hint: "From a Git URL",
+    icon: FolderGit2,
+  },
+  {
+    kind: "name",
+    title: "Start an empty project",
+    hint: "A new folder with a name",
+    icon: FolderPlus,
+  },
+];
+
+/** Add the project the first session will open in, or pick one already there. */
+export function ProjectStep() {
+  const { projectId } = useSnapshot(welcomeUi);
+  const { data: projects = [] } = useProjectsQuery();
+  const own = projects.filter((p) => !p.is_uncategorized);
+
+  const add = (kind: AddProjectKind) =>
+    addProjectActions.show(kind, "local", (id) => {
+      welcomeUiActions.setProject(id);
+      welcomeUiActions.go("finish");
+    });
+
+  return (
+    <div className="flex flex-col gap-3">
+      {own.length > 0 && (
+        <ul className="flex flex-col gap-2">
+          {own.map((p) => (
+            <li key={p.id}>
+              <button
+                type="button"
+                onClick={() => {
+                  welcomeUiActions.setProject(p.id);
+                  welcomeUiActions.go("finish");
+                }}
+                className={cn(
+                  "bg-muted/40 hover:bg-accent flex min-h-11 w-full items-center gap-3 rounded-lg px-3 py-2 text-left",
+                  projectId === p.id && "ring-primary/40 ring-2"
+                )}
+              >
+                <span className="min-w-0 flex-1">
+                  <span className="block truncate text-sm font-medium">
+                    {p.name}
+                  </span>
+                  <span className="text-muted-foreground block truncate text-xs">
+                    {p.working_directory}
+                  </span>
+                </span>
+                {projectId === p.id && <Check className="size-4" />}
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+      <div className="flex flex-col gap-2">
+        {WAYS.map((w) => (
+          <Button
+            key={w.kind}
+            variant="outline"
+            className="h-auto min-h-11 justify-start gap-3 px-3 py-2.5 text-left"
+            onClick={() => add(w.kind)}
+          >
+            <w.icon />
+            <span className="min-w-0">
+              <span className="block text-sm font-medium">{w.title}</span>
+              <span className="text-muted-foreground block text-xs font-normal">
+                {w.hint}
+              </span>
+            </span>
+          </Button>
+        ))}
+      </div>
+    </div>
+  );
+}

package/components/Welcome/SetupTerminal.tsx

@@ -0,0 +1,64 @@
+"use client";
+
+import { useCallback, useEffect, useRef } from "react";
+import dynamic from "next/dynamic";
+import { Button } from "@/components/ui/button";
+import type { TerminalHandle } from "@/components/Terminal";
+
+const Terminal = dynamic(
+  () => import("@/components/Terminal").then((m) => m.Terminal),
+  { ssr: false }
+);
+
+/**
+ * A terminal on this machine with one setup command typed at the prompt, for
+ * the user to read and run with Enter. It goes into their own shell over the
+ * existing terminal socket; the server runs nothing.
+ */
+export function SetupTerminal({
+  title,
+  command,
+  onDone,
+}: {
+  title: string;
+  command: string;
+  onDone: () => void;
+}) {
+  const ref = useRef<TerminalHandle | null>(null);
+  const typed = useRef(false);
+  const box = useRef<HTMLDivElement>(null);
+
+  // On a phone it opens below the list, out of sight.
+  useEffect(() => {
+    box.current?.scrollIntoView?.({ block: "nearest", behavior: "smooth" });
+  }, []);
+
+  const connected = useCallback(() => {
+    if (typed.current) return;
+    typed.current = true;
+    setTimeout(() => {
+      ref.current?.sendInput("\x15");
+      // Typed, not run: the user reads it and presses Enter.
+      setTimeout(() => ref.current?.sendInput(command), 50);
+    }, 100);
+  }, [command]);
+
+  return (
+    <div
+      ref={box}
+      className="bg-muted/30 hairline flex flex-col overflow-hidden rounded-lg"
+    >
+      <div className="flex items-center justify-between gap-2 px-3 py-1.5">
+        <span className="text-muted-foreground truncate text-xs">
+          {title}. Press Enter to run it.
+        </span>
+        <Button size="sm" onClick={onDone}>
+          Done, check again
+        </Button>
+      </div>
+      <div className="h-64 min-h-0">
+        <Terminal ref={ref} onConnected={connected} />
+      </div>
+    </div>
+  );
+}