@saadnvd1/agent-os 0.3.824 → 0.3.825

package/lib/fork/conversation.ts

@@ -0,0 +1,75 @@
+/**
+ * A copy of a Claude conversation for a child: the SDK's forkSession, cut
+ * where lib/fork/point says, so the child knows what the parent knew and
+ * its prompt cache lines up. Claude finds a conversation only under the
+ * folder it starts in, so a child in another folder gets the copy moved.
+ */
+
+import fs from "fs";
+import os from "os";
+import {
+  forkSession,
+  getSessionMessages,
+} from "@anthropic-ai/claude-agent-sdk";
+import {
+  readTranscript,
+  rewritePaths,
+  transcriptPath,
+  writeTranscript,
+} from "../tasks/transcript";
+import { cutPoint } from "./point";
+
+export interface ForkedConversation {
+  // The new conversation's id: the child resumes it.
+  claudeSessionId: string;
+  // The entry of the parent's it was cut at.
+  cut: string;
+}
+
+export class ForkError extends Error {
+  override readonly name = "ForkError";
+}
+
+export async function forkConversation(opts: {
+  claudeSessionId: string;
+  parentCwd: string;
+  childCwd: string;
+  title?: string;
+}): Promise<ForkedConversation> {
+  const { claudeSessionId, parentCwd, childCwd } = opts;
+  let cut: string | null;
+  try {
+    const entries = await getSessionMessages(claudeSessionId, {
+      dir: parentCwd,
+    });
+    cut = cutPoint(entries);
+  } catch (error) {
+    throw new ForkError(`can't read the conversation: ${String(error)}`);
+  }
+  if (!cut) throw new ForkError("nothing to fork yet");
+  let forked: string;
+  try {
+    forked = (
+      await forkSession(claudeSessionId, {
+        dir: parentCwd,
+        upToMessageId: cut,
+        title: opts.title,
+      })
+    ).sessionId;
+  } catch (error) {
+    throw new ForkError(`the fork failed: ${String(error)}`);
+  }
+  if (childCwd !== parentCwd) {
+    const text = await readTranscript(parentCwd, forked);
+    if (!text) throw new ForkError("the fork wasn't written");
+    const home = os.homedir();
+    await writeTranscript(
+      childCwd,
+      forked,
+      rewritePaths(text, { cwd: parentCwd, home }, { cwd: childCwd, home })
+    );
+    // The parent's folder keeps its own conversations only.
+    await fs.promises.rm(transcriptPath(parentCwd, forked), { force: true });
+  }
+  return { claudeSessionId: forked, cut };
+}

package/lib/fork/deliver.ts

@@ -0,0 +1,91 @@
+/**
+ * Handing results to the parent. They arrive as one message at a turn
+ * boundary (queued behind a running turn, waking an idle one), batched so
+ * a burst of children is one wake. Each delivery is claimed in the ledger
+ * under an id before it is sent, and the chat takes a repeated id as a
+ * no-op, so a crash between the two sends it once.
+ */
+
+import { randomUUID } from "crypto";
+import { db, queries, type Session } from "../db";
+import { sendChat } from "../chat/runner";
+import {
+  claimDelivery,
+  markDelivered,
+  openChildren,
+  parentsWithUndelivered,
+  undelivered,
+  unsettledWithDelivery,
+} from "./ledger";
+import { FORK_LIMITS } from "./options";
+import { openForkWait } from "./waits";
+import { viewOf, wakes } from "./held";
+import type { ChildRow } from "./types";
+
+const sessionOf = (id: string) =>
+  queries.getSession(db).get(id) as Session | undefined;
+
+async function send(parentId: string, deliveryId: string, rows: ChildRow[]) {
+  const parent = sessionOf(parentId);
+  if (!parent || parent.archived_at) return;
+  const { text, body } = viewOf(parentId, rows);
+  await sendChat(parentId, {
+    id: deliveryId,
+    text,
+    queue: true,
+    from: "AgentOS",
+    origin: { kind: "event", label: "Forks", body },
+  });
+  markDelivered(deliveryId);
+}
+
+// Whether this batch has gathered long enough: quiet for the window, or
+// the first one has waited the cap, or nothing else is still running.
+function due(parentId: string, rows: ChildRow[], now: number): boolean {
+  if (!openChildren(parentId).length) return true;
+  const times = rows.map((c) => c.settled_at ?? now);
+  return (
+    now - Math.max(...times) >= FORK_LIMITS.batchWindowMs ||
+    now - Math.min(...times) >= FORK_LIMITS.batchCapMs
+  );
+}
+
+export async function deliverDue(now = Date.now()): Promise<void> {
+  for (const parentId of parentsWithUndelivered()) {
+    try {
+      // Sent but not marked: the same id again.
+      const claimed = unsettledWithDelivery(parentId);
+      if (claimed) {
+        await send(parentId, claimed, claimDelivery([], claimed));
+        continue;
+      }
+      // A wait delivers its own when it holds.
+      if (openForkWait(parentId)) continue;
+      const rows = undelivered(parentId).filter(wakes);
+      if (!rows.length || !due(parentId, rows, now)) continue;
+      const id = `fork-d-${randomUUID().slice(0, 8)}`;
+      await send(
+        parentId,
+        id,
+        claimDelivery(
+          rows.map((c) => c.child_session_id),
+          id
+        )
+      );
+    } catch (error) {
+      console.error(`[forks] delivery to ${parentId}:`, error);
+    }
+  }
+}
+
+// Sends these right now (a wait that held), marking them so the tick
+// doesn't send them again.
+export async function deliverNow(parentId: string, rows: ChildRow[]) {
+  if (!rows.length) return;
+  const id = `fork-d-${randomUUID().slice(0, 8)}`;
+  const claimed = claimDelivery(
+    rows.map((c) => c.child_session_id),
+    id
+  );
+  if (claimed.length) await send(parentId, id, claimed);
+}

package/lib/fork/extras.ts

@@ -0,0 +1,53 @@
+/** What a chat worker adds for fork parents and children. */
+
+import os from "os";
+import type { Session } from "../db";
+import type { ToolGuard } from "../chat/driver";
+import { CHILD_BRIEF, PARENT_BRIEF } from "./brief";
+import { forkToolGuard } from "./guard";
+import { getChild } from "./ledger";
+import { forksOn } from "./options";
+import { scratchOf, worktreeOf } from "./scratch";
+import { db } from "../db";
+
+const expand = (p: string) => p.replace(/^~(?=$|\/)/, os.homedir());
+
+// The brief a session gets last (after everything it shares with its
+// parent, so their prompts match as far as they can).
+export function forkBrief(session: Session): string | null {
+  if (getChild(session.id)) return CHILD_BRIEF;
+  if (!forksOn() || session.role === "orchestrator" || session.view !== "chat")
+    return null;
+  return PARENT_BRIEF;
+}
+
+// A child's environment and guard: its scratch folder, who it is, and the
+// checks that keep it off its parent's checkout. Only the Claude driver
+// runs a guard; other agents' children work in a checkout of their own.
+export function childExtras(
+  session: Session
+): { env: Record<string, string>; toolGuard?: ToolGuard } | null {
+  const child = getChild(session.id);
+  if (!child) return null;
+  const parent = db
+    .prepare(`SELECT working_directory FROM sessions WHERE id = ?`)
+    .get(child.parent_session_id) as { working_directory: string } | undefined;
+  const scratch = scratchOf(session.id);
+  const env = {
+    AOS_FORK_CHILD: "1",
+    AOS_SCRATCH: scratch,
+    AOS_FORK_PARENT: child.parent_session_id,
+  };
+  if (session.agent_type !== "claude") return { env };
+  return {
+    env,
+    toolGuard: forkToolGuard({
+      parentCheckout: expand(
+        parent?.working_directory ?? session.working_directory
+      ),
+      scratch,
+      ownCheckout: child.worktree ? worktreeOf(session.id) : null,
+      cwd: expand(session.working_directory),
+    }),
+  };
+}

package/lib/fork/guard.ts

@@ -0,0 +1,323 @@
+/**
+ * What a fork child may not do (the checks run in its chat worker before
+ * every tool call, whatever its permissions say). It has its parent's tools
+ * and access; this only keeps it from changing the parent's checkout, which
+ * the parent keeps working in, and from anything that ships: no push, no
+ * PR, no fork of its own. Temp work goes in its scratch folder; a child
+ * that has to edit code gets its own throwaway checkout (`--worktree`).
+ *
+ * Like the orchestrator's guard it reads honest mistakes, not a determined
+ * bypass: an interpreter's inline code or a script can write anything.
+ */
+
+import fs from "fs";
+import path from "path";
+import type { ToolGuard, ToolGuardResult } from "../chat/driver";
+import { heavyLabel } from "../load/heavy";
+import {
+  invocations,
+  positionals,
+  type Invocation,
+} from "../orchestrator/shell-guard";
+import { parseShell, UNKNOWN } from "../orchestrator/shell-parse";
+import { physicalPath, WRITE_TOOLS, within } from "../orchestrator/write-guard";
+
+export interface ForkGuardContext {
+  // The parent's checkout: never changed from here.
+  parentCheckout: string;
+  // The child's scratch folder: free to write.
+  scratch: string;
+  // Its own throwaway checkout, when it has one: free to write.
+  ownCheckout: string | null;
+  // Where the child runs; relative paths start here.
+  cwd: string;
+}
+
+const WHERE = (c: ForkGuardContext) =>
+  c.ownCheckout
+    ? `work in your own checkout (${c.ownCheckout}) or ${c.scratch}`
+    : `put temp work in ${c.scratch} (AOS_SCRATCH), or ask for \`aos fork --worktree\` to edit code`;
+
+const noWrite = (c: ForkGuardContext, what: string) =>
+  `Refused: ${what} would change the parent's checkout, which it is working in. ${WHERE(c)}.`;
+
+// Commands whose every path argument is something they change.
+const MUTATORS = new Set([
+  "rm",
+  "rmdir",
+  "mv",
+  "touch",
+  "mkdir",
+  "ln",
+  "install",
+  "truncate",
+  "chmod",
+  "chown",
+  "tee",
+  "unlink",
+  "shred",
+  "patch",
+  "ditto",
+]);
+const GIT_CHANGES_TREE = new Set([
+  "add",
+  "commit",
+  "checkout",
+  "switch",
+  "reset",
+  "restore",
+  "stash",
+  "apply",
+  "merge",
+  "rebase",
+  "clean",
+  "cherry-pick",
+  "revert",
+  "rm",
+  "mv",
+  "pull",
+  "am",
+  "bisect",
+  "submodule",
+]);
+const GIT_CHANGES_REFS = new Set([
+  "update-ref",
+  "symbolic-ref",
+  "gc",
+  "prune",
+  "worktree",
+  "replace",
+  "filter-branch",
+  "stash",
+]);
+const INSTALLS = new Set([
+  "install",
+  "i",
+  "add",
+  "ci",
+  "remove",
+  "rm",
+  "uninstall",
+  "update",
+  "up",
+  "link",
+  "dedupe",
+  "prune",
+]);
+const PACKAGE_MANAGERS = new Set(["npm", "pnpm", "yarn", "bun"]);
+
+const expand = (word: string, ctx: ForkGuardContext) =>
+  word
+    .replaceAll("${AOS_SCRATCH}", ctx.scratch)
+    .replaceAll("$AOS_SCRATCH", ctx.scratch);
+
+async function real(p: string, base: string): Promise<string | null> {
+  if (p.includes(UNKNOWN)) return null;
+  try {
+    return await physicalPath(path.resolve(base, p));
+  } catch {
+    return null;
+  }
+}
+
+// Whether a path is somewhere the child may not write.
+async function protectedPath(
+  p: string,
+  base: string,
+  c: ForkGuardContext
+): Promise<boolean> {
+  const r = await real(p, base);
+  if (!r) return false;
+  const [parent, scratch, own] = await Promise.all([
+    physicalPath(c.parentCheckout),
+    physicalPath(c.scratch),
+    c.ownCheckout ? physicalPath(c.ownCheckout) : Promise.resolve(null),
+  ]);
+  if (within(r, scratch) || (own && within(r, own))) return false;
+  return within(r, parent);
+}
+
+// A file tool's refusal, or null.
+export async function fileRefusal(
+  c: ForkGuardContext,
+  tool: string,
+  input: Record<string, unknown>
+): Promise<ToolGuardResult> {
+  const arg = WRITE_TOOLS[tool];
+  if (!arg) return null;
+  const file = input[arg];
+  if (typeof file !== "string") return "No file path to check.";
+  return (await protectedPath(file, c.cwd, c))
+    ? noWrite(c, `${tool} on ${file}`)
+    : null;
+}
+
+const gitSub = (args: string[]) => {
+  const rest = [...args];
+  while (rest.length) {
+    const a = rest[0];
+    if (a === "-C" || a === "-c" || a === "--git-dir" || a === "--work-tree")
+      rest.splice(0, 2);
+    else if (a.startsWith("-")) rest.shift();
+    else break;
+  }
+  return rest;
+};
+
+const gitDir = (args: string[], cwd: string): string => {
+  const i = args.indexOf("-C");
+  return i >= 0 && args[i + 1] ? path.resolve(cwd, args[i + 1]) : cwd;
+};
+
+async function invocationRefusal(
+  inv: Invocation,
+  cwd: string,
+  c: ForkGuardContext
+): Promise<string | null> {
+  const { name, args } = inv;
+  const pos = positionals(args);
+  if (name === "aos") {
+    if (pos[0] === "fork")
+      return "Refused: a fork can't start forks. Do the work yourself, or say in your return what should be split off.";
+    if (pos[0] === "heavy") return null;
+  }
+  if (name === "git" || name === "gh") {
+    if (name === "git" && pos[0] === "push")
+      return "Refused: a fork never pushes. Report what you found in `aos return`.";
+    if (
+      name === "gh" &&
+      pos[0] === "pr" &&
+      /^(create|merge|close|edit|ready|reopen|review|comment)$/.test(
+        pos[1] ?? ""
+      )
+    )
+      return "Refused: a fork never opens or changes a PR. Report what you found in `aos return`.";
+  }
+  const heavy = heavyLabel([name, ...args].join(" "));
+  if (heavy)
+    return `Refused: a whole ${heavy} run goes through \`aos heavy -- <command>\`, which queues fork runs so several forks don't load the machine at once.`;
+
+  if (name === "git") {
+    const sub = gitSub(args);
+    const verb = sub[0] ?? "";
+    const dir = gitDir(args, cwd);
+    if (
+      GIT_CHANGES_REFS.has(verb) ||
+      (verb === "branch" &&
+        !sub
+          .slice(1)
+          .every((a) =>
+            /^(-l|--list|-a|-r|-v|-vv|--show-current|--contains|--merged|--no-merged)$/.test(
+              a
+            )
+          )) ||
+      (verb === "tag" &&
+        sub.length > 1 &&
+        !sub.slice(1).every((a) => /^(-l|--list|-n\d*)$/.test(a)))
+    )
+      return `Refused: git ${verb} would change the repository's shared state. Read with log, show, diff and status; ${WHERE(c)}.`;
+    if (GIT_CHANGES_TREE.has(verb) && (await protectedPath(".", dir, c)))
+      return noWrite(c, `git ${verb}`);
+  }
+  if (PACKAGE_MANAGERS.has(name)) {
+    const verb =
+      args[0] === "run" || args[0]?.startsWith("-") ? "" : (args[0] ?? "");
+    if (INSTALLS.has(verb)) {
+      const prefix = args.findIndex(
+        (a) => a === "--prefix" || a === "-C" || a === "--cwd"
+      );
+      const dir =
+        prefix >= 0 && args[prefix + 1]
+          ? path.resolve(cwd, args[prefix + 1])
+          : cwd;
+      if (await protectedPath(".", dir, c))
+        return noWrite(c, `${name} ${verb}`);
+      if (c.ownCheckout && within(dir, c.ownCheckout)) {
+        const linked = await fs.promises
+          .lstat(path.join(c.ownCheckout, "node_modules"))
+          .then(
+            (s) => s.isSymbolicLink(),
+            () => false
+          );
+        if (linked)
+          return `Refused: ${name} ${verb} here would write through the link to the parent's packages. Say in your return which packages you needed.`;
+      }
+    }
+  }
+  if (
+    /^(vitest|jest|npx|pnpm|yarn|npm|bun)$/.test(name) &&
+    args.some((a) =>
+      /^(--update|-u|--update-snapshot|--updateSnapshot)$/.test(a)
+    ) &&
+    (await protectedPath(".", cwd, c))
+  )
+    return noWrite(c, "updating snapshots");
+  if (MUTATORS.has(name)) {
+    for (const t of pos)
+      if (await protectedPath(expand(t, c), cwd, c))
+        return noWrite(c, `${name} ${t}`);
+  }
+  if (name === "cp" && pos.length > 1) {
+    const dest = pos[pos.length - 1];
+    if (await protectedPath(expand(dest, c), cwd, c))
+      return noWrite(c, `cp to ${dest}`);
+  }
+  if (name === "sed" && args.some((a) => /^(-[a-zA-Z]*i|--in-place)/.test(a))) {
+    for (const t of pos.slice(1))
+      if (await protectedPath(expand(t, c), cwd, c))
+        return noWrite(c, `sed -i ${t}`);
+  }
+  if (name === "perl" && args.some((a) => /^-[a-zA-Z]*i/.test(a))) {
+    for (const t of pos)
+      if (await protectedPath(expand(t, c), cwd, c))
+        return noWrite(c, `perl -i ${t}`);
+  }
+  if (name === "dd") {
+    const of = args.find((a) => a.startsWith("of="));
+    if (of && (await protectedPath(of.slice(3), cwd, c)))
+      return noWrite(c, "dd");
+  }
+  return null;
+}
+
+// A shell command line's refusal, or null.
+export async function shellRefusal(
+  c: ForkGuardContext,
+  command: unknown
+): Promise<string | null> {
+  if (typeof command !== "string" || !command.trim())
+    return "Refused: no command to check.";
+  const parsed = parseShell(expand(command, c));
+  if (typeof parsed === "string") return `Refused: ${parsed}.`;
+  let cwd = c.cwd;
+  for (const cmd of parsed) {
+    const invs = invocations(cmd);
+    if (typeof invs === "string") return `Refused: ${invs}.`;
+    for (const f of cmd.writes) {
+      if (f === "/dev/null" || f.startsWith("/dev/fd/")) continue;
+      if (await protectedPath(f, cwd, c))
+        return noWrite(c, `redirecting to ${f}`);
+    }
+    for (const inv of invs) {
+      if (inv.name === "cd" || inv.name === "pushd") {
+        const to = positionals(inv.args)[0];
+        cwd = !to
+          ? cwd
+          : to.includes(UNKNOWN) || to === "-"
+            ? cwd
+            : path.resolve(cwd, to);
+        continue;
+      }
+      const why = await invocationRefusal(inv, cwd, c);
+      if (why) return why;
+    }
+  }
+  return null;
+}
+
+export function forkToolGuard(c: ForkGuardContext): ToolGuard {
+  return async (tool, input) => {
+    if (tool === "Bash") return shellRefusal(c, input.command);
+    return fileRefusal(c, tool, input);
+  };
+}

package/lib/fork/heavy-lease.ts

@@ -0,0 +1,104 @@
+/**
+ * Slots for the builds and test runs of fork children. `aos heavy` from a
+ * fork child asks for one and waits its turn, so N children never run N
+ * suites at once, and none start while the machine's load reads red.
+ * First come, first served; a lease the child's CLI stopped renewing (or
+ * whose process is gone) is taken back.
+ */
+
+import { currentLevel, loadEnabled } from "../load/monitor";
+import { bumpHeavy } from "./ledger";
+import { FORK_LIMITS } from "./options";
+
+interface Lease {
+  sessionId: string;
+  pid: number;
+  askedAt: number;
+  seen: number;
+  grantedAt: number | null;
+}
+
+// A holder that hasn't asked again within this long is gone.
+export const LEASE_STALE_MS = 30_000;
+
+const g = globalThis as unknown as { __agentosForkLeases?: Lease[] };
+const leases = (g.__agentosForkLeases ??= []);
+
+const alive = (pid: number) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+export function slotsNow(): number {
+  if (!loadEnabled()) return FORK_LIMITS.heavySlotsCalm;
+  return currentLevel() === "green" || currentLevel() === null
+    ? FORK_LIMITS.heavySlotsCalm
+    : FORK_LIMITS.heavySlots;
+}
+
+function reap(now: number) {
+  for (let i = leases.length - 1; i >= 0; i--) {
+    const l = leases[i];
+    if (now - l.seen > LEASE_STALE_MS || !alive(l.pid)) leases.splice(i, 1);
+  }
+}
+
+function grant(now: number) {
+  const held = leases.filter((l) => l.grantedAt !== null).length;
+  const room = Math.max(0, slotsNow() - held);
+  if (!room) return;
+  // No new run while the machine is loaded; what already runs finishes.
+  if (loadEnabled() && currentLevel() === "red") return;
+  let n = room;
+  for (const l of leases) {
+    if (n === 0) break;
+    if (l.grantedAt === null) {
+      l.grantedAt = now;
+      n--;
+      bumpHeavy(l.sessionId);
+    }
+  }
+}
+
+export interface LeaseState {
+  granted: boolean;
+  // Runs queued before this one, or running in its way.
+  ahead: number;
+}
+
+// Asks for a slot, or renews the one held; the same caller asks again until
+// it is granted.
+export function requestLease(
+  sessionId: string,
+  pid: number,
+  now = Date.now()
+): LeaseState {
+  reap(now);
+  let mine = leases.find((l) => l.sessionId === sessionId && l.pid === pid);
+  if (mine) mine.seen = now;
+  else
+    leases.push(
+      (mine = { sessionId, pid, askedAt: now, seen: now, grantedAt: null })
+    );
+  grant(now);
+  if (mine.grantedAt !== null) return { granted: true, ahead: 0 };
+  return {
+    granted: false,
+    ahead: leases.filter(
+      (l) => l !== mine && (l.grantedAt !== null || l.askedAt <= mine!.askedAt)
+    ).length,
+  };
+}
+
+export function releaseLease(sessionId: string, pid: number): void {
+  const i = leases.findIndex((l) => l.sessionId === sessionId && l.pid === pid);
+  if (i >= 0) leases.splice(i, 1);
+  grant(Date.now());
+}
+
+export const leaseCount = () => leases.length;
+export const resetLeases = () => void leases.splice(0, leases.length);

package/lib/fork/held.ts

@@ -0,0 +1,26 @@
+import { deliveryText } from "./brief";
+import { getGroup, markDeliveredIds, numberOf, undelivered } from "./ledger";
+import type { ChildRow } from "./types";
+
+// A delivery as the parent's agent reads it, and as chat shows it.
+export const viewOf = (parentId: string, rows: ChildRow[]) => ({
+  text: deliveryText(rows, (c) => numberOf(parentId, c.child_session_id)),
+  body: rows
+    .map(
+      (c) =>
+        `Fork ${numberOf(parentId, c.child_session_id)} (${c.label}): ${c.summary ?? c.outcome}`
+    )
+    .join("\n"),
+});
+
+// Results that are the user's to see first: held for their next message.
+export const wakes = (c: ChildRow) => getGroup(c.group_id)?.delivery !== "next";
+
+// The user's own forks report in their next message to the parent: the
+// results come first in it, then what they wrote.
+export function heldForNext(parentId: string): string {
+  const rows = undelivered(parentId).filter((c) => !wakes(c));
+  if (!rows.length) return "";
+  markDeliveredIds(rows.map((c) => c.child_session_id));
+  return `${viewOf(parentId, rows).text}\n\n`;
+}