@saadnvd1/agent-os 0.3.723 → 0.3.731

package/lib/reports/evidence/gather.ts

@@ -0,0 +1,229 @@
+// Reads everything a report is built from: the task's state, its checks and
+// review, the diff, the plan, the tests it ran, what waits on a human and,
+// once merged, its log. No model is involved.
+
+import fs from "fs/promises";
+import path from "path";
+import { git } from "../../git-exec";
+import { db, type Session } from "../../db";
+import { taskView } from "../../tasks";
+import { taskChecks } from "../../tasks/checks-view";
+import { expandHome, localWorktree } from "../../tasks/session";
+import { PLAN_FILE } from "../../models/plan-step";
+import { parseAcceptance } from "../../plans/acceptance";
+import { lastItems } from "../../chat/store";
+import { turnSignals } from "../../analyst/signals";
+import { getLog, headerOf } from "../../session-logs/store";
+import { pieceOfSession } from "../../plans/features";
+import { liveLinkFor, listRecommendations } from "../../analyst/store";
+import { criteriaOf, latestLoopFor } from "../../loops/store";
+import { isFinished, type TaskState } from "../../tasks/state";
+import { scrub } from "../../session-audit/normalize";
+import type { AcceptanceItem, Stages } from "../estimate";
+import type { EvidenceRef, NextPromptDraft } from "../types";
+import {
+  acceptEvidence,
+  askEvidence,
+  ciEvidence,
+  diffEvidence,
+  evidenceHash,
+  logEvidence,
+  reviewEvidence,
+  stateEvidence,
+  testEvidence,
+} from "./build";
+
+export interface Gathered {
+  state: TaskState;
+  head: string | null;
+  evidence: EvidenceRef[];
+  hash: string;
+  items: AcceptanceItem[];
+  stages: Stages;
+  analystDraft: NextPromptDraft | null;
+}
+
+async function readPlan(s: Session): Promise<string | null> {
+  const dir = s.worktree_path ? expandHome(s.worktree_path) : null;
+  if (!dir) return null;
+  try {
+    return await fs.readFile(path.join(dir, PLAN_FILE), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+async function numstat(s: Session): Promise<string> {
+  const dir = localWorktree(s);
+  if (!dir) return "";
+  const base = (s.base_branch ?? "main").replace(/^origin\//, "");
+  try {
+    return await git(dir, ["diff", "--numstat", `origin/${base}...HEAD`], {
+      timeout: 10_000,
+    });
+  } catch {
+    return "";
+  }
+}
+
+function openAsks(s: Session) {
+  if (!s.workspace_id) return [];
+  return db
+    .prepare(
+      `SELECT id, title, detail, created_at FROM orchestrator_asks
+        WHERE workspace_id = ? AND subject = ? AND status = 'open'`
+    )
+    .all(s.workspace_id, `task:${s.id}`) as {
+    id: number;
+    title: string;
+    detail: string;
+    created_at: string;
+  }[];
+}
+
+export async function gather(
+  s: Session,
+  extra?: { analystSummary?: string | null }
+): Promise<Gathered> {
+  const at = new Date().toISOString();
+  const [view, checks, plan, stat] = await Promise.all([
+    taskView(s),
+    taskChecks(s, { logs: true }).catch(() => null),
+    readPlan(s),
+    numstat(s),
+  ]);
+  const head = checks?.pr?.head ?? view.pr?.head ?? null;
+  const evidence: EvidenceRef[] = [
+    stateEvidence(view.state, view.blocked, at),
+    ...ciEvidence(checks?.checks ?? [], head, at),
+    ...reviewEvidence(checks?.review ?? null),
+    ...diffEvidence(stat, s.id, at),
+    ...askEvidence(openAsks(s)),
+  ];
+
+  if (s.view === "chat")
+    evidence.push(
+      ...testEvidence(turnSignals(lastItems(s.id, 600)), s.id, head, at)
+    );
+
+  const piece = pieceOfSession(s.id);
+  if (piece)
+    evidence.push({
+      id: `piece:${piece.position}`,
+      kind: "piece",
+      label: `Piece "${piece.name}" is ${piece.status}`,
+      status:
+        piece.status === "merged"
+          ? "pass"
+          : piece.status === "blocked"
+            ? "fail"
+            : "info",
+      at,
+    });
+
+  if (extra?.analystSummary)
+    evidence.push({
+      id: "state:analyst",
+      kind: "state",
+      label: "The analyst's summary of the last cycle",
+      status: "info",
+      at,
+      excerpt: scrub(extra.analystSummary).slice(0, 1500),
+    });
+
+  const log = isFinished(view.state) ? getLog(s.id) : null;
+  if (log) {
+    const h = headerOf(log);
+    evidence.push(
+      logEvidence({
+        sessionId: s.id,
+        mergeCommit: h.mergeCommit,
+        prNumber: h.prNumber,
+        durationMs: h.durationMs,
+        costUsd: h.costUsd,
+        createdAt: h.createdAt,
+      })
+    );
+  }
+
+  // Acceptance: the plan's checklist, else the loop's criteria. A loop
+  // criterion is met only when its cited evidence resolved (verified).
+  let items: AcceptanceItem[] = [];
+  const planItems = parseAcceptance(plan);
+  if (planItems.length) {
+    items = planItems.map((label) => ({ label }));
+    evidence.push(
+      ...acceptEvidence(
+        planItems.map((label) => ({ label, met: false })),
+        at
+      )
+    );
+  } else {
+    const loop = latestLoopFor(s.id);
+    const crit = loop
+      ? criteriaOf(loop.id).filter((c) => c.status !== "waived")
+      : [];
+    if (crit.length) {
+      const met = (c: (typeof crit)[number]) =>
+        c.status === "met" && c.verified;
+      evidence.push(
+        ...acceptEvidence(
+          crit.map((c) => ({
+            label: c.text,
+            met: met(c),
+            note: c.evidence?.note,
+          })),
+          at
+        )
+      );
+      items = crit.map((c, i) => ({
+        label: c.text,
+        evidence: met(c) ? [`accept:${i + 1}`] : undefined,
+      }));
+    }
+  }
+
+  const merged = view.state === "merged";
+  const pr = checks?.pr ?? null;
+  const ci = evidence.filter((e) => e.kind === "ci");
+  const stages: Stages = {
+    planned:
+      !!plan ||
+      s.plan_phase === "implementing" ||
+      s.plan_phase === "handoff" ||
+      !!pr,
+    pushed: !!pr || evidence.some((e) => e.kind === "diff"),
+    prOpen: !!pr,
+    ciGreen: ci.length > 0 && ci.every((e) => e.status === "pass"),
+    reviewed: evidence.some((e) => e.kind === "review" && e.status === "pass"),
+    merged,
+  };
+
+  return {
+    state: view.state,
+    head,
+    evidence,
+    hash: evidenceHash(evidence, head),
+    items,
+    stages,
+    analystDraft: analystDraft(s.id),
+  };
+}
+
+// The analyst's open recommendation with a prompt, when the task has one.
+export function analystDraft(sessionId: string): NextPromptDraft | null {
+  const link = liveLinkFor(sessionId);
+  if (!link) return null;
+  const rec = listRecommendations(link.id, 5).find(
+    (r) => r.state === "open" && r.prompt
+  );
+  return rec
+    ? {
+        source: "analyst",
+        id: rec.id,
+        text: rec.prompt!,
+        status: "pending",
+        linkId: link.id,
+      }
+    : null;
+}

package/lib/reports/fixtures.ts

@@ -0,0 +1,17 @@
+import type { EvidenceRef } from "./types";
+
+export const HEAD = "abc1234";
+
+export const ev = (
+  id: string,
+  kind: EvidenceRef["kind"],
+  status: EvidenceRef["status"],
+  extra: Partial<EvidenceRef> = {}
+): EvidenceRef => ({
+  id,
+  kind,
+  label: extra.label ?? id,
+  status,
+  at: "2026-10-21T12:00:00.000Z",
+  ...extra,
+});

package/lib/reports/generate.ts

@@ -0,0 +1,159 @@
+// Builds, stores and serves a task's health report. Evidence first (server
+// code), words second (the analyst model), then every claim is checked and
+// the estimate is computed here. Cached on an evidence hash; one generation
+// per task at a time.
+
+import { db, type Session } from "../db";
+import type { ClaudeRunner } from "../orchestrator/claude-cli";
+import type { RunUsage } from "../usage/check-runs";
+import { isFinished } from "../tasks/state";
+import { gather, type Gathered } from "./evidence/gather";
+import { computeEstimate } from "./estimate";
+import { askModel, evidencePack } from "./model";
+import { modeOf, workspaceOf } from "./mode";
+import { hashOfLatest, insertReport, latestReport } from "./store";
+import { headlineFor, templateLines } from "./template";
+import { validateModelReport } from "./validate";
+import type { HealthReport, ReportTrigger } from "./types";
+import { notifyTopic } from "../status/hub";
+
+export const reportTopic = (sessionId: string) => `report:${sessionId}`;
+
+const inFlight = new Map<string, Promise<HealthReport>>();
+export const isGenerating = (sessionId: string) => inFlight.has(sessionId);
+
+export interface GenerateOptions {
+  analystSummary?: string | null;
+  runner?: ClaudeRunner;
+  // Build a new report even when the evidence is unchanged.
+  force?: boolean;
+}
+
+export function buildReport(
+  s: Pick<Session, "id" | "name" | "task_prompt">,
+  g: Gathered,
+  trigger: ReportTrigger,
+  raw: unknown | null,
+  usage: RunUsage | null
+): Omit<HealthReport, "id" | "createdAt" | "stale"> {
+  const v = raw === null ? null : validateModelReport(raw, g.evidence);
+  const fromModel = !!v && (v.lines.length > 0 || !!v.recommendation);
+  const tmpl = templateLines(g.state, g.evidence);
+  const estimate = computeEstimate({
+    head: g.head,
+    evidence: g.evidence,
+    items: g.items,
+    mappings: v?.mappings ?? [],
+    stages: g.stages,
+  });
+  const mode = modeOf(s.id).mode;
+  const finished = isFinished(g.state);
+  const text = mode !== "manual" && !finished ? (v?.nextPrompt ?? null) : null;
+  const draft =
+    mode === "manual" || finished
+      ? null
+      : (g.analystDraft ??
+        (text
+          ? {
+              source: "report" as const,
+              id: "",
+              text,
+              status: "pending" as const,
+            }
+          : null));
+  return {
+    sessionId: s.id,
+    workspaceId: workspaceOf(s.id),
+    head: g.head,
+    trigger,
+    headline: (fromModel && v?.headline) || headlineFor(g.state),
+    state: g.state,
+    estimate,
+    lines: fromModel ? v!.lines : tmpl.lines,
+    recommendation: fromModel ? v!.recommendation : tmpl.recommendation,
+    draft,
+    evidence: g.evidence,
+    source: fromModel ? "model" : "template",
+    dropped: v?.dropped ?? 0,
+    model: usage?.model ?? null,
+    costUsd: usage?.costUsd ?? null,
+  };
+}
+
+async function run(
+  sessionId: string,
+  trigger: ReportTrigger,
+  opts: GenerateOptions
+): Promise<HealthReport> {
+  const s = db
+    .prepare(`SELECT * FROM session_rows WHERE id = ?`)
+    .get(sessionId) as Session | undefined;
+  if (!s) throw new Error("No such task");
+  const g = await gather(s, { analystSummary: opts.analystSummary });
+  const last = latestReport(sessionId, g.head);
+  // The same evidence needs no new report, and a task's end report is final.
+  if (
+    last &&
+    !opts.force &&
+    (hashOfLatest(sessionId) === g.hash ||
+      (last.trigger === "end" && isFinished(g.state)))
+  )
+    return last;
+
+  let raw: unknown = null;
+  let usage: RunUsage | null = null;
+  try {
+    raw = await askModel(
+      {
+        prompt: evidencePack(
+          { name: s.name, prompt: s.task_prompt ?? "" },
+          g.state,
+          g.evidence,
+          g.items
+        ),
+        workspaceId: workspaceOf(sessionId),
+        onUsage: (u) => (usage = u),
+      },
+      opts.runner
+    );
+  } catch (error) {
+    console.error(`Report for ${s.name}:`, error);
+  }
+  const report = buildReport(s, g, trigger, raw, usage);
+  const id = insertReport(report, g.hash);
+  notifyTopic(reportTopic(sessionId));
+  return (
+    latestReport(sessionId, g.head) ?? {
+      ...report,
+      id,
+      createdAt: "",
+      stale: false,
+    }
+  );
+}
+
+// One generation per task: a request while one runs shares its result.
+export function generateReport(
+  sessionId: string,
+  trigger: ReportTrigger,
+  opts: GenerateOptions = {}
+): Promise<HealthReport> {
+  const running = inFlight.get(sessionId);
+  if (running) return running;
+  const p = run(sessionId, trigger, opts).finally(() =>
+    inFlight.delete(sessionId)
+  );
+  inFlight.set(sessionId, p);
+  return p;
+}
+
+// The trigger entry the loop and the task hooks use: fire and forget.
+export function requestReport(
+  sessionId: string,
+  trigger: ReportTrigger,
+  opts: GenerateOptions & { cycleId?: number } = {}
+): void {
+  generateReport(sessionId, trigger, opts).catch((error) =>
+    console.error(`Report ${sessionId}:`, error)
+  );
+}

package/lib/reports/hooks.ts

@@ -0,0 +1,30 @@
+// How the developer-analyst loop meets the reports: a loop makes its task
+// Autonomous, every stop hands it back to Assisted with the instruction that
+// wasn't sent kept as a pending draft, and each settled cycle asks for a
+// report.
+
+import { setLoopHooks } from "../loops/hooks";
+import { setTaskEndHook } from "./end-hook";
+import { generateReport, requestReport } from "./generate";
+import { setTaskMode } from "./mode";
+import { setDraftText } from "./store";
+
+let installed = false;
+
+export function installReportHooks(): void {
+  if (installed) return;
+  installed = true;
+  setTaskEndHook((id) => requestReport(id, "end"));
+  setLoopHooks({
+    onCycleSettled: ({ taskId, analystSummary }) =>
+      requestReport(taskId, "cycle", { analystSummary }),
+    onStart: (loop) => setTaskMode(loop.sessionId, "autonomous"),
+    onStop: (loop, _stop, pending) => {
+      setTaskMode(loop.sessionId, "assisted");
+      if (!pending) return;
+      generateReport(loop.sessionId, "cycle", { force: true })
+        .then((r) => setDraftText(r.id, pending, "pending"))
+        .catch((error) => console.error("Keeping the loop's draft:", error));
+    },
+  });
+}

package/lib/reports/mode.ts

@@ -0,0 +1,65 @@
+// The operating mode: a workspace default and a per-task override. Manual
+// until someone says otherwise. The developer-analyst loop reads it here.
+
+import { db } from "../db";
+import { isMode, type OperatingMode } from "./types";
+
+export interface ModeOf {
+  mode: OperatingMode;
+  source: "task" | "workspace" | "default";
+}
+
+const read = (
+  scope: "task" | "workspace",
+  id: string
+): OperatingMode | null => {
+  const row = db
+    .prepare(
+      `SELECT mode FROM operating_modes WHERE scope = ? AND scope_id = ?`
+    )
+    .get(scope, id) as { mode: string } | undefined;
+  return row && isMode(row.mode) ? row.mode : null;
+};
+
+export function workspaceOf(sessionId: string): string | null {
+  const row = db
+    .prepare(`SELECT workspace_id FROM session_rows WHERE id = ?`)
+    .get(sessionId) as { workspace_id: string | null } | undefined;
+  return row?.workspace_id ?? null;
+}
+
+export function modeOf(sessionId: string): ModeOf {
+  const own = read("task", sessionId);
+  if (own) return { mode: own, source: "task" };
+  const ws = workspaceOf(sessionId);
+  const inherited = ws ? read("workspace", ws) : null;
+  return inherited
+    ? { mode: inherited, source: "workspace" }
+    : { mode: "manual", source: "default" };
+}
+
+export const workspaceMode = (workspaceId: string): OperatingMode =>
+  read("workspace", workspaceId) ?? "manual";
+
+// null clears the task's override so it follows its workspace again.
+function put(
+  scope: "task" | "workspace",
+  id: string,
+  mode: OperatingMode | null
+) {
+  if (mode === null) {
+    db.prepare(
+      `DELETE FROM operating_modes WHERE scope = ? AND scope_id = ?`
+    ).run(scope, id);
+    return;
+  }
+  db.prepare(
+    `INSERT INTO operating_modes (scope, scope_id, mode) VALUES (?, ?, ?)
+     ON CONFLICT(scope, scope_id) DO UPDATE SET mode = excluded.mode, updated_at = datetime('now')`
+  ).run(scope, id, mode);
+}
+
+export const setTaskMode = (sessionId: string, mode: OperatingMode | null) =>
+  put("task", sessionId, mode);
+export const setWorkspaceMode = (id: string, mode: OperatingMode) =>
+  put("workspace", id, mode);

package/lib/reports/model.ts

@@ -0,0 +1,115 @@
+// The model's part of a report: word what the evidence shows. It has no field
+// for an estimate, a percentage or a count of finished work; the server
+// computes those (estimate.ts) and checks every claim (validate.ts).
+
+import os from "os";
+import { runClaude, type ClaudeRunner } from "../orchestrator/claude-cli";
+import { untrusted, UNTRUSTED_RULE } from "../orchestrator/untrusted";
+import type { RunUsage } from "../usage/check-runs";
+import type { AcceptanceItem } from "./estimate";
+import type { EvidenceRef } from "./types";
+import { MAX_PROMPT } from "./validate";
+
+export const REPORT_TIMEOUT_MS = 60_000;
+const PACK_CHARS = 12_000;
+
+const SYSTEM = `You write a short plain-English progress report on one software task for someone who does not read code. You are given numbered evidence items (CI checks, test runs, the review, changed files, acceptance items). Rules:
+- Every line must cite the ids of the evidence it rests on, copied exactly. A line with no evidence is thrown away.
+- Say only what the evidence shows. Use plain words: no file paths, no jargon, no stack traces.
+- Never write a percentage, a completion estimate or a count of finished work: the system works those out. Any number you write must appear in the evidence you cite.
+- Tones: "done" for something that passed or happened, "warn" for something failing or still running, "blocked" for something waiting on a person, "next" for what should happen next. A "done" line must cite a passing item; a "warn" or "blocked" line must cite a failing, pending or waiting item.
+- "acceptance": for each numbered acceptance item that the evidence proves, give its number and the ids that prove it (a passing test, CI check or review at the latest push; a changed file alone proves nothing). Leave out items you cannot prove.
+- "recommendation": one short paragraph on the single best next step, citing evidence.
+- "nextPrompt": when work should go on, the exact message to send the coding agent, written as an instruction to it (no more than a few sentences); otherwise null.
+${UNTRUSTED_RULE}`;
+
+export const SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["headline", "lines", "recommendation", "acceptance", "nextPrompt"],
+  properties: {
+    headline: { type: "string" },
+    lines: {
+      type: "array",
+      maxItems: 10,
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["tone", "text", "evidence"],
+        properties: {
+          tone: { enum: ["done", "warn", "blocked", "next"] },
+          text: { type: "string" },
+          evidence: { type: "array", items: { type: "string" } },
+        },
+      },
+    },
+    recommendation: {
+      type: ["object", "null"],
+      additionalProperties: false,
+      required: ["text", "evidence"],
+      properties: {
+        text: { type: "string" },
+        evidence: { type: "array", items: { type: "string" } },
+      },
+    },
+    acceptance: {
+      type: "array",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["item", "evidence"],
+        properties: {
+          item: { type: "integer" },
+          evidence: { type: "array", items: { type: "string" } },
+        },
+      },
+    },
+    nextPrompt: { type: ["string", "null"], maxLength: MAX_PROMPT },
+  },
+} as const;
+
+export function evidencePack(
+  task: { name: string; prompt: string },
+  state: string,
+  evidence: EvidenceRef[],
+  items: AcceptanceItem[]
+): string {
+  const rows = evidence.map(
+    (e) =>
+      `${e.id} | ${e.kind} | ${e.status} | ${e.label}${
+        e.excerpt ? `\n${untrusted(`evidence ${e.id}`, e.excerpt)}` : ""
+      }`
+  );
+  const accept = items.map((it, i) => `${i + 1}. ${it.label}`);
+  const body = [
+    `Task: ${task.name}`,
+    `Brief: ${untrusted("task brief", task.prompt.slice(0, 1200))}`,
+    `State: ${state}`,
+    accept.length ? `Acceptance items:\n${accept.join("\n")}` : "",
+    `Evidence (id | kind | status | label):\n${rows.join("\n")}`,
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+  return body.slice(0, PACK_CHARS);
+}
+
+export async function askModel(
+  input: {
+    prompt: string;
+    workspaceId: string | null;
+    onUsage: (u: RunUsage) => void;
+  },
+  runner: ClaudeRunner = runClaude
+): Promise<unknown> {
+  return runner({
+    cwd: os.tmpdir(),
+    system: SYSTEM,
+    prompt: input.prompt,
+    schema: SCHEMA,
+    tools: [],
+    timeoutMs: REPORT_TIMEOUT_MS,
+    role: "analyze",
+    workspaceId: input.workspaceId,
+    onUsage: input.onUsage,
+  });
+}

package/lib/reports/read.ts

@@ -0,0 +1,26 @@
+// The report a client sees: the stored one, with the current draft laid over
+// it and its staleness against the task's head.
+
+import { isFinished } from "../tasks/state";
+import { analystDraft } from "./evidence/gather";
+import { isGenerating } from "./generate";
+import { modeOf } from "./mode";
+import { latestReport } from "./store";
+import type { ReportResponse } from "./types";
+
+export function readReport(sessionId: string): ReportResponse {
+  const mode = modeOf(sessionId);
+  const report = latestReport(sessionId);
+  if (report) {
+    const live = mode.mode !== "manual" && !isFinished(report.state);
+    // The analyst's open recommendation is the draft when the task has one.
+    const own = live ? analystDraft(sessionId) : null;
+    report.draft = !live
+      ? null
+      : (own ??
+        (report.draft?.status === "pending" || report.draft?.status === "sent"
+          ? report.draft
+          : null));
+  }
+  return { report, generating: isGenerating(sessionId), mode };
+}