@saadnvd1/agent-os 0.3.723 → 0.3.728

package/lib/loops/runCycle.ts

@@ -0,0 +1,323 @@
+import type { Session } from "../db";
+import type { SessionFacts } from "../orchestrator/facts";
+import { checkCriteria } from "./checkCriteria";
+import { evidenceText, scoreOf } from "./compactEvidence";
+import { decideStop, type Stop } from "./decideStop";
+import type { LoopDeps } from "./deps";
+import { callHook } from "./hooks";
+import { instructionText, mirrorToPairing } from "./sendInstruction";
+import { screenInstruction } from "./screenInstruction";
+import {
+  claimCycle,
+  criteriaOf,
+  cycleCount,
+  cyclesOf,
+  getCycle,
+  getLoop,
+  markCriterion,
+  moveCycle,
+  patchCycle,
+  touchLoop,
+} from "./store";
+import { finishLoop } from "./stopLoop";
+import type { CycleRow, CycleTrigger, EvidenceSummary, LoopRow } from "./types";
+
+// A turn that ends with nothing changed: nudge, don't spend a model run.
+export const NO_CHANGE_NUDGE =
+  "Your last turn changed nothing in the worktree. Take the first open acceptance criterion and make a concrete change for it, then run the checks. If something is stopping you, say so on a line starting with BLOCKED:.";
+
+const inflight = new Set<string>();
+export const cycleInFlight = (loopId: string) => inflight.has(loopId);
+
+const BLOCKED_LINE = /^\s*BLOCKED:\s*(.+)$/m;
+const RETRY_AFTER_ERROR_MS = 60_000;
+const SEND_RETRY_MS = 15_000;
+
+interface Ctx {
+  loop: LoopRow;
+  task: Session;
+  facts: SessionFacts | undefined;
+  deps: LoopDeps;
+}
+
+const nameOf = (task: Session) => task.name;
+
+function stop(ctx: Ctx, s: Stop): void {
+  finishLoop(ctx.loop, s, { taskName: nameOf(ctx.task), now: ctx.deps.now() });
+}
+
+// Opens a cycle and runs it to the point where an instruction waits to be
+// sent (or the loop stopped). One at a time per loop.
+export async function startCycle(
+  loopId: string,
+  trigger: CycleTrigger,
+  facts: SessionFacts | undefined,
+  deps: LoopDeps
+): Promise<void> {
+  if (inflight.has(loopId)) return;
+  const loop = getLoop(loopId);
+  const task = loop && deps.task(loop.sessionId);
+  if (!loop || loop.state !== "running" || !task) return;
+  const cycle = claimCycle(loop.id, trigger, deps.now());
+  if (!cycle) return;
+  await processCycle({ loop, task, facts, deps }, cycle);
+}
+
+// Runs a claimed cycle; after a restart it picks the same row up again.
+export async function processCycle(ctx: Ctx, cycle: CycleRow): Promise<void> {
+  if (inflight.has(ctx.loop.id)) return;
+  inflight.add(ctx.loop.id);
+  try {
+    await analyseCycle(ctx, cycle);
+  } catch (error) {
+    const why = error instanceof Error ? error.message : String(error);
+    patchCycle(ctx.loop.id, cycle.n, {
+      state: "error",
+      error: why.slice(0, 500),
+      endedAt: ctx.deps.now(),
+    });
+    const recent = cyclesOf(ctx.loop.id, { limit: 2 });
+    if (recent.length === 2 && recent.every((c) => c.state === "error"))
+      stop(ctx, {
+        reason: "blocked",
+        detail: `The cycle failed twice: ${why.slice(0, 200)}`,
+      });
+  } finally {
+    inflight.delete(ctx.loop.id);
+  }
+}
+
+async function analyseCycle(ctx: Ctx, cycle: CycleRow): Promise<void> {
+  const { loop, task, deps } = ctx;
+  const previous = cyclesOf(loop.id, { limit: 10 }).filter(
+    (c) => c.n < cycle.n
+  );
+  const lastSnap = previous.find((c) => c.snapshotSha);
+  const prepared = await deps.prepare(task);
+  const snap = await deps.snapshot(prepared.dir);
+  const changed = !lastSnap?.tree || lastSnap.tree !== snap.tree;
+  const reply = deps.coderReply(task);
+
+  let evidence: EvidenceSummary;
+  let signature: string | null;
+  let analysis: CycleRow["analysis"] = null;
+  let costUsd = 0;
+  let marksMet: number;
+
+  if (!changed && lastSnap?.evidence) {
+    // Nothing to inspect that the last cycle didn't: its evidence stands.
+    evidence = lastSnap.evidence;
+    signature = lastSnap.signature;
+    marksMet = criteriaOf(loop.id).filter(
+      (c) => c.status === "met" || c.status === "waived"
+    ).length;
+    patchCycle(loop.id, cycle.n, {
+      snapshotSha: snap.sha,
+      tree: snap.tree,
+      changed: false,
+      evidence,
+      signature,
+    });
+  } else {
+    const commands = await deps.commands(prepared.repo, prepared.base);
+    const testFiles = await deps.testFiles(
+      prepared.dir,
+      prepared.base,
+      snap.sha
+    );
+    const gathered = await deps.gather({
+      taskId: task.id,
+      n: cycle.n,
+      dir: prepared.dir,
+      commands,
+      testFiles,
+    });
+    const pr = ctx.facts?.task?.pr;
+    const ci = pr
+      ? [
+          {
+            name: pr.failing ?? "checks",
+            state: pr.checks === "pass" ? "success" : String(pr.checks),
+            sha: pr.head ?? null,
+          },
+        ]
+      : [];
+    evidence = { ...gathered.summary, ci };
+    signature = gathered.signature;
+    patchCycle(loop.id, cycle.n, {
+      snapshotSha: snap.sha,
+      tree: snap.tree,
+      changed: true,
+      evidence,
+      logPath: gathered.logPath,
+      signature,
+    });
+    const diff = await deps.diff(
+      prepared.dir,
+      prepared.base,
+      snap.sha,
+      lastSnap?.snapshotSha ?? null
+    );
+    const wake =
+      pr && pr.checks === "fail" && pr.failing
+        ? `CI check "${pr.failing}" is failing on the PR's head.`
+        : null;
+    const result = await deps.analyse({
+      repo: prepared.repo,
+      sha: snap.sha,
+      workspaceId: loop.workspaceId,
+      prompt: {
+        goal: task.task_prompt || loop.goal,
+        amendments: deps.amendments(task.id),
+        criteria: criteriaOf(loop.id),
+        evidence: evidenceText(evidence.commands, ci),
+        diffMap: diff.map,
+        recent: previous.slice(0, 2).reverse(),
+        coderReply: reply,
+        wake,
+      },
+    });
+    analysis = result.analysis;
+    costUsd = result.costUsd;
+    const marks = checkCriteria(criteriaOf(loop.id), analysis, {
+      green: evidence.green,
+      commands: evidence.commands,
+      hunks: diff.hunks,
+      ci,
+      snapshotSha: snap.sha,
+    });
+    for (const m of marks)
+      markCriterion(m.id, m.status, m.evidence, m.verified, cycle.n);
+    marksMet = marks.filter(
+      (m) => m.status === "met" || m.status === "waived"
+    ).length;
+  }
+
+  const score = scoreOf(evidence.commands, marksMet);
+  patchCycle(loop.id, cycle.n, {
+    analysis,
+    score,
+    costUsd,
+    input: reply ? reply.slice(0, 2000) : null,
+  });
+  callHook("onCycleSettled", {
+    taskId: task.id,
+    cycleId: cycle.id,
+    analystSummary: analysis?.summary ?? null,
+  });
+
+  // The user typed to the coder meanwhile: their message wins.
+  if (await deps.coderRunning(task)) {
+    moveCycle(loop.id, cycle.n, ["claimed"], {
+      state: "superseded",
+      endedAt: deps.now(),
+    });
+    return;
+  }
+
+  const criteria = criteriaOf(loop.id);
+  const finished = cyclesOf(loop.id, { limit: 40 })
+    .filter((c) => c.score)
+    .reverse();
+  const blocked =
+    analysis?.blocker?.text ??
+    BLOCKED_LINE.exec(reply ?? "")?.[1]?.trim() ??
+    (ctx.facts?.needsInput
+      ? "the coding agent is waiting for an answer"
+      : null) ??
+    deps.waitingOnPerson(task);
+  const fresh = getLoop(loop.id)!;
+  const draft = changed
+    ? (analysis?.next?.instruction ?? null)
+    : NO_CHANGE_NUDGE;
+  const decided = decideStop({
+    limits: fresh,
+    startedAt: fresh.startedAt,
+    cycles: finished,
+    cycleCount: cycleCount(loop.id),
+    criteria,
+    green: evidence.green,
+    spentUsd: deps.spent(fresh),
+    now: deps.now(),
+    blocked,
+  });
+  if (decided) {
+    patchCycle(loop.id, cycle.n, {
+      instruction: decided.reason === "done" ? null : draft,
+    });
+    stop(ctx, decided);
+    return;
+  }
+  if (!draft) {
+    patchCycle(loop.id, cycle.n, {});
+    stop(ctx, {
+      reason: "blocked",
+      detail: "The analyst has no next step, but criteria are still open",
+    });
+    return;
+  }
+  const refused = screenInstruction(draft);
+  if (refused) {
+    patchCycle(loop.id, cycle.n, { instruction: draft });
+    stop(ctx, {
+      reason: "blocked",
+      detail: `The next instruction was held back: ${refused.why}`,
+      askKind: refused.kind,
+    });
+    return;
+  }
+  const grace = fresh.graceSeconds;
+  patchCycle(loop.id, cycle.n, {
+    instruction: draft,
+    sender: "analyst",
+    sendAt: deps.now() + grace * 1000,
+  });
+  moveCycle(loop.id, cycle.n, ["claimed"], { state: "counting" });
+  touchLoop(loop.id, deps.now());
+  if (grace === 0) await deliverCycle({ ...ctx, loop: fresh }, cycle.n);
+}
+
+// Sends a cycle's instruction once (the state move claims it). A failed
+// send goes back to counting; a second failure stops the loop.
+export async function deliverCycle(ctx: Ctx, n: number): Promise<boolean> {
+  const { loop, task, deps } = ctx;
+  const before = getCycle(loop.id, n);
+  if (!before || !before.instruction) return false;
+  if (!moveCycle(loop.id, n, ["counting", "decided"], { state: "sending" }))
+    return false;
+  const open = criteriaOf(loop.id).filter(
+    (c) => c.status !== "met" && c.status !== "waived"
+  );
+  const text =
+    before.instructionSent ?? instructionText(before.instruction, open);
+  try {
+    const delivery = await deps.send(task, loop.id, n, text);
+    patchCycle(loop.id, n, {
+      state: "sent",
+      delivery,
+      instructionSent: text,
+      sender: before.sender ?? "analyst",
+      error: null,
+      endedAt: deps.now(),
+    });
+    touchLoop(loop.id, deps.now());
+    mirrorToPairing(task.id, loop.id, n, text, before.analysis);
+    return true;
+  } catch (error) {
+    const why = error instanceof Error ? error.message : String(error);
+    patchCycle(loop.id, n, {
+      state: "counting",
+      sendAt: deps.now() + SEND_RETRY_MS,
+      error: why.slice(0, 300),
+    });
+    if (before.error) {
+      stop(ctx, {
+        reason: "blocked",
+        detail: `The instruction couldn't be delivered: ${why.slice(0, 200)}`,
+      });
+    }
+    return false;
+  }
+}
+
+export const RETRY_MS = RETRY_AFTER_ERROR_MS;

package/lib/loops/screenInstruction.ts

@@ -0,0 +1,59 @@
+import type { AskKind } from "../orchestrator/ask-view";
+
+export interface Refusal {
+  kind: AskKind;
+  why: string;
+}
+
+// Command-shaped on purpose: the broad ask classifier would trip on
+// "token" in ordinary code, and an instruction about a token fixture is
+// fine. These are the things the loop must never tell the coder to do.
+const RULES: { kind: AskKind; why: string; re: RegExp }[] = [
+  {
+    kind: "irreversible",
+    why: "it tells the coder to merge",
+    re: /\b(?:gh\s+pr\s+merge|git\s+merge\b[^.\n]*\b(?:main|master)\b|merge\s+(?:the\s+|this\s+)?(?:pr|pull request)\b|(?:squash|rebase)[- ]and[- ]merge)/i,
+  },
+  {
+    kind: "irreversible",
+    why: "it tells the coder to push to the default branch or force-push",
+    re: /\bgit\s+push\b[^.\n]*(?:--force\b|--force-with-lease|\s-f\b|\b(?:origin\s+)?(?:main|master)\b)|\bforce[- ]push\b/i,
+  },
+  {
+    kind: "public",
+    why: "it tells the coder to publish or release",
+    re: /\b(?:npm|pnpm|yarn|bun)\s+publish\b|\bcargo\s+publish\b|\btwine\s+upload\b|\bgh\s+release\s+create\b|\bpublish\s+(?:the\s+|this\s+)?(?:package|release|build|version)\b|\bcut\s+a\s+release\b|\bgit\s+tag\b[^.\n]*\bpush\b/i,
+  },
+  {
+    kind: "public",
+    why: "it tells the coder to deploy",
+    re: /\bdeploy\s+(?:it\s+|this\s+|the\s+[\w -]{0,30})?(?:to|on)\s+(?:prod|production|staging|the\s+(?:server|box|cluster))\b|\b(?:kubectl\s+apply|terraform\s+apply|vercel\s+--prod|fly\s+deploy|helm\s+upgrade)\b/i,
+  },
+  {
+    kind: "public",
+    why: "it tells the coder to post or send something outbound",
+    re: /\b(?:send|post|tweet|publish)\s+(?:an?\s+|the\s+)?(?:email|e-mail|message|tweet|post|announcement|slack message)\s+to\b|\bgh\s+(?:issue|pr)\s+comment\b|\bcurl\b[^\n]*\s-X\s*(?:POST|PUT|DELETE)\b/i,
+  },
+  {
+    kind: "credentials",
+    why: "it tells the coder to read or change credentials",
+    re: /\b(?:print|cat|echo|dump|exfiltrate|send|upload)\b[^.\n]{0,40}(?:\.env\b|\bapi[_ -]?key|private key|ssh key|keychain|secrets?\b(?!\s+fixture))|\brotate\s+(?:the\s+)?(?:production|prod|live)\s+(?:key|token|secret|password)/i,
+  },
+  {
+    kind: "irreversible",
+    why: "it tells the coder to delete data outside the worktree",
+    re: /\brm\s+-[a-z]*r[a-z]*f?\s+(?:~|\/(?!tmp\b)|\$HOME)|\bdrop\s+(?:table|database)\b|\bgit\s+(?:reset\s+--hard|clean\s+-[a-z]*f)\b[^.\n]*\borigin\b|\bdelete\s+(?:the\s+)?(?:remote\s+)?branch\b/i,
+  },
+  {
+    kind: "money",
+    why: "it tells the coder to spend money",
+    re: /\b(?:purchase|buy|subscribe to|upgrade (?:the )?(?:plan|subscription))\b[^.\n]{0,40}\b(?:license|plan|subscription|credits|domain)\b|\b(?:charge|bill)\s+(?:the\s+)?(?:card|customer)/i,
+  },
+];
+
+// The first rule the text breaks, or null.
+export function screenInstruction(text: string): Refusal | null {
+  for (const r of RULES)
+    if (r.re.test(text)) return { kind: r.kind, why: r.why };
+  return null;
+}

package/lib/loops/sendInstruction.ts

@@ -0,0 +1,83 @@
+import { deliver } from "../bus";
+import { forwardToCoder } from "../analyst/forward";
+import {
+  insertRecommendation,
+  decideRecommendation,
+  liveLinkFor,
+} from "../analyst/store";
+import type { Session } from "../db";
+import { statusDetector } from "../status-detector";
+import type { Analysis } from "./types";
+
+export const LOOP_LABEL = "Analyst loop";
+
+// The id the chat keeps the message by, so a resend after a restart is a
+// no-op.
+export const instructionId = (loopId: string, n: number) =>
+  `loop-${loopId}-${n}`;
+
+// The instruction as the coder reads it: the instruction, then which
+// criteria are still open.
+export function instructionText(
+  instruction: string,
+  open: { id: number; text: string }[]
+): string {
+  const list = open.length
+    ? `\n\nStill open (acceptance criteria):\n${open.map((c) => `${c.id}. ${c.text}`).join("\n")}`
+    : "";
+  return `${instruction.trim()}${list}`;
+}
+
+// Hands the instruction to the task's agent: a chat's next prompt (the
+// analyst-forward path, by id) or typed into a terminal. Throws when it
+// could not be delivered. Returns how it went.
+export async function sendInstruction(
+  task: Session,
+  loopId: string,
+  n: number,
+  text: string
+): Promise<string> {
+  if (task.view === "chat") {
+    await forwardToCoder(task.id, {
+      text,
+      id: instructionId(loopId, n),
+      label: LOOP_LABEL,
+    });
+    return "sent";
+  }
+  await statusDetector.refreshCache();
+  const delivery = await deliver(task, text, { name: LOOP_LABEL });
+  if (delivery.state === "failed") throw new Error(delivery.why);
+  return delivery.state;
+}
+
+// A paired analyst's split view shows the same history: the instruction as
+// a sent card. Best effort; the loop never depends on it.
+export function mirrorToPairing(
+  taskId: string,
+  loopId: string,
+  n: number,
+  text: string,
+  analysis: Analysis | null
+): void {
+  try {
+    const link = liveLinkFor(taskId);
+    if (link?.coderSessionId !== taskId) return;
+    const itemId = instructionId(loopId, n);
+    const rec = insertRecommendation({
+      linkId: link.id,
+      analystItemId: itemId,
+      coderThrough: null,
+      signals: null,
+      verdict: "continue",
+      summary: analysis?.summary ?? "",
+      issues: [],
+      prompt: text,
+      state: "open",
+    });
+    if (rec)
+      decideRecommendation(rec.id, "sent", { text, itemId, edited: false });
+  } catch {
+    // The loop goes on.
+  }
+}

package/lib/loops/snapshot.ts

@@ -0,0 +1,38 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { git } from "../git-exec";
+
+// A commit of the worktree as it is, uncommitted work included, made with a
+// throwaway index so the real index, the stash and the branch don't move.
+// A clean worktree is HEAD itself. Untracked files that .gitignore hides stay
+// out, as they do for any commit.
+export async function snapshotWorktree(dir: string): Promise<string> {
+  const head = (await git(dir, ["rev-parse", "HEAD"])).trim();
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "aos-loop-idx-"));
+  const env = { GIT_INDEX_FILE: path.join(tmp, "index") };
+  try {
+    await git(dir, ["read-tree", "HEAD"], { env });
+    await git(dir, ["add", "-A"], { env });
+    const tree = (await git(dir, ["write-tree"], { env })).trim();
+    const headTree = (await git(dir, ["rev-parse", "HEAD^{tree}"])).trim();
+    if (tree === headTree) return head;
+    return (
+      await git(
+        dir,
+        ["commit-tree", tree, "-p", head, "-m", "AgentOS loop snapshot"],
+        {
+          env: {
+            ...env,
+            GIT_AUTHOR_NAME: "AgentOS",
+            GIT_AUTHOR_EMAIL: "agentos@localhost",
+            GIT_COMMITTER_NAME: "AgentOS",
+            GIT_COMMITTER_EMAIL: "agentos@localhost",
+          },
+        }
+      )
+    ).trim();
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}

package/lib/loops/stopLoop.ts

@@ -0,0 +1,86 @@
+import { raiseAsk, AskRefused, taskSubject } from "../orchestrator/asks";
+import { queueEventOnce } from "../orchestrator/events";
+import { addNote } from "../orchestrator/notes";
+import type { Stop } from "./decideStop";
+import { callHook } from "./hooks";
+import { getLoop, cyclesOf, moveCycle, stopLoopRow } from "./store";
+import type { LoopRow, StopReason } from "./types";
+
+export const REASON_LABEL: Record<StopReason, string> = {
+  stopped: "stopped by you",
+  blocked: "needs you",
+  done: "all criteria met",
+  repeat: "the same failure kept coming back",
+  no_progress: "no progress",
+  "limit:cycles": "reached its cycle limit",
+  "limit:cost": "reached its cost cap",
+  "limit:time": "reached its time limit",
+};
+
+// These raise an ask: the loop stopped short of done and someone has to
+// decide. Done and the user's own stop don't.
+const ASKS: StopReason[] = [
+  "blocked",
+  "repeat",
+  "no_progress",
+  "limit:cycles",
+  "limit:cost",
+  "limit:time",
+];
+
+// Ends a running loop once. The cycle in flight is closed, its undelivered
+// instruction kept as the draft, the orchestrator told, an ask raised when
+// someone has to decide, and the operating mode handed back.
+export function finishLoop(
+  loop: LoopRow,
+  stop: Stop,
+  opts: { taskName: string; now: number }
+): boolean {
+  if (!stopLoopRow(loop.id, stop.reason, stop.detail, opts.now)) return false;
+  const last = cyclesOf(loop.id, { limit: 1 })[0];
+  let pending: string | null = null;
+  if (last) {
+    pending = last.instruction;
+    const unsent = ["claimed", "decided", "counting", "sending"] as const;
+    if (unsent.includes(last.state as (typeof unsent)[number]))
+      moveCycle(loop.id, last.n, [...unsent], {
+        state: "stopped",
+        endedAt: opts.now,
+      });
+  }
+  const label = REASON_LABEL[stop.reason];
+  const text = `Loop on ${opts.taskName}: ${label}${stop.detail && stop.reason !== "stopped" ? ` (${stop.detail})` : ""}.`;
+  if (loop.workspaceId) {
+    try {
+      addNote(loop.workspaceId, text);
+    } catch {}
+    try {
+      queueEventOnce(
+        loop.workspaceId,
+        `loop:${loop.sessionId}:${loop.id}:${stop.reason}`,
+        loop.sessionId,
+        text
+      );
+    } catch {}
+    if (ASKS.includes(stop.reason)) {
+      try {
+        raiseAsk({
+          workspaceId: loop.workspaceId,
+          subject: taskSubject(loop.sessionId),
+          kind: stop.askKind ?? "decision",
+          title: `Loop on ${opts.taskName} ${label}`,
+          detail: [
+            stop.detail,
+            pending ? `The next instruction was not sent:\n${pending}` : "",
+          ]
+            .filter(Boolean)
+            .join("\n\n"),
+        });
+      } catch (error) {
+        if (!(error instanceof AskRefused)) console.error("Loop ask:", error);
+      }
+    }
+  }
+  callHook("onStop", getLoop(loop.id) ?? loop, stop, pending);
+  return true;
+}