@saadnvd1/agent-os 0.3.698 → 0.3.715

package/README.md

@@ -31,6 +31,7 @@ and check on all of it from your phone.
 - **Machine load and status.** A load gauge, each session's share of CPU and memory, and Needs you, Working, In review and Done as it changes. [More](docs/guides/sessions.md)
 - **A health watcher.** Zero-token checks on the orchestrator's tick catch a red machine load, a held queue, a quiet background job, a restart loop, slow CI, a PR armed for hours and a piece started twice. Each trip wakes one short, tool-less Sonnet call that judges it and posts one line to the orchestrator; only a thing you alone can clear reaches your phone. Settings → Health lists what is open, the history, the notes on what normal looks like and the thresholds. Report only: it never acts. [More](docs/reference/health.md)
 - **Workspaces.** Group projects, finish work with Done, and get a log of every merged task. [More](docs/reference/workspaces.md)
+- **Session groups.** Named shelves inside a workspace, under Pinned, for sessions that belong together; a group stays put while its sessions change state. [More](docs/guides/sessions.md#groups)
 - **LumifyHub (optional).** Boards, cards and docs for a workspace, if you want them. [More](docs/lumifyhub.md)
 - **No approvals mode.** One switch in Settings that approves every ask, lets brakes and plan-only tasks through, and starts every agent with its permission prompts off; each approval it makes is logged. Off by default. [More](docs/reference/orchestrator.md#no-approvals-mode)
 - **Experiments.** Settings → Experiments lists features still being tried, each off until you turn it on, with what it has cost and how often its suggestions were taken. The first is Learning cards: when a session ends it can offer to save the work as a recipe or keep a lesson where it belongs. [More](docs/decisions/2026-10-13-experiments.md)

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

@@ -0,0 +1,44 @@
+import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
+import { groupCommand } from "@/lib/session-groups/cli";
+import { GROUP_STATUS, GroupError } from "@/lib/session-groups";
+
+const refs = z.array(z.string().min(1)).min(1);
+const body = z.object({
+  from: z.string().min(1, "aos group runs from inside an AgentOS session"),
+  command: z.discriminatedUnion("action", [
+    z.object({ action: z.literal("list") }),
+    z.object({ action: z.literal("new"), name: z.string() }),
+    z.object({
+      action: z.literal("rename"),
+      group: z.string(),
+      name: z.string(),
+    }),
+    z.object({
+      action: z.literal("add"),
+      group: z.string(),
+      sessions: refs,
+    }),
+    z.object({ action: z.literal("rm"), sessions: refs }),
+  ]),
+});
+
+// POST /api/bus/groups { from, command } - `aos group …`, scoped to the
+// asking session's workspace like `aos read`.
+export async function POST(request: NextRequest) {
+  const parsed = body.safeParse(await request.json().catch(() => null));
+  if (!parsed.success)
+    return NextResponse.json(
+      { error: parsed.error.issues[0]?.message ?? "Bad request" },
+      { status: 400 }
+    );
+  try {
+    return NextResponse.json({
+      summary: groupCommand(parsed.data.from, parsed.data.command),
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const status = error instanceof GroupError ? GROUP_STATUS[error.code] : 409;
+    return NextResponse.json({ error: message }, { status });
+  }
+}

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

@@ -1,16 +1,26 @@
 import { NextRequest, NextResponse } from "next/server";
 import { sendMessage } from "@/lib/bus";
+import { parseTimeout } from "@/lib/bus/waits/register";
 
 // from: the sending session's id, or null when the user sends from the UI.
 // The message is stored either way; delivery says whether it reached the
 // recipient ("delivered", "queued" behind a busy turn, or "failed" + why).
 export async function POST(request: NextRequest) {
   try {
-    const { from = null, to, body } = await request.json();
+    const {
+      from = null,
+      to,
+      body,
+      await: waits = false,
+      timeout,
+      replyTo,
+    } = await request.json();
     const sent = await sendMessage({
       fromId: from,
       to: String(to ?? ""),
       body: String(body ?? ""),
+      replyTo: replyTo == null ? undefined : Number(replyTo),
+      awaitMs: waits ? parseTimeout(timeout) : undefined,
     });
     return NextResponse.json(sent, { status: 201 });
   } catch (error) {

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

@@ -4,6 +4,7 @@ import { createTask } from "@/lib/tasks";
 import { startOrQueue, stampPriority } from "@/lib/tasks/queue";
 import { isPriority } from "@/lib/tasks/schedule-types";
 import { hostIdNamed } from "@/lib/hosts";
+import { resolveGroup } from "@/lib/session-groups";
 import { startView } from "@/lib/sessions/launch";
 import { callerSession, starterOf } from "@/lib/tasks/starter";
 import { callingDevice } from "@/lib/security/device-me";
@@ -33,6 +34,7 @@ export async function POST(request: NextRequest) {
       from,
       cwd,
       piece,
+      group,
     } = await request.json();
     // Whoever called: a session (by `from`, else the worktree it runs in) or a person.
     const starter = starterOf(
@@ -53,8 +55,15 @@ export async function POST(request: NextRequest) {
       throw new Error('machine is "mac" or "any"');
     if (piece !== undefined && mode !== "task")
       throw new Error("--piece works for tasks only");
+    const target = findProject(String(project ?? ""));
+    if (group !== undefined && (typeof group !== "string" || !group.trim()))
+      throw new Error("--group needs a group name");
+    const groupId =
+      typeof group === "string"
+        ? resolveGroup(target.workspace_id ?? null, group).id
+        : undefined;
     if (mode === "task") {
-      const projectId = findProject(String(project ?? "")).id;
+      const projectId = target.id;
       // A task whose plan has pieces waiting here must say which it builds.
       const waiting = startedBy ? waitingPiecesFor(startedBy, projectId) : [];
       let pieceId: number | undefined;
@@ -73,6 +82,7 @@ export async function POST(request: NextRequest) {
         model,
         hostId: on ? hostIdNamed(String(on)) : undefined,
         view: startView(view),
+        groupId,
         planOnly: planOnly === true ? true : undefined,
       };
       const out = await startOrQueue(
@@ -100,6 +110,7 @@ export async function POST(request: NextRequest) {
       model,
       startedBy,
       parentSessionId: starter.parentSessionId,
+      groupId,
     });
     return NextResponse.json({ session }, { status: 201 });
   } catch (error) {

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

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { registerWait } from "@/lib/bus/waits/register";
+
+// `aos wait <session> --until idle|merged|reply`: records the wait and
+// returns; the sweep wakes the sender when it holds (lib/bus/waits/tick).
+export async function POST(request: NextRequest) {
+  try {
+    const { from, to, until, timeout } = await request.json();
+    if (typeof from !== "string" || !from)
+      throw new Error("aos wait runs from inside an AgentOS session");
+    const result = await registerWait({
+      fromId: from,
+      to: String(to ?? ""),
+      until: String(until ?? ""),
+      timeout: timeout == null ? null : String(timeout),
+    });
+    return NextResponse.json(result, { status: 201 });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return NextResponse.json({ error: message }, { status: 400 });
+  }
+}

package/app/api/claims/[id]/route.ts

@@ -0,0 +1,20 @@
+import { NextResponse } from "next/server";
+import { endOutside } from "@/lib/claims";
+
+export const dynamic = "force-dynamic";
+
+// DELETE /api/claims/:id - an outside session ends its own claim. A task's
+// or another machine's claim can't be ended this way.
+export async function DELETE(
+  _request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  const result = endOutside(id);
+  if (result === "forbidden")
+    return NextResponse.json(
+      { error: "Only an outside session's claim can be ended here" },
+      { status: 403 }
+    );
+  return NextResponse.json({ ok: true, ended: result === "ended" });
+}

package/app/api/claims/check/route.ts

@@ -0,0 +1,23 @@
+import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
+import { checkStart } from "@/lib/claims/startCheck";
+import { startWarning } from "@/lib/claims/startWarning";
+
+export const dynamic = "force-dynamic";
+
+const body = z.object({
+  projectId: z.string().min(1).max(100),
+  name: z.string().max(200).optional(),
+  prompt: z.string().max(100_000),
+  branch: z.string().max(250).nullable().optional(),
+});
+
+// POST /api/claims/check - before a person starts a task: who else is on the
+// same work. Reads claims and the repo's file list; never blocks a start.
+export async function POST(request: NextRequest) {
+  const parsed = body.safeParse(await request.json().catch(() => null));
+  if (!parsed.success)
+    return NextResponse.json({ error: "Bad check" }, { status: 400 });
+  const { overlaps } = await checkStart(parsed.data);
+  return NextResponse.json({ overlaps: overlaps.map(startWarning) });
+}

package/app/api/claims/check.test.ts

@@ -0,0 +1,113 @@
+import { execFileSync } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { NextRequest } from "next/server";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { tempDir } from "@/lib/test-temp";
+import { seedWorkspace } from "@/lib/orchestrator/testing";
+
+const { db } = await import("@/lib/db");
+const { machineId } = await import("@/lib/claims/machine");
+const { upsertRemote } = await import("@/lib/claims/store");
+const { putSetting } = await import("@/lib/settings-store");
+const { POST } = await import("./check/route");
+
+const FILES = ["lib/auth/session.ts", "lib/auth/index.ts", "lib/auth/token.ts"];
+const REPO = "git.example.test/team/widgets";
+
+let dir: string;
+let projectId: string;
+
+const sh = (cwd: string, ...args: string[]) =>
+  execFileSync("git", args, { cwd, stdio: "pipe" });
+
+const check = (body: unknown) =>
+  POST(
+    new NextRequest("http://localhost/api/claims/check", {
+      method: "POST",
+      body: typeof body === "string" ? body : JSON.stringify(body),
+    })
+  );
+
+beforeAll(() => {
+  vi.spyOn(os, "homedir").mockReturnValue(tempDir("aos-claim-check-"));
+  dir = tempDir("claim-check-repo-");
+  sh(dir, "init", "-q", "-b", "main");
+  sh(dir, "config", "user.email", "t@example.test");
+  sh(dir, "config", "user.name", "t");
+  sh(dir, "remote", "add", "origin", "git@git.example.test:team/widgets.git");
+  for (const f of FILES) {
+    fs.mkdirSync(path.dirname(path.join(dir, f)), { recursive: true });
+    fs.writeFileSync(path.join(dir, f), "x");
+  }
+  sh(dir, "add", "-A");
+  sh(dir, "commit", "-q", "-m", "init");
+});
+
+beforeEach(() => {
+  db.prepare(`DELETE FROM work_claims`).run();
+  putSetting("claims.share", "on");
+  const t = seedWorkspace();
+  projectId = t.app.id;
+  db.prepare(`UPDATE projects SET working_directory = ? WHERE id = ?`).run(
+    dir,
+    projectId
+  );
+});
+
+const remote = (files: string[]) =>
+  upsertRemote(machineId(), "peer-1", {
+    id: "claim-box-1",
+    origin: "box-machine",
+    origin_name: "box",
+    hops: 0,
+    source: "session",
+    session_name: "Rework login sessions",
+    repo: REPO,
+    branch: "feature/login",
+    base: "main",
+    goal: "Rework login sessions",
+    files,
+    files_more: 0,
+    pr_url: null,
+    ttl_s: 600,
+    age_s: 60,
+    released: null,
+  });
+
+describe("POST /api/claims/check", () => {
+  it("refuses a body that isn't a check", async () => {
+    expect((await check("nope")).status).toBe(400);
+    expect((await check({ projectId })).status).toBe(400);
+    expect((await check({ projectId, prompt: 5 })).status).toBe(400);
+  });
+
+  it("says nothing when no one else is on the repo", async () => {
+    const res = await check({ projectId, prompt: "Tidy auth" });
+    expect(await res.json()).toEqual({ overlaps: [] });
+  });
+
+  it("returns the overlap with the other claim, strong first", async () => {
+    remote(FILES);
+    const res = await check({
+      projectId,
+      name: "Tidy auth",
+      prompt: `Touch ${FILES.join(" ")}`,
+    });
+    const { overlaps } = await res.json();
+    expect(overlaps).toHaveLength(1);
+    expect(overlaps[0]).toMatchObject({
+      strength: "strong",
+      claim: { id: "claim-box-1", machine: "box", branch: "feature/login" },
+    });
+    expect(overlaps[0].shared).toEqual([...FILES].sort());
+  });
+
+  it("returns no overlaps when sharing is off", async () => {
+    remote(FILES);
+    putSetting("claims.share", "off");
+    const res = await check({ projectId, prompt: `Touch ${FILES.join(" ")}` });
+    expect(await res.json()).toEqual({ overlaps: [] });
+  });
+});

package/app/api/claims/exchange/route.ts

@@ -0,0 +1,42 @@
+import { NextRequest, NextResponse } from "next/server";
+import { acceptExchange, answerExchange } from "@/lib/claims/exchange";
+import { claimsShared } from "@/lib/claims/machine";
+import { rememberPeer } from "@/lib/claims/peers";
+import { exchangeBody } from "@/lib/claims/types";
+import { pinForHost } from "@/lib/peer/links";
+import { PEER_HEADER, TRUST_HEADER } from "@/lib/security/auth";
+import { readCapped } from "@/lib/security/read-capped";
+
+export const dynamic = "force-dynamic";
+
+const MAX_BYTES = 2 * 1024 * 1024;
+
+// POST /api/claims/exchange - a linked machine sends its claims and gets
+// ours back. Paths and one-line goals only; the device-token gate applies.
+export async function POST(request: NextRequest) {
+  // A Connect peer arrives as `peer` trust naming its pin. The RPC layer has
+  // already refused suspended and unknown ones; a pin suspended since is
+  // refused here too.
+  let viaHost: string | null = null;
+  if (request.headers.get(TRUST_HEADER) === "peer") {
+    const hostId = request.headers.get(PEER_HEADER);
+    if (!hostId || pinForHost(hostId)?.state !== "active")
+      return NextResponse.json({ error: "forbidden" }, { status: 403 });
+    viaHost = hostId;
+  }
+  const raw = await readCapped(request, MAX_BYTES);
+  if (raw === null)
+    return NextResponse.json({ error: "Too large" }, { status: 413 });
+  let json: unknown;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    return NextResponse.json({ error: "Not JSON" }, { status: 400 });
+  }
+  const body = exchangeBody.safeParse(json);
+  if (!body.success)
+    return NextResponse.json({ error: "Bad claims" }, { status: 400 });
+  if (viaHost && claimsShared()) rememberPeer(viaHost, body.data.machine.id);
+  acceptExchange(body.data, viaHost);
+  return NextResponse.json(answerExchange(body.data));
+}

package/app/api/claims/outside.test.ts

@@ -0,0 +1,90 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { NextRequest } from "next/server";
+import { db } from "@/lib/db";
+import { machineId } from "@/lib/claims/machine";
+import { putSetting } from "@/lib/settings-store";
+import { upsertLocal } from "@/lib/claims/store";
+import { POST } from "./route";
+import { DELETE } from "./[id]/route";
+
+beforeEach(() => {
+  db.prepare(`DELETE FROM work_claims`).run();
+  putSetting("claims.share", null);
+});
+
+const post = (body: unknown) =>
+  POST(
+    new NextRequest("http://localhost/api/claims", {
+      method: "POST",
+      body: JSON.stringify(body),
+    })
+  );
+const del = (id: string) =>
+  DELETE(new Request("http://localhost"), { params: Promise.resolve({ id }) });
+
+const ok = {
+  remote: "https://github.com/acme/widgets.git",
+  branch: "feature/search",
+  goal: "Rework search",
+  files: ["src/search.ts"],
+};
+
+describe("POST /api/claims", () => {
+  it("registers, then reports an overlap with a task's claim", async () => {
+    upsertLocal(
+      { id: machineId(), name: "here" },
+      {
+        sessionId: "t1",
+        sessionName: "Task",
+        repo: "github.com/acme/widgets",
+        branch: "task/search",
+        base: "main",
+        goal: "Search work",
+        files: ["src/search.ts"],
+        filesMore: 0,
+        prUrl: null,
+      }
+    );
+    const res = await post(ok);
+    const data = await res.json();
+    expect(res.status).toBe(200);
+    expect(data.id).toMatch(/^o-/);
+    expect(data.overlaps[0].strength).toBe("strong");
+  });
+
+  it("rejects a bad body, a non-remote and a custom id", async () => {
+    expect((await post({ remote: 5 })).status).toBe(400);
+    expect((await post({ ...ok, id: "s-abc" })).status).toBe(400);
+    expect((await post({ ...ok, remote: "/srv/x" })).status).toBe(422);
+  });
+
+  it("is off when claims are", async () => {
+    putSetting("claims.share", "off");
+    expect((await post(ok)).status).toBe(409);
+  });
+});
+
+describe("DELETE /api/claims/:id", () => {
+  it("ends an outside claim but not a task's", async () => {
+    upsertLocal(
+      { id: machineId(), name: "here" },
+      {
+        sessionId: "t1",
+        sessionName: "Task",
+        repo: "github.com/acme/widgets",
+        branch: "x",
+        base: "main",
+        goal: "Task",
+        files: [],
+        filesMore: 0,
+        prUrl: null,
+      }
+    );
+    expect((await del("s-t1")).status).toBe(403);
+    const { id } = await (await post(ok)).json();
+    expect((await del(id)).status).toBe(200);
+    expect((await del("o-00000000-0000-0000-0000-000000000000")).status).toBe(
+      200
+    );
+  });
+});

package/app/api/claims/route.test.ts

@@ -0,0 +1,193 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { NextRequest } from "next/server";
+import { db } from "@/lib/db";
+import { machineId } from "@/lib/claims/machine";
+import { createConnectHost } from "@/lib/hosts";
+import { putSetting } from "@/lib/settings-store";
+import { savePin, suspendPin } from "@/lib/peer/links";
+import { upsertLocal } from "@/lib/claims/store";
+import { GET } from "./route";
+import { POST } from "./exchange/route";
+
+const post = (body: unknown) =>
+  POST(
+    new NextRequest("http://localhost/api/claims/exchange", {
+      method: "POST",
+      body: typeof body === "string" ? body : JSON.stringify(body),
+    })
+  );
+
+beforeEach(() => {
+  db.prepare(`DELETE FROM work_claims`).run();
+});
+
+const claim = {
+  id: "r1",
+  origin: "peer-1",
+  origin_name: "box",
+  goal: "Add oauth",
+  repo: "github.com/acme/widgets",
+  branch: "feature/oauth",
+  files: ["a.ts"],
+  ttl_s: 300,
+  age_s: 5,
+};
+
+describe("POST /api/claims/exchange", () => {
+  it("stores a peer's claims and answers with ours", async () => {
+    upsertLocal(
+      { id: machineId(), name: "here" },
+      {
+        sessionId: "s",
+        sessionName: "Mine",
+        repo: "github.com/acme/widgets",
+        branch: "feature/mine",
+        base: "main",
+        goal: "Mine",
+        files: [],
+        filesMore: 0,
+        prUrl: null,
+      }
+    );
+    const res = await post({
+      machine: { id: "peer-1", name: "box" },
+      claims: [claim],
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.machine.id).toBe(machineId());
+    expect(body.claims.map((c: { id: string }) => c.id)).toEqual(["s-s"]);
+    const list = await (
+      await GET(new NextRequest("http://localhost/api/claims"))
+    ).json();
+    expect(list.claims.map((c: { id: string }) => c.id).sort()).toEqual([
+      "r1",
+      "s-s",
+    ]);
+  });
+
+  it("refuses bodies that are not claims", async () => {
+    expect((await post("{nope")).status).toBe(400);
+    expect(
+      (await post({ machine: { id: "p", name: "n" }, claims: [{ id: "x" }] }))
+        .status
+    ).toBe(400);
+    expect(
+      (
+        await post({
+          machine: { id: "p", name: "n" },
+          claims: [{ ...claim, ttl_s: -5 }],
+        })
+      ).status
+    ).toBe(400);
+  });
+});
+
+describe("POST /api/claims/exchange as a Connect peer", () => {
+  const asPeer = (hostId: string | null) =>
+    POST(
+      new NextRequest("http://localhost/api/claims/exchange", {
+        method: "POST",
+        headers: {
+          "x-agentos-trust": "peer",
+          ...(hostId && { "x-agentos-peer": hostId }),
+        },
+        body: JSON.stringify({
+          machine: { id: "peer-1", name: "box" },
+          claims: [claim],
+        }),
+      })
+    );
+
+  it("refuses a host with no active pin and stores nothing", async () => {
+    expect((await asPeer("no-such-host")).status).toBe(403);
+    expect((await asPeer(null)).status).toBe(403);
+    expect(db.prepare(`SELECT 1 FROM work_claims`).all()).toEqual([]);
+  });
+
+  it("refuses a suspended pin, and an active one keeps its via_host", async () => {
+    const host = createConnectHost(`Spark-${Date.now()}`).id;
+    savePin({
+      hostId: host,
+      machineId: "b2b2b2b2",
+      hostname: "m-0123456789abcdef.runagentos.com",
+      signPub: "s",
+      boxPub: "b",
+    });
+    expect((await asPeer(host)).status).toBe(200);
+    const via = () =>
+      (
+        db.prepare(`SELECT via_host FROM work_claims WHERE id='r1'`).get() as {
+          via_host: string | null;
+        }
+      ).via_host;
+    expect(via()).toBe(host);
+    // A token caller re-sending it, with more life, must not clear the pin.
+    await post({
+      machine: { id: "peer-1", name: "box" },
+      claims: [{ ...claim, ttl_s: 600 }],
+    });
+    expect(via()).toBe(host);
+    suspendPin(host, "revoked");
+    db.prepare(`DELETE FROM work_claims`).run();
+    expect((await asPeer(host)).status).toBe(403);
+    expect(db.prepare(`SELECT 1 FROM work_claims`).all()).toEqual([]);
+  });
+
+  it("writes nothing when sharing is off", async () => {
+    const host = createConnectHost(`Studio-${Date.now()}`).id;
+    savePin({
+      hostId: host,
+      machineId: "c3c3c3c3",
+      hostname: "m-fedcba9876543210.runagentos.com",
+      signPub: "s",
+      boxPub: "b",
+    });
+    db.prepare(`DELETE FROM claim_peers`).run();
+    putSetting("claims.share", "off");
+    try {
+      expect((await asPeer(host)).status).toBe(200);
+    } finally {
+      putSetting("claims.share", "on");
+    }
+    expect(db.prepare(`SELECT 1 FROM claim_peers`).all()).toEqual([]);
+  });
+});
+
+describe("GET /api/claims", () => {
+  it("rejects a bad query and an unknown session", async () => {
+    const bad = await GET(
+      new NextRequest(`http://localhost/api/claims?repo=${"x".repeat(400)}`)
+    );
+    expect(bad.status).toBe(400);
+    const none = await GET(
+      new NextRequest("http://localhost/api/claims?session=missing")
+    );
+    expect(none.status).toBe(404);
+  });
+
+  it("narrows to a repo and lists overlaps", async () => {
+    await post({
+      machine: { id: "peer-1", name: "box" },
+      claims: [
+        claim,
+        {
+          ...claim,
+          id: "r2",
+          origin: "peer-2",
+          origin_name: "pc",
+          repo: "github.com/acme/other",
+        },
+      ],
+    });
+    const body = await (
+      await GET(
+        new NextRequest(
+          "http://localhost/api/claims?repo=github.com/acme/widgets"
+        )
+      )
+    ).json();
+    expect(body.claims.map((c: { id: string }) => c.id)).toEqual(["r1"]);
+    expect(body.overlaps).toEqual([]);
+  });
+});