@ninemind/agentgem 0.1.1 → 0.3.0

package/README.md

@@ -37,9 +37,18 @@ call exactly the same thing.
   re-reading raw config.
 - **Composition** — the manifest/lock split lets small, focused Gems be reconciled into
   larger agents with a single re-resolved lock, not a pile of overlapping config.
+- **Workflow-aware recommendations** — [Analyze](docs/analyze.md) scans your agent's
+  session history to see which skills, MCP servers, and hooks you actually use, and
+  suggests ready-to-build Gems grouped by recurring workflow. It also **distills brand-new
+  draft skills** from the procedures you repeat by hand — review them and fold them
+  straight into a Gem.
 - **Deploy targets** — Eve and OpenAI Sandbox (code-gen), Flue (materialize, deployable to
   Cloudflare), and Bedrock AgentCore (managed backend); code-gen targets share a common
   `compose` step.
+- **Agent-to-agent (A2A)** — export a Gem as an [A2A](docs/a2a.md) Agent Card or a
+  runnable A2A server so other agents can discover and call it.
+- **A native desktop app** — a [macOS/Windows/Linux build](docs/desktop.md) alongside the
+  `npx` CLI, hosting the same local server in its own window.
 - **A GitHub-backed registry** — publish, resolve, merge, and install composable Gems over
   the same archive format.
 - **An agent-native path** — every operation is also an MCP tool, so your local agent can
@@ -106,6 +115,20 @@ pnpm clean       # or: npm run clean — rm -rf dist *.tsbuildinfo (run before r
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.
 
+### Desktop app
+
+Prefer a double-click app over the CLI? AgentGem ships a native **desktop build**
+for macOS, Windows, and Linux — download it from
+[Releases](https://github.com/ninemindai/agentgem/releases) (a `desktop-v*` build).
+It hosts the same local server in its own window, adds a native folder picker, app
+menu, and system tray, and never sends secrets off your machine.
+
+> The builds are currently **unsigned**: on macOS right-click → **Open**, on Windows
+> choose **More info → Run anyway** the first time.
+
+To run or package it from source, see the [desktop guide](docs/desktop.md) — in
+short, `pnpm -C desktop dev` to run, `pnpm -C desktop dist` to build installers.
+
 ## Layering
 
 Depends on AgentBack: `@agentback/core` (lifecycle), `@agentback/rest` +
@@ -116,8 +139,11 @@ API, and the MCP endpoint are three boundaries over one set of Zod contracts —
 
 For deeper reference, see [`docs/`](docs/index.md):
 [getting started](docs/getting-started.md) ·
+[desktop app](docs/desktop.md) ·
+[analyze](docs/analyze.md) ·
 [concepts](docs/concepts.md) ·
 [targets & deploy](docs/targets.md) ·
+[A2A](docs/a2a.md) ·
 [registry](docs/registry.md).
 
 ## License

package/dist/gem/acpRecommender.js

@@ -0,0 +1,259 @@
+// src/gem/acpRecommender.ts
+//
+// Turns a deterministic WorkflowSignal + inventory into a GemRecommendation by
+// grounding a local ACP coding agent (Claude) with the signal and asking it to
+// cluster/name/justify a Gem. The agent only ranks and explains — its output is
+// re-validated against the inventory (the source of truth), and any failure
+// degrades to a deterministic frequency-based recommendation. Never throws.
+import { join } from "node:path";
+import { agentgemHome } from "../resolveDir.js";
+import { connectAcpAdapter } from "./acpSession.js";
+// Instructions are a boolean on ProjectSelection, not a named include.
+const SELECTABLE = ["skill", "mcp_server", "hook"];
+// Pinned Claude ACP adapter (npm: @agentclientprotocol/claude-agent-acp).
+export const CLAUDE_AGENT = { id: "claude-code", name: "Claude Code", command: ["claude-agent-acp"] };
+// Neutral working dir for the recommender's ACP session. We do NOT open the
+// session in the analyzed project, or claude-agent-acp would log a session
+// transcript THERE — inflating that project's own session history (skewing
+// future analyses and busting the per-project cache). The agent only reasons
+// over the JSON brief, so its cwd is irrelevant to the result.
+export function analysisWorkspace() { return join(agentgemHome(), ".agentgem", "analysis"); }
+let testConnectFn = null;
+/** Test-only seam: route recommendWorkflow + distillWorkflow through an in-process fake agent. */
+export function setConnectFnForTests(fn) { testConnectFn = fn; }
+/** The active test connect fn (or null). distillWorkflow shares this seam. */
+export function currentTestConnectFn() { return testConnectFn; }
+// ── Deterministic analysis (fallback + the agent's baseline) ─────────────────
+// One frequency-based candidate. Multi-candidate splitting is the agent's value-add;
+// the deterministic fallback stays a single coherent Gem.
+export function deterministicAnalysis(signal) {
+    const include = [];
+    let includeInstructions = false;
+    for (const a of signal.artifacts) {
+        if (a.type === "instructions") {
+            if (a.invocations > 0)
+                includeInstructions = true;
+            continue;
+        }
+        if (!SELECTABLE.includes(a.type))
+            continue;
+        if (a.invocations > 0 && a.confidence === "high")
+            include.push({ type: a.type, name: a.name, reason: `${a.invocations} use(s) across ${a.sessionsUsedIn} session(s)`, root: a.root });
+    }
+    const gaps = signal.unresolved.filter((u) => u.kind !== "builtin").map((u) => u.name);
+    const candidates = include.length ? [{
+            name: signal.root.split("/").pop() || "workflow",
+            description: `Recommended from ${signal.sessions.scanned} session(s) of usage.`,
+            root: signal.root,
+            includeInstructions,
+            include,
+            confidence: "medium",
+        }] : [];
+    return { candidates, gaps, distilled: [] };
+}
+/**
+ * Map a validated candidate to a GemSelection. Global artifacts (root===null)
+ * go top-level; project artifacts go under projects[root]; instructions are a
+ * project boolean. buildGem resolves both namespaces from introspectAll.
+ */
+export function recommendationToSelection(c) {
+    const sel = {};
+    const globalNames = (t) => c.include.filter((i) => i.type === t && i.root === null).map((i) => i.name);
+    const gSkills = globalNames("skill"), gMcp = globalNames("mcp_server"), gHooks = globalNames("hook");
+    if (gSkills.length)
+        sel.skills = gSkills;
+    if (gMcp.length)
+        sel.mcpServers = gMcp;
+    if (gHooks.length)
+        sel.hooks = gHooks;
+    const projects = {};
+    const ensure = (root) => (projects[root] ??= {});
+    for (const i of c.include) {
+        if (i.root === null)
+            continue;
+        const ps = ensure(i.root);
+        if (i.type === "skill")
+            (ps.skills ??= []).push(i.name);
+        else if (i.type === "mcp_server")
+            (ps.mcpServers ??= []).push(i.name);
+        else if (i.type === "hook")
+            (ps.hooks ??= []).push(i.name);
+    }
+    if (c.includeInstructions)
+        ensure(c.root).includeInstructions = true;
+    if (Object.keys(projects).length)
+        sel.projects = projects;
+    return sel;
+}
+// Pull the first {...} block out of an agent message that may wrap JSON in prose/fences.
+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 against the inventory. Each candidate's include
+ * names are checked against the inventory; hallucinated names are dropped
+ * (logged) and a candidate with no surviving includes is discarded. On any
+ * structural failure or zero valid candidates, fall back to the deterministic
+ * analysis. The inventory is authoritative.
+ */
+export function validateAnalysis(raw, inv, signal) {
+    const fallback = deterministicAnalysis(signal);
+    let obj = raw;
+    if (typeof raw === "string") {
+        try {
+            obj = JSON.parse(extractJson(raw));
+        }
+        catch {
+            return fallback;
+        }
+    }
+    if (!obj || typeof obj !== "object" || !Array.isArray(obj.candidates))
+        return fallback;
+    const g = inv.global ?? { skills: [], mcpServers: [], hooks: [] };
+    // Resolve a name to its namespace: project root if present there, else global
+    // (null), else undefined (hallucinated). Project is preferred on collision.
+    const proj = {
+        skill: new Set(inv.project.skills.map((s) => s.name)),
+        mcp_server: new Set(inv.project.mcpServers.map((m) => m.name)),
+        hook: new Set(inv.project.hooks.map((h) => h.name)),
+    };
+    const glob = {
+        skill: new Set(g.skills.map((s) => s.name)),
+        mcp_server: new Set(g.mcpServers.map((m) => m.name)),
+        hook: new Set(g.hooks.map((h) => h.name)),
+    };
+    const resolveRoot = (type, name) => proj[type]?.has(name) ? inv.project.root : glob[type]?.has(name) ? null : undefined;
+    const candidates = [];
+    for (const c of obj.candidates) {
+        if (!c || typeof c !== "object" || !Array.isArray(c.include))
+            continue;
+        const include = [];
+        for (const it of c.include) {
+            if (!it || !SELECTABLE.includes(it.type) || typeof it.name !== "string")
+                continue;
+            const root = resolveRoot(it.type, it.name);
+            if (root === undefined) {
+                console.error(`workflow: dropping hallucinated ${it.type} '${it.name}'`);
+                continue;
+            }
+            include.push({ type: it.type, name: it.name, reason: typeof it.reason === "string" ? it.reason : "", root });
+        }
+        if (!include.length)
+            continue;
+        candidates.push({
+            name: typeof c.name === "string" ? c.name : (signal.root.split("/").pop() || "workflow"),
+            description: typeof c.description === "string" ? c.description : "",
+            root: signal.root,
+            includeInstructions: c.includeInstructions === true,
+            include,
+            confidence: ["high", "medium", "low"].includes(c.confidence) ? c.confidence : "medium",
+        });
+    }
+    if (!candidates.length)
+        return fallback;
+    const gaps = Array.isArray(obj.gaps) ? obj.gaps.filter((g) => typeof g === "string") : fallback.gaps;
+    return { candidates, gaps, distilled: [] };
+}
+// ── The agent run ────────────────────────────────────────────────────────────
+const GROUNDING = (signalJson, inventoryJson) => `You recommend reusable "Gems" — bundles of installed artifacts for a recurring workflow.\n` +
+    `A project often exercises SEVERAL distinct flows (e.g. diagram generation vs web scraping). ` +
+    `Use the per-session "shapes" (sets of artifacts used together) plus co-occurrence to identify each ` +
+    `recurring flow, and propose ONE Gem per flow.\n` +
+    `The inventory has PROJECT artifacts (scoped to this repo) and GLOBAL artifacts (from the machine / ` +
+    `installed plugins). Include either by exact name — both get bundled into the Gem.\n` +
+    `USAGE SIGNAL (authoritative — invocation counts and shapes are facts):\n${signalJson}\n\n` +
+    `INVENTORY (the only artifacts that exist — never invent names outside this):\n${inventoryJson}\n\n` +
+    `Return ONLY a JSON object: {"candidates":[{"name","description","includeInstructions":bool,` +
+    `"include":[{"type":"skill"|"mcp_server"|"hook","name","reason"}],"confidence":"high"|"medium"|"low"}],"gaps":[string]}.\n` +
+    `Each candidate is one coherent flow. Prefer 1–4 candidates; don't split trivially or duplicate. Use exact inventory names.`;
+// Skill bodies are large; send descriptions only. Global section is limited to
+// artifacts that actually fired (the global catalog can be huge) — `usedGlobal`.
+function trimInventory(inv, usedGlobal) {
+    const p = inv.project;
+    const g = inv.global ?? { skills: [], mcpServers: [], hooks: [] };
+    return {
+        projectRoot: p.root, name: p.name,
+        project: {
+            skills: p.skills.map((s) => ({ name: s.name, description: s.description ?? "" })),
+            mcpServers: p.mcpServers.map((m) => ({ name: m.name, transport: m.transport })),
+            instructions: p.instructions.map((i) => ({ name: i.name })),
+            hooks: p.hooks.map((h) => ({ name: h.name, event: h.event, matcher: h.matcher ?? null })),
+        },
+        global: {
+            skills: g.skills.filter((s) => usedGlobal.has(s.name)).map((s) => ({ name: s.name })),
+            mcpServers: g.mcpServers.filter((m) => usedGlobal.has(m.name)).map((m) => ({ name: m.name })),
+            hooks: g.hooks.filter((h) => usedGlobal.has(h.name)).map((h) => ({ name: h.name, event: h.event })),
+        },
+    };
+}
+function withTimeout(p, ms) {
+    return Promise.race([p, new Promise((_, rej) => setTimeout(() => rej(new Error(`agent timeout after ${ms}ms`)), ms))]);
+}
+/**
+ * Analyse `signal`/`inventory` into candidate Gems. Total: never throws. On any
+ * agent error/timeout/junk, returns the deterministic analysis with degraded:true.
+ */
+export async function recommendWorkflow(signal, inv, opts = {}) {
+    const connectFn = opts.connectFn ?? testConnectFn ?? defaultConnectFn;
+    const timeoutMs = opts.timeoutMs ?? 60_000;
+    let conn = null;
+    let handle = null;
+    try {
+        const usedGlobal = new Set(signal.artifacts.filter((a) => a.root === null && a.invocations > 0).map((a) => a.name));
+        const trimmedInv = trimInventory(inv, usedGlobal);
+        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 prompt = GROUNDING(JSON.stringify(signal), JSON.stringify(trimmedInv));
+        const text = await withTimeout(handle.promptText(prompt, opts.onDelta), timeoutMs);
+        return { analysis: validateAnalysis(text, inv, signal), degraded: false };
+    }
+    catch (err) {
+        console.error("workflow: recommender fell back to deterministic:", err.message);
+        return { analysis: deterministicAnalysis(signal), degraded: true };
+    }
+    finally {
+        try {
+            handle?.dispose();
+        }
+        catch { /* ignore */ }
+        try {
+            conn?.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * Real connect: route through the shared adapter plumbing in plan mode with
+ * permissions auto-denied (the recommender must never run tools), aggregating
+ * only the agent's message text into a string.
+ */
+export const defaultConnectFn = async (descriptor) => {
+    const raw = await connectAcpAdapter(descriptor, { clientName: "agentgem-workflow-recommender", permission: "deny" });
+    const ctx = {
+        async open(cwd) {
+            const session = await raw.open(cwd);
+            return {
+                setMode: (mode) => session.setMode(mode),
+                async promptText(text, onDelta) {
+                    let out = "";
+                    await session.prompt(text, (u) => {
+                        const update = u;
+                        if (update?.sessionUpdate === "agent_message_chunk") {
+                            const block = update.content;
+                            if (block?.type === "text" && typeof block.text === "string") {
+                                out += block.text;
+                                onDelta?.(block.text);
+                            }
+                        }
+                    });
+                    return out;
+                },
+                dispose: () => session.dispose(),
+            };
+        },
+    };
+    return { ctx, close: raw.close };
+};

package/dist/gem/acpRun.js

@@ -0,0 +1,156 @@
+// src/gem/acpRun.ts
+//
+// Runs a materialized Gem by driving a locally-installed ACP coding agent (Claude)
+// against a task, and captures what the agent DID — its message text plus the
+// trace of tool invocations. This is the trust-inversion of acpRecommender:
+//   recommender                     runner (here)
+//   ───────────                     ─────────────
+//   neutral analysisWorkspace()  →  the materialized testbed dir
+//   mode "plan" (never edits)    →  a tool-capable mode (agent uses the Gem)
+//   captures agent_message_chunk →  also captures tool_call updates
+//
+// As with the recommender, the SDK details live behind a single connectFn seam so
+// tests inject a plain fake. Unlike the recommender there is no deterministic
+// fallback — a failed run is a real outcome the caller (e.g. verification) needs,
+// so we never throw: failures surface as { ok:false, error }.
+//
+// NOTE (consolidation): the ACP façade is duplicated from acpRecommender on purpose
+// while this path is prototyped. Once both are proven, the two connectFns should be
+// unified into a shared acpSession module.
+import { connectAcpAdapter } from "./acpSession.js";
+import { selectRunBackend, envPermission } from "./sandbox.js"; // values used at call-time (safe ESM cycle)
+export function createAccumulator() {
+    return { text: "", toolCalls: [] };
+}
+export function applyUpdate(acc, update, handlers) {
+    switch (update.sessionUpdate) {
+        case "agent_message_chunk": {
+            const block = update.content;
+            if (block?.type === "text" && typeof block.text === "string") {
+                acc.text += block.text;
+                handlers?.onDelta?.(block.text);
+            }
+            return;
+        }
+        case "tool_call": {
+            if (!update.toolCallId)
+                return;
+            const tool = {
+                toolCallId: update.toolCallId,
+                title: update.title ?? "",
+                kind: update.kind,
+                status: update.status,
+            };
+            acc.toolCalls.push(tool);
+            handlers?.onToolCall?.(tool); // fires once, on start — final status lands in the result
+            return;
+        }
+        case "tool_call_update": {
+            const existing = acc.toolCalls.find((t) => t.toolCallId === update.toolCallId);
+            if (!existing)
+                return; // update for a tool we never saw start — ignore
+            if (update.status !== undefined)
+                existing.status = update.status;
+            if (update.kind !== undefined)
+                existing.kind = update.kind;
+            if (update.title !== undefined && update.title !== "")
+                existing.title = update.title;
+            return;
+        }
+        default:
+            return;
+    }
+}
+// Pinned Claude ACP adapter, same binary the recommender spawns.
+export const CLAUDE_RUN_AGENT = { id: "claude-code", name: "Claude Code", command: ["claude-agent-acp"] };
+// The default non-plan mode: lets the agent actually invoke the Gem's tools. The
+// recommender pins "plan"; the runner pins its counterpart so the trust-inversion
+// is explicit rather than incidental.
+export const DEFAULT_RUN_MODE = "default";
+// Default prompt timeout. Generous — a real Gem run can drive the agent through
+// several tool calls — but bounded so a wedged agent can't hang the caller.
+export const DEFAULT_RUN_TIMEOUT_MS = 300_000;
+function withTimeout(p, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`agent run timed out after ${ms}ms`)), ms);
+        p.then((v) => { clearTimeout(timer); resolve(v); }, (e) => { clearTimeout(timer); reject(e); });
+    });
+}
+// Test seam: route runGemWithAgent through an in-process fake agent (mirrors
+// acpRecommender.setConnectFnForTests). Lets the REST/SSE surface be exercised
+// without spawning a real coding agent.
+let testConnectFn = null;
+export function setRunConnectFnForTests(fn) { testConnectFn = fn; }
+/** True when a fake agent is injected — callers skip adapter resolution/fetch. */
+export function hasTestConnectFn() { return testConnectFn !== null; }
+/**
+ * Drive a local ACP agent against `task` inside the already-materialized `dir`,
+ * returning what it did. Never throws — connection/spawn failures come back as
+ * { ok:false, error }.
+ */
+export async function runGemWithAgent(opts) {
+    const explicit = opts.connectFn ?? testConnectFn;
+    const selected = explicit ? null : selectRunBackend(opts.dir);
+    const connectFn = explicit ?? selected.connectFn;
+    const sandbox = selected
+        ? { backend: selected.backend.id, isolated: selected.backend.isolated }
+        : { backend: "injected", isolated: false };
+    const mode = opts.mode ?? DEFAULT_RUN_MODE;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_RUN_TIMEOUT_MS;
+    let conn = null;
+    let handle = null;
+    try {
+        conn = await connectFn(opts.descriptor ?? CLAUDE_RUN_AGENT, null);
+        handle = await conn.ctx.open(opts.dir); // the testbed dir — NOT a neutral one
+        await handle.setMode(mode); // tool-capable — the agent uses the Gem
+        const result = await withTimeout(handle.prompt(opts.task, opts.onDelta, opts.onToolCall), timeoutMs);
+        return { ok: true, result, sandbox };
+    }
+    catch (err) {
+        return { ok: false, result: { text: "", toolCalls: [] }, error: err.message, sandbox };
+    }
+    finally {
+        try {
+            handle?.dispose();
+        }
+        catch { /* ignore */ }
+        try {
+            conn?.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * The shared run-session façade: connect the ACP adapter with an explicit permission
+ * policy and fold each update into a RunResult via applyUpdate, capturing the tool
+ * trace. Backends in sandbox.ts call this with a wrapped descriptor (isolated => "allow")
+ * or the raw descriptor (child-spawn => env policy).
+ *
+ * SECURITY: On the isolated path (macos-seatbelt / linux-bubblewrap), auto-allow is
+ * safe by default — the OS-native FS boundary bounds the blast radius to the run dir
+ * and temp. On the child-spawn fallback, permission is "deny" unless
+ * AGENTGEM_GEM_RUN_AUTOALLOW=1 is set (env escape hatch, retained for trusted local
+ * sessions). Combined with the loopback origin guard and the server-derived run dir,
+ * this keeps a malicious browser tab from driving a fully-permissioned local agent.
+ */
+export async function connectRunSession(descriptor, permission, _app) {
+    const raw = await connectAcpAdapter(descriptor, { clientName: "agentgem-gem-runner", permission });
+    const ctx = {
+        async open(cwd) {
+            const session = await raw.open(cwd);
+            return {
+                setMode: (mode) => session.setMode(mode),
+                async prompt(text, onDelta, onToolCall) {
+                    const acc = createAccumulator();
+                    await session.prompt(text, (u) => applyUpdate(acc, (u ?? {}), { onDelta, onToolCall }));
+                    return acc;
+                },
+                dispose: () => session.dispose(),
+            };
+        },
+    };
+    return { ctx, close: raw.close };
+}
+// Back-compat: the unsandboxed child-spawn connect, env-gated via the single source of
+// truth for the auto-allow flag (shared with sandbox.ts's child-spawn backend).
+export const defaultRunConnectFn = (descriptor, app) => connectRunSession(descriptor, envPermission(), app);

package/dist/gem/acpSession.js

@@ -0,0 +1,79 @@
+// src/gem/acpSession.ts
+//
+// The shared ACP adapter plumbing used by BOTH the workflow recommender and the
+// Gem runner: spawn the adapter binary, bridge stdio via the SDK, build a session,
+// set its mode, and pump session updates until the turn stops. The two callers
+// differ only in permission policy (deny vs allow) and how they fold updates
+// (text-only string vs structured RunResult), so those stay in the callers — this
+// module owns the boilerplate that was previously copy-pasted between them.
+//
+// NEEDS LIVE VALIDATION: stdio bridging against the real ACP adapter (covered by
+// the runner + recommender live smokes, since both now route through here).
+import { spawn } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { Readable, Writable } from "node:stream";
+export async function connectAcpAdapter(descriptor, opts) {
+    const { client, ndJsonStream, PROTOCOL_VERSION } = await import("@agentclientprotocol/sdk");
+    const [bin, ...args] = descriptor.command;
+    const child = spawn(bin, args, { stdio: ["pipe", "pipe", "inherit"], env: process.env });
+    await new Promise((resolve, reject) => {
+        child.once("spawn", () => resolve());
+        child.once("error", (e) => reject(new Error(`failed to spawn ${bin}: ${e.message}`)));
+    });
+    const app = client({ name: opts.clientName });
+    const reply = opts.permission === "allow"
+        ? { outcome: { outcome: "selected", optionId: "allow" } }
+        : { outcome: { outcome: "cancelled" } };
+    app.onRequest?.("session/request_permission", async () => reply);
+    const input = Readable.toWeb(child.stdout);
+    const output = Writable.toWeb(child.stdin);
+    const connection = app.connect(ndJsonStream(output, input));
+    const agentCtx = connection.agent;
+    // ACP requires an `initialize` handshake before any session/new. claude-agent-acp
+    // tolerated skipping it; codex-acp strictly rejects session/new with "Not
+    // initialized" (-32603) without it. We advertise no client capabilities we don't
+    // implement (no fs/terminal handlers) — both adapters write files directly.
+    await agentCtx.request("initialize", { protocolVersion: PROTOCOL_VERSION });
+    return {
+        async open(cwd) {
+            try {
+                mkdirSync(cwd, { recursive: true });
+            }
+            catch { /* best-effort */ }
+            const session = await agentCtx.buildSession(cwd).start();
+            const sessionId = session.sessionId;
+            return {
+                async setMode(mode) {
+                    try {
+                        await agentCtx.request("session/set_mode", { sessionId, modeId: mode });
+                    }
+                    catch { /* best-effort */ }
+                },
+                async prompt(text, onUpdate) {
+                    void session.prompt(text);
+                    for (;;) {
+                        const msg = await session.nextUpdate();
+                        if (msg.kind === "stop")
+                            break;
+                        if (msg.kind === "session_update")
+                            onUpdate(msg.update);
+                    }
+                },
+                dispose() { try {
+                    session.dispose?.();
+                }
+                catch { /* ignore */ } },
+            };
+        },
+        close: () => {
+            try {
+                connection.close();
+            }
+            catch { /* ignore */ }
+            try {
+                child.kill();
+            }
+            catch { /* ignore */ }
+        },
+    };
+}

package/dist/gem/analysisCache.js

@@ -0,0 +1,55 @@
+// src/gem/analysisCache.ts
+//
+// Per-project cache of the (expensive, ~15-20s) workflow analysis. Keyed by the
+// project root and a transcript "token" that changes whenever a session is added
+// or updated — so the cache stays valid until the project's sessions change, and
+// revisiting a project to pick a different candidate is instant. Best-effort and
+// persistent (~/.agentgem/analysis-cache.json); failures never throw.
+import { readFileSync, writeFileSync, mkdirSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { agentgemHome } from "../resolveDir.js";
+const MAX_ENTRIES = 50;
+function cachePath() { return join(agentgemHome(), ".agentgem", "analysis-cache.json"); }
+// Bump on any change to what an analysis result contains (the token is otherwise
+// content-blind). v2 = the payload now carries the `distilled` track, so v1 entries
+// (which lack it) must not be served (proposal §8).
+const TOKEN_VERSION = "v2";
+/** A cheap validity token: version + transcript count + newest mtime. New/updated session → new token. */
+export function transcriptToken(paths) {
+    let maxMs = 0;
+    for (const p of paths) {
+        try {
+            const m = statSync(p).mtimeMs;
+            if (m > maxMs)
+                maxMs = m;
+        }
+        catch { /* gone — ignore */ }
+    }
+    return `${TOKEN_VERSION}:${paths.length}:${Math.round(maxMs)}`;
+}
+function readAll() {
+    try {
+        const j = JSON.parse(readFileSync(cachePath(), "utf8"));
+        return Array.isArray(j) ? j : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Cached result for (root, token), or null on miss/stale. */
+export function readAnalysisCache(root, token) {
+    const e = readAll().find((x) => x.root === root && x.token === token);
+    return e ? e.result : null;
+}
+/** Store (root, token) → result, replacing any prior entry for root. Capped + best-effort. */
+export function writeAnalysisCache(root, token, result, nowMs) {
+    try {
+        const all = readAll().filter((x) => x.root !== root);
+        all.push({ root, token, result, ts: nowMs });
+        all.sort((a, b) => b.ts - a.ts);
+        const path = cachePath();
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(all.slice(0, MAX_ENTRIES)), "utf8");
+    }
+    catch { /* best-effort */ }
+}

package/dist/gem/archive.js

@@ -86,6 +86,14 @@ export function writeGemArchive(gem, opts = {}) {
             if (place(path, JSON.stringify(body, null, 2), a.name, "mcp_server"))
                 artifacts.push({ type: "mcp_server", name: a.name, path });
         }
+        else if (a.type === "channel") {
+            const path = `channels/${withExt(seg, ".json")}`;
+            const body = { platform: a.platform, secretRefs: a.secretRefs };
+            if (a.description !== undefined)
+                body.description = a.description;
+            if (place(path, JSON.stringify(body, null, 2), a.name, "channel"))
+                artifacts.push({ type: "channel", name: a.name, path });
+        }
         else {
             const path = `hooks/${withExt(seg, ".json")}`;
             const body = { event: a.event, config: a.config };
@@ -159,6 +167,15 @@ export function readGemArchive(files) {
                 a.secretRefs = o.secretRefs;
             return a;
         }
+        if (e.type === "channel") {
+            const o = JSON.parse(body(e.path));
+            const a = { type: "channel", name: e.name, platform: o.platform, secretRefs: o.secretRefs };
+            if (o.description !== undefined)
+                a.description = o.description;
+            return a;
+        }
+        if (e.type !== "hook")
+            throw new Error(`unknown artifact type '${e.type}' in manifest`);
         const o = JSON.parse(body(e.path));
         const a = { type: "hook", name: e.name, event: o.event, config: o.config };
         if (o.matcher !== undefined)

package/dist/gem/binPath.js

@@ -0,0 +1,9 @@
+// src/gem/binPath.ts
+// Leaf helper: is `binName` resolvable on the current PATH? Shared by the adapter
+// resolver (runGem) and the sandbox backend availability checks (sandbox), so neither
+// hard-codes an absolute install path for a tool that distros place in different dirs.
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+export function binOnPath(binName) {
+    return (process.env.PATH ?? "").split(delimiter).some((d) => d && existsSync(join(d, binName)));
+}

package/dist/gem/buildGem.js

@@ -1,4 +1,5 @@
 import { redactMcpConfig } from "./redact.js";
+import { makeChannelArtifact } from "./channels.js";
 export function buildGem(inventory, selection, opts = {}) {
     const artifacts = [];
     const projects = inventory.projects ?? [];
@@ -68,9 +69,11 @@ export function buildGem(inventory, selection, opts = {}) {
     });
     artifacts.length = 0;
     artifacts.push(...guarded);
+    for (const ch of opts.channels ?? [])
+        artifacts.push(makeChannelArtifact(ch.platform, ch.name));
     const requiredSecrets = [];
     for (const a of artifacts) {
-        if ((a.type === "mcp_server" || a.type === "hook") && a.secretRefs) {
+        if ((a.type === "mcp_server" || a.type === "hook" || a.type === "channel") && a.secretRefs) {
             for (const ref of a.secretRefs)
                 requiredSecrets.push({ name: ref.name, artifact: a.name, location: ref.location });
         }