@shardworks/claude-code-session-provider 0.1.23

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Sean Boots
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Claude Code Session Provider
+ *
+ * Implements the SessionProvider interface for Claude Code sessions.
+ * Handles both interactive (TUI) and autonomous (--print) modes.
+ *
+ * This is a platform dependency of the CLI, not a guild-registered engine.
+ * The CLI imports it at startup and registers it as the session provider.
+ * Guilds don't need to know about it — it's a transitive dep of @shardworks/nexus.
+ *
+ * Key design choice: uses async spawn() instead of spawnSync().
+ * This is required for stream-json transcript parsing, timeout enforcement,
+ * and future concurrent session support.
+ */
+import type { ResolvedTool } from '@shardworks/nexus-core';
+import type { McpServerConfig } from './mcp-server.ts';
+import type { SessionProvider } from '@shardworks/nexus-core';
+/**
+ * Generate the MCP server config for the resolved tool set.
+ *
+ * For tools with a `package` field in guild.json, the modulePath is the
+ * npm package name (resolved via NODE_PATH at runtime). For tools without
+ * a package field, the modulePath is an absolute path to the entry point.
+ */
+export declare function generateMcpConfig(home: string, tools: ResolvedTool[]): McpServerConfig;
+/**
+ * Claude Code session provider.
+ *
+ * Launches sessions via the `claude` CLI. Interactive mode inherits stdio;
+ * autonomous mode uses --print with optional --output-format stream-json.
+ */
+export declare const claudeCodeProvider: SessionProvider;
+export default claudeCodeProvider;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,wBAAwB,CAAC;AAC3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAuD,MAAM,wBAAwB,CAAC;AAInH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,YAAY,EAAE,GACpB,eAAe,CAqBjB;AA8CD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,eAsDhC,CAAC;AAsCF,eAAe,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,159 @@
+/**
+ * Claude Code Session Provider
+ *
+ * Implements the SessionProvider interface for Claude Code sessions.
+ * Handles both interactive (TUI) and autonomous (--print) modes.
+ *
+ * This is a platform dependency of the CLI, not a guild-registered engine.
+ * The CLI imports it at startup and registers it as the session provider.
+ * Guilds don't need to know about it — it's a transitive dep of @shardworks/nexus.
+ *
+ * Key design choice: uses async spawn() instead of spawnSync().
+ * This is required for stream-json transcript parsing, timeout enforcement,
+ * and future concurrent session support.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+// ── MCP Config Generation ──────────────────────────────────────────────
+/**
+ * Generate the MCP server config for the resolved tool set.
+ *
+ * For tools with a `package` field in guild.json, the modulePath is the
+ * npm package name (resolved via NODE_PATH at runtime). For tools without
+ * a package field, the modulePath is an absolute path to the entry point.
+ */
+export function generateMcpConfig(home, tools) {
+    const mcpTools = [];
+    for (const t of tools) {
+        if (t.package) {
+            mcpTools.push({ name: t.name, modulePath: t.package });
+        }
+        else {
+            const descriptorPath = path.join(t.path, 'nexus-tool.json');
+            if (!fs.existsSync(descriptorPath))
+                continue;
+            const descriptor = JSON.parse(fs.readFileSync(descriptorPath, 'utf-8'));
+            const entry = descriptor.entry;
+            mcpTools.push({ name: t.name, modulePath: path.join(t.path, entry) });
+        }
+    }
+    // Set NODE_PATH so the MCP server process can resolve npm-installed guild
+    // tools from the guildhall's node_modules, regardless of where the MCP
+    // engine code itself lives on disk.
+    const nodePath = path.join(home, 'node_modules');
+    return { home, tools: mcpTools, env: { NODE_PATH: nodePath } };
+}
+// ── Claude MCP Config ──────────────────────────────────────────────────
+/**
+ * Build the Claude MCP config JSON (mcpServers format) that launches the
+ * MCP server as a stdio process serving the anima's tools.
+ */
+function buildClaudeMcpConfig(tmpDir, mcpServerConfigPath, serverConfig) {
+    // Resolve the mcp-server entry point within this package
+    const mcpServerUrl = import.meta.resolve('./mcp-server.ts');
+    const mcpServerPath = fileURLToPath(mcpServerUrl);
+    // Write a wrapper script that imports and invokes main().
+    const wrapperPath = path.join(tmpDir, 'mcp-entry.mjs');
+    fs.writeFileSync(wrapperPath, `import { main } from ${JSON.stringify(mcpServerUrl)};\nawait main();\n`);
+    // In dev the resolved path is .ts source; add the transform flag.
+    const nodeArgs = [];
+    if (mcpServerPath.endsWith('.ts')) {
+        nodeArgs.push('--disable-warning=ExperimentalWarning', '--experimental-transform-types');
+    }
+    return {
+        mcpServers: {
+            'nexus-guild': {
+                command: 'node',
+                args: [...nodeArgs, wrapperPath, mcpServerConfigPath],
+                env: serverConfig.env ?? {},
+            },
+        },
+    };
+}
+// ── Session Provider ───────────────────────────────────────────────────
+/**
+ * Claude Code session provider.
+ *
+ * Launches sessions via the `claude` CLI. Interactive mode inherits stdio;
+ * autonomous mode uses --print with optional --output-format stream-json.
+ */
+export const claudeCodeProvider = {
+    name: 'claude-code',
+    async launch(options) {
+        const { home, manifest, prompt, interactive, cwd, name } = options;
+        const startTime = Date.now();
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nsg-session-'));
+        try {
+            // Generate MCP config from resolved tools
+            const mcpConfig = generateMcpConfig(home, manifest.tools);
+            const systemPromptPath = path.join(tmpDir, 'system-prompt.md');
+            const mcpServerConfigPath = path.join(tmpDir, 'mcp-server-config.json');
+            const claudeMcpConfigPath = path.join(tmpDir, 'claude-mcp-config.json');
+            fs.writeFileSync(systemPromptPath, manifest.systemPrompt);
+            fs.writeFileSync(mcpServerConfigPath, JSON.stringify(mcpConfig, null, 2));
+            fs.writeFileSync(claudeMcpConfigPath, JSON.stringify(buildClaudeMcpConfig(tmpDir, mcpServerConfigPath, mcpConfig), null, 2));
+            // Base args — shared between interactive and print modes
+            const args = [
+                '--bare',
+                '--setting-sources', 'user',
+                '--dangerously-skip-permissions',
+                '--system-prompt-file', systemPromptPath,
+                '--mcp-config', claudeMcpConfigPath,
+            ];
+            if (name) {
+                args.push('--name', name);
+            }
+            if (interactive) {
+                // Interactive: human at keyboard, inherit stdio
+                const exitCode = await spawnClaude(args, cwd, 'inherit');
+                const durationMs = Date.now() - startTime;
+                return { exitCode, durationMs };
+            }
+            else {
+                // Autonomous: commission spec / brief as prompt
+                args.push('--print', prompt ?? '');
+                // TODO Phase 4: add --output-format stream-json and parse transcript + metrics
+                const exitCode = await spawnClaude(args, cwd, 'pipe');
+                const durationMs = Date.now() - startTime;
+                return { exitCode, durationMs };
+            }
+        }
+        finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    },
+};
+/**
+ * Spawn the claude CLI process asynchronously.
+ *
+ * Uses child_process.spawn (not spawnSync) for:
+ * - Stream-json transcript parsing (future)
+ * - Timeout enforcement (future)
+ * - Concurrent session support (future)
+ *
+ * @param args - CLI arguments for claude
+ * @param cwd - Working directory for the process
+ * @param stdio - 'inherit' for interactive, 'pipe' for autonomous
+ * @returns Exit code (0 = success)
+ */
+function spawnClaude(args, cwd, stdio) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn('claude', args, {
+            cwd,
+            stdio: stdio === 'inherit'
+                ? 'inherit'
+                : ['pipe', 'inherit', 'inherit'],
+        });
+        proc.on('error', (err) => {
+            reject(new Error(`Failed to spawn claude: ${err.message}`));
+        });
+        proc.on('close', (code) => {
+            resolve(code ?? 1);
+        });
+    });
+}
+export default claudeCodeProvider;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server.d.ts

@@ -0,0 +1,60 @@
+/**
+ * MCP Server — serves guild tools as typed MCP tools during anima sessions.
+ *
+ * Absorbed from the former `engine-mcp-server` package. This is an internal
+ * module of claude-code-session-provider — not a separate package.
+ *
+ * The session provider launches this as a stdio process, configured with
+ * the set of tools the anima has access to (based on role gating).
+ *
+ * One process per session. All the anima's tools. Claude's runtime manages
+ * the lifecycle — spawns at session start, kills at session end.
+ *
+ * ## Usage
+ *
+ * The server reads a JSON config from a file path passed as argv[2]:
+ *
+ *   node mcp-server <config.json>
+ *
+ * Config shape:
+ *   {
+ *     "home": "/absolute/path/to/guild-root",
+ *     "tools": [
+ *       { "name": "install-tool", "modulePath": "@shardworks/nexus-stdlib/tools" },
+ *       { "name": "my-tool", "modulePath": "/absolute/path/to/handler.ts" }
+ *     ]
+ *   }
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** A single tool to load into the MCP server. */
+export interface ToolSpec {
+    /** Tool name — how the anima sees it. */
+    name: string;
+    /** Module path — package name (for framework tools) or absolute file path (for guild tools). */
+    modulePath: string;
+}
+/** Configuration for the MCP server. */
+export interface McpServerConfig {
+    /** Absolute path to the guild root. */
+    home: string;
+    /** Tools to register as MCP tools. */
+    tools: ToolSpec[];
+    /** Environment variables for the MCP server process. */
+    env?: Record<string, string>;
+}
+/**
+ * Create and configure an MCP server with the given tools.
+ *
+ * Each tool's Zod param schema is registered directly with the MCP SDK
+ * (which handles JSON Schema conversion). The handler is wrapped to inject
+ * the framework context and format the result as MCP tool output.
+ */
+export declare function createMcpServer(config: McpServerConfig): Promise<McpServer>;
+/**
+ * Entry point when run as a standalone process.
+ *
+ * Reads config from a JSON file (path passed as first argument),
+ * creates the MCP server, and connects via stdio transport.
+ */
+export declare function main(configPath?: string): Promise<void>;
+//# sourceMappingURL=mcp-server.d.ts.map

package/dist/mcp-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,iDAAiD;AACjD,MAAM,WAAW,QAAQ;IACvB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,gGAAgG;IAChG,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AA6BD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,CA0CjF;AAED;;;;;GAKG;AACH,wBAAsB,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAe7D"}

package/dist/mcp-server.js

@@ -0,0 +1,123 @@
+/**
+ * MCP Server — serves guild tools as typed MCP tools during anima sessions.
+ *
+ * Absorbed from the former `engine-mcp-server` package. This is an internal
+ * module of claude-code-session-provider — not a separate package.
+ *
+ * The session provider launches this as a stdio process, configured with
+ * the set of tools the anima has access to (based on role gating).
+ *
+ * One process per session. All the anima's tools. Claude's runtime manages
+ * the lifecycle — spawns at session start, kills at session end.
+ *
+ * ## Usage
+ *
+ * The server reads a JSON config from a file path passed as argv[2]:
+ *
+ *   node mcp-server <config.json>
+ *
+ * Config shape:
+ *   {
+ *     "home": "/absolute/path/to/guild-root",
+ *     "tools": [
+ *       { "name": "install-tool", "modulePath": "@shardworks/nexus-stdlib/tools" },
+ *       { "name": "my-tool", "modulePath": "/absolute/path/to/handler.ts" }
+ *     ]
+ *   }
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { VERSION, resolveToolFromExport } from '@shardworks/nexus-core';
+/**
+ * Load a tool definition from a module path.
+ *
+ * Handles both single-tool and array-of-tools exports:
+ * - Single: `export default tool({...})` → returned directly
+ * - Array: `export default [tool({...}), ...]` → resolved by spec.name
+ */
+async function loadTool(spec) {
+    try {
+        const mod = await import(__rewriteRelativeImportExtension(spec.modulePath));
+        const def = resolveToolFromExport(mod.default, spec.name);
+        if (!def) {
+            console.error(`[mcp-server] ${spec.name}: could not resolve tool from "${spec.modulePath}". ` +
+                `Module must export a tool() definition or an array of tool() definitions with matching names. Skipping.`);
+            return null;
+        }
+        return def;
+    }
+    catch (err) {
+        console.error(`[mcp-server] ${spec.name}: failed to load module "${spec.modulePath}":`, err);
+        return null;
+    }
+}
+/**
+ * Create and configure an MCP server with the given tools.
+ *
+ * Each tool's Zod param schema is registered directly with the MCP SDK
+ * (which handles JSON Schema conversion). The handler is wrapped to inject
+ * the framework context and format the result as MCP tool output.
+ */
+export async function createMcpServer(config) {
+    const server = new McpServer({
+        name: 'nexus-guild',
+        version: VERSION,
+    });
+    const context = { home: config.home };
+    for (const spec of config.tools) {
+        const def = await loadTool(spec);
+        if (!def)
+            continue;
+        // Register the tool as an MCP tool.
+        // The MCP SDK accepts Zod shapes directly — it handles JSON Schema conversion.
+        server.tool(spec.name, def.description, def.params.shape, async (params) => {
+            try {
+                // Validate params through Zod before passing to handler
+                const validated = def.params.parse(params);
+                const result = await def.handler(validated, context);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                        }],
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [{ type: 'text', text: `Error: ${message}` }],
+                    isError: true,
+                };
+            }
+        });
+    }
+    return server;
+}
+/**
+ * Entry point when run as a standalone process.
+ *
+ * Reads config from a JSON file (path passed as first argument),
+ * creates the MCP server, and connects via stdio transport.
+ */
+export async function main(configPath) {
+    const resolvedPath = configPath ?? process.argv[2];
+    if (!resolvedPath) {
+        console.error('Usage: nexus-mcp-server <config.json>');
+        process.exit(1);
+    }
+    const fs = await import('node:fs');
+    const configText = fs.readFileSync(resolvedPath, 'utf-8');
+    const config = JSON.parse(configText);
+    const server = await createMcpServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+//# sourceMappingURL=mcp-server.js.map

package/dist/mcp-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.js","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@shardworks/claude-code-session-provider",
+  "version": "0.1.23",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shardworks/nexus-mk2",
+    "directory": "packages/claude-code-session-provider"
+  },
+  "description": "Claude Code session provider — launches claude sessions with MCP tool serving",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.27.1",
+    "zod": "4.3.6",
+    "@shardworks/nexus-core": "0.1.23"
+  },
+  "devDependencies": {
+    "@types/node": "25.5.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --disable-warning=ExperimentalWarning --experimental-transform-types --test 'src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  }
+}