@ninemind/agentgem 0.1.1 → 0.3.0

package/dist/schemas.js

@@ -34,11 +34,24 @@ export const HookArtifactSchema = z.object({
     source: z.string().optional(),
     secretRefs: z.array(z.object({ name: z.string(), location: z.string() })).optional(),
 });
+export const ChannelPlatformSchema = z.enum(["slack", "telegram", "discord", "teams", "twilio", "github"]);
+export const ChannelArtifactSchema = z.object({
+    type: z.literal("channel"),
+    name: z.string(),
+    platform: ChannelPlatformSchema,
+    secretRefs: z.array(z.object({ name: z.string(), location: z.string() })),
+    description: z.string().optional(),
+});
+// Declared channels on a request body. Shared by every endpoint that builds a Gem from a selection
+// (gem preview, materialize, archive, create-workspace, publish) so channels are never dropped on one
+// path while present on another. Each platform entry becomes a channel artifact via buildGem.
+export const ChannelDeclSchema = z.array(z.object({ platform: ChannelPlatformSchema, name: z.string().optional() })).optional();
 export const GemArtifactSchema = z.discriminatedUnion("type", [
     SkillArtifactSchema,
     McpServerArtifactSchema,
     InstructionsArtifactSchema,
     HookArtifactSchema,
+    ChannelArtifactSchema,
 ]);
 export const SecretRequirementSchema = z.object({
     name: z.string(),
@@ -105,25 +118,48 @@ export const GemSelectionSchema = z.union([
         projects: ProjectSelectionSchema.optional(),
     }),
 ]);
+// A draft skill distilled from the builtin procedure (proposal §2). status is
+// always "draft" — never installed by this pipeline. Defined before the build
+// request schemas that reference it (module load order).
+export const DistilledSkillSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    triggers: z.array(z.string()),
+    tools: z.array(z.string()),
+    mutating: z.boolean(),
+    body: z.string(),
+    evidence: z.object({
+        sessions: z.number(),
+        exampleSequence: z.array(z.string()),
+        root: z.string(),
+    }),
+    status: z.literal("draft"),
+    confidence: z.enum(["high", "medium", "low"]),
+});
 export const GemRequestSchema = z.object({
     selection: GemSelectionSchema,
     name: z.string().optional(),
     dir: z.string().optional(),
     projects: z.array(z.string()).optional(),
     checks: z.array(GemCheckSchema).optional(),
+    channels: ChannelDeclSchema,
+    // Accepted distilled drafts to fold into the build — staged into the inventory
+    // (by evidence.root) before resolution, so a selection can reference one by name.
+    distilledDrafts: z.array(DistilledSkillSchema).optional(),
 });
 export const ScaffoldChecksRequestSchema = z.object({
     selection: GemSelectionSchema,
     name: z.string().optional(),
     dir: z.string().optional(),
     projects: z.array(z.string()).optional(),
+    distilledDrafts: z.array(DistilledSkillSchema).optional(),
 });
 export const ScaffoldChecksResponseSchema = z.object({ checks: z.array(GemCheckSchema) });
 const TARGET_IDS = Object.keys(TARGET_REGISTRY);
 export const TargetIdSchema = z.enum(TARGET_IDS);
 export const SkippedArtifactSchema = z.object({
     artifact: z.string(),
-    type: z.enum(["skill", "mcp_server", "instructions", "hook"]),
+    type: z.enum(["skill", "mcp_server", "instructions", "hook", "channel"]),
     reason: z.string(),
 });
 export const MaterializeResponseSchema = z.object({
@@ -140,7 +176,7 @@ export const GemLockSchema = z.object({
     signature: z.string().nullable(),
 });
 export const GemManifestArtifactSchema = z.object({
-    type: z.enum(["skill", "mcp_server", "instructions", "hook"]),
+    type: z.enum(["skill", "mcp_server", "instructions", "hook", "channel"]),
     name: z.string(),
     path: z.string(),
     description: z.string().optional(),
@@ -162,24 +198,31 @@ export const ArchiveRequestSchema = z.object({
     dir: z.string().optional(),
     projects: z.array(z.string()).optional(),
     outDir: z.string().optional(), // when set, write the tree here and return its path
+    outFile: z.string().optional(), // when set, write one portable .gem (tar.gz) here
     tar: z.boolean().optional(), // when true, also return the tree as a base64 .tar.gz
+    channels: ChannelDeclSchema,
 });
 export const ArchiveResponseSchema = z.object({
     files: z.record(z.string(), z.string()),
     lock: GemLockSchema,
     skipped: z.array(SkippedArtifactSchema),
     path: z.string().nullable(),
+    gemFile: z.string().nullable(), // path to the written .gem when `outFile` was set, else null
     tarGz: z.string().nullable(), // base64 .tar.gz when `tar` was requested, else null
 });
 export const MaterializeRequestSchema = z.object({
     selection: GemSelectionSchema.optional(),
     archivePath: z.string().optional(),
+    gemPath: z.string().optional(), // install from a single .gem (tar.gz) file on disk
+    gemUrl: z.string().optional(), // install from a .gem fetched over http(s)
     target: TargetIdSchema,
     name: z.string().optional(),
     dir: z.string().optional(),
     projects: z.array(z.string()).optional(),
-}).refine((d) => d.selection !== undefined || d.archivePath !== undefined, {
-    message: "provide either selection or archivePath",
+    a2aServer: z.boolean().optional(), // a2a target: also emit the runnable server, not just the Agent Card
+    channels: ChannelDeclSchema, // applied only when building from `selection` (ignored for archive/gem sources)
+}).refine((d) => d.selection !== undefined || d.archivePath !== undefined || d.gemPath !== undefined || d.gemUrl !== undefined, {
+    message: "provide one of selection, archivePath, gemPath, or gemUrl",
 });
 export const DeployTargetIdSchema = z.enum(deployTargetIds);
 export const DeployReadyQuerySchema = z.object({ target: DeployTargetIdSchema.optional() });
@@ -193,6 +236,7 @@ export const PublishPreviewRequestSchema = z.object({
     dir: z.string().optional(),
     projects: z.array(z.string()).optional(),
     target: DeployTargetIdSchema.optional(),
+    channels: ChannelDeclSchema,
 });
 export const PublishRequestSchema = PublishPreviewRequestSchema.extend({ requestId: z.string().min(8).max(128), wsName: z.string().optional() });
 const ManagedAgentPayloadSchema = z.object({
@@ -236,6 +280,41 @@ export const PublishResultSchema = z.discriminatedUnion("kind", [ManagedAgentRes
 export const DirQuerySchema = z.object({ dir: z.string().optional(), projects: z.string().optional() });
 export const PickQuerySchema = z.object({});
 export const PickFolderSchema = z.object({ path: z.string().nullable() });
+// ── Workflow-aware Gem recommendation ──
+export const WorkflowAnalyzeRequestSchema = z.object({
+    dir: z.string().optional(), // .claude dir (resolveDirs handles the default)
+    root: z.string(), // the project root to analyze (one of the discovered cwds)
+});
+const RecommendedItemSchema = z.object({
+    // mirrors ArtifactType (incl. "channel") — RecommendedItem.type is ArtifactType, so this must stay in sync
+    type: z.enum(["skill", "mcp_server", "instructions", "hook", "channel"]),
+    name: z.string(),
+    reason: z.string(),
+    root: z.string().nullable(), // project root, or null for a global/plugin artifact
+});
+// One candidate Gem, carrying its own ready-to-POST GemSelection.
+const GemCandidateSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    root: z.string(),
+    includeInstructions: z.boolean(),
+    include: z.array(RecommendedItemSchema),
+    confidence: z.enum(["high", "medium", "low"]),
+    selection: z.record(z.string(), z.unknown()), // a GemSelection; buildGem validates structurally at /api/gem
+});
+export const WorkflowAnalyzeResponseSchema = z.object({
+    candidates: z.array(GemCandidateSchema),
+    gaps: z.array(z.string()), // project-level: used but absent from inventory
+    distilled: z.array(DistilledSkillSchema), // draft skills distilled from the builtin procedure
+    signalSummary: z.object({
+        sessionsScanned: z.number(),
+        spanDays: z.number(),
+        notes: z.array(z.string()),
+    }),
+    degraded: z.boolean(),
+});
+// Accept a distilled draft → write it to .agentgem/distilled/<name>/SKILL.md.
+export const WorkflowDraftWriteResponseSchema = z.object({ path: z.string() });
 export const GemSchema = z.object({
     name: z.string(),
     createdFrom: z.string(),
@@ -268,9 +347,10 @@ export const CreateWorkspaceRequestSchema = z.object({
     dir: z.string().optional(),
     projects: z.array(z.string()).optional(),
     version: z.string().optional(),
+    channels: ChannelDeclSchema,
 });
 export const WorkspaceQuerySchema = z.object({ name: z.string() });
-export const RenderRequestSchema = z.object({ name: z.string(), target: TargetIdSchema });
+export const RenderRequestSchema = z.object({ name: z.string(), target: TargetIdSchema, a2aServer: z.boolean().optional() });
 export const WorkspaceNameRequestSchema = z.object({ name: z.string() });
 export const ListWorkspacesResponseSchema = z.object({ workspaces: z.array(WorkspaceSummarySchema) });
 export const DeleteWorkspaceResponseSchema = z.object({ deleted: z.string() });
@@ -337,7 +417,8 @@ export const TestbedImportRequestSchema = z.object({
     flavor: TestbedFlavorIdSchema.optional(),
 });
 export const ImportedRefSchema = z.object({
-    type: z.enum(["skill", "mcp_server", "instructions", "hook"]),
+    // mirrors ArtifactType (incl. "channel") — ImportedRef.type is ArtifactType, so this must stay in sync
+    type: z.enum(["skill", "mcp_server", "instructions", "hook", "channel"]),
     name: z.string(),
     overwritten: z.boolean(),
 });
@@ -345,6 +426,74 @@ export const TestbedImportResponseSchema = z.object({
     written: z.array(ImportedRefSchema),
     skipped: z.array(z.object({ artifact: z.string(), reason: z.string() })),
 });
+// ── Run a Gem with a local ACP coding agent ──
+export const ToolInvocationSchema = z.object({
+    toolCallId: z.string(),
+    title: z.string(),
+    kind: z.string().optional(),
+    status: z.string().optional(),
+});
+export const RunResultSchema = z.object({
+    text: z.string(),
+    toolCalls: z.array(ToolInvocationSchema),
+});
+export const GemRunOutcomeSchema = z.object({
+    ok: z.boolean(),
+    error: z.string().optional(),
+    result: RunResultSchema,
+    sandbox: z.object({ backend: z.string(), isolated: z.boolean() }),
+});
+export const GemExpectationsSchema = z.object({
+    expectTools: z.array(z.string()).optional(),
+    expectText: z.string().optional(),
+    forbidToolFailures: z.boolean().optional(),
+});
+export const VerificationReportSchema = z.object({
+    passed: z.boolean(),
+    checks: z.array(z.object({ name: z.string(), passed: z.boolean(), detail: z.string() })),
+});
+export const GemRunRequestSchema = z.object({
+    // The Gem: either a built selection (like /materialize) or a .gem archive dir.
+    selection: GemSelectionSchema.optional(),
+    archivePath: z.string().optional(),
+    name: z.string().optional(),
+    dir: z.string().optional(), // introspect home (selection mode), like /materialize
+    projects: z.array(z.string()).optional(),
+    task: z.string(),
+    // runDir is intentionally NOT accepted from the client: a caller-controlled path is a path-injection
+    // sink (and the agent runs there with tool permissions). The server always derives it under
+    // AGENTGEM_HOME from the gem name. See gem.controller runGem/prepareGemRun.
+    agent: z.enum(["claude", "codex"]).optional(), // which local ACP adapter to drive
+    expectations: GemExpectationsSchema.optional(),
+}).refine((d) => d.selection !== undefined || d.archivePath !== undefined, {
+    message: "provide either selection or archivePath",
+});
+export const GemRunResponseSchema = z.object({
+    dir: z.string(),
+    agent: z.string(),
+    materialized: TestbedImportResponseSchema,
+    run: GemRunOutcomeSchema,
+    verification: VerificationReportSchema.optional(),
+});
+// Streaming split: prepare (POST, carries the selection) materializes and hands
+// back an opaque runId; the GET stream then runs it with simple query params.
+export const GemRunPrepareRequestSchema = z.object({
+    selection: GemSelectionSchema.optional(),
+    archivePath: z.string().optional(),
+    name: z.string().optional(),
+    dir: z.string().optional(),
+    projects: z.array(z.string()).optional(),
+    // runDir is intentionally NOT accepted from the client (see GemRunRequestSchema). Server-derived only.
+    agent: z.enum(["claude", "codex"]).optional(),
+}).refine((d) => d.selection !== undefined || d.archivePath !== undefined, {
+    message: "provide either selection or archivePath",
+});
+export const GemRunPrepareResponseSchema = z.object({
+    runId: z.string(),
+    runDir: z.string(),
+    agent: z.string(),
+    materialized: TestbedImportResponseSchema,
+});
 // ── AgentCore deploy (Phase 2) ──
 export const AgentcoreReadyResponseSchema = z.object({ cli: z.boolean(), awsCreds: z.boolean() });
 export const AgentcoreDeployRequestSchema = z.object({ name: z.string() });
@@ -357,14 +506,35 @@ export const AgentcoreDeployStateSchema = z.object({
 // ── Gem Registry ──
 export const RegistryReadyResponseSchema = z.object({ ready: z.boolean() });
 const RegistryItemVersionSchema = z.object({ path: z.string(), gemDigest: z.string(), dependencies: z.array(z.string()) });
+const RegistryItemDiscoverySchema = z.object({
+    description: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    author: z.string().optional(),
+    artifactKinds: z.array(z.string()).optional(),
+    updatedAt: z.string().optional(),
+});
 export const RegistryIndexResponseSchema = z.object({
     formatVersion: z.number(),
-    items: z.record(z.string(), z.object({ latest: z.string(), versions: z.record(z.string(), RegistryItemVersionSchema) })),
+    items: z.record(z.string(), z.object({ latest: z.string(), versions: z.record(z.string(), RegistryItemVersionSchema), discovery: RegistryItemDiscoverySchema.optional() })),
+});
+export const RegistrySearchQuerySchema = z.object({
+    q: z.string().optional(),
+    kind: z.string().optional(),
+    tag: z.string().optional(),
+    limit: z.coerce.number().int().positive().max(100).optional(),
+});
+export const RegistrySearchResponseSchema = z.object({
+    results: z.array(z.object({
+        key: z.string(), latest: z.string(), score: z.number(),
+        description: z.string().optional(), tags: z.array(z.string()).optional(),
+        author: z.string().optional(), artifactKinds: z.array(z.string()).optional(), updatedAt: z.string().optional(),
+    })),
 });
 export const RegistryResolveRequestSchema = z.object({
     refs: z.array(z.string()).min(1),
     mode: z.enum(["materialize", "workspace"]),
     target: TargetIdSchema.optional(),
+    a2aServer: z.boolean().optional(),
 });
 const InstallPlanSchema = z.object({
     items: z.array(z.object({ key: z.string(), version: z.string() })),
@@ -383,6 +553,7 @@ export const RegistryInstallRequestSchema = z.object({
     target: TargetIdSchema.optional(),
     dest: z.string().optional(),
     workspaceName: z.string().optional(),
+    a2aServer: z.boolean().optional(),
 });
 export const RegistryInstallResponseSchema = z.object({
     plan: InstallPlanSchema,
@@ -397,6 +568,8 @@ export const RegistryPublishRequestSchema = z.object({
     name: z.string().optional(),
     version: z.string(),
     dependencies: z.array(z.string()).optional(),
+    description: z.string().optional(), // discovery metadata for search
+    tags: z.array(z.string()).optional(),
 });
 export const RegistryPublishResponseSchema = z.object({
     ref: z.string(), version: z.string(), gemDigest: z.string(), commit: z.string(), path: z.string(),

package/dist/workflowStream.js

@@ -0,0 +1,78 @@
+// src/workflowStream.ts
+//
+// SSE endpoint for the workflow analysis. agentgem's decorator framework returns
+// a single JSON body, so streaming progress (scan → agent token stream → done)
+// is served by a raw Express handler registered on `server.expressApp`. The
+// non-streaming POST /api/workflow/analyze stays for programmatic/test callers.
+import { introspectConfig, introspectProject } from "./gem/introspect.js";
+import { resolveDirs, resolveProject } from "./resolveDir.js";
+import { claudeTranscriptsForCwd, scanWorkflow } from "./gem/workflowScan.js";
+import { recommendWorkflow, recommendationToSelection } from "./gem/acpRecommender.js";
+import { distillWorkflow } from "./gem/distill.js";
+import { transcriptToken, readAnalysisCache, writeAnalysisCache } from "./gem/analysisCache.js";
+export async function streamWorkflowAnalyze(req, res) {
+    const root = typeof req.query.root === "string" ? req.query.root : "";
+    const dir = typeof req.query.dir === "string" ? req.query.dir : undefined;
+    const fresh = req.query.fresh === "1"; // bypass the cache (Re-analyze)
+    res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache, no-transform",
+        Connection: "keep-alive",
+        "X-Accel-Buffering": "no", // disable proxy buffering so events flush immediately
+    });
+    const send = (event, data) => {
+        res.write(`event: ${event}\n`);
+        res.write(`data: ${JSON.stringify(data)}\n\n`);
+    };
+    try {
+        if (!root) {
+            send("failed", { message: "missing root" });
+            return;
+        }
+        const dirs = resolveDirs(dir);
+        const project = introspectProject(resolveProject(root));
+        const globalInv = introspectConfig(dirs); // global + plugin artifacts
+        const scanInv = { project, global: { skills: globalInv.skills, mcpServers: globalInv.mcpServers, hooks: globalInv.hooks } };
+        send("phase", { phase: "scanning" });
+        const paths = claudeTranscriptsForCwd(dirs.claudeDir, root);
+        // Cache hit (unless Re-analyze): return the prior result instantly so the
+        // user can revisit a project to pick another candidate without re-running
+        // the agent. Token invalidates when sessions are added/updated.
+        const token = transcriptToken(paths);
+        if (!fresh) {
+            const cached = readAnalysisCache(root, token);
+            if (cached) {
+                send("done", { ...cached, cached: true });
+                return;
+            }
+        }
+        const signal = scanWorkflow(paths, scanInv, { retainSequences: true });
+        send("phase", { phase: "scanned", transcripts: paths.length, sessions: signal.sessions.scanned });
+        send("phase", { phase: "thinking" });
+        // Selective recommendation streams its tokens; distillation runs concurrently
+        // but SILENT — two delta streams would interleave and garble the display
+        // (proposal §5). Both never throw, so wall-clock is max(...), not the sum.
+        const [{ analysis, degraded }, distill] = await Promise.all([
+            recommendWorkflow(signal, scanInv, { onDelta: (chunk) => send("delta", { text: chunk }) }),
+            distillWorkflow(signal, scanInv),
+        ]);
+        send("phase", { phase: "validating" });
+        const candidates = analysis.candidates.map((c) => ({ ...c, selection: recommendationToSelection(c) }));
+        const payload = {
+            candidates,
+            gaps: analysis.gaps,
+            distilled: distill.distilled,
+            signalSummary: { sessionsScanned: signal.sessions.scanned, spanDays: signal.sessions.spanDays, notes: signal.notes },
+            degraded,
+        };
+        if (!degraded)
+            writeAnalysisCache(root, token, payload, Date.now()); // don't cache fallbacks
+        send("done", { ...payload, cached: false });
+    }
+    catch (err) {
+        send("failed", { message: err?.message ?? String(err) });
+    }
+    finally {
+        res.end();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninemind/agentgem",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "A local web UI that introspects your coding-agent config, redacts secrets at capture, and builds a portable, composable Gem.",
   "license": "MIT",
   "bin": {
@@ -39,7 +39,7 @@
   "type": "module",
   "packageManager": "pnpm@10.29.2",
   "scripts": {
-    "build": "tsc -b && mkdir -p dist/public && cp src/public/index.html dist/public/index.html",
+    "build": "tsc -b && node scripts/copy-public.mjs",
     "dev": "pnpm build && node dist/index.js",
     "start": "node dist/index.js",
     "build:site": "node website/build.mjs",
@@ -54,17 +54,22 @@
     "@agentback/openapi": "^0.5.2",
     "@agentback/rest": "^0.5.2",
     "@agentback/rest-explorer": "^0.5.2",
+    "@agentclientprotocol/sdk": "^0.28.1",
     "@anthropic-ai/sdk": "^0.104.2",
     "@aws-sdk/client-bedrock-agentcore-control": "^3.1073.0",
     "dotenv": "^17.4.2",
     "tslib": "^2.8.1",
+    "undici": "^6.27.0",
     "vercel": "^54.14.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^24",
     "@types/supertest": "^6",
+    "eve": "^0.15.0",
+    "highlight.js": "^11.11.1",
     "marked": "^18.0.5",
+    "marked-highlight": "^2.2.4",
     "supertest": "^7",
     "typescript": "^6",
     "vitest": "^3"