@saadnvd1/agent-os 0.3.557 → 0.3.558

package/lib/db/migrations.ts

@@ -2061,6 +2061,32 @@ const migrations: Migration[] = [
       `);
     },
   },
+  {
+    id: 86,
+    name: "learning_cards",
+    up: (db) => {
+      // End-of-session suggestions (save as recipe, keep a lesson). An
+      // accepted lesson row is the record of where it was applied.
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS learning_cards (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          session_id TEXT NOT NULL,
+          workspace_id TEXT,
+          kind TEXT NOT NULL,
+          status TEXT NOT NULL DEFAULT 'pending',
+          payload TEXT NOT NULL,
+          destination TEXT,
+          applied_ref TEXT,
+          shown_at INTEGER,
+          decided_at INTEGER,
+          created_at INTEGER NOT NULL,
+          UNIQUE (session_id, kind)
+        );
+        CREATE INDEX IF NOT EXISTS idx_learning_cards_dest
+          ON learning_cards(destination, decided_at);
+      `);
+    },
+  },
 ];
 
 // `upTo`: stop after this id (tests that start from an older database).

package/lib/experiments/hooks.ts

@@ -6,16 +6,24 @@ 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>> = {};
+// Loaded on first use so the places that end sessions don't pull in the
+// experiment's code. A hook does its own once-only check in the database: this
+// process forgets what it has seen on a restart.
+export const END_HOOKS: Partial<Record<ExperimentId, EndHook>> = {
+  "learning-cards": async (id, how) =>
+    (await import("../learning-cards/analyze")).analyzeSession(id, how),
+};
 
-// A merge is seen again on every poll; each session is handed on once.
+// A merge is seen again on every poll; each session is handed on once. A
+// recipe run settling is its own event: its session has usually ended already.
 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);
+  const key = how === "recipe-settled" ? `${sessionId}:settled` : sessionId;
+  if (seen.has(key)) return Promise.resolve();
+  seen.add(key);
   return (async () => {
     await new Promise<void>((r) => setImmediate(r));
     for (const { id } of EXPERIMENTS) {

package/lib/learning-cards/__fixtures__/db.ts

@@ -0,0 +1,52 @@
+import { randomUUID } from "crypto";
+import { db } from "../../db";
+import { saveItem } from "../../chat/store";
+import { makeSession, workspaceWithProject } from "../../recipes/test-fixtures";
+import type { Step } from "../types";
+
+// A finished session in a fresh workspace, its steps written as chat items.
+export function seedSession(
+  o: {
+    prompt?: string;
+    steps?: Step[];
+    final?: string;
+    orchestrator?: boolean;
+    fields?: Record<string, string | number | null>;
+  } = {}
+) {
+  const { ws, project } = workspaceWithProject();
+  const id = makeSession({
+    project_id: project.id,
+    task_prompt: o.prompt ?? "Send the latest build to the beta testers",
+    name: "Beta build",
+    ...o.fields,
+  });
+  let n = 0;
+  const at = () => ({ id: `i${n++}`, createdAt: Date.now() + n });
+  for (const s of o.steps ?? [])
+    saveItem(
+      id,
+      s.kind === "user"
+        ? { ...at(), kind: "user", text: s.text }
+        : {
+            ...at(),
+            kind: "tool",
+            name: s.name,
+            title: s.name,
+            input: s.command ? { command: s.command } : { file_path: s.path },
+            status: s.failed ? "error" : "done",
+            output: s.output,
+          }
+    );
+  if (o.final) saveItem(id, { ...at(), kind: "assistant", text: o.final });
+  if (o.orchestrator)
+    makeSession({ role: "orchestrator", workspace_id: ws.id });
+  return { id, ws, project };
+}
+
+export const clearCards = () =>
+  db.exec(
+    `DELETE FROM learning_cards; DELETE FROM experiment_usage; DELETE FROM orchestrator_notes`
+  );
+
+export const uid = () => randomUUID();

package/lib/learning-cards/__fixtures__/sessions.ts

@@ -0,0 +1,63 @@
+import type { SessionInput, Step } from "../types";
+
+export const bash = (
+  command: string,
+  o: { ok?: boolean; output?: string } = {}
+): Step => ({
+  kind: "tool",
+  name: "Bash",
+  ok: o.ok ?? true,
+  failed: !(o.ok ?? true),
+  command,
+  path: "",
+  input: command,
+  output: o.output ?? "",
+});
+
+export const edit = (path: string, change = "x"): Step => ({
+  kind: "tool",
+  name: "Edit",
+  ok: true,
+  failed: false,
+  command: "",
+  path,
+  input: `${path} ${change}`,
+  output: "",
+});
+
+export const said = (text: string, byPerson = true): Step => ({
+  kind: "user",
+  text,
+  byPerson,
+});
+
+export const input = (o: Partial<SessionInput> = {}): SessionInput => ({
+  id: "s1",
+  name: "A session",
+  workspaceId: "w1",
+  projectId: "p1",
+  skip: null,
+  brief: "Refactor the parser module",
+  final: "Done. The parser is split in two files.",
+  steps: [],
+  reviews: [],
+  inRepo: true,
+  run: null,
+  previousRun: null,
+  recentBriefs: [],
+  ...o,
+});
+
+// Sends a build to testers: external CLIs, a report of facts, no repo.
+export const releaseToTesters = (): SessionInput =>
+  input({
+    brief: "Send the latest build to the beta testers",
+    final:
+      "Build 57 (1.4.2) sent to 3 testers. Invite id 6a1f2c9d, group Beta.",
+    inRepo: false,
+    steps: [
+      said("Send the latest build to the beta testers"),
+      bash("asc builds list --app 123"),
+      bash("cd app && eas submit --platform ios"),
+    ],
+  });

package/lib/learning-cards/analyze.ts

@@ -0,0 +1,228 @@
+// The end-of-session hook: scripts first (free); a helper-model call only
+// on a hit, through the experiments meter, never on the transcript.
+
+import os from "os";
+import { runClaude, type ClaudeRunner } from "../orchestrator/claude-cli";
+import { getOrchestrator } from "../orchestrator/home";
+import { addNote } from "../orchestrator/notes";
+import { untrusted, UNTRUSTED_RULE } from "../orchestrator/untrusted";
+import { isRemoteHost } from "../hosts";
+import { getProject } from "../projects";
+import { getRecipe } from "../recipes/store";
+import { draftRequest, parseDraft, recipePrefill } from "../recipes/draft";
+import { countEvent, experimentRun, hasEvent } from "../experiments/meter";
+import { experimentOn } from "../experiments";
+import type { EndHow } from "../experiments/hooks";
+import { readSession } from "./input";
+import { correctionPairs } from "./pairs";
+import { recipeSignals } from "./signals";
+import { insertCard } from "./store";
+import type { Destination, Pair, SessionInput } from "./types";
+
+const ID = "learning-cards" as const;
+const LESSON_MAX = 200;
+const TASK_MAX = 600;
+
+const inFlight = new Set<string>();
+
+const LESSON_SYSTEM = `You judge whether a few corrections from one finished agent session are worth keeping for next time. Reply reusable=false for anything specific to that one piece of work. Otherwise give one plain line (the lesson, under ${LESSON_MAX} characters) and where it belongs:
+- "recipe": the session ran from a saved recipe and the lesson is about running that recipe.
+- "claude_md": a fact about the repository (how to build, test, run or avoid breaking it) that every future agent there should know.
+- "check": better caught by a script or automated check; put a short task brief for it in taskPrompt instead of a lesson.
+- "rule": only a preference about how work is done in this workspace (process, style, when to ask), never a fact about code.
+${UNTRUSTED_RULE}`;
+const LESSON_SCHEMA = {
+  type: "object",
+  properties: {
+    reusable: { type: "boolean" },
+    lesson: { type: "string" },
+    destination: { enum: ["recipe", "claude_md", "check", "rule"] },
+    taskPrompt: { type: "string" },
+  },
+  required: ["reusable", "lesson", "destination"],
+};
+
+interface Where {
+  recipe: { id: string; name: string } | null;
+  project: { id: string; name: string } | null;
+  repo: boolean;
+  workspaceId: string | null;
+}
+
+function whereOf(input: SessionInput): Where {
+  const project = input.projectId ? getProject(input.projectId) : null;
+  const usable = project && !project.is_uncategorized ? project : null;
+  const recipe = input.run ? getRecipe(input.run.recipeId) : null;
+  return {
+    recipe: recipe ? { id: recipe.id, name: recipe.name } : null,
+    project: usable ? { id: usable.id, name: usable.name } : null,
+    repo: !!usable && input.inRepo && !isRemoteHost(usable.host_id),
+    workspaceId: input.workspaceId,
+  };
+}
+
+export interface Verdict {
+  reusable?: unknown;
+  lesson?: unknown;
+  destination?: unknown;
+  taskPrompt?: unknown;
+}
+
+// What the model said, held to what the session can actually do. Null: no card.
+export function checkLesson(
+  v: Verdict | null,
+  where: Where
+): { lesson: string; destination: Destination; taskPrompt?: string } | null {
+  if (!v || v.reusable !== true || typeof v.lesson !== "string") return null;
+  const lesson = v.lesson.replace(/\s+/g, " ").trim().slice(0, LESSON_MAX);
+  const task =
+    typeof v.taskPrompt === "string"
+      ? v.taskPrompt.trim().slice(0, TASK_MAX)
+      : "";
+  let destination = v.destination as Destination;
+  // Not run from a recipe: its lesson is a repo fact, if there is a repo.
+  if (destination === "recipe" && !where.recipe) destination = "claude_md";
+  switch (destination) {
+    case "recipe":
+      return lesson ? { lesson, destination } : null;
+    case "claude_md":
+      return lesson && where.repo && where.project
+        ? { lesson, destination }
+        : null;
+    case "check":
+      return task && where.project
+        ? {
+            lesson: lesson || task.slice(0, LESSON_MAX),
+            destination,
+            taskPrompt: task,
+          }
+        : null;
+    case "rule":
+      return lesson && where.workspaceId ? { lesson, destination } : null;
+    default:
+      return null;
+  }
+}
+
+const pairsText = (pairs: Pair[]) =>
+  pairs
+    .map((p, i) => `${i + 1}. [${p.kind}] ${p.before}\n   then: ${p.after}`)
+    .join("\n");
+
+export async function analyzeSession(
+  sessionId: string,
+  how: EndHow,
+  runner: ClaudeRunner = runClaude
+): Promise<void> {
+  if (!experimentOn(ID)) return;
+  if (
+    inFlight.has(sessionId) ||
+    hasEvent(ID, sessionId, "script", "session-end")
+  )
+    return;
+  inFlight.add(sessionId);
+  try {
+    const input = await readSession(sessionId);
+    if (!input || input.skip) return;
+    // A recipe run's session ends before the run settles; its settle comes.
+    if (input.run && !input.run.settled && how !== "recipe-settled") return;
+
+    const ctx = { sessionId, workspaceId: input.workspaceId };
+    const recipe = recipeSignals(input);
+    const pairs = correctionPairs(input);
+    countEvent(ID, "script", {
+      ...ctx,
+      trigger: "session-end",
+      detail: `signals: ${recipe.signals.join(",") || "none"}; pairs: ${pairs.length}`,
+    });
+
+    let made = 0;
+    if (recipe.hit && input.workspaceId) {
+      try {
+        recipePrefill(sessionId);
+        const out = await experimentRun(
+          ID,
+          { ...ctx, trigger: "recipe-draft" },
+          {
+            ...draftRequest(input.brief, input.final, true),
+            workspaceId: input.workspaceId,
+          },
+          runner
+        );
+        const draft = parseDraft(out);
+        if (
+          (out as { repeatable?: unknown } | null)?.repeatable === true &&
+          draft
+        )
+          made += insertCard({
+            sessionId,
+            workspaceId: input.workspaceId,
+            kind: "recipe",
+            payload: { signals: recipe.signals, ...draft },
+          })
+            ? 1
+            : 0;
+      } catch (error) {
+        console.warn("[learning-cards] recipe draft:", error);
+      }
+    }
+
+    if (pairs.length) {
+      try {
+        const where = whereOf(input);
+        const out = (await experimentRun(
+          ID,
+          { ...ctx, trigger: "lesson" },
+          {
+            cwd: os.tmpdir(),
+            system: LESSON_SYSTEM,
+            prompt: [
+              where.recipe
+                ? `The session ran from the recipe "${where.recipe.name}".`
+                : "The session did not run from a recipe.",
+              untrusted("session corrections", pairsText(pairs)),
+            ].join("\n\n"),
+            schema: LESSON_SCHEMA,
+            tools: [],
+            role: "helper",
+            timeoutMs: 20_000,
+            workspaceId: input.workspaceId ?? undefined,
+          },
+          runner
+        )) as Verdict | null;
+        const ok = checkLesson(out, where);
+        if (ok)
+          made += insertCard({
+            sessionId,
+            workspaceId: input.workspaceId,
+            kind: "lesson",
+            destination: ok.destination,
+            payload: {
+              ...ok,
+              recipeId: where.recipe?.id,
+              recipeName: where.recipe?.name,
+              projectId: where.project?.id,
+              projectName: where.project?.name,
+              pairs: pairs.length,
+            },
+          })
+            ? 1
+            : 0;
+      } catch (error) {
+        console.warn("[learning-cards] lesson:", error);
+      }
+    }
+
+    if (made && input.workspaceId && getOrchestrator(input.workspaceId))
+      addNote(
+        input.workspaceId,
+        `Learning card on ${input.name}: ${
+          made > 1
+            ? "save as a recipe and keep a lesson"
+            : "a suggestion to save or keep"
+        }? Open the session to decide.`
+      );
+  } finally {
+    inFlight.delete(sessionId);
+  }
+}

package/lib/learning-cards/apply.ts

@@ -0,0 +1,196 @@
+// What a tap on a card does. The only place a lesson is written anywhere.
+
+import fs from "fs";
+import path from "path";
+import { db } from "../db";
+import { countEvent } from "../experiments/meter";
+import { experimentOn } from "../experiments";
+import { getOrchestrator } from "../orchestrator/home";
+import { quickPR, startQuickChange } from "../orchestrator/quick";
+import { addRule } from "../orchestrator/rules";
+import { isRemoteHost } from "../hosts";
+import { getProject } from "../projects";
+import { createRecipe, getRecipe, updateRecipe } from "../recipes/store";
+import { recipePrefill } from "../recipes/draft";
+import { createTask } from "../tasks";
+import { claimCard, getCard, releaseCard, settleCard } from "./store";
+import type { Card, LessonPayload, RecipePayload } from "./types";
+
+const ID = "learning-cards" as const;
+const HEADING = "## Lessons";
+
+export class CardRefused extends Error {}
+
+export interface Edits {
+  lesson?: string;
+  brief?: string;
+  taskPrompt?: string;
+}
+
+// CLAUDE.md with the line under "## Lessons" (the heading made if missing).
+export function withLesson(text: string, line: string): string {
+  const bullet = `- ${line.replace(/\s+/g, " ").trim()}`;
+  const lines = text.replace(/\s+$/, "").split("\n");
+  const at = lines.findIndex((l) => l.trim() === HEADING);
+  if (at === -1)
+    return `${text.trim() ? `${lines.join("\n")}\n\n` : ""}${HEADING}\n\n${bullet}\n`;
+  let end = at + 1;
+  while (end < lines.length && !/^#{1,6}\s/.test(lines[end])) end++;
+  while (end > at + 1 && !lines[end - 1].trim()) end--;
+  if (lines.slice(at + 1, end).some((l) => l.trim() === bullet))
+    return `${lines.join("\n")}\n`;
+  lines.splice(end, 0, ...(end === at + 1 ? ["", bullet] : [bullet]));
+  return `${lines.join("\n")}\n`;
+}
+
+const clean = (s: string | undefined, max: number) =>
+  (s ?? "").replace(/\s+/g, " ").trim().slice(0, max);
+
+async function toClaudeMd(card: Card, p: LessonPayload, line: string) {
+  const project = p.projectId ? getProject(p.projectId) : null;
+  if (!project) throw new CardRefused("That project is gone");
+  const workspaceId = card.workspace_id;
+  const source = (
+    db
+      .prepare(`SELECT name FROM sessions WHERE id = ?`)
+      .get(card.session_id) as { name: string } | undefined
+  )?.name;
+  if (
+    workspaceId &&
+    getOrchestrator(workspaceId) &&
+    !isRemoteHost(project.host_id)
+  ) {
+    const quick = await startQuickChange(
+      workspaceId,
+      project.id,
+      "Add a lesson to CLAUDE.md"
+    );
+    const file = path.join(quick.worktreePath, "CLAUDE.md");
+    const before = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+    fs.writeFileSync(file, withLesson(before, line));
+    await quickPR(
+      workspaceId,
+      quick.id,
+      "docs: add a lesson to CLAUDE.md",
+      `${line}${source ? `\n\nFrom the session "${source}".` : ""}`
+    );
+    return quick.id;
+  }
+  const task = await createTask({
+    projectId: project.id,
+    prompt: `Add exactly this line under a "${HEADING}" heading in CLAUDE.md at the repository root, creating the file and heading if missing, and change nothing else: ${line}`,
+    startedBy: null,
+  });
+  return task.id;
+}
+
+async function applyLesson(card: Card, p: LessonPayload, edits: Edits) {
+  const line = clean(edits.lesson, 200) || p.lesson;
+  switch (p.destination) {
+    case "recipe": {
+      const recipe = p.recipeId ? getRecipe(p.recipeId) : null;
+      if (!recipe || recipe.archived_at)
+        throw new CardRefused("That recipe is gone");
+      updateRecipe(
+        recipe.id,
+        { brief: `${recipe.brief}\n\nLesson: ${line}` },
+        null
+      );
+      return recipe.id;
+    }
+    case "claude_md":
+      return toClaudeMd(card, p, line);
+    case "check": {
+      const prompt = clean(edits.taskPrompt, 600) || p.taskPrompt;
+      if (!prompt || !p.projectId)
+        throw new CardRefused("There's no task to start");
+      return (
+        await createTask({ projectId: p.projectId, prompt, startedBy: null })
+      ).id;
+    }
+    case "rule":
+      if (!card.workspace_id)
+        throw new CardRefused("There's no workspace for a rule");
+      return String(addRule(card.workspace_id, line, "saad").id);
+  }
+}
+
+async function applyRecipe(card: Card, p: RecipePayload, edits: Edits) {
+  const base = recipePrefill(card.session_id);
+  const recipe = createRecipe(
+    {
+      workspaceId: base.workspaceId,
+      projectId: base.projectId,
+      name: base.name,
+      kind: base.kind,
+      brief: edits.brief?.trim() || p.brief,
+      model: base.model ?? undefined,
+      view: base.view,
+      sourceSessionId: card.session_id,
+    },
+    null
+  );
+  return recipe.id;
+}
+
+function pending(cardId: number): Card {
+  if (!experimentOn(ID)) throw new CardRefused("Learning cards are off");
+  const card = getCard(cardId);
+  if (!card) throw new CardRefused("No such card");
+  if (card.status !== "pending") throw new CardRefused("Already decided");
+  return card;
+}
+
+const meter = (card: Card, event: "accepted" | "dismissed") =>
+  countEvent(
+    ID,
+    event,
+    {
+      trigger: "card-apply",
+      sessionId: card.session_id,
+      workspaceId: card.workspace_id,
+      detail: card.kind === "lesson" ? `lesson: ${card.destination}` : "recipe",
+    },
+    true
+  );
+
+export async function applyCard(
+  cardId: number,
+  edits: Edits = {}
+): Promise<Card> {
+  const card = pending(cardId);
+  if (!claimCard(cardId)) throw new CardRefused("Already decided");
+  try {
+    const ref =
+      card.kind === "recipe"
+        ? await applyRecipe(card, card.payload as RecipePayload, edits)
+        : await applyLesson(card, card.payload as LessonPayload, edits);
+    settleCard(cardId, "accepted", ref);
+  } catch (error) {
+    releaseCard(cardId);
+    throw error;
+  }
+  meter(card, "accepted");
+  return getCard(cardId)!;
+}
+
+export function dismissCard(cardId: number): Card {
+  const card = pending(cardId);
+  settleCard(cardId, "dismissed", null);
+  meter(card, "dismissed");
+  return getCard(cardId)!;
+}
+
+// The recipe form saved a recipe from this session: its card is taken.
+export function acceptRecipeCardFor(sessionId: string, recipeId: string): void {
+  if (!experimentOn(ID)) return;
+  const row = db
+    .prepare(
+      `SELECT id FROM learning_cards WHERE session_id = ? AND kind = 'recipe' AND status = 'pending'`
+    )
+    .get(sessionId) as { id: number } | undefined;
+  if (!row || !claimCard(row.id)) return;
+  const card = getCard(row.id)!;
+  settleCard(row.id, "accepted", recipeId);
+  meter(card, "accepted");
+}

package/lib/learning-cards/index.ts

@@ -0,0 +1,29 @@
+import { experimentOn } from "../experiments";
+import { countEvent } from "../experiments/meter";
+import { listCards, markShown } from "./store";
+import type { Card, RecipePayload } from "./types";
+
+const ID = "learning-cards" as const;
+
+// A session's pending cards. Nothing, and no work, while the experiment is off.
+export function cardsFor(sessionId: string): Card[] {
+  if (!experimentOn(ID)) return [];
+  const cards = listCards(sessionId, "pending");
+  for (const c of cards)
+    if (markShown(c.id))
+      countEvent(ID, "shown", {
+        trigger: "card-view",
+        sessionId,
+        workspaceId: c.workspace_id,
+        detail: c.kind,
+      });
+  return cards;
+}
+
+// The brief a pending recipe card drafted, so Edit needn't draft it again.
+export function pendingRecipeDraft(sessionId: string) {
+  if (!experimentOn(ID)) return undefined;
+  const card = listCards(sessionId, "pending").find((c) => c.kind === "recipe");
+  const p = card?.payload as RecipePayload | undefined;
+  return p ? { brief: p.brief, summary: p.summary } : undefined;
+}