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

package/dist/remote/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * 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.
+ */
+/**
+ * Transport abstraction for remote MCP communication.
+ * Designed for future extension (WebSocket, gRPC, etc.).
+ */
+export interface RemoteTransport {
+    /** Send a JSON-RPC 2.0 request and receive a response. */
+    send(request: McpJsonRpcRequest): Promise<McpJsonRpcResponse>;
+    /** Release transport resources. */
+    close(): Promise<void>;
+}
+/** MCP JSON-RPC 2.0 Request */
+export interface McpJsonRpcRequest {
+    jsonrpc: '2.0';
+    id: string;
+    method: string;
+    params?: Record<string, unknown>;
+}
+/** MCP JSON-RPC 2.0 Response */
+export interface McpJsonRpcResponse<T = unknown> {
+    jsonrpc: '2.0';
+    id: string;
+    result?: T;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/** Remote agent configuration (SDK-internal format). */
+export interface RemoteAgentConfig {
+    /** Remote agent type (currently only mcp-http supported). */
+    type: 'mcp-http';
+    /** Base URL for the remote MCP server. */
+    url: string;
+    /** Optional API key for authentication. */
+    apiKey?: string;
+    /** Optional custom headers. */
+    headers?: Record<string, string>;
+    /** Optional timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Remote agent ID (may differ from local agent ID). */
+    agentId?: string;
+    /** Tool name mappings (optional). */
+    tools?: {
+        query?: string;
+        execute?: string;
+    };
+}
+/** Remote provider config as defined in crewx.yaml `providers:` section. */
+export interface RemoteProviderConfig {
+    /** Provider ID (e.g. "remote_cto"). */
+    id: string;
+    /** Provider type — must be "remote". */
+    type: 'remote';
+    /** Location of the remote agent (file:// or http(s)://). */
+    location: string;
+    /** Agent ID on the remote side. */
+    external_agent_id?: string;
+    /** Display name for UI. */
+    display_name?: string;
+    /** Description. */
+    description?: string;
+    /** Timeout per mode (ms). */
+    timeout?: {
+        query?: number;
+        execute?: number;
+    };
+    /** Optional API key for MCP-HTTP authentication. */
+    apiKey?: string;
+    /** Optional custom headers for MCP-HTTP. */
+    headers?: Record<string, string>;
+}
+/** Remote agent query request parameters. */
+export interface RemoteAgentQueryRequest {
+    /** The agent ID to query. */
+    agentId: string;
+    /** The query text. */
+    query: string;
+    /** Optional context. */
+    context?: string;
+    /** Optional model override. */
+    model?: string;
+    /** Optional platform identifier. */
+    platform?: string;
+    /** Optional conversation messages. */
+    messages?: Array<{
+        text: string;
+        isAssistant: boolean;
+        metadata?: Record<string, unknown>;
+    }>;
+}
+/** Remote agent execute request parameters. */
+export interface RemoteAgentExecuteRequest {
+    /** The agent ID to execute. */
+    agentId: string;
+    /** The task to execute. */
+    task: string;
+    /** Optional context. */
+    context?: string;
+    /** Optional model override. */
+    model?: string;
+    /** Optional platform identifier. */
+    platform?: string;
+    /** Optional conversation messages. */
+    messages?: Array<{
+        text: string;
+        isAssistant: boolean;
+        metadata?: Record<string, unknown>;
+    }>;
+}
+/** Remote agent response. */
+export interface RemoteAgentResponse {
+    /** Response content blocks. */
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    /** Success flag. */
+    success?: boolean;
+    /** Error message if failed. */
+    error?: string;
+    /** Additional metadata. */
+    [key: string]: unknown;
+}
+/** Tool name mapping for remote agents. */
+export interface ToolNameMapping {
+    /** Tool name for query operations. */
+    query: string;
+    /** Tool name for execute operations. */
+    execute: string;
+}
+/** Remote agent descriptor containing configuration and metadata. */
+export interface RemoteAgentDescriptor {
+    /** Local agent ID. */
+    localAgentId: string;
+    /** Remote agent ID (may differ). */
+    remoteAgentId: string;
+    /** Remote agent configuration. */
+    config: RemoteAgentConfig;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/remote/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/server/auth.d.ts

@@ -0,0 +1,21 @@
+/**
+ * MCP Server authentication & Origin validation.
+ *
+ * - Origin header 검증 (DNS rebinding 방어, MCP 스펙 필수)
+ * - 커스텀 auth 콜백 래퍼
+ */
+export interface AuthOptions {
+    /** Custom auth callback. Return false to reject the request. */
+    auth?: (req: Request) => Promise<boolean>;
+}
+/**
+ * Validate the Origin header is present (MCP spec requirement).
+ * Returns a 403 Response if validation fails, or null if ok.
+ */
+export declare function validateOrigin(req: Request): Response | null;
+/**
+ * Run the custom auth callback if provided.
+ * Returns a 401 Response if auth fails, or null if ok.
+ */
+export declare function runAuthCallback(req: Request, auth?: (req: Request) => Promise<boolean>): Promise<Response | null>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/server/auth.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * MCP Server authentication & Origin validation.
+ *
+ * - Origin header 검증 (DNS rebinding 방어, MCP 스펙 필수)
+ * - 커스텀 auth 콜백 래퍼
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateOrigin = validateOrigin;
+exports.runAuthCallback = runAuthCallback;
+/**
+ * Validate the Origin header is present (MCP spec requirement).
+ * Returns a 403 Response if validation fails, or null if ok.
+ */
+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.
+ */
+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/server/handler.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 type { Crewx } from '../facade/Crewx';
+export interface HandlerOptions {
+    /** Agent IDs to expose via MCP. Required — explicit selection for security. */
+    agents: string[];
+    /** Custom auth callback. Return false to reject the request. */
+    auth?: (req: Request) => Promise<boolean>;
+}
+/** The Web Standard handler type returned by crewx.handler(). */
+export type CrewxHandler = (req: Request) => Promise<Response>;
+/**
+ * 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 declare function createHandler(crewx: Crewx, options: HandlerOptions): CrewxHandler;
+//# sourceMappingURL=handler.d.ts.map

package/dist/server/handler.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHandler = createHandler;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const webStandardStreamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js");
+const tool_adapter_1 = require("./tool-adapter");
+const auth_1 = require("./auth");
+/**
+ * Create a fresh McpServer with tools registered.
+ */
+function createMcpServer(crewx, allowedAgents) {
+    const mcpServer = new mcp_js_1.McpServer({
+        name: 'crewx-mcp-server',
+        version: '1.0.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    (0, tool_adapter_1.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
+ */
+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 = (0, auth_1.validateOrigin)(req);
+        if (originError)
+            return originError;
+        // ── Security: Custom auth callback ───────────────────────────────────
+        const authError = await (0, auth_1.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 webStandardStreamableHttp_js_1.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/server/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @crewx/sdk server module — MCP HTTP handler for exposing agents.
+ */
+export { createHandler } from './handler';
+export type { HandlerOptions, CrewxHandler } from './handler';
+export type { AuthOptions } from './auth';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * @crewx/sdk server module — MCP HTTP handler for exposing agents.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHandler = void 0;
+var handler_1 = require("./handler");
+Object.defineProperty(exports, "createHandler", { enumerable: true, get: function () { return handler_1.createHandler; } });
+//# sourceMappingURL=index.js.map

package/dist/server/tool-adapter.d.ts

@@ -0,0 +1,19 @@
+/**
+ * MCP tool adapter — 범용 MCP 도구 3개를 McpServer에 등록한다.
+ *
+ * 도구:
+ *   crewx_queryAgent(agentId, query, context?, thread?)
+ *   crewx_executeAgent(agentId, task, context?, thread?)
+ *   crewx_listAgents()
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Crewx } from '../facade/Crewx';
+/**
+ * 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 declare function registerCrewxTools(server: McpServer, crewx: Crewx, allowedAgents: Set<string>): void;
+//# sourceMappingURL=tool-adapter.d.ts.map

package/dist/server/tool-adapter.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * MCP tool adapter — 범용 MCP 도구 3개를 McpServer에 등록한다.
+ *
+ * 도구:
+ *   crewx_queryAgent(agentId, query, context?, thread?)
+ *   crewx_executeAgent(agentId, task, context?, thread?)
+ *   crewx_listAgents()
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCrewxTools = registerCrewxTools;
+const zod_1 = require("zod");
+const querySchema = {
+    agentId: zod_1.z.string().describe('The agent ID to query'),
+    query: zod_1.z.string().describe('The query message to send'),
+    context: zod_1.z.string().optional().describe('Additional context'),
+    thread: zod_1.z.string().optional().describe('Thread ID for conversation continuity'),
+};
+const executeSchema = {
+    agentId: zod_1.z.string().describe('The agent ID to execute'),
+    task: zod_1.z.string().describe('The task description to execute'),
+    context: zod_1.z.string().optional().describe('Additional context'),
+    thread: zod_1.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
+ */
+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/template/engine.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 type { TemplateContext, TemplateEngineOptions } from './types';
+export declare class TemplateEngine {
+    private readonly hbs;
+    private readonly execPolicy;
+    private readonly execEnabled;
+    constructor(options?: TemplateEngineOptions);
+    /**
+     * Register all P0 helpers onto this engine's Handlebars instance.
+     */
+    private registerHelpers;
+    /**
+     * 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
+     */
+    render(template: string, context?: TemplateContext): Promise<string>;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/template/engine.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * 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)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TemplateEngine = void 0;
+const Handlebars = __importStar(require("handlebars"));
+const exec_1 = require("./helpers/exec");
+const include_1 = require("./helpers/include");
+const fenced_code_1 = require("./helpers/fenced_code");
+const p1p2_1 = require("./helpers/p1p2");
+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((0, exec_1.executeCommand)(command, policy));
+        });
+        // ── include: inline string passthrough ───────────────────────────────────
+        hbs.registerHelper('include', function (content) {
+            return new hbs.SafeString((0, include_1.includeHelper)(content));
+        });
+        // ── fenced_code: Markdown code block wrapper ──────────────────────────────
+        hbs.registerHelper('fenced_code', function (content, options) {
+            return new hbs.SafeString((0, fenced_code_1.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 (0, p1p2_1.truncateHelper)(text, maxLength);
+        });
+        hbs.registerHelper('length', function (value) {
+            return (0, p1p2_1.lengthHelper)(value);
+        });
+        hbs.registerHelper('escapeHandlebars', function (text) {
+            return new hbs.SafeString((0, p1p2_1.escapeHandlebarsHelper)(text));
+        });
+        // ── P2 helpers ────────────────────────────────────────────────────────────
+        hbs.registerHelper('formatFileSize', function (bytes) {
+            return (0, p1p2_1.formatFileSizeHelper)(bytes);
+        });
+        hbs.registerHelper('formatTimestamp', function (timestamp) {
+            return (0, p1p2_1.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);
+    }
+}
+exports.TemplateEngine = TemplateEngine;
+//# sourceMappingURL=engine.js.map

package/dist/template/helpers/exec.browser.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+import type { ExecPolicy } from '../types';
+export declare function getSanitizedEnv(): Record<string, string>;
+export declare function validateCommand(_command: string): void;
+export declare function isBuiltinAllowed(_command: string): boolean;
+export declare function validateAllowPattern(_pattern: string): void;
+export declare function isAllowed(_command: string, _policy: ExecPolicy): boolean;
+export declare function setAuditVerbose(_enabled: boolean): void;
+export declare function logExecAudit(_entry: {
+    command: string;
+    status: 'allowed' | 'denied' | 'error';
+    allowed_by?: string;
+    reason?: string;
+    duration_ms?: number;
+}): void;
+export declare function executeCommand(_command: string, _policy: ExecPolicy): string;
+//# sourceMappingURL=exec.browser.d.ts.map