@saadnvd1/agent-os 0.3.723 → 0.3.728

package/lib/reports/types.ts

@@ -0,0 +1,135 @@
+// Plain-English health reports: types shared by the server, the browser and
+// the native app (no Node modules here).
+
+import type { TaskState } from "../tasks/state";
+
+export const OPERATING_MODES = ["manual", "assisted", "autonomous"] as const;
+export type OperatingMode = (typeof OPERATING_MODES)[number];
+export const isMode = (v: unknown): v is OperatingMode =>
+  typeof v === "string" && (OPERATING_MODES as readonly string[]).includes(v);
+
+export const MODE_COPY: Record<
+  OperatingMode,
+  { label: string; blurb: string }
+> = {
+  manual: {
+    label: "Manual",
+    blurb: "The analyst recommends, you decide.",
+  },
+  assisted: {
+    label: "Assisted",
+    blurb: "The analyst drafts the next prompt, you approve it with one click.",
+  },
+  autonomous: {
+    label: "Autonomous",
+    blurb: "Agents iterate on their own, within the loop's safeguards.",
+  },
+};
+
+export type ReportTrigger = "on-demand" | "cycle" | "end";
+export type LineTone = "done" | "warn" | "blocked" | "next";
+export type EvidenceKind =
+  | "ci"
+  | "test"
+  | "review"
+  | "diff"
+  | "piece"
+  | "accept"
+  | "ask"
+  | "state"
+  | "log";
+export type EvidenceStatus = "pass" | "fail" | "pending" | "info";
+
+export interface EvidenceRef {
+  id: string;
+  kind: EvidenceKind;
+  label: string;
+  status: EvidenceStatus;
+  at: string;
+  // The head it belongs to; stale when it differs from the current head.
+  sha?: string;
+  url?: string;
+  href?: string;
+  excerpt?: string;
+}
+
+export interface ReportLine {
+  id: string;
+  tone: LineTone;
+  text: string;
+  evidence: string[];
+}
+
+export interface EstimateItem {
+  label: string;
+  verified: boolean;
+  evidence: string[];
+}
+
+export interface Estimate {
+  done: number;
+  total: number;
+  basis: "acceptance" | "stages";
+  items: EstimateItem[];
+}
+
+export type DraftStatus = "pending" | "sent" | "dismissed" | "superseded";
+
+export interface NextPromptDraft {
+  // The report row that holds it, or the analyst recommendation.
+  source: "report" | "analyst";
+  id: string;
+  text: string;
+  status: DraftStatus;
+  // Analyst drafts send through the analyst link.
+  linkId?: string;
+}
+
+export interface HealthReport {
+  id: number;
+  sessionId: string;
+  workspaceId: string | null;
+  head: string | null;
+  trigger: ReportTrigger;
+  createdAt: string;
+  headline: string;
+  state: TaskState;
+  estimate: Estimate;
+  lines: ReportLine[];
+  recommendation: { text: string; evidence: string[] } | null;
+  draft: NextPromptDraft | null;
+  evidence: EvidenceRef[];
+  // "template": the model failed, or every line it wrote was rejected.
+  source: "model" | "template";
+  // Model lines the validator rejected.
+  dropped: number;
+  model: string | null;
+  costUsd: number | null;
+  // Computed on read: the head moved since.
+  stale: boolean;
+}
+
+export interface ReportSummary {
+  sessionId: string;
+  name: string;
+  headline: string;
+  state: TaskState;
+  estimate: Pick<Estimate, "done" | "total" | "basis">;
+  createdAt: string;
+}
+
+export interface ReportResponse {
+  report: HealthReport | null;
+  generating: boolean;
+  mode: { mode: OperatingMode; source: "task" | "workspace" | "default" };
+}
+
+export const estimateLabel = (e: Pick<Estimate, "done" | "total" | "basis">) =>
+  `Estimate · ${e.done} of ${e.total} ${
+    e.basis === "acceptance"
+      ? "acceptance items verified"
+      : "delivery stages reached"
+  }`;
+
+export const estimatePercent = (e: Pick<Estimate, "done" | "total">) =>
+  e.total ? Math.round((100 * e.done) / e.total) : 0;

package/lib/reports/validate.ts

@@ -0,0 +1,142 @@
+// What a model may say in a report. Every line must cite evidence that
+// exists, say only numbers that evidence contains, never use a percent sign,
+// and take a tone its evidence supports. What fails is dropped and counted.
+
+import type { EvidenceRef, LineTone, ReportLine } from "./types";
+import type { Mapping } from "./estimate";
+
+export interface ModelReport {
+  headline?: unknown;
+  lines?: unknown;
+  recommendation?: unknown;
+  acceptance?: unknown;
+  nextPrompt?: unknown;
+}
+
+export interface Validated {
+  headline: string | null;
+  lines: ReportLine[];
+  recommendation: { text: string; evidence: string[] } | null;
+  mappings: Mapping[];
+  nextPrompt: string | null;
+  dropped: number;
+}
+
+export const MAX_LINE = 280;
+export const MAX_LINES = 10;
+export const MAX_PROMPT = 4000;
+const TONES: LineTone[] = ["done", "warn", "blocked", "next"];
+
+const str = (v: unknown, max: number) =>
+  typeof v === "string" ? v.trim().slice(0, max) : "";
+const ids = (v: unknown): string[] =>
+  Array.isArray(v)
+    ? [...new Set(v.filter((x): x is string => typeof x === "string"))]
+    : [];
+
+// Digits in the text that none of the cited evidence contains.
+function inventedNumber(text: string, cited: EvidenceRef[]): boolean {
+  const nums = text.match(/\d+/g);
+  if (!nums) return false;
+  const haystack = cited
+    .map((e) => `${e.id} ${e.label} ${e.excerpt ?? ""} ${e.sha ?? ""}`)
+    .join("\n");
+  return nums.some((n) => !new RegExp(`(?<!\\d)${n}(?!\\d)`).test(haystack));
+}
+
+export function sayable(text: string, cited: EvidenceRef[]): boolean {
+  return (
+    !!text &&
+    text.length <= MAX_LINE &&
+    !/%/.test(text) &&
+    !inventedNumber(text, cited)
+  );
+}
+
+function toneFits(tone: LineTone, cited: EvidenceRef[]): boolean {
+  if (tone === "done") return cited.some((e) => e.status === "pass");
+  if (tone === "warn" || tone === "blocked")
+    return cited.some(
+      (e) => e.status === "fail" || e.status === "pending" || e.kind === "ask"
+    );
+  return true;
+}
+
+export function validateModelReport(
+  raw: unknown,
+  evidence: EvidenceRef[]
+): Validated {
+  const out: Validated = {
+    headline: null,
+    lines: [],
+    recommendation: null,
+    mappings: [],
+    nextPrompt: null,
+    dropped: 0,
+  };
+  if (!raw || typeof raw !== "object") return out;
+  const m = raw as ModelReport;
+  const byId = new Map(evidence.map((e) => [e.id, e]));
+  const resolve = (cites: string[]) => {
+    const found = cites.map((c) => byId.get(c));
+    return found.some((e) => !e) ? null : (found as EvidenceRef[]);
+  };
+
+  const headline = str(m.headline, MAX_LINE);
+  if (
+    headline &&
+    sayable(
+      headline,
+      evidence.filter((e) => e.kind === "state")
+    )
+  )
+    out.headline = headline;
+  else if (headline) out.dropped++;
+
+  const rawLines = Array.isArray(m.lines) ? m.lines.slice(0, 24) : [];
+  for (const l of rawLines) {
+    const o = (l ?? {}) as Record<string, unknown>;
+    const tone = o.tone as LineTone;
+    const text = str(o.text, MAX_LINE + 1);
+    const cites = ids(o.evidence);
+    const cited = cites.length ? resolve(cites) : null;
+    if (
+      !TONES.includes(tone) ||
+      !cited ||
+      !sayable(text, cited) ||
+      !toneFits(tone, cited) ||
+      out.lines.length >= MAX_LINES
+    ) {
+      out.dropped++;
+      continue;
+    }
+    out.lines.push({
+      id: `l${out.lines.length + 1}`,
+      tone,
+      text,
+      evidence: cites,
+    });
+  }
+
+  if (m.recommendation && typeof m.recommendation === "object") {
+    const r = m.recommendation as Record<string, unknown>;
+    const text = str(r.text, 600);
+    const cites = ids(r.evidence);
+    const cited = cites.length ? resolve(cites) : null;
+    if (text && cited && !/%/.test(text) && !inventedNumber(text, cited))
+      out.recommendation = { text, evidence: cites };
+    else out.dropped++;
+  }
+
+  if (Array.isArray(m.acceptance))
+    for (const a of m.acceptance.slice(0, 24)) {
+      const o = (a ?? {}) as Record<string, unknown>;
+      // The model sees items numbered from 1, as in "accept:1".
+      if (typeof o.item === "number" && Number.isInteger(o.item) && o.item >= 1)
+        out.mappings.push({ item: o.item - 1, evidence: ids(o.evidence) });
+    }
+
+  const prompt = str(m.nextPrompt, MAX_PROMPT);
+  if (prompt) out.nextPrompt = prompt;
+  return out;
+}

package/lib/sidebar/row-menu.ts

@@ -23,6 +23,7 @@ export type RowMenuItem =
   | "move-machine"
   | "move-project"
   | "move-group"
+  | "add-analyst"
   | "check-ins"
   | "save-recipe"
   | "run-again"
@@ -55,6 +56,7 @@ export interface RowMenuInput {
     | "has_brief"
     | "archived_at"
     | "pause_state"
+    | "agent_role"
   >;
   row?: Pick<SidebarRow, "task" | "wakesAt" | "settled">;
   // A linked machine runs it: what can't reach it yet is left out.
@@ -142,6 +144,13 @@ export function rowMenu(input: RowMenuInput): RowMenuPlan {
       agentRow && "move-group",
     ]),
     ...group("automate", [
+      // A local chat can have an analyst review its turns; not an analyst.
+      s.view === "chat" &&
+        agentRow &&
+        live &&
+        !s.archived_at &&
+        s.agent_role !== "analyst" &&
+        "add-analyst",
       input.hasWorkspace &&
         !orchestrator &&
         (!s.task_status || s.task_status === "running") &&

package/lib/tasks/contract/routes.ts

@@ -3,6 +3,11 @@
 export const taskPath = (id: string, leaf: string) =>
   `/api/tasks/${encodeURIComponent(id)}/${leaf}`;
 
+// The loop's routes are the task's own: GET/POST/PATCH on `loop`, and the
+// leaves stop, run and next beside it (lib/loops/route.ts).
+export const loopPath = (id: string, leaf = "") =>
+  taskPath(id, leaf ? `loop/${leaf}` : "loop");
+
 export const LIST = "/api/tasks";
 export const IMPORT = "/api/tasks/import";
 export const HELD_REPLIES = "/api/tasks/held-replies";

package/lib/tasks/contract/types.ts

@@ -27,6 +27,9 @@ export const TASK_CAPABILITIES = [
   // compat: the shims marked "task-contract-1" in contract/ go once every
   // linked machine reports this.
   "task-contract-1",
+  // A task's developer-analyst loop: /api/tasks/:id/loop and its leaves
+  // (lib/loops). A task started on a linked machine is looped from there.
+  "task-loop-1",
 ] as const;
 
 export interface HostTasks {

package/lib/tasks/finish.ts

@@ -36,6 +36,7 @@ import {
 } from "./session";
 import { releaseSessionLeftovers } from "../sessions/leftovers";
 import { captureMergedTask } from "../session-logs";
+import { taskEnded } from "../reports/end-hook";
 import { sessionEnded } from "../experiments/hooks";
 import { snapshotWorktree } from "../resurrect/snapshot";
 import { keepSessionFiles } from "../session-artifacts/collect";
@@ -202,6 +203,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 });
+  taskEnded(id);
   void sessionEnded(id, "merged");
   const head = opts.head ?? pr!.head;
   resolveMergedTaskAsks(

package/lib/tasks/move-carry.ts

@@ -27,6 +27,7 @@ export const REKEYED = [
   ["check_runs", "session_id", "id"],
   ["away_actions", "subject", "task"],
   ["task_queue", "after_task", "id"],
+  ["task_loops", "session_id", "id"],
 ] as const;
 
 // Session-keyed columns that stay on the old id, and why.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.723",
+  "version": "0.3.728",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"
@@ -133,7 +133,7 @@
     "mdast-util-from-markdown": "^2.1.0",
     "mdast-util-gfm": "^3.1.0",
     "mdast-util-to-markdown": "^2.2.0",
-    "mermaid": "^11.17.2",
+    "mermaid": "^12.2.0",
     "micromark-extension-gfm": "^3.0.0",
     "monaco-editor": "^0.57.0",
     "next": "^16.3.8",

package/stores/analystUi.ts

@@ -0,0 +1,19 @@
+import { proxy } from "valtio";
+
+// The Add analyst sheet: the chat it pairs with, and the pane to open the
+// analyst beside.
+export const analystUi = proxy<{
+  open: boolean;
+  sessionId: string | null;
+  name: string;
+  paneId: string | null;
+}>({ open: false, sessionId: null, name: "", paneId: null });
+
+export const analystUiActions = {
+  open(sessionId: string, name: string, paneId: string | null = null) {
+    Object.assign(analystUi, { open: true, sessionId, name, paneId });
+  },
+  close() {
+    analystUi.open = false;
+  },
+};