@saadnvd1/agent-os 0.3.557 → 0.3.558

package/README.md

@@ -27,7 +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. [More](docs/decisions/2026-10-13-experiments.md)
+- **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/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)}
+    />
+  );
+}

package/data/learning-cards/index.ts

@@ -0,0 +1,79 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { toast } from "sonner";
+import type { Card } from "@/lib/learning-cards/types";
+import { useExperiment } from "../experiments";
+
+export type { Card };
+
+export interface CardEdits {
+  lesson?: string;
+  brief?: string;
+  taskPrompt?: string;
+}
+
+export const learningCardsKeys = {
+  session: (sessionId: string) => ["learning-cards", sessionId] as const,
+};
+
+async function json<T>(res: Response): Promise<T> {
+  const data = await res.json();
+  if (!res.ok) throw new Error(data.error || "Request failed");
+  return data;
+}
+
+// Pending cards of a session; nothing is asked while the experiment is off.
+export function useLearningCards(sessionId: string) {
+  const enabled = useExperiment("learning-cards");
+  return useQuery({
+    queryKey: learningCardsKeys.session(sessionId),
+    queryFn: async () =>
+      (
+        await json<{ cards: Card[] }>(
+          await fetch(
+            `/api/sessions/${encodeURIComponent(sessionId)}/learning-cards`
+          )
+        )
+      ).cards,
+    enabled,
+    staleTime: 10_000,
+    refetchInterval: 30_000,
+  });
+}
+
+function useDecide(sessionId: string) {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (
+      v: { id: number; action: "apply" | "dismiss" } & CardEdits
+    ) =>
+      json<{ card: Card }>(
+        await fetch(`/api/learning-cards/${encodeURIComponent(String(v.id))}`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(v),
+        })
+      ),
+    onSuccess: (_d, v) => {
+      queryClient.invalidateQueries({
+        queryKey: learningCardsKeys.session(sessionId),
+      });
+      // A saved recipe or a new rule shows up in their own lists.
+      if (v.action === "apply") {
+        queryClient.invalidateQueries({ queryKey: ["recipes"] });
+        queryClient.invalidateQueries({ queryKey: ["orchestrator"] });
+      }
+    },
+    onError: (error) =>
+      toast.error(error instanceof Error ? error.message : "Couldn't do that"),
+  });
+}
+
+export const useApplyCard = (sessionId: string) => {
+  const m = useDecide(sessionId);
+  return {
+    ...m,
+    apply: (id: number, edits: CardEdits = {}) =>
+      m.mutate({ id, action: "apply", ...edits }),
+    dismiss: (id: number) => m.mutate({ id, action: "dismiss" }),
+  };
+};

package/lib/chat/store.ts

@@ -180,6 +180,22 @@ export function itemsOfKind<K extends ChatItem["kind"]>(
   ).map((r) => JSON.parse(r.data));
 }
 
+// Several kinds in the order they happened.
+export function itemsOfKinds<K extends ChatItem["kind"]>(
+  sessionId: string,
+  kinds: K[]
+): Extract<ChatItem, { kind: K }>[] {
+  flushItems();
+  return (
+    db
+      .prepare(
+        `SELECT data FROM chat_items WHERE session_id = ?
+         AND kind IN (${kinds.map(() => "?").join(",")}) ORDER BY seq`
+      )
+      .all(sessionId, ...kinds) as { data: string }[]
+  ).map((r) => JSON.parse(r.data));
+}
+
 // A chat's background tasks still running, or ended after `since` (ms): what
 // the composer lists, read without parsing the rest of a long conversation.
 export function recentTasks(