@ninemind/agentgem 0.2.0 → 0.3.0

package/dist/gem/distill.js

@@ -0,0 +1,162 @@
+import { CLAUDE_AGENT, analysisWorkspace, defaultConnectFn, currentTestConnectFn } from "./acpRecommender.js";
+// skillify Phase-0 thresholds (proposal §4): "invoked 2+ times" and ">20 lines of
+// logic" (~4 distinct action verbs). The third criterion (clear trigger phrase) is
+// deferred to the agent + validation.
+export const MIN_RECURRENCE = 2;
+export const MIN_STEPS = 3; // procedures are mined as >=3-gram action runs (§3c)
+const KEBAB_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const MUTATING_TOOL_RE = /^(Bash|Edit|Write|NotebookEdit)$/;
+function extractJson(text) {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    return start >= 0 && end > start ? text.slice(start, end + 1) : text;
+}
+/**
+ * Validate a raw agent response into DistilledSkills. A distilled skill cannot be
+ * checked against the inventory (it is new), so validation is shape + evidence-
+ * grounding (proposal §6): kebab name, non-empty triggers + body, slug not already
+ * installed, and every claimed tool present in the candidates' sampled evidence.
+ * `mutating` is forced true when the procedure touches Bash/Edit/Write. Never throws.
+ */
+export function validateDistilled(raw, inv, candidates) {
+    let obj = raw;
+    if (typeof raw === "string") {
+        try {
+            obj = JSON.parse(extractJson(raw));
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!obj || typeof obj !== "object" || !Array.isArray(obj.distilled))
+        return [];
+    const installed = new Set([
+        ...inv.project.skills.map((s) => s.name),
+        ...(inv.global?.skills ?? []).map((s) => s.name),
+    ]);
+    // Evidence pool: tools that actually appear in any candidate's sampled run.
+    const evidenceTools = new Set();
+    for (const c of candidates)
+        for (const st of c.sample.steps)
+            evidenceTools.add(st.tool);
+    const evidenceIsMutating = [...evidenceTools].some((t) => MUTATING_TOOL_RE.test(t));
+    const sessions = candidates.reduce((m, c) => Math.max(m, c.sessions), 0);
+    const exampleSequence = candidates[0]?.verbs ?? [];
+    const root = inv.project.root;
+    const out = [];
+    for (const it of obj.distilled) {
+        if (!it || typeof it !== "object")
+            continue;
+        if (typeof it.name !== "string" || !KEBAB_RE.test(it.name)) {
+            console.error(`distill: dropping non-kebab name '${it.name}'`);
+            continue;
+        }
+        if (installed.has(it.name)) {
+            console.error(`distill: dropping slug colliding with installed skill '${it.name}'`);
+            continue;
+        }
+        const triggers = Array.isArray(it.triggers) ? it.triggers.filter((t) => typeof t === "string" && t.trim().length > 0) : [];
+        if (!triggers.length)
+            continue;
+        if (typeof it.body !== "string" || !it.body.trim())
+            continue;
+        const tools = Array.isArray(it.tools) ? it.tools.filter((t) => typeof t === "string") : [];
+        if (tools.some((t) => !evidenceTools.has(t))) {
+            console.error(`distill: dropping '${it.name}' — fabricated tool not in evidence`);
+            continue;
+        }
+        out.push({
+            name: it.name,
+            description: typeof it.description === "string" ? it.description : "",
+            triggers,
+            tools,
+            mutating: evidenceIsMutating || tools.some((t) => MUTATING_TOOL_RE.test(t)),
+            body: it.body,
+            evidence: { sessions, exampleSequence, root },
+            status: "draft",
+            confidence: ["high", "medium", "low"].includes(it.confidence) ? it.confidence : "medium",
+        });
+    }
+    return out;
+}
+export function distillCandidates(signal, opts = {}) {
+    const minRecurrence = opts.minRecurrence ?? MIN_RECURRENCE;
+    const minSteps = opts.minSteps ?? MIN_STEPS;
+    const sessions = signal.sequences?.sessions;
+    if (!signal.procedures || !sessions)
+        return [];
+    return signal.procedures
+        .filter((p) => p.sessions >= minRecurrence && p.verbs.length >= minSteps)
+        .map((p) => ({ ...p, sample: sessions[p.sampleSessionIdx] }))
+        .filter((c) => c.sample !== undefined);
+}
+// ── The generative ACP step (proposal §5) ───────────────────────────────────
+// Distinct from the selective recommender's GROUNDING prompt. Names/scopes a
+// skill by the MISSION it accomplished; dedups against installed skills.
+export const DISTILL = (candidatesJson, installedSkillsJson) => `You distill the WORKFLOW a coding agent used to accomplish a mission into a ` +
+    `reusable skill. Each candidate carries: a mission hint (the task the user set ` +
+    `out to do + the outcome), an ordered redacted sequence of tool calls, and how ` +
+    `many sessions it recurred across.\n` +
+    `Name and scope each skill by the MISSION it accomplished — not by its tool ` +
+    `fingerprint. For each genuinely reusable workflow, emit a skill with:\n` +
+    `  frontmatter: name (kebab), description (one paragraph), triggers (phrases a ` +
+    `user would actually type), tools (from the sequence), mutating (bool)\n` +
+    `  body: ## Contract (guarantees) / ## Phases (reproduce the ordered ` +
+    `instructions/steps the agent followed) / ## Output Format (the deliverable)\n` +
+    `DEDUP — do NOT propose a skill that overlaps any installed skill:\n${installedSkillsJson}\n` +
+    `Drop a candidate that is one-off, trivial, or has no clear trigger phrase.\n` +
+    `MISSIONS + WORKFLOWS (redacted; counts are facts):\n${candidatesJson}\n\n` +
+    `Return ONLY JSON: {"distilled":[{"name","description","triggers":[],"tools":[],` +
+    `"mutating":bool,"body","confidence":"high"|"medium"|"low"}]}.`;
+// Bound the prompt: send each candidate's verbs, recurrence, mission hint, and a
+// capped slice of its sampled steps.
+function trimCandidate(c) {
+    return {
+        verbs: c.verbs,
+        sessions: c.sessions,
+        missionHint: c.sample.missionHint ?? null,
+        steps: c.sample.steps.slice(0, 30).map((s) => ({ verb: s.verb, arg: s.arg })),
+    };
+}
+function installedSkillNames(inv) {
+    return [...inv.project.skills.map((s) => s.name), ...(inv.global?.skills ?? []).map((s) => s.name)];
+}
+function withTimeout(p, ms) {
+    return Promise.race([p, new Promise((_, rej) => setTimeout(() => rej(new Error(`distill agent timeout after ${ms}ms`)), ms))]);
+}
+/**
+ * Distil draft skills from a WorkflowSignal. Total: never throws. Short-circuits to
+ * an empty (non-degraded) result when no procedure clears Phase-0 — the agent is
+ * not even spawned. Any agent error/timeout/junk → { distilled: [], degraded: true }.
+ */
+export async function distillWorkflow(signal, inv, opts = {}) {
+    const candidates = distillCandidates(signal, opts);
+    if (!candidates.length)
+        return { distilled: [], degraded: false };
+    const connectFn = opts.connectFn ?? currentTestConnectFn() ?? defaultConnectFn;
+    const timeoutMs = opts.timeoutMs ?? 60_000;
+    let conn = null;
+    let handle = null;
+    try {
+        const prompt = DISTILL(JSON.stringify(candidates.map(trimCandidate)), JSON.stringify(installedSkillNames(inv)));
+        conn = await connectFn(CLAUDE_AGENT, null);
+        handle = await conn.ctx.open(analysisWorkspace()); // neutral cwd — don't pollute the project
+        await handle.setMode("plan"); // explicit — never edits files
+        const text = await withTimeout(handle.promptText(prompt), timeoutMs);
+        return { distilled: validateDistilled(text, inv, candidates), degraded: false };
+    }
+    catch (err) {
+        console.error("distill: fell back to empty:", err.message);
+        return { distilled: [], degraded: true };
+    }
+    finally {
+        try {
+            handle?.dispose();
+        }
+        catch { /* ignore */ }
+        try {
+            conn?.close();
+        }
+        catch { /* ignore */ }
+    }
+}

package/dist/gem/draftStage.js

@@ -0,0 +1,77 @@
+// src/gem/draftStage.ts
+//
+// Stage a distilled DRAFT skill so a Gem candidate can include it before it is
+// installed (proposal §7b). The seam is at inventory assembly, NOT buildGem:
+// buildGem resolves names against the in-memory ConfigInventory and throws on a
+// miss (buildGem.ts), so we materialize each draft into a SkillArtifact and merge
+// it into the inventory upstream. buildGem itself is unchanged.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { agentgemHome } from "../resolveDir.js";
+// Assemble the SKILL.md text: skillify-shaped frontmatter + the captured body.
+// This is also exactly what the draft-write handler persists to disk (§9).
+export function distilledSkillMarkdown(s) {
+    return [
+        "---",
+        `name: ${s.name}`,
+        `description: ${s.description}`,
+        "triggers:",
+        ...s.triggers.map((t) => `  - ${t}`),
+        `tools: [${s.tools.join(", ")}]`,
+        `mutating: ${s.mutating}`,
+        "---",
+        "",
+        s.body.trim(),
+        "",
+    ].join("\n");
+}
+export function distilledToArtifact(s) {
+    return { type: "skill", name: s.name, description: s.description, source: "distilled-draft", content: distilledSkillMarkdown(s) };
+}
+/**
+ * Stage every draft into the project named by its own `evidence.root` (drafts may
+ * span projects). Pure; no-op (same reference) when there are no drafts. Used by the
+ * build path so a candidate can include an accepted draft the server hasn't installed.
+ */
+export function stageDraftsByEvidence(inv, drafts) {
+    if (!drafts.length)
+        return inv;
+    const byRoot = new Map();
+    for (const d of drafts) {
+        const r = d.evidence.root;
+        const list = byRoot.get(r) ?? [];
+        list.push(d);
+        byRoot.set(r, list);
+    }
+    let out = inv;
+    for (const [root, list] of byRoot)
+        out = stageDistilledDrafts(out, list, root);
+    return out;
+}
+/**
+ * Persist an accepted draft to `<base>/.agentgem/distilled/<name>/SKILL.md` for the
+ * user to review and promote (proposal §7) — NOT into `.claude/skills/`. Returns the
+ * written path. `name` is a validated kebab slug (validateDistilled), so path-safe.
+ */
+export function writeDistilledDraft(s, base = agentgemHome()) {
+    const dir = join(base, ".agentgem", "distilled", s.name);
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, "SKILL.md");
+    writeFileSync(path, distilledSkillMarkdown(s), "utf8");
+    return path;
+}
+/**
+ * Return a copy of `inv` with each draft materialized into the project (matching
+ * `root`) skills, or top-level skills if no project matches. Pure — never mutates
+ * the input. A no-op (returns the same reference) when there are no drafts.
+ */
+export function stageDistilledDrafts(inv, drafts, root) {
+    if (!drafts.length)
+        return inv;
+    const arts = drafts.map(distilledToArtifact);
+    const matched = (inv.projects ?? []).some((p) => p.root === root);
+    const projects = (inv.projects ?? []).map((p) => p.root === root ? { ...p, skills: [...p.skills, ...arts] } : p);
+    return matched
+        ? { ...inv, projects }
+        : { ...inv, skills: [...inv.skills, ...arts], projects: inv.projects ? projects : undefined };
+}

package/dist/gem/gemVerify.js

@@ -0,0 +1,35 @@
+export function verifyGemRun(outcome, expectations = {}) {
+    // A run that never completed can't be reasoned about — fail fast, single check.
+    if (!outcome.ok) {
+        return { passed: false, checks: [{ name: "run completed", passed: false, detail: outcome.error ?? "run did not complete" }] };
+    }
+    const checks = [];
+    const { toolCalls, text } = outcome.result;
+    const titles = toolCalls.map((t) => t.title);
+    for (const want of expectations.expectTools ?? []) {
+        const hit = titles.some((title) => title.toLowerCase().includes(want.toLowerCase()));
+        checks.push({
+            name: `invoked tool ~ "${want}"`,
+            passed: hit,
+            detail: hit ? `matched ${JSON.stringify(titles.find((t) => t.toLowerCase().includes(want.toLowerCase())))}` : `no invoked tool matched (saw: ${titles.length ? titles.join(", ") : "none"})`,
+        });
+    }
+    if (expectations.expectText !== undefined) {
+        const pat = expectations.expectText;
+        const hit = typeof pat === "string" ? text.includes(pat) : pat.test(text);
+        checks.push({
+            name: "output text matches",
+            passed: hit,
+            detail: hit ? "matched" : `expected ${typeof pat === "string" ? JSON.stringify(pat) : String(pat)} in agent output`,
+        });
+    }
+    if (expectations.forbidToolFailures ?? true) {
+        const failed = toolCalls.filter((t) => t.status === "failed").map((t) => t.title);
+        checks.push({
+            name: "no tool failures",
+            passed: failed.length === 0,
+            detail: failed.length === 0 ? "all tools ok" : `failed tools: ${failed.join(", ")}`,
+        });
+    }
+    return { passed: checks.every((c) => c.passed), checks };
+}

package/dist/gem/inputError.js

@@ -0,0 +1,21 @@
+// src/gem/inputError.ts
+// A rejection of a caller-supplied value by an input-containment guard: an unsafe
+// workspace-name path segment, a non-public (SSRF) URL, a malformed credential.
+//
+// These are NOT server faults — the request was refused on purpose — so the caller
+// should learn WHY. @agentback/rest hides the message of any error whose status is
+// >= 500 ("Internal Server Error"), but surfaces e.message verbatim for a 4xx. By
+// carrying statusCode 400 (read by the framework's buildErrorEnvelope) this turns the
+// previously opaque 500 into a 400 whose message names the violated rule — matching
+// how the zod body/param validators already report bad input.
+export class InvalidInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.statusCode = 400;
+        this.code = "invalid_input";
+        // Override the framework's default invalid_input hint, which points at a per-field
+        // `issues`/`schema` payload these single-rule guards don't carry.
+        this.hint = "Correct the value to satisfy the rule stated in `message`, then retry.";
+        this.name = "InvalidInputError";
+    }
+}

package/dist/gem/registry.js

@@ -178,6 +178,21 @@ export async function mergeGems(graph, source) {
     };
     return { gem: merged, provenance };
 }
+// Derive the searchable discovery block for a publish: caller-supplied description/tags,
+// falling back to the first artifact's description; kinds/author derived from the gem.
+export function buildDiscovery(gem, scope, opts = {}) {
+    const description = opts.description ?? gem.artifacts.find((a) => "description" in a && a.description)?.["description"];
+    const tags = (opts.tags ?? []).map((t) => t.toLowerCase());
+    const artifactKinds = [...new Set(gem.artifacts.map((a) => a.type))];
+    const d = { author: scope, artifactKinds };
+    if (description)
+        d.description = description;
+    if (tags.length)
+        d.tags = tags;
+    if (opts.updatedAt)
+        d.updatedAt = opts.updatedAt;
+    return d;
+}
 export function updateIndex(index, e) {
     const items = { ...index.items };
     const existing = items[e.key];
@@ -187,8 +202,11 @@ export function updateIndex(index, e) {
         throw new Error(`${e.key}@${e.version} is immutable (published ${existingVersion.gemDigest}, attempted ${e.gemDigest})`);
     }
     versions[e.version] = { path: e.path, gemDigest: e.gemDigest, dependencies: e.dependencies };
-    const latest = existing && cmpSemver(existing.latest, e.version) >= 0 ? existing.latest : e.version;
-    items[e.key] = { latest, versions };
+    const isNewLatest = !existing || cmpSemver(existing.latest, e.version) < 0;
+    const latest = isNewLatest ? e.version : existing.latest;
+    // discovery reflects the latest version; keep the prior block when publishing an older version
+    const discovery = isNewLatest ? (e.discovery ?? existing?.discovery) : existing?.discovery;
+    items[e.key] = { latest, versions, ...(discovery ? { discovery } : {}) };
     return { formatVersion: REGISTRY_FORMAT_VERSION, items };
 }
 export async function publishGem(args) {
@@ -207,7 +225,8 @@ export async function publishGem(args) {
     if (prior && prior.gemDigest === gemDigest) {
         return { ref: key, version: args.version, gemDigest, commit: "", path };
     }
-    const nextIndex = updateIndex(args.index, { key, version: args.version, path, gemDigest, dependencies });
+    const discovery = buildDiscovery(args.gem, args.scope, { description: args.description, tags: args.tags, updatedAt: args.updatedAt });
+    const nextIndex = updateIndex(args.index, { key, version: args.version, path, gemDigest, dependencies, discovery });
     const commitFiles = { "registry.json": JSON.stringify(nextIndex, null, 2) };
     for (const [rel, content] of Object.entries(files))
         commitFiles[`${path}/${rel}`] = content;
@@ -227,7 +246,7 @@ export async function resolveInstall(args) {
     if (args.mode === "materialize") {
         if (!args.target)
             throw new Error("materialize mode requires a target harness id");
-        plan.materialize = materialize(gem, args.target);
+        plan.materialize = materialize(gem, args.target, { a2aServer: args.a2aServer });
     }
     return { plan, gem };
 }

package/dist/gem/runGem.js

@@ -0,0 +1,161 @@
+// src/gem/runGem.ts
+//
+// The end-to-end "run my Gem" path: materialize a portable Gem into a runnable
+// testbed dir, then drive a local ACP agent against it (optionally verifying).
+//
+// Why not targets.materialize(gem, "claude")? That renders the gem-archive layout
+// (skills under `skills/<n>/SKILL.md`), which is NOT where Claude Code discovers
+// skills at runtime. The runnable layout (`.claude/skills/<n>/SKILL.md`, etc.) is
+// produced by the testbed import writer — so we adapt the Gem's self-contained
+// artifacts into a ConfigInventory and reuse that tested writer.
+import { randomUUID } from "node:crypto";
+import { createRequire } from "node:module";
+import { spawn } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { agentgemHome } from "../resolveDir.js";
+import { binOnPath } from "./binPath.js";
+import { scaffoldTestbed, importArtifacts } from "./testbed.js";
+import { runGemWithAgent, hasTestConnectFn } from "./acpRun.js";
+import { verifyGemRun } from "./gemVerify.js";
+// ── Opaque run registry ──────────────────────────────────────────────────────
+// The streaming UI prepares a run (materialize) over POST, then streams it over a
+// GET. We hand the client an opaque runId — NOT the raw runDir — so a crafted GET
+// can't point the agent at an arbitrary path; the id maps server-side to the dir
+// (always under AGENTGEM_HOME) and the agent chosen at prepare time.
+const RUN_REGISTRY = new Map();
+export function registerRun(dir, agent) {
+    const id = randomUUID();
+    RUN_REGISTRY.set(id, { dir, agent });
+    return id;
+}
+export function resolveRun(id) {
+    return RUN_REGISTRY.get(id);
+}
+export const AGENT_ADAPTERS = {
+    claude: { id: "claude", name: "Claude Code", pkg: "@agentclientprotocol/claude-agent-acp", bin: "claude-agent-acp", version: "0.51.0", flavor: "claude", validated: true },
+    codex: { id: "codex", name: "Codex", pkg: "@agentclientprotocol/codex-acp", bin: "codex-acp", version: "1.0.0", flavor: "codex", validated: true },
+};
+const require = createRequire(import.meta.url);
+// Resolve a package's bin to `[node, <bin path>]` from a given module root (default:
+// agentgem's own deps). Returns null if the package isn't installed there.
+function resolveBinFrom(pkg, binName, fromDir) {
+    try {
+        const req = fromDir ? createRequire(join(fromDir, "noop.cjs")) : require;
+        const pkgJsonPath = req.resolve(`${pkg}/package.json`);
+        const pkgJson = req(pkgJsonPath);
+        const binRel = typeof pkgJson.bin === "string" ? pkgJson.bin : pkgJson.bin?.[binName];
+        if (binRel)
+            return [process.execPath, join(dirname(pkgJsonPath), binRel)];
+    }
+    catch { /* not resolvable here */ }
+    return null;
+}
+// Where on-demand-fetched adapters are cached (under AGENTGEM_HOME, never global).
+export function adapterCacheDir() { return join(agentgemHome(), "adapters"); }
+// Back-compat sync resolver (local dep → [node,path], else bare PATH name). The
+// async resolveOrFetchAdapter below is the full chain used at run time.
+export function resolveAdapterCommand(pkg, binName) {
+    return resolveBinFrom(pkg, binName) ?? [binName];
+}
+const npmInstaller = (pkg, version, prefixDir) => new Promise((resolve, reject) => {
+    mkdirSync(prefixDir, { recursive: true });
+    const child = spawn("npm", ["install", `${pkg}@${version}`, "--prefix", prefixDir, "--no-audit", "--no-fund", "--loglevel", "error"], { stdio: "inherit" });
+    child.once("error", reject);
+    child.once("exit", (code) => (code === 0 ? resolve() : reject(new Error(`npm install ${pkg}@${version} exited with code ${code}`))));
+});
+// Dedupe concurrent fetches of the same package (two runs racing the install).
+const inflightFetch = new Map();
+// Locate an adapter's spawnable command via a fallback chain, fetching on demand
+// only as a last resort. Order (reuse what exists, fetch last):
+//   1. global install on PATH        (the user explicitly installed the adapter)
+//   2. agentgem's own dep            (bundled/optional dependency)
+//   3. agentgem cache                (a prior on-demand fetch, under AGENTGEM_HOME)
+//   4. on-demand fetch into the cache (pinned version), then resolve
+export async function resolveOrFetchAdapter(adapter, opts = {}) {
+    if (binOnPath(adapter.bin))
+        return [adapter.bin];
+    const dep = resolveBinFrom(adapter.pkg, adapter.bin);
+    if (dep)
+        return dep;
+    const cache = adapterCacheDir();
+    const cached = resolveBinFrom(adapter.pkg, adapter.bin, cache);
+    if (cached)
+        return cached;
+    if (opts.allowFetch === false) {
+        throw new Error(`${adapter.name} adapter (${adapter.pkg}) is not installed and on-demand fetch is disabled`);
+    }
+    let fetching = inflightFetch.get(adapter.pkg);
+    if (!fetching) {
+        const installer = opts.installer ?? npmInstaller;
+        fetching = (async () => {
+            opts.onFetch?.();
+            await installer(adapter.pkg, adapter.version, cache);
+            const resolved = resolveBinFrom(adapter.pkg, adapter.bin, cache);
+            if (!resolved)
+                throw new Error(`fetched ${adapter.pkg} but its '${adapter.bin}' bin was not found`);
+            return resolved;
+        })();
+        inflightFetch.set(adapter.pkg, fetching);
+        void fetching.catch(() => { }).finally(() => inflightFetch.delete(adapter.pkg));
+    }
+    return fetching;
+}
+// Partition a Gem's flat artifact list into the inventory shape importArtifacts wants.
+// A Gem is self-contained (each artifact carries its content), so no disk read needed.
+export function gemToInventory(gem) {
+    const inv = { skills: [], mcpServers: [], instructions: [], hooks: [] };
+    for (const a of gem.artifacts) {
+        if (a.type === "skill")
+            inv.skills.push(a);
+        else if (a.type === "mcp_server")
+            inv.mcpServers.push(a);
+        else if (a.type === "instructions")
+            inv.instructions.push(a);
+        else if (a.type === "hook")
+            inv.hooks.push(a);
+    }
+    return inv;
+}
+/**
+ * Scaffold a runnable testbed at `dir` and write every artifact the Gem carries
+ * into the flavor's discoverable locations (`.claude/skills/...`, CLAUDE.md, etc.).
+ */
+export function materializeGemToTestbed(gem, dir, flavor = "claude") {
+    scaffoldTestbed(dir, gem.name, flavor);
+    const inv = gemToInventory(gem);
+    const selection = {
+        skills: inv.skills.map((s) => s.name),
+        mcpServers: inv.mcpServers.map((s) => s.name),
+        hooks: inv.hooks.map((h) => h.name),
+        includeInstructions: inv.instructions.length > 0,
+    };
+    return importArtifacts(dir, selection, inv, flavor);
+}
+/**
+ * Gem → dir → run → (verify). The one call that turns a portable Gem into an
+ * observed agent run. Verification is attached only when `expectations` are given.
+ */
+export async function materializeAndRunGem(opts) {
+    const agent = opts.agent ?? "claude";
+    const adapter = AGENT_ADAPTERS[agent];
+    const flavor = opts.flavor ?? adapter.flavor;
+    const materialized = materializeGemToTestbed(opts.gem, opts.dir, flavor);
+    // Resolve (and if needed fetch) the adapter command, unless a connectFn is
+    // injected — fakes never spawn, so don't trigger resolution/fetch in tests.
+    const command = opts.connectFn || hasTestConnectFn()
+        ? [adapter.bin]
+        : await resolveOrFetchAdapter(adapter, { installer: opts.installer, onFetch: opts.onFetch, allowFetch: opts.allowFetch });
+    const run = await runGemWithAgent({
+        dir: opts.dir,
+        task: opts.task,
+        mode: opts.mode,
+        descriptor: { id: adapter.id, name: adapter.name, command },
+        connectFn: opts.connectFn,
+        timeoutMs: opts.timeoutMs,
+        onDelta: opts.onDelta,
+        onToolCall: opts.onToolCall,
+    });
+    const verification = opts.expectations ? verifyGemRun(run, opts.expectations) : undefined;
+    return { agent, materialized, run, verification };
+}

package/dist/gem/safeFetch.js

@@ -0,0 +1,112 @@
+// src/gem/safeFetch.ts
+// SSRF guard for installing a .gem from a URL. A localhost-bound dev server is still
+// reachable by a malicious page via CSRF, so an unguarded server-side fetch lets an
+// attacker reach cloud metadata (169.254.169.254) or internal hosts. We resolve the
+// host and refuse any non-public address, re-validate every redirect hop, AND pin the
+// socket to the validated IP via an undici dispatcher so a DNS rebind between the
+// validation and the connect cannot swing the request onto a blocked address.
+import { lookup } from "node:dns/promises";
+import { Agent } from "undici";
+import { InvalidInputError } from "./inputError.js";
+// True for loopback, RFC1918, CGNAT, link-local/metadata, and IPv6 loopback/link-local/ULA.
+export function isBlockedAddress(ip) {
+    const v4 = ip.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+    if (v4) {
+        const a = Number(v4[1]), b = Number(v4[2]);
+        if (a === 0 || a === 127)
+            return true; // 0.0.0.0/8, loopback
+        if (a === 10)
+            return true; // RFC1918
+        if (a === 172 && b >= 16 && b <= 31)
+            return true; // RFC1918
+        if (a === 192 && b === 168)
+            return true; // RFC1918
+        if (a === 169 && b === 254)
+            return true; // link-local + cloud metadata
+        if (a === 100 && b >= 64 && b <= 127)
+            return true; // CGNAT 100.64/10
+        return false;
+    }
+    const v6 = ip.toLowerCase().replace(/^\[/, "").replace(/\]$/, "");
+    if (v6 === "::1" || v6 === "::")
+        return true; // loopback / unspecified
+    if (v6.startsWith("fe80"))
+        return true; // link-local
+    if (v6.startsWith("fc") || v6.startsWith("fd"))
+        return true; // unique-local fc00::/7
+    const mapped = v6.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/); // IPv4-mapped
+    if (mapped)
+        return isBlockedAddress(mapped[1]);
+    return false;
+}
+// Parse + scheme-check + DNS-resolve a URL, rejecting any non-public address.
+// Returns the URL plus the validated addresses (null when allowPrivate skips resolution).
+async function validatePublic(raw, opts) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new InvalidInputError(`invalid gem URL: ${raw}`);
+    }
+    if (u.protocol !== "http:" && u.protocol !== "https:") {
+        throw new InvalidInputError(`gem URL must be http(s), got ${u.protocol}`);
+    }
+    if (opts.allowPrivate)
+        return { url: u, validated: null };
+    const host = u.hostname.replace(/^\[/, "").replace(/\]$/, "");
+    const results = await lookup(host, { all: true });
+    if (results.length === 0)
+        throw new InvalidInputError(`could not resolve gem URL host: ${host}`);
+    for (const r of results) {
+        if (isBlockedAddress(r.address))
+            throw new InvalidInputError(`refusing to fetch gem from non-public address ${r.address} (${host})`);
+    }
+    return { url: u, validated: results };
+}
+export async function assertPublicUrl(raw, opts = {}) {
+    return (await validatePublic(raw, opts)).url;
+}
+// A Node lookup function pinned to the validated addresses — it ignores the hostname it is
+// asked to resolve, so a host that rebinds to a blocked IP after validation cannot redirect
+// the socket. This is the piece that actually closes the validate→connect race.
+export function makePinnedLookup(validated) {
+    return (_hostname, options, callback) => {
+        const cb = (typeof options === "function" ? options : callback);
+        const all = typeof options === "object" && options.all;
+        if (all)
+            cb(null, validated);
+        else
+            cb(null, validated[0].address, validated[0].family);
+    };
+}
+// Fetch a .gem over http(s): validate the URL + every redirect hop, and pin each connection
+// to the validated IP set via an undici dispatcher. Size-capped.
+export async function fetchGemBytes(raw, opts = {}) {
+    const maxRedirects = opts.maxRedirects ?? 3;
+    const maxBytes = opts.maxBytes ?? 50 * 1024 * 1024;
+    let target = raw;
+    for (let hop = 0;; hop++) {
+        const { url, validated } = await validatePublic(target, opts);
+        const dispatcher = validated ? new Agent({ connect: { lookup: makePinnedLookup(validated) } }) : undefined;
+        try {
+            const res = await fetch(url.toString(), { redirect: "manual", ...(dispatcher ? { dispatcher } : {}) });
+            const loc = res.headers.get("location");
+            if (res.status >= 300 && res.status < 400 && loc) {
+                if (hop >= maxRedirects)
+                    throw new Error("too many redirects fetching gem");
+                target = new URL(loc, url).toString();
+                continue;
+            }
+            if (!res.ok)
+                throw new Error(`gem fetch failed: HTTP ${res.status}`);
+            const buf = Buffer.from(await res.arrayBuffer());
+            if (buf.length > maxBytes)
+                throw new Error(`gem exceeds max size (${buf.length} > ${maxBytes} bytes)`);
+            return buf;
+        }
+        finally {
+            await dispatcher?.close();
+        }
+    }
+}

package/dist/gem/sandbox.js

@@ -0,0 +1,37 @@
+// src/gem/sandbox.ts
+// Pluggable sandbox-backend registry in front of the RunConnectFn seam. Each backend
+// produces a RunConnectFn pre-scoped to a run dir. Auto-allow is capability-gated:
+// isolated backends run permission:"allow" (the FS boundary bounds blast radius);
+// the child-spawn fallback stays deny unless AGENTGEM_GEM_RUN_AUTOALLOW=1.
+import { connectRunSession } from "./acpRun.js"; // value used at call-time (safe ESM cycle)
+import { wrapWithSandbox } from "./sandboxLaunch.js";
+import { binOnPath } from "./binPath.js";
+export function envPermission(env = process.env) {
+    return env.AGENTGEM_GEM_RUN_AUTOALLOW === "1" ? "allow" : "deny";
+}
+// An isolated backend: wrap the agent command with the OS sandbox launcher (so the
+// agent AND its child shells inherit the jail) and auto-allow tool calls. `bin` is the
+// launcher resolved on PATH (not a hard-coded absolute path — distros place bwrap in
+// /usr/bin or /usr/local/bin), matching the bare name `wrapWithSandbox` actually spawns.
+function isolatedBackend(id, kind, bin, supported) {
+    return {
+        id, isolated: true,
+        available: () => supported() && binOnPath(bin),
+        connectFn: (runDir) => (descriptor, app) => connectRunSession({ ...descriptor, command: wrapWithSandbox(kind, runDir, descriptor.command) }, "allow", app),
+    };
+}
+export const childSpawnBackend = {
+    id: "child-spawn",
+    isolated: false,
+    available: () => true,
+    connectFn: () => (descriptor, app) => connectRunSession(descriptor, envPermission(), app),
+};
+export const RUN_BACKENDS = [
+    isolatedBackend("macos-seatbelt", "macos-seatbelt", "sandbox-exec", () => process.platform === "darwin"),
+    isolatedBackend("linux-bubblewrap", "linux-bubblewrap", "bwrap", () => process.platform === "linux"),
+    childSpawnBackend,
+];
+export function selectRunBackend(runDir, registry = RUN_BACKENDS) {
+    const backend = registry.find((b) => b.isolated && b.available()) ?? registry[registry.length - 1] ?? childSpawnBackend;
+    return { backend, connectFn: backend.connectFn(runDir) };
+}