@ninemind/agentgem 0.2.0 → 0.3.0

package/dist/gem/sandboxLaunch.js

@@ -0,0 +1,55 @@
+// src/gem/sandboxLaunch.ts
+// Pure generators for the OS-native sandbox launchers. The v1 boundary contains
+// FILESYSTEM WRITES to the run dir (+ temp); reads, exec, and network stay open. This
+// "write-deny" shape (allow-all, then deny writes, then re-allow under runDir) avoids
+// the deny-default trap that kills the agent's own runtime before it can start.
+import { tmpdir } from "node:os";
+import { realpathSync } from "node:fs";
+// Resolve symlinks when the path exists; fall back to the original string otherwise.
+function tryRealpath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+export function seatbeltPolicy(runDir, tmpDir = tmpdir()) {
+    // Resolve symlinks so the SBPL subpath clause matches the kernel's canonical path.
+    // On macOS, tmpdir() returns /var/folders/... but the kernel sees /private/var/folders/...
+    // Fall back to the original path if the directory doesn't exist yet.
+    const realRun = tryRealpath(runDir);
+    const realTmp = tryRealpath(tmpDir);
+    return [
+        "(version 1)",
+        "(allow default)",
+        "(deny file-write*)",
+        "(allow file-write*",
+        `  (subpath ${q(realRun)})`,
+        `  (subpath ${q(realTmp)})`,
+        '  (literal "/dev/null") (literal "/dev/stdout") (literal "/dev/stderr")',
+        '  (subpath "/dev/tty") (regex #"^/dev/fd/"))',
+    ].join("\n");
+}
+// SBPL string literal: wrap in double quotes (paths under our control have no quotes).
+function q(p) { return `"${p}"`; }
+export function bwrapArgs(runDir, tmpDir = tmpdir()) {
+    // Resolve symlinks so the writable bind matches the kernel's canonical path
+    // (mirrors seatbeltPolicy); fall back to the original if the dir doesn't exist yet.
+    const realRun = tryRealpath(runDir);
+    const realTmp = tryRealpath(tmpDir);
+    return [
+        "--ro-bind", "/", "/", // everything readable, nothing writable…
+        "--bind", realRun, realRun, // …except the run dir…
+        "--bind", realTmp, realTmp, // …and temp.
+        "--dev", "/dev",
+        "--unshare-pid", // own PID namespace: the agent can't see/signal host processes
+        "--proc", "/proc", // fresh procfs for that namespace (must follow --unshare-pid)
+        "--die-with-parent",
+    ];
+}
+export function wrapWithSandbox(kind, runDir, command) {
+    if (kind === "macos-seatbelt")
+        return ["sandbox-exec", "-p", seatbeltPolicy(runDir), ...command];
+    return ["bwrap", ...bwrapArgs(runDir), "--", ...command];
+}

package/dist/gem/scrub.js

@@ -0,0 +1,108 @@
+// src/gem/scrub.ts
+//
+// Field-aware, default-deny scrubber for builtin tool_use inputs captured during
+// transcript distillation (see docs/proposals/skill-distillation-from-transcripts.md
+// §3a). Unlike redact.ts (which redacts secret VALUES in a structured config),
+// this keeps only an allowlisted structural slice per builtin and DROPS everything
+// else — removing the file-content/PII class by construction rather than blocklist.
+//
+// Output per step: { verb, arg } — a coarse low-cardinality `verb` for procedure
+// recurrence (§3c) and a minimal scrubbed `arg` for the agent.
+// Token-level secret detection. redact.ts redacts the WHOLE value and can lean on
+// bare keywords because it has key/value structure; here we scrub free-text command
+// tokens, where bare words like "secret"/"token"/"password" legitimately appear in
+// filenames and commit messages (`cat secret.env`). So the rule is intentionally
+// narrower: a token is secret only if it is HIGH-ENTROPY or carries a known secret
+// PREFIX — never a plain dictionary keyword. (Short keyword-less secrets survive;
+// that residual risk is accepted under the draft-only review gate — proposal §3a.)
+const SECRET_PREFIX_RE = /^(sk-|ghp_|gho_|ghu_|ghs_|github_pat_|xox[a-z]-|AKIA|ASIA|glpat-)/;
+function looksLikeSecretToken(t) {
+    if (t.length >= 32 && /^[A-Za-z0-9_-]+$/.test(t))
+        return true; // high entropy
+    if (t.length >= 8 && SECRET_PREFIX_RE.test(t))
+        return true; // prefixed token
+    return false;
+}
+// Rewrite $HOME-absolute prefixes to ~ and any /Users/<name>/ to ~/, so paths
+// never carry a username. Applied before token scrub.
+function dehomePaths(s) {
+    const home = process.env.HOME;
+    let out = home ? s.split(home).join("~") : s;
+    out = out.replace(/\/Users\/[^/\s]+\//g, "~/");
+    return out;
+}
+// Token-scrub a free-text arg: de-home paths, then replace any secret-looking
+// whitespace token with <redacted>, leaving the rest of the command intact.
+function scrubText(s) {
+    return dehomePaths(s)
+        .split(/(\s+)/) // keep separators so spacing is preserved
+        .map((tok) => (/\s/.test(tok) ? tok : redactToken(tok)))
+        .join("");
+}
+// A token may carry a secret embedded in surrounding syntax (https://SECRET@host).
+// Redact the embedded secret, not the whole token, so structure survives.
+function redactToken(tok) {
+    if (!tok)
+        return tok;
+    return tok
+        .split(/([^A-Za-z0-9_-]+)/) // split on non-identifier runs, keep them
+        .map((part) => (/^[A-Za-z0-9_-]+$/.test(part) && looksLikeSecretToken(part) ? "<redacted>" : part))
+        .join("");
+}
+// Scrub free-text prose (mission-hint task/outcome). Same token scrub + de-home as
+// command args, plus a hard length cap — this is the one place free text is kept,
+// so it is deliberately short and low-detail (proposal §3b).
+export function scrubProse(s, maxLen = 280) {
+    const scrubbed = scrubText(s).trim();
+    if (scrubbed.length <= maxLen)
+        return scrubbed;
+    return scrubbed.slice(0, maxLen) + "…";
+}
+// Coarse procedure verb: "git commit -m fix" -> "Bash:git commit", "cd /x" ->
+// "Bash:cd", "/usr/bin/npx vitest" -> "Bash:npx vitest". argv0 is basenamed; the
+// 2nd token counts as a subcommand ONLY if it's a clean lowercase word — a path,
+// filename, flag, or quoted arg is NOT a subcommand, so it never inflates the verb.
+function bashVerb(command) {
+    const toks = command.trim().split(/\s+/).filter(Boolean);
+    if (!toks.length)
+        return "Bash";
+    const argv0 = (toks[0].split("/").pop() || toks[0]).replace(/[;|&]+$/, "");
+    if (!argv0)
+        return "Bash";
+    const sub = toks[1] && /^[a-z][a-z0-9-]*$/.test(toks[1]) ? ` ${toks[1]}` : "";
+    return `Bash:${argv0}${sub}`;
+}
+function str(input, key) {
+    const v = input?.[key];
+    return typeof v === "string" ? v : "";
+}
+// Default-deny: each builtin keeps only an allowlisted structural slice; every
+// other field (file contents, agent prompts, tool output, unknown fields) is
+// dropped, not scrubbed — so the file-content/PII class is removed by construction.
+export function scrubStep(tool, input) {
+    switch (tool) {
+        case "Bash": {
+            const command = str(input, "command");
+            return { verb: bashVerb(command), arg: scrubText(command) };
+        }
+        // Edit/Write/NotebookEdit: keep the path; DROP old_string/new_string/content.
+        case "Edit":
+        case "Write":
+        case "NotebookEdit":
+            return { verb: tool, arg: scrubText(str(input, "file_path") || str(input, "notebook_path")) };
+        // Read/Grep/Glob: keep the path/pattern; DROP file contents and match output.
+        case "Read":
+        case "Grep":
+        case "Glob":
+            return { verb: tool, arg: scrubText(str(input, "file_path") || str(input, "path") || str(input, "pattern")) };
+        // Task/agent spawns: keep the short description; DROP the prompt.
+        case "Task":
+        case "Agent": {
+            const sub = str(input, "subagent_type");
+            return { verb: sub ? `${tool}:${sub}` : tool, arg: scrubText(str(input, "description")) };
+        }
+        // Unknown tool: verb only, entire input dropped.
+        default:
+            return { verb: tool, arg: "" };
+    }
+}

package/dist/gem/search.js

@@ -0,0 +1,34 @@
+// Weighted field match: name >> tags > description. An empty query (with optional
+// kind/tag filter) browses the catalog — every gem returns, score 0.
+export function searchIndex(index, query, opts = {}) {
+    const terms = query.trim().toLowerCase().split(/\s+/).filter(Boolean);
+    const hits = [];
+    for (const [key, item] of Object.entries(index.items)) {
+        const d = item.discovery ?? {};
+        if (opts.kind && !(d.artifactKinds ?? []).includes(opts.kind))
+            continue;
+        if (opts.tag && !(d.tags ?? []).includes(opts.tag))
+            continue;
+        const name = key.toLowerCase();
+        const tags = (d.tags ?? []).join(" ").toLowerCase();
+        const desc = (d.description ?? "").toLowerCase();
+        let score = 0;
+        for (const t of terms) {
+            if (name === t)
+                score += 100;
+            else if (name.includes(t))
+                score += 10;
+            if (tags.split(/\s+/).includes(t))
+                score += 5;
+            else if (tags.includes(t))
+                score += 3;
+            if (desc.includes(t))
+                score += 1;
+        }
+        if (terms.length && score === 0)
+            continue; // query given but nothing matched
+        hits.push({ key, latest: item.latest, score, description: d.description, tags: d.tags, author: d.author, artifactKinds: d.artifactKinds, updatedAt: d.updatedAt });
+    }
+    hits.sort((a, b) => b.score - a.score || a.key.localeCompare(b.key));
+    return hits.slice(0, opts.limit ?? 25);
+}

package/dist/gem/share.js

@@ -0,0 +1,21 @@
+// src/gem/share.ts
+// The registry-optional "easy share" loop: turn a Gem into one portable .gem file
+// and install one back. Pure + in-process — no disk/network — so it composes with
+// any transport (file, URL, gist, paste). Integrity is inherited from readGemArchive,
+// which verifies gem.lock and throws on any mismatch, so a tampered .gem never installs.
+import { writeGemArchive, readGemArchive, readGemMeta } from "./archive.js";
+import { packTar, unpackTar } from "./archiveTar.js";
+import { safePathSegment } from "./targets.js";
+// Gem -> a single self-verifying .gem (gzipped tar of the archive file tree).
+export function exportGem(gem, opts = {}) {
+    const { files, skipped } = writeGemArchive(gem, opts);
+    const version = opts.version ?? "0.1.0";
+    return { filename: `${safePathSegment(gem.name)}-${version}.gem`, bytes: packTar(files), skipped };
+}
+// A .gem's bytes -> the verified Gem. Throws if the bytes aren't a valid archive
+// or if gem.lock verification fails (tampering / corruption).
+export function importGem(bytes) {
+    const files = unpackTar(bytes);
+    const gem = readGemArchive(files); // verifies gem.lock; throws on mismatch
+    return { gem, meta: readGemMeta(files) };
+}

package/dist/gem/targets.js

@@ -1,3 +1,4 @@
+import { channelScaffold } from "./channels.js";
 import { tomlMcpServers } from "./toml.js";
 import { stdioProxyRunner, PROXY_BASE_PORT, PROXY_HOST } from "./mcpProxy.js";
 export function safePathSegment(name) {
@@ -19,6 +20,17 @@ const fluePascal = (name) => flueName(name).split("-").filter(Boolean).map((w) =
 // Flue skills live under src/ (the agent file is src/agents/<name>.ts and imports ../skills/...).
 const skillFlueMd = (a) => ({ [`src/skills/${safePathSegment(a.name)}/SKILL.md`]: a.content });
 const rendered = (files) => ({ files, skipped: [] });
+// MCP header secrets -> [headerName, envVarName] entries, Authorization first. Shared by the HTTP/SSE
+// renderers (flue / openai-sandbox / a2a); the env-var NAME is emitted, never a value. Callers that
+// require header-only auth check separately for a non-`headers.` secret (the unsupported case).
+const headerSecretEntries = (refs) => {
+    const authorization = refs.find((r) => r.location.toLowerCase() === "headers.authorization");
+    return [
+        ...(authorization ? [["Authorization", authorization.name]] : []),
+        ...refs.filter((r) => /^headers\./i.test(r.location) && r !== authorization)
+            .map((r) => [r.location.slice("headers.".length), r.name]),
+    ];
+};
 // ── shared convention renderers ──
 const skillSkillMd = (a) => ({ [`skills/${safePathSegment(a.name)}/SKILL.md`]: a.content });
 const skillDescriptionMd = (a) => ({ [`skills/${safePathSegment(a.name)}/DESCRIPTION.md`]: a.content });
@@ -220,13 +232,7 @@ function escapeTemplate(s) {
 // env var name, never a value). stdio -> a localhost connection plus a generated proxy runner under
 // proxies/ that bridges the stdio server to HTTP (same mechanism as Eve).
 const flueConnection = (server, url) => {
-    const refs = server.secretRefs ?? [];
-    const authorization = refs.find((r) => r.location.toLowerCase() === "headers.authorization");
-    const headerEntries = [
-        ...(authorization ? [["Authorization", authorization.name]] : []),
-        ...refs.filter((r) => /^headers\./i.test(r.location) && r !== authorization)
-            .map((r) => [r.location.slice("headers.".length), r.name]),
-    ];
+    const headerEntries = headerSecretEntries(server.secretRefs ?? []);
     const transport = server.transport === "sse" ? `,\n  transport: "sse"` : "";
     const headers = headerEntries.length
         ? `,\n  headers: { ${headerEntries.map(([h, env]) => `${JSON.stringify(h)}: process.env[${JSON.stringify(env)}]!`).join(", ")} }`
@@ -339,11 +345,7 @@ const sandboxMcpServer = (s) => {
         const unsupported = refs.find((r) => !/^headers\./i.test(r.location));
         if (unsupported)
             return { skip: `OpenAI sandbox cannot map secret at ${unsupported.location}` };
-        const authorization = refs.find((r) => r.location.toLowerCase() === "headers.authorization");
-        const headerEntries = [
-            ...(authorization ? [["Authorization", authorization.name]] : []),
-            ...refs.filter((r) => /^headers\./i.test(r.location) && r !== authorization).map((r) => [r.location.slice("headers.".length), r.name]),
-        ];
+        const headerEntries = headerSecretEntries(refs);
         const requestInit = headerEntries.length
             ? `, requestInit: { headers: { ${headerEntries.map(([h, e]) => `${JSON.stringify(h)}: process.env[${JSON.stringify(e)}]!`).join(", ")} } }`
             : "";
@@ -475,10 +477,10 @@ const evePackageJson = (gemName) => JSON.stringify({
     type: "module",
     imports: { "#*": "./agent/*", "#evals/*": "./evals/*" },
     scripts: { build: "eve build", dev: "eve dev", start: "eve start", typecheck: "tsgo" },
-    dependencies: { "@vercel/connect": "0.2.2", ai: "7.0.0-beta.178", eve: "^0.11.7", microsandbox: "^0.5.0", zod: "4.4.3" },
+    dependencies: { "@vercel/connect": "0.2.2", ai: "7.0.2", eve: "^0.15.0", microsandbox: "^0.5.0", zod: "4.4.3" },
     devDependencies: { "@types/node": "24.x", "@typescript/native-preview": "7.0.0-dev.20260523.1" },
-    overrides: { ai: "7.0.0-beta.178" },
-    resolutions: { ai: "7.0.0-beta.178" },
+    overrides: { ai: "7.0.2" },
+    resolutions: { ai: "7.0.2" },
     engines: { node: "24.x" },
 }, null, 2) + "\n";
 // Cross-cutting scaffold: the files `eve init` provides so the rendered agent/ source is runnable.
@@ -499,6 +501,26 @@ const eveComposeProject = (gem, opts = {}) => {
     }
     return rendered(files);
 };
+// Eve channel files: one agent/channels/<name>.ts per declared channel, from the platform registry
+// scaffold. "eve" is reserved for the always-on web/auth channel that eveComposeProject emits.
+const channelEve = (channels) => {
+    const files = {};
+    const skipped = [];
+    for (const c of channels) {
+        const seg = eveSegment(c.name);
+        const path = `agent/channels/${seg}.ts`;
+        if (seg === "eve") {
+            skipped.push({ artifact: c.name, type: "channel", reason: "channel name 'eve' is reserved for the web channel" });
+            continue;
+        }
+        if (path in files) {
+            skipped.push({ artifact: c.name, type: "channel", reason: `path collision with an earlier channel at ${path}` });
+            continue;
+        }
+        files[path] = channelScaffold(c.platform);
+    }
+    return { files, skipped };
+};
 // ── A2A (Agent2Agent) target ──
 // Card primitive: materialize(gem, "a2a") emits a runtime-free Agent Card derived from the gem — the
 // A2A discovery surface, publishable to the registry. The Card is the part native to AgentGem's
@@ -512,10 +534,13 @@ const a2aSkillCard = (a) => ({
 });
 // A one-line card description from an instruction artifact: prefer the first non-empty *prose* line
 // (instruction files usually open with a throwaway "# Title" heading); fall back to the de-headed
-// first line if the doc is headings-only.
+// first line if the doc is headings-only. Only ATX headings ("# " … "###### ") count as headings, so a
+// prose line that merely starts with '#' (e.g. "#launch") is kept. Bounded so the card carries a label,
+// not a paragraph.
 const a2aFirstLine = (s) => {
     const lines = s.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
-    return lines.find((l) => !l.startsWith("#")) ?? lines[0]?.replace(/^#+\s*/, "") ?? "";
+    const line = lines.find((l) => !/^#{1,6}\s/.test(l)) ?? lines[0]?.replace(/^#+\s*/, "") ?? "";
+    return line.length > 200 ? line.slice(0, 197).replace(/\s+\S*$/, "") + "…" : line;
 };
 // Pure Gem -> AgentCard projection. Skills advertise as A2A skills (metadata, not bodies); the first
 // instruction line becomes the card description; a skill-less Gem gets a synthesized `chat` skill
@@ -529,7 +554,9 @@ export const a2aAgentCard = (gem) => {
         name: gem.name,
         description: a2aFirstLine(instr[0]?.content ?? "") || `An agent packaged by AgentGem from ${skills.length} skill(s).`,
         version: "0.1.0",
-        url: "http://localhost:41241/a2a/jsonrpc", // discovery placeholder; the (future) server overrides from PUBLIC_URL
+        // Non-resolving placeholder (RFC 6761 reserved TLD): a published card must NOT carry a localhost url
+        // a consumer would dial against its own machine. Server mode rebinds this from PUBLIC_URL at boot.
+        url: "https://set-public-url.invalid/a2a/jsonrpc",
         capabilities: { streaming: false, pushNotifications: false },
         defaultInputModes: ["text"],
         defaultOutputModes: ["text"],
@@ -548,12 +575,7 @@ const a2aMcpClient = (s) => {
         const unsupported = refs.find((r) => !/^headers\./i.test(r.location));
         if (unsupported)
             return { skip: `A2A (AI SDK) cannot map secret at ${unsupported.location}` };
-        const authorization = refs.find((r) => r.location.toLowerCase() === "headers.authorization");
-        const headerEntries = [
-            ...(authorization ? [["Authorization", authorization.name]] : []),
-            ...refs.filter((r) => /^headers\./i.test(r.location) && r !== authorization)
-                .map((r) => [r.location.slice("headers.".length), r.name]),
-        ];
+        const headerEntries = headerSecretEntries(refs);
         const headers = headerEntries.length
             ? `, headers: { ${headerEntries.map(([h, e]) => `${JSON.stringify(h)}: process.env[${JSON.stringify(e)}]!`).join(", ")} }`
             : "";
@@ -584,8 +606,8 @@ const a2aSecretsMd = (secrets) => {
 const a2aPackageJson = (gemName) => JSON.stringify({
     name: safePathSegment(gemName).toLowerCase(), version: "0.1.0", private: true, type: "module",
     scripts: { build: "tsc", start: "node dist/server.js", dev: "tsx src/server.ts" },
-    // Verified pins: ai v7 beta pairs with @ai-sdk/mcp v2 beta; @a2a-js/sdk 0.3.x.
-    dependencies: { "@a2a-js/sdk": "^0.3.13", ai: "7.0.0-beta.178", "@ai-sdk/mcp": "2.0.0-beta.67", express: "^5", uuid: "^11" },
+    // Verified pins: ai v7 GA pairs with @ai-sdk/mcp v2 GA (both on @ai-sdk/provider@4); @a2a-js/sdk 0.3.x.
+    dependencies: { "@a2a-js/sdk": "^0.3.13", ai: "7.0.2", "@ai-sdk/mcp": "2.0.0", express: "^5", uuid: "^11" },
     devDependencies: { "@types/express": "^5", "@types/node": "^24", tsx: "^4", typescript: "^5" },
 }, null, 2) + "\n";
 // The runnable A2A server: an AI SDK `streamText` tool loop behind the @a2a-js/sdk JSON-RPC handler.
@@ -632,7 +654,15 @@ class GemExecutor implements AgentExecutor {
   private inflight = new Map<string, AbortController>();
   async execute(ctx: RequestContext, bus: ExecutionEventBus): Promise<void> {
     const { taskId, contextId, userMessage, task } = ctx;
-    const text = (userMessage.parts ?? []).filter((p: any) => p.kind === "text").map((p: any) => p.text).join("\\n");
+    const text = (userMessage.parts ?? []).filter((p: any) => p.kind === "text").map((p: any) => p.text).join("\\n").trim();
+    // Guard: an A2A message may carry no text parts (file/data only). streamText rejects an empty
+    // prompt, so reply directly instead of failing the request.
+    if (!text) {
+      bus.publish({ kind: "message", messageId: uuid(), role: "agent", contextId,
+        parts: [{ kind: "text", text: "Please include a text message for the agent." }] });
+      bus.finished();
+      return;
+    }
     const ac = new AbortController();
     this.inflight.set(taskId, ac);
     if (!task) bus.publish({ kind: "task", id: taskId, contextId, status: { state: "submitted", timestamp: new Date().toISOString() }, history: [userMessage] });
@@ -646,7 +676,8 @@ class GemExecutor implements AgentExecutor {
           artifact: { artifactId, name: "response", parts: [{ kind: "text", text: delta }] } });
         started = true;
       }
-      bus.publish({ kind: "artifact-update", taskId, contextId, append: true, lastChunk: true, artifact: { artifactId, parts: [] } });
+      // Only close an artifact that was actually opened (empty/tool-only completions stream nothing).
+      if (started) bus.publish({ kind: "artifact-update", taskId, contextId, append: true, lastChunk: true, artifact: { artifactId, parts: [] } });
       bus.publish({ kind: "status-update", taskId, contextId, status: { state: "completed", timestamp: new Date().toISOString() }, final: true });
     } catch (err) {
       const state = ac.signal.aborted ? "canceled" : "failed";
@@ -675,22 +706,29 @@ app.use("/a2a/rest", restHandler({ requestHandler, userBuilder: UserBuilder.noAu
 app.listen(port, () => console.log(\`A2A agent "\${card.name}" listening on :\${port}\`));
 `;
 };
-// A2A is wholly compose-driven: per-type renderers are no-ops (so no artifact is skip-reported), and
-// compose emits the Agent Card. Card-only mode models neither MCP nor hooks, so nothing is skipped.
-// With opts.a2aServer, it additionally emits a runnable server and evaluates MCP/hook mappability.
+// A2A is wholly compose-driven: per-type renderers are no-ops (so materialize never auto-skip-reports),
+// and compose owns ALL skip reporting for both modes. Hooks are never expressible by A2A (card or
+// server). MCP is not expressible by a *Card* (card-only -> all MCP skipped), but the *server* wires it
+// (server mode -> only unmappable MCP skipped). This keeps compatibility() honest: card-only reflects
+// that a Card carries identity + skills, not MCP/hooks, instead of over-claiming full support.
 const a2aComposeProject = (gem, opts = {}) => {
     const files = { "agent-card.json": JSON.stringify(a2aAgentCard(gem), null, 2) + "\n" };
-    if (!opts.a2aServer)
-        return { files, skipped: [] };
-    const skills = gem.artifacts.filter((a) => a.type === "skill");
-    const instr = gem.artifacts.filter((a) => a.type === "instructions");
     const mcps = gem.artifacts.filter((a) => a.type === "mcp_server");
     const hooks = gem.artifacts.filter((a) => a.type === "hook");
+    const hookSkips = hooks.map((h) => ({ artifact: h.name, type: "hook", reason: "A2A has no hook concept" }));
+    if (!opts.a2aServer) {
+        // Card-only: an Agent Card represents identity + skills, not MCP servers or hooks.
+        const cardSkips = mcps.map((s) => ({ artifact: s.name, type: "mcp_server", reason: "an Agent Card cannot express MCP servers (materialize with a2aServer to wire them)" }));
+        return { files, skipped: [...cardSkips, ...hookSkips] };
+    }
+    const skills = gem.artifacts.filter((a) => a.type === "skill");
+    const instr = gem.artifacts.filter((a) => a.type === "instructions");
     // AI SDK has no skills primitive -> fold skill bodies (frontmatter-stripped) into the system prompt.
     const instrText = instr.map((i) => `## ${i.name}\n\n${i.content}`).join("\n\n---\n\n");
     const skillText = skills.map((s) => `## Skill: ${s.name}\n\n${stripYamlFrontmatter(s.content)}`).join("\n\n---\n\n");
     const system = [instrText, skillText].filter(Boolean).join("\n\n---\n\n");
-    const skipped = [];
+    // Server mode: the server wires MCP, so only UNMAPPABLE MCP is skipped; hooks remain unsupported.
+    const skipped = [...hookSkips];
     const clientCodes = [];
     let usesStdio = false;
     for (const s of mcps) {
@@ -702,8 +740,6 @@ const a2aComposeProject = (gem, opts = {}) => {
         clientCodes.push(r.code);
         usesStdio ||= r.stdio;
     }
-    for (const h of hooks)
-        skipped.push({ artifact: h.name, type: "hook", reason: "A2A has no hook concept" });
     return {
         files: {
             ...files,
@@ -721,7 +757,7 @@ export const TARGET_REGISTRY = {
     agents: { id: "agents", label: "Agents", skill: skillSkillMd, instructions: instructionsAgentsMd },
     hermes: { id: "hermes", label: "Hermes", skill: skillDescriptionMd, instructions: instructionsSoulMd },
     // Eve project layout (agent/...). Hooks are event-reacting code in Eve, not config -> unsupported.
-    eve: { id: "eve", label: "Eve", skill: skillEveMd, instructions: concatInstructions("agent/instructions.md"), mcp: mcpEveConnections, compose: eveComposeProject },
+    eve: { id: "eve", label: "Eve", skill: skillEveMd, instructions: concatInstructions("agent/instructions.md"), mcp: mcpEveConnections, channel: channelEve, compose: eveComposeProject },
     // Flue project layout. Skills reuse SKILL.md; instructions fold into the composed agent file (no
     // standalone file -> the empty instructions renderer marks them handled, not skipped). MCP added in Task 2.
     flue: { id: "flue", label: "Flue", skill: skillFlueMd, instructions: () => ({}), mcp: mcpFlueConnections, compose: flueComposeAgent },
@@ -753,6 +789,7 @@ export function materialize(gem, target, opts = {}) {
     const mcp = gem.artifacts.filter((a) => a.type === "mcp_server");
     const instr = gem.artifacts.filter((a) => a.type === "instructions");
     const hooks = gem.artifacts.filter((a) => a.type === "hook");
+    const channels = gem.artifacts.filter((a) => a.type === "channel");
     if (spec.skill)
         for (const s of skills)
             merge(spec.skill(s), s.name, "skill");
@@ -779,6 +816,15 @@ export function materialize(gem, target, opts = {}) {
         else
             skipAll(hooks, "hook");
     }
+    if (channels.length) {
+        if (spec.channel) {
+            const result = spec.channel(channels);
+            merge(result.files, channels.map((c) => c.name).join(", "), "channel");
+            skipped.push(...result.skipped);
+        }
+        else
+            skipAll(channels, "channel");
+    }
     if (spec.compose) {
         const result = spec.compose(gem, opts);
         merge(result.files, "(composed agent)", "instructions"); // collisions reported; agent file derives from instructions+skills

package/dist/gem/workspaces.js

@@ -8,6 +8,7 @@ import { mkdirSync, rmSync, readdirSync, statSync, existsSync, readFileSync } fr
 import { materialize, compatibility, TARGET_REGISTRY, safePathSegment } from "./targets.js";
 import { writeGemArchive, readGemArchive } from "./archive.js";
 import { writeArchiveDir, readArchiveDir } from "./archiveFs.js";
+import { InvalidInputError } from "./inputError.js";
 const TARGETS_DIR = ".targets";
 export function workspacesRoot() {
     const home = process.env.AGENTGEM_HOME ?? join(homedir(), ".agentgem");
@@ -18,7 +19,7 @@ export function workspacesRoot() {
 export function workspaceName(name) {
     const seg = safePathSegment(name);
     if (seg !== name)
-        throw new Error(`invalid workspace name '${name}' — use only [A-Za-z0-9._-], no separators`);
+        throw new InvalidInputError(`invalid workspace name '${name}' — use only [A-Za-z0-9._-], no separators`);
     return seg;
 }
 export function workspaceDir(name) {
@@ -73,12 +74,12 @@ export function readWorkspace(name) {
     const gem = readGemArchive(files); // verifies the lock
     return { ...summary(workspaceName(name), files["gem.json"], dir), files, compatibility: compatibility(gem) };
 }
-export function renderTarget(name, target) {
+export function renderTarget(name, target, opts = {}) {
     const dir = workspaceDir(name);
     if (!existsSync(join(dir, "gem.json")))
         throw new Error(`no workspace '${name}'`);
     const gem = readGemArchive(readArchiveDir(dir));
-    const { files, skipped } = materialize(gem, target);
+    const { files, skipped } = materialize(gem, target, opts);
     const out = join(dir, TARGETS_DIR, target);
     rmSync(out, { recursive: true, force: true }); // clear stale renders
     mkdirSync(out, { recursive: true });