@saadnvd1/agent-os 0.3.556 → 0.3.557

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. [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/components/Settings/ExperimentsSection.test.ts

@@ -0,0 +1,89 @@
+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";
+
+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 w = (calls: number) => ({
+  calls,
+  tokens: calls * 1000,
+  costUsd: calls * 0.01,
+  scripts: 0,
+  shown: 0,
+  accepted: 1,
+  dismissed: 1,
+  acceptRate: 0.5,
+});
+const state = vi.hoisted(() => ({ mutate: vi.fn() }));
+vi.mock("@/data/experiments", () => ({
+  useExperimentsQuery: () => ({
+    isPending: false,
+    isError: false,
+    data: {
+      locked: false,
+      experiments: [
+        {
+          id: "learning-cards",
+          name: "Learning cards",
+          description: "Suggest things when a session ends.",
+          area: "sessions",
+          status: "experimental",
+          suggests: true,
+          on: false,
+          usage: { today: w(1), d7: w(2), d30: w(3) },
+        },
+      ],
+    },
+  }),
+  useSetExperiment: () => ({ mutate: state.mutate }),
+  useExperimentDetailQuery: () => ({ isPending: true }),
+}));
+
+const { ExperimentsSection } = await import("./ExperimentsSection");
+
+let root: Root;
+let host: HTMLDivElement;
+beforeEach(() => {
+  state.mutate.mockReset();
+  host = document.createElement("div");
+  document.body.appendChild(host);
+  root = createRoot(host);
+});
+afterEach(() => {
+  act(() => root.unmount());
+  host.remove();
+});
+
+describe("ExperimentsSection", () => {
+  it("lists each experiment, off, with its usage", () => {
+    act(() => root.render(createElement(ExperimentsSection)));
+    expect(host.textContent).toContain("Learning cards");
+    expect(host.textContent).toContain("Suggest things when a session ends.");
+    expect(host.textContent).toContain("50% (1/2)");
+    expect(
+      host.querySelector('[role="switch"]')?.getAttribute("aria-checked")
+    ).toBe("false");
+  });
+
+  it("turns one on from its toggle", () => {
+    act(() => root.render(createElement(ExperimentsSection)));
+    act(() => {
+      host
+        .querySelector('[role="switch"]')
+        ?.dispatchEvent(new window.MouseEvent("click", { bubbles: true }));
+    });
+    expect(state.mutate).toHaveBeenCalledWith(
+      { id: "learning-cards", on: true },
+      expect.any(Object)
+    );
+  });
+});

package/components/Settings/ExperimentsSection.tsx

@@ -0,0 +1,225 @@
+"use client";
+
+import { useState } from "react";
+import { toast } from "sonner";
+import { ArrowLeft } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { SettingToggle } from "@/components/Settings/SettingToggle";
+import { formatTokens } from "@/lib/chat/context";
+import {
+  useExperimentDetailQuery,
+  useExperimentsQuery,
+  useSetExperiment,
+  type ExperimentView,
+} from "@/data/experiments";
+
+const usd = (n: number) => `$${n.toFixed(2)}`;
+const pct = (n: number | null) =>
+  n === null ? "-" : `${Math.round(n * 100)}%`;
+
+const WINDOWS = [
+  ["today", "Today"],
+  ["d7", "7 days"],
+  ["d30", "30 days"],
+] as const;
+
+function Usage({ e }: { e: ExperimentView }) {
+  return (
+    <table className="w-full text-xs tabular-nums">
+      <thead className="text-muted-foreground">
+        <tr>
+          <th className="py-1 text-left font-normal" />
+          <th className="py-1 text-right font-normal">Calls</th>
+          <th className="py-1 text-right font-normal">Tokens</th>
+          <th className="py-1 text-right font-normal">Cost</th>
+          {e.suggests && (
+            <th className="py-1 text-right font-normal">Accepted</th>
+          )}
+        </tr>
+      </thead>
+      <tbody>
+        {WINDOWS.map(([key, label]) => {
+          const w = e.usage[key];
+          return (
+            <tr key={key} className="border-border border-t">
+              <td className="py-1">{label}</td>
+              <td className="py-1 text-right">{w.calls}</td>
+              <td className="py-1 text-right">{formatTokens(w.tokens)}</td>
+              <td className="py-1 text-right">{usd(w.costUsd)}</td>
+              {e.suggests && (
+                <td className="py-1 text-right">
+                  {pct(w.acceptRate)}
+                  {w.accepted + w.dismissed > 0 &&
+                    ` (${w.accepted}/${w.accepted + w.dismissed})`}
+                </td>
+              )}
+            </tr>
+          );
+        })}
+      </tbody>
+    </table>
+  );
+}
+
+function Detail({ id, onBack }: { id: string; onBack: () => void }) {
+  const { data, isPending, isError, error } = useExperimentDetailQuery(id);
+  return (
+    <div className="space-y-4">
+      <Button
+        variant="ghost"
+        size="sm"
+        onClick={onBack}
+        className="min-h-11 md:min-h-0"
+      >
+        <ArrowLeft className="h-4 w-4" /> Experiments
+      </Button>
+      {isPending && (
+        <div className="bg-muted/40 h-24 animate-pulse rounded-lg" />
+      )}
+      {isError && <p className="text-destructive text-sm">{error.message}</p>}
+      {data && (
+        <>
+          <div>
+            <h3 className="text-sm font-medium">{data.name}</h3>
+            <p className="text-muted-foreground text-xs">{data.description}</p>
+          </div>
+          <Usage e={data} />
+          <Breakdowns title="By trigger" rows={data.detail.byTrigger} />
+          <Breakdowns title="By model" rows={data.detail.byModel} />
+          <section>
+            <h4 className="text-muted-foreground mb-1 text-xs">Last 30 days</h4>
+            <table className="w-full text-xs tabular-nums">
+              <tbody>
+                {data.detail.days
+                  .filter((d) => d.calls || d.accepted || d.dismissed)
+                  .reverse()
+                  .map((d) => (
+                    <tr key={d.day} className="border-border border-t">
+                      <td className="py-1">{d.day}</td>
+                      <td className="py-1 text-right">{d.calls} calls</td>
+                      <td className="py-1 text-right">
+                        {formatTokens(d.tokens)}
+                      </td>
+                      <td className="py-1 text-right">{usd(d.costUsd)}</td>
+                      <td className="py-1 text-right">
+                        {d.accepted}/{d.accepted + d.dismissed}
+                      </td>
+                    </tr>
+                  ))}
+                <tr className="border-border border-t font-medium">
+                  <td className="py-1">Total</td>
+                  <td className="py-1 text-right">
+                    {data.detail.days.reduce((t, d) => t + d.calls, 0)} calls
+                  </td>
+                  <td className="py-1 text-right">
+                    {formatTokens(
+                      data.detail.days.reduce((t, d) => t + d.tokens, 0)
+                    )}
+                  </td>
+                  <td className="py-1 text-right">
+                    {usd(data.detail.days.reduce((t, d) => t + d.costUsd, 0))}
+                  </td>
+                  <td />
+                </tr>
+              </tbody>
+            </table>
+          </section>
+          {data.detail.recent.length > 0 && (
+            <section>
+              <h4 className="text-muted-foreground mb-1 text-xs">Recent</h4>
+              <ul className="space-y-1 text-xs">
+                {data.detail.recent.map((r, i) => (
+                  <li key={i} className="flex justify-between gap-3">
+                    <span className="min-w-0 truncate">
+                      {new Date(r.at).toLocaleString()} · {r.event} ·{" "}
+                      {r.trigger}
+                      {r.detail ? ` · ${r.detail}` : ""}
+                    </span>
+                    <span className="text-muted-foreground tabular-nums">
+                      {r.tokens ? formatTokens(r.tokens) : ""}
+                    </span>
+                  </li>
+                ))}
+              </ul>
+            </section>
+          )}
+        </>
+      )}
+    </div>
+  );
+}
+
+function Breakdowns({
+  title,
+  rows,
+}: {
+  title: string;
+  rows: { key: string; calls: number; tokens: number; costUsd: number }[];
+}) {
+  if (!rows.length) return null;
+  return (
+    <section>
+      <h4 className="text-muted-foreground mb-1 text-xs">{title}</h4>
+      <table className="w-full text-xs tabular-nums">
+        <tbody>
+          {rows.map((r) => (
+            <tr key={r.key} className="border-border border-t">
+              <td className="py-1">{r.key}</td>
+              <td className="py-1 text-right">{r.calls} calls</td>
+              <td className="py-1 text-right">{formatTokens(r.tokens)}</td>
+              <td className="py-1 text-right">{usd(r.costUsd)}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </section>
+  );
+}
+
+export function ExperimentsSection() {
+  const { data, isPending, isError, error } = useExperimentsQuery();
+  const set = useSetExperiment();
+  const [open, setOpen] = useState<string | null>(null);
+
+  if (open) return <Detail id={open} onBack={() => setOpen(null)} />;
+  if (isPending)
+    return <div className="bg-muted/40 h-16 animate-pulse rounded-lg" />;
+  if (isError)
+    return <p className="text-destructive text-sm">{error.message}</p>;
+
+  return (
+    <div className="space-y-5">
+      <p className="text-muted-foreground text-sm">
+        Features still being tried. Each is off until you turn it on, does no
+        work while off, and shows what it costs here.
+      </p>
+      {data.experiments.map((e) => (
+        <div key={e.id} className="space-y-2">
+          <SettingToggle
+            title={`${e.name} · ${e.status === "beta" ? "Beta" : "Experimental"}`}
+            detail={e.description}
+            checked={e.on}
+            locked={data.locked}
+            onChange={(on) =>
+              set.mutate(
+                { id: e.id, on },
+                { onError: (err) => toast.error(err.message) }
+              )
+            }
+          />
+          <div className="px-3">
+            <Usage e={e} />
+            <Button
+              variant="link"
+              size="sm"
+              className="min-h-11 px-0 md:min-h-0"
+              onClick={() => setOpen(e.id)}
+            >
+              Details
+            </Button>
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}

package/components/Settings/SettingsDialog.test.ts

@@ -47,6 +47,9 @@ vi.mock("@/components/Audits/AuditsPanel", () => ({
 vi.mock("@/components/Updates/UpdatesSection", () => ({
   UpdatesSection: stub("updates"),
 }));
+vi.mock("./ExperimentsSection", () => ({
+  ExperimentsSection: stub("experiments"),
+}));
 vi.mock("./NotificationsSection", () => ({
   NotificationsSection: stub("notifications"),
 }));

package/components/Settings/SettingsDialog.tsx

@@ -14,6 +14,7 @@ import {
   LayoutGrid,
   ListChecks,
   ShieldOff,
+  FlaskConical,
   RefreshCw,
   Smartphone,
   X,
@@ -33,6 +34,7 @@ import { GlobalMergeSection } from "@/components/Merge/GlobalMergeSection";
 import { ModelsSection } from "@/components/Models/ModelsSection";
 import { SchedulesPanel } from "@/components/Schedules";
 import { UpdatesSection } from "@/components/Updates/UpdatesSection";
+import { ExperimentsSection } from "./ExperimentsSection";
 import { WorkspaceSettings } from "@/components/Workspaces";
 import { useSettingsUrl } from "@/hooks/useSettingsUrl";
 import { SETTINGS_SECTIONS, type SettingsSection } from "@/lib/settings-url";
@@ -106,6 +108,11 @@ export const SECTION_INFO: Record<
     hint: "Version, check for updates, the update banner",
     icon: RefreshCw,
   },
+  experiments: {
+    label: "Experiments",
+    hint: "Try features that aren't finished, and see what they cost",
+    icon: FlaskConical,
+  },
 };
 
 function SectionBody({
@@ -138,6 +145,8 @@ function SectionBody({
       return <SetupSection />;
     case "updates":
       return <UpdatesSection />;
+    case "experiments":
+      return <ExperimentsSection />;
   }
 }
 

package/components/Settings/commands.ts

@@ -3,6 +3,7 @@ import {
   ClipboardList,
   Clock,
   Cpu,
+  FlaskConical,
   GitMerge,
   LayoutGrid,
   RefreshCw,
@@ -111,5 +112,13 @@ export function settingsCommands(workspaceId: string | null): PaletteCommand[] {
       icon: RefreshCw,
       run: () => settingsUiActions.open("updates"),
     },
+    {
+      id: "app.experiments",
+      title: "Experiments",
+      group,
+      keywords: ["experiment", "labs", "beta", "feature", "try"],
+      icon: FlaskConical,
+      run: () => settingsUiActions.open("experiments"),
+    },
   ];
 }

package/components/Settings/entry-points.test.ts

@@ -28,6 +28,7 @@ describe("⌘K entry points", () => {
     ["app.schedules", "schedules"],
     ["app.audits", "audits"],
     ["app.updates", "updates"],
+    ["app.experiments", "experiments"],
   ] as const)("%s opens Settings at %s", (id, section) => {
     run(id);
     expect(settingsUi.open).toBe(true);

package/data/experiments/index.ts

@@ -0,0 +1,67 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import type { ExperimentView } from "@/lib/experiments/view";
+import type { UsageDetail } from "@/lib/experiments/meter";
+import type { ExperimentId } from "@/lib/experiments/registry";
+
+export type { ExperimentView, UsageDetail };
+
+export interface ExperimentsList {
+  locked: boolean;
+  experiments: ExperimentView[];
+}
+
+export interface ExperimentDetail extends ExperimentView {
+  locked: boolean;
+  detail: UsageDetail;
+}
+
+export const experimentsKeys = {
+  all: ["experiments"] as const,
+  detail: (id: string) => ["experiments", id] 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;
+}
+
+export function useExperimentsQuery() {
+  return useQuery({
+    queryKey: experimentsKeys.all,
+    queryFn: async () => json<ExperimentsList>(await fetch("/api/experiments")),
+    staleTime: 10_000,
+  });
+}
+
+export function useExperimentDetailQuery(id: string | null) {
+  return useQuery({
+    queryKey: experimentsKeys.detail(id ?? ""),
+    queryFn: async () =>
+      json<ExperimentDetail>(await fetch(`/api/experiments/${id}`)),
+    enabled: !!id,
+    staleTime: 10_000,
+  });
+}
+
+// The client's one check: false until the list has loaded.
+export function useExperiment(id: ExperimentId): boolean {
+  const { data } = useExperimentsQuery();
+  return !!data?.experiments.find((e) => e.id === id)?.on;
+}
+
+export function useSetExperiment() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async ({ id, on }: { id: string; on: boolean }) =>
+      json<ExperimentView>(
+        await fetch(`/api/experiments/${id}`, {
+          method: "PUT",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ on }),
+        })
+      ),
+    onSuccess: () =>
+      queryClient.invalidateQueries({ queryKey: experimentsKeys.all }),
+  });
+}

package/lib/db/migrations.ts

@@ -2028,6 +2028,39 @@ const migrations: Migration[] = [
       `);
     },
   },
+  {
+    id: 85,
+    name: "experiment_usage",
+    up: (db) => {
+      // What each experiment did: model calls with their cost, and the
+      // non-model work (scripts run, suggestions shown and decided).
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS experiment_usage (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          experiment_id TEXT NOT NULL,
+          event TEXT NOT NULL,
+          trigger TEXT NOT NULL,
+          session_id TEXT,
+          workspace_id TEXT,
+          model TEXT,
+          provider TEXT,
+          input_tokens INTEGER NOT NULL DEFAULT 0,
+          cache_write_tokens INTEGER NOT NULL DEFAULT 0,
+          cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+          output_tokens INTEGER NOT NULL DEFAULT 0,
+          cost_usd REAL NOT NULL DEFAULT 0,
+          duration_ms INTEGER,
+          ok INTEGER NOT NULL DEFAULT 1,
+          detail TEXT,
+          at INTEGER NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_experiment_usage_exp_at
+          ON experiment_usage(experiment_id, at);
+        CREATE INDEX IF NOT EXISTS idx_experiment_usage_session
+          ON experiment_usage(session_id, experiment_id, event);
+      `);
+    },
+  },
 ];
 
 // `upTo`: stop after this id (tests that start from an older database).

package/lib/done/index.ts

@@ -32,6 +32,7 @@ import { doneOnPeer, peerSessionLink } from "../hosts/peer-actions";
 import { hostLink } from "../hosts/remote-api";
 import { doneHeldTask } from "../tasks/held-remote";
 import { captureMergedTask } from "../session-logs";
+import { sessionEnded } from "../experiments/hooks";
 import { pushMerged } from "../notify/push/events";
 
 export interface DoneOptions {
@@ -112,6 +113,7 @@ function mark(s: Session, status: "merged" | "done", pr: TaskPR | null) {
       : `UPDATE sessions SET task_status = 'done' WHERE id = ?`
   ).run(s.id);
   syncTaskCardInBackground(s, status, pr);
+  void sessionEnded(s.id, status);
   if (status === "merged") {
     pushMerged(s.id);
     void captureMergedTask(s.id, { head: pr?.head });

package/lib/experiments/hooks.ts

@@ -0,0 +1,31 @@
+import { experimentOn } from ".";
+import { EXPERIMENTS, type ExperimentId } from "./registry";
+
+export type EndHow = "done" | "merged" | "recipe-settled";
+export type EndHook = (sessionId: string, how: EndHow) => Promise<void> | void;
+
+// What each experiment does when a session ends. An experiment adds itself
+// here; one that is off is never called.
+export const END_HOOKS: Partial<Record<ExperimentId, EndHook>> = {};
+
+// A merge is seen again on every poll; each session is handed on once.
+const seen = new Set<string>();
+export const resetEndHooks = () => seen.clear();
+
+// Called where sessions end. Never makes the caller wait or fail.
+export function sessionEnded(sessionId: string, how: EndHow): Promise<void> {
+  if (seen.has(sessionId)) return Promise.resolve();
+  seen.add(sessionId);
+  return (async () => {
+    await new Promise<void>((r) => setImmediate(r));
+    for (const { id } of EXPERIMENTS) {
+      const hook = END_HOOKS[id];
+      if (!hook || !experimentOn(id)) continue;
+      try {
+        await hook(sessionId, how);
+      } catch (error) {
+        console.error(`[experiments] ${id} on ${sessionId}:`, error);
+      }
+    }
+  })();
+}

package/lib/experiments/index.ts

@@ -0,0 +1,19 @@
+import { getSetting, putSetting } from "../settings-store";
+import { type ExperimentId } from "./registry";
+
+type Env = Record<string, string | undefined>;
+
+const key = (id: ExperimentId) => `experiments.${id}`;
+
+// AGENTOS_EXPERIMENTS=off pins every experiment off, like the update banner.
+export const experimentsLocked = (env: Env = process.env) =>
+  env.AGENTOS_EXPERIMENTS === "off";
+
+// The one check, on the server. Off by default: no row means off.
+export function experimentOn(id: ExperimentId, env: Env = process.env) {
+  if (experimentsLocked(env)) return false;
+  return getSetting(key(id)) === "1";
+}
+
+export const setExperiment = (id: ExperimentId, on: boolean) =>
+  putSetting(key(id), on ? "1" : null);

package/lib/experiments/meter.ts

@@ -0,0 +1,327 @@
+/**
+ * What experiments cost and whether they earn it. Every model call an
+ * experiment makes goes through experimentRun, which records it here and in
+ * the usage ledger; non-model work (scripts, suggestions shown, accepted,
+ * dismissed) is counted with countEvent.
+ */
+
+import { db } from "../db";
+import {
+  runClaude,
+  type ClaudeRun,
+  type ClaudeRunner,
+} from "../orchestrator/claude-cli";
+import type { RunUsage } from "../usage/check-runs";
+import { recordLooseCall } from "../usage/calls";
+import { dayKey } from "../usage/aggregate";
+import { experimentOn } from ".";
+import { getExperiment, type ExperimentId } from "./registry";
+
+export type ExperimentEvent =
+  | "model"
+  | "script"
+  | "shown"
+  | "accepted"
+  | "dismissed"
+  | "applied"
+  | "error";
+
+export interface MeterContext {
+  trigger: string;
+  sessionId?: string | null;
+  workspaceId?: string | null;
+  detail?: string | null;
+}
+
+const clip = (s: string | null | undefined, n = 120) =>
+  s ? s.slice(0, n) : null;
+
+function insert(
+  id: ExperimentId,
+  event: ExperimentEvent,
+  ctx: MeterContext,
+  u?: RunUsage,
+  ok = true,
+  at = Date.now()
+): number {
+  const info = db
+    .prepare(
+      `INSERT INTO experiment_usage (experiment_id, event, trigger, session_id, workspace_id, model, provider,
+         input_tokens, cache_write_tokens, cache_read_tokens, output_tokens, cost_usd, duration_ms, ok, detail, at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    )
+    .run(
+      id,
+      event,
+      ctx.trigger,
+      ctx.sessionId ?? null,
+      ctx.workspaceId ?? null,
+      u?.model ?? null,
+      u ? (u.provider ?? "anthropic") : null,
+      u?.inputTokens ?? 0,
+      u?.cacheWriteTokens ?? 0,
+      u?.cacheReadTokens ?? 0,
+      u?.outputTokens ?? 0,
+      u?.costUsd ?? 0,
+      u?.durationMs ?? null,
+      ok ? 1 : 0,
+      clip(ctx.detail),
+      at
+    );
+  return Number(info.lastInsertRowid);
+}
+
+function recordModel(id: ExperimentId, ctx: MeterContext, u: RunUsage) {
+  try {
+    const rowId = insert(id, "model", ctx, u);
+    recordLooseCall({
+      callKey: `experiment:${rowId}`,
+      at: Date.now(),
+      sessionId: ctx.sessionId ?? null,
+      taskId: null,
+      workspaceId: ctx.workspaceId ?? null,
+      projectId: null,
+      sessionName: getExperiment(id).name,
+      role: `experiment:${id}`,
+      kind: "helper",
+      agentType: null,
+      model: u.model,
+      provider: u.provider ?? "anthropic",
+      input: u.inputTokens,
+      cacheRead: u.cacheReadTokens,
+      cacheWrite5m: u.cacheWriteTokens,
+      cacheWrite1h: 0,
+      output: u.outputTokens,
+      source: "helper",
+    });
+  } catch (e) {
+    console.error(`[experiments] recording ${id}:`, e);
+  }
+}
+
+/**
+ * The only way an experiment calls a model. Returns null, having started
+ * nothing, when the experiment is off. A failed run is recorded too (its
+ * usage, or an error row when it reported none) and then thrown.
+ */
+export async function experimentRun(
+  id: ExperimentId,
+  ctx: MeterContext,
+  run: ClaudeRun,
+  runner: ClaudeRunner = runClaude
+): Promise<unknown | null> {
+  if (!experimentOn(id)) return null;
+  let usage: RunUsage | null = null;
+  try {
+    const out = await runner({
+      ...run,
+      onUsage: (u) => {
+        usage = u;
+        run.onUsage?.(u);
+      },
+    });
+    if (usage) recordModel(id, ctx, usage);
+    return out;
+  } catch (error) {
+    try {
+      if (usage) recordModel(id, ctx, usage);
+      insert(
+        id,
+        "error",
+        {
+          ...ctx,
+          detail: error instanceof Error ? error.message : String(error),
+        },
+        undefined,
+        false
+      );
+    } catch (e) {
+      console.error(`[experiments] recording ${id}:`, e);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Non-model work. Does nothing when the experiment is off, unless `force`:
+ * a person deciding on a card that is already on screen is still counted.
+ */
+export function countEvent(
+  id: ExperimentId,
+  event: Exclude<ExperimentEvent, "model">,
+  ctx: MeterContext,
+  force = false
+): void {
+  if (!force && !experimentOn(id)) return;
+  try {
+    insert(id, event, ctx);
+  } catch (e) {
+    console.error(`[experiments] counting ${id}:`, e);
+  }
+}
+
+// Whether this session already has this event, so a hook runs once.
+export function hasEvent(
+  id: ExperimentId,
+  sessionId: string,
+  event: ExperimentEvent,
+  trigger?: string
+): boolean {
+  return !!db
+    .prepare(
+      `SELECT 1 FROM experiment_usage WHERE experiment_id = ? AND session_id = ? AND event = ?
+         AND (? IS NULL OR trigger = ?) LIMIT 1`
+    )
+    .get(id, sessionId, event, trigger ?? null, trigger ?? null);
+}
+
+export interface WindowTotals {
+  calls: number;
+  tokens: number;
+  costUsd: number;
+  scripts: number;
+  shown: number;
+  accepted: number;
+  dismissed: number;
+  // accepted / (accepted + dismissed); null with no decisions yet.
+  acceptRate: number | null;
+}
+
+export interface UsageSummary {
+  today: WindowTotals;
+  d7: WindowTotals;
+  d30: WindowTotals;
+}
+
+const DAY = 86_400_000;
+
+export function startOfDay(now: number): number {
+  const d = new Date(now);
+  d.setHours(0, 0, 0, 0);
+  return d.getTime();
+}
+
+function windowTotals(id: ExperimentId, since: number): WindowTotals {
+  const r = db
+    .prepare(
+      `SELECT
+         coalesce(sum(event = 'model'), 0) AS calls,
+         coalesce(sum(input_tokens + cache_write_tokens + cache_read_tokens + output_tokens), 0) AS tokens,
+         coalesce(sum(cost_usd), 0) AS costUsd,
+         coalesce(sum(event = 'script'), 0) AS scripts,
+         coalesce(sum(event = 'shown'), 0) AS shown,
+         coalesce(sum(event = 'accepted'), 0) AS accepted,
+         coalesce(sum(event = 'dismissed'), 0) AS dismissed
+       FROM experiment_usage WHERE experiment_id = ? AND at >= ?`
+    )
+    .get(id, since) as Omit<WindowTotals, "acceptRate">;
+  const decided = r.accepted + r.dismissed;
+  return { ...r, acceptRate: decided ? r.accepted / decided : null };
+}
+
+export function usageSummary(id: ExperimentId, now = Date.now()): UsageSummary {
+  const today = startOfDay(now);
+  return {
+    today: windowTotals(id, today),
+    d7: windowTotals(id, today - 6 * DAY),
+    d30: windowTotals(id, today - 29 * DAY),
+  };
+}
+
+export interface DayRow {
+  day: string;
+  calls: number;
+  tokens: number;
+  costUsd: number;
+  accepted: number;
+  dismissed: number;
+}
+
+export interface Breakdown {
+  key: string;
+  calls: number;
+  tokens: number;
+  costUsd: number;
+}
+
+export interface RecentEvent {
+  at: number;
+  event: string;
+  trigger: string;
+  model: string | null;
+  tokens: number;
+  costUsd: number;
+  ok: boolean;
+  detail: string | null;
+}
+
+export interface UsageDetail {
+  days: DayRow[];
+  byTrigger: Breakdown[];
+  byModel: Breakdown[];
+  recent: RecentEvent[];
+}
+
+export function usageDetail(id: ExperimentId, now = Date.now()): UsageDetail {
+  const since = startOfDay(now) - 29 * DAY;
+  const rows = db
+    .prepare(
+      `SELECT at, event, trigger, model, cost_usd AS costUsd,
+         input_tokens + cache_write_tokens + cache_read_tokens + output_tokens AS tokens
+       FROM experiment_usage WHERE experiment_id = ? AND at >= ?`
+    )
+    .all(id, since) as {
+    at: number;
+    event: string;
+    trigger: string;
+    model: string | null;
+    costUsd: number;
+    tokens: number;
+  }[];
+  const days = new Map<string, DayRow>();
+  for (let i = 29; i >= 0; i--) {
+    const day = dayKey(startOfDay(now) - i * DAY);
+    days.set(day, {
+      day,
+      calls: 0,
+      tokens: 0,
+      costUsd: 0,
+      accepted: 0,
+      dismissed: 0,
+    });
+  }
+  const trig = new Map<string, Breakdown>();
+  const mod = new Map<string, Breakdown>();
+  const add = (m: Map<string, Breakdown>, key: string, r: (typeof rows)[0]) => {
+    const b = m.get(key) ?? { key, calls: 0, tokens: 0, costUsd: 0 };
+    b.calls += r.event === "model" ? 1 : 0;
+    b.tokens += r.tokens;
+    b.costUsd += r.costUsd;
+    m.set(key, b);
+  };
+  for (const r of rows) {
+    const d = days.get(dayKey(r.at));
+    if (d) {
+      d.calls += r.event === "model" ? 1 : 0;
+      d.tokens += r.tokens;
+      d.costUsd += r.costUsd;
+      d.accepted += r.event === "accepted" ? 1 : 0;
+      d.dismissed += r.event === "dismissed" ? 1 : 0;
+    }
+    add(trig, r.trigger, r);
+    if (r.event === "model") add(mod, r.model ?? "unrecorded", r);
+  }
+  const recent = db
+    .prepare(
+      `SELECT at, event, trigger, model, input_tokens + cache_write_tokens + cache_read_tokens + output_tokens AS tokens,
+         cost_usd AS costUsd, ok, detail
+       FROM experiment_usage WHERE experiment_id = ? ORDER BY at DESC, id DESC LIMIT 50`
+    )
+    .all(id) as (Omit<RecentEvent, "ok"> & { ok: number })[];
+  return {
+    days: [...days.values()],
+    byTrigger: [...trig.values()],
+    byModel: [...mod.values()],
+    recent: recent.map((r) => ({ ...r, ok: !!r.ok })),
+  };
+}

package/lib/experiments/registry.ts

@@ -0,0 +1,37 @@
+// Every experiment AgentOS knows about. All are off until someone turns them
+// on. To add one: an entry here, `experimentOn(id)` where it does its work,
+// and `experimentRun(id, ...)` for any model call it makes.
+
+export type ExperimentStatus = "experimental" | "beta";
+
+export interface Experiment {
+  // Kebab-case and stable: it names the setting and keys the usage rows.
+  id: string;
+  name: string;
+  description: string;
+  // Who owns it: "sessions", "tasks", "orchestrator"...
+  area: string;
+  status: ExperimentStatus;
+  // It shows suggestions, so an accept rate means something for it.
+  suggests?: boolean;
+}
+
+export const EXPERIMENTS = [
+  {
+    id: "learning-cards",
+    name: "Learning cards",
+    description:
+      "When a session ends, suggest saving it as a recipe or keeping a lesson, in the one place it belongs.",
+    area: "sessions",
+    status: "experimental",
+    suggests: true,
+  },
+] as const satisfies readonly Experiment[];
+
+export type ExperimentId = (typeof EXPERIMENTS)[number]["id"];
+
+export const isExperimentId = (v: unknown): v is ExperimentId =>
+  EXPERIMENTS.some((e) => e.id === v);
+
+export const getExperiment = (id: ExperimentId): Experiment =>
+  EXPERIMENTS.find((e) => e.id === id)!;

package/lib/experiments/view.ts

@@ -0,0 +1,19 @@
+import { experimentOn, experimentsLocked } from ".";
+import { EXPERIMENTS, type Experiment, type ExperimentId } from "./registry";
+import { usageSummary, type UsageSummary } from "./meter";
+
+export interface ExperimentView extends Experiment {
+  on: boolean;
+  usage: UsageSummary;
+}
+
+export const experimentView = (id: ExperimentId): ExperimentView => ({
+  ...EXPERIMENTS.find((e) => e.id === id)!,
+  on: experimentOn(id),
+  usage: usageSummary(id),
+});
+
+export const experimentsView = () => ({
+  locked: experimentsLocked(),
+  experiments: EXPERIMENTS.map((e) => experimentView(e.id)),
+});

package/lib/recipes/settle.ts

@@ -11,6 +11,7 @@ import { blockedReason } from "../tasks/state";
 import { runClaude, type ClaudeRunner } from "../orchestrator/claude-cli";
 import { releasePieces } from "../plans/release";
 import { queueEvent } from "../orchestrator/events";
+import { sessionEnded } from "../experiments/hooks";
 import { untrusted } from "../orchestrator/untrusted";
 import {
   cleanOutputs,
@@ -172,8 +173,10 @@ function finish(
       run.id
     ).changes;
   idleSince.delete(run.id);
-  if (changed)
+  if (changed) {
     tell(run, status, summary, result, session?.pr_number ?? run.pr_number);
+    if (run.session_id) void sessionEnded(run.session_id, "recipe-settled");
+  }
   return changed === 1;
 }
 

package/lib/settings-store.ts

@@ -0,0 +1,22 @@
+import { getDb } from "@/lib/db";
+
+// The settings table: a key and a string, shared by every feature.
+export function getSetting(key: string): string | null {
+  const row = getDb()
+    .prepare(`SELECT value FROM settings WHERE key = ?`)
+    .get(key) as { value: string } | undefined;
+  return row?.value ?? null;
+}
+
+export function putSetting(key: string, value: string | null): void {
+  if (value === null) {
+    getDb().prepare(`DELETE FROM settings WHERE key = ?`).run(key);
+    return;
+  }
+  getDb()
+    .prepare(
+      `INSERT INTO settings (key, value) VALUES (?, ?)
+       ON CONFLICT(key) DO UPDATE SET value = excluded.value`
+    )
+    .run(key, value);
+}

package/lib/settings-url.ts

@@ -16,6 +16,7 @@ export const SETTINGS_SECTIONS = [
   "audits",
   "setup",
   "updates",
+  "experiments",
 ] as const;
 
 export type SettingsSection = (typeof SETTINGS_SECTIONS)[number];

package/lib/tasks/finish.ts

@@ -26,6 +26,7 @@ import { canSignOff } from "./state";
 import { forgetPR, getTaskSession, prFor, projectPathFor } from "./session";
 import { dropSessionDatabase } from "../project-config/database";
 import { captureMergedTask } from "../session-logs";
+import { sessionEnded } from "../experiments/hooks";
 
 // Never deleted, whatever a setting says.
 export const PROTECTED_BRANCHES = new Set(["main", "master", "HEAD"]);
@@ -163,6 +164,7 @@ export async function signOffTask(
   pushMerged(id);
   // Reads the plan file now: cleanup below removes the worktree.
   void captureMergedTask(id, { head: opts.head ?? pr!.head ?? null });
+  void sessionEnded(id, "merged");
   const head = opts.head ?? pr!.head;
   resolveMergedTaskAsks(
     id,

package/lib/tasks/session.ts

@@ -16,6 +16,7 @@ import { findPRStrict } from "./gh";
 import { currentBranch, git } from "../git-exec";
 import { lookupPR } from "./pr-poll";
 import { captureMergedTask } from "../session-logs";
+import { sessionEnded } from "../experiments/hooks";
 import { getOrchestrator } from "../orchestrator/home";
 import {
   pushCiFailed,
@@ -211,6 +212,7 @@ export async function prFor(
     if (pr.state === "MERGED") {
       if (session.pr_status !== "merged") pushMerged(session.id);
       void captureMergedTask(session.id, { head: pr.head });
+      void sessionEnded(session.id, "merged");
     }
   }
   // Only an answer just read from GitHub: a cached one may predate a

package/lib/updates/settings.ts

@@ -1,4 +1,4 @@
-import { getDb } from "@/lib/db";
+import { getSetting, putSetting } from "../settings-store";
 
 // Whether this server shows the update banner, and the checks behind it.
 // AGENTOS_UPDATE_BANNER=off pins it off, like the network settings.
@@ -17,22 +17,4 @@ export function bannerEnabled(env: Env = process.env): boolean {
 export const setBannerEnabled = (on: boolean) =>
   putSetting(KEY, on ? "1" : "0");
 
-export function getSetting(key: string): string | null {
-  const row = getDb()
-    .prepare(`SELECT value FROM settings WHERE key = ?`)
-    .get(key) as { value: string } | undefined;
-  return row?.value ?? null;
-}
-
-export function putSetting(key: string, value: string | null): void {
-  if (value === null) {
-    getDb().prepare(`DELETE FROM settings WHERE key = ?`).run(key);
-    return;
-  }
-  getDb()
-    .prepare(
-      `INSERT INTO settings (key, value) VALUES (?, ?)
-       ON CONFLICT(key) DO UPDATE SET value = excluded.value`
-    )
-    .run(key, value);
-}
+export { getSetting, putSetting } from "../settings-store";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.556",
+  "version": "0.3.557",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"