@ninemind/agentgem 0.1.1 → 0.3.0

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,255 @@ 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
+// "describe an agent" mission; a runnable A2A server is a planned opt-in flavor (MaterializeOpts).
+const A2A_PROTOCOL_VERSION = "0.3.0";
+const a2aSkillCard = (a) => ({
+    id: safePathSegment(a.name),
+    name: a.name,
+    description: a.description?.trim() || `The ${a.name} skill.`,
+    tags: ["skill"],
+});
+// 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. 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);
+    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
+// (A2A requires >=1). Emits no secret values (skills/instructions carry none post-redaction).
+export const a2aAgentCard = (gem) => {
+    const skills = gem.artifacts.filter((a) => a.type === "skill");
+    const instr = gem.artifacts.filter((a) => a.type === "instructions");
+    const cardSkills = skills.map(a2aSkillCard);
+    return {
+        protocolVersion: A2A_PROTOCOL_VERSION,
+        name: gem.name,
+        description: a2aFirstLine(instr[0]?.content ?? "") || `An agent packaged by AgentGem from ${skills.length} skill(s).`,
+        version: "0.1.0",
+        // 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"],
+        skills: cardSkills.length ? cardSkills
+            : [{ id: "chat", name: "chat", description: `Converse with ${gem.name}.`, tags: ["chat"] }],
+    };
+};
+// ── A2A server mode (opt-in via MaterializeOpts.a2aServer) ──
+// Runtime is Vercel AI SDK v7 (`ai` + `@ai-sdk/mcp`), vendor-neutral via the gateway model string —
+// deliberately NOT @openai/agents, so sandboxMcpServer is not reused (a2aMcpClient is its analogue).
+const A2A_MODEL = "anthropic/claude-sonnet-4-6";
+const a2aMcpClient = (s) => {
+    const url = typeof s.config.url === "string" ? s.config.url : "";
+    if (/^https?:\/\//.test(url)) {
+        const refs = s.secretRefs ?? [];
+        const unsupported = refs.find((r) => !/^headers\./i.test(r.location));
+        if (unsupported)
+            return { skip: `A2A (AI SDK) cannot map secret at ${unsupported.location}` };
+        const headerEntries = headerSecretEntries(refs);
+        const headers = headerEntries.length
+            ? `, headers: { ${headerEntries.map(([h, e]) => `${JSON.stringify(h)}: process.env[${JSON.stringify(e)}]!`).join(", ")} }`
+            : "";
+        const type = s.transport === "sse" ? "sse" : "http";
+        return { code: `  createMCPClient({ transport: { type: ${JSON.stringify(type)}, url: ${JSON.stringify(url)}${headers} } }),`, stdio: false };
+    }
+    if (s.transport === "stdio" && typeof s.config.command === "string") {
+        const args = Array.isArray(s.config.args) ? s.config.args.filter((a) => typeof a === "string") : [];
+        const envNames = (s.secretRefs ?? []).map((r) => r.name);
+        const envStr = envNames.length ? `, env: { ${envNames.map((n) => `${JSON.stringify(n)}: process.env[${JSON.stringify(n)}]!`).join(", ")} }` : "";
+        return { code: `  createMCPClient({ transport: new Experimental_StdioMCPTransport({ command: ${JSON.stringify(s.config.command)}, args: ${JSON.stringify(args)}${envStr} }) }),`, stdio: true };
+    }
+    return { skip: `${s.transport} MCP has no usable URL or stdio command` };
+};
+// A2A projects authenticate via plain process.env. Deliberately NOT agentcoreSecretsMd (its
+// `agentcore add credential` / ${arn:...} body is wrong for an A2A/AI-SDK project).
+const a2aSecretsMd = (secrets) => {
+    const model = `## Model access\n\nThe agent calls \`${A2A_MODEL}\` via the AI SDK. Set \`AI_GATEWAY_API_KEY\` ` +
+        `(Vercel AI Gateway) or a direct provider key (e.g. \`ANTHROPIC_API_KEY\`).\n`;
+    const access = `## Access control (optional)\n\nSet \`A2A_API_KEY\` to require \`Authorization: Bearer <key>\` on the ` +
+        `agent's JSON-RPC/REST routes. Agent Card discovery (the \`.well-known\` endpoint) stays open.\n`;
+    const mcp = secrets.length
+        ? `## MCP credentials\n\nSet these before \`npm start\` (e.g. a \`.env\` file):\n\n` +
+            `${secrets.map((s) => `- \`${s.name}\` (for ${s.artifact} at ${s.location})`).join("\n")}\n`
+        : `## MCP credentials\n\nThis agent declares no MCP secrets.\n`;
+    return `# Secrets\n\n${model}\n${access}\n${mcp}`;
+};
+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 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.
+// Streams incrementally via the A2A task lifecycle (submitted -> working -> artifact-update* ->
+// completed); the same executor serves message/send (aggregated) and message/stream (SSE). The served
+// card advertises streaming: true and rebinds `url` from PUBLIC_URL (the static card carries neither).
+const a2aServerTs = (system, clientCodes, usesStdio) => {
+    const mcpImports = clientCodes.length
+        ? `import { createMCPClient } from "@ai-sdk/mcp";\n${usesStdio ? `import { Experimental_StdioMCPTransport } from "@ai-sdk/mcp/mcp-stdio";\n` : ""}`
+        : "";
+    const bootBlock = clientCodes.length
+        ? `const mcpClients = await Promise.all([\n${clientCodes.join("\n")}\n]);
+const tools = Object.assign({}, ...(await Promise.all(mcpClients.map((c) => c.tools()))));
+for (const sig of ["SIGINT", "SIGTERM"] as const)
+  process.on(sig, () => { Promise.allSettled(mcpClients.map((c) => c.close())).finally(() => process.exit(0)); });`
+        : `const tools = {};`;
+    return `import express from "express";
+import { streamText, stepCountIs } from "ai";
+${mcpImports}import { type AgentCard, AGENT_CARD_PATH } from "@a2a-js/sdk";
+import { type AgentExecutor, type RequestContext, type ExecutionEventBus,
+  DefaultRequestHandler, InMemoryTaskStore, InMemoryPushNotificationStore, DefaultPushNotificationSender } from "@a2a-js/sdk/server";
+import { agentCardHandler, jsonRpcHandler, restHandler, UserBuilder } from "@a2a-js/sdk/server/express";
+import { v4 as uuid } from "uuid";
+import cardBase from "../agent-card.json" with { type: "json" };
+
+const MODEL = ${JSON.stringify(A2A_MODEL)};
+const SYSTEM = \`${escapeTemplate(system)}\`;
+
+const port = Number(process.env.PORT ?? 41241);
+const baseUrl = process.env.PUBLIC_URL ?? \`http://localhost:\${port}\`;
+const API_KEY = process.env.A2A_API_KEY; // when set, require \`Authorization: Bearer <key>\` on the RPC/REST routes
+const card: AgentCard = { ...(cardBase as AgentCard), url: \`\${baseUrl}/a2a/jsonrpc\`,
+  capabilities: { ...(cardBase as AgentCard).capabilities, streaming: true, pushNotifications: true },
+  additionalInterfaces: [
+    { url: \`\${baseUrl}/a2a/jsonrpc\`, transport: "JSONRPC" },
+    { url: \`\${baseUrl}/a2a/rest\`, transport: "HTTP+JSON" },
+  ],
+  ...(API_KEY ? { securitySchemes: { bearer: { type: "http", scheme: "bearer" } }, security: [{ bearer: [] }] } : {}) };
+
+${bootBlock}
+
+// Streaming executor: drive the tool loop and publish A2A task-lifecycle + artifact-update events.
+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").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] });
+    bus.publish({ kind: "status-update", taskId, contextId, status: { state: "working", timestamp: new Date().toISOString() }, final: false });
+    const artifactId = uuid();
+    let started = false;
+    try {
+      const result = streamText({ model: MODEL, system: SYSTEM, tools, stopWhen: stepCountIs(10), prompt: text, abortSignal: ac.signal });
+      for await (const delta of result.textStream) {
+        bus.publish({ kind: "artifact-update", taskId, contextId, append: started, lastChunk: false,
+          artifact: { artifactId, name: "response", parts: [{ kind: "text", text: delta }] } });
+        started = true;
+      }
+      // 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";
+      bus.publish({ kind: "status-update", taskId, contextId, status: { state, timestamp: new Date().toISOString() }, final: true });
+    } finally {
+      this.inflight.delete(taskId);
+      bus.finished();
+    }
+  }
+  cancelTask = async (taskId: string): Promise<void> => { this.inflight.get(taskId)?.abort(); };
+}
+
+const pushStore = new InMemoryPushNotificationStore();
+const requestHandler = new DefaultRequestHandler(card, new InMemoryTaskStore(), new GemExecutor(),
+  undefined, pushStore, new DefaultPushNotificationSender(pushStore));
+const app = express();
+// Discovery (the /.well-known Agent Card) stays open; gate only the invocation routes when A2A_API_KEY is set.
+const requireAuth: express.RequestHandler = (req, res, next) => {
+  if (!API_KEY || req.headers.authorization === \`Bearer \${API_KEY}\`) return next();
+  res.status(401).json({ error: "unauthorized" });
+};
+app.use("/a2a", requireAuth);
+app.use(\`/\${AGENT_CARD_PATH}\`, agentCardHandler({ agentCardProvider: requestHandler }));
+app.use("/a2a/jsonrpc", jsonRpcHandler({ requestHandler, userBuilder: UserBuilder.noAuthentication }));
+app.use("/a2a/rest", restHandler({ requestHandler, userBuilder: UserBuilder.noAuthentication }));
+app.listen(port, () => console.log(\`A2A agent "\${card.name}" listening on :\${port}\`));
+`;
+};
+// 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" };
+    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");
+    // 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) {
+        const r = a2aMcpClient(s);
+        if ("skip" in r) {
+            skipped.push({ artifact: s.name, type: "mcp_server", reason: r.skip });
+            continue;
+        }
+        clientCodes.push(r.code);
+        usesStdio ||= r.stdio;
+    }
+    return {
+        files: {
+            ...files,
+            "src/server.ts": a2aServerTs(system, clientCodes, usesStdio),
+            "package.json": a2aPackageJson(gem.name),
+            "SECRETS.md": a2aSecretsMd(gem.requiredSecrets),
+        },
+        skipped,
+    };
+};
 // ── targets compose the shared renderers (convergence is literal, not duplicated) ──
 export const TARGET_REGISTRY = {
     claude: { id: "claude", label: "Claude", skill: skillSkillMd, instructions: instructionsClaudeMd, mcp: mcpDotMcpJson, hook: hooksSettingsJson },
@@ -506,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 },
@@ -516,6 +767,9 @@ export const TARGET_REGISTRY = {
     // AgentCore harness project (app/<gem>/harness.json + container-baked skills). Instructions/MCP
     // fold into the composed harness.json; stdio MCP is reported skipped by compose; hooks unsupported.
     agentcore: { id: "agentcore", label: "AgentCore", skill: skillAgentcoreMd, instructions: () => ({}), mcp: () => ({ files: {}, skipped: [] }), compose: agentcoreComposeProject },
+    // A2A Agent Card primitive. Wholly compose-driven (all per-type renderers no-op); compose emits the
+    // runtime-free agent-card.json. Card-only mode reports nothing skipped.
+    a2a: { id: "a2a", label: "A2A", skill: () => ({}), instructions: () => ({}), mcp: () => ({ files: {}, skipped: [] }), hook: () => ({}), compose: a2aComposeProject },
 };
 export function materialize(gem, target, opts = {}) {
     const spec = TARGET_REGISTRY[target];
@@ -535,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");
@@ -561,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/testbedFlavors.js

@@ -133,6 +133,7 @@ export function discoverProjects(dirs) {
         }
     }
     return [...best.values()]
+        .filter((p) => !p.path.includes("/.agentgem/")) // hide agentgem's own internal workspaces (e.g. the analysis cwd)
         .sort((a, b) => b.lastUsedMs - a.lastUsedMs)
         .map((p) => ({
         path: p.path,

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 });