@saadnvd1/agent-os 0.3.824 → 0.3.826

package/lib/fork/snapshot.ts

@@ -0,0 +1,69 @@
+/**
+ * What a child that can't have a copy of the conversation is told about
+ * where its parent stands: built from AgentOS's own records, the same pieces
+ * as the note after a compaction (lib/chat/compact-context).
+ */
+
+import os from "node:os";
+import { db, type Session } from "../db";
+import { statusPorcelain } from "../git-exec";
+import { lastItems } from "../chat/store";
+import { editedFiles } from "../chat/working-state";
+
+const EXCHANGES = 6;
+const CLIP = 700;
+const MAX = 10_000;
+
+const clip = (text: string, max = CLIP) =>
+  text.length > max ? `${text.slice(0, max)}…` : text;
+
+export async function parentSnapshot(parentId: string): Promise<string> {
+  const session = db
+    .prepare(
+      `SELECT name, working_directory, task_prompt FROM session_rows WHERE id = ?`
+    )
+    .get(parentId) as
+    Pick<Session, "name" | "working_directory" | "task_prompt"> | undefined;
+  if (!session) return "";
+  const parts: string[] = [`Parent session: ${session.name}`];
+  if (session.task_prompt?.trim())
+    parts.push(`## Its task\n${clip(session.task_prompt, 4_000)}`);
+  const said = lastItems(parentId, 60)
+    .filter((i) => i.kind === "user" || i.kind === "assistant")
+    .slice(-EXCHANGES * 2)
+    .map((i) =>
+      i.kind === "user"
+        ? `User: ${clip(i.text)}`
+        : i.kind === "assistant"
+          ? `Agent: ${clip(i.text)}`
+          : ""
+    )
+    .filter(Boolean);
+  if (said.length) parts.push(`## The latest exchanges\n${said.join("\n\n")}`);
+  const todos = lastItems(parentId, 1, "todos").find((i) => i.kind === "todos");
+  if (todos?.kind === "todos" && todos.todos.length)
+    parts.push(
+      `## Its todo list\n${todos.todos.map((t) => `- [${t.status}] ${t.text}`).join("\n")}`
+    );
+  const files = editedFiles(
+    lastItems(parentId, 400, "tool").filter((i) => i.kind === "tool")
+  );
+  if (files.length)
+    parts.push(
+      `## Files it was editing\n${files.map((f) => `- ${f}`).join("\n")}`
+    );
+  try {
+    const status = await statusPorcelain(
+      session.working_directory.replace(/^~/, os.homedir()),
+      { timeout: 3_000, maxBuffer: 64 * 1024 }
+    );
+    if (status.trim())
+      parts.push(
+        `## git status\n${status.split("\n").slice(0, 40).join("\n")}`
+      );
+  } catch {
+    // Not a repository, or git is slow: the rest stands.
+  }
+  const text = parts.join("\n\n");
+  return text.length > MAX ? `${text.slice(0, MAX)}\n… (cut)` : text;
+}

package/lib/fork/start.ts

@@ -0,0 +1,273 @@
+/**
+ * Starting forks: the ledger rows first (so a crash or a repeated request
+ * never doubles them), then each child's session in the background as the
+ * limits allow. A parent's first open child always starts, so a parent that
+ * holds a slot never waits on its own children.
+ */
+
+import os from "os";
+import { randomUUID } from "crypto";
+import { db, queries, type Session } from "../db";
+import type { AgentType } from "../providers";
+import { launchSession } from "../sessions/launch";
+import { sendChat } from "../chat/runner";
+import { saveItem } from "../chat/store";
+import { emit } from "../chat/registry";
+import { runInBackground } from "../async-operations";
+import { getProject } from "../projects";
+import { limitOf, runningIn, startingIn } from "../tasks/queue-rows";
+import { currentLevel, loadEnabled } from "../load/monitor";
+import { childFirstMessage } from "./brief";
+import { ForkError, forkConversation } from "./conversation";
+import {
+  childrenOf,
+  getChild,
+  groupByRequest,
+  groupChildren,
+  insertGroup,
+  markFellBack,
+  newGroupId,
+  numberOf,
+  openChildren,
+  setCut,
+  setState,
+} from "./ledger";
+import { FORK_LIMITS, FORKS_OFF, forksOn, type DeliveryMode } from "./options";
+import { ensureScratch, removeFork } from "./scratch";
+import { parentSnapshot } from "./snapshot";
+import { createForkWorktree } from "./worktree";
+import type { ChildRow } from "./types";
+
+const expand = (p: string) => p.replace(/^~(?=$|\/)/, os.homedir());
+
+const sessionOf = (id: string) =>
+  queries.getSession(db).get(id) as Session | undefined;
+
+export interface ForkRequest {
+  parentId: string;
+  // The caller's key for this call; a repeat returns the same group.
+  requestId: string;
+  instructions: string[];
+  labels?: string[];
+  worktree?: boolean;
+  startedBy: "agent" | "user";
+  delivery?: DeliveryMode;
+}
+
+export interface ForkStarted {
+  groupId: string;
+  repeat: boolean;
+  children: { id: string; n: number; label: string }[];
+}
+
+// Why this session can't fork, or null.
+export function refusal(parent: Session | undefined): string | null {
+  if (!forksOn()) return FORKS_OFF;
+  if (!parent) return "Unknown session";
+  if (getChild(parent.id)) return "A fork child can't fork";
+  if (parent.role === "orchestrator")
+    return "An orchestrator doesn't fork: start tasks or sessions instead";
+  if (parent.archived_at) return "That session is archived";
+  if (parent.view !== "chat") return "Forks work from a chat session";
+  if (parent.host_id && parent.host_id !== "local")
+    return "Forks run on this machine only";
+  return null;
+}
+
+const labelFor = (instruction: string, i: number) => {
+  const words = instruction.trim().split(/\s+/).slice(0, 5).join(" ");
+  return `${i + 1}. ${words.length > 40 ? `${words.slice(0, 39)}…` : words}`;
+};
+
+export function startFork(req: ForkRequest): ForkStarted {
+  const parent = sessionOf(req.parentId);
+  const refused = refusal(parent);
+  if (refused || !parent) throw new Error(refused ?? "Unknown session");
+  const again = groupByRequest(req.requestId);
+  if (again)
+    return {
+      groupId: again.id,
+      repeat: true,
+      children: groupChildren(again.id).map((c) => ({
+        id: c.child_session_id,
+        n: numberOf(parent.id, c.child_session_id),
+        label: c.label,
+      })),
+    };
+  const texts = req.instructions.map((t) => t.trim()).filter(Boolean);
+  if (!texts.length) throw new Error("Give each fork an instruction");
+  if (texts.length > FORK_LIMITS.maxPerFork)
+    throw new Error(`At most ${FORK_LIMITS.maxPerFork} forks at a time`);
+  if (texts.some((t) => t.length > FORK_LIMITS.instructionChars))
+    throw new Error(
+      `An instruction is over ${FORK_LIMITS.instructionChars} characters: put the detail in a file and point at it`
+    );
+  if (
+    openChildren(parent.id).length + texts.length >
+    FORK_LIMITS.maxOpenPerParent
+  )
+    throw new Error(
+      `${FORK_LIMITS.maxOpenPerParent} forks open at once is the most: wait for some to finish`
+    );
+  const claude = parent.agent_type === "claude";
+  // Only the Claude driver runs a guard, so any other agent's children get
+  // their own checkout instead.
+  const worktree = !claude || !!req.worktree;
+  const groupId = newGroupId();
+  const children = texts.map((instruction, i) => ({
+    childId: randomUUID(),
+    label: req.labels?.[i]?.trim() || labelFor(instruction, i),
+    instruction,
+    worktree,
+  }));
+  const noteId = `fork-${groupId}`;
+  insertGroup({
+    id: groupId,
+    parentId: parent.id,
+    requestId: req.requestId,
+    startedBy: req.startedBy,
+    context: claude ? "fork" : "brief",
+    delivery: req.delivery ?? (req.startedBy === "agent" ? "wake" : "next"),
+    forkItemId: noteId,
+    children,
+  });
+  const item = {
+    id: noteId,
+    kind: "note" as const,
+    tone: "note" as const,
+    createdAt: Date.now(),
+    text: `Forked ${children.length === 1 ? "1 copy" : `${children.length} copies`}: ${children.map((c) => c.label).join(" · ")}`,
+  };
+  saveItem(parent.id, item);
+  emit(parent.id, { type: "item", item });
+  const out = children.map((c) => ({
+    id: c.childId,
+    n: numberOf(parent.id, c.childId),
+    label: c.label,
+  }));
+  runInBackground(() => admitQueued(parent.id), `fork-admit-${groupId}`);
+  return { groupId, repeat: false, children: out };
+}
+
+const red = () => loadEnabled() && currentLevel() === "red";
+
+// Whether one more child of this parent may start, when it has none open.
+function mayStart(parent: Session, running: number): boolean {
+  if (running === 0) return true;
+  if (running >= FORK_LIMITS.maxRunningPerParent || red()) return false;
+  const project = getProject(parent.project_id ?? "");
+  const ws = project?.workspace_id ?? null;
+  const limit = limitOf(ws);
+  if (limit == null) return true;
+  const busy =
+    runningIn({ workspaceId: ws, projectId: parent.project_id ?? "" }, true)
+      .length + (ws ? startingIn(ws) : 0);
+  return busy < limit;
+}
+
+const STARTED = new Set<ChildRow["state"]>([
+  "starting",
+  "running",
+  "needs_input",
+]);
+
+// Starts what the limits allow, oldest first. Called when forks are made,
+// when one settles, and by the tick.
+export async function admitQueued(parentId: string): Promise<void> {
+  const parent = sessionOf(parentId);
+  if (!parent || parent.archived_at) return;
+  const all = childrenOf(parentId);
+  let running = all.filter((c) => STARTED.has(c.state)).length;
+  for (const c of all) {
+    if (c.state !== "queued") continue;
+    if (!mayStart(parent, running)) break;
+    setState(c.child_session_id, "starting");
+    running++;
+    runInBackground(
+      () => startChild(c.child_session_id),
+      `fork-child-${c.child_session_id}`
+    );
+  }
+}
+
+async function startChild(childId: string): Promise<void> {
+  const row = getChild(childId);
+  if (!row) return;
+  const parent = sessionOf(row.parent_session_id);
+  if (!parent) return;
+  try {
+    const parentCwd = expand(parent.working_directory);
+    await ensureScratch(childId);
+    const checkout = row.worktree
+      ? await createForkWorktree({ childId, parentCwd })
+      : null;
+    const cwd = checkout?.cwd ?? parentCwd;
+    const n = numberOf(parent.id, childId);
+    await launchSession({
+      id: childId,
+      projectId: parent.project_id,
+      workingDirectory: checkout?.cwd ?? parent.working_directory,
+      agentType: parent.agent_type as AgentType,
+      model: parent.model,
+      access: parent.chat_access,
+      autoApprove: !!parent.auto_approve,
+      name: `${parent.name} · fork ${n}`,
+      view: "chat",
+      parentSessionId: parent.id,
+      startedVia: "session",
+    });
+    db.prepare(
+      `UPDATE sessions SET conductor_session_id = ?, model_provider = ? WHERE id = ?`
+    ).run(parent.id, parent.model_provider, childId);
+    let snapshot: string | undefined;
+    if (parent.agent_type === "claude" && parent.claude_session_id) {
+      try {
+        const forked = await forkConversation({
+          claudeSessionId: parent.claude_session_id,
+          parentCwd,
+          childCwd: cwd,
+          title: `fork ${n} of ${parent.name}`,
+        });
+        db.prepare(
+          `UPDATE sessions SET claude_session_id = ?, chat_resume_at = NULL WHERE id = ?`
+        ).run(forked.claudeSessionId, childId);
+        setCut(childId, forked.cut);
+      } catch (error) {
+        if (!(error instanceof ForkError)) throw error;
+        markFellBack(childId);
+        snapshot = await parentSnapshot(parent.id);
+      }
+    } else snapshot = await parentSnapshot(parent.id);
+    const instruction = row.instruction;
+    await sendChat(childId, {
+      id: `fork-start-${childId}`,
+      text: childFirstMessage({
+        parentName: parent.name,
+        n,
+        instruction,
+        worktree: !!row.worktree,
+        scratch: await ensureScratch(childId),
+        snapshot,
+        checkout: checkout?.root,
+      }),
+      from: "AgentOS",
+      origin: {
+        kind: "event",
+        label: `Fork ${n} of ${parent.name}`,
+        sessionId: parent.id,
+        body: instruction,
+      },
+    });
+    setState(childId, "running");
+  } catch (error) {
+    const why = error instanceof Error ? error.message : String(error);
+    const { settleAndDeliver } = await import("./settle");
+    await removeFork(childId).catch(() => undefined);
+    await settleAndDeliver(childId, {
+      outcome: "failed",
+      summary: `couldn't start: ${why.split("\n")[0]}`,
+      result: `Fork didn't start: ${why}`,
+      kind: "implicit",
+    });
+  }
+}

package/lib/fork/tick.ts

@@ -0,0 +1,54 @@
+/** The fork watcher: looks at open children, delivers results, runs waits. */
+
+import { db } from "../db";
+import { admitQueued } from "./start";
+import { childrenOf } from "./ledger";
+import { deliverDue } from "./deliver";
+import { lookAtChild } from "./settle";
+import { tickForkWaits } from "./waits";
+import { forksOn } from "./options";
+import type { ChildRow } from "./types";
+
+const EVERY_MS = 5000;
+let running = false;
+let timer: NodeJS.Timeout | null = null;
+let kicked = false;
+
+export async function forksTick(now = Date.now()): Promise<void> {
+  if (running || !forksOn()) return;
+  running = true;
+  try {
+    const open = db
+      .prepare(`SELECT * FROM session_children WHERE state != 'settled'`)
+      .all() as ChildRow[];
+    for (const row of open) {
+      try {
+        await lookAtChild(row, now);
+      } catch (error) {
+        console.error(`[forks] child ${row.child_session_id}:`, error);
+      }
+    }
+    for (const parent of new Set(open.map((c) => c.parent_session_id)))
+      if (childrenOf(parent).some((c) => c.state === "queued"))
+        await admitQueued(parent);
+    await tickForkWaits(now);
+    await deliverDue(now);
+  } finally {
+    running = false;
+  }
+}
+
+export function kickForks(): void {
+  if (kicked) return;
+  kicked = true;
+  setImmediate(() => {
+    kicked = false;
+    void forksTick();
+  });
+}
+
+export function startForkWatcher(): void {
+  if (timer) return;
+  timer = setInterval(() => void forksTick(), EVERY_MS);
+  timer.unref();
+}

package/lib/fork/types.ts

@@ -0,0 +1,79 @@
+export type ChildState =
+  "queued" | "starting" | "running" | "needs_input" | "settled";
+
+export type ChildOutcome = "ok" | "failed" | "cancelled";
+
+// `implicit`: the child's turn ended without `aos return`, so its final
+// answer stands in (kept apart so stats can tell them).
+export type ResultKind = "explicit" | "implicit";
+
+export interface GroupRow {
+  id: string;
+  parent_session_id: string;
+  request_id: string;
+  started_by: "agent" | "user";
+  context: "fork" | "brief";
+  delivery: "wake" | "next";
+  fork_item_id: string | null;
+  created_at: number;
+  last_settled_at: number | null;
+}
+
+export interface ChildRow {
+  child_session_id: string;
+  parent_session_id: string;
+  group_id: string;
+  position: number;
+  label: string;
+  instruction: string;
+  worktree: number;
+  state: ChildState;
+  hold: string | null;
+  outcome: ChildOutcome | null;
+  summary: string | null;
+  result: string | null;
+  result_kind: ResultKind | null;
+  fell_back: number;
+  cut_message_id: string | null;
+  idle_since: number | null;
+  started_at: number | null;
+  settled_at: number | null;
+  tokens_in: number | null;
+  tokens_out: number | null;
+  cache_read: number | null;
+  heavy_runs: number;
+  delivered_at: number | null;
+  delivery_id: string | null;
+  used: "opened" | "mentioned" | null;
+  created_at: number;
+}
+
+// What a client shows for one child.
+export interface ChildView {
+  id: string;
+  n: number;
+  group: string;
+  label: string;
+  instruction: string;
+  state: ChildState;
+  hold: string | null;
+  outcome: ChildOutcome | null;
+  summary: string | null;
+  resultKind: ResultKind | null;
+  worktree: boolean;
+  fellBack: boolean;
+  startedAt: number | null;
+  settledAt: number | null;
+  delivered: boolean;
+  // A question or approval it's waiting on.
+  asks: string | null;
+}
+
+export interface GroupView {
+  id: string;
+  delivery: "wake" | "next";
+  context: "fork" | "brief";
+  startedBy: "agent" | "user";
+  createdAt: number;
+  stats: string | null;
+}

package/lib/fork/view.ts

@@ -0,0 +1,116 @@
+/** What clients and `aos children` show, and the numbers behind them. */
+
+import { childrenOf, getGroup } from "./ledger";
+import type { ChildRow, ChildView, GroupView } from "./types";
+
+export const childView = (c: ChildRow): ChildView => ({
+  id: c.child_session_id,
+  n: 0,
+  group: c.group_id,
+  label: c.label,
+  instruction: c.instruction,
+  state: c.state,
+  hold: c.hold,
+  outcome: c.outcome,
+  summary: c.summary,
+  resultKind: c.result_kind,
+  worktree: !!c.worktree,
+  fellBack: !!c.fell_back,
+  startedAt: c.started_at,
+  settledAt: c.settled_at,
+  delivered: c.delivered_at != null,
+  asks: c.state === "needs_input" ? c.hold : null,
+});
+
+export function childrenView(parentId: string): {
+  children: ChildView[];
+  groups: GroupView[];
+} {
+  const rows = childrenOf(parentId);
+  const seen = new Set<string>();
+  const groups: GroupView[] = [];
+  for (const c of rows) {
+    if (seen.has(c.group_id)) continue;
+    seen.add(c.group_id);
+    const g = getGroup(c.group_id);
+    if (g)
+      groups.push({
+        id: g.id,
+        delivery: g.delivery,
+        context: g.context,
+        startedBy: g.started_by,
+        createdAt: g.created_at,
+        stats: null,
+      });
+  }
+  return {
+    children: rows.map((c, i) => ({ ...childView(c), n: i + 1 })),
+    groups,
+  };
+}
+
+const median = (xs: number[]): number | null => {
+  if (!xs.length) return null;
+  const s = [...xs].sort((a, b) => a - b);
+  return s[Math.floor(s.length / 2)];
+};
+
+export interface ForkStats {
+  children: number;
+  settled: number;
+  ok: number;
+  failed: number;
+  cancelled: number;
+  implicit: number;
+  fellBack: number;
+  medianSeconds: number | null;
+  tokensIn: number;
+  tokensOut: number;
+  cacheRead: number;
+  heavyRuns: number;
+  delivered: number;
+  opened: number;
+  mentioned: number;
+}
+
+export function statsOf(rows: ChildRow[]): ForkStats {
+  const done = rows.filter((c) => c.state === "settled");
+  const sum = (f: (c: ChildRow) => number | null) =>
+    rows.reduce((n, c) => n + (f(c) ?? 0), 0);
+  return {
+    children: rows.length,
+    settled: done.length,
+    ok: done.filter((c) => c.outcome === "ok").length,
+    failed: done.filter((c) => c.outcome === "failed").length,
+    cancelled: done.filter((c) => c.outcome === "cancelled").length,
+    implicit: done.filter(
+      (c) => c.result_kind === "implicit" && c.outcome === "ok"
+    ).length,
+    fellBack: rows.filter((c) => c.fell_back).length,
+    medianSeconds: median(
+      done
+        .filter((c) => c.started_at && c.settled_at)
+        .map((c) => Math.round((c.settled_at! - c.started_at!) / 1000))
+    ),
+    tokensIn: sum((c) => c.tokens_in),
+    tokensOut: sum((c) => c.tokens_out),
+    cacheRead: sum((c) => c.cache_read),
+    heavyRuns: sum((c) => c.heavy_runs),
+    delivered: rows.filter((c) => c.delivered_at != null).length,
+    opened: rows.filter((c) => c.used === "opened").length,
+    mentioned: rows.filter((c) => c.used === "mentioned").length,
+  };
+}
+
+export function statsText(s: ForkStats): string {
+  const pct = (n: number) =>
+    s.settled ? `${Math.round((n / s.settled) * 100)}%` : "-";
+  return [
+    `${s.children} children, ${s.settled} settled (${s.ok} ok, ${s.failed} failed, ${s.cancelled} cancelled)`,
+    `returned without aos return: ${s.implicit} (${pct(s.implicit)}); started from a brief, not a fork: ${s.fellBack}`,
+    `median time to settle: ${s.medianSeconds ?? "-"}s`,
+    `tokens: ${s.tokensIn} in, ${s.tokensOut} out, ${s.cacheRead} cache read`,
+    `heavy runs queued: ${s.heavyRuns}`,
+    `results delivered: ${s.delivered}; opened in full: ${s.opened}; mentioned later: ${s.mentioned}`,
+  ].join("\n");
+}

package/lib/fork/waits.ts

@@ -0,0 +1,83 @@
+/** `aos wait children`: the parent ends its turn and is woken with results. */
+
+import { db } from "../db";
+import { numberOf, openChildren, childrenOf, undelivered } from "./ledger";
+import { deliverNow } from "./deliver";
+
+interface WaitRow {
+  id: number;
+  parent_session_id: string;
+  mode: "all" | "any";
+  created_at: number;
+  deadline: number;
+}
+
+export const MAX_WAIT_MS = 24 * 60 * 60_000;
+export const DEFAULT_WAIT_MS = 30 * 60_000;
+
+export const openForkWait = (parentId: string): WaitRow | undefined =>
+  db
+    .prepare(
+      `SELECT * FROM fork_waits WHERE parent_session_id = ? AND closed_at IS NULL`
+    )
+    .get(parentId) as WaitRow | undefined;
+
+export function registerForkWait(
+  parentId: string,
+  mode: "all" | "any",
+  timeoutMs = DEFAULT_WAIT_MS,
+  now = Date.now()
+): { id: number; deadline: number } | { already: string } {
+  const open = childrenOf(parentId).filter((c) => c.state !== "settled");
+  const waiting = undelivered(parentId);
+  if (!open.length && !waiting.length)
+    return { already: "you have no running forks and no unread results" };
+  const deadline = now + Math.min(Math.max(timeoutMs, 60_000), MAX_WAIT_MS);
+  // One wait per parent: a new one replaces it.
+  db.prepare(
+    `UPDATE fork_waits SET closed_at = ? WHERE parent_session_id = ? AND closed_at IS NULL`
+  ).run(now, parentId);
+  const { lastInsertRowid } = db
+    .prepare(
+      `INSERT INTO fork_waits (parent_session_id, mode, created_at, deadline) VALUES (?, ?, ?, ?)`
+    )
+    .run(parentId, mode, now, deadline);
+  return { id: Number(lastInsertRowid), deadline };
+}
+
+const close = (id: number, now: number): boolean =>
+  db
+    .prepare(
+      `UPDATE fork_waits SET closed_at = ? WHERE id = ? AND closed_at IS NULL`
+    )
+    .run(now, id).changes === 1;
+
+export async function tickForkWaits(now = Date.now()): Promise<void> {
+  const waits = db
+    .prepare(`SELECT * FROM fork_waits WHERE closed_at IS NULL`)
+    .all() as WaitRow[];
+  for (const w of waits) {
+    const ready = undelivered(w.parent_session_id);
+    const open = openChildren(w.parent_session_id);
+    const holds =
+      w.mode === "all"
+        ? open.length === 0
+        : ready.length > 0 || open.length === 0;
+    const timedOut = now >= w.deadline;
+    if (!holds && !timedOut) continue;
+    if (!close(w.id, now)) continue;
+    if (!ready.length && !timedOut) continue;
+    if (!ready.length) {
+      const { sendChat } = await import("../chat/runner");
+      await sendChat(w.parent_session_id, {
+        id: `fork-w-${w.id}`,
+        text: `[AgentOS: your wait on forks timed out; ${open.map((c) => numberOf(w.parent_session_id, c.child_session_id)).join(", ")} still running. \`aos children\` shows them.]`,
+        queue: true,
+        from: "AgentOS",
+        origin: { kind: "event", label: "Forks" },
+      });
+      continue;
+    }
+    await deliverNow(w.parent_session_id, ready);
+  }
+}