@staix/agent-hub 0.2.0

package/src/hub/tasks.ts

@@ -0,0 +1,293 @@
+import type { Briefs } from "../memory/brief.ts";
+import type { MemoryClient } from "../memory/client.ts";
+import { CLASSES, type Board, type Task, type TaskClass, type TaskRefs } from "./board.ts";
+import type { Bus } from "./bus.ts";
+import { HUB, newEnvelope, USER, type Envelope, type PeerId, type PeerState } from "./envelope.ts";
+import { assign, detectSignals, LOCAL, type Assignment, type Routing } from "./routing.ts";
+
+export interface TasksDeps {
+  board: Board;
+  bus: Bus;
+  routing: () => Routing;
+  cwd: string;
+  project: string;
+  briefs?: Briefs;
+  memory?: MemoryClient;
+  /** a line for the human: console tail and hub.log */
+  notify: (line: string) => void;
+  /** Optional: name a class for a task proposed without one. `onCampus` says whether the model call stays on campus. */
+  triage?: { classify: (title: string, detail: string) => Promise<TaskClass | undefined>; onCampus: () => Promise<boolean> };
+}
+
+const ESCALATE_AFTER = 2;
+const OPEN: Task["state"][] = ["proposed", "in_progress", "changes_requested"];
+
+/** Tool callers are models: inputSchema is not enforced on the way in, so refs are normalized before they reach the board. */
+function cleanRefs(input: unknown): TaskRefs {
+  const r = (input && typeof input === "object" ? input : {}) as Record<string, unknown>;
+  const text = (v: unknown) => (typeof v === "string" && v.trim() ? v.trim().slice(0, 300) : undefined);
+  const paths = (Array.isArray(r.paths) ? r.paths : typeof r.paths === "string" ? [r.paths] : []).map(text).filter((p): p is string => !!p).slice(0, 50);
+  const out: TaskRefs = {};
+  for (const k of ["repo", "branch", "commit"] as const) if (text(r[k])) out[k] = text(r[k])!;
+  if (paths.length) out.paths = paths;
+  return out;
+}
+
+/**
+ * The task flow. Adapters and tools never touch the board: every change comes through here, where assignment,
+ * PII handling, envelopes, briefs and memory notes are decided in one place.
+ */
+export class Tasks {
+  constructor(private readonly d: TasksDeps) {
+    // What the on-prem worker says about a PII task is private on the bus (console tail and log show a stub), so the
+    // board keeps the text: `ahub task show <id>` is where the console user reads it, a refusal included.
+    d.bus.tap((e) => {
+      if (e.t !== "envelope" || !e.env.private || e.env.from === HUB || !e.env.refs?.task) return;
+      try {
+        d.board.update(Number(e.env.refs.task), e.env.from, "answer", {}, e.env.body.slice(0, 4000));
+      } catch {
+        // the task is gone: nothing to attach the answer to
+      }
+    });
+  }
+
+  isPii = (task: Pick<Task, "signals">) => task.signals.includes("pii") && this.d.routing().constraints.pii === "local_only";
+
+  /** What peers other than the owner, the console stream and the log may see of a task. */
+  publicTitle = (task: Task) => (this.isPii(task) ? `#${task.id} [pii]` : `#${task.id} ${task.title}`);
+
+  /** A task as a cloud peer may see it. */
+  publicView(task: Task): Record<string, unknown> {
+    const { title, detail, history, ...rest } = task;
+    return this.isPii(task) ? { ...rest, title: "[pii]", detail: "[pii]" } : { ...rest, title, detail, history: history.slice(-5) };
+  }
+
+  private states(): Record<PeerId, PeerState> {
+    return Object.fromEntries([...this.d.bus.peers.keys()].map((id) => [id, this.d.bus.stateOf(id)]));
+  }
+
+  async propose(by: PeerId, input: { title?: string; detail?: string; class?: string; refs?: TaskRefs; owner?: PeerId }): Promise<Task> {
+    const title = String(input.title ?? "").trim().slice(0, 300); // callers are models: a title is a line, not a document
+    if (!title) throw new Error("title is required");
+    const given = input.class === undefined || input.class === "" ? undefined : input.class;
+    if (given !== undefined && !CLASSES.includes(given as TaskClass)) throw new Error(`class must be one of ${CLASSES.join(", ")}`);
+    const text = { title, detail: String(input.detail ?? "").slice(0, 8000), refs: cleanRefs(input.refs) };
+    const signals = detectSignals(text, this.d.routing(), this.d.cwd);
+    let cls = given as TaskClass | undefined;
+    let triaged = false;
+    if (!cls && this.d.triage) {
+      // Signals first: a PII task's text may only go to a model that is reached without leaving the campus network.
+      const pii = signals.includes("pii") && this.d.routing().constraints.pii === "local_only";
+      if (!pii || (await this.d.triage.onCampus().catch(() => false))) cls = await this.d.triage.classify(text.title, text.detail).catch(() => undefined);
+      triaged = !!cls;
+    }
+    if (!cls) throw new Error(`class is required (one of ${CLASSES.join(", ")}); the hub could not name one for you`);
+    const draft = { ...text, class: cls };
+    let task = this.d.board.propose(by, { ...draft, signals });
+    if (triaged) task = this.d.board.update(task.id, "hub", "triaged", {}, `class ${cls} named by the hub's model`);
+    this.d.notify(`task ${this.publicTitle(task)} proposed by ${by} [${task.class}]${task.signals.length ? ` signals: ${task.signals.join(", ")}` : ""}`);
+    return this.assignOwner(task, by, input.owner ? { candidates: [input.owner] } : {});
+  }
+
+  /** Same code as assignment, without doing it. */
+  explain(target: number | { title: string; detail?: string; class: TaskClass; refs?: TaskRefs }): string[] {
+    const routing = this.d.routing();
+    if (typeof target === "number") {
+      const task = this.d.board.get(target);
+      if (!task) throw new Error(`no task #${target}`);
+      return [`task ${this.publicTitle(task)} (${task.state}, owner ${task.owner ?? "none"})`, "if it were assigned now:", ...assign(task, this.states(), routing, { exclude: this.declined(task) }).trace];
+    }
+    const draft = { title: target.title, detail: target.detail ?? "", refs: target.refs ?? {} };
+    return assign({ class: target.class, signals: detectSignals(draft, routing, this.d.cwd) }, this.states(), routing).trace;
+  }
+
+  private declined = (task: Task) => task.history.filter((h) => h.event === "declined").map((h) => h.by);
+
+  private async assignOwner(task: Task, by: PeerId, opts: { candidates?: PeerId[]; event?: string; note?: string; clearOnFail?: boolean; exclude?: PeerId[]; context?: string } = {}): Promise<Task> {
+    const a = assign(task, this.states(), this.d.routing(), { exclude: [...this.declined(task), ...(opts.exclude ?? []), ...(opts.event === "escalated" && task.owner ? [task.owner] : [])], ...(opts.candidates ? { candidates: opts.candidates } : {}) });
+    if (!a.owner) {
+      this.d.notify(`task ${this.publicTitle(task)}: no peer can take it (${a.trace.filter((l) => l.includes("skipped")).length} skipped); assign with: ahub task assign ${task.id} <peer>`);
+      // Only a decline takes the task away from its owner; a failed console assign or escalation leaves it where it was.
+      return opts.clearOnFail && task.owner ? this.d.board.update(task.id, by, "unassigned", { owner: null }) : task;
+    }
+    const next = this.d.board.update(task.id, by, opts.event ?? "assigned", { owner: a.owner, reviewer: a.reviewer ?? null, ...(opts.event === "escalated" ? { rejections: 0 } : {}) }, opts.note ?? `to ${a.owner}`);
+    await this.sendTask(next, a, opts.context);
+    return next;
+  }
+
+  private async sendTask(task: Task, a: Assignment, context?: string): Promise<void> {
+    const pii = this.isPii(task);
+    const brief = pii ? undefined : await this.d.briefs?.forTask(task.owner!, task).catch(() => undefined);
+    const rejected = task.history.filter((h) => h.event === "changes_requested").map((h) => `- ${h.by}: ${h.note ?? ""}`);
+    const facts = [`class ${task.class}`, task.refs.paths?.length ? `paths ${task.refs.paths.join(", ")}` : "", task.refs.branch ? `branch ${task.refs.branch}` : "", a.reviewer ? `reviewer ${a.reviewer}` : "no reviewer"].filter(Boolean).join("; ");
+    const body = [
+      `Task #${task.id} [${task.class}] ${task.title}`,
+      task.detail,
+      `Facts: ${facts}`,
+      rejected.length ? `Earlier review notes:\n${rejected.join("\n")}` : "",
+      brief ?? "",
+      // What the previous owner left behind. Peer-written free text: never attached to a PII task.
+      context && !pii ? `Handoff from the previous owner:\n${context.slice(0, 3000)}` : "",
+      `Take it with hub_task_accept {id: ${task.id}} or pass with hub_task_decline. When finished: hub_task_done {id: ${task.id}, summary, refs}.`,
+    ].filter(Boolean).join("\n\n");
+    this.d.bus.publish(newEnvelope(HUB, body, { to: [task.owner!], kind: "task", priority: "important", refs: { ...task.refs, task: String(task.id) }, ...(pii ? { private: true } : {}) }));
+  }
+
+  private mine(task: Task, by: PeerId, role: "owner" | "reviewer"): void {
+    if (by !== USER && task[role] !== by) throw new Error(`task #${task.id}: only its ${role} (${task[role] ?? "none"}) or the console user can do that`);
+  }
+
+  private need(id: unknown, open = false): Task {
+    const task = this.d.board.get(Number(id));
+    if (!task) throw new Error(`no task #${id}`);
+    // Handing a task to someone else only makes sense while there is work left on it.
+    if (open && !OPEN.includes(task.state)) throw new Error(`task #${task.id} is ${task.state}: it can no longer change hands`);
+    return task;
+  }
+
+  accept(by: PeerId, id: unknown): Task {
+    const task = this.need(id);
+    this.mine(task, by, "owner");
+    const next = this.d.board.update(task.id, by, "accepted", { state: "in_progress" });
+    this.d.notify(`task ${this.publicTitle(next)} accepted by ${by}`);
+    return next;
+  }
+
+  async decline(by: PeerId, id: unknown, reason?: string): Promise<Task> {
+    const task = this.need(id, true);
+    this.mine(task, by, "owner");
+    const back = this.d.board.update(task.id, by, "declined", task.state === "in_progress" ? { state: "proposed" } : {}, reason);
+    this.d.notify(`task ${this.publicTitle(back)} declined by ${by}${reason && !this.isPii(back) ? `: ${reason}` : ""}`);
+    return this.assignOwner(back, HUB, { event: "reassigned", clearOnFail: true });
+  }
+
+  async done(by: PeerId, id: unknown, summary?: string, refs?: TaskRefs): Promise<Task> {
+    let task = this.need(id);
+    this.mine(task, by, "owner");
+    if (task.state === "in_review" || task.state === "approved") throw new Error(`task #${task.id} is already ${task.state}`);
+    if (task.state === "proposed" || task.state === "changes_requested") task = this.d.board.update(task.id, by, "accepted", { state: "in_progress" }); // done without a separate accept
+    const reviewer = task.reviewer;
+    const next = this.d.board.update(task.id, by, "done", { state: reviewer ? "in_review" : "approved", refs: cleanRefs(refs) }, summary);
+    this.note(next, by, "finding", `Task #${next.id} done by ${by}: ${next.title}\n${summary ?? ""}`);
+    if (!reviewer) this.d.notify(`task ${this.publicTitle(next)} done by ${by}, no reviewer: approved`);
+    else if (reviewer === USER) this.d.notify(`task ${this.publicTitle(next)} done by ${by}: review it with ahub task show ${next.id}, then ahub review ${next.id} approved|changes_requested [note]`);
+    else this.sendReview(next, reviewer);
+    return next;
+  }
+
+  /** The one place a review request is written: the first reviewer and a replacement get the same text, refs and privacy. */
+  private sendReview(task: Task, reviewer: PeerId, why = ""): void {
+    const r = task.refs;
+    const last = [...task.history].reverse().find((h) => h.event === "done");
+    const where = [r.branch ? `branch ${r.branch}` : "", r.commit ? `commit ${r.commit}` : "", r.paths?.length ? `paths ${r.paths.join(", ")}` : ""].filter(Boolean).join("; ");
+    const body = `Review task #${task.id} [${task.class}] ${task.title}\nDone by ${last?.by ?? task.owner}: ${last?.note ?? "(no summary)"}\n${where ? `Where: ${where}\n` : ""}${why ? `${why}\n` : ""}Give your verdict with hub_review {id: ${task.id}, verdict: "approved" | "changes_requested", note}.`;
+    this.d.bus.publish(newEnvelope(HUB, body, { to: [reviewer], kind: "review", priority: "important", refs: { ...r, task: String(task.id) }, ...(this.isPii(task) ? { private: true } : {}) }));
+  }
+
+  async review(by: PeerId, id: unknown, verdict: unknown, note?: string): Promise<Task> {
+    const task = this.need(id);
+    this.mine(task, by, "reviewer");
+    if (verdict !== "approved" && verdict !== "changes_requested") throw new Error('verdict must be "approved" or "changes_requested"');
+    if (task.state !== "in_review") throw new Error(`task #${task.id} is ${task.state}: cannot move to ${verdict} before its owner calls hub_task_done`);
+    const pii = this.isPii(task);
+    if (verdict === "approved") {
+      const next = this.d.board.update(task.id, by, "approved", { state: "approved", rejections: 0 }, note);
+      this.note(next, by, "decision", `Task #${next.id} approved by ${by}: ${next.title}\n${note ?? ""}`);
+      this.tell(next, `Task #${next.id} approved by ${by}.${note ? ` ${note}` : ""}`, pii);
+      return next;
+    }
+    const rejected = this.d.board.update(task.id, by, "changes_requested", { state: "changes_requested", rejections: task.rejections + 1 }, note);
+    this.note(rejected, by, "decision", `Task #${rejected.id} changes requested by ${by}: ${rejected.title}\n${note ?? ""}`);
+    if (rejected.rejections >= ESCALATE_AFTER) {
+      const moved = await this.escalate(HUB, rejected.id, `${rejected.rejections} consecutive changes_requested`);
+      if (moved.owner !== rejected.owner) return moved;
+      // Nobody to escalate to: the owner still has to hear the verdict and the note.
+      this.tell(moved, `Task #${moved.id}: ${by} requests changes again.${note ? ` ${note}` : ""} Nobody else can take it; fix it and call hub_task_done again.`, pii);
+      return moved;
+    }
+    const reopened = this.d.board.update(rejected.id, HUB, "reopened", { state: "in_progress" });
+    this.tell(reopened, `Task #${reopened.id}: ${by} requests changes.${note ? ` ${note}` : ""} Fix it and call hub_task_done again.`, pii);
+    return reopened;
+  }
+
+  /** Task-level escalation: the next attached peer in the class's escalate_to takes over, with the history. */
+  async escalate(by: PeerId, id: unknown, why = "by hand"): Promise<Task> {
+    let task = this.need(id, true);
+    const list = this.d.routing().classes[task.class]?.escalate_to ?? [];
+    if (task.state === "changes_requested") task = this.d.board.update(task.id, HUB, "reopened", { state: "in_progress" });
+    const from = task.owner;
+    const next = await this.assignOwner(task, by, { candidates: list, event: "escalated", note: `${why}; from ${from ?? "none"}` });
+    if (next.owner && next.owner !== from) {
+      this.d.notify(`task ${this.publicTitle(next)} escalated from ${from} to ${next.owner} (${why})`);
+      this.note(next, by, "decision", `Task #${next.id} escalated from ${from} to ${next.owner}: ${why}`);
+      if (from) this.tell({ ...next, owner: from }, `Task #${next.id} moved to ${next.owner} (${why}). Stop working on it.`, this.isPii(next));
+    } else this.d.notify(`task ${this.publicTitle(task)}: escalation found nobody in [${list.join(", ")}]; it stays with ${from ?? "nobody"}`);
+    return this.d.board.get(next.id)!;
+  }
+
+  /** Console only. */
+  async assignTo(id: unknown, peer: PeerId): Promise<Task> {
+    return this.assignOwner(this.need(id, true), USER, { candidates: [peer], event: "reassigned" });
+  }
+
+  /**
+   * Budget relay: a paused peer's open work moves on. `local` first (it has no quota), then the class list, all through
+   * the usual constraints. Tasks it was reviewing get another reviewer. Moves are reported, never taken back automatically.
+   */
+  async reassignForPause(peer: PeerId, context: string | undefined): Promise<{ id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]> {
+    const moved: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[] = [];
+    const routing = this.d.routing();
+    for (const task of this.d.board.list()) {
+      if (task.owner === peer && OPEN.includes(task.state)) {
+        const candidates = [LOCAL, ...(routing.classes[task.class]?.peers ?? []).filter((p) => p !== LOCAL)];
+        const back = task.state === "in_progress" ? this.d.board.update(task.id, HUB, "released", { state: "proposed" }, `budget pause of ${peer}`) : task;
+        const next = await this.assignOwner(back, HUB, { candidates, exclude: [peer], event: "reassigned", note: `budget pause of ${peer}`, clearOnFail: true, ...(context ? { context } : {}) });
+        moved.push({ id: task.id, title: this.publicTitle(task), to: next.owner, role: "owner" });
+      } else if (task.reviewer === peer && task.state !== "approved") {
+        // No owner candidates: only the reviewer is wanted, and it must be neither the paused peer nor the task's owner.
+        const a = assign(task, this.states(), routing, { exclude: [peer], candidates: [], ...(task.owner ? { notReviewer: task.owner } : {}) });
+        const reviewer = a.reviewer && a.reviewer !== peer && a.reviewer !== task.owner ? a.reviewer : null;
+        const next = this.d.board.update(task.id, HUB, "reviewer changed", { reviewer }, `budget pause of ${peer}`);
+        moved.push({ id: task.id, title: this.publicTitle(task), to: reviewer, role: "reviewer" });
+        if (next.state === "in_review" && reviewer && reviewer !== USER) this.sendReview(next, reviewer, `(${peer} was reviewing this and is paused for quota.)`);
+        else if (next.state === "in_review" && !reviewer) this.d.notify(`task ${this.publicTitle(next)}: its reviewer ${peer} is paused and nobody else can review; use ahub review ${next.id}`);
+      }
+    }
+    return moved;
+  }
+
+  /** What the local worker needs to know about the turn it is about to run. */
+  turnPolicy(envs: Envelope[]): { route?: string; fixedModel?: string; pii: boolean; task?: string } | undefined {
+    const found = envs.map((e) => (e.refs?.task ? this.d.board.get(Number(e.refs.task)) : undefined)).filter((t): t is Task => !!t);
+    // One PII item makes the whole turn a PII turn: a digest can carry a PII task next to ordinary messages.
+    const pii = envs.some((e) => e.private) || found.some((t) => this.isPii(t));
+    if (!found.length) return pii ? { pii } : undefined;
+    const policy = this.d.routing().classes[found[0]!.class];
+    const about = found.find((t) => this.isPii(t)) ?? found[0]!; // the answer is filed under the PII task when there is one
+    return { ...(policy?.route ? { route: policy.route } : {}), ...(policy?.fixed_model ? { fixedModel: policy.fixed_model } : {}), pii, task: String(about.id) };
+  }
+
+  async remember(by: PeerId, input: { text?: string; title?: string; kind?: string; task?: unknown }): Promise<string> {
+    const text = String(input.text ?? "").trim();
+    if (!text) throw new Error("text is required");
+    const task = input.task !== undefined ? this.d.board.get(Number(input.task)) : undefined;
+    if (task && this.isPii(task)) throw new Error("notes about a PII task are not saved: claude-mem processes what it stores with a cloud model");
+    if (!this.d.memory) return "memory is disabled; nothing saved";
+    const kind = ["decision", "finding", "contract"].includes(String(input.kind)) ? String(input.kind) : "finding";
+    const res = await this.d.memory.save({ text, ...(input.title ? { title: input.title } : {}), project: this.d.project, metadata: { peer: by, kind, ...(task ? { task: task.id } : {}) } });
+    return res ? "saved to shared memory" : "memory worker unavailable; nothing saved";
+  }
+
+  /** Auto notes: only transitions that carry content, never for PII. */
+  private note(task: Task, by: PeerId, kind: string, text: string): void {
+    if (this.isPii(task) || !this.d.memory) return;
+    void this.d.memory.save({ text, title: `agent-hub task #${task.id}: ${task.title}`.slice(0, 120), project: this.d.project, metadata: { peer: by, task: task.id, kind } });
+  }
+
+  private tell(task: Task, body: string, pii: boolean): void {
+    if (!task.owner || task.owner === USER) return;
+    this.d.bus.publish(newEnvelope(HUB, body, { to: [task.owner], kind: "task", priority: "important", refs: { task: String(task.id) }, ...(pii ? { private: true } : {}) }));
+  }
+}
+
+export { LOCAL };

package/src/local/deny.ts

@@ -0,0 +1,36 @@
+import { basename, sep } from "node:path";
+
+/**
+ * The one denylist. tools.ts checks paths against it, sandbox.ts turns it into seatbelt rules, capture.ts keeps
+ * matching calls out of memory. Two lists would drift, and the gap is where a secret leaks.
+ */
+export const DENY_SEGMENTS = [".maru/secrets", ".agenthub/state"];
+/** Regex sources, matched against a file's basename. */
+export const DENY_NAMES = ["^\\.env", "\\.pem$", "\\.key$", "^id_rsa", "^id_ed25519", "^credentials(\\.|$)", "^auth\\.json$", "^\\.netrc$", "^\\.npmrc$", "^\\.pypirc$"];
+
+const hasSegment = (rel: string, seg: string) => `/${rel}/`.includes(`/${seg}/`);
+export { hasSegment };
+
+/** True when a path names something the worker must never read, write or report. `extra`: substrings from `local.deny`. */
+export function isDenied(path: string, extra: string[] = []): boolean {
+  const norm = path.split(sep).join("/");
+  return DENY_SEGMENTS.some((s) => hasSegment(norm, s)) || DENY_NAMES.some((re) => new RegExp(re).test(basename(norm))) || extra.some((e) => e && norm.includes(e));
+}
+
+const sbplEscape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/"/g, '\\"');
+
+/**
+ * Seatbelt regex filters equivalent to isDenied. Seatbelt sees absolute paths, so the `local.deny` substrings are
+ * anchored under the project root: a bare "private/" would otherwise match /private/var/... and deny the whole temp tree.
+ */
+export function denyRegexes(root: string, extra: string[] = []): string[] {
+  const names = DENY_NAMES.map((re) => {
+    const body = re.startsWith("^") ? re.slice(1) : `[^/]*${re}`;
+    return `/${body}${body.endsWith("$") ? "" : "[^/]*$"}`;
+  });
+  return [
+    ...DENY_SEGMENTS.map((s) => `/${sbplEscape(s)}(/|$)`),
+    ...names,
+    ...extra.filter(Boolean).map((e) => `^${sbplEscape(root)}/.*${sbplEscape(e)}`),
+  ].map((re) => `(regex #"${re.replace(/"/g, '\\"')}")`);
+}

package/src/local/sandbox.ts

@@ -0,0 +1,94 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { denyRegexes } from "./deny.ts";
+
+const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
+export const OUTPUT_CAP = 20_000;
+
+export const sandboxAvailable = () => process.platform === "darwin" && existsSync(SANDBOX_EXEC);
+
+const q = (s: string) => `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+
+/**
+ * Seatbelt profile for everything the local worker executes (bash, git). Path checks cannot scope a shell,
+ * so the kernel does: writes only under cwd and temp, no reads of credential stores or denylisted files,
+ * no network unless asked. In SBPL the last matching rule wins, so the denies come last.
+ */
+/** Toolchains and git identity: the only parts of the home directory a sandboxed command may read besides the project. */
+const HOME_READABLE = [".bun", ".cargo", ".rustup", ".local", ".npm", ".cache", ".pyenv", ".nvm", ".deno", "go", ".gitconfig", ".config/git", "Library/Caches"];
+
+/** A submodule or worktree keeps its git dir outside the project; git needs it, minus the parts that execute or reconfigure. */
+function externalGitDirs(root: string): string[] {
+  const out = spawnSync("git", ["-C", root, "rev-parse", "--absolute-git-dir", "--git-common-dir"], { encoding: "utf8" });
+  if (out.status !== 0) return [];
+  const dirs = out.stdout.trim().split("\n").map((d) => resolve(root, d));
+  return [...new Set(dirs)].filter((d) => !d.startsWith(`${root}/`));
+}
+
+export function profile(cwd: string, network: boolean, readAllow: string[] = [], deny: string[] = []): string {
+  const home = homedir();
+  const inHome = (p: string) => (p.startsWith("~/") ? join(home, p.slice(2)) : p);
+  const root = realpathSync(cwd);
+  const tmp = realpathSync(tmpdir());
+  const gitDirs = externalGitDirs(root);
+  const creds = [".ssh", ".aws", ".gnupg", ".config/gh", ".config/gcloud", ".kube", ".docker", ".netrc", ".npmrc", ".omniroute", ".claude", ".codex", ".kimi-code", "Library/Keychains"];
+  return [
+    "(version 1)",
+    "(allow default)",
+    ...(network ? [] : ["(deny network*)"]),
+    // Home is default-deny for reads: whatever a command reads can end up in the model's answer, and that answer
+    // is shared with agents that run on cloud subscriptions (~/.claude.json, app tokens, browser profiles ...).
+    `(deny file-read* (subpath ${q(home)}))`,
+    `(allow file-read-metadata (subpath ${q(home)}))`,
+    `(allow file-read* (subpath ${q(root)}) ${[...HOME_READABLE.map((p) => join(home, p)), ...readAllow.map(inHome), ...gitDirs].map((p) => `(subpath ${q(p)})`).join(" ")})`,
+    "(deny file-write*)",
+    `(allow file-write* (subpath ${q(root)}) (subpath ${q(tmp)}) (subpath "/private/tmp") (regex #"^/dev/") ${gitDirs.map((d) => `(subpath ${q(d)})`).join(" ")})`,
+    // Inside cwd: nothing that runs later outside the sandbox, nothing that reconfigures the hub.
+    `(deny file-write* (subpath ${q(join(root, ".agenthub"))}) ${[join(root, ".git"), ...gitDirs].map((d) => `(subpath ${q(join(d, "hooks"))}) (literal ${q(join(d, "config"))})`).join(" ")})`,
+    `(deny file-read* file-write* ${creds.map((c) => `(subpath ${q(join(home, c))})`).join(" ")})`,
+    `(deny file-read* file-write* ${denyRegexes(root, deny).join(" ")})`,
+  ].join("\n");
+}
+
+export interface ExecResult {
+  code: number | null;
+  output: string;
+}
+
+/** Run argv under seatbelt with a scrubbed environment. Never runs unsandboxed: no sandbox, no exec. */
+export function sandboxedExec(argv: string[], opts: { cwd: string; profile: string; timeoutMs?: number }): Promise<ExecResult> {
+  if (!sandboxAvailable()) return Promise.resolve({ code: null, output: "error: command execution needs macOS sandbox-exec and is disabled on this host" });
+  return new Promise((resolve) => {
+    const env = { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: homedir(), LANG: process.env.LANG ?? "en_US.UTF-8", TERM: "dumb", TMPDIR: tmpdir() };
+    // Own process group: a timeout has to take the grandchildren too, or they keep the pipes open and the project writable.
+    const child = spawn(SANDBOX_EXEC, ["-p", opts.profile, ...argv], { cwd: opts.cwd, env, stdio: ["ignore", "pipe", "pipe"], detached: true });
+    let output = "";
+    const take = (d: Buffer) => {
+      if (output.length < OUTPUT_CAP) output += d.toString();
+    };
+    child.stdout.on("data", take);
+    child.stderr.on("data", take);
+    const killGroup = () => {
+      try {
+        process.kill(-child.pid!, "SIGKILL");
+      } catch {
+        child.kill("SIGKILL");
+      }
+    };
+    const timer = setTimeout(killGroup, opts.timeoutMs ?? 120_000);
+    let done = false;
+    const finish = (code: number | null, signal: NodeJS.Signals | null) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      const clipped = output.length >= OUTPUT_CAP ? `${output.slice(0, OUTPUT_CAP)}\n(output truncated)` : output;
+      resolve({ code, output: signal ? `${clipped}\n(killed: ${signal}, timeout?)` : clipped });
+    };
+    child.on("error", (e) => (done || ((done = true), resolve({ code: null, output: `error: ${e.message}` }))));
+    child.on("close", finish);
+    // `close` waits for every holder of the pipes; after `exit` give stragglers a moment, then stop waiting and reap them.
+    child.on("exit", (code, signal) => setTimeout(() => (killGroup(), finish(code, signal)), 500).unref());
+  });
+}

package/src/local/tools.ts

@@ -0,0 +1,160 @@
+import { lstatSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { hasSegment, isDenied } from "./deny.ts";
+import { OUTPUT_CAP, sandboxedExec } from "./sandbox.ts";
+
+export { isDenied };
+
+export interface ToolContext {
+  cwd: string;
+  /** Extra denylist entries from config: substrings of the project-relative path. */
+  deny: string[];
+  /** Seatbelt profile for this project, built once per worker (`profile()` in sandbox.ts): it spawns git and must not run per tool call. */
+  sandboxProfile: string;
+  /** Ask the console. Resolves false on deny or timeout. */
+  permit: (title: string) => Promise<boolean>;
+  /** Publish a message to other peers mid-turn. Returns a one-line receipt. */
+  send: (text: string, to?: string[]) => string;
+}
+
+/** Not secret, but writing them changes what runs outside the worker's control. */
+const WRITE_DENY_SEGMENTS = [".git", ".agenthub"];
+
+const lexists = (p: string) => {
+  try {
+    lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** Absolute path inside cwd after resolving symlinks, or an Error. `write` also refuses .git and .agenthub. */
+export function guardPath(ctx: Pick<ToolContext, "cwd" | "deny">, path: string, mode: "read" | "write"): string {
+  const root = realpathSync(ctx.cwd);
+  const abs = resolve(root, path);
+  // Resolve symlinks on the deepest part that exists: a link pointing outside must not pass as an inside path.
+  // lstat, not exists: a dangling symlink "does not exist" to existsSync, yet a write through it lands at its target.
+  let existing = abs;
+  while (!lexists(existing)) existing = dirname(existing);
+  let realExisting: string;
+  try {
+    realExisting = realpathSync(existing);
+  } catch {
+    throw new Error(`${path} goes through a dangling symlink`);
+  }
+  const real = join(realExisting, relative(existing, abs));
+  const rel = relative(root, real);
+  if (rel.startsWith("..") || resolve(root, rel) !== real) throw new Error(`${path} is outside the project directory`);
+  if (isDenied(rel, ctx.deny)) throw new Error(`${path} is on the secrets denylist`);
+  if (mode === "write" && WRITE_DENY_SEGMENTS.some((s) => hasSegment(rel, s))) throw new Error(`${path} is not writable by the local worker`);
+  return real;
+}
+
+/** Shown to the person approving: enough of the content to know what they approve. */
+const preview = (text: string, n = 1500) => (text.length > n ? `${text.slice(0, n)}\n... (${text.length - n} more chars)` : text);
+
+/**
+ * git takes paths and revisions that never pass through guardPath: `diff --no-index /dev/null ~/.cargo/credentials.toml`,
+ * `show HEAD:.env`. Every argument is checked: nothing absolute, nothing with `..`, nothing on the denylist.
+ */
+function gitArgsProblem(args: string[], deny: string[]): string | undefined {
+  for (const arg of args.slice(1)) {
+    if (arg === "--no-index" || arg.startsWith("--output") || arg.startsWith("--ext-diff") || arg.startsWith("--textconv")) return `${arg} is not available`;
+    const path = arg.includes(":") ? arg.slice(arg.indexOf(":") + 1) : arg.replace(/^--[a-z-]+=/, "");
+    if (path.startsWith("/") || path.startsWith("~") || path.split("/").includes("..")) return `${arg} points outside the project`;
+    if (isDenied(path, deny)) return `${arg} is on the secrets denylist`;
+  }
+  return undefined;
+}
+
+const GIT_READ = new Set(["status", "diff", "log", "show", "ls-files", "blame", "rev-parse"]);
+const GIT_WRITE = new Set(["add", "commit", "restore", "checkout", "switch", "stash", "mv", "rm", "branch", "merge", "rebase", "cherry-pick", "revert", "tag"]);
+
+const str = { type: "string" } as const;
+const fn = (name: string, description: string, properties: Record<string, unknown>, required: string[]) => ({
+  type: "function",
+  function: { name, description, parameters: { type: "object", properties, required, additionalProperties: false } },
+});
+
+export const TOOL_SCHEMAS = [
+  fn("read", "Read a text file inside the project. Returns numbered lines.", { path: str, offset: { type: "integer", minimum: 1 }, limit: { type: "integer", minimum: 1 } }, ["path"]),
+  fn("write", "Create or overwrite a file inside the project. Needs the user's approval.", { path: str, content: str }, ["path", "content"]),
+  fn("edit", "Replace one exact, unique occurrence of `old` with `new` in a file. Needs the user's approval.", { path: str, old: str, new: str }, ["path", "old", "new"]),
+  fn("bash", "Run a shell command in the project directory, sandboxed: no writes outside the project, no credential reads, no network unless the hub enables it. Needs the user's approval.", { command: str, timeout_s: { type: "integer", minimum: 1, maximum: 600 } }, ["command"]),
+  fn("git", "Run git in the project. status, diff, log, show, ls-files, blame, rev-parse run freely; add, commit, restore, checkout, switch, stash, mv, rm, branch, merge, rebase, cherry-pick, revert, tag need approval; everything else (push, fetch, config, remote ...) is refused.", { args: { type: "array", items: str, minItems: 1 } }, ["args"]),
+  fn("hub_send", "Send a message to the other agents now, before your turn ends. Conclusions only. Your final answer is shared anyway; use this for something that cannot wait.", { text: str, to: { type: "array", items: str } }, ["text"]),
+];
+
+/** Every path-like argument of a call, for the memory capture filter. */
+export function touchedPaths(name: string, args: Record<string, unknown>): string[] {
+  if (name === "read" || name === "write" || name === "edit") return [String(args.path ?? "")];
+  if (name === "bash") return [String(args.command ?? "")];
+  if (name === "git") return (Array.isArray(args.args) ? args.args : []).map(String);
+  return [];
+}
+
+/** Executes one tool call. Never throws: every failure comes back as text for the model to read. */
+export async function runTool(name: string, rawArgs: string, ctx: ToolContext): Promise<string> {
+  let a: Record<string, any>;
+  try {
+    a = JSON.parse(rawArgs || "{}");
+  } catch {
+    return "error: tool arguments were not valid JSON";
+  }
+  try {
+    switch (name) {
+      case "read": {
+        const file = guardPath(ctx, String(a.path), "read");
+        if (statSync(file).size > 5_000_000) return "error: file is larger than 5 MB; use bash (head, grep, sed -n) to look at parts of it";
+        const lines = readFileSync(file, "utf8").split("\n");
+        const from = Math.max(1, Number(a.offset) || 1);
+        const out = lines.slice(from - 1, from - 1 + (Number(a.limit) || 2000)).map((l, i) => `${from + i}\t${l}`).join("\n");
+        return out.length > OUTPUT_CAP ? `${out.slice(0, OUTPUT_CAP)}\n(truncated: read again with offset/limit)` : out;
+      }
+      case "write": {
+        const file = guardPath(ctx, String(a.path), "write");
+        const content = String(a.content ?? "");
+        if (!(await ctx.permit(`write ${a.path} (${content.length} chars):\n${preview(content)}`))) return "error: the user did not approve this write";
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, content);
+        return `wrote ${a.path}`;
+      }
+      case "edit": {
+        const file = guardPath(ctx, String(a.path), "write");
+        const text = readFileSync(file, "utf8");
+        const count = text.split(String(a.old)).length - 1;
+        if (!a.old || count !== 1) return `error: \`old\` must match exactly once, it matched ${count} times`;
+        if (!(await ctx.permit(`edit ${a.path}:\n- ${preview(String(a.old), 600)}\n+ ${preview(String(a.new ?? ""), 600)}`))) return "error: the user did not approve this edit";
+        writeFileSync(file, text.replace(String(a.old), () => String(a.new ?? "")));
+        return `edited ${a.path}`;
+      }
+      case "bash": {
+        const command = String(a.command ?? "");
+        if (!command.trim()) return "error: empty command";
+        // The approver sees the whole command, not a prefix: what is hidden cannot be approved.
+        if (command.length > 4000) return "error: command longer than 4000 characters; put it in a script file with write, then run that";
+        if (!(await ctx.permit(`bash: ${command}`))) return "error: the user did not approve this command";
+        const res = await sandboxedExec(["/bin/bash", "-c", command], { cwd: ctx.cwd, profile: ctx.sandboxProfile, timeoutMs: (Number(a.timeout_s) || 120) * 1000 });
+        return `${res.output}\n(exit ${res.code})`;
+      }
+      case "git": {
+        const args: string[] = Array.isArray(a.args) ? a.args.map(String) : [];
+        const sub = args[0] ?? "";
+        if (!GIT_READ.has(sub) && !GIT_WRITE.has(sub)) return `error: git ${sub} is not available to the local worker`;
+        const problem = gitArgsProblem(args, ctx.deny);
+        if (problem) return `error: git ${sub}: ${problem}`;
+        if (GIT_WRITE.has(sub) && !(await ctx.permit(`git ${args.join(" ")}`))) return "error: the user did not approve this git command";
+        // Sandboxed like bash: flags such as --output or an editor cannot write outside the project or reach the network.
+        const res = await sandboxedExec(["git", "--no-pager", ...args], { cwd: ctx.cwd, profile: ctx.sandboxProfile });
+        return `${res.output}\n(exit ${res.code})`;
+      }
+      case "hub_send":
+        return a.text ? ctx.send(String(a.text), Array.isArray(a.to) ? a.to.map(String) : undefined) : "error: text is required";
+      default:
+        return `error: unknown tool ${name}`;
+    }
+  } catch (e) {
+    return `error: ${(e as Error).message}`;
+  }
+}

package/src/memory/brief.ts

@@ -0,0 +1,59 @@
+import type { PeerId } from "../hub/envelope.ts";
+import type { MemoryClient } from "./client.ts";
+
+export interface BriefItem {
+  id: number;
+  time: string;
+  type: string;
+  title: string;
+}
+
+/** Rows of claude-mem's index tables: `| #65499 | 12:30 PM | ◆ | Title | ~372 |`. A row that does not match is skipped, never an error. */
+export function parseRows(markdown: string | undefined): BriefItem[] {
+  const out: BriefItem[] = [];
+  for (const m of (markdown ?? "").matchAll(/^\|\s*#(\d+)\s*\|\s*([^|]*?)\s*\|\s*([^|]*?)\s*\|\s*(.*?)\s*\|/gm)) {
+    out.push({ id: Number(m[1]), time: m[2]!, type: m[3]!, title: m[4]!.replace(/\s*<-\s*\*\*ANCHOR\*\*/, "") });
+  }
+  return out;
+}
+
+/** Index first, then the neighbourhood of the top hit: the retrieval both task briefs and `ahub ask` use. Deduplicated, in order. */
+export async function related(client: MemoryClient, project: string, query: string, around = 3): Promise<BriefItem[]> {
+  const hits = parseRows(await client.search(query.slice(0, 300), project, 10));
+  if (!hits.length) return [];
+  const near = parseRows(await client.timeline(hits[0]!.id, project, around, around));
+  const out: BriefItem[] = [];
+  for (const item of [...hits, ...near]) if (!out.some((o) => o.id === item.id)) out.push(item);
+  return out;
+}
+
+/**
+ * Task briefs: what memory already knows about a piece of work, handed over with it. Index first (search), then the
+ * neighbourhood of the top hit (timeline); details stay in claude-mem for the receiver to fetch by id. A peer is never
+ * shown the same observation twice in one hub run.
+ */
+export class Briefs {
+  private readonly seen = new Map<PeerId, Set<number>>();
+
+  constructor(
+    private readonly client: MemoryClient,
+    private readonly project: string,
+    private readonly maxItems = 8,
+  ) {}
+
+  async forTask(peer: PeerId, task: { title: string; refs: { paths?: string[] } }): Promise<string | undefined> {
+    const found = await related(this.client, this.project, [task.title, ...(task.refs.paths ?? [])].join(" "));
+    if (!found.length) return undefined;
+    const seen = this.seen.get(peer) ?? new Set<number>();
+    this.seen.set(peer, seen);
+    const items: BriefItem[] = [];
+    for (const item of found) {
+      if (seen.has(item.id)) continue;
+      items.push(item);
+      if (items.length === this.maxItems) break;
+    }
+    if (!items.length) return undefined;
+    for (const item of items) seen.add(item.id);
+    return ["Memory brief (claude-mem; fetch details by id if you need them):", ...items.map((i) => `#${i.id} ${i.time} ${i.type} ${i.title}`)].join("\n");
+  }
+}