@crewx/sdk 0.8.0-rc.72 → 0.8.0-rc.74

package/dist/facade/Crewx.browser.js

@@ -0,0 +1,314 @@
+"use strict";
+/**
+ * Browser-safe Crewx facade.
+ *
+ * Stripped of all Node.js dependencies (path, fs, child_process, crypto, events).
+ * Supports: fromConfig(), query(), execute(), registerTool(), agents, tools.
+ *
+ * Built-in providers (e.g. api/webllm) are auto-initialised when detected
+ * in the agents list — no manual registerProviderFactory required.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Crewx = void 0;
+const resolver_js_1 = require("../agent/resolver.js");
+const bridge_browser_js_1 = require("../provider/bridge.browser.js");
+/** Dynamic import that bypasses TypeScript module resolution for CDN URLs. */
+const _cdnImport = new Function('u', 'return import(u)');
+class Crewx {
+    _agents;
+    _config;
+    _tools = new Map();
+    _apiProviders = new Map();
+    constructor(agents, config) {
+        this._agents = new Map(agents.map(a => [a.id, a]));
+        this._config = config;
+    }
+    /**
+     * Create a Crewx instance from an already-parsed config object.
+     *
+     * Built-in browser providers (api/webllm, api/openrouter) are auto-initialised
+     * when detected in the agents list — no manual registerProviderFactory required.
+     */
+    static async fromConfig(config, options) {
+        const instance = new Crewx(config.agents ?? [], config);
+        const agents = config.agents ?? [];
+        const providerOf = (a) => Array.isArray(a.provider) ? a.provider[0] : a.provider;
+        const webllmAgents = agents.filter(a => providerOf(a) === 'api/webllm');
+        const openrouterAgents = agents.filter(a => providerOf(a) === 'api/openrouter');
+        if (webllmAgents.length > 0) {
+            await instance._initWebLLM(webllmAgents, options?.onProgress);
+        }
+        if (openrouterAgents.length > 0) {
+            if (!options?.openrouterApiKey) {
+                throw new Error('openrouterApiKey is required when using api/openrouter provider');
+            }
+            instance._initOpenRouter(openrouterAgents, options.openrouterApiKey);
+        }
+        // Register unified api factory dispatching to initialised sub-providers
+        if (instance._apiProviders.size > 0) {
+            (0, bridge_browser_js_1.registerProviderFactory)('api', (id, providerStr) => {
+                const provider = instance._apiProviders.get(id);
+                if (!provider) {
+                    throw new bridge_browser_js_1.ProviderError(`Unknown api provider: ${id}`, providerStr);
+                }
+                return provider;
+            });
+        }
+        return instance;
+    }
+    // ── web-llm auto-init ──────────────────────────────────────────────────────
+    /**
+     * Load web-llm from CDN, create the inference engine, and store
+     * the provider runtime.  Called automatically by fromConfig().
+     */
+    async _initWebLLM(agents, onProgress) {
+        if (typeof navigator === 'undefined' || !navigator.gpu) {
+            throw new Error('WebGPU is not available. Chrome 113+ or Edge 113+ required.');
+        }
+        const webllm = await _cdnImport('https://esm.run/@mlc-ai/web-llm');
+        const modelId = agents[0]?.inline?.model ?? 'gemma-2-2b-it-q4f16_1-MLC';
+        const engine = await webllm.CreateMLCEngine(modelId, {
+            initProgressCallback: onProgress
+                ? (report) => onProgress(report)
+                : undefined,
+        });
+        const history = [];
+        this._apiProviders.set('webllm', {
+            async query(message, options) {
+                const messages = [];
+                if (options?.systemPrompt) {
+                    messages.push({ role: 'system', content: options.systemPrompt });
+                }
+                messages.push(...history);
+                messages.push({ role: 'user', content: message });
+                let fullReply = '';
+                const stream = await engine.chat.completions.create({
+                    messages,
+                    stream: true,
+                    temperature: 0.7,
+                    max_tokens: 4096,
+                });
+                for await (const chunk of stream) {
+                    const delta = chunk.choices?.[0]?.delta?.content ?? '';
+                    fullReply += delta;
+                    if (options?.onOutput) {
+                        options.onOutput(fullReply, 'stdout');
+                    }
+                }
+                history.push({ role: 'user', content: message });
+                history.push({ role: 'assistant', content: fullReply });
+                return fullReply;
+            },
+            async execute(message, options) {
+                return this.query(message, options);
+            },
+        });
+    }
+    /**
+     * Initialise the OpenRouter API provider.
+     * Uses fetch + SSE streaming against the OpenAI-compatible endpoint.
+     */
+    _initOpenRouter(agents, apiKey) {
+        const defaultModel = agents[0]?.inline?.model ?? 'google/gemma-2-2b-it';
+        const history = [];
+        this._apiProviders.set('openrouter', {
+            async query(message, options) {
+                const messages = [];
+                if (options?.systemPrompt) {
+                    messages.push({ role: 'system', content: options.systemPrompt });
+                }
+                messages.push(...history);
+                messages.push({ role: 'user', content: message });
+                const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
+                    method: 'POST',
+                    headers: {
+                        'Authorization': `Bearer ${apiKey}`,
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        model: options?.model || defaultModel,
+                        messages,
+                        stream: true,
+                    }),
+                });
+                if (!response.ok) {
+                    const errorBody = await response.text();
+                    throw new Error(`OpenRouter API error (${response.status}): ${errorBody}`);
+                }
+                const reader = response.body.getReader();
+                const decoder = new TextDecoder();
+                let fullReply = '';
+                let buffer = '';
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    buffer += decoder.decode(value, { stream: true });
+                    const lines = buffer.split('\n');
+                    buffer = lines.pop();
+                    for (const line of lines) {
+                        const trimmed = line.trim();
+                        if (!trimmed || !trimmed.startsWith('data: '))
+                            continue;
+                        const data = trimmed.slice(6);
+                        if (data === '[DONE]')
+                            continue;
+                        try {
+                            const parsed = JSON.parse(data);
+                            const delta = parsed.choices?.[0]?.delta?.content ?? '';
+                            fullReply += delta;
+                            if (delta && options?.onOutput) {
+                                options.onOutput(fullReply, 'stdout');
+                            }
+                        }
+                        catch {
+                            // skip malformed SSE chunks
+                        }
+                    }
+                }
+                history.push({ role: 'user', content: message });
+                history.push({ role: 'assistant', content: fullReply });
+                return fullReply;
+            },
+            async execute(message, options) {
+                return this.query(message, options);
+            },
+        });
+    }
+    get agents() {
+        return this._agents;
+    }
+    get config() {
+        return this._config;
+    }
+    get tools() {
+        return this._tools;
+    }
+    registerTool(name, definition) {
+        this._tools.set(name, { name, ...definition });
+    }
+    /**
+     * Query an agent with a message.
+     * Browser version — delegates directly to the registered provider factory.
+     * Passes onOutput through for streaming support.
+     */
+    async query(agentRef, message, options) {
+        const startMs = Date.now();
+        let agent;
+        try {
+            agent = (0, resolver_js_1.resolveAgent)(agentRef, Array.from(this._agents.values()));
+        }
+        catch (err) {
+            if (err instanceof resolver_js_1.AgentNotFoundError) {
+                return {
+                    ok: false,
+                    data: '',
+                    error: { code: 'AGENT_NOT_FOUND', message: err.message },
+                    meta: { agentId: agentRef.replace(/^@/, ''), provider: '', durationMs: Date.now() - startMs },
+                };
+            }
+            throw err;
+        }
+        const providerStr = Array.isArray(agent.provider)
+            ? agent.provider[0] ?? 'api/default'
+            : agent.provider;
+        const effectiveProviderStr = options?.provider ?? providerStr;
+        const effectiveModel = options?.model ?? agent.inline?.model;
+        let provider;
+        try {
+            provider = (0, bridge_browser_js_1.createProvider)(effectiveProviderStr);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                data: '',
+                error: { code: 'PROVIDER_ERROR', message: err.message },
+                meta: { agentId: agent.id, provider: effectiveProviderStr, model: effectiveModel, durationMs: Date.now() - startMs },
+            };
+        }
+        try {
+            const response = await provider.query(message, {
+                model: effectiveModel,
+                context: options?.context,
+                systemPrompt: agent.inline?.system_prompt ?? agent.inline?.prompt,
+                onOutput: options?.onOutput
+                    ? (line) => options.onOutput(line)
+                    : undefined,
+            });
+            return {
+                ok: true,
+                data: response,
+                meta: { agentId: agent.id, provider: effectiveProviderStr, model: effectiveModel, durationMs: Date.now() - startMs },
+            };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                data: '',
+                error: { code: 'QUERY_FAILED', message: err.message },
+                meta: { agentId: agent.id, provider: effectiveProviderStr, model: effectiveModel, durationMs: Date.now() - startMs },
+            };
+        }
+    }
+    /**
+     * Execute a task with an agent.
+     * Browser version — same delegation pattern as query().
+     */
+    async execute(agentRef, message, options) {
+        const startMs = Date.now();
+        let agent;
+        try {
+            agent = (0, resolver_js_1.resolveAgent)(agentRef, Array.from(this._agents.values()));
+        }
+        catch (err) {
+            if (err instanceof resolver_js_1.AgentNotFoundError) {
+                return {
+                    ok: false,
+                    data: '',
+                    error: { code: 'AGENT_NOT_FOUND', message: err.message },
+                    meta: { agentId: agentRef.replace(/^@/, ''), provider: '', durationMs: Date.now() - startMs },
+                };
+            }
+            throw err;
+        }
+        const providerStr = Array.isArray(agent.provider)
+            ? agent.provider[0] ?? 'api/default'
+            : agent.provider;
+        const effectiveProviderStr = options?.provider ?? providerStr;
+        const effectiveModel = options?.model ?? agent.inline?.model;
+        let provider;
+        try {
+            provider = (0, bridge_browser_js_1.createProvider)(effectiveProviderStr);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                data: '',
+                error: { code: 'PROVIDER_ERROR', message: err.message },
+                meta: { agentId: agent.id, provider: effectiveProviderStr, model: effectiveModel, durationMs: Date.now() - startMs },
+            };
+        }
+        try {
+            const response = await provider.execute(message, {
+                model: effectiveModel,
+                context: options?.context,
+                systemPrompt: agent.inline?.system_prompt ?? agent.inline?.prompt,
+            });
+            return {
+                ok: true,
+                data: response,
+                meta: { agentId: agent.id, provider: effectiveProviderStr, model: effectiveModel, durationMs: Date.now() - startMs },
+            };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                data: '',
+                error: { code: 'EXECUTE_FAILED', message: err.message },
+                meta: { agentId: agent.id, provider: effectiveProviderStr, model: effectiveModel, durationMs: Date.now() - startMs },
+            };
+        }
+    }
+}
+exports.Crewx = Crewx;
+//# sourceMappingURL=Crewx.browser.js.map

package/dist/facade/Crewx.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Crewx facade — main entry point for the CrewX SDK.
+ * Provides loadYaml(), fromConfig(), query(), execute(), renderAgentPromptFull(),
+ * and registerLayout() methods.
+ */
+import { TypedEventEmitter } from '../events/TypedEventEmitter';
+import type { CrewxPlugin } from '../plugin';
+import type { IFsAdapter } from '../platform/IFsAdapter';
+import type { ChannelAdapterRegistration } from '../adapter/types';
+import type { CrewxProjectConfig, AgentConfig, CrewxOptions, QueryOptions, QueryResult, ExecuteOptions, ExecuteResult } from '../types';
+import type { TemplateContext } from '../template/types';
+import type { CustomLayoutDefinition } from '../layout/types';
+import type { TemplateMessage } from '../conversation/types';
+import type { HandlerOptions, CrewxHandler } from '../server/handler';
+import type { RemoteProviderConfig } from '../remote/types.js';
+/**
+ * Definition for a custom tool that can be registered via crewx.registerTool().
+ * Tools are made available in the agent prompt context for browser/API environments.
+ */
+export interface ToolDefinition {
+    /** Tool name (unique identifier). */
+    name: string;
+    /** Human-readable description of what the tool does. */
+    description: string;
+    /** JSON Schema for tool parameters (optional). */
+    parameters?: Record<string, unknown>;
+    /** Tool execution function. Omit for client-side tools (Vercel AI SDK client tools). */
+    execute?: (args: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * Layout specification for renderAgentPromptFull options.
+ * Matches the crewx.yaml inline.layout schema.
+ */
+export type LayoutSpec = string | {
+    id: string;
+    props?: Record<string, any>;
+} | {
+    template: string;
+};
+/**
+ * Skill entry for available_skills rendering in agent prompts.
+ */
+export interface SkillEntry {
+    metadata: {
+        name: string;
+        version: string;
+        description: string;
+    };
+    filePath: string;
+}
+/**
+ * Options for renderAgentPromptFull().
+ */
+export interface RenderAgentPromptOptions {
+    /** Override layout resolution. Priority: options.layout > agent.inline.layout > project default > SDK default. */
+    layout?: LayoutSpec;
+    /** Override session info (default: { mode: 'query', platform: 'cli' }). */
+    session?: {
+        mode?: string;
+        platform?: string;
+        options?: string[];
+    };
+    /** Override env (default: process.env). */
+    env?: Record<string, string>;
+    /** Override vars (e.g. security_key). Default: auto-generated. */
+    vars?: Record<string, unknown>;
+    /** Skills to inject as available_skills context. Default: []. */
+    skills?: SkillEntry[];
+    /** Conversation history messages for layout rendering (WI-CONV-002). Caller-provided takes priority over auto-fetch. */
+    messages?: TemplateMessage[];
+}
+export declare class Crewx extends TypedEventEmitter {
+    private readonly _agents;
+    private readonly _templateEngine;
+    private readonly _documentLoader;
+    private readonly _layoutLoader;
+    private readonly _layoutRenderer;
+    private readonly _config?;
+    private readonly _projectRoot;
+    private readonly _workspaceId;
+    private readonly _workspaceName;
+    private readonly _plugins;
+    private readonly _tools;
+    private readonly _activeAdapters;
+    private readonly _pendingThreads;
+    /**
+     * Bootstrap factory for target Crewx instances when delegating file:// remote agents.
+     * Consumers (CLI / server / Slack) provide their own bootstrap wrapper so that the
+     * target inherits the same plugin/environment setup as the caller.
+     */
+    private readonly _remoteFactory?;
+    /** Lazily-created target Crewx instances, keyed by absolute configPath. */
+    private readonly _remoteTargets;
+    private constructor();
+    /**
+     * If `agentRef` resolves to a `remote/*` provider backed by `file://`, return
+     * the target Crewx (lazily bootstrapped) together with the agent ref to use
+     * inside the target. Returns null for local agents or non-file remotes.
+     *
+     * The caller's Crewx.query/execute delegates entirely to the returned target
+     * (including task:start/end emit, renderContext, plugins) so execution
+     * semantics exactly match running `crewx q` inside the target workspace.
+     */
+    private resolveFileRemoteTarget;
+    /**
+     * Load crewx.yaml from the given file path and create a Crewx instance.
+     */
+    static loadYaml(path: string, options?: CrewxOptions, fsAdapter?: IFsAdapter): Promise<Crewx>;
+    /**
+     * Create a Crewx instance from an already-parsed config object.
+     */
+    static fromConfig(config: CrewxProjectConfig, options?: CrewxOptions, projectRoot?: string, fsAdapter?: IFsAdapter): Promise<Crewx>;
+    /** All loaded agents, keyed by agent id. */
+    get agents(): ReadonlyMap<string, AgentConfig>;
+    /** The raw project config (includes providers, settings, etc.). */
+    get config(): CrewxProjectConfig | undefined;
+    /** All registered plugins. */
+    get plugins(): readonly CrewxPlugin[];
+    /** All registered custom tools. */
+    get tools(): ReadonlyMap<string, ToolDefinition>;
+    /** Workspace ID (SHA-256 hash). Single source of truth for all plugins. */
+    get workspaceId(): string;
+    /** Human-readable workspace name (basename of cwd). */
+    get workspaceName(): string;
+    /**
+     * Return an agent config by ref (with or without leading '@').
+     * Returns undefined if the agent is not found.
+     */
+    getAgent(agentRef: string): AgentConfig | undefined;
+    /**
+     * Return a remote provider config by provider ID from the crewx.yaml `providers:` section.
+     * Returns undefined if not found or if config has no providers.
+     */
+    getRemoteProviderConfig(providerId: string): RemoteProviderConfig | undefined;
+    private computeTaskLogPath;
+    /**
+     * Register a custom tool for use in agent prompts.
+     *
+     * Registered tools are included in the `tools` context of renderAgentPromptFull(),
+     * and can be invoked programmatically (e.g. in browser environments with API providers).
+     *
+     * @param name - Unique tool name (overwrites if already registered)
+     * @param definition - Tool definition with description, parameters, and execute function
+     */
+    registerTool(name: string, definition: Omit<ToolDefinition, 'name'>): void;
+    /**
+     * Register a plugin and immediately call attach().
+     * Same instance registered twice is silently ignored (by reference).
+     */
+    use(plugin: CrewxPlugin): Promise<void>;
+    /**
+     * Create a Web Standard MCP HTTP handler for exposing agents over the network.
+     *
+     * @param options - Handler config. `agents` list is required for security.
+     * @returns `(req: Request) => Promise<Response>` handler
+     */
+    handler(options: HandlerOptions): CrewxHandler;
+    /**
+     * Register a channel adapter and start it.
+     */
+    registerChannelAdapter<TConfig = unknown>(reg: ChannelAdapterRegistration<TConfig>): Promise<void>;
+    /**
+     * Unregister and stop a channel adapter by instanceId.
+     */
+    unregisterChannelAdapter(instanceId: string): Promise<void>;
+    /**
+     * Stop all registered adapters with a timeout.
+     */
+    stopAllAdapters(opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Detach all plugins in LIFO order and release resources.
+     * Call before process exit for clean shutdown.
+     */
+    close(): Promise<void>;
+    /**
+     * Filter agents by role, team, and/or provider.
+     */
+    filterAgents(filters: {
+        role?: string;
+        team?: string;
+        provider?: string;
+    }): AgentConfig[];
+    /**
+     * Return the raw system prompt for the given agent (no template expansion, no layout).
+     * @throws AgentNotFoundError if agentId is not found
+     */
+    renderAgentPrompt(agentId: string): string;
+    /**
+     * Render a Handlebars template string with the given context.
+     * Documents from crewx.yaml are automatically merged into context.documents.
+     */
+    renderPrompt(template: string, context?: TemplateContext): Promise<string>;
+    /**
+     * Register a custom layout template at runtime.
+     *
+     * @param name     - Layout identifier (used as-is, no forced namespace)
+     * @param template - Handlebars template string or CustomLayoutDefinition
+     */
+    registerLayout(name: string, template: string | CustomLayoutDefinition): void;
+    /**
+     * Render the full agent prompt using the layout system.
+     *
+     * Resolution priority (first match wins):
+     *   1. options.layout           (call-site override)
+     *   2. agent.inline.layout      (agent YAML definition)
+     *   3. config.layouts.default   (project-level default)
+     *   4. SDK built-in default     (crewx/default)
+     *
+     * @param agentId - Agent ID (with or without leading '@')
+     * @param options - Optional layout/session/env/vars overrides
+     * @throws AgentNotFoundError if agentId is not found
+     */
+    renderAgentPromptFull(agentId: string, options?: RenderAgentPromptOptions): Promise<string>;
+    /**
+     * Filter tools by allowed names from agent options (query/execute mode).
+     * If allowedNames is undefined, return all registered tools.
+     */
+    private _filterToolsByMode;
+    /**
+     * Resolve layout spec following the priority order.
+     */
+    private _resolveLayoutSpec;
+    /** Extract the layout ID string from a LayoutSpec. */
+    private _extractLayoutId;
+    /** Extract layout props overrides from agent inline.layout and call-site options. */
+    private _extractLayoutProps;
+    /**
+     * Get the ConversationPlugin's provider for history auto-fetch (WI-CONV-002).
+     * Returns undefined if no ConversationPlugin is registered.
+     */
+    private _getConversationProvider;
+    /**
+     * Auto-fetch conversation history and convert to TemplateMessage[] (WI-CONV-002).
+     * Returns undefined if no threadId, no provider, or fetch fails.
+     */
+    private _fetchHistoryMessages;
+    private emitToolEvents;
+    private tryParseJson;
+    /**
+     * Query an agent with a message.
+     *
+     * Emits task:start (with child pid when available) then task:output per
+     * stdout/stderr line, then task:end on completion or error.
+     */
+    query(agentRef: string, message: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Continue a conversation after providing client-side tool results.
+     *
+     * Called when a previous query() returned status: 'requires_action'.
+     * Feeds the tool result back to the agent and resumes generation.
+     * May return 'requires_action' again if the agent calls another client tool.
+     */
+    continueQuery(threadId: string, toolResults: Array<{
+        toolCallId: string;
+        result: unknown;
+    }>): Promise<QueryResult>;
+    /**
+     * Execute a task with an agent.
+     *
+     * Emits task:start (with child pid when available) then task:output per
+     * stdout/stderr line, then task:end on completion or error.
+     */
+    execute(agentRef: string, message: string, options?: ExecuteOptions): Promise<ExecuteResult>;
+}
+//# sourceMappingURL=Crewx.d.ts.map