@saadnvd1/agent-os 0.3.821 → 0.3.825

package/lib/fork/settle.ts

@@ -0,0 +1,215 @@
+/**
+ * How a child ends: it returns (`aos return`), its turn ends without one and
+ * its last reply stands in after a grace, it is cancelled, or it can't be
+ * run. A child settles once; the settle that changed the row does the rest.
+ */
+
+import fs from "fs";
+import path from "path";
+import { db, queries, type Session } from "../db";
+import { git } from "../git-exec";
+import { statusOf } from "../orchestrator/facts";
+import { openWaits } from "../bus/waits/store";
+import { lastItems } from "../chat/store";
+import { stopChat } from "../chat/runner";
+import type { UsageTotals } from "../chat/events";
+import {
+  getChild,
+  markIdle,
+  setState,
+  settleChild,
+  summaryOf,
+  updateResult,
+  childrenOf,
+  findChild,
+  markDeliveredIds,
+} from "./ledger";
+import { FORK_LIMITS } from "./options";
+import { forksRoot, removeFork, worktreeOf } from "./scratch";
+import type { ChildOutcome, ChildRow, ResultKind } from "./types";
+
+const sessionOf = (id: string) =>
+  queries.getSession(db).get(id) as Session | undefined;
+
+function tokensOf(childId: string) {
+  const raw = (
+    db.prepare(`SELECT chat_usage FROM sessions WHERE id = ?`).get(childId) as
+      { chat_usage: string | null } | undefined
+  )?.chat_usage;
+  if (!raw) return null;
+  try {
+    const u = JSON.parse(raw) as UsageTotals;
+    return {
+      in: u.inputTokens,
+      out: u.outputTokens,
+      cacheRead: u.cacheReadTokens,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export const patchPath = (childId: string) =>
+  path.join(forksRoot(), `${childId}.patch`);
+
+// What a child changed in its own checkout, kept as a patch the parent can
+// apply: its checkout goes with it.
+async function keepPatch(childId: string): Promise<string | null> {
+  const wt = worktreeOf(childId);
+  if (!fs.existsSync(wt)) return null;
+  try {
+    await git(wt, ["add", "-A"]);
+    const diff = await git(wt, ["diff", "--cached", "HEAD", "--binary"], {
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    if (!diff.trim()) return null;
+    const file = patchPath(childId);
+    await fs.promises.mkdir(path.dirname(file), { recursive: true });
+    await fs.promises.writeFile(file, diff);
+    return file;
+  } catch {
+    return null;
+  }
+}
+
+export interface Settlement {
+  outcome: ChildOutcome;
+  summary: string;
+  result?: string | null;
+  kind: ResultKind;
+}
+
+// Settles, tidies up and starts what was waiting for the room. True when
+// this call was the one that settled it.
+export async function settleAndDeliver(
+  childId: string,
+  s: Settlement
+): Promise<boolean> {
+  const row = getChild(childId);
+  if (!row || row.state === "settled") return false;
+  let result = s.result ?? null;
+  if (row.worktree && s.outcome !== "cancelled") {
+    const patch = await keepPatch(childId);
+    if (patch)
+      result =
+        `${result ?? ""}\n\nIts changes are in ${patch} (apply with \`git apply ${patch}\`).`.trim();
+  }
+  const changed = settleChild(childId, {
+    ...s,
+    result,
+    tokens: tokensOf(childId),
+  });
+  if (!changed) return false;
+  // Cancelled by its parent or the user: they know, so nothing is sent.
+  if (s.outcome === "cancelled") markDeliveredIds([childId]);
+  await removeFork(childId).catch(() => undefined);
+  const { admitQueued } = await import("./start");
+  await admitQueued(row.parent_session_id).catch(() => undefined);
+  const { kickForks } = await import("./tick");
+  kickForks();
+  return true;
+}
+
+// `aos return`. After settling it replaces the result, shown as updated.
+export async function returnChild(
+  childId: string,
+  text: string,
+  failed: boolean
+): Promise<"settled" | "updated"> {
+  const row = getChild(childId);
+  if (!row) throw new Error("Only a fork child can return a result");
+  const body = text.trim();
+  if (!body) throw new Error('Give the result: aos return "<result>"');
+  const outcome: ChildOutcome = failed ? "failed" : "ok";
+  if (
+    await settleAndDeliver(childId, {
+      outcome,
+      summary: summaryOf(body),
+      result: body,
+      kind: "explicit",
+    })
+  )
+    return "settled";
+  updateResult(childId, summaryOf(body), body, outcome);
+  return "updated";
+}
+
+export async function cancelChild(childId: string): Promise<boolean> {
+  const row = getChild(childId);
+  if (!row || row.state === "settled") return false;
+  if (row.state !== "queued") stopChat(childId);
+  return settleAndDeliver(childId, {
+    outcome: "cancelled",
+    summary: "cancelled",
+    kind: "implicit",
+  });
+}
+
+export async function cancelChildren(
+  parentId: string,
+  ref?: string
+): Promise<ChildRow[]> {
+  const targets = ref
+    ? [findChild(parentId, ref)]
+    : childrenOf(parentId).filter((c) => c.state !== "settled");
+  const done: ChildRow[] = [];
+  for (const c of targets)
+    if (await cancelChild(c.child_session_id)) done.push(c);
+  return done;
+}
+
+const lastReply = (childId: string): string => {
+  const said = lastItems(childId, 40)
+    .reverse()
+    .find((i) => i.kind === "assistant" && i.text.trim());
+  return said?.kind === "assistant" ? said.text.trim() : "";
+};
+
+// One look at a child that hasn't settled: needing an answer, still working,
+// gone, or idle long enough that its last reply is its result.
+export async function lookAtChild(row: ChildRow, now: number): Promise<void> {
+  if (row.state === "queued" || row.state === "settled") return;
+  const session = sessionOf(row.child_session_id);
+  if (!session || session.archived_at) {
+    await settleAndDeliver(row.child_session_id, {
+      outcome: "failed",
+      summary: "its session was closed before it returned",
+      kind: "implicit",
+    });
+    return;
+  }
+  const { status, activity } = await statusOf(session);
+  if (status === "waiting") {
+    setState(
+      row.child_session_id,
+      "needs_input",
+      activity ?? "waiting for an answer"
+    );
+    markIdle(row.child_session_id, null);
+    return;
+  }
+  if (status === "running" || status === "dead") {
+    if (row.state !== "running" || row.hold)
+      setState(row.child_session_id, "running");
+    markIdle(row.child_session_id, null);
+    return;
+  }
+  if (row.state === "starting") return;
+  if (row.state !== "running" || row.hold)
+    setState(row.child_session_id, "running");
+  if (row.idle_since == null) {
+    markIdle(row.child_session_id, now);
+    return;
+  }
+  if (now - row.idle_since < FORK_LIMITS.implicitGraceMs) return;
+  // It asked its parent something and is waiting for the answer.
+  if (openWaits().some((w) => w.waiter_id === row.child_session_id)) return;
+  const reply = lastReply(row.child_session_id);
+  if (!reply) return;
+  await settleAndDeliver(row.child_session_id, {
+    outcome: "ok",
+    summary: summaryOf(reply),
+    result: reply,
+    kind: "implicit",
+  });
+}

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;
+}