@saadnvd1/agent-os 0.3.723 → 0.3.728

package/README.md

@@ -19,6 +19,7 @@ and check on all of it from your phone.
 - **Other machines in the same list.** Link another machine that runs AgentOS and start or move work there. [More](docs/reference/machines.md)
 - **Built for your phone.** The whole app works on a phone; pair it with a QR code. [More](docs/guides/phone.md)
 - **Phone to orchestrator.** A paired phone can send a shake report or a shared page or file to a workspace's orchestrator (`POST /api/orchestrators/:workspaceId/intake`, saved under `intake/` beside the database, shared content marked untrusted), and fetch names to improve dictation (`GET /api/voice/vocab?workspace=`). [More](docs/guides/phone.md)
+- **An analyst beside your coding agent.** Pair a chat with a second one that reviews each turn, explains it in plain English, flags issues and drafts the next prompt, which you send, edit or dismiss. Side by side on a desktop, a switch on a phone. [More](docs/decisions/2026-10-21-analyst-sessions.md)
 - **Agents that talk to each other.** Sessions message each other with `aos`, and you see every conversation in Messages. [More](docs/guides/agent-network.md)
 - **Chat or terminal, same conversation.** Streaming replies, steps and diffs, plan mode, slash commands, `@file`, undo. [More](docs/guides/chat.md)
 - **Bookmarks.** Star any message, tool call or turn, then find it again from the chat or across every chat, with a search. [More](docs/guides/chat.md)

package/app/api/loops/route.ts

@@ -0,0 +1,17 @@
+import { NextResponse } from "next/server";
+import { db } from "@/lib/db";
+import { loopSummary } from "@/lib/loops";
+
+// GET /api/loops - the pill for every task that has had a loop in the last
+// day, by task id.
+export async function GET() {
+  const since = Date.now() - 24 * 60 * 60 * 1000;
+  const ids = db
+    .prepare(
+      `SELECT DISTINCT session_id FROM task_loops WHERE state = 'running' OR COALESCE(ended_at, 0) >= ?`
+    )
+    .all(since) as { session_id: string }[];
+  const loops: Record<string, ReturnType<typeof loopSummary>> = {};
+  for (const { session_id } of ids) loops[session_id] = loopSummary(session_id);
+  return NextResponse.json({ loops });
+}

package/app/api/tasks/[id]/loop/cycles/[n]/log/route.ts

@@ -0,0 +1,29 @@
+import { readFile } from "fs/promises";
+import { NextRequest } from "next/server";
+import { loopLogPath } from "@/lib/loops/gatherEvidence";
+import { latestLoopFor } from "@/lib/loops/store";
+import { loopRoute } from "@/lib/loops/route";
+import { LoopError } from "@/lib/loops/types";
+import { redact } from "@/lib/models/secrets";
+
+const MAX = 64 * 1024;
+
+// GET /api/tasks/:id/loop/cycles/:n/log - the tail of that cycle's checks
+// output, redacted and capped.
+export async function GET(
+  request: NextRequest,
+  ctx: { params: Promise<{ id: string; n: string }> }
+) {
+  const n = Number((await ctx.params).n);
+  return loopRoute(request, ctx, {}, async (task) => {
+    if (!latestLoopFor(task.id) || !Number.isInteger(n) || n < 1)
+      throw new LoopError("No such cycle", 404);
+    let text = "";
+    try {
+      text = await readFile(loopLogPath(task.id, n), "utf8");
+    } catch {
+      throw new LoopError("No log for that cycle", 404);
+    }
+    return { log: redact(text.length > MAX ? text.slice(-MAX) : text) };
+  });
+}

package/app/api/tasks/[id]/loop/draft-criteria/route.ts

@@ -0,0 +1,17 @@
+import { NextRequest } from "next/server";
+import { draftCriteria } from "@/lib/loops";
+import { loopRoute } from "@/lib/loops/route";
+import { LoopError } from "@/lib/loops/types";
+
+// POST /api/tasks/:id/loop/draft-criteria - a drafted checklist from the
+// card or the task's text; nothing is saved.
+export async function POST(
+  request: NextRequest,
+  ctx: { params: Promise<{ id: string }> }
+) {
+  return loopRoute(request, ctx, {}, async (task) => {
+    if (!task.worktree_path)
+      throw new LoopError("The task has no worktree", 409);
+    return { criteria: await draftCriteria(task, task.worktree_path) };
+  });
+}

package/app/api/tasks/[id]/loop/next/route.ts

@@ -0,0 +1,25 @@
+import { NextRequest } from "next/server";
+import { z } from "zod";
+import { actOnNext } from "@/lib/loops";
+import { loopRoute } from "@/lib/loops/route";
+
+const schema = z.object({
+  action: z.enum(["send", "hold", "skip"]),
+  instruction: z.string().max(8000).optional(),
+});
+
+// POST /api/tasks/:id/loop/next - what to do with the instruction in its
+// countdown: send it (edited or not), hold the countdown, or skip the cycle.
+export async function POST(
+  request: NextRequest,
+  ctx: { params: Promise<{ id: string }> }
+) {
+  return loopRoute(request, ctx, { schema }, async (task, body) => ({
+    view: await actOnNext(
+      task.id,
+      body.action === "send"
+        ? { action: "send", instruction: body.instruction }
+        : { action: body.action }
+    ),
+  }));
+}

package/app/api/tasks/[id]/loop/route.ts

@@ -0,0 +1,72 @@
+import { NextRequest } from "next/server";
+import { z } from "zod";
+import { editLoop, loopView, startLoop } from "@/lib/loops";
+import { criterionSchema, limitsSchema, loopRoute } from "@/lib/loops/route";
+
+type Ctx = { params: Promise<{ id: string }> };
+
+// GET /api/tasks/:id/loop - the loop, its checklist and its newest cycles;
+// ?before=<n> pages back.
+export async function GET(request: NextRequest, ctx: Ctx) {
+  const before = Number(request.nextUrl.searchParams.get("before"));
+  return loopRoute(request, ctx, {}, (task) => ({
+    view: loopView(task.id, undefined, {
+      before: Number.isFinite(before) && before > 0 ? before : undefined,
+    }),
+  }));
+}
+
+const startSchema = z.object({
+  criteria: z.array(criterionSchema).max(60),
+  limits: limitsSchema.optional(),
+});
+
+// POST /api/tasks/:id/loop - start a loop with its criteria and limits.
+export async function POST(request: NextRequest, ctx: Ctx) {
+  return loopRoute(
+    request,
+    ctx,
+    { schema: startSchema },
+    async (task, body) => ({
+      view: await startLoop(task.id, body),
+    })
+  );
+}
+
+const editSchema = z.object({
+  limits: limitsSchema.optional(),
+  extend: z
+    .object({
+      cycles: z.number().optional(),
+      costUsd: z.number().optional(),
+      minutes: z.number().optional(),
+    })
+    .optional(),
+  addCriteria: z.array(criterionSchema).optional(),
+  editCriteria: z
+    .array(z.object({ id: z.number(), text: z.string() }))
+    .optional(),
+  removeCriteria: z.array(z.number()).optional(),
+  waive: z.array(z.number()).optional(),
+});
+
+// PATCH /api/tasks/:id/loop - limits, an extension, or the checklist.
+// Raising the spend and waiving a criterion need "Can approve".
+export async function PATCH(request: NextRequest, ctx: Ctx) {
+  return loopRoute(
+    request,
+    ctx,
+    {
+      schema: editSchema,
+      approver: (b) =>
+        !!(
+          b.extend ||
+          b.waive?.length ||
+          (b.limits && b.limits.maxCostUsd !== undefined)
+        ),
+    },
+    (task, body, device) => ({
+      view: editLoop(task.id, body, device ? "a device" : "you"),
+    })
+  );
+}

package/app/api/tasks/[id]/loop/run/route.ts

@@ -0,0 +1,12 @@
+import { NextRequest } from "next/server";
+import { runNow } from "@/lib/loops";
+import { loopRoute } from "@/lib/loops/route";
+
+// POST /api/tasks/:id/loop/run - a cycle at the next tick; resumes a loop
+// that stopped for a reason other than done.
+export async function POST(
+  request: NextRequest,
+  ctx: { params: Promise<{ id: string }> }
+) {
+  return loopRoute(request, ctx, {}, (task) => ({ view: runNow(task.id) }));
+}

package/app/api/tasks/[id]/loop/stop/route.ts

@@ -0,0 +1,12 @@
+import { NextRequest } from "next/server";
+import { stopByUser } from "@/lib/loops";
+import { loopRoute } from "@/lib/loops/route";
+
+// POST /api/tasks/:id/loop/stop - end the loop; the coder's turn, if one
+// is running, is left alone.
+export async function POST(
+  request: NextRequest,
+  ctx: { params: Promise<{ id: string }> }
+) {
+  return loopRoute(request, ctx, {}, (task) => ({ view: stopByUser(task.id) }));
+}

package/app/api/tasks/[id]/mode/route.ts

@@ -0,0 +1,29 @@
+import { NextRequest, NextResponse } from "next/server";
+import { refuse } from "@/lib/tasks/contract/authorize";
+import { modeOf, setTaskMode } from "@/lib/reports/mode";
+import { isMode } from "@/lib/reports/types";
+
+type Ctx = { params: Promise<{ id: string }> };
+
+// GET /api/tasks/:id/mode - the operating mode in force and where it comes from.
+export async function GET(request: NextRequest, { params }: Ctx) {
+  const { id } = await params;
+  const refused = refuse(request, id, "open");
+  if (refused) return refused;
+  return NextResponse.json(modeOf(id));
+}
+
+// PUT /api/tasks/:id/mode {mode} - this task's override; null follows its workspace.
+export async function PUT(request: NextRequest, { params }: Ctx) {
+  const { id } = await params;
+  const refused = refuse(request, id, "plan");
+  if (refused) return refused;
+  const { mode } = await request.json().catch(() => ({}));
+  if (mode !== null && !isMode(mode))
+    return NextResponse.json(
+      { error: "mode is manual, assisted, autonomous or null" },
+      { status: 400 }
+    );
+  setTaskMode(id, mode);
+  return NextResponse.json(modeOf(id));
+}

package/app/api/tasks/[id]/report/draft/route.ts

@@ -0,0 +1,54 @@
+import { NextRequest, NextResponse } from "next/server";
+import { refuse } from "@/lib/tasks/contract/authorize";
+import { approveDraft, dismissDraft, DraftError } from "@/lib/reports/drafts";
+import { AnalystError } from "@/lib/analyst/types";
+import { readReport } from "@/lib/reports/read";
+
+// POST /api/tasks/:id/report/draft {source, id, linkId?, action, text?} -
+// send the drafted next prompt to the coding agent (text: the reader's
+// edit), or dismiss it. 409 when it was already decided.
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id: taskId } = await params;
+  const refused = refuse(request, taskId, "plan");
+  if (refused) return refused;
+  const b = await request.json().catch(() => ({}));
+  const source =
+    b.source === "analyst"
+      ? "analyst"
+      : b.source === "report"
+        ? "report"
+        : null;
+  if (
+    !source ||
+    typeof b.id !== "string" ||
+    !["send", "dismiss"].includes(b.action)
+  )
+    return NextResponse.json({ error: "Bad draft request" }, { status: 400 });
+  if (
+    b.text !== undefined &&
+    (typeof b.text !== "string" || b.text.length > 20_000)
+  )
+    return NextResponse.json({ error: "Bad text" }, { status: 400 });
+  const ref = {
+    source,
+    id: b.id,
+    linkId: typeof b.linkId === "string" ? b.linkId : undefined,
+  } as const;
+  try {
+    if (b.action === "send")
+      await approveDraft(taskId, { ...ref, text: b.text });
+    else dismissDraft(taskId, ref);
+    return NextResponse.json(readReport(taskId));
+  } catch (error) {
+    if (error instanceof DraftError || error instanceof AnalystError)
+      return NextResponse.json(
+        { error: error.message },
+        { status: error.status }
+      );
+    const message = error instanceof Error ? error.message : String(error);
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}

package/app/api/tasks/[id]/report/evidence/[evId]/route.ts

@@ -0,0 +1,18 @@
+import { NextRequest, NextResponse } from "next/server";
+import { refuse } from "@/lib/tasks/contract/authorize";
+import { latestReport } from "@/lib/reports/store";
+
+// GET /api/tasks/:id/report/evidence/:evId - one piece of evidence behind the
+// latest report, for the drill-down. Its text is untrusted: show it only.
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string; evId: string }> }
+) {
+  const { id, evId } = await params;
+  const refused = refuse(request, id, "open");
+  if (refused) return refused;
+  const ev = latestReport(id)?.evidence.find((e) => e.id === evId);
+  if (!ev)
+    return NextResponse.json({ error: "No such evidence" }, { status: 404 });
+  return NextResponse.json({ evidence: ev });
+}

package/app/api/tasks/[id]/report/route.ts

@@ -0,0 +1,39 @@
+import { NextRequest, NextResponse } from "next/server";
+import { refuse } from "@/lib/tasks/contract/authorize";
+import { generateReport } from "@/lib/reports/generate";
+import { readReport } from "@/lib/reports/read";
+import { historyOf } from "@/lib/reports/store";
+import { db } from "@/lib/db";
+
+type Ctx = { params: Promise<{ id: string }> };
+
+const exists = (id: string) =>
+  !!db.prepare(`SELECT 1 FROM session_rows WHERE id = ?`).get(id);
+
+// GET /api/tasks/:id/report - the latest plain-English health report, whether
+// one is being built, and the task's operating mode. ?history=1 lists the
+// earlier ones.
+export async function GET(request: NextRequest, { params }: Ctx) {
+  const { id } = await params;
+  const refused = refuse(request, id, "open");
+  if (refused) return refused;
+  if (!exists(id))
+    return NextResponse.json({ error: "No such task" }, { status: 404 });
+  if (request.nextUrl.searchParams.get("history") === "1")
+    return NextResponse.json({ history: historyOf(id) });
+  return NextResponse.json(readReport(id));
+}
+
+// POST /api/tasks/:id/report - build a new report now. Answers at once; the
+// client polls the GET until `generating` clears.
+export async function POST(request: NextRequest, { params }: Ctx) {
+  const { id } = await params;
+  const refused = refuse(request, id, "plan");
+  if (refused) return refused;
+  if (!exists(id))
+    return NextResponse.json({ error: "No such task" }, { status: 404 });
+  generateReport(id, "on-demand").catch((error) =>
+    console.error(`Report ${id}:`, error)
+  );
+  return NextResponse.json({ generating: true }, { status: 202 });
+}

package/app/api/workspaces/[id]/mode/route.ts

@@ -0,0 +1,23 @@
+import { NextRequest, NextResponse } from "next/server";
+import { setWorkspaceMode, workspaceMode } from "@/lib/reports/mode";
+import { isMode } from "@/lib/reports/types";
+
+type Ctx = { params: Promise<{ id: string }> };
+
+// GET /api/workspaces/:id/mode - the default operating mode of its tasks.
+export async function GET(_request: NextRequest, { params }: Ctx) {
+  return NextResponse.json({ mode: workspaceMode((await params).id) });
+}
+
+// PUT /api/workspaces/:id/mode {mode}
+export async function PUT(request: NextRequest, { params }: Ctx) {
+  const { id } = await params;
+  const { mode } = await request.json().catch(() => ({}));
+  if (!isMode(mode))
+    return NextResponse.json(
+      { error: "mode is manual, assisted or autonomous" },
+      { status: 400 }
+    );
+  setWorkspaceMode(id, mode);
+  return NextResponse.json({ mode });
+}

package/app/api/workspaces/[id]/reports/route.ts

@@ -0,0 +1,17 @@
+import { NextRequest, NextResponse } from "next/server";
+import { isFinished } from "@/lib/tasks/state";
+import { latestByTask, summaryOf } from "@/lib/reports/store";
+
+// GET /api/workspaces/:id/reports - the newest report of each task: headline,
+// estimate and state. ?active=1 leaves out finished tasks.
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  const active = request.nextUrl.searchParams.get("active") === "1";
+  const reports = latestByTask(id)
+    .filter(({ report }) => !active || !isFinished(report.state))
+    .map(({ report, name }) => summaryOf(report, name));
+  return NextResponse.json({ reports });
+}

package/app/page.tsx

@@ -142,6 +142,13 @@ const ExportSheet = dynamic(
   () => import("@/components/Export/ExportSheet").then((m) => m.ExportSheet),
   { ssr: false }
 );
+const StartAnalystSheet = dynamic(
+  () =>
+    import("@/components/Analyst/StartAnalystSheet").then(
+      (m) => m.StartAnalystSheet
+    ),
+  { ssr: false }
+);
 const CommandPalette = dynamic(
   () =>
     import("@/components/CommandPalette/CommandPalette").then(
@@ -171,6 +178,7 @@ const AppDialogs = memo(function AppDialogs({
       <MoveDialog />
       <ShareDialog />
       <ExportSheet />
+      <StartAnalystSheet />
       <AwayReport />
       <IncomingLinks />
       <CommandPalette />

package/components/Analyst/PairChip.tsx

@@ -0,0 +1,131 @@
+"use client";
+
+import { toast } from "sonner";
+import { Eye, Loader2 } from "lucide-react";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { usePanes } from "@/contexts/PaneContext";
+import {
+  useAskAgain,
+  useEndAnalyst,
+  useReviewNow,
+  useSessionAnalyst,
+  useSetAnalystPaused,
+} from "@/data/analyst";
+import type { Session } from "@/lib/db";
+import { cn } from "@/lib/utils";
+import {
+  PAIR_STATUS_LABEL,
+  pairStatus,
+  partnerOf,
+  paneTmux,
+  type PairStatus,
+} from "./pair";
+
+const DOT: Record<PairStatus, string> = {
+  paused: "bg-muted-foreground/50",
+  reviewing: "bg-primary animate-pulse",
+  recommendation: "bg-primary",
+  watching: "bg-green-500",
+};
+
+const fail = (e: Error) => toast.error(e.message);
+
+// A paired chat's link to the other side, with the pairing's controls.
+// Nothing for a session that isn't paired.
+export function PairChip({
+  session,
+  paneId,
+}: {
+  session: Session | null | undefined;
+  paneId: string;
+}) {
+  const { data: link } = useSessionAnalyst(
+    session?.view === "chat" ? session.id : undefined
+  );
+  const { openBeside } = usePanes();
+  const id = link?.id ?? "";
+  const review = useReviewNow(id);
+  const pause = useSetAnalystPaused(id);
+  const end = useEndAnalyst(id);
+  const again = useAskAgain(id);
+  if (!session || !link || link.endedAt) return null;
+
+  const status = pairStatus(link);
+  const isCoder = link.coder.id === session.id;
+  const partner = partnerOf(link, session.id);
+  const latest = link.recommendations[0];
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <button
+          type="button"
+          onClick={(e) => e.stopPropagation()}
+          title={PAIR_STATUS_LABEL[status]}
+          aria-label={`${isCoder ? "Analyst" : "Reviewing"} ${partner.name}: ${PAIR_STATUS_LABEL[status]}`}
+          className="ring-border/70 bg-muted/60 hover:bg-accent flex h-7 max-w-56 shrink-0 items-center gap-1.5 rounded-full px-2.5 text-xs ring-1 ring-inset"
+        >
+          <Eye className="text-muted-foreground h-3.5 w-3.5 shrink-0" />
+          <span className="truncate">
+            {isCoder ? "Analyst" : "Coding agent"}
+          </span>
+          <span
+            className={cn("h-1.5 w-1.5 shrink-0 rounded-full", DOT[status])}
+          />
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="start" className="w-60">
+        <DropdownMenuLabel className="space-y-0.5">
+          <div className="text-muted-foreground text-[11px] font-normal">
+            {isCoder ? "Reviewed by" : "Reviewing"} ·{" "}
+            {PAIR_STATUS_LABEL[status]}
+          </div>
+          <div className="truncate text-sm">{partner.name}</div>
+        </DropdownMenuLabel>
+        <DropdownMenuItem
+          onSelect={() =>
+            openBeside(paneId, {
+              sessionId: partner.id,
+              tmux: paneTmux(partner),
+            })
+          }
+        >
+          Open {isCoder ? "analyst" : "coding agent"} beside
+        </DropdownMenuItem>
+        <DropdownMenuItem
+          disabled={review.isPending || !!link.pendingDigestId}
+          onSelect={() => review.mutate(undefined, { onError: fail })}
+        >
+          {review.isPending && <Loader2 className="animate-spin" />}
+          {link.pendingDigestId ? "Reviewing…" : "Review now"}
+        </DropdownMenuItem>
+        {latest?.state === "invalid" && (
+          <DropdownMenuItem
+            onSelect={() => again.mutate(latest.id, { onError: fail })}
+          >
+            Ask for the review again
+          </DropdownMenuItem>
+        )}
+        <DropdownMenuItem
+          onSelect={() => pause.mutate(!link.paused, { onError: fail })}
+        >
+          {link.paused ? "Resume reviews" : "Pause reviews"}
+        </DropdownMenuItem>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem
+          variant="destructive"
+          onSelect={() => end.mutate(true, { onError: fail })}
+        >
+          Unlink and finish the analyst
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

package/components/Analyst/PairSwitch.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+import { usePanes } from "@/contexts/PaneContext";
+import { useSessionAnalyst } from "@/data/analyst";
+import type { Session } from "@/lib/db";
+import { cn } from "@/lib/utils";
+import { PAIR_STATUS_LABEL, pairStatus, paneTmux } from "./pair";
+
+// A phone shows one pane: a paired chat switches between its two sides
+// here, with a dot on the analyst while a recommendation waits.
+export function PairSwitch({
+  session,
+  paneId,
+}: {
+  session: Session | null | undefined;
+  paneId: string;
+}) {
+  const { data: link } = useSessionAnalyst(
+    session?.view === "chat" ? session.id : undefined
+  );
+  const { attachSession } = usePanes();
+  if (!session || !link || link.endedAt) return null;
+
+  const status = pairStatus(link);
+  const sides = [
+    { side: link.coder, label: "Coding agent", note: null },
+    {
+      side: link.analyst,
+      label: "Analyst",
+      note: PAIR_STATUS_LABEL[status],
+    },
+  ];
+
+  return (
+    <div
+      role="tablist"
+      aria-label="Paired sessions"
+      className="bg-muted grid grid-cols-2 gap-1 px-2 pb-1.5"
+      onClick={(e) => e.stopPropagation()}
+    >
+      {sides.map(({ side, label, note }) => {
+        const active = side.id === session.id;
+        return (
+          <button
+            key={side.id}
+            type="button"
+            role="tab"
+            aria-selected={active}
+            onClick={() =>
+              !active && attachSession(paneId, side.id, paneTmux(side))
+            }
+            className={cn(
+              "flex h-11 min-w-0 items-center justify-center gap-1.5 rounded-lg text-sm",
+              active
+                ? "bg-background text-foreground font-medium shadow-sm"
+                : "text-muted-foreground"
+            )}
+          >
+            <span className="truncate">{label}</span>
+            {note && status === "recommendation" && !active && (
+              <span
+                aria-label="Recommendation waiting"
+                className="bg-primary h-2 w-2 shrink-0 rounded-full"
+              />
+            )}
+            {note && (
+              <span className="text-muted-foreground shrink-0 text-xs font-normal">
+                {note}
+              </span>
+            )}
+          </button>
+        );
+      })}
+    </div>
+  );
+}