@saadnvd1/agent-os 0.3.556 → 0.3.558

package/README.md

@@ -27,6 +27,7 @@ and check on all of it from your phone.
 - **Workspaces.** Group projects, finish work with Done, and get a log of every merged task. [More](docs/reference/workspaces.md)
 - **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)
 - **Also:** a ⌘K palette, code search, a file picker, a git panel, dev servers, up to four panes, and dictation.
 
 ## Documentation

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

@@ -0,0 +1,39 @@
+import { NextRequest, NextResponse } from "next/server";
+import { experimentsLocked, setExperiment } from "@/lib/experiments";
+import { isExperimentId } from "@/lib/experiments/registry";
+import { usageDetail } from "@/lib/experiments/meter";
+import { experimentView } from "@/lib/experiments/view";
+
+type Ctx = { params: Promise<{ id: string }> };
+
+// GET /api/experiments/:id - the experiment with its per-day usage
+export async function GET(_req: NextRequest, { params }: Ctx) {
+  const { id } = await params;
+  if (!isExperimentId(id))
+    return NextResponse.json({ error: "Unknown experiment" }, { status: 404 });
+  return NextResponse.json({
+    ...experimentView(id),
+    locked: experimentsLocked(),
+    detail: usageDetail(id),
+  });
+}
+
+// PUT /api/experiments/:id {on} - anyone using the app may switch one
+export async function PUT(request: NextRequest, { params }: Ctx) {
+  const { id } = await params;
+  if (!isExperimentId(id))
+    return NextResponse.json({ error: "Unknown experiment" }, { status: 404 });
+  const body = (await request.json().catch(() => ({}))) as { on?: unknown };
+  if (typeof body.on !== "boolean")
+    return NextResponse.json(
+      { error: "on must be true or false" },
+      { status: 400 }
+    );
+  if (experimentsLocked())
+    return NextResponse.json(
+      { error: "Experiments are switched off for this server" },
+      { status: 409 }
+    );
+  setExperiment(id, body.on);
+  return NextResponse.json(experimentView(id));
+}

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

@@ -0,0 +1,51 @@
+import { NextRequest } from "next/server";
+import { beforeEach, describe, expect, it } from "vitest";
+import { db } from "@/lib/db";
+import { experimentOn } from "@/lib/experiments";
+import { GET } from "./route";
+import * as one from "./[id]/route";
+
+const ctx = (id: string) => ({ params: Promise.resolve({ id }) });
+const put = (id: string, body: unknown) =>
+  one.PUT(
+    new NextRequest(`http://localhost/api/experiments/${id}`, {
+      method: "PUT",
+      body: JSON.stringify(body),
+    }),
+    ctx(id)
+  );
+
+beforeEach(() => {
+  db.prepare(`DELETE FROM settings WHERE key LIKE 'experiments.%'`).run();
+});
+
+describe("/api/experiments", () => {
+  it("lists every experiment, off, with zero usage", async () => {
+    const body = await (await GET()).json();
+    const e = body.experiments.find(
+      (x: { id: string }) => x.id === "learning-cards"
+    );
+    expect(e).toMatchObject({ on: false, status: "experimental" });
+    expect(e.usage.today.calls).toBe(0);
+  });
+
+  it("switches one on and off", async () => {
+    expect((await put("learning-cards", { on: true })).status).toBe(200);
+    expect(experimentOn("learning-cards")).toBe(true);
+    await put("learning-cards", { on: false });
+    expect(experimentOn("learning-cards")).toBe(false);
+  });
+
+  it("refuses an unknown id and a bad body", async () => {
+    expect((await put("nope", { on: true })).status).toBe(404);
+    expect((await put("learning-cards", { on: "yes" })).status).toBe(400);
+  });
+
+  it("gives the detail view", async () => {
+    const res = await one.GET(
+      new NextRequest("http://localhost/api/experiments/learning-cards"),
+      ctx("learning-cards")
+    );
+    expect((await res.json()).detail.days).toHaveLength(30);
+  });
+});

package/app/api/experiments/route.ts

@@ -0,0 +1,7 @@
+import { NextResponse } from "next/server";
+import { experimentsView } from "@/lib/experiments/view";
+
+// GET /api/experiments - every experiment, whether it's on, and what it used
+export function GET() {
+  return NextResponse.json(experimentsView());
+}

package/app/api/learning-cards/[id]/route.test.ts

@@ -0,0 +1,62 @@
+import { NextRequest } from "next/server";
+import { beforeEach, describe, expect, it } from "vitest";
+import { setExperiment } from "@/lib/experiments";
+import { listRules } from "@/lib/orchestrator/rules";
+import { clearCards, seedSession } from "@/lib/learning-cards/__fixtures__/db";
+import { insertCard } from "@/lib/learning-cards/store";
+import { POST } from "./route";
+
+const post = (id: string, body: unknown) =>
+  POST(
+    new NextRequest(`http://localhost/api/learning-cards/${id}`, {
+      method: "POST",
+      body: JSON.stringify(body),
+    }),
+    { params: Promise.resolve({ id }) }
+  );
+
+function card() {
+  const s = seedSession();
+  const c = insertCard({
+    sessionId: s.id,
+    workspaceId: s.ws.id,
+    kind: "lesson",
+    destination: "rule",
+    payload: { lesson: "Ask before deleting", destination: "rule", pairs: 1 },
+  })!;
+  return { s, c };
+}
+
+beforeEach(() => {
+  clearCards();
+  setExperiment("learning-cards", true);
+});
+
+describe("POST /api/learning-cards/[id]", () => {
+  it("applies a card", async () => {
+    const { s, c } = card();
+    const res = await post(String(c.id), {
+      action: "apply",
+      lesson: "Ask first",
+    });
+    expect(res.status).toBe(200);
+    expect(listRules(s.ws.id)[0].text).toBe("Ask first");
+  });
+
+  it("dismisses a card", async () => {
+    const { s, c } = card();
+    expect((await post(String(c.id), { action: "dismiss" })).status).toBe(200);
+    expect(listRules(s.ws.id)).toEqual([]);
+  });
+
+  it("is 409 while off or when already decided, 400 for a bad id or action", async () => {
+    const { c } = card();
+    setExperiment("learning-cards", false);
+    expect((await post(String(c.id), { action: "apply" })).status).toBe(409);
+    setExperiment("learning-cards", true);
+    expect((await post("abc", { action: "apply" })).status).toBe(400);
+    expect((await post(String(c.id), { action: "nope" })).status).toBe(400);
+    await post(String(c.id), { action: "dismiss" });
+    expect((await post(String(c.id), { action: "apply" })).status).toBe(409);
+  });
+});

package/app/api/learning-cards/[id]/route.ts

@@ -0,0 +1,36 @@
+import { NextRequest, NextResponse } from "next/server";
+import {
+  applyCard,
+  CardRefused,
+  dismissCard,
+} from "@/lib/learning-cards/apply";
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  const cardId = Number(id);
+  if (!Number.isInteger(cardId) || cardId < 1)
+    return NextResponse.json({ error: "Bad card id" }, { status: 400 });
+  const body = await request.json().catch(() => ({}));
+  const text = (v: unknown) => (typeof v === "string" ? v : undefined);
+  try {
+    if (body.action === "dismiss")
+      return NextResponse.json({ card: dismissCard(cardId) });
+    if (body.action !== "apply")
+      return NextResponse.json({ error: "Unknown action" }, { status: 400 });
+    const card = await applyCard(cardId, {
+      lesson: text(body.lesson),
+      brief: text(body.brief),
+      taskPrompt: text(body.taskPrompt),
+    });
+    return NextResponse.json({ card });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Failed";
+    return NextResponse.json(
+      { error: message },
+      { status: error instanceof CardRefused ? 409 : 400 }
+    );
+  }
+}

package/app/api/recipes/draft/route.ts

@@ -1,5 +1,6 @@
 import { NextRequest, NextResponse } from "next/server";
 import { recipeDraft } from "@/lib/recipes/draft";
+import { pendingRecipeDraft } from "@/lib/learning-cards";
 import { failed } from "@/lib/recipes/api";
 
 // A finished session as a recipe form: prefilled, with a drafted brief when
@@ -7,7 +8,11 @@ import { failed } from "@/lib/recipes/api";
 export async function POST(request: NextRequest) {
   try {
     const { sessionId } = await request.json();
-    return NextResponse.json(await recipeDraft(String(sessionId ?? "")));
+    const id = String(sessionId ?? "");
+    // A learning card may have drafted it already.
+    return NextResponse.json(
+      await recipeDraft(id, undefined, pendingRecipeDraft(id))
+    );
   } catch (error) {
     return failed(error);
   }

package/app/api/recipes/route.ts

@@ -5,6 +5,7 @@ import {
   recipeView,
   setTimer,
 } from "@/lib/recipes";
+import { acceptRecipeCardFor } from "@/lib/learning-cards/apply";
 import { failed } from "@/lib/recipes/api";
 
 export async function GET(request: NextRequest) {
@@ -27,6 +28,8 @@ export async function POST(request: NextRequest) {
       maxMinutes: body.maxMinutes,
       sourceSessionId: body.sourceSessionId,
     });
+    if (typeof body.sourceSessionId === "string")
+      acceptRecipeCardFor(body.sourceSessionId, recipe.id);
     if (body.timer) setTimer(recipe, body.timer);
     return NextResponse.json({ recipe: recipeView(recipe) }, { status: 201 });
   } catch (error) {

package/app/api/sessions/[id]/learning-cards/route.test.ts

@@ -0,0 +1,35 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { setExperiment } from "@/lib/experiments";
+import { clearCards, seedSession } from "@/lib/learning-cards/__fixtures__/db";
+import { insertCard } from "@/lib/learning-cards/store";
+import { GET } from "./route";
+
+const get = async (id: string) =>
+  (
+    await (
+      await GET(new Request("http://localhost/x"), {
+        params: Promise.resolve({ id }),
+      })
+    ).json()
+  ).cards;
+
+beforeEach(() => {
+  clearCards();
+  setExperiment("learning-cards", true);
+});
+
+describe("GET /api/sessions/[id]/learning-cards", () => {
+  it("lists pending cards, and none while off", async () => {
+    const s = seedSession();
+    insertCard({
+      sessionId: s.id,
+      workspaceId: s.ws.id,
+      kind: "lesson",
+      destination: "rule",
+      payload: { lesson: "x", destination: "rule", pairs: 1 },
+    });
+    expect(await get(s.id)).toHaveLength(1);
+    setExperiment("learning-cards", false);
+    expect(await get(s.id)).toEqual([]);
+  });
+});

package/app/api/sessions/[id]/learning-cards/route.ts

@@ -0,0 +1,10 @@
+import { NextResponse } from "next/server";
+import { cardsFor } from "@/lib/learning-cards";
+
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  return NextResponse.json({ cards: cardsFor(id) });
+}

package/components/Chat/ChatPanel.tsx

@@ -37,6 +37,7 @@ import { UndoDialog, UndoneBlock } from "./Undo";
 import { Composer } from "./Composer";
 import { Queue } from "./Queue";
 import { StaleChip } from "./StaleChip";
+import { LearningCardsHost } from "@/components/LearningCards/LearningCard";
 import { composerCompacts } from "@/lib/chat/stale";
 import { useFreshStartQuery } from "@/data/fresh-start";
 import { QuoteButton } from "./QuoteButton";
@@ -734,6 +735,7 @@ export function ChatPanel({
           asIs={asIs}
           onAsIs={setAsIs}
         />
+        <LearningCardsHost sessionId={sessionId} />
         <Composer
           draftKey={sessionId}
           suggestion={shownSuggestion}

package/components/LearningCards/LearningCard.test.ts

@@ -0,0 +1,156 @@
+import "@/components/Chat/composer/test-dom";
+import { act, createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { Card } from "@/lib/learning-cards/types";
+
+for (const key of ["Event", "CustomEvent", "FocusEvent", "HTMLButtonElement"])
+  Object.defineProperty(globalThis, key, {
+    value: (window as unknown as Record<string, unknown>)[key],
+    configurable: true,
+    writable: true,
+  });
+(
+  globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+const state = vi.hoisted(() => ({
+  cards: undefined as unknown,
+  apply: vi.fn(),
+  dismiss: vi.fn(),
+  saveSessionAs: vi.fn(),
+}));
+vi.mock("@/data/learning-cards", () => ({
+  useLearningCards: () => ({ data: state.cards }),
+  useApplyCard: () => ({
+    apply: state.apply,
+    dismiss: state.dismiss,
+    isPending: false,
+  }),
+}));
+vi.mock("@/stores/recipesUi", () => ({
+  recipesUiActions: { saveSessionAs: state.saveSessionAs },
+}));
+
+const { LearningCards, LearningCardsHost, destinationLabel } =
+  await import("./LearningCard");
+
+const base = {
+  session_id: "s1",
+  workspace_id: "w1",
+  status: "pending",
+  applied_ref: null,
+  shown_at: null,
+  decided_at: null,
+  created_at: 1,
+} as const;
+const cards = [
+  {
+    ...base,
+    id: 1,
+    kind: "recipe",
+    destination: null,
+    payload: { signals: [], brief: "Send the build", summary: "" },
+  },
+  {
+    ...base,
+    id: 2,
+    kind: "lesson",
+    destination: "claude_md",
+    payload: {
+      lesson: "Run the linter first",
+      destination: "claude_md",
+      projectName: "Web",
+      pairs: 1,
+    },
+  },
+] as unknown as Card[];
+
+let root: Root;
+let host: HTMLDivElement;
+beforeEach(() => {
+  for (const f of [state.apply, state.dismiss, state.saveSessionAs])
+    f.mockReset();
+  state.cards = cards;
+  host = document.createElement("div");
+  document.body.appendChild(host);
+  root = createRoot(host);
+});
+afterEach(() => {
+  act(() => root.unmount());
+  host.remove();
+});
+
+const click = (label: string, nth = 0) =>
+  act(() => {
+    [...host.querySelectorAll("button")]
+      .filter((b) => b.textContent === label)
+      [nth].dispatchEvent(new window.MouseEvent("click", { bubbles: true }));
+  });
+
+describe("LearningCardsHost", () => {
+  it("shows both rows, with the destination in plain words", () => {
+    act(() =>
+      root.render(createElement(LearningCardsHost, { sessionId: "s1" }))
+    );
+    expect(host.textContent).toContain("Save as recipe?");
+    expect(host.textContent).toContain("Keep this for next time?");
+    expect(host.textContent).toContain("CLAUDE.md in Web, through a PR");
+    expect(host.querySelector("input")?.value).toBe("Run the linter first");
+  });
+
+  it("saves the recipe, applies the lesson with its edit, and dismisses", () => {
+    act(() =>
+      root.render(createElement(LearningCardsHost, { sessionId: "s1" }))
+    );
+    click("Save");
+    expect(state.apply).toHaveBeenCalledWith(1, { brief: "Send the build" });
+    click("Apply");
+    expect(state.apply).toHaveBeenCalledWith(2, {
+      lesson: "Run the linter first",
+      taskPrompt: "",
+    });
+    click("Dismiss", 1);
+    expect(state.dismiss).toHaveBeenCalledWith(2);
+  });
+
+  it("Edit opens the recipe form for the session", () => {
+    act(() =>
+      root.render(createElement(LearningCardsHost, { sessionId: "s1" }))
+    );
+    click("Edit");
+    expect(state.saveSessionAs).toHaveBeenCalledWith("s1");
+  });
+
+  it("renders nothing when off (no data) or when there are no cards", () => {
+    state.cards = undefined;
+    act(() =>
+      root.render(createElement(LearningCardsHost, { sessionId: "s1" }))
+    );
+    expect(host.innerHTML).toBe("");
+    act(() =>
+      root.render(
+        createElement(LearningCards, {
+          cards: [],
+          onApply: vi.fn(),
+          onDismiss: vi.fn(),
+          onEditRecipe: vi.fn(),
+        })
+      )
+    );
+    expect(host.innerHTML).toBe("");
+  });
+});
+
+describe("destinationLabel", () => {
+  it("names each place", () => {
+    const p = { lesson: "x", pairs: 1 } as const;
+    expect(
+      destinationLabel({ ...p, destination: "recipe", recipeName: "Build" })
+    ).toBe("Recipe brief: Build");
+    expect(destinationLabel({ ...p, destination: "rule" })).toBe(
+      "Workspace rule"
+    );
+    expect(destinationLabel({ ...p, destination: "check" })).toContain("task");
+  });
+});

package/components/LearningCards/LearningCard.tsx

@@ -0,0 +1,210 @@
+"use client";
+
+import { useState } from "react";
+import { BookmarkPlus, ChefHat } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { recipesUiActions } from "@/stores/recipesUi";
+import { useApplyCard, useLearningCards } from "@/data/learning-cards";
+import type {
+  Card,
+  LessonPayload,
+  RecipePayload,
+} from "@/lib/learning-cards/types";
+
+export function destinationLabel(p: LessonPayload): string {
+  switch (p.destination) {
+    case "recipe":
+      return `Recipe brief: ${p.recipeName ?? "this recipe"}`;
+    case "claude_md":
+      return `CLAUDE.md in ${p.projectName ?? "the project"}, through a PR`;
+    case "check":
+      return "Start a task to build a check";
+    case "rule":
+      return "Workspace rule";
+  }
+}
+
+function RecipeRow({
+  card,
+  busy,
+  onSave,
+  onEdit,
+  onDismiss,
+}: {
+  card: Card;
+  busy: boolean;
+  onSave: (brief: string) => void;
+  onEdit: () => void;
+  onDismiss: () => void;
+}) {
+  const p = card.payload as RecipePayload;
+  const [open, setOpen] = useState(false);
+  return (
+    <div className="flex flex-col gap-1.5">
+      <div className="flex items-center gap-2 text-sm font-medium">
+        <ChefHat className="text-muted-foreground h-3.5 w-3.5" />
+        Save as recipe?
+      </div>
+      <button
+        type="button"
+        onClick={() => setOpen(!open)}
+        className={`text-muted-foreground text-left text-xs whitespace-pre-wrap ${open ? "" : "line-clamp-3"}`}
+      >
+        {p.brief}
+      </button>
+      <div className="flex flex-wrap gap-1">
+        <Button
+          size="sm"
+          className="h-11 md:h-8"
+          disabled={busy}
+          onClick={() => onSave(p.brief)}
+        >
+          Save
+        </Button>
+        <Button
+          size="sm"
+          variant="outline"
+          className="h-11 md:h-8"
+          disabled={busy}
+          onClick={onEdit}
+        >
+          Edit
+        </Button>
+        <Button
+          size="sm"
+          variant="ghost"
+          className="text-muted-foreground h-11 md:h-8"
+          disabled={busy}
+          onClick={onDismiss}
+        >
+          Dismiss
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+function LessonRow({
+  card,
+  busy,
+  onApply,
+  onDismiss,
+}: {
+  card: Card;
+  busy: boolean;
+  onApply: (edits: { lesson: string; taskPrompt?: string }) => void;
+  onDismiss: () => void;
+}) {
+  const p = card.payload as LessonPayload;
+  const [lesson, setLesson] = useState(p.lesson);
+  const [task, setTask] = useState(p.taskPrompt ?? "");
+  return (
+    <div className="flex flex-col gap-1.5">
+      <div className="flex items-center gap-2 text-sm font-medium">
+        <BookmarkPlus className="text-muted-foreground h-3.5 w-3.5" />
+        Keep this for next time?
+      </div>
+      {p.destination === "check" ? (
+        <textarea
+          aria-label="Task to start"
+          value={task}
+          onChange={(e) => setTask(e.target.value)}
+          rows={3}
+          className="bg-background border-border w-full rounded-lg border p-2 text-xs"
+        />
+      ) : (
+        <input
+          aria-label="Lesson"
+          value={lesson}
+          maxLength={200}
+          onChange={(e) => setLesson(e.target.value)}
+          className="bg-background border-border h-11 w-full rounded-lg border px-2 text-xs md:h-8"
+        />
+      )}
+      <p className="text-muted-foreground text-xs">{destinationLabel(p)}</p>
+      <div className="flex flex-wrap gap-1">
+        <Button
+          size="sm"
+          className="h-11 md:h-8"
+          disabled={
+            busy || !(p.destination === "check" ? task.trim() : lesson.trim())
+          }
+          onClick={() => onApply({ lesson, taskPrompt: task })}
+        >
+          Apply
+        </Button>
+        <Button
+          size="sm"
+          variant="ghost"
+          className="text-muted-foreground h-11 md:h-8"
+          disabled={busy}
+          onClick={onDismiss}
+        >
+          Dismiss
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+export function LearningCards({
+  cards,
+  busy = false,
+  onApply,
+  onDismiss,
+  onEditRecipe,
+}: {
+  cards: Card[];
+  busy?: boolean;
+  onApply: (
+    id: number,
+    edits: { lesson?: string; brief?: string; taskPrompt?: string }
+  ) => void;
+  onDismiss: (id: number) => void;
+  onEditRecipe: (sessionId: string) => void;
+}) {
+  if (!cards.length) return null;
+  return (
+    <div
+      role="region"
+      aria-label="Learning cards"
+      className="bg-card popover-surface mb-2 flex flex-col gap-3 rounded-2xl p-3"
+    >
+      {cards.map((c) =>
+        c.kind === "recipe" ? (
+          <RecipeRow
+            key={c.id}
+            card={c}
+            busy={busy}
+            onSave={(brief) => onApply(c.id, { brief })}
+            onEdit={() => onEditRecipe(c.session_id)}
+            onDismiss={() => onDismiss(c.id)}
+          />
+        ) : (
+          <LessonRow
+            key={c.id}
+            card={c}
+            busy={busy}
+            onApply={(edits) => onApply(c.id, edits)}
+            onDismiss={() => onDismiss(c.id)}
+          />
+        )
+      )}
+    </div>
+  );
+}
+
+// On a finished session, above the composer. Nothing while the experiment is off.
+export function LearningCardsHost({ sessionId }: { sessionId: string }) {
+  const { data } = useLearningCards(sessionId);
+  const { apply, dismiss, isPending } = useApplyCard(sessionId);
+  return (
+    <LearningCards
+      cards={data ?? []}
+      busy={isPending}
+      onApply={apply}
+      onDismiss={dismiss}
+      onEditRecipe={(id) => recipesUiActions.saveSessionAs(id)}
+    />
+  );
+}