@openparachute/agent 0.1.2 → 0.2.2

package/src/runner.ts

@@ -0,0 +1,255 @@
+/**
+ * The runner — a scheduler that fires scheduled jobs (design
+ * `2026-06-17-runner-scheduled-agent-turns.md`).
+ *
+ * It does NOT execute anything. On each tick it loads the current jobs (from the
+ * VAULT-NATIVE store), asks each enabled job "are you due?" and, if so, FIRES it —
+ * where "fire" means "inject an inbound note onto the job's vault channel." The
+ * existing vault trigger → agent-turn → outbound flow does all the work. The
+ * runner is a clock that authors messages.
+ *
+ * Determinism is the design's hard requirement: the testable core takes an
+ * INJECTABLE clock (`now`), INJECTABLE load + fire + persist fns, and an
+ * INJECTABLE tick driver. The daemon's boot supplies the real ones (`Date`, the
+ * vault job store, the vault-inject fire, a `setInterval` tick); tests supply
+ * fakes and step time by hand. No real `setInterval`/`Date.now()` appears in
+ * `tick()` itself.
+ *
+ * Storage-agnostic: the runner never touches the vault directly. It calls:
+ *   - `loadJobs()`        → the current jobs (the store queries the vault),
+ *   - `fire(job)`         → inject the inbound note (the transport writes it),
+ *   - `persistFire(job)`  → write back lastRunAt/lastStatus (the store PATCHes).
+ *
+ * `nextRunAt` is COMPUTED IN MEMORY and NEVER persisted. The runner keeps a small
+ * per-job horizon map (keyed by id) across ticks so a job fires once per slot; a
+ * job seen for the first time gets a horizon computed from now (and won't fire
+ * until that horizon passes — so a freshly-created job never back-fires on its
+ * first tick).
+ *
+ * Catch-up policy = FIRE-ONCE-ON-MISS: if a job's horizon is already in the past
+ * on a tick (the daemon was down across one or more slots), the job fires ONCE and
+ * the horizon is recomputed forward from now — never replaying every missed slot.
+ *
+ * Idempotency under overlap: a job that's mid-fire (its async fire hasn't resolved)
+ * is SKIPPED on subsequent ticks, so a slow vault write can't be double-fired.
+ */
+
+import { nextRunAfter } from "./cron.ts";
+import type { Job } from "./jobs.ts";
+
+/** Load the current jobs (the vault-native store queries the vault). Async. */
+export type LoadJobsFn = () => Promise<Job[]>;
+
+/** Fire a job: inject its message as an inbound note onto its channel. Async. */
+export type FireFn = (job: Job) => Promise<void>;
+
+/** Persist a job's bookkeeping (lastRunAt/lastStatus) after a fire. Async. */
+export type PersistFireFn = (job: Job) => Promise<void>;
+
+/** A scheduler driver: schedule `fn` to run every `ms`, return a cancel handle. */
+export interface TickDriver {
+  schedule(fn: () => void, ms: number): { cancel: () => void };
+}
+
+export interface RunnerOptions {
+  /** Load the current jobs (queries the vault each tick). */
+  loadJobs: LoadJobsFn;
+  /** Fire a due job (inject the inbound note). */
+  fire: FireFn;
+  /** Persist a job's bookkeeping after a fire. */
+  persistFire: PersistFireFn;
+  /** Clock — injected for determinism. Default `() => new Date()`. */
+  now?: () => Date;
+  /** Tick driver — injected for determinism. Default a real-setInterval driver. */
+  driver?: TickDriver;
+  /** Tick interval (ms). Default 30s. */
+  intervalMs?: number;
+  /** Log sink (errors per job/tick never throw out). Default `console`. */
+  log?: { warn: (msg: string) => void; error: (msg: string) => void };
+}
+
+/** A real `setInterval`-backed tick driver (the daemon uses this; tests don't). */
+export function realTickDriver(): TickDriver {
+  return {
+    schedule(fn, ms) {
+      const t = setInterval(fn, ms);
+      // Don't keep the process alive solely for the runner tick.
+      if (typeof t === "object" && t && "unref" in t) (t as { unref: () => void }).unref();
+      return { cancel: () => clearInterval(t) };
+    },
+  };
+}
+
+const DEFAULT_INTERVAL_MS = 30_000;
+
+export class Runner {
+  private readonly loadJobs: LoadJobsFn;
+  private readonly fire: FireFn;
+  private readonly persistFire: PersistFireFn;
+  private readonly now: () => Date;
+  private readonly driver: TickDriver;
+  private readonly intervalMs: number;
+  private readonly log: { warn: (msg: string) => void; error: (msg: string) => void };
+
+  /**
+   * Per-job next-fire horizon (ISO), COMPUTED IN MEMORY and carried across ticks.
+   * Keyed by job id. Seeded the first time a job is seen; recomputed forward after
+   * each fire. Not persisted — the vault store doesn't carry nextRunAt.
+   */
+  private readonly horizons = new Map<string, string>();
+  /** Job ids currently mid-fire — skipped by an interleaving tick (overlap guard). */
+  private readonly inFlight = new Set<string>();
+  private handle: { cancel: () => void } | undefined;
+
+  constructor(opts: RunnerOptions) {
+    this.loadJobs = opts.loadJobs;
+    this.fire = opts.fire;
+    this.persistFire = opts.persistFire;
+    this.now = opts.now ?? (() => new Date());
+    this.driver = opts.driver ?? realTickDriver();
+    this.intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+    this.log = opts.log ?? {
+      warn: (m) => console.warn(m),
+      error: (m) => console.error(m),
+    };
+  }
+
+  /**
+   * The stable per-job key for horizon + in-flight tracking. Prefer the vault
+   * `noteId` (globally unique across channels/vaults) so two jobs that share a
+   * SLUG in different channels don't collide; fall back to the slug `id` for an
+   * in-memory job that hasn't been persisted yet (tests).
+   */
+  private keyOf(job: Job): string {
+    return job.noteId ?? job.id;
+  }
+
+  /** Compute the next fire instant for a job after `from`, or null on a bad cron. */
+  private computeNext(job: Job, from: Date): Date | null {
+    try {
+      return nextRunAfter(job.schedule.cron, job.schedule.tz, from);
+    } catch (err) {
+      this.log.warn(`runner: job "${job.id}" has an unschedulable cron: ${(err as Error).message}`);
+      return null;
+    }
+  }
+
+  /** Start the periodic tick. Idempotent (a second start is a no-op). */
+  start(): void {
+    if (this.handle) return;
+    this.handle = this.driver.schedule(() => {
+      // A tick must never throw out (it'd kill the interval). `tick()` already
+      // guards; this is belt-and-suspenders for an unexpected throw.
+      void this.tick().catch((err) => this.log.error(`runner: tick failed: ${err}`));
+    }, this.intervalMs);
+  }
+
+  /** Stop the tick. Safe to call when not started. */
+  stop(): void {
+    this.handle?.cancel();
+    this.handle = undefined;
+  }
+
+  /**
+   * One scheduling pass. Loads the current jobs; for each enabled, not-in-flight
+   * job whose horizon is due (≤ now), fires it once and advances the horizon
+   * forward from now. A job seen for the first time gets a horizon computed (it
+   * won't fire this tick — it's in the future). Per-job failures are caught and
+   * recorded; one bad job never aborts the pass. A load failure is logged and the
+   * tick is a no-op (it retries next interval). Awaitable for deterministic tests.
+   */
+  async tick(): Promise<void> {
+    const at = this.now();
+    let jobs: Job[];
+    try {
+      jobs = await this.loadJobs();
+    } catch (err) {
+      this.log.error(`runner: loadJobs failed (skipping this tick): ${(err as Error).message}`);
+      return;
+    }
+
+    // Prune horizons for jobs that no longer exist (deleted), so the map can't grow.
+    const liveKeys = new Set(jobs.map((j) => this.keyOf(j)));
+    for (const key of [...this.horizons.keys()]) {
+      if (!liveKeys.has(key)) this.horizons.delete(key);
+    }
+
+    const fires: Array<Promise<void>> = [];
+    for (const job of jobs) {
+      if (!job.enabled) continue;
+      const key = this.keyOf(job);
+      if (this.inFlight.has(key)) continue; // overlap guard — already firing.
+
+      let horizon = this.horizons.get(key);
+      if (!horizon) {
+        // First time we've seen this job — seed a horizon from now. Future → not
+        // due this tick (a freshly-created job never back-fires on first sight).
+        const next = this.computeNext(job, at);
+        if (!next) continue; // unschedulable cron — skip (logged in computeNext).
+        horizon = next.toISOString();
+        this.horizons.set(key, horizon);
+        job.nextRunAt = horizon;
+        continue;
+      }
+
+      job.nextRunAt = horizon;
+      if (new Date(horizon).getTime() <= at.getTime()) {
+        fires.push(this.fireOne(job, at));
+      }
+    }
+    await Promise.allSettled(fires);
+  }
+
+  /**
+   * Fire one due job: mark in-flight, inject, record bookkeeping, recompute the
+   * horizon FORWARD FROM NOW (fire-once-on-miss — never replay missed slots),
+   * persist the bookkeeping. Never throws — a fire failure is recorded as
+   * `lastStatus: "error: …"` and still advances the horizon (so it retries the
+   * next slot rather than getting stuck).
+   */
+  private async fireOne(job: Job, at: Date): Promise<void> {
+    const key = this.keyOf(job);
+    this.inFlight.add(key);
+    try {
+      await this.fire(job);
+      job.lastStatus = "ok";
+    } catch (err) {
+      job.lastStatus = `error: ${(err as Error).message}`;
+      this.log.error(`runner: job "${job.id}" fire failed: ${(err as Error).message}`);
+    } finally {
+      job.lastRunAt = at.toISOString();
+      // Recompute the horizon from NOW (not the missed slot) — fire-once-on-miss.
+      const next = this.computeNext(job, at);
+      if (next) {
+        this.horizons.set(key, next.toISOString());
+        job.nextRunAt = next.toISOString();
+      } else {
+        this.horizons.delete(key);
+        job.nextRunAt = undefined;
+      }
+      this.inFlight.delete(key);
+      // Persist the bookkeeping (lastRunAt/lastStatus) — best-effort.
+      try {
+        await this.persistFire(job);
+      } catch (err) {
+        this.log.warn(`runner: persist bookkeeping for "${job.id}" failed (continuing): ${(err as Error).message}`);
+      }
+    }
+  }
+
+  /**
+   * Fire a single job immediately, on demand (the "Run now" API). Loads jobs to
+   * find it, bypasses the schedule + due check but honors the overlap guard and
+   * records bookkeeping exactly like a scheduled fire. Returns the resulting
+   * `lastStatus`. Throws only if the job is unknown; a fire failure is recorded
+   * and returned, not thrown.
+   */
+  async runNow(id: string): Promise<string> {
+    const jobs = await this.loadJobs();
+    const job = jobs.find((j) => j.id === id);
+    if (!job) throw new Error(`runner: no job with id "${id}"`);
+    if (this.inFlight.has(this.keyOf(job))) return job.lastStatus ?? "already running";
+    await this.fireOne(job, this.now());
+    return job.lastStatus ?? "ok";
+  }
+}

package/src/sandbox/config.test.ts

@@ -0,0 +1,150 @@
+import { describe, test, expect } from "bun:test";
+import { buildSandboxConfig } from "./config.ts";
+import type { AgentSpec, BaseBinds } from "./types.ts";
+import type { EgressBaseInput } from "./egress.ts";
+
+const BASE_BINDS: BaseBinds = {
+  workspace: "/state/sessions/arm",
+  runtimeReadOnly: ["/home/op/.claude"],
+};
+const EGRESS_BASE: EgressBaseInput = { hubOrigin: "https://hub.example.com" };
+
+// Most cases exercise the egress floor, which needs network "restricted". Scoped
+// reads are the DEFAULT (filesystem "workspace"), so the helper only sets the
+// network and leaves filesystem at its default. A spread `p` overrides (e.g.
+// `filesystem: "full"` to test broad reads).
+function specOf(p: Partial<AgentSpec> = {}): AgentSpec {
+  return { name: "arm", channels: ["ch"], network: "restricted", ...p };
+}
+
+describe("buildSandboxConfig — defaults (scoped reads + open network)", () => {
+  test("DEFAULT: scoped reads (home tree denied) + open network (no allowedDomains), writes confined", () => {
+    const cfg = buildSandboxConfig({
+      spec: { name: "arm", channels: ["ch"] }, // no filesystem/network → both defaults
+      baseBinds: BASE_BINDS,
+      egressBase: EGRESS_BASE,
+      platform: "darwin",
+    });
+    // Scoped reads by default: the home tree is DENIED — this is what keeps the
+    // operator's secrets (~/.parachute/operator.token, SSH keys) unreadable.
+    expect(cfg.filesystem.denyRead).toContain("/Users");
+    // Open network by default: allowedDomains omitted entirely (runtime = no restriction).
+    expect((cfg.network as { allowedDomains?: string[] }).allowedDomains).toBeUndefined();
+    // Writes confined to the workspace.
+    expect(cfg.filesystem.allowWrite).toContain("/state/sessions/arm");
+  });
+
+  test("filesystem 'full': broad reads (no home-tree deny), writes still confined", () => {
+    const cfg = buildSandboxConfig({
+      spec: { name: "arm", channels: ["ch"], filesystem: "full" },
+      baseBinds: BASE_BINDS,
+      egressBase: EGRESS_BASE,
+      platform: "darwin",
+    });
+    expect(cfg.filesystem.denyRead).toEqual([]);
+    expect(cfg.filesystem.allowWrite).toContain("/state/sessions/arm");
+  });
+});
+
+describe("buildSandboxConfig — spec → SandboxRuntimeConfig", () => {
+  test("network: deny-by-default + base floor present, deniedDomains empty", () => {
+    const cfg = buildSandboxConfig({
+      spec: specOf({ egress: [] }),
+      baseBinds: BASE_BINDS,
+      egressBase: EGRESS_BASE,
+      platform: "darwin",
+    });
+    expect(cfg.network.allowedDomains).toContain("api.anthropic.com");
+    expect(cfg.network.allowedDomains).toContain("hub.example.com");
+    expect(cfg.network.deniedDomains).toEqual([]);
+  });
+
+  test("SECURITY: a spec with foreign egress still carries the base floor", () => {
+    const cfg = buildSandboxConfig({
+      spec: specOf({ egress: ["registry.npmjs.org"] }),
+      baseBinds: BASE_BINDS,
+      egressBase: EGRESS_BASE,
+      platform: "darwin",
+    });
+    expect(cfg.network.allowedDomains).toContain("api.anthropic.com");
+    expect(cfg.network.allowedDomains).toContain("hub.example.com");
+    expect(cfg.network.allowedDomains).toContain("registry.npmjs.org");
+  });
+
+  test("filesystem: scoped reads (deny home tree, re-allow binds) + write confinement", () => {
+    const cfg = buildSandboxConfig({
+      spec: specOf({ mounts: [{ hostPath: "/proj", mountPath: "/work", mode: "rw" }] }),
+      baseBinds: BASE_BINDS,
+      egressBase: EGRESS_BASE,
+      platform: "darwin",
+    });
+    expect(cfg.filesystem.denyRead).toContain("/Users");
+    expect(cfg.filesystem.allowRead).toContain("/state/sessions/arm");
+    expect(cfg.filesystem.allowRead).toContain("/home/op/.claude");
+    expect(cfg.filesystem.allowRead).toContain("/proj");
+    expect(cfg.filesystem.allowWrite).toContain("/state/sessions/arm");
+    expect(cfg.filesystem.allowWrite).toContain("/proj");
+  });
+
+  test("Linux platform denies /home instead of /Users", () => {
+    const cfg = buildSandboxConfig({
+      spec: specOf(),
+      baseBinds: BASE_BINDS,
+      egressBase: EGRESS_BASE,
+      platform: "linux",
+    });
+    expect(cfg.filesystem.denyRead).toContain("/home");
+    expect(cfg.filesystem.denyRead).not.toContain("/Users");
+  });
+
+  test("allowPty defaults true (interactive claude needs a pty)", () => {
+    const cfg = buildSandboxConfig({
+      spec: specOf(),
+      baseBinds: BASE_BINDS,
+      egressBase: EGRESS_BASE,
+      platform: "darwin",
+    });
+    expect(cfg.allowPty).toBe(true);
+  });
+
+  test("ripgrep override threads through when provided", () => {
+    const cfg = buildSandboxConfig({
+      spec: specOf(),
+      baseBinds: BASE_BINDS,
+      egressBase: EGRESS_BASE,
+      platform: "darwin",
+      ripgrep: { command: "/abs/rg" },
+    });
+    expect(cfg.ripgrep).toEqual({ command: "/abs/rg" });
+  });
+
+  test("a restricted-network config carries the full runtime shape (allowedDomains present)", () => {
+    const cfg = buildSandboxConfig({
+      spec: specOf(), // network "restricted" → allowedDomains present
+      baseBinds: BASE_BINDS,
+      egressBase: EGRESS_BASE,
+      platform: "darwin",
+    });
+    expect(cfg.network).toHaveProperty("allowedDomains");
+    expect(cfg.network).toHaveProperty("deniedDomains");
+    expect(cfg.filesystem).toHaveProperty("denyRead");
+    expect(cfg.filesystem).toHaveProperty("allowRead");
+    expect(cfg.filesystem).toHaveProperty("allowWrite");
+    expect(cfg.filesystem).toHaveProperty("denyWrite");
+  });
+
+  test("an open-network config OMITS allowedDomains but keeps the rest of the shape", () => {
+    const cfg = buildSandboxConfig({
+      spec: { name: "arm", channels: ["ch"] }, // default → network open
+      baseBinds: BASE_BINDS,
+      egressBase: EGRESS_BASE,
+      platform: "darwin",
+    });
+    // allowedDomains is deliberately ABSENT on open (the runtime's allow-all shape);
+    // this is NOT a protocol guarantee that allowedDomains is always present.
+    expect(cfg.network).not.toHaveProperty("allowedDomains");
+    expect(cfg.network).toHaveProperty("deniedDomains");
+    expect(cfg.filesystem).toHaveProperty("denyRead");
+    expect(cfg.filesystem).toHaveProperty("allowWrite");
+  });
+});

package/src/sandbox/config.ts

@@ -0,0 +1,102 @@
+/**
+ * Map an agent-spec → a `SandboxRuntimeConfig` for `@anthropic-ai/sandbox-runtime`
+ * (design §3 — the isolation envelope).
+ *
+ * The runtime config shape (verified against the package's own types,
+ * `@anthropic-ai/sandbox-runtime` 0.0.54 `SandboxRuntimeConfig`):
+ *
+ *   {
+ *     network:    { allowedDomains: string[], deniedDomains: string[] },
+ *     filesystem: { denyRead: string[], allowRead?: string[],
+ *                   allowWrite: string[], denyWrite: string[] },
+ *     …optional knobs (allowPty, bwrapPath, ripgrep, …)
+ *   }
+ *
+ * This module is the single place spec → runtime-config happens, so the egress
+ * floor (§4.4) and scoped-read policy (§4.5) are guaranteed on every launch.
+ */
+
+import type { SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
+import type { AgentSpec, BaseBinds, SandboxPlatform } from "./types.ts";
+import { composeEgressAllowlist, type EgressBaseInput } from "./egress.ts";
+import { composeFilesystemView } from "./mounts.ts";
+
+export interface BuildSandboxConfigInput {
+  spec: AgentSpec;
+  /** Workspace + runtime/config binds the contract always grants. */
+  baseBinds: BaseBinds;
+  /** Origins for the non-removable egress base. */
+  egressBase: EgressBaseInput;
+  /** Target platform. Defaults to the running platform. */
+  platform?: SandboxPlatform;
+  /**
+   * Allow the session to allocate a pty (a tmux/interactive `claude` needs one).
+   * Defaults true. Surfaced so a non-interactive arm can drop it.
+   */
+  allowPty?: boolean;
+  /**
+   * Optional ripgrep override the runtime uses for deny-path scanning. On macOS
+   * the runtime needs a ripgrep binary; pass `{ command: <abs path> }` when the
+   * host has no `rg` on PATH. Omitted = the runtime's own resolution.
+   */
+  ripgrep?: { command: string; args?: string[] };
+}
+
+/** Resolve the running platform to the two we support. */
+export function currentSandboxPlatform(): SandboxPlatform {
+  return process.platform === "darwin" ? "darwin" : "linux";
+}
+
+/**
+ * Build the `SandboxRuntimeConfig` for an agent spec. The egress allowlist is the
+ * non-removable base unioned with the spec's additions; the filesystem view is
+ * scoped-read (home-tree denied, binds re-allowed) with writes confined to the
+ * workspace + rw mounts.
+ */
+export function buildSandboxConfig(input: BuildSandboxConfigInput): SandboxRuntimeConfig {
+  const platform = input.platform ?? currentSandboxPlatform();
+
+  // The two containment boundaries are INDEPENDENT (Anthropic's model). Each has a
+  // security-first default: reads scoped to the workspace, network open.
+  const scopedReads = input.spec.filesystem !== "full"; // default "workspace" = scoped
+  const restrictedNet = input.spec.network === "restricted"; // default "open"
+
+  // Filesystem: scoped reads (deny home tree, re-allow private home + claude
+  // runtime + the working dir + mounts) unless explicitly "full". Writes are
+  // confined to the private home + the working dir + rw mounts in BOTH cases. The
+  // scoped default is what keeps the operator's secrets (e.g.
+  // ~/.parachute/operator.token) unreadable even with the network open. The spec's
+  // `workspace` (the shared real dir the agent works from) is threaded in as an rw
+  // working-root — decoupled from the private home, so `.mcp.json`'s secrets stay
+  // per-agent even when the working dir is shared (design
+  // 2026-06-16-agent-filesystem-and-sharing.md).
+  const fs = composeFilesystemView(
+    input.baseBinds,
+    input.spec.mounts,
+    platform,
+    scopedReads,
+    input.spec.workspace,
+  );
+
+  // Network: "open" (default) OMITS `allowedDomains` — the runtime treats an absent
+  // allowedDomains as "no restriction" (verified: present-but-empty = block all,
+  // absent = allow all). "restricted" = the non-removable base UNIONed with the
+  // spec's additions. The cast is because the runtime's TS type marks allowedDomains
+  // required while its runtime honors the absent case as the documented allow-all.
+  const network: SandboxRuntimeConfig["network"] = restrictedNet
+    ? { allowedDomains: composeEgressAllowlist(input.egressBase, input.spec.egress), deniedDomains: [] }
+    : ({ deniedDomains: [] } as unknown as SandboxRuntimeConfig["network"]);
+
+  const config: SandboxRuntimeConfig = {
+    network,
+    filesystem: {
+      denyRead: fs.denyRead,
+      allowRead: fs.allowRead,
+      allowWrite: fs.allowWrite,
+      denyWrite: fs.denyWrite,
+    },
+    allowPty: input.allowPty ?? true,
+  };
+  if (input.ripgrep) config.ripgrep = input.ripgrep;
+  return config;
+}

package/src/sandbox/egress.test.ts

@@ -0,0 +1,113 @@
+import { describe, test, expect } from "bun:test";
+import {
+  ANTHROPIC_EGRESS_HOSTS,
+  baseEgressAllowlist,
+  composeEgressAllowlist,
+  hostFromOrigin,
+  type EgressBaseInput,
+} from "./egress.ts";
+
+const BASE: EgressBaseInput = { hubOrigin: "https://hub.example.com" };
+
+describe("hostFromOrigin", () => {
+  test("reduces an origin to its hostname (strips scheme + port + path)", () => {
+    expect(hostFromOrigin("https://hub.example.com:1939/admin")).toBe("hub.example.com");
+  });
+  test("passes a bare host through", () => {
+    expect(hostFromOrigin("registry.npmjs.org")).toBe("registry.npmjs.org");
+  });
+  test("strips a :port from a bare host:port", () => {
+    expect(hostFromOrigin("127.0.0.1:1939")).toBe("127.0.0.1");
+  });
+  test("preserves loopback (a co-located dev hub is loopback)", () => {
+    expect(hostFromOrigin("http://127.0.0.1:1939")).toBe("127.0.0.1");
+  });
+  test("returns null for empty / nullish input", () => {
+    expect(hostFromOrigin("")).toBeNull();
+    expect(hostFromOrigin(undefined)).toBeNull();
+    expect(hostFromOrigin("   ")).toBeNull();
+  });
+});
+
+describe("baseEgressAllowlist — the non-removable base", () => {
+  test("always includes the Anthropic hosts + the hub host", () => {
+    const base = baseEgressAllowlist(BASE);
+    for (const h of ANTHROPIC_EGRESS_HOSTS) expect(base).toContain(h);
+    expect(base).toContain("hub.example.com");
+  });
+
+  test("includes a distinct vault host when given", () => {
+    const base = baseEgressAllowlist({ ...BASE, vaultOrigin: "https://vault.example.com" });
+    expect(base).toContain("vault.example.com");
+  });
+
+  test("dedupes a vault origin equal to the hub origin", () => {
+    const base = baseEgressAllowlist({
+      hubOrigin: "https://h.example.com",
+      vaultOrigin: "https://h.example.com",
+    });
+    expect(base.filter((h) => h === "h.example.com")).toHaveLength(1);
+  });
+});
+
+describe("composeEgressAllowlist — base floor is non-removable, spec is additive", () => {
+  test("an empty spec egress still gets the full base (weaver-style arm)", () => {
+    const allow = composeEgressAllowlist(BASE, []);
+    for (const h of ANTHROPIC_EGRESS_HOSTS) expect(allow).toContain(h);
+    expect(allow).toContain("hub.example.com");
+  });
+
+  test("an undefined spec egress still gets the full base", () => {
+    const allow = composeEgressAllowlist(BASE, undefined);
+    expect(allow).toContain("api.anthropic.com");
+    expect(allow).toContain("hub.example.com");
+  });
+
+  test("spec hosts are ADDED on top of the base", () => {
+    const allow = composeEgressAllowlist(BASE, ["registry.npmjs.org", "pypi.org"]);
+    // base present...
+    expect(allow).toContain("api.anthropic.com");
+    expect(allow).toContain("hub.example.com");
+    // ...plus the additions
+    expect(allow).toContain("registry.npmjs.org");
+    expect(allow).toContain("pypi.org");
+  });
+
+  test("SECURITY: a spec that lists ONLY a foreign host CANNOT drop the base — the base is still present", () => {
+    // A spec authored to omit the base entirely (the malicious-omit case).
+    const allow = composeEgressAllowlist(BASE, ["evil.example.com"]);
+    // The base floor survives regardless of what the spec listed.
+    expect(allow).toContain("api.anthropic.com");
+    expect(allow).toContain("hub.example.com");
+    // The spec's own host is added (additive), not a replacement.
+    expect(allow).toContain("evil.example.com");
+  });
+
+  test("SECURITY: a spec cannot REPLACE the Anthropic host with a look-alike — both end up present, base is not dropped", () => {
+    // A spec that tries to "override" the Anthropic host by re-declaring a near-miss.
+    const allow = composeEgressAllowlist(BASE, ["api.anthropic.com.evil.example.com"]);
+    // The real Anthropic apex is still on the list (the base recomputed from code).
+    expect(allow).toContain("api.anthropic.com");
+    // The look-alike is just an additional (separate) host, not a substitution.
+    expect(allow).toContain("api.anthropic.com.evil.example.com");
+    // And the look-alike did not evict the real host.
+    expect(allow.indexOf("api.anthropic.com")).toBeGreaterThanOrEqual(0);
+  });
+
+  test("the base always sorts FIRST (recomputed from code, prepended)", () => {
+    const allow = composeEgressAllowlist(BASE, ["z-late.example.com"]);
+    expect(allow[0]).toBe("api.anthropic.com");
+    expect(allow[allow.length - 1]).toBe("z-late.example.com");
+  });
+
+  test("spec origins are normalized to hosts (full URL and bare host land the same)", () => {
+    const a = composeEgressAllowlist(BASE, ["https://registry.npmjs.org"]);
+    const b = composeEgressAllowlist(BASE, ["registry.npmjs.org"]);
+    expect(a).toEqual(b);
+  });
+
+  test("dedupes a spec host that duplicates a base host", () => {
+    const allow = composeEgressAllowlist(BASE, ["hub.example.com"]);
+    expect(allow.filter((h) => h === "hub.example.com")).toHaveLength(1);
+  });
+});