@saadnvd1/agent-os 0.3.723 → 0.3.731

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/bus/ports/route.test.ts

@@ -0,0 +1,43 @@
+import { NextRequest } from "next/server";
+import { describe, expect, it, vi } from "vitest";
+
+const ensure = vi.hoisted(() => vi.fn());
+vi.mock("@/lib/ports/ensurePorts", () => ({ ensurePorts: ensure }));
+
+const { POST } = await import("./route");
+
+const call = (body: unknown) =>
+  POST(
+    new NextRequest("http://localhost/api/bus/ports", {
+      method: "POST",
+      body: JSON.stringify(body),
+    })
+  );
+
+describe("POST /api/bus/ports (aos port)", () => {
+  it("refuses a body without a session or with a target that's neither a name nor a port", async () => {
+    expect((await call({})).status).toBe(400);
+    expect((await call({ from: "s", target: "3000; rm -rf /" })).status).toBe(
+      400
+    );
+    expect(ensure).not.toHaveBeenCalled();
+  });
+
+  it("hands the session and target to ensurePorts and returns its report", async () => {
+    ensure.mockResolvedValueOnce({
+      text: "PORT=3101 is free.",
+      blocked: false,
+    });
+    const res = await call({ from: "s1", target: "PORT" });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({ text: "PORT=3101 is free." });
+    expect(ensure).toHaveBeenCalledWith("s1", "PORT");
+  });
+
+  it("is 404 for an unknown session and 409 for anything else it refuses", async () => {
+    ensure.mockRejectedValueOnce(new Error("No session nope"));
+    expect((await call({ from: "nope" })).status).toBe(404);
+    ensure.mockRejectedValueOnce(new Error("No port named X"));
+    expect((await call({ from: "s1", target: "X" })).status).toBe(409);
+  });
+});

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

@@ -0,0 +1,35 @@
+import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
+import { ensurePorts } from "@/lib/ports/ensurePorts";
+
+const body = z.object({
+  from: z.string().min(1),
+  target: z
+    .string()
+    .regex(/^(\d{1,5}|[A-Za-z_][A-Za-z0-9_]*)$/)
+    .optional(),
+});
+
+// POST /api/bus/ports { from, target? } - `aos port`: whether the caller's
+// ports are free on this machine, who holds the ones that aren't, and a free
+// one in place of each taken one.
+export async function POST(request: NextRequest) {
+  const parsed = body.safeParse(await request.json().catch(() => null));
+  if (!parsed.success)
+    return NextResponse.json(
+      {
+        error: "Send { from: your session id, target?: a port name or number }",
+      },
+      { status: 400 }
+    );
+  const { from, target } = parsed.data;
+  try {
+    return NextResponse.json(await ensurePorts(from, target));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return NextResponse.json(
+      { error: message },
+      { status: /^No session /.test(message) ? 404 : 409 }
+    );
+  }
+}

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/sessions/[id]/export/turn/route.test.ts

@@ -0,0 +1,65 @@
+import { randomUUID } from "crypto";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const route = await import("./route");
+const { saveItem } = await import("@/lib/chat/store");
+const { seedSession } = await import("@/lib/orchestrator/testing");
+const { createProject } = await import("@/lib/projects");
+
+const secret = ["gh", "p_", "d".repeat(36)].join("");
+const post = (b: unknown) =>
+  new Request("http://localhost/x", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(b),
+  });
+const params = (id: string) => ({ params: Promise.resolve({ id }) });
+
+function session() {
+  const project = createProject({
+    name: `p-${randomUUID().slice(0, 6)}`,
+    workingDirectory: "/tmp/p",
+  });
+  const id = seedSession({
+    projectId: project.id,
+    name: "Copy me",
+    view: "chat",
+  });
+  let t = 1;
+  const add = (i: Record<string, unknown>) =>
+    saveItem(id, { id: `c${t}`, createdAt: t++, ...i } as never);
+  add({ kind: "user", text: "first" });
+  add({ kind: "assistant", text: "one" });
+  add({ kind: "user", text: "second" });
+  add({ kind: "assistant", text: `two ${secret}` });
+  return id;
+}
+
+afterEach(() => vi.unstubAllEnvs());
+
+describe("POST /api/sessions/:id/export/turn", () => {
+  it("returns the turn and its response, secrets masked", async () => {
+    const id = session();
+    const res = await route.POST(post({ startId: "c3" }), params(id));
+    expect(res.status).toBe(200);
+    const j = await res.json();
+    expect(j.response).toContain("two [secret]");
+    expect(j.full).toContain("two [secret]");
+    expect(j.full).not.toContain("one");
+    expect(JSON.stringify(j)).not.toContain(secret);
+  });
+
+  it("404s an unknown turn and 400s a missing id", async () => {
+    const id = session();
+    expect((await route.POST(post({ startId: "zz" }), params(id))).status).toBe(
+      404
+    );
+    expect((await route.POST(post({}), params(id))).status).toBe(400);
+  });
+
+  it("refuses in the demo", async () => {
+    vi.stubEnv("AGENTOS_DEMO", "1");
+    const res = await route.POST(post({ startId: "c1" }), params(session()));
+    expect(res.status).toBe(403);
+  });
+});

package/app/api/sessions/[id]/export/turn/route.ts

@@ -0,0 +1,33 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { loadSession } from "@/lib/export/load";
+import { copyTurn } from "@/lib/export/turn";
+import { shareContext } from "@/lib/share/context";
+import { readJson, refuseDemo, toResponse } from "@/lib/share/route";
+import { BadShare } from "@/lib/share/service";
+
+const Body = z.object({ startId: z.string().min(1).max(200) });
+
+// POST /api/sessions/:id/export/turn - one turn as Markdown for the clipboard,
+// secrets masked: the whole turn, and its last agent message.
+export async function POST(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const refused = refuseDemo();
+  if (refused) return refused;
+  const read = await readJson(request);
+  if ("refused" in read) return read.refused;
+  try {
+    const { id } = await params;
+    const body = Body.safeParse(read.body);
+    if (!body.success) throw new BadShare("startId is required", 400);
+    const loaded = loadSession(id);
+    return NextResponse.json(
+      copyTurn(loaded.items, body.data.startId, shareContext(), loaded.meta),
+      { headers: { "Cache-Control": "no-store" } }
+    );
+  } catch (err) {
+    return toResponse(err);
+  }
+}

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 />