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

package/dist/esm/utils/glob-match.js

@@ -0,0 +1,38 @@
+/**
+ * Glob pattern matching utilities.
+ * Shared by exec helper (security allow/deny) and agent ls filter.
+ *
+ * '*'  — matches any characters within a single path segment (non-'/').
+ * '**' — matches any characters including '/'.
+ */
+/**
+ * Converts a glob pattern to a RegExp.
+ * Handles path-based matching (split by '/') consistent with minimatch behavior.
+ */
+export function globToRegex(pattern) {
+    const escape = (s) => s.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    const parts = pattern.split('/');
+    const regexParts = parts.map(part => {
+        if (part === '**') {
+            return '.*';
+        }
+        return part
+            .split('*')
+            .map(escape)
+            .join('[^/]*');
+    });
+    return new RegExp(`^${regexParts.join('\\/')}$`);
+}
+/**
+ * Checks if a value matches a glob pattern.
+ * Returns false on any regex construction error.
+ */
+export function matchesPattern(value, pattern) {
+    try {
+        return globToRegex(pattern).test(value);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=glob-match.js.map

package/dist/esm/utils/id.js

@@ -0,0 +1,46 @@
+/**
+ * ID generation utilities.
+ * Backward-compatible with packages that import generateId from @crewx/sdk.
+ */
+import { randomBytes } from 'crypto';
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+function randomBase62(length) {
+    const bytes = randomBytes(length * 2);
+    let result = '';
+    for (let i = 0; i < bytes.length && result.length < length; i++) {
+        const byte = bytes[i];
+        if (byte < 248) {
+            result += ALPHABET[byte % 62];
+        }
+    }
+    // Fill remaining with fallback
+    while (result.length < length) {
+        result += ALPHABET[randomBytes(1)[0] % 62];
+    }
+    return result;
+}
+/**
+ * Generate a random prefixed ID.
+ * @example generateId('tsk') // → "tsk_V1StGXR8"
+ */
+export function generateId(prefix) {
+    return `${prefix}_${randomBase62(8)}`;
+}
+/**
+ * Generate a deterministic fingerprint ID from a string input.
+ */
+export function generateFingerprint(prefix, input) {
+    const { createHash } = require('crypto');
+    const hash = createHash('sha256').update(input).digest();
+    // XOR-fold 32 bytes into 8 bytes
+    const folded = Buffer.alloc(8);
+    for (let i = 0; i < 32; i++) {
+        folded[i % 8] ^= hash[i];
+    }
+    let result = '';
+    for (const byte of folded) {
+        result += ALPHABET[byte % 62];
+    }
+    return `${prefix}_${result}`;
+}
+//# sourceMappingURL=id.js.map

package/dist/esm/utils/workspace.js

@@ -0,0 +1,21 @@
+/**
+ * Workspace path normalization and hashing utilities.
+ */
+import * as path from 'path';
+import { createHash } from 'crypto';
+export function normalizeWorkspacePath(workspacePath) {
+    let resolved = path.resolve(workspacePath);
+    if (process.platform === 'win32') {
+        resolved = resolved.replace(/\\/g, '/');
+        resolved = resolved.replace(/^([A-Z]):/, (_match, drive) => `${drive.toLowerCase()}:`);
+    }
+    if (resolved.length > 1 && !/^[a-zA-Z]:\/$/.test(resolved)) {
+        resolved = resolved.replace(/\/+$/, '');
+    }
+    return resolved;
+}
+export function hashWorkspaceId(workspacePath) {
+    const normalizedPath = normalizeWorkspacePath(workspacePath);
+    return createHash('sha256').update(normalizedPath).digest('hex');
+}
+//# sourceMappingURL=workspace.js.map

package/dist/events/TypedEventEmitter.d.ts

@@ -0,0 +1,31 @@
+/**
+ * TypedEventEmitter — typed wrapper around Node's EventEmitter.
+ *
+ * Design:
+ * - `on` / `once` are public (callers subscribe)
+ * - `emit` is protected (only subclasses like Crewx can emit)
+ * - Async listeners are supported (fire-and-forget, errors isolated)
+ * - Returns an UnsubscribeFn from on/once for easy cleanup
+ */
+import type { CrewxEventName, CrewxEventPayload, UnsubscribeFn } from './types';
+export declare class TypedEventEmitter {
+    private readonly _emitter;
+    /**
+     * Subscribe to an event. Returns an unsubscribe function.
+     *
+     * @example
+     * const unsub = crewx.on('task:start', (e) => console.log(e.agentRef));
+     * // later:
+     * unsub();
+     */
+    on<K extends CrewxEventName>(event: K, listener: (payload: CrewxEventPayload<K>) => void | Promise<void>): UnsubscribeFn;
+    /**
+     * Subscribe to an event exactly once.
+     */
+    once<K extends CrewxEventName>(event: K, listener: (payload: CrewxEventPayload<K>) => void | Promise<void>): UnsubscribeFn;
+    /**
+     * Emit an event with payload. Only accessible to subclasses.
+     */
+    protected emit<K extends CrewxEventName>(event: K, payload: CrewxEventPayload<K>): void;
+}
+//# sourceMappingURL=TypedEventEmitter.d.ts.map

package/dist/events/TypedEventEmitter.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * TypedEventEmitter — typed wrapper around Node's EventEmitter.
+ *
+ * Design:
+ * - `on` / `once` are public (callers subscribe)
+ * - `emit` is protected (only subclasses like Crewx can emit)
+ * - Async listeners are supported (fire-and-forget, errors isolated)
+ * - Returns an UnsubscribeFn from on/once for easy cleanup
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypedEventEmitter = void 0;
+const events_1 = require("events");
+/**
+ * Wraps a listener to isolate errors and support async fire-and-forget.
+ */
+function makeSafeListener(event, listener) {
+    return (payload) => {
+        try {
+            const result = listener(payload);
+            if (result instanceof Promise) {
+                result.catch((err) => {
+                    // Fire-and-forget: isolate async listener errors
+                    console.error(`[crewx] event listener error (${event}): ${err instanceof Error ? err.message : String(err)}`);
+                });
+            }
+        }
+        catch (err) {
+            // Synchronous listener error — log and continue
+            console.error(`[crewx] event listener error (${event}): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+}
+class TypedEventEmitter {
+    _emitter = new events_1.EventEmitter();
+    /**
+     * Subscribe to an event. Returns an unsubscribe function.
+     *
+     * @example
+     * const unsub = crewx.on('task:start', (e) => console.log(e.agentRef));
+     * // later:
+     * unsub();
+     */
+    on(event, listener) {
+        const safeListener = makeSafeListener(event, listener);
+        this._emitter.on(event, safeListener);
+        return () => this._emitter.off(event, safeListener);
+    }
+    /**
+     * Subscribe to an event exactly once.
+     */
+    once(event, listener) {
+        const safeListener = makeSafeListener(event, listener);
+        this._emitter.once(event, safeListener);
+        return () => this._emitter.off(event, safeListener);
+    }
+    /**
+     * Emit an event with payload. Only accessible to subclasses.
+     */
+    emit(event, payload) {
+        this._emitter.emit(event, payload);
+    }
+}
+exports.TypedEventEmitter = TypedEventEmitter;
+//# sourceMappingURL=TypedEventEmitter.js.map

package/dist/events/types.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Event types for the CrewX SDK event system.
+ *
+ * SDK emits events; callers (CLI, users) subscribe to persist or react.
+ * No DB dependencies in the SDK — storage is the caller's responsibility.
+ */
+import type { Platform } from '../conversation/types';
+/** Base fields present on every event. */
+export interface BaseEvent {
+    /** Unique trace ID for correlating start/end events. Format: tsk_XXXXXXXX */
+    traceId: string;
+    /** Event timestamp */
+    timestamp: Date;
+}
+/** Emitted when a query() or execute() call begins. */
+export interface TaskStartEvent extends BaseEvent {
+    /** Agent reference (e.g. "@claude", "claude") */
+    agentRef: string;
+    /** The message/prompt being sent */
+    message: string;
+    /** "query" or "execute" */
+    mode: 'query' | 'execute';
+    /** PID of the spawned child process (undefined for non-process providers) */
+    pid?: number;
+    /** Effective model used (e.g. "claude-sonnet-4-6") */
+    model?: string;
+    /** Provider string (e.g. "cli/claude") */
+    provider?: string;
+    /** Full CLI command spawned (e.g. "claude -p ... --output-format stream-json") */
+    codingAgentCommand?: string;
+    /** Full rendered agent system prompt (Handlebars-rendered) */
+    renderedPrompt?: string;
+    /** Extra metadata (e.g. { provider: "cli/claude" }) */
+    metadata?: Record<string, unknown>;
+    /** Conversation thread ID */
+    threadId?: string;
+    /** Platform origin. Defaults to 'cli'. */
+    platform?: Platform;
+    /** Workspace ID (SHA-256 hash of normalized cwd). Single source of truth from Crewx instance. */
+    workspaceId?: string;
+    /** Human-readable workspace name (basename of cwd). */
+    workspaceName?: string;
+}
+/** Emitted when a query() or execute() call completes (success or failure). */
+export interface TaskEndEvent extends BaseEvent {
+    /** Agent reference */
+    agentRef: string;
+    /** "query" or "execute" */
+    mode: 'query' | 'execute';
+    /** Result data (on success) */
+    result?: string;
+    /** Elapsed time in milliseconds */
+    durationMs: number;
+    /** Error info (on failure) */
+    error?: {
+        code: string;
+        message: string;
+    };
+    /** Provider process exit code (0 = success) */
+    exitCode?: number;
+    /** Total input tokens consumed */
+    inputTokens?: number;
+    /** Total output tokens consumed */
+    outputTokens?: number;
+    /** Cache-read input tokens */
+    cachedInputTokens?: number;
+    /** Total cost in USD */
+    costUsd?: number;
+    /** Actual model used (may differ from agent config when resolved at runtime) */
+    model?: string;
+    /** Extra metadata propagated from QueryOptions/ExecuteOptions.metadata (e.g. workflow info) */
+    metadata?: Record<string, unknown>;
+}
+/** Emitted for each output line from the provider process. */
+export interface TaskOutputEvent extends BaseEvent {
+    /** Agent reference */
+    agentRef: string;
+    /** One line of raw output */
+    output: string;
+    /** Output stream origin */
+    level?: 'stdout' | 'stderr' | 'info';
+}
+export interface ToolBeforeEvent extends BaseEvent {
+    agentRef: string;
+    agentId: string;
+    threadId: string;
+    sessionId: string;
+    provider: string;
+    tool: {
+        name: string;
+        rawName: string;
+        input: unknown;
+        toolUseId?: string;
+    };
+}
+export interface ToolAfterEvent extends BaseEvent {
+    agentRef: string;
+    agentId: string;
+    threadId: string;
+    sessionId: string;
+    provider: string;
+    tool: {
+        name: string;
+        rawName: string;
+        toolUseId?: string;
+        result?: string;
+        isError?: boolean;
+    };
+}
+export interface AdapterLifecycleEvent {
+    adapterId: string;
+    instanceId: string;
+    state: 'starting' | 'started' | 'stopping' | 'stopped' | 'failed';
+    error?: Error;
+    timestamp: Date;
+}
+export interface AdapterMessageEvent {
+    adapterId: string;
+    instanceId: string;
+    direction: 'inbound' | 'outbound';
+    messageId: string;
+    threadId: string;
+    timestamp: Date;
+}
+/** All events emitted by the Crewx SDK. */
+export interface CrewxEvents {
+    'task:start': TaskStartEvent;
+    'task:end': TaskEndEvent;
+    'task:output': TaskOutputEvent;
+    'tool:observed:before': ToolBeforeEvent;
+    'tool:observed:after': ToolAfterEvent;
+    'adapter:lifecycle': AdapterLifecycleEvent;
+    'adapter:message': AdapterMessageEvent;
+}
+export type CrewxEventName = keyof CrewxEvents;
+export type CrewxEventPayload<K extends CrewxEventName> = CrewxEvents[K];
+/** Call to remove a specific event listener. */
+export type UnsubscribeFn = () => void;
+//# sourceMappingURL=types.d.ts.map

package/dist/events/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Event types for the CrewX SDK event system.
+ *
+ * SDK emits events; callers (CLI, users) subscribe to persist or react.
+ * No DB dependencies in the SDK — storage is the caller's responsibility.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/facade/Crewx.browser.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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.
+ */
+import type { AgentConfig, CrewxProjectConfig, QueryOptions as BaseQueryOptions, QueryResult, ExecuteOptions, ExecuteResult } from '../types/index.js';
+/**
+ * Definition for a custom tool that can be registered via crewx.registerTool().
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters?: Record<string, unknown>;
+    execute: (args: Record<string, unknown>) => Promise<unknown>;
+}
+/** Extended query options with browser streaming callback. */
+export interface BrowserQueryOptions extends BaseQueryOptions {
+    onOutput?: (partial: string) => void;
+}
+/** Options for Crewx.fromConfig() in the browser environment. */
+export interface BrowserFromConfigOptions {
+    /** Progress callback for model loading (web-llm). */
+    onProgress?: (report: {
+        progress?: number;
+        text?: string;
+    }) => void;
+    /** API key for OpenRouter provider. Required when any agent uses api/openrouter. */
+    openrouterApiKey?: string;
+}
+export declare class Crewx {
+    private readonly _agents;
+    private readonly _config?;
+    private readonly _tools;
+    private readonly _apiProviders;
+    private constructor();
+    /**
+     * 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 fromConfig(config: CrewxProjectConfig, options?: BrowserFromConfigOptions): Promise<Crewx>;
+    /**
+     * Load web-llm from CDN, create the inference engine, and store
+     * the provider runtime.  Called automatically by fromConfig().
+     */
+    private _initWebLLM;
+    /**
+     * Initialise the OpenRouter API provider.
+     * Uses fetch + SSE streaming against the OpenAI-compatible endpoint.
+     */
+    private _initOpenRouter;
+    get agents(): ReadonlyMap<string, AgentConfig>;
+    get config(): CrewxProjectConfig | undefined;
+    get tools(): ReadonlyMap<string, ToolDefinition>;
+    registerTool(name: string, definition: Omit<ToolDefinition, 'name'>): void;
+    /**
+     * Query an agent with a message.
+     * Browser version — delegates directly to the registered provider factory.
+     * Passes onOutput through for streaming support.
+     */
+    query(agentRef: string, message: string, options?: BrowserQueryOptions): Promise<QueryResult>;
+    /**
+     * Execute a task with an agent.
+     * Browser version — same delegation pattern as query().
+     */
+    execute(agentRef: string, message: string, options?: ExecuteOptions): Promise<ExecuteResult>;
+}
+//# sourceMappingURL=Crewx.browser.d.ts.map