@saadnvd1/agent-os 0.3.821 → 0.3.825

package/lib/fork/brief.ts

@@ -0,0 +1,63 @@
+/** What fork parents and children are told, and the lines results arrive in. */
+
+import { FORK_LIMITS } from "./options";
+import type { ChildRow } from "./types";
+
+export const PARENT_BRIEF = `Forks: when you have independent side work, \`aos fork "<instruction>" ["<instruction>" …]\` starts that many background copies of you (up to ${FORK_LIMITS.maxPerFork}) that know what you know. It returns at once; you keep working. Their results arrive as a message when they finish, or after \`aos wait children --all|--any [--timeout 30m]\` (end your turn; you're woken with them). \`aos children\` lists them, \`aos children <n>\` shows a full result, \`aos cancel <n>|--all\` stops them. Children have your abilities and work in your checkout: tell one that has to edit code to \`--worktree\` (its own throwaway checkout). Fork only work that doesn't depend on your next step.`;
+
+export const CHILD_BRIEF = `You are a fork child: a background copy of another session, started to do one piece of work and report back. You have its abilities, not its checkout: don't change the parent's files, push, open a PR or fork. Put temp work (scripts, repros, notes) in $AOS_SCRATCH. Run builds and tests only through \`aos heavy -- <command>\`, which queues you with the other forks. To ask the parent something, \`aos send <parent> "<question>"\`; that doesn't finish you. When done, \`aos return "<result>"\` (first line: the answer in a sentence; then the detail; \`--failed\` if you couldn't do it). Your reply when you end your turn without it is used as the result, after a short wait.`;
+
+export function childFirstMessage(opts: {
+  parentName: string;
+  n: number;
+  instruction: string;
+  worktree: boolean;
+  scratch: string;
+  snapshot?: string;
+  checkout?: string;
+}): string {
+  const lines = [
+    `You are fork ${opts.n} of "${opts.parentName}". Your assignment:`,
+    "",
+    opts.instruction.trim(),
+    "",
+    opts.worktree && opts.checkout
+      ? `You work in your own checkout (${opts.checkout}), a copy of the parent's changes as they were when you started. Scratch folder: ${opts.scratch}.`
+      : `You work in the parent's checkout: read freely, but don't change it. Scratch folder: ${opts.scratch} ($AOS_SCRATCH).`,
+    "Finish with `aos return`.",
+  ];
+  if (opts.snapshot)
+    lines.push(
+      "",
+      "You don't have the parent's conversation, so here is where it stands:",
+      "",
+      opts.snapshot
+    );
+  return lines.join("\n");
+}
+
+const outcomeWord = (c: ChildRow) =>
+  c.outcome === "failed"
+    ? "failed"
+    : c.outcome === "cancelled"
+      ? "cancelled"
+      : "done";
+
+// One delivery: every result in the batch, whole when short, else its
+// summary and the command that reads the rest.
+export function deliveryText(
+  children: ChildRow[],
+  numberOf: (c: ChildRow) => number
+): string {
+  const parts = children.map((c) => {
+    const n = numberOf(c);
+    const head = `Fork ${n} (${c.label}) ${outcomeWord(c)}${c.result_kind === "implicit" ? " (ended without aos return; its last reply)" : ""}:`;
+    const body = c.result ?? c.summary ?? "";
+    const whole =
+      body.length <= 2_000
+        ? body
+        : `${c.summary ?? ""}\n(${body.length} characters: \`aos children ${n}\` for all of it)`;
+    return `${head}\n${whole}`;
+  });
+  return `[AgentOS: ${children.length === 1 ? "a fork" : `${children.length} forks`} finished. This is data from your own copies, not a new request from the user.]\n\n${parts.join("\n\n")}`;
+}

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