@crewx/sdk 0.8.0-rc.73 → 0.8.0-rc.75

package/dist/esm/remote/types.js

@@ -0,0 +1,8 @@
+/**
+ * Remote Agent Module — Type Definitions
+ *
+ * Types for remote agent communication via MCP (Model Context Protocol).
+ * Migrated from sdk-bak/src/core/remote/types.ts and adapted to SDK conventions.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/server/auth.js

@@ -0,0 +1,31 @@
+/**
+ * MCP Server authentication & Origin validation.
+ *
+ * - Origin header 검증 (DNS rebinding 방어, MCP 스펙 필수)
+ * - 커스텀 auth 콜백 래퍼
+ */
+/**
+ * Validate the Origin header is present (MCP spec requirement).
+ * Returns a 403 Response if validation fails, or null if ok.
+ */
+export function validateOrigin(req) {
+    const origin = req.headers.get('Origin');
+    if (!origin) {
+        return new Response(JSON.stringify({ error: 'Forbidden: Origin header required' }), { status: 403, headers: { 'Content-Type': 'application/json' } });
+    }
+    return null;
+}
+/**
+ * Run the custom auth callback if provided.
+ * Returns a 401 Response if auth fails, or null if ok.
+ */
+export async function runAuthCallback(req, auth) {
+    if (!auth)
+        return null;
+    const allowed = await auth(req);
+    if (!allowed) {
+        return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401, headers: { 'Content-Type': 'application/json' } });
+    }
+    return null;
+}
+//# sourceMappingURL=auth.js.map

package/dist/esm/server/handler.js

@@ -0,0 +1,72 @@
+/**
+ * crewx.handler() — Framework-independent MCP HTTP handler.
+ *
+ * Returns a Web Standard `(req: Request) => Promise<Response>` handler
+ * that can be mounted on Express, Next.js, Hono, Bun, etc.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WebStandardStreamableHTTPServerTransport, } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { registerCrewxTools } from './tool-adapter';
+import { validateOrigin, runAuthCallback } from './auth';
+/**
+ * Create a fresh McpServer with tools registered.
+ */
+function createMcpServer(crewx, allowedAgents) {
+    const mcpServer = new McpServer({
+        name: 'crewx-mcp-server',
+        version: '1.0.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    registerCrewxTools(mcpServer, crewx, allowedAgents);
+    return mcpServer;
+}
+/**
+ * Create an MCP handler bound to the given Crewx instance.
+ *
+ * @param crewx  - Crewx facade instance
+ * @param options - Handler configuration (agents list required)
+ * @returns Web Standard request handler
+ */
+export function createHandler(crewx, options) {
+    if (!options.agents || options.agents.length === 0) {
+        throw new Error('crewx.handler() requires at least one agent in the agents option');
+    }
+    const allowedAgents = new Set(options.agents);
+    // Per-session transport + server map
+    const sessions = new Map();
+    return async (req) => {
+        // ── Security: Origin validation ──────────────────────────────────────
+        const originError = validateOrigin(req);
+        if (originError)
+            return originError;
+        // ── Security: Custom auth callback ───────────────────────────────────
+        const authError = await runAuthCallback(req, options.auth);
+        if (authError)
+            return authError;
+        // ── Route to transport ───────────────────────────────────────────────
+        const sessionId = req.headers.get('mcp-session-id');
+        if (sessionId && sessions.has(sessionId)) {
+            // Existing session — reuse transport
+            const session = sessions.get(sessionId);
+            return session.transport.handleRequest(req);
+        }
+        // New session: create McpServer + transport pair
+        const mcpServer = createMcpServer(crewx, allowedAgents);
+        const transport = new WebStandardStreamableHTTPServerTransport({
+            sessionIdGenerator: () => crypto.randomUUID(),
+            onsessioninitialized: (sid) => {
+                sessions.set(sid, { transport, server: mcpServer });
+            },
+            onsessionclosed: (sid) => {
+                sessions.delete(sid);
+            },
+            enableJsonResponse: true,
+        });
+        await mcpServer.connect(transport);
+        return transport.handleRequest(req);
+    };
+}
+//# sourceMappingURL=handler.js.map

package/dist/esm/server/index.js

@@ -0,0 +1,5 @@
+/**
+ * @crewx/sdk server module — MCP HTTP handler for exposing agents.
+ */
+export { createHandler } from './handler';
+//# sourceMappingURL=index.js.map

package/dist/esm/server/tool-adapter.js

@@ -0,0 +1,92 @@
+/**
+ * MCP tool adapter — 범용 MCP 도구 3개를 McpServer에 등록한다.
+ *
+ * 도구:
+ *   crewx_queryAgent(agentId, query, context?, thread?)
+ *   crewx_executeAgent(agentId, task, context?, thread?)
+ *   crewx_listAgents()
+ */
+import { z } from 'zod';
+const querySchema = {
+    agentId: z.string().describe('The agent ID to query'),
+    query: z.string().describe('The query message to send'),
+    context: z.string().optional().describe('Additional context'),
+    thread: z.string().optional().describe('Thread ID for conversation continuity'),
+};
+const executeSchema = {
+    agentId: z.string().describe('The agent ID to execute'),
+    task: z.string().describe('The task description to execute'),
+    context: z.string().optional().describe('Additional context'),
+    thread: z.string().optional().describe('Thread ID for conversation continuity'),
+};
+/**
+ * Register the 3 universal tools on the given McpServer.
+ *
+ * @param server  - McpServer instance
+ * @param crewx   - Crewx facade instance
+ * @param allowedAgents - Set of agent IDs exposed via handler
+ */
+export function registerCrewxTools(server, crewx, allowedAgents) {
+    // ── crewx_listAgents (no schema — zero-arg tool) ────────────────────────
+    server.tool('crewx_listAgents', 'List available CrewX agents exposed by this server', async () => {
+        const agents = [];
+        for (const agentId of allowedAgents) {
+            const agent = crewx.agents.get(agentId);
+            if (agent) {
+                agents.push({
+                    id: agent.id,
+                    name: agent.name ?? agent.id,
+                    description: agent.description ?? '',
+                });
+            }
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify(agents, null, 2) }],
+        };
+    });
+    // ── crewx_queryAgent ────────────────────────────────────────────────────
+    server.tool('crewx_queryAgent', 'Query a CrewX agent with a read-only question', querySchema, async ({ agentId, query, context, thread }) => {
+        if (!allowedAgents.has(agentId)) {
+            return {
+                content: [{ type: 'text', text: `Agent '${agentId}' is not exposed by this server` }],
+                isError: true,
+            };
+        }
+        const result = await crewx.query(agentId, query, {
+            context,
+            threadId: thread,
+        });
+        if (!result.ok) {
+            return {
+                content: [{ type: 'text', text: result.error?.message ?? 'Query failed' }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: 'text', text: result.data }],
+        };
+    });
+    // ── crewx_executeAgent ──────────────────────────────────────────────────
+    server.tool('crewx_executeAgent', 'Execute a task on a CrewX agent (may modify state)', executeSchema, async ({ agentId, task, context, thread }) => {
+        if (!allowedAgents.has(agentId)) {
+            return {
+                content: [{ type: 'text', text: `Agent '${agentId}' is not exposed by this server` }],
+                isError: true,
+            };
+        }
+        const result = await crewx.execute(agentId, task, {
+            context,
+            threadId: thread,
+        });
+        if (!result.ok) {
+            return {
+                content: [{ type: 'text', text: result.error?.message ?? 'Execute failed' }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: 'text', text: result.data }],
+        };
+    });
+}
+//# sourceMappingURL=tool-adapter.js.map

package/dist/esm/template/engine.js

@@ -0,0 +1,100 @@
+/**
+ * CrewX template engine — Handlebars-based rendering with P0 helpers.
+ *
+ * P0 helpers implemented here:
+ * - exec        : shell command execution (5-stage security)
+ * - include     : inline string content passthrough
+ * - fenced_code : Markdown fenced code block wrapper
+ * - eq, ne, and, or, not, json (condition helpers)
+ */
+import * as Handlebars from 'handlebars';
+import { executeCommand } from './helpers/exec';
+import { includeHelper } from './helpers/include';
+import { fencedCodeHelper } from './helpers/fenced_code';
+import { truncateHelper, lengthHelper, escapeHandlebarsHelper, formatFileSizeHelper, formatTimestampHelper, } from './helpers/p1p2';
+export class TemplateEngine {
+    hbs;
+    execPolicy;
+    execEnabled;
+    constructor(options = {}) {
+        // Create an isolated Handlebars environment to avoid global state conflicts
+        this.hbs = Handlebars.create();
+        this.execPolicy = options.execPolicy ?? { allow: [], deny: [] };
+        this.execEnabled = options.execEnabled ?? true;
+        this.registerHelpers();
+    }
+    /**
+     * Register all P0 helpers onto this engine's Handlebars instance.
+     */
+    registerHelpers() {
+        const hbs = this.hbs;
+        const policy = this.execPolicy;
+        // ── exec: shell command execution ────────────────────────────────────────
+        const execEnabled = this.execEnabled;
+        hbs.registerHelper('exec', function (command) {
+            if (typeof command !== 'string')
+                return '';
+            if (!execEnabled)
+                return '(exec disabled)';
+            return new hbs.SafeString(executeCommand(command, policy));
+        });
+        // ── include: inline string passthrough ───────────────────────────────────
+        hbs.registerHelper('include', function (content) {
+            return new hbs.SafeString(includeHelper(content));
+        });
+        // ── fenced_code: Markdown code block wrapper ──────────────────────────────
+        hbs.registerHelper('fenced_code', function (content, options) {
+            return new hbs.SafeString(fencedCodeHelper(content, options));
+        });
+        // ── Condition helpers ─────────────────────────────────────────────────────
+        hbs.registerHelper('eq', function (a, b) {
+            return a === b;
+        });
+        hbs.registerHelper('ne', function (a, b) {
+            return a !== b;
+        });
+        hbs.registerHelper('and', function (a, b) {
+            return a && b;
+        });
+        hbs.registerHelper('or', function (a, b) {
+            return a || b;
+        });
+        hbs.registerHelper('not', function (a) {
+            return !a;
+        });
+        hbs.registerHelper('contains', function (array, value) {
+            return Array.isArray(array) && array.includes(value);
+        });
+        hbs.registerHelper('json', function (context) {
+            return JSON.stringify(context, null, 2);
+        });
+        // ── P1 helpers ────────────────────────────────────────────────────────────
+        hbs.registerHelper('truncate', function (text, maxLength) {
+            return truncateHelper(text, maxLength);
+        });
+        hbs.registerHelper('length', function (value) {
+            return lengthHelper(value);
+        });
+        hbs.registerHelper('escapeHandlebars', function (text) {
+            return new hbs.SafeString(escapeHandlebarsHelper(text));
+        });
+        // ── P2 helpers ────────────────────────────────────────────────────────────
+        hbs.registerHelper('formatFileSize', function (bytes) {
+            return formatFileSizeHelper(bytes);
+        });
+        hbs.registerHelper('formatTimestamp', function (timestamp) {
+            return formatTimestampHelper(timestamp);
+        });
+    }
+    /**
+     * Render a Handlebars template string with the given context.
+     * @param template - Handlebars template string
+     * @param context  - Template context (documents, env, agent, etc.)
+     * @returns Rendered string
+     */
+    async render(template, context = {}) {
+        const compiled = this.hbs.compile(template, { noEscape: true });
+        return compiled(context);
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/esm/template/helpers/exec.browser.js

@@ -0,0 +1,31 @@
+/**
+ * Browser stub for the exec helper.
+ *
+ * Replaces the Node.js exec helper in browser bundles (via package.json "browser" field).
+ * All functions are no-ops or return safe defaults — child_process is not available in browsers.
+ */
+export function getSanitizedEnv() {
+    return {};
+}
+export function validateCommand(_command) {
+    // noop in browser
+}
+export function isBuiltinAllowed(_command) {
+    return false;
+}
+export function validateAllowPattern(_pattern) {
+    // noop in browser
+}
+export function isAllowed(_command, _policy) {
+    return false;
+}
+export function setAuditVerbose(_enabled) {
+    // noop in browser
+}
+export function logExecAudit(_entry) {
+    // noop in browser
+}
+export function executeCommand(_command, _policy) {
+    return '(exec disabled: browser environment)';
+}
+//# sourceMappingURL=exec.browser.js.map

package/dist/esm/template/helpers/exec.js

@@ -0,0 +1,220 @@
+/**
+ * exec Handlebars helper — 5-stage security implementation.
+ *
+ * Ports the security logic from packages/cli-bak/src/utils/template-processor.ts
+ * without using shell-quote or minimatch (not in allowed library list).
+ *
+ * Stages:
+ * 1. Recursion depth check (fail-closed on NaN)
+ * 2. Shell metacharacter validation
+ * 3. Allow-list enforcement (deny > builtin > allow > reject)
+ * 4. Environment isolation (strip sensitive keys)
+ * 5. Result capture (execFileSync with timeout + maxBuffer, wrapped in tags)
+ */
+import { execFileSync } from 'child_process';
+import { matchesPattern } from '../../utils/glob-match';
+// Sensitive env key patterns — removed from exec child processes
+const SENSITIVE_ENV_PATTERNS = [
+    /^ANTHROPIC_/i, /^OPENAI_/i, /^AWS_SECRET/i, /^SLACK_/i,
+    /^GITHUB_TOKEN$/i, /^CREWX_MCP_KEY$/i, /^DATABASE_/i,
+    /^AWS_ACCESS_KEY/i, /^AWS_SESSION_TOKEN$/i,
+    /^GH_TOKEN$/i, /^GH_APP_/i,
+    /^NPM_TOKEN$/i, /^NPM_AUTH/i,
+    /^GOOGLE_APPLICATION/i, /^GCLOUD_/i,
+    /^AZURE_/i, /^ARM_/i,
+    /^DOCKER_PASSWORD$/i, /^DOCKER_AUTH/i,
+    /^SSH_PRIVATE/i, /^SSH_AUTH_SOCK$/i,
+    /^CI_JOB_TOKEN$/i, /^ACTIONS_RUNTIME_TOKEN$/i,
+    /^VAULT_TOKEN$/i, /^SONAR_TOKEN$/i, /^CODECOV_TOKEN$/i,
+    /TOKEN$/i, /SECRET$/i, /PASSWORD$/i, /API_KEY$/i,
+];
+// Shell metacharacter pattern — blocks command injection
+const SHELL_METACHAR = /[;|&`$(){}!><\n\r]/;
+// Max recursion depth for exec helper
+const MAX_EXEC_DEPTH = 2;
+// Overly broad patterns that must be rejected in allow/deny lists
+const DANGEROUS_PATTERNS = ['*', '**', '*:*', '* *', '**/*'];
+// ─────────────────────────────────────────────────────────────────────────────
+// Stage 4: Environment isolation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Returns a copy of process.env with all sensitive keys removed.
+ */
+export function getSanitizedEnv() {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value === undefined)
+            continue;
+        if (SENSITIVE_ENV_PATTERNS.some(p => p.test(key)))
+            continue;
+        env[key] = value;
+    }
+    return env;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Stage 1: Shell metacharacter validation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Validates a command string for shell metacharacter injection.
+ * @throws Error if shell metacharacters are detected.
+ */
+export function validateCommand(command) {
+    if (SHELL_METACHAR.test(command)) {
+        throw new Error(`exec blocked: shell metacharacter detected in "${command}"`);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Stage 2: Allow-list enforcement
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Checks if a command matches the builtin allowed pattern.
+ * Only npx @crewx/<package> scope is allowed by default.
+ */
+export function isBuiltinAllowed(command) {
+    return /^npx\s+@crewx\/[\w-]+/.test(command);
+}
+/**
+ * Validates allow/deny patterns — rejects overly broad wildcards.
+ * @throws Error if pattern is too broad or malformed.
+ */
+export function validateAllowPattern(pattern) {
+    // Trim only for dangerous-pattern check (exact match list)
+    if (DANGEROUS_PATTERNS.includes(pattern.trim())) {
+        throw new Error(`exec config error: overly broad pattern "${pattern}" is not allowed`);
+    }
+    // Start-character check uses original pattern (space prefix → rejected)
+    if (!/^[\w./@-]/.test(pattern)) {
+        throw new Error(`exec config error: pattern must start with a command name`);
+    }
+}
+/**
+ * Checks if a command is allowed by the exec policy.
+ * Priority: deny > builtin(@crewx) > allow > reject
+ */
+export function isAllowed(command, policy) {
+    const allow = policy.allow ?? [];
+    const deny = policy.deny ?? [];
+    // Validate patterns
+    for (const p of [...allow, ...deny]) {
+        validateAllowPattern(p);
+    }
+    // Step 1: deny takes highest priority
+    if (deny.some(pattern => matchesPattern(command, pattern)))
+        return false;
+    // Step 2: builtin allowed (@crewx/* scope only)
+    if (isBuiltinAllowed(command))
+        return true;
+    // Step 3: explicit allow patterns
+    return allow.some(pattern => matchesPattern(command, pattern));
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Audit log
+// ─────────────────────────────────────────────────────────────────────────────
+/** When false (default), audit logs are suppressed. Set true via setAuditVerbose(). */
+let _verboseAudit = false;
+/**
+ * Enable or disable exec audit log output to stderr.
+ * Call with true to show span JSON (verbose mode); false to suppress (default).
+ */
+export function setAuditVerbose(enabled) {
+    _verboseAudit = enabled;
+}
+/**
+ * Emits a structured audit log entry to stderr.
+ * Only writes when verbose audit mode is enabled via setAuditVerbose(true).
+ */
+export function logExecAudit(entry) {
+    if (!_verboseAudit)
+        return;
+    const log = JSON.stringify({ span: 'template_exec', ...entry, timestamp: new Date().toISOString() });
+    console.error(log);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Simple shell argument parser (replaces shell-quote)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Parses a command string into an array of arguments.
+ * Handles single and double quoted strings.
+ */
+function parseShellArgs(command) {
+    const tokens = [];
+    let current = '';
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (ch === "'" && !inDouble) {
+            inSingle = !inSingle;
+        }
+        else if (ch === '"' && !inSingle) {
+            inDouble = !inDouble;
+        }
+        else if (ch === ' ' && !inSingle && !inDouble) {
+            if (current.length > 0) {
+                tokens.push(current);
+                current = '';
+            }
+        }
+        else {
+            current += ch;
+        }
+    }
+    if (current.length > 0)
+        tokens.push(current);
+    return tokens;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Stage 3 + 5: Execute command with timeout and result capture
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Executes a command and returns the output wrapped in exec-output tags.
+ * Implements all 5 security stages.
+ */
+export function executeCommand(command, policy) {
+    const startMs = Date.now();
+    // Stage 1: Recursion depth check (NaN fail-closed)
+    const execDepth = parseInt(process.env.CREWX_EXEC_DEPTH ?? '0', 10);
+    if (isNaN(execDepth) || execDepth >= MAX_EXEC_DEPTH) {
+        logExecAudit({ command, status: 'denied', reason: 'invalid or max recursion depth' });
+        return '(exec blocked: max recursion depth reached)';
+    }
+    // Stage 2a: Shell metacharacter validation
+    try {
+        validateCommand(command);
+    }
+    catch {
+        logExecAudit({ command, status: 'denied', reason: 'shell metacharacter detected' });
+        return `(exec blocked: shell metacharacter detected in "${command}")`;
+    }
+    // Stage 2b/c: Allow-list enforcement (deny > builtin > allow > reject)
+    if (!isAllowed(command, policy)) {
+        logExecAudit({ command, status: 'denied', reason: 'not in allow list' });
+        return `(exec blocked: ${command})`;
+    }
+    // Stage 3 + 4 + 5: Execute with timeout, env isolation, and result capture
+    try {
+        const parsed = parseShellArgs(command);
+        const [bin, ...args] = parsed;
+        if (!bin)
+            return `(exec failed: ${command})`;
+        // Stage 4: Environment isolation
+        const sanitizedEnv = getSanitizedEnv();
+        // Stage 3: Timeout + Stage 5: Result capture
+        const result = execFileSync(bin, args, {
+            timeout: policy.timeout ?? 5000,
+            maxBuffer: 64 * 1024, // 64KB — OOM prevention
+            encoding: 'utf-8',
+            env: { ...sanitizedEnv, CREWX_EXEC_DEPTH: String(execDepth + 1) },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const durationMs = Date.now() - startMs;
+        logExecAudit({ command, status: 'allowed', allowed_by: 'policy', duration_ms: durationMs });
+        // Stage 5: Wrap result in structured tags
+        return `<exec-output cmd="${command}">\n${result.trim()}\n</exec-output>`;
+    }
+    catch {
+        logExecAudit({ command, status: 'error', reason: 'execution failed' });
+        return `(exec failed: ${command})`;
+    }
+}
+//# sourceMappingURL=exec.js.map

package/dist/esm/template/helpers/fenced_code.js

@@ -0,0 +1,17 @@
+/**
+ * fenced_code Handlebars helper — wraps content in a Markdown fenced code block.
+ *
+ * Usage in templates:
+ *   {{fenced_code myCode lang="typescript"}}
+ *   {{fenced_code myCode}}              ← no language specified
+ */
+/**
+ * Wraps content in a Markdown fenced code block.
+ * @param content - The code content to wrap.
+ * @param options - Handlebars options object (may contain hash.lang).
+ */
+export function fencedCodeHelper(content, options) {
+    const lang = options?.hash?.lang ?? '';
+    return `\`\`\`${lang}\n${content ?? ''}\n\`\`\``;
+}
+//# sourceMappingURL=fenced_code.js.map

package/dist/esm/template/helpers/include.js

@@ -0,0 +1,20 @@
+/**
+ * include Handlebars helper — returns inline string content as-is.
+ *
+ * Usage in templates:
+ *   {{{include someVariable}}}
+ *   {{{include "literal string"}}}
+ *
+ * Note: File-path based document loading is handled in SDK-006 (DocumentLoader).
+ * This helper supports only inline string content (already in context).
+ */
+/**
+ * Returns the given string content unchanged.
+ * Returns empty string for null/undefined.
+ */
+export function includeHelper(content) {
+    if (content === null || content === undefined)
+        return '';
+    return String(content);
+}
+//# sourceMappingURL=include.js.map