@saadnvd1/agent-os 0.3.723 → 0.3.731

package/lib/loops/types.ts

@@ -0,0 +1,223 @@
+// The developer-analyst loop: types shared by the engine, the routes and
+// the browser (no Node modules here).
+
+export const CRITERION_STATUSES = ["open", "failing", "met", "waived"] as const;
+export type CriterionStatus = (typeof CRITERION_STATUSES)[number];
+
+export const CRITERION_SOURCES = ["card", "brief", "plan", "user"] as const;
+export type CriterionSource = (typeof CRITERION_SOURCES)[number];
+
+export const EVIDENCE_KINDS = ["test", "diff", "typecheck", "ci"] as const;
+export type EvidenceKind = (typeof EVIDENCE_KINDS)[number];
+
+export interface Evidence {
+  kind: EvidenceKind;
+  ref: string;
+  note: string;
+}
+
+export interface Criterion {
+  id: number;
+  loopId: string;
+  position: number;
+  text: string;
+  source: CriterionSource;
+  evidenceKind: EvidenceKind | null;
+  status: CriterionStatus;
+  evidence: Evidence | null;
+  // False when the analyst said "met" but the citation didn't resolve.
+  verified: boolean;
+  metCycle: number | null;
+  waivedBy: string | null;
+}
+
+export interface CriterionDraft {
+  text: string;
+  source?: CriterionSource;
+  evidenceKind?: EvidenceKind | null;
+}
+
+export type LoopState = "running" | "stopped";
+
+export const STOP_REASONS = [
+  "stopped",
+  "blocked",
+  "done",
+  "repeat",
+  "no_progress",
+  "limit:cycles",
+  "limit:cost",
+  "limit:time",
+] as const;
+export type StopReason = (typeof STOP_REASONS)[number];
+
+export interface Limits {
+  maxCycles: number;
+  maxCostUsd: number;
+  maxMinutes: number;
+  graceSeconds: number;
+  stallCycles: number;
+  repeatCycles: number;
+}
+
+export const DEFAULT_LIMITS: Limits = {
+  maxCycles: 8,
+  maxCostUsd: 15,
+  maxMinutes: 180,
+  graceSeconds: 30,
+  stallCycles: 3,
+  repeatCycles: 3,
+};
+
+export const LIMIT_BOUNDS = {
+  maxCycles: [1, 30],
+  maxCostUsd: [1, 200],
+  maxMinutes: [10, 24 * 60],
+  graceSeconds: [0, 300],
+  stallCycles: [2, 10],
+  repeatCycles: [2, 10],
+} as const satisfies Record<keyof Limits, readonly [number, number]>;
+
+export interface LoopRow extends Limits {
+  id: string;
+  sessionId: string;
+  workspaceId: string | null;
+  state: LoopState;
+  stopReason: StopReason | null;
+  stopDetail: string | null;
+  goal: string;
+  costBaseUsd: number;
+  startedAt: number;
+  endedAt: number | null;
+  lastCycleAt: number | null;
+  runNow: boolean;
+}
+
+export type CycleTrigger = "turn_end" | "ci" | "review" | "manual";
+
+// Where a cycle is. The steps before "decided" are redone after a restart;
+// "sending" is safe to redo because the message goes by a fixed id.
+export type CycleState =
+  | "claimed"
+  | "decided"
+  | "counting"
+  | "sending"
+  | "sent"
+  | "skipped"
+  | "stopped"
+  | "superseded"
+  | "error";
+
+export type Sender = "analyst" | "user";
+
+export interface Finding {
+  severity: "blocking" | "minor";
+  file?: string;
+  line?: number;
+  text: string;
+}
+
+export interface Analysis {
+  summary: string;
+  findings: Finding[];
+  criteria: {
+    id: number;
+    status: "met" | "open" | "failing";
+    evidence?: Evidence;
+  }[];
+  next: { instruction: string; focus: number[] } | null;
+  blocker: {
+    kind:
+      | "decision"
+      | "credential"
+      | "hard-line"
+      | "unclear-criteria"
+      | "environment";
+    text: string;
+  } | null;
+}
+
+export interface CommandResult {
+  name: "typecheck" | "test";
+  command: string;
+  exitCode: number | null;
+  durationMs: number;
+  passed: string[];
+  failed: string[];
+  errors: string[];
+  excerpt: string;
+  skipped?: string;
+}
+
+export interface EvidenceSummary {
+  green: boolean;
+  commands: CommandResult[];
+  ci: { name: string; state: string; sha?: string | null }[];
+  note?: string;
+}
+
+// The numbers "progress" is judged by: more met criteria, fewer failing
+// tests, fewer type errors.
+export interface Score {
+  met: number;
+  failingTests: number;
+  typeErrors: number;
+}
+
+export interface CycleRow {
+  id: number;
+  loopId: string;
+  n: number;
+  trigger: CycleTrigger;
+  state: CycleState;
+  snapshotSha: string | null;
+  tree: string | null;
+  changed: boolean;
+  evidence: EvidenceSummary | null;
+  logPath: string | null;
+  analysis: Analysis | null;
+  signature: string | null;
+  score: Score | null;
+  instruction: string | null;
+  instructionSent: string | null;
+  sender: Sender | null;
+  delivery: string | null;
+  sendAt: number | null;
+  input: string | null;
+  costUsd: number;
+  error: string | null;
+  startedAt: number;
+  endedAt: number | null;
+}
+
+// What the loop view shows.
+export interface LoopView {
+  loop: LoopRow;
+  // Why nothing is moving right now, when something is holding it.
+  hold: "paused" | "usage-window" | null;
+  holdReason: string | null;
+  spentUsd: number;
+  elapsedMs: number;
+  criteria: Criterion[];
+  cycles: CycleRow[];
+}
+
+// What the pill on a task row shows.
+export interface LoopSummary {
+  state: LoopState;
+  stopReason: StopReason | null;
+  cycle: number;
+  maxCycles: number;
+  met: number;
+  total: number;
+  hold: "paused" | "usage-window" | null;
+}
+
+export class LoopError extends Error {
+  constructor(
+    message: string,
+    readonly status = 409
+  ) {
+    super(message);
+  }
+}

package/lib/loops/world.test-helpers.ts

@@ -0,0 +1,223 @@
+// A stubbed world for the loop: a coder that ends turns and changes files, an
+// analyst that answers from a script, and a checks run that reports what the
+// scenario says, on a clock the test moves. No model, shell or chat.
+import { db, updateSessionRow } from "@/lib/db";
+import { createProject } from "@/lib/projects";
+import { createWorkspace, setProjectWorkspace } from "@/lib/workspaces";
+import { ensureOrchestrator } from "@/lib/orchestrator/home";
+import { seedSession } from "@/lib/orchestrator/testing";
+import type { SessionFacts } from "@/lib/orchestrator/facts";
+import type { LoopDeps } from "./deps";
+import { resetLoopMemory, tickLoops } from "./tickLoops";
+import { startLoop } from "./controls";
+import { latestLoopFor } from "./store";
+import type { Analysis, CommandResult, Limits } from "./types";
+
+export interface Scenario {
+  // The failing tests (and so the signature) of cycle n; [] is green.
+  failing: (n: number) => string[];
+  // How many criteria the analyst marks met in cycle n (citing the diff).
+  met: (n: number) => number;
+  // Spend by the end of cycle n, in dollars.
+  spent?: (n: number) => number;
+  // The coder changed nothing in this cycle's turn.
+  unchanged?: (n: number) => boolean;
+  // Words the analyst gives as the next instruction.
+  instruction?: (n: number) => string | null;
+  blocker?: (n: number) => Analysis["blocker"];
+}
+
+export const CRITERIA = Array.from({ length: 10 }, (_, i) => ({
+  text: `Criterion ${i + 1}`,
+}));
+
+export async function makeWorld(
+  scenario: Scenario,
+  limits: Partial<Limits> = {}
+) {
+  const ws = createWorkspace(
+    `loop-ws-${Math.random().toString(36).slice(2, 8)}`
+  );
+  const project = createProject({
+    name: `loop-app-${Math.random().toString(36).slice(2, 8)}`,
+    workingDirectory: "/tmp/loop-app",
+  });
+  setProjectWorkspace(project.id, ws.id);
+  ensureOrchestrator(ws.id);
+  const taskId = seedSession({
+    projectId: project.id,
+    name: "loop-task",
+    task: true,
+    view: "chat",
+    branch: "feature/x",
+  });
+  updateSessionRow(db, taskId, {
+    base_branch: "main",
+    task_prompt: "Build the thing",
+    worktree_path: "/tmp/loop-app",
+    workspace_id: ws.id,
+  });
+
+  const world = {
+    ws: ws.id,
+    taskId,
+    t: Date.parse("2026-10-21T12:00:00Z"),
+    rev: 1,
+    cycle: 0,
+    spent: 0,
+    sent: [] as string[],
+    running: false,
+    prompts: [] as string[],
+    fact: {
+      id: taskId,
+      name: "loop-task",
+      project: project.id,
+      view: "chat",
+      status: "idle",
+      activity: null,
+      needsInput: false,
+      lastActive: 0,
+      branch: "feature/x",
+      task: { state: "working", pr: null, blocked: null },
+      stack: null,
+    } as unknown as SessionFacts,
+  };
+  world.fact.lastActive = world.t - 10 * 60_000;
+
+  const deps: LoopDeps = {
+    now: () => world.t,
+    task: (id) =>
+      id === taskId
+        ? (db
+            .prepare(`SELECT * FROM session_rows WHERE id = ?`)
+            .get(id) as never)
+        : undefined,
+    prepare: async () => ({
+      repo: "/tmp/loop-app",
+      base: "origin/main",
+      dir: "/tmp/loop-app",
+    }),
+    snapshot: async () => ({
+      sha: `sha${world.rev}`,
+      tree: `tree${world.rev}`,
+    }),
+    commands: async () => ({ typecheck: null, test: "npm test" }),
+    testFiles: async () => [],
+    gather: async () => {
+      const n = world.cycle;
+      const failing = scenario.failing(n);
+      const test: CommandResult = {
+        name: "test",
+        command: "npm test",
+        exitCode: failing.length ? 1 : 0,
+        durationMs: 1000,
+        passed: failing.length ? [] : ["all.test.ts"],
+        failed: failing,
+        errors: [],
+        excerpt: failing.length ? failing.join("\n") : "",
+      };
+      return {
+        summary: { green: !failing.length, commands: [test], ci: [] },
+        signature: failing.length ? `test: ${failing.join("; ")}` : null,
+        logPath: null,
+      };
+    },
+    diff: async () => ({
+      map: "diff",
+      hunks: new Map([["a.ts", [[1, 100] as [number, number]]]]),
+    }),
+    analyse: async (input) => {
+      const n = world.cycle;
+      world.prompts.push(input.prompt.goal);
+      world.spent = scenario.spent?.(n) ?? world.spent;
+      const met = scenario.met(n);
+      const criteria = input.prompt.criteria;
+      return {
+        costUsd: 0,
+        analysis: {
+          summary: `Cycle ${n} summary`,
+          findings: [],
+          criteria: criteria.map((c, i) => ({
+            id: c.id,
+            status: i < met ? ("met" as const) : ("open" as const),
+            ...(i < met
+              ? {
+                  evidence: {
+                    kind: "diff" as const,
+                    ref: "a.ts:5",
+                    note: "changed",
+                  },
+                }
+              : {}),
+          })),
+          next:
+            scenario.instruction?.(n) === null
+              ? null
+              : {
+                  instruction:
+                    scenario.instruction?.(n) ??
+                    `Fix the failures from cycle ${n}`,
+                  focus: [],
+                },
+          blocker: scenario.blocker?.(n) ?? null,
+        },
+      };
+    },
+    send: async (_task, _loopId, _n, text) => {
+      world.sent.push(text);
+      world.running = true;
+      return "sent";
+    },
+    coderReply: () => null,
+    coderRunning: async () => false,
+    amendments: () => [],
+    spent: () => world.spent,
+    hold: () => null,
+    waitingOnPerson: () => null,
+  };
+  // The cycle number gather and analyse see is the one being claimed.
+  const real = deps.snapshot;
+  deps.snapshot = async (dir) => {
+    world.cycle = latestCycleN() ?? 0;
+    return real(dir);
+  };
+  const latestCycleN = () => {
+    const loop = latestLoopFor(taskId);
+    return loop
+      ? (
+          db
+            .prepare(
+              `SELECT MAX(n) AS n FROM task_loop_cycles WHERE loop_id = ?`
+            )
+            .get(loop.id) as { n: number | null }
+        ).n
+      : null;
+  };
+
+  resetLoopMemory();
+  await startLoop(
+    taskId,
+    { criteria: CRITERIA, limits: { graceSeconds: 0, ...limits } },
+    deps
+  );
+
+  const tick = () => tickLoops(world.ws, [world.fact], deps);
+  const state = () => latestLoopFor(taskId)!;
+  // The coder takes a turn (runs, then goes quiet), then the loop looks.
+  async function round() {
+    world.fact.status = "running";
+    await tick();
+    world.t += 60_000;
+    world.fact.status = "idle";
+    world.fact.lastActive = world.t - 30_000;
+    if (!scenario.unchanged?.(world.cycle)) world.rev++;
+    await tick();
+  }
+  async function run(maxRounds = 40) {
+    await tick();
+    for (let i = 0; i < maxRounds && state().state === "running"; i++)
+      await round();
+    return state();
+  }
+  return { world, deps, tick, round, run, state };
+}

package/lib/models/plan-step.ts

@@ -22,6 +22,7 @@ import { queueEvent } from "../orchestrator/events";
 import { recordAutoApproval } from "../approvals/no-approvals";
 import { addNote } from "../orchestrator/notes";
 import { amendBrief, scopeChangesOf } from "../orchestrator/amendments";
+import { ACCEPTANCE_PROMPT } from "../plans/acceptance";
 import { PIECES_PROMPT, foldedBrief, pieceBrief } from "../plans/pieces";
 import { orchestratorOf } from "../tasks/starter";
 import { isRemoteHost } from "../hosts";
@@ -46,7 +47,9 @@ export function planPrompt(task: string, only = false): string {
 ---
 Plan first. This turn, only read and plan: write the implementation plan for the task above to \`${PLAN_FILE}\` in this worktree (what to change, file by file; the tests; how you'll verify it; anything ambiguous and the call you'd make). Change no other file, and don't commit, push or open a PR. Don't end your turn while subagents or background commands you started are still running; wait for their results and write the plan in the same turn. End the turn once the plan is written: ${after}.
 
-${PIECES_PROMPT}`;
+${PIECES_PROMPT}
+
+${ACCEPTANCE_PROMPT}`;
 }
 
 export const PLAN_RETRY_PROMPT = `Write the plan to \`${PLAN_FILE}\` now, plan only.`;

package/lib/orchestrator/digest.ts

@@ -7,6 +7,7 @@
  * is by id, so the same database gives the same text.
  */
 
+import { loopDigestNote } from "../loops/summary";
 import { db } from "../db";
 import { openAsks } from "./asks";
 import { listRules } from "./rules";
@@ -185,7 +186,7 @@ function tasksSection(
         ? ` | ${t.pause_state}${t.paused_until ? ` until ${t.paused_until} UTC` : t.pause_state === "paused" ? " until resumed" : ""}${t.pause_note ? ` (${t.pause_note})` : ""}`
         : "";
       const placed = t.placed_note ? ` | ${t.placed_note}` : "";
-      return `- ${clip(t.name, 80)} (${t.project ?? "?"}, ${t.view}, id ${shortId(t.id)}): ${pr}${arm}${paused}${placed}${gates ? ` | ${gates}` : ""}`;
+      return `- ${clip(t.name, 80)} (${t.project ?? "?"}, ${t.view}, id ${shortId(t.id)}): ${pr}${arm}${paused}${placed}${loopDigestNote(t.id)}${gates ? ` | ${gates}` : ""}`;
     }),
     empty: "- None.",
     more: "the sessions tool",

package/lib/orchestrator/loop-guard.ts

@@ -76,9 +76,10 @@ const ERROR_LINE =
   /##\[error\]|\berror\b|\bfail(ed|ure|s)?\b|AssertionError|panic:/i;
 const RUNNER_EXIT = /Process completed with exit code/;
 
-// A CI failure: the job, then its failing tests, or its first error line.
+// A failure's log (CI, or a local test run): the job or command, then its
+// failing tests, or its first error line.
 // Null when there's nothing to tell one failure from another.
-export function ciSignature(
+export function failureSignature(
   check: string | null | undefined,
   log: string | null
 ): string | null {
@@ -100,6 +101,8 @@ export function ciSignature(
   return error ? cap(`${check}: ${normalize(error)}`) : null;
 }
 
+export const ciSignature = failureSignature;
+
 // A review's blocking findings, by where they are: the reviewer words the
 // same finding differently each time, but not its file and line. A finding
 // with no place is known by the start of its summary.

package/lib/orchestrator/pr-wake.ts

@@ -42,6 +42,7 @@ import { isPaused } from "./pause";
 import { repoOf } from "./repo";
 import { untrusted, UNTRUSTED_RULE } from "./untrusted";
 import { setPr } from "../db/session-parts";
+import { liveLoopFor } from "../loops/store";
 
 export const COMMENT_WAKE_CAP = 10;
 // A first look at a PR this young takes its whole history as new.
@@ -170,6 +171,9 @@ export async function wakeTasks(
   for (const w of watched) {
     if (isPaused(workspaceId)) return;
     if (w.pr.checks !== "fail" || !w.pr.failing) continue;
+    // A running loop reads CI as part of its evidence and tells the coder
+    // in its next instruction: a task never has two steerers.
+    if (liveLoopFor(w.task.id)) continue;
     await wakeOnCheck(workspaceId, w, deps).catch((error) =>
       console.error(`Waking ${w.task.name} on CI:`, error)
     );

package/lib/orchestrator/watcher.ts

@@ -26,6 +26,8 @@ import { followAskVerdicts } from "./ask-verdict";
 import { raiseHeldAsks } from "./held-asks";
 import { rebaseConflicting } from "./rebase";
 import { wakeTasks } from "./pr-wake";
+import { tickLoops } from "../loops/tickLoops";
+import { installReportHooks } from "../reports/hooks";
 import { awayTick } from "../away/run";
 import { healthTick } from "../health/tick";
 import { observeCi } from "../health/ci";
@@ -93,7 +95,8 @@ export async function diffWorkspace(
   return nextDiffAt(now, facts, working);
 }
 
-// Wakes tasks whose PRs failed CI or got reviews, rebases what conflicts
+// Wakes tasks whose PRs failed CI or got reviews, advances developer-analyst
+// loops, rebases what conflicts
 // with its base, then merges what's armed and passes. In the background, one run per workspace at a time, so a git
 // fetch or a merge never holds up event delivery.
 const piping = new Set<string>();
@@ -105,6 +108,9 @@ function mergePipeline(workspaceId: string, facts: SessionFacts[]): void {
     await wakeTasks(workspaceId, facts).catch((error) =>
       console.error(`Waking tasks in ${workspaceId}:`, error)
     );
+    await tickLoops(workspaceId, facts).catch((error) =>
+      console.error(`Ticking loops in ${workspaceId}:`, error)
+    );
     await followAskHeads(workspaceId, facts).catch((error) =>
       console.error(`Following ask heads in ${workspaceId}:`, error)
     );
@@ -189,6 +195,7 @@ async function tick(): Promise<void> {
 }
 
 export function startOrchestratorWatcher(): void {
+  installReportHooks();
   if (timer) return;
   timer = setInterval(() => void tick(), DELIVER_EVERY_MS);
   timer.unref();

package/lib/panes.ts

@@ -208,6 +208,58 @@ export function closePane(state: PaneState, paneId: string): PaneState | null {
   };
 }
 
+export interface OpenSession {
+  sessionId: string;
+  tmux: string;
+  hostId?: string | null;
+}
+
+// Shows a session beside a pane (an analyst beside its coder): where a pane
+// already shows it, that one; else in a new pane to its right; with no room
+// for another pane, in a new tab of this one.
+export function openBeside(
+  state: PaneState,
+  paneId: string,
+  open: OpenSession
+): PaneState {
+  for (const id of getAllPaneIds(state.layout)) {
+    const pane = state.panes[id];
+    const tab = pane?.tabs.find((t) => t.sessionId === open.sessionId);
+    if (tab)
+      return {
+        ...state,
+        focusedPaneId: id,
+        panes: { ...state.panes, [id]: { ...pane, activeTabId: tab.id } },
+      };
+  }
+  const tab: TabData = {
+    ...createTab(),
+    sessionId: open.sessionId,
+    attachedTmux: open.tmux,
+    attachedHost: open.hostId ?? null,
+  };
+  const split = state.panes[paneId] && splitPane(state, paneId, "horizontal");
+  if (split)
+    return {
+      ...split,
+      panes: {
+        ...split.panes,
+        [split.focusedPaneId]: { tabs: [tab], activeTabId: tab.id },
+      },
+    };
+  const pane = state.panes[paneId] ?? state.panes[state.focusedPaneId];
+  if (!pane) return state;
+  const target = state.panes[paneId] ? paneId : state.focusedPaneId;
+  return {
+    ...state,
+    focusedPaneId: target,
+    panes: {
+      ...state.panes,
+      [target]: { tabs: [...pane.tabs, tab], activeTabId: tab.id },
+    },
+  };
+}
+
 // Get all pane IDs from layout
 export function getAllPaneIds(layout: PaneLayout): string[] {
   if (layout.type === "leaf") {

package/lib/plans/acceptance.ts

@@ -0,0 +1,23 @@
+// A plan's optional "## Acceptance" section: a checklist of observable
+// outcomes, parsed like the "## Pieces" block.
+
+const MAX_ITEMS = 12;
+const MAX_LEN = 240;
+
+export function parseAcceptance(plan: string | null | undefined): string[] {
+  if (!plan) return [];
+  const lines = plan.split("\n");
+  const start = lines.findIndex((l) => /^##\s+Acceptance\s*$/i.test(l.trim()));
+  if (start < 0) return [];
+  const items: string[] = [];
+  for (const line of lines.slice(start + 1)) {
+    if (/^#{1,6}\s/.test(line)) break;
+    const m = /^\s*[-*]\s+\[[ xX]\]\s+(.+?)\s*$/.exec(line);
+    if (!m) continue;
+    items.push(m[1].slice(0, MAX_LEN));
+    if (items.length >= MAX_ITEMS) break;
+  }
+  return items;
+}
+
+export const ACCEPTANCE_PROMPT = `Also end the plan with an \`## Acceptance\` section: 3 to 8 checklist lines (\`- [ ] ...\`), each one outcome a test, a CI check or the review could show is true. They become the progress report's completion estimate.`;