@mhingston5/conduit 1.0.0

package/.env.example

@@ -0,0 +1,13 @@
+# Server Configuration
+PORT=3000
+LOG_LEVEL=info
+NODE_ENV=development
+
+# Security
+# Set this to a secure secret for production
+IPC_BEARER_TOKEN=change_me_to_a_secure_token
+
+# Upstream Configuration Examples
+# GITHUB_MCP_URL=http://localhost:8080/mcp
+# GITHUB_CLIENT_ID=...
+# GITHUB_CLIENT_SECRET=...

package/.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.8.0
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24.x
+          cache: 'pnpm'
+      
+      - name: Install build dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y python3 make g++
+      
+      - name: Setup Deno
+        uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+      
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Rebuild native modules
+        env:
+          PYTHON: python3
+        run: |
+          # Force rebuild isolated-vm which sometimes fails to build automatically
+          # Find the directory and build it
+          find node_modules/.pnpm -name "isolated-vm" -type d -exec bash -c 'cd "$0" && npm install --build-from-source' {} \;
+          # Also run general rebuild just in case
+          pnpm rebuild --recursive
+      
+      - name: Run tests
+        run: pnpm test
+      
+      - name: Build
+        run: pnpm build
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.8.0
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24.x
+          cache: 'pnpm'
+      
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      
+      - name: Rebuild native modules
+        env:
+          PYTHON: python3
+        run: |
+          find node_modules/.pnpm -name "isolated-vm" -type d -exec bash -c 'cd "$0" && npm install --build-from-source' {} \;
+          pnpm rebuild --recursive
+      
+      - name: Check TypeScript
+        run: pnpm exec tsc --noEmit

package/.github/workflows/pr-checks.yml

@@ -0,0 +1,90 @@
+name: PR Checks
+
+on:
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  validate:
+    name: Validate PR
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.8.0
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24.x
+          cache: 'pnpm'
+      
+      - name: Setup Deno
+        uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+      
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Rebuild native modules
+        env:
+          PYTHON: python3
+        run: |
+          find node_modules/.pnpm -name "isolated-vm" -type d -exec bash -c 'cd "$0" && npm install --build-from-source' {} \;
+          pnpm rebuild --recursive
+      
+      - name: Run tests
+        run: pnpm test
+      
+      - name: Build
+        run: pnpm build
+      
+      - name: Check TypeScript
+        run: pnpm exec tsc --noEmit
+      
+      - name: Check for uncommitted changes
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "Error: Found uncommitted changes after build"
+            git status --porcelain
+            exit 1
+          fi
+
+  size-check:
+    name: Bundle Size Check
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.8.0
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24.x
+          cache: 'pnpm'
+      
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      
+      - name: Build
+        run: pnpm build
+      
+      - name: Check bundle size
+        run: |
+          echo "Bundle size:"
+          du -sh dist/
+          find dist/ -name "*.js" -exec du -h {} \; | sort -h

package/.tool-versions

@@ -0,0 +1,2 @@
+nodejs 24.0.0
+deno 2.0.0

package/README.md

@@ -0,0 +1,177 @@
+<div align="center">
+  <img src="./logo.png" alt="Conduit Logo" width="400"/>
+</div>
+
+# Conduit
+
+<div align="center">
+
+[![npm version](https://badge.fury.io/js/@mhingston5%2Fconduit.svg)](https://www.npmjs.com/package/@mhingston/conduit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js Version](https://img.shields.io/badge/node-24-brightgreen.svg)](https://nodejs.org/)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io/)
+
+</div>
+
+## What is Conduit?
+
+Conduit is a **secure Code Mode execution substrate** for [MCP](https://modelcontextprotocol.io/) agents.
+
+It lets agents:
+- generate **real TypeScript or Python code**
+- call tools via **language-native APIs** (`tools.github.createIssue()`)
+- run that code in **isolated, resource-governed sandboxes**
+- without exposing credentials or the host environment
+
+Conduit is optimized for:
+- [Code Mode](./docs/CODE_MODE.md) (not JSON tool calling)
+- composable multi-tool execution
+- strict safety, limits, and observability
+
+## What Conduit Is Not
+
+- ❌ A general-purpose script runner
+- ❌ An LLM gateway or provider abstraction
+- ❌ A plugin UI or agent framework
+- ❌ A long-lived compute environment
+
+Conduit executes **short-lived, isolated programs** with explicit limits.
+
+---
+
+## Installation
+
+```bash
+npm install @mhingston5/conduit
+```
+
+## 5-Minute Quick Start (Code Mode)
+
+### 1. Start Conduit
+```bash
+pnpm install
+# Build the project
+npm run build
+# Start the server
+node dist/index.js
+```
+
+### 2. Register an upstream MCP server
+
+Create a `conduit.yaml` in the root:
+```yaml
+upstreams:
+  - id: github
+    type: http
+    url: "http://localhost:3000/mcp"
+    # Or use local stdio for testing:
+  - id: filesystem
+    type: stdio
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+```
+
+### 3. Execute TypeScript
+
+Using any [MCP Client](https://modelcontextprotocol.io/clients) (Claude Desktop, etc.), call `mcp.executeTypeScript`:
+
+```ts
+// The agent writes this code:
+const result = await tools.filesystem.list_allowed_directories();
+console.log("Files:", result);
+```
+
+### 4. Result
+
+Conduit runs the code, handles the tool call securely, and returns:
+
+```json
+{
+  "stdout": "Files: ['/tmp']\n",
+  "stderr": "",
+  "exitCode": 0
+}
+```
+
+---
+
+## How It Works (High Level)
+
+```
+LLM → generates code  
+↓  
+Client → sends code to Conduit  
+↓  
+Conduit:
+- injects a `tools.*` SDK
+- enforces limits + allowlists
+- runs code in an isolated runtime (Deno / Pyodide / Isolate)
+↓  
+Tools are called via the Gateway  
+↓  
+Results returned as stdout / stderr
+```
+
+For implementation details, see [Architecture](./docs/ARCHITECTURE.md).
+
+---
+
+## Security & Isolation Guarantees
+
+Each execution:
+- runs in a fresh sandbox (no state reuse)
+- has strict CPU, memory, output, and log limits
+- cannot access host credentials or filesystem
+- can only call explicitly allowed tools
+- is forcibly terminated on violation
+
+**SSRF protection**:
+- private IP ranges blocked
+- DNS rebinding prevented
+- IPv6-mapped IPv4 handled
+
+**Secrets**:
+- never injected into user code
+- redacted from logs by default
+
+See [Security](./docs/SECURITY.md) for the full threat model.
+
+---
+
+## Strict vs Permissive Tool Validation
+
+By default, Conduit runs in **Permissive Mode** to allow easy exploration.
+
+**Strict mode**:
+- blocks unknown tools
+- blocks tools without schemas
+- enforces argument validation
+
+**Recommended**:
+- permissive mode for exploration
+- strict mode for production agents
+
+---
+
+## Design Principles
+
+- **Code over configuration**: Logic belongs in code, not yaml.
+- **Isolation over reuse**: Every execution is fresh.
+- **Explicit limits over best-effort**: Fail fast if limits are breached.
+- **SDKs over RPC**: Agents should write code against libraries, not protocols.
+
+---
+
+## Advanced Documentation
+
+- [Architecture](./docs/ARCHITECTURE.md) - Internals, IPC, Executors
+- [Security](./docs/SECURITY.md) - Threat model, specific mitigations
+- [Code Mode Philosophy](./docs/CODE_MODE.md) - Why we generate code
+
+## Note on Unix Sockets
+
+When using Unix domain sockets (`path` in configuration), Conduit does not automatically `unlink` the socket file on startup. It is recommended to ensure the socket path is cleaned up by the deployment environment or startup script to avoid `EADDRINUSE` errors.
+
+## License
+MIT

package/conduit.yaml.test

@@ -0,0 +1,3 @@
+port: ${TEST_PORT:-5555}
+envTest: ${TEST_ENV}
+

package/docs/ARCHITECTURE.md

@@ -0,0 +1,35 @@
+# Conduit Architecture
+
+Conduit is built with a modular architecture, designed to be secure, observable, and composable.
+
+## Core Components
+
+- **`src/core`**: Core services (Config, Logger, Concurrency, Ops, Request Dispatching).
+- **`src/executors`**: Secure runtime environments for code execution.
+- **`src/gateway`**: Upstream client management, auth (OAuth2/API Keys), and schema caching.
+- **`src/transport`**: Network abstraction layer.
+- **`src/sdk`**: SDK generation for typed tool bindings.
+
+## Detailed Flow
+
+1. **Client Request**: A client (like VS Code or Claude Desktop) sends a JSON-RPC request (`mcp.executeTypeScript`).
+2. **Transportation**: The request is received via `SocketTransport` (TCP/UDS/Pipe).
+3. **Dispatch**: `RequestController` validates the request and session tokens.
+4. **Tool Discovery**: `GatewayService` aggregates tools from all upstream MCP servers.
+5. **SDK Generation**: The `SdkService` generates a type-safe SDK (`tools.*`) based on discovered schemas.
+6. **Execution**:
+    - **Deno**: Spawns a Deno subprocess with limited permissions.
+    - **Browser-style (In-Process)**: Uses `isolated-vm` for high-speed JS logic.
+    - **Python**: Uses Pyodide in a worker thread.
+7. **Result**: Stdout/stderr and return values are captured and returned to the client.
+
+## IPC & Transport
+
+Conduit supports multiple transports:
+- **TCP**: Standard network sockets.
+- **Unix Domain Sockets**: For local IPC.
+- **Windows Named Pipes**: For local IPC on Windows.
+
+## Schema Caching
+
+To optimize performance, upstreams are polled for tool schemas, which are cached with a TTL. This prevents repeated network calls during high-frequency execution loops.

package/docs/CODE_MODE.md

@@ -0,0 +1,33 @@
+# Code Mode Philosophy
+
+Conduit is built for **Code Mode**.
+
+## What is Code Mode?
+
+"Code Mode" is an architectural pattern for AI Agents where:
+- **LLMs generate code**, not JSON tool calls.
+- **Tools are libraries**, not RPC endpoints.
+- **Execution is sandboxed**, not local.
+
+Reference: [Cloudflare Code Mode](https://developers.cloudflare.com/agents/code-mode/)
+
+## Why Code Mode?
+
+### 1. Context Efficiency (98% Reduction)
+Traditional "Tool Use" requires pasting typically huge JSON schemas for every available tool into the LLM system prompt.
+In Code Mode, you paste **0 schemas**. The agent writes code to *discover* tools dynamically at runtime, or assumes standard SDK shapes.
+
+### 2. Composition & Logic
+Agent logic (loops, conditionals, retries, variable transformations) happens **in the code**, not in the LLM's context window.
+- **Old Way**: LLM -> Tool Call -> LLM -> Tool Call -> LLM -> Result
+- **Code Mode**: LLM -> `for (item in items) { await tool(item) }` -> Result
+
+### 3. Safety
+Because logic executes in a sandbox, you can enforce limits on loops, memory, and duration that are impossible to enforce on an LLM's token stream.
+
+## Implementation in Conduit
+
+Conduit provides:
+1. **`executeTypeScript` / `executePython`**: The entry points.
+2. **`tools.*` SDK**: A dynamically generated client injected into the runtime.
+3. **Sandboxes**: Deno, Pyodide, and isolated-vm to run the code safely.

package/docs/SECURITY.md

@@ -0,0 +1,52 @@
+# Security & Isolation Guarantees
+
+Conduit implements a defense-in-depth security model to ensure safe code execution.
+
+## Isolation Guarantees
+
+Each execution:
+- runs in a **fresh sandbox** (no state reuse).
+- has strict **CPU, memory, output, and log limits**.
+- cannot access **host credentials or filesystem** (unless explicitly allowed via tools).
+- can only call **explicitly allowed tools**.
+- is **forcibly terminated** on violation.
+
+## SSRF Protection
+
+Conduit enforces strict Server-Side Request Forgery (SSRF) protections on upstreams:
+- **Private IP ranges blocked** (unless explicitly allowed).
+- **DNS rebinding prevented** by verifying IP resolution before connection.
+- **IPv6-mapped IPv4** addresses are handled correctly.
+- **HTTP Redirects** are visually disabled or strictly validated.
+
+## Secrets Management
+
+- **Injection**: Secrets are never injected into user code as environment variables (unless via specific secure tool config).
+- **Redaction**: Logs are automatically scrubbed for known secrets and PII patterns.
+
+## Authorization
+
+- **Master Token**: Full access to all methods (set via `IPC_BEARER_TOKEN`).
+- **Session Tokens**: Generated per-execution, restricted to `mcp.discoverTools` and `mcp.callTool` only.
+- **Tool Allowlisting**: Per-request scope limits which tools code can discover/call (e.g., `["github.*"]`).
+
+## Runtime Security
+
+- **Deno**: Uses OS-level sandbox permissions (`--allow-net`, `--allow-read` are restricted).
+- **Pyodide**: Runs in a Worker Thread with no access to the main thread's DOM or context.
+- **In-Process JS (isolated-vm)**: Uses V8 isolates for memory isolation but shares the host process.
+
+## Production Hardening Recommendations
+
+While Conduit provides robust application-level sandboxing, `isolated-vm` and Deno subprocesses still share the host kernel. For **multi-tenant** or **hostile** workloads, you must implement defense-in-depth by wrapping Conduit itself.
+
+### Tiered Isolation Model
+
+| Component | Protection Against | Vulnerable To |
+|-----------|--------------------|---------------|
+| **Conduit (Code)** | Logical errors, resource exhaustion, unauthorized tool use | Runtime/V8 escapes, Kernel exploits |
+| **Container (Docker)** | Filesystem access, network enumeration | Kernel exploits, Container breakouts |
+| **MicroVM (Firecracker/gVisor)** | Kernel exploits, complete system compromise | Hypervisor exploits (rare) |
+
+**Recommendation:**
+For production deployments executing untrusted code, deploy Conduit inside a **gVisor-backed container** or a **Firecracker MicroVM** (like AWS Fargate or Fly.io Machines). This prevents a V8/Deno escape from compromising the host infrastructure.

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@mhingston5/conduit",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "A secure Code Mode execution substrate for MCP agents",
+  "main": "index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "tsup"
+  },
+  "keywords": [
+    "mcp",
+    "agent",
+    "sandbox",
+    "code-execution",
+    "typescript",
+    "python",
+    "isolation"
+  ],
+  "author": "Mark Hingston",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mhingston/conduit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mhingston/conduit/issues"
+  },
+  "homepage": "https://github.com/mhingston/conduit#readme",
+  "packageManager": "pnpm@10.8.0",
+  "engines": {
+    "node": "24.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.67.3",
+    "@opentelemetry/exporter-prometheus": "^0.208.0",
+    "@opentelemetry/instrumentation-pino": "^0.55.1",
+    "@opentelemetry/resources": "^2.2.0",
+    "@opentelemetry/sdk-node": "^0.208.0",
+    "@opentelemetry/semantic-conventions": "^1.38.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "axios": "^1.13.2",
+    "dotenv": "^17.2.3",
+    "fastify": "^5.6.2",
+    "isolated-vm": "^6.0.2",
+    "js-yaml": "^4.1.1",
+    "lru-cache": "^11.2.4",
+    "p-limit": "^7.2.0",
+    "pino": "^10.1.0",
+    "pyodide": "^0.29.0",
+    "uuid": "^13.0.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.0.3",
+    "@types/pino": "^7.0.5",
+    "@types/uuid": "^11.0.0",
+    "pino-pretty": "^13.1.3",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16",
+    "vitest-mock-extended": "^3.1.0"
+  }
+}

package/src/assets/deno-shim.ts

@@ -0,0 +1,93 @@
+// @ts-nocheck
+// Deno Shim for Conduit - Code Mode SDK
+const IPC_ADDRESS = '__CONDUIT_IPC_ADDRESS__';
+const IPC_TOKEN = '__CONDUIT_IPC_TOKEN__';
+
+async function sendIPCRequest(method: string, params: any) {
+    if (!IPC_ADDRESS) throw new Error('Conduit IPC address not configured');
+
+    let conn: any;
+    try {
+        if (IPC_ADDRESS.includes(':')) {
+            const lastColon = IPC_ADDRESS.lastIndexOf(':');
+            const hostname = IPC_ADDRESS.substring(0, lastColon);
+            const port = IPC_ADDRESS.substring(lastColon + 1);
+
+            // Normalize hostname for Deno connect
+            let targetHost = hostname.replace(/[\[\]]/g, '');
+            if (targetHost === '0.0.0.0' || targetHost === '::' || targetHost === '::1' || targetHost === '') {
+                targetHost = '127.0.0.1';
+            }
+
+            conn = await (Deno as any).connect({
+                hostname: targetHost,
+                port: Number(port)
+            });
+        } else {
+            conn = await (Deno as any).connect({ transport: 'unix', path: IPC_ADDRESS });
+        }
+    } catch (err: any) {
+        throw new Error(`Failed to connect to Conduit IPC (${IPC_ADDRESS}): ${err.message}`);
+    }
+
+    try {
+        const id = Math.random().toString(36).substring(7);
+        const request = {
+            jsonrpc: '2.0',
+            id,
+            method,
+            params: params || {},
+            auth: { bearerToken: IPC_TOKEN }
+        };
+
+        const encoder = new TextEncoder();
+        await conn.write(encoder.encode(JSON.stringify(request) + '\n'));
+
+        const decoder = new TextDecoder();
+        let buffer = '';
+        const chunk = new Uint8Array(2 * 1024 * 1024); // 2MB buffer for large tool returns
+
+        while (true) {
+            const n = await conn.read(chunk);
+            if (n === null) throw new Error('IPC connection closed by host before receiving response');
+
+            buffer += decoder.decode(chunk.subarray(0, n));
+            const lines = buffer.split('\n');
+            buffer = lines.pop() || ''; // Keep partial line
+
+            for (const line of lines) {
+                if (!line.trim()) continue;
+                try {
+                    const response = JSON.parse(line);
+                    if (response.id === id) {
+                        if (response.error) {
+                            const error = new Error(response.error.message);
+                            (error as any).code = response.error.code;
+                            (error as any).data = response.error.data;
+                            throw error;
+                        }
+                        return response.result;
+                    }
+                } catch (e: any) {
+                    if (e.message.includes('JSON')) continue;
+                    throw e;
+                }
+            }
+        }
+    } finally {
+        conn.close();
+    }
+}
+
+// Internal tool call function - used by generated SDK
+const __internalCallTool = async (name: string, params: any) => {
+    return await sendIPCRequest('mcp.callTool', { name, arguments: params });
+};
+
+// Tool discovery - still available for dynamic scenarios
+(globalThis as any).discoverMCPTools = async (options: any) => {
+    const result = await sendIPCRequest('mcp.discoverTools', options);
+    return result.tools || [];
+};
+
+// __CONDUIT_SDK_INJECTION__

package/src/assets/python-shim.py

@@ -0,0 +1,21 @@
+# Python Shim for Conduit - Code Mode SDK
+import asyncio
+
+async def discover_mcp_tools(options=None):
+    """Discover available MCP tools from the gateway."""
+    # These functions are injected into the Python global scope by the executor
+    res = await discover_mcp_tools_js(options)
+    # Pyodide's JS proxy handles conversion broadly, but we might need to convert the tools list
+    if hasattr(res, 'to_py'):
+        data = res.to_py()
+        return data.get('tools', []) if isinstance(data, dict) else []
+    return []
+
+async def _internal_call_tool(name, arguments):
+    """Internal tool call function - used by generated SDK."""
+    res = await call_mcp_tool_js(name, arguments)
+    if hasattr(res, 'to_py'):
+        return res.to_py()
+    return res
+
+# __CONDUIT_SDK_INJECTION__