stagent 0.1.11 → 0.1.12

package/src/lib/docs/adoption.ts

@@ -0,0 +1,105 @@
+import { db } from "@/lib/db";
+import {
+  tasks,
+  workflows,
+  documents,
+  schedules,
+  usageLedger,
+  learnedContext,
+  settings,
+} from "@/lib/db/schema";
+import { count, like, sql } from "drizzle-orm";
+import type { AdoptionEntry } from "./types";
+
+function toDepth(n: number): AdoptionEntry["depth"] {
+  if (n === 0) return "none";
+  if (n <= 3) return "light";
+  return "deep";
+}
+
+function entry(n: number): AdoptionEntry {
+  return { adopted: n > 0, depth: toDepth(n) };
+}
+
+/** Map each manifest section slug to DB evidence of adoption */
+export async function getAdoptionMap(): Promise<Map<string, AdoptionEntry>> {
+  const [
+    taskCount,
+    workflowCount,
+    documentCount,
+    scheduleCount,
+    profileUsed,
+    usageCount,
+    learnedCount,
+    permissionCount,
+    providerCount,
+  ] = await Promise.all([
+    db
+      .select({ n: count() })
+      .from(tasks)
+      .then((r) => r[0]?.n ?? 0),
+    db
+      .select({ n: count() })
+      .from(workflows)
+      .then((r) => r[0]?.n ?? 0),
+    db
+      .select({ n: count() })
+      .from(documents)
+      .then((r) => r[0]?.n ?? 0),
+    db
+      .select({ n: count() })
+      .from(schedules)
+      .then((r) => r[0]?.n ?? 0),
+    db
+      .select({ n: count() })
+      .from(tasks)
+      .where(sql`${tasks.agentProfile} IS NOT NULL`)
+      .then((r) => r[0]?.n ?? 0),
+    db
+      .select({ n: count() })
+      .from(usageLedger)
+      .then((r) => r[0]?.n ?? 0),
+    db
+      .select({ n: count() })
+      .from(learnedContext)
+      .then((r) => r[0]?.n ?? 0),
+    db
+      .select({ n: count() })
+      .from(settings)
+      .where(like(settings.key, "permission:%"))
+      .then((r) => r[0]?.n ?? 0),
+    db
+      .select({ n: sql<number>`COUNT(DISTINCT ${usageLedger.providerId})` })
+      .from(usageLedger)
+      .then((r) => Number(r[0]?.n ?? 0)),
+  ]);
+
+  const map = new Map<string, AdoptionEntry>();
+
+  // Always adopted
+  map.set("home-workspace", { adopted: true, depth: "deep" });
+  map.set("settings", { adopted: true, depth: "deep" });
+
+  // Feature sections
+  map.set("dashboard-kanban", entry(taskCount));
+  map.set("inbox-notifications", entry(taskCount)); // notifications come with tasks
+  map.set("monitoring", entry(taskCount));
+  map.set("projects", entry(taskCount)); // projects enable tasks
+  map.set("workflows", entry(workflowCount));
+  map.set("documents", entry(documentCount));
+  map.set("profiles", entry(profileUsed));
+  map.set("schedules", entry(scheduleCount));
+  map.set("cost-usage", entry(usageCount));
+
+  // Cross-cutting
+  map.set(
+    "provider-runtimes",
+    providerCount > 1
+      ? { adopted: true, depth: "deep" }
+      : entry(usageCount > 0 ? 1 : 0)
+  );
+  map.set("agent-intelligence", entry(learnedCount));
+  map.set("tool-permissions", entry(permissionCount));
+
+  return map;
+}

package/src/lib/docs/journey-tracker.ts

@@ -0,0 +1,21 @@
+import type { AdoptionEntry, DocJourney, JourneyCompletion } from "./types";
+
+/** Compute journey completion from adoption data */
+export function getJourneyCompletions(
+  journeys: DocJourney[],
+  adoptionMap: Map<string, AdoptionEntry>
+): Map<string, JourneyCompletion> {
+  const completions = new Map<string, JourneyCompletion>();
+
+  for (const journey of journeys) {
+    const total = journey.sections.length;
+    const completed = journey.sections.filter(
+      (slug) => adoptionMap.get(slug)?.adopted === true
+    ).length;
+    const percentage = total > 0 ? Math.round((completed / total) * 100) : 0;
+
+    completions.set(journey.slug, { completed, total, percentage });
+  }
+
+  return completions;
+}

package/src/lib/docs/reader.ts

@@ -0,0 +1,102 @@
+import { readFileSync, readdirSync, existsSync } from "fs";
+import { join, basename } from "path";
+import type { DocManifest, ParsedDoc } from "./types";
+
+/** Resolve the docs directory relative to project root */
+function docsDir(): string {
+  return join(process.cwd(), "docs");
+}
+
+/** Read and parse docs/manifest.json */
+export function getManifest(): DocManifest {
+  const raw = readFileSync(join(docsDir(), "manifest.json"), "utf-8");
+  return JSON.parse(raw) as DocManifest;
+}
+
+/** Parse a markdown file into frontmatter + body */
+function parseMarkdown(content: string, slug: string): ParsedDoc {
+  const fmRegex = /^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/;
+  const match = content.match(fmRegex);
+
+  if (!match) {
+    return { frontmatter: {}, body: content, slug };
+  }
+
+  const frontmatter: Record<string, unknown> = {};
+  const fmLines = match[1].split("\n");
+  for (const line of fmLines) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    let value: unknown = line.slice(colonIdx + 1).trim();
+
+    // Strip surrounding quotes
+    if (
+      typeof value === "string" &&
+      value.startsWith('"') &&
+      value.endsWith('"')
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    // Parse arrays: ["a", "b"]
+    if (typeof value === "string" && value.startsWith("[")) {
+      try {
+        value = JSON.parse(value);
+      } catch {
+        // keep as string
+      }
+    }
+
+    frontmatter[key] = value;
+  }
+
+  return { frontmatter, body: match[2], slug };
+}
+
+/** Read a single doc by slug (searches features/ then journeys/ then root) */
+export function getDocBySlug(slug: string): ParsedDoc | null {
+  const dirs = ["features", "journeys", ""];
+  for (const dir of dirs) {
+    const filePath = join(docsDir(), dir, `${slug}.md`);
+    if (existsSync(filePath)) {
+      const content = readFileSync(filePath, "utf-8");
+      return parseMarkdown(content, slug);
+    }
+  }
+  return null;
+}
+
+/** Read all docs from features/ and journeys/ */
+export function getAllDocs(): ParsedDoc[] {
+  const docs: ParsedDoc[] = [];
+  const subDirs = ["features", "journeys"];
+
+  for (const dir of subDirs) {
+    const dirPath = join(docsDir(), dir);
+    if (!existsSync(dirPath)) continue;
+
+    const files = readdirSync(dirPath).filter((f) => f.endsWith(".md"));
+    for (const file of files) {
+      const content = readFileSync(join(dirPath, file), "utf-8");
+      const slug = basename(file, ".md");
+      docs.push(parseMarkdown(content, slug));
+    }
+  }
+
+  // Also check for getting-started.md at root
+  const gsPath = join(docsDir(), "getting-started.md");
+  if (existsSync(gsPath)) {
+    const content = readFileSync(gsPath, "utf-8");
+    docs.push(parseMarkdown(content, "getting-started"));
+  }
+
+  return docs;
+}
+
+/** Read the .last-generated timestamp */
+export function getDocsLastGenerated(): string | null {
+  const filePath = join(docsDir(), ".last-generated");
+  if (!existsSync(filePath)) return null;
+  return readFileSync(filePath, "utf-8").trim();
+}

package/src/lib/docs/types.ts

@@ -0,0 +1,54 @@
+// Types for the Playbook documentation system
+
+export interface DocManifest {
+  generated: string;
+  version: number;
+  sections: DocSection[];
+  journeys: DocJourney[];
+  metadata: {
+    totalDocs: number;
+    totalScreengrabs: number;
+    featuresCovered: number;
+    appSections: number;
+  };
+}
+
+export interface DocSection {
+  slug: string;
+  title: string;
+  category: string;
+  path: string;
+  route: string;
+  tags: string[];
+  features: string[];
+  screengrabCount: number;
+}
+
+export interface DocJourney {
+  slug: string;
+  title: string;
+  persona: string;
+  difficulty: string;
+  path: string;
+  sections: string[];
+  stepCount: number;
+}
+
+export interface ParsedDoc {
+  frontmatter: Record<string, unknown>;
+  body: string;
+  slug: string;
+}
+
+export type UsageStage = "new" | "early" | "active" | "power";
+
+export interface AdoptionEntry {
+  adopted: boolean;
+  depth: "none" | "light" | "deep";
+}
+
+export interface JourneyCompletion {
+  completed: number;
+  total: number;
+  percentage: number;
+}

package/src/lib/docs/usage-stage.ts

@@ -0,0 +1,60 @@
+import { db } from "@/lib/db";
+import {
+  tasks,
+  projects,
+  workflows,
+  schedules,
+  usageLedger,
+} from "@/lib/db/schema";
+import { count, isNotNull } from "drizzle-orm";
+import type { UsageStage } from "./types";
+
+/** Compute the user's usage stage from DB state */
+export async function getUsageStage(): Promise<UsageStage> {
+  const [taskCount, projectCount, workflowCount, scheduleCount, profileUsed] =
+    await Promise.all([
+      db
+        .select({ n: count() })
+        .from(tasks)
+        .then((r) => r[0]?.n ?? 0),
+      db
+        .select({ n: count() })
+        .from(projects)
+        .then((r) => r[0]?.n ?? 0),
+      db
+        .select({ n: count() })
+        .from(workflows)
+        .then((r) => r[0]?.n ?? 0),
+      db
+        .select({ n: count() })
+        .from(schedules)
+        .then((r) => r[0]?.n ?? 0),
+      db
+        .select({ n: count() })
+        .from(tasks)
+        .where(isNotNull(tasks.agentProfile))
+        .then((r) => r[0]?.n ?? 0),
+    ]);
+
+  // Power: has workflows + schedules + profiles
+  if (workflowCount > 0 && scheduleCount > 0 && profileUsed > 0) {
+    return "power";
+  }
+
+  // Active: 6+ tasks OR 3+ projects OR any workflows/schedules
+  if (
+    taskCount >= 6 ||
+    projectCount >= 3 ||
+    workflowCount > 0 ||
+    scheduleCount > 0
+  ) {
+    return "active";
+  }
+
+  // Early: 1-5 tasks, <=2 projects
+  if (taskCount >= 1 || projectCount >= 1) {
+    return "early";
+  }
+
+  return "new";
+}

package/src/lib/notifications/actionable.ts

@@ -80,6 +80,7 @@ export async function listPendingApprovalPayloads(
         inArray(notifications.type, [
           "permission_required",
           "context_proposal",
+          "context_proposal_batch",
         ]),
         isNull(notifications.response)
       )
@@ -89,6 +90,7 @@ export async function listPendingApprovalPayloads(
 
   return rows.map((row) => {
     const isContextProposal = row.type === "context_proposal";
+    const isBatchProposal = row.type === "context_proposal_batch";
     const parsedInput = parseNotificationToolInput(row.toolInput);
 
     return {
@@ -97,16 +99,22 @@ export async function listPendingApprovalPayloads(
       taskId: row.taskId,
       workflowId: row.workflowId,
       toolName: row.toolName,
-      permissionLabel: isContextProposal
-        ? "Context Proposal"
-        : getPermissionKindLabel(row.toolName),
-      compactSummary: isContextProposal
-        ? `Learned patterns proposed for profile "${row.toolName}"`
-        : buildPermissionSummary(row.toolName, parsedInput),
-      deepLink: isContextProposal
-        ? `/profiles/${row.toolName}`
-        : buildDeepLink(row.taskId, row.workflowId),
-      supportedActionIds: isContextProposal
+      permissionLabel: isBatchProposal
+        ? "Workflow Learning"
+        : isContextProposal
+          ? "Context Proposal"
+          : getPermissionKindLabel(row.toolName),
+      compactSummary: isBatchProposal
+        ? `Batch of learned patterns from workflow execution`
+        : isContextProposal
+          ? `Learned patterns proposed for profile "${row.toolName}"`
+          : buildPermissionSummary(row.toolName, parsedInput),
+      deepLink: isBatchProposal
+        ? "/inbox"
+        : isContextProposal
+          ? `/profiles/${row.toolName}`
+          : buildDeepLink(row.taskId, row.workflowId),
+      supportedActionIds: (isContextProposal || isBatchProposal)
         ? (["allow_once", "deny"] as ApprovalActionId[])
         : [...APPROVAL_ACTION_IDS],
       title: row.title,

package/src/lib/settings/__tests__/budget-guardrails.test.ts

@@ -8,10 +8,13 @@ let tempDir: string;
 beforeEach(() => {
   tempDir = mkdtempSync(join(tmpdir(), "stagent-budget-guardrails-"));
   vi.resetModules();
+  vi.useFakeTimers();
+  vi.setSystemTime(new Date("2026-03-17T12:00:00.000Z"));
   vi.stubEnv("STAGENT_DATA_DIR", tempDir);
 });
 
 afterEach(() => {
+  vi.useRealTimers();
   vi.unstubAllEnvs();
   rmSync(tempDir, { recursive: true, force: true });
 });
@@ -21,8 +24,9 @@ async function loadModules() {
   const schema = await import("@/lib/db/schema");
   const ledger = await import("@/lib/usage/ledger");
   const budgets = await import("../budget-guardrails");
+  const auth = await import("../auth");
 
-  return { db, ...schema, ...ledger, ...budgets };
+  return { db, ...schema, ...ledger, ...budgets, ...auth };
 }
 
 describe("budget guardrails", () => {
@@ -33,25 +37,22 @@ describe("budget guardrails", () => {
       recordUsageLedgerEntry,
       setBudgetPolicy,
       enforceBudgetGuardrails,
+      setAuthSettings,
     } = await loadModules();
 
+    vi.stubEnv("ANTHROPIC_API_KEY", "sk-ant-test-key");
+    await setAuthSettings({ method: "api_key" });
+
     await setBudgetPolicy({
       overall: {
-        dailySpendCapUsd: 0.012,
-        monthlySpendCapUsd: null,
+        monthlySpendCapUsd: 0.36,
       },
       runtimes: {
         "claude-code": {
-          dailySpendCapUsd: null,
-          monthlySpendCapUsd: null,
-          dailyTokenCap: null,
-          monthlyTokenCap: null,
+          monthlySpendCapUsd: 0.36,
         },
         "openai-codex-app-server": {
-          dailySpendCapUsd: null,
           monthlySpendCapUsd: null,
-          dailyTokenCap: null,
-          monthlyTokenCap: null,
         },
       },
     });
@@ -80,9 +81,10 @@ describe("budget guardrails", () => {
     });
 
     const rows = await db.select().from(notifications);
-    expect(rows).toHaveLength(1);
-    expect(rows[0]?.type).toBe("budget_alert");
-    expect(rows[0]?.title).toContain("Overall daily spend");
+    expect(rows).toHaveLength(2);
+    expect(rows.every((row) => row.type === "budget_alert")).toBe(true);
+    expect(rows.some((row) => row.title.includes("Overall daily spend"))).toBe(true);
+    expect(rows.some((row) => row.title.includes("Claude Code daily spend"))).toBe(true);
   });
 
   it("blocks new runtime activity, records a zero-cost ledger row, and fails queued tasks when requested", async () => {
@@ -95,8 +97,12 @@ describe("budget guardrails", () => {
       setBudgetPolicy,
       enforceTaskBudgetGuardrails,
       BudgetLimitExceededError,
+      setAuthSettings,
     } = await loadModules();
 
+    vi.stubEnv("ANTHROPIC_API_KEY", "sk-ant-test-key");
+    await setAuthSettings({ method: "api_key" });
+
     const taskId = crypto.randomUUID();
     const now = new Date();
 
@@ -120,21 +126,14 @@ describe("budget guardrails", () => {
 
     await setBudgetPolicy({
       overall: {
-        dailySpendCapUsd: null,
-        monthlySpendCapUsd: null,
+        monthlySpendCapUsd: 0.001,
       },
       runtimes: {
         "claude-code": {
-          dailySpendCapUsd: null,
-          monthlySpendCapUsd: null,
-          dailyTokenCap: 100,
-          monthlyTokenCap: null,
+          monthlySpendCapUsd: 0.001,
         },
         "openai-codex-app-server": {
-          dailySpendCapUsd: null,
           monthlySpendCapUsd: null,
-          dailyTokenCap: null,
-          monthlyTokenCap: null,
         },
       },
     });
@@ -159,7 +158,7 @@ describe("budget guardrails", () => {
 
     const [task] = await db.select().from(tasks);
     expect(task?.status).toBe("failed");
-    expect(task?.result).toContain("token usage");
+    expect(task?.result).toContain("spend");
 
     const ledgerRows = await db.select().from(usageLedger);
     const blockedRow = ledgerRows.find((row) => row.status === "blocked");
@@ -176,6 +175,69 @@ describe("budget guardrails", () => {
 
     const budgetNotifications = await db.select().from(notifications);
     expect(budgetNotifications.at(-1)?.title).toContain("blocked");
-    expect(budgetNotifications.at(-1)?.body).toContain("Resets");
+    expect(budgetNotifications.at(-1)?.body).toContain("spend");
+  });
+
+  it("derives daily spend caps from the monthly cap and auto-assigns a single configured runtime", async () => {
+    const { setBudgetPolicy, getBudgetGuardrailSnapshot, setAuthSettings } =
+      await loadModules();
+
+    vi.stubEnv("ANTHROPIC_API_KEY", "sk-ant-test-key");
+    vi.stubEnv("OPENAI_API_KEY", "");
+    await setAuthSettings({ method: "api_key" });
+
+    await setBudgetPolicy({
+      overall: {
+        monthlySpendCapUsd: 310,
+      },
+      runtimes: {
+        "claude-code": {
+          monthlySpendCapUsd: 155,
+        },
+        "openai-codex-app-server": {
+          monthlySpendCapUsd: 155,
+        },
+      },
+    });
+
+    const snapshot = await getBudgetGuardrailSnapshot();
+    const overallDaily = snapshot.statuses.find(
+      (status) => status.scopeId === "overall" && status.window === "daily"
+    );
+    const claudeMonthly = snapshot.policy.runtimes["claude-code"].monthlySpendCapUsd;
+    const openAIMonthly =
+      snapshot.policy.runtimes["openai-codex-app-server"].monthlySpendCapUsd;
+
+    expect(overallDaily?.limitValue).toBe(10_000_000);
+    expect(claudeMonthly).toBe(310);
+    expect(openAIMonthly).toBeNull();
+  });
+
+  it("splits configured provider caps from the overall budget when both runtimes are configured", async () => {
+    vi.stubEnv("ANTHROPIC_API_KEY", "sk-ant-test-key");
+    vi.stubEnv("OPENAI_API_KEY", "sk-test-openai");
+    const { setBudgetPolicy, getBudgetGuardrailSnapshot, setAuthSettings } =
+      await loadModules();
+    await setAuthSettings({ method: "api_key" });
+
+    await setBudgetPolicy({
+      overall: {
+        monthlySpendCapUsd: 300,
+      },
+      runtimes: {
+        "claude-code": {
+          monthlySpendCapUsd: 120,
+        },
+        "openai-codex-app-server": {
+          monthlySpendCapUsd: 180,
+        },
+      },
+    });
+
+    const snapshot = await getBudgetGuardrailSnapshot();
+    expect(snapshot.policy.runtimes["claude-code"].monthlySpendCapUsd).toBe(120);
+    expect(snapshot.policy.runtimes["openai-codex-app-server"].monthlySpendCapUsd).toBe(
+      180
+    );
   });
 });