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

package/dist/conversation/to-template-messages.d.ts

@@ -0,0 +1,15 @@
+/**
+ * toTemplateMessages — maps ConversationThread messages to TemplateMessage[]
+ * for consumption by the formatConversation block helper.
+ *
+ * Includes SEC-M1 sanitization at the provider boundary:
+ * <, > are entity-escaped to prevent XML structure tag injection in the
+ * <conversation_history> block.
+ */
+import type { ConversationThread, TemplateMessage } from './types';
+/**
+ * Convert a ConversationThread to a TemplateMessage array suitable for
+ * formatConversation block helper consumption.
+ */
+export declare function toTemplateMessages(thread: ConversationThread): TemplateMessage[];
+//# sourceMappingURL=to-template-messages.d.ts.map

package/dist/conversation/to-template-messages.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * toTemplateMessages — maps ConversationThread messages to TemplateMessage[]
+ * for consumption by the formatConversation block helper.
+ *
+ * Includes SEC-M1 sanitization at the provider boundary:
+ * <, > are entity-escaped to prevent XML structure tag injection in the
+ * <conversation_history> block.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toTemplateMessages = toTemplateMessages;
+/**
+ * SEC-M1: sanitize message text to prevent conversation_history XML block pollution.
+ * User input containing </conversation_history> or <system_prompt> could be
+ * misinterpreted by the LLM as breaking out of the structured block.
+ */
+function sanitizeMessageText(text) {
+    if (typeof text !== 'string')
+        return '';
+    return text.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/**
+ * Convert a ConversationThread to a TemplateMessage array suitable for
+ * formatConversation block helper consumption.
+ */
+function toTemplateMessages(thread) {
+    return thread.messages.map(m => ({
+        text: sanitizeMessageText(m.text),
+        isAssistant: m.isAssistant,
+        metadata: m.metadata,
+        files: undefined,
+    }));
+}
+//# sourceMappingURL=to-template-messages.js.map

package/dist/conversation/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Conversation history types — SDK public API for reading/writing thread history.
+ *
+ * **Security (SEC-3):** history content is untrusted user input.
+ * Consumers (e.g. Phase 2 CLI wiring) MUST delimit history from system prompts
+ * using structured blocks (e.g. `[HISTORY START]...[HISTORY END]`).
+ */
+export interface ConversationMessage {
+    id: string;
+    userId?: string;
+    text: string;
+    isAssistant: boolean;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+export type Platform = 'cli' | 'web' | 'api' | `channel/${string}`;
+export interface ConversationThread {
+    threadId: string;
+    /** Immutable after ensureThread — reusing a 'cli' thread as 'channel/slack' is forbidden (P1-6). */
+    platform: Platform;
+    messages: ConversationMessage[];
+    metadata?: {
+        title?: string;
+        firstMessage?: string;
+        lastMessage?: string;
+        messageCount?: number;
+        updatedAt?: number;
+    };
+}
+/**
+ * Template-friendly message shape consumed by formatConversation block helper.
+ * Matches default.yaml L292~303 expected structure.
+ */
+export interface TemplateMessage {
+    text: string;
+    isAssistant: boolean;
+    metadata?: Record<string, unknown>;
+    files?: Array<{
+        name: string;
+        size?: number;
+        localPath?: string;
+    }>;
+}
+export interface FetchHistoryOptions {
+    limit?: number;
+    maxContextLength?: number;
+    /**
+     * Trace ID of the currently running task — excluded from history
+     * to avoid including in-progress turns (SQ2).
+     */
+    currentTraceId?: string;
+}
+/**
+ * Provider interface for reading/writing conversation history.
+ *
+ * **Security (SEC-3):** history content is untrusted user input.
+ * Consumers (Phase 2 CLI wiring) MUST delimit history from system prompts
+ * using structured blocks (e.g. `[HISTORY START]...[HISTORY END]`).
+ */
+export interface IConversationHistoryProvider {
+    /**
+     * Ensure a thread row exists in the threads table.
+     * @param threadId - Recommended: unguessable value (UUID/nanoid).
+     *   WI-C2 Slack environments MUST enforce userId/channelId-based namespace
+     *   isolation in threadId generation policy.
+     */
+    ensureThread(threadId: string, platform: Platform, workspaceId?: string): Promise<void>;
+    /**
+     * Fetch conversation history from the tasks table.
+     *
+     * Filter rules (SQ2, aligned with server thread.service.ts:373):
+     *  - WHERE thread_id = ?
+     *  - AND parent_task_id IS NULL            (exclude chain child tasks)
+     *  - AND (status IN ('done','completed') OR status IS NULL)  (exclude failed/running)
+     *  - AND (if options.currentTraceId) trace_id != currentTraceId
+     *  - ORDER BY started_at ASC
+     *  - LIMIT options.limit ?? 100
+     */
+    fetchHistory(threadId: string, options?: FetchHistoryOptions): Promise<ConversationThread>;
+    /**
+     * Phase 1: update threads metadata only (updated_at, last_message, message_count).
+     * User content is written by SqliteTracingPlugin to tasks.prompt.
+     * userId parameter is a WI-C2 (Slack) extension point.
+     *
+     * **⛔ (SEC-5)** Do NOT pass credentials, env vars, or API keys in metadata —
+     * this data is persisted as JSON in the threads table.
+     */
+    saveUserMessage(threadId: string, text: string, userId?: string, metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * Phase 1: update threads metadata only.
+     * Assistant content is written by SqliteTracingPlugin to tasks.result.
+     * agentId parameter enriches threads metadata only.
+     *
+     * **⛔ (SEC-5)** Do NOT pass credentials, env vars, or API keys in metadata —
+     * this data is persisted as JSON in the threads table.
+     */
+    saveAssistantMessage(threadId: string, text: string, agentId: string, metadata?: Record<string, unknown>): Promise<void>;
+    /** Optional — prevent connection leaks in long-running server/test environments. */
+    close?(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/conversation/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Conversation history types — SDK public API for reading/writing thread history.
+ *
+ * **Security (SEC-3):** history content is untrusted user input.
+ * Consumers (e.g. Phase 2 CLI wiring) MUST delimit history from system prompts
+ * using structured blocks (e.g. `[HISTORY START]...[HISTORY END]`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/esm/agent/resolver.js

@@ -0,0 +1,41 @@
+/**
+ * Agent resolver: looks up an agent from a list by ref.
+ * Supports both bare id ('claude') and @mention format ('@claude').
+ * Falls back to built-in provider shorthands (claude, gemini, copilot, codex).
+ */
+export class AgentNotFoundError extends Error {
+    constructor(agentRef, availableIds) {
+        const available = availableIds.length > 0
+            ? ` Available: ${availableIds.join(', ')}`
+            : '';
+        super(`Agent not found: "${agentRef}".${available}`);
+        this.name = 'AgentNotFoundError';
+    }
+}
+/** Built-in provider shorthands that can be used without a crewx.yaml entry. */
+const BUILTIN_PROVIDERS = {
+    claude: { id: 'claude', provider: 'cli/claude' },
+    gemini: { id: 'gemini', provider: 'cli/gemini' },
+    copilot: { id: 'copilot', provider: 'cli/copilot' },
+    codex: { id: 'codex', provider: 'cli/codex' },
+};
+/**
+ * Resolve an agent by reference.
+ * @param agentRef - Agent reference: '@claude', 'claude', '@my_agent', etc.
+ * @param agents   - List of available agent configs.
+ * @returns The matching AgentConfig.
+ * @throws AgentNotFoundError when no match is found.
+ */
+export function resolveAgent(agentRef, agents) {
+    const agentId = agentRef.startsWith('@') ? agentRef.slice(1) : agentRef;
+    // 1. Look in YAML-defined agents first
+    const agent = agents.find(a => a.id === agentId);
+    if (agent)
+        return agent;
+    // 2. Fall back to built-in provider shorthands
+    const builtin = BUILTIN_PROVIDERS[agentId];
+    if (builtin)
+        return builtin;
+    throw new AgentNotFoundError(agentRef, agents.map(a => a.id));
+}
+//# sourceMappingURL=resolver.js.map

package/dist/esm/boxing/box-storage.interface.js

@@ -0,0 +1,5 @@
+/**
+ * Box storage interfaces — used by SdkBoxService and buildContext.
+ */
+export {};
+//# sourceMappingURL=box-storage.interface.js.map

package/dist/esm/boxing/box.service.js

@@ -0,0 +1,69 @@
+/**
+ * SdkBoxService — manages box creation, retrieval, and listing.
+ */
+import { generateId } from '../utils/id';
+const ID_PATTERN = /^[a-zA-Z0-9._-]+$/;
+export class SdkBoxService {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    listBoxes(threadId) {
+        this.validateId(threadId);
+        const rows = this.storage.listBoxes(threadId);
+        const boxes = rows.map((row) => this.toBoxResponse(row));
+        return { boxes, total: boxes.length };
+    }
+    getBox(threadId, boxId) {
+        this.validateId(threadId);
+        this.validateId(boxId);
+        const row = this.storage.findBox(threadId, boxId);
+        if (!row)
+            return null;
+        return this.toBoxResponse(row);
+    }
+    createBox(threadId, params) {
+        this.validateId(threadId);
+        const id = this.generateBoxId();
+        const createdAt = new Date().toISOString();
+        const row = this.storage.insertBox(threadId, {
+            id,
+            seq: params.seq,
+            firstTaskId: params.firstTaskId,
+            midTaskId: params.midTaskId,
+            lastTaskId: params.lastTaskId,
+            taskCount: params.taskCount,
+            summary: params.summary ?? null,
+            sourceTokens: params.sourceTokens,
+            summaryTokens: params.summaryTokens ?? null,
+            createdAt,
+        });
+        return this.toBoxResponse(row);
+    }
+    toBoxResponse(row) {
+        return {
+            id: row.id,
+            threadId: row.thread_id,
+            seq: row.seq,
+            firstTaskId: row.first_task_id,
+            lastTaskId: row.last_task_id,
+            taskCount: row.task_count,
+            sourceTokens: row.source_tokens,
+            summaryTokens: row.summary_tokens,
+            summary: row.summary,
+            previewFirst: this.storage.getTaskPreview(row.first_task_id, 200),
+            previewMid: this.storage.getTaskPreview(row.mid_task_id, 200),
+            previewLast: this.storage.getTaskPreview(row.last_task_id, 200),
+            createdAt: row.created_at,
+        };
+    }
+    validateId(id) {
+        if (!ID_PATTERN.test(id)) {
+            throw new Error(`Invalid ID format: ${id}`);
+        }
+    }
+    generateBoxId() {
+        return generateId('box');
+    }
+}
+//# sourceMappingURL=box.service.js.map

package/dist/esm/boxing/box.types.js

@@ -0,0 +1,5 @@
+/**
+ * Boxing domain types — Box/Thread/Context types for SDK boxing module.
+ */
+export {};
+//# sourceMappingURL=box.types.js.map

package/dist/esm/boxing/context-builder.js

@@ -0,0 +1,76 @@
+/**
+ * buildContext() — builds hot/warm context windows from thread messages and box summaries.
+ */
+export function buildContext(threadId, taskReader, boxService, params, tokenizer) {
+    const { maxTokens, hotzoneRatio, warmzoneRatio } = params;
+    const hotBudget = maxTokens * hotzoneRatio;
+    const warmBudget = maxTokens * warmzoneRatio;
+    const totalBudget = hotBudget + warmBudget;
+    const tasks = taskReader.getThreadMessages(threadId);
+    const hotMessages = [];
+    let hotTokens = 0;
+    let hotOverflow = false;
+    const taskPairs = [];
+    for (let i = 0; i < tasks.length; i += 2) {
+        const userMsg = tasks[i];
+        const assistantMsg = tasks[i + 1];
+        const prompt = userMsg?.content || '';
+        const result = assistantMsg?.content || '';
+        const tokens = tokenizer.countTokens(prompt + result);
+        const msgs = [];
+        if (userMsg)
+            msgs.push(userMsg);
+        if (assistantMsg)
+            msgs.push(assistantMsg);
+        taskPairs.push({ messages: msgs, tokens });
+    }
+    for (let i = taskPairs.length - 1; i >= 0; i--) {
+        const pair = taskPairs[i];
+        if (hotTokens + pair.tokens > hotBudget) {
+            hotOverflow = true;
+            break;
+        }
+        hotTokens += pair.tokens;
+        hotMessages.unshift(...pair.messages);
+    }
+    const warmBoxes = [];
+    let warmTokens = 0;
+    if (hotOverflow && warmBudget > 0) {
+        try {
+            const { boxes } = boxService.listBoxes(threadId);
+            for (let i = boxes.length - 1; i >= 0; i--) {
+                const box = boxes[i];
+                const tokens = box.summaryTokens ?? box.sourceTokens;
+                if (warmTokens + tokens > warmBudget)
+                    break;
+                warmTokens += tokens;
+                warmBoxes.unshift({
+                    boxId: box.id,
+                    seq: box.seq,
+                    taskCount: box.taskCount,
+                    sourceTokens: box.sourceTokens,
+                    summary: box.summary,
+                    previewFirst: box.previewFirst,
+                    previewMid: box.previewMid,
+                    previewLast: box.previewLast,
+                    createdAt: box.createdAt,
+                });
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && !/not found/i.test(error.message)) {
+                throw error;
+            }
+        }
+    }
+    return {
+        hot: hotMessages,
+        warm: warmBoxes,
+        hotTokens,
+        warmTokens,
+        hotOverflow,
+        totalBudget,
+        config: { maxTokens, hotzoneRatio, warmzoneRatio },
+    };
+}
+//# sourceMappingURL=context-builder.js.map

package/dist/esm/client/CrewxClient.js

@@ -0,0 +1,82 @@
+/**
+ * CrewxClient — Browser client for CrewX SDK.
+ *
+ * Communicates with a server running CrewX SDK via HTTP.
+ * Handles the Client-Intercept pattern automatically:
+ *   registerTool() + query() — that's it.
+ *
+ * @example
+ * ```ts
+ * import { CrewxClient } from '@crewx/sdk/client';
+ *
+ * const crewx = new CrewxClient('http://localhost:3000');
+ * crewx.registerTool('browser_storage_read', {
+ *   execute: async ({ key }) => localStorage.getItem(key),
+ * });
+ *
+ * const result = await crewx.query('assistant', 'read my settings');
+ * console.log(result.data);
+ * ```
+ */
+export class CrewxClient {
+    baseUrl;
+    tools = new Map();
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+    }
+    /**
+     * Register a browser-side tool.
+     * When the server agent calls a tool with this name (and no server-side execute),
+     * CrewxClient automatically runs it locally and sends the result back.
+     */
+    registerTool(name, definition) {
+        this.tools.set(name, definition);
+    }
+    /**
+     * Send a message to an agent.
+     * The requires_action loop is handled automatically — if the agent calls a
+     * client tool, CrewxClient executes it locally and continues the conversation.
+     */
+    async query(agent, message, callbacks) {
+        let response = await this._post('/api/chat', { agent, message });
+        while (response.status === 'requires_action') {
+            const { toolCall, threadId } = response;
+            if (!toolCall)
+                break;
+            const tool = this.tools.get(toolCall.toolName);
+            if (callbacks?.onToolCall) {
+                callbacks.onToolCall(toolCall);
+            }
+            let toolResult;
+            if (tool?.execute) {
+                try {
+                    const raw = await tool.execute(toolCall.args);
+                    toolResult = typeof raw === 'string' ? raw : JSON.stringify(raw);
+                }
+                catch (err) {
+                    toolResult = `Error: ${err.message}`;
+                }
+            }
+            else {
+                toolResult = `Error: No client handler for tool "${toolCall.toolName}"`;
+            }
+            response = await this._post('/api/chat/continue', {
+                threadId,
+                toolCallId: toolCall.toolCallId,
+                result: toolResult,
+            });
+        }
+        return response;
+    }
+    async _post(path, body) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        return res.json();
+    }
+}
+//# sourceMappingURL=CrewxClient.js.map

package/dist/esm/client/index.js

@@ -0,0 +1,2 @@
+export { CrewxClient } from './CrewxClient.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/config/loader.browser.js

@@ -0,0 +1,54 @@
+/**
+ * Browser-safe YAML config loader.
+ * Only parseYamlContent — no file I/O.
+ */
+import { load as loadYaml } from 'js-yaml';
+import { CrewxProjectConfigSchema } from '../types/index.js';
+export class ConfigLoadError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'ConfigLoadError';
+    }
+}
+/**
+ * Parse YAML string into a validated CrewxProjectConfig.
+ */
+export function parseYamlContent(yamlString) {
+    if (!yamlString || typeof yamlString !== 'string' || !yamlString.trim()) {
+        throw new ConfigLoadError('YAML content must be a non-empty string');
+    }
+    let raw;
+    try {
+        raw = loadYaml(yamlString);
+    }
+    catch (err) {
+        throw new ConfigLoadError(`YAML parse error: ${err.message}`, err);
+    }
+    const normalized = normalizeRaw(raw);
+    const result = CrewxProjectConfigSchema.safeParse(normalized);
+    if (!result.success) {
+        throw new ConfigLoadError(`Config validation error: ${result.error.message}`);
+    }
+    return result.data;
+}
+function normalizeRaw(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return { agents: [] };
+    }
+    const obj = raw;
+    if (obj.agents && typeof obj.agents === 'object' && !Array.isArray(obj.agents)) {
+        const agentsMap = obj.agents;
+        const agentsArray = Object.entries(agentsMap).map(([id, cfg]) => {
+            const agentCfg = (cfg && typeof cfg === 'object' ? cfg : {});
+            return { id, ...agentCfg };
+        });
+        return { ...obj, agents: agentsArray };
+    }
+    if (!obj.agents) {
+        return { ...obj, agents: [] };
+    }
+    return obj;
+}
+//# sourceMappingURL=loader.browser.js.map

package/dist/esm/config/loader.js

@@ -0,0 +1,77 @@
+/**
+ * YAML configuration loader for CrewX projects.
+ * Reads crewx.yaml and validates it with Zod schema.
+ */
+import { load as loadYaml } from 'js-yaml';
+import { readFileSync } from 'fs';
+import { CrewxProjectConfigSchema } from '../types';
+export class ConfigLoadError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'ConfigLoadError';
+    }
+}
+/**
+ * Parse YAML string into a validated CrewxProjectConfig.
+ * Converts the agents record (keyed by id) into an array.
+ */
+export function parseYamlContent(yamlString) {
+    if (!yamlString || typeof yamlString !== 'string' || !yamlString.trim()) {
+        throw new ConfigLoadError('YAML content must be a non-empty string');
+    }
+    let raw;
+    try {
+        raw = loadYaml(yamlString);
+    }
+    catch (err) {
+        throw new ConfigLoadError(`YAML parse error: ${err.message}`, err);
+    }
+    // Normalize agents: YAML has agents as a map (Record<id, config>),
+    // but our type uses an array with 'id' field.
+    const normalized = normalizeRaw(raw);
+    const result = CrewxProjectConfigSchema.safeParse(normalized);
+    if (!result.success) {
+        throw new ConfigLoadError(`Config validation error: ${result.error.message}`);
+    }
+    return result.data;
+}
+/**
+ * Load and parse crewx.yaml from a file path.
+ */
+export function loadYamlFile(filePath) {
+    let content;
+    try {
+        content = readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        throw new ConfigLoadError(`Cannot read file: ${filePath}`, err);
+    }
+    return parseYamlContent(content);
+}
+/**
+ * Normalize raw YAML output:
+ * - agents map (Record<id, agentConfig>) → agents array ([{ id, ...agentConfig }])
+ */
+function normalizeRaw(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return { agents: [] };
+    }
+    const obj = raw;
+    // Convert agents map to array
+    if (obj.agents && typeof obj.agents === 'object' && !Array.isArray(obj.agents)) {
+        const agentsMap = obj.agents;
+        const agentsArray = Object.entries(agentsMap).map(([id, cfg]) => {
+            const agentCfg = (cfg && typeof cfg === 'object' ? cfg : {});
+            return { id, ...agentCfg };
+        });
+        return { ...obj, agents: agentsArray };
+    }
+    // agents already array or absent
+    if (!obj.agents) {
+        return { ...obj, agents: [] };
+    }
+    return obj;
+}
+//# sourceMappingURL=loader.js.map

package/dist/esm/events/TypedEventEmitter.js

@@ -0,0 +1,61 @@
+/**
+ * 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 { EventEmitter } from '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)}`);
+        }
+    };
+}
+export class TypedEventEmitter {
+    _emitter = new 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);
+    }
+}
+//# sourceMappingURL=TypedEventEmitter.js.map

package/dist/esm/events/types.js

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=types.js.map