@saadnvd1/agent-os 0.3.715 → 0.3.728

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/agent-binding.ts

@@ -0,0 +1,102 @@
+/**
+ * Starting a session in an agent role: which model its binding gives it,
+ * whether that model's server answers, and what to run it on. A local model
+ * that's down never turns into a cloud one by itself: only a fallback the
+ * user set for the role, and only when the start asks for it.
+ */
+
+import { AGENT_ROLE_DEFS, type AgentRole } from "./agent-roles";
+import { modelAvailability, choiceFor } from "./catalog";
+import { savedModelSettings } from "./config";
+import { PI } from "./providers";
+import { resolveRole, type RoleSource, type RoutedModel } from "./resolve";
+
+export interface RoleBinding {
+  role: AgentRole;
+  routed: RoutedModel;
+  // The user's fallback for the role, if set.
+  fallback?: string;
+}
+
+export function bindingFor(
+  role: AgentRole,
+  opts: {
+    workspaceId?: string | null;
+    projectId?: string | null;
+    // The model picked for this one session.
+    override?: string | null;
+  } = {}
+): RoleBinding {
+  const modelRole = AGENT_ROLE_DEFS[role].modelRole;
+  const routed = resolveRole(modelRole, { ...opts, allowPi: true });
+  return {
+    role,
+    routed,
+    fallback: savedModelSettings().fallbacks?.[modelRole],
+  };
+}
+
+export class ModelUnavailableError extends Error {
+  readonly code = "model_unavailable";
+  constructor(
+    readonly role: AgentRole,
+    readonly ref: string,
+    readonly detail: string,
+    readonly fallback?: string
+  ) {
+    super(
+      `${AGENT_ROLE_DEFS[role].label}'s model ${ref} isn't answering${detail ? ` (${detail})` : ""}`
+    );
+  }
+}
+
+export interface RoleStart {
+  role: AgentRole;
+  routed: RoutedModel;
+  // "pi" runs the Pi agent on the model; "claude" runs Claude Code.
+  agentType: "claude" | "pi";
+  // What the agent CLI is given as its model.
+  model: string;
+  source: RoleSource | "fallback";
+}
+
+const startFrom = (
+  role: AgentRole,
+  routed: RoutedModel,
+  source: RoleStart["source"]
+): RoleStart =>
+  routed.provider.id === PI
+    ? {
+        role,
+        routed,
+        agentType: "pi",
+        model: routed.ref.slice(PI.length + 1),
+        source,
+      }
+    : { role, routed, agentType: "claude", model: routed.model, source };
+
+// The model a session started in `role` runs on, after checking its server.
+export async function prepareRoleStart(
+  role: AgentRole,
+  opts: Parameters<typeof bindingFor>[1] & { useFallback?: boolean }
+): Promise<RoleStart> {
+  const binding = bindingFor(role, opts);
+  const state = await modelAvailability(binding.routed.ref);
+  if (state.state !== "down")
+    return startFrom(role, binding.routed, binding.routed.source);
+  if (opts.useFallback && binding.fallback) {
+    const alt = bindingFor(role, { ...opts, override: binding.fallback });
+    const altState = await modelAvailability(alt.routed.ref);
+    if (altState.state !== "down")
+      return startFrom(role, alt.routed, "fallback");
+  }
+  throw new ModelUnavailableError(
+    role,
+    binding.routed.ref,
+    state.error ?? "",
+    binding.fallback &&
+      choiceFor(binding.fallback)?.availability.state !== "down"
+      ? binding.fallback
+      : undefined
+  );
+}

package/lib/models/agent-roles-view.ts

@@ -0,0 +1,157 @@
+/**
+ * What the Agent roles screen and the native app show: each role, the model
+ * saved at a scope, the model in force there and where it came from, and
+ * what the server knows of that model (local or cloud, answering or not).
+ * Saving checks what a role may run on.
+ */
+
+import {
+  AGENT_ROLES,
+  AGENT_ROLE_DEFS,
+  INTERNAL_MODEL_ROLES,
+  type AgentRole,
+} from "./agent-roles";
+import { choiceFor, type ModelChoice } from "./catalog";
+import {
+  effectiveModels,
+  projectModels,
+  savedModelSettings,
+  setModelSettings,
+  setProjectModels,
+  setWorkspaceModels,
+  workspaceModels,
+  type RoleMap,
+} from "./config";
+import { PI } from "./providers";
+import { resolveRole, type RoleSource } from "./resolve";
+import {
+  DEFAULT_ROLE_MODELS,
+  GATE_ROLES,
+  MODEL_ROLES,
+  ROLE_LABELS,
+  parseModelRef,
+  type ModelRole,
+} from "./roles";
+
+export type RoleScope = "settings" | "workspace" | "project";
+export interface ScopeRef {
+  scope: RoleScope;
+  id?: string | null;
+}
+
+export interface RoleView {
+  modelRole: ModelRole;
+  label: string;
+  hint: string;
+  // Saved at this scope, or null when it inherits.
+  value: string | null;
+  binding: { ref: string; source: RoleSource } | null;
+  fallback: string | null;
+  choice: ModelChoice | null;
+  // Why the binding can't be used (a provider turned off).
+  error?: string;
+  default: string;
+}
+
+export interface AgentRoleView extends RoleView {
+  id: AgentRole;
+  purpose: string;
+  brief: string;
+  edits: boolean;
+}
+
+function savedAt({ scope, id }: ScopeRef): RoleMap {
+  if (scope === "workspace" && id) return workspaceModels(id).roles ?? {};
+  if (scope === "project" && id) return projectModels(id).roles ?? {};
+  return savedModelSettings().roles ?? {};
+}
+
+function viewOf(modelRole: ModelRole, at: ScopeRef, ctx: ContextIds): RoleView {
+  const effective = effectiveModels();
+  let binding: RoleView["binding"] = null;
+  let error: string | undefined;
+  try {
+    const r = resolveRole(modelRole, { ...ctx, allowPi: true }, effective);
+    binding = { ref: r.ref, source: r.source };
+  } catch (e) {
+    error = e instanceof Error ? e.message : String(e);
+  }
+  return {
+    modelRole,
+    label: ROLE_LABELS[modelRole].label,
+    hint: ROLE_LABELS[modelRole].hint,
+    value: savedAt(at)[modelRole] ?? null,
+    binding,
+    fallback: savedModelSettings().fallbacks?.[modelRole] ?? null,
+    choice: binding ? (choiceFor(binding.ref, effective) ?? null) : null,
+    ...(error ? { error } : {}),
+    default: DEFAULT_ROLE_MODELS[modelRole],
+  };
+}
+
+interface ContextIds {
+  workspaceId?: string | null;
+  projectId?: string | null;
+}
+
+const contextOf = ({ scope, id }: ScopeRef): ContextIds =>
+  scope === "workspace"
+    ? { workspaceId: id }
+    : scope === "project"
+      ? { projectId: id }
+      : {};
+
+export function agentRolesView(at: ScopeRef, ctx?: ContextIds) {
+  const ids = ctx ?? contextOf(at);
+  return {
+    roles: AGENT_ROLES.map((id): AgentRoleView => ({
+      ...viewOf(AGENT_ROLE_DEFS[id].modelRole, at, ids),
+      id,
+      label: AGENT_ROLE_DEFS[id].label,
+      hint: AGENT_ROLE_DEFS[id].purpose,
+      purpose: AGENT_ROLE_DEFS[id].purpose,
+      brief: AGENT_ROLE_DEFS[id].brief,
+      edits: AGENT_ROLE_DEFS[id].edits,
+    })),
+    internal: INTERNAL_MODEL_ROLES(MODEL_ROLES).map((r) => viewOf(r, at, ids)),
+  };
+}
+
+// The models a role can be bound to: a Pi model runs a role session only,
+// never a task, a gate or the orchestrator.
+const PI_ROLES: readonly ModelRole[] = ["implement", "analyze", "advise"];
+
+function checkRoles(roles: RoleMap): void {
+  for (const [role, ref] of Object.entries(roles) as [ModelRole, string][]) {
+    if (parseModelRef(ref).provider !== PI) continue;
+    if (!PI_ROLES.includes(role))
+      throw new Error(
+        `${ROLE_LABELS[role].label} can't run on a Pi model (${GATE_ROLES.includes(role) ? "a merge gate needs Claude Code" : "only the Developer, Analyst and Reviewer can"})`
+      );
+  }
+}
+
+export function saveAgentRoles(
+  at: ScopeRef,
+  roles: RoleMap,
+  fallbacks?: RoleMap
+): void {
+  checkRoles(roles);
+  if (fallbacks) {
+    for (const ref of Object.values(fallbacks))
+      if (ref && parseModelRef(ref).provider === PI)
+        throw new Error("A fallback must be a cloud or Claude Code model");
+  }
+  if (at.scope === "settings") {
+    const saved = savedModelSettings();
+    setModelSettings({
+      ...saved,
+      roles,
+      ...(fallbacks ? { fallbacks } : {}),
+    });
+    return;
+  }
+  if (!at.id) throw new Error(`${at.scope} needs an id`);
+  if (at.scope === "workspace") setWorkspaceModels(at.id, { roles });
+  else setProjectModels(at.id, { roles });
+}