@nxuss/lemma 1.18.1 → 1.19.0

package/sdks/crewai/dist/crewai/src/index.js

@@ -0,0 +1,325 @@
+"use strict";
+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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LemmaCrew = exports.LemmaCrewAgent = void 0;
+const ws_1 = __importDefault(require("ws"));
+const uuid_1 = require("uuid");
+/**
+ * CrewAI Agent integrated with Lemma Router
+ */
+class LemmaCrewAgent {
+    constructor(config) {
+        this.ws = null;
+        this.connected = false;
+        this.pendingTasks = new Map();
+        this.config = {
+            routerUrl: config.routerUrl,
+            agentId: config.agentId,
+            role: config.role,
+            goal: config.goal,
+            backstory: config.backstory || '',
+            capabilities: config.capabilities || ['crewai'],
+            verbose: config.verbose || false,
+            allowDelegation: config.allowDelegation !== false,
+        };
+    }
+    /**
+     * Connect to Lemma router
+     */
+    async connect() {
+        return new Promise((resolve, reject) => {
+            this.ws = new ws_1.default(this.config.routerUrl);
+            this.ws.on('open', () => {
+                this.log('Connected to Lemma router');
+                // Send handshake
+                this.send({
+                    type: 'HANDSHAKE',
+                    messageId: (0, uuid_1.v4)(),
+                    timestamp: Date.now(),
+                    payload: {
+                        agentId: this.config.agentId,
+                        agentName: `${this.config.role} (CrewAI)`,
+                        version: '1.0.0',
+                        capabilities: this.config.capabilities.map(name => ({
+                            name,
+                            version: '1.0.0',
+                        })),
+                        metadata: {
+                            role: this.config.role,
+                            goal: this.config.goal,
+                            backstory: this.config.backstory,
+                            framework: 'crewai',
+                        },
+                    },
+                });
+            });
+            this.ws.on('message', (data) => {
+                try {
+                    const message = JSON.parse(data.toString());
+                    this.handleMessage(message);
+                    if (message.type === 'HANDSHAKE_ACK') {
+                        this.connected = true;
+                        this.log('Handshake acknowledged');
+                        resolve();
+                    }
+                }
+                catch (error) {
+                    console.error('Error parsing message:', error);
+                }
+            });
+            this.ws.on('error', (error) => {
+                console.error('WebSocket error:', error);
+                if (!this.connected) {
+                    reject(error);
+                }
+            });
+            this.ws.on('close', () => {
+                this.connected = false;
+                this.log('Disconnected from router');
+            });
+            // Connection timeout
+            setTimeout(() => {
+                if (!this.connected) {
+                    reject(new Error('Connection timeout'));
+                }
+            }, 10000);
+        });
+    }
+    /**
+     * Disconnect from router
+     */
+    disconnect() {
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+            this.connected = false;
+        }
+    }
+    /**
+     * Execute a task
+     */
+    async execute(task) {
+        if (!this.connected) {
+            throw new Error('Not connected to router. Call connect() first.');
+        }
+        const taskId = (0, uuid_1.v4)();
+        this.log(`Executing task: ${task.description}`);
+        return new Promise((resolve, reject) => {
+            this.pendingTasks.set(taskId, { resolve, reject });
+            // Send task request to router
+            this.send({
+                type: 'TASK_REQUEST',
+                messageId: (0, uuid_1.v4)(),
+                timestamp: Date.now(),
+                payload: {
+                    taskId,
+                    description: task.description,
+                    requiredCapabilities: this.config.capabilities,
+                    parameters: {
+                        expectedOutput: task.expectedOutput,
+                        context: task.context,
+                        allowDelegation: task.allowDelegation ?? this.config.allowDelegation,
+                    },
+                },
+            });
+        });
+    }
+    /**
+     * Handle incoming message from router
+     */
+    handleMessage(message) {
+        switch (message.type) {
+            case 'TASK_ASSIGN':
+                this.handleTaskAssign(message);
+                break;
+            case 'TASK_RESPONSE':
+                this.handleTaskResponse(message);
+                break;
+            case 'PING':
+                this.send({
+                    type: 'PONG',
+                    messageId: (0, uuid_1.v4)(),
+                    timestamp: Date.now(),
+                    payload: {
+                        originalMessageId: message.messageId,
+                    },
+                });
+                break;
+        }
+    }
+    /**
+     * Handle task assignment from router
+     */
+    async handleTaskAssign(message) {
+        const { taskId, description, parameters } = message.payload;
+        const startTime = Date.now();
+        this.log(`Received task assignment: ${description}`);
+        try {
+            // Execute the task (override this method in subclasses)
+            const output = await this.performTask(description, parameters);
+            // Send response back to router
+            this.send({
+                type: 'TASK_RESPONSE',
+                messageId: (0, uuid_1.v4)(),
+                timestamp: Date.now(),
+                payload: {
+                    taskId,
+                    success: true,
+                    result: output,
+                    executionTime: Date.now() - startTime,
+                    taskDescription: description,
+                },
+            });
+        }
+        catch (error) {
+            this.send({
+                type: 'TASK_RESPONSE',
+                messageId: (0, uuid_1.v4)(),
+                timestamp: Date.now(),
+                payload: {
+                    taskId,
+                    success: false,
+                    error: error instanceof Error ? error.message : 'Unknown error',
+                    executionTime: Date.now() - startTime,
+                },
+            });
+        }
+    }
+    /**
+     * Handle task response from router
+     */
+    handleTaskResponse(message) {
+        const { taskId, success, result, error, executionTime, cached, similarity } = message.payload;
+        const pending = this.pendingTasks.get(taskId);
+        if (!pending) {
+            return;
+        }
+        this.pendingTasks.delete(taskId);
+        if (success) {
+            this.log(`Task completed in ${executionTime}ms${cached ? ' (cached)' : ''}`);
+            pending.resolve({
+                success: true,
+                output: result,
+                executionTime,
+                cached,
+                similarity,
+            });
+        }
+        else {
+            pending.reject(new Error(error || 'Task failed'));
+        }
+    }
+    /**
+     * Perform task (override in subclasses)
+     */
+    async performTask(description, parameters) {
+        // Default implementation - subclasses should override
+        return `Task completed: ${description}`;
+    }
+    /**
+     * Send message to router
+     */
+    send(message) {
+        if (!this.ws || !this.connected) {
+            throw new Error('Not connected to router');
+        }
+        this.ws.send(JSON.stringify(message));
+    }
+    /**
+     * Log message if verbose
+     */
+    log(message) {
+        if (this.config.verbose) {
+            console.log(`[${this.config.role}] ${message}`);
+        }
+    }
+    /**
+     * Get agent info
+     */
+    getInfo() {
+        return {
+            agentId: this.config.agentId,
+            role: this.config.role,
+            goal: this.config.goal,
+            backstory: this.config.backstory,
+            capabilities: this.config.capabilities,
+        };
+    }
+}
+exports.LemmaCrewAgent = LemmaCrewAgent;
+class LemmaCrew {
+    constructor(config) {
+        this.agents = [];
+        this.config = config;
+        // Create agents
+        this.agents = config.agents.map(agentConfig => new LemmaCrewAgent({
+            ...agentConfig,
+            routerUrl: config.routerUrl,
+            verbose: config.verbose,
+        }));
+    }
+    /**
+     * Connect all agents
+     */
+    async connect() {
+        await Promise.all(this.agents.map(agent => agent.connect()));
+    }
+    /**
+     * Disconnect all agents
+     */
+    disconnect() {
+        this.agents.forEach(agent => agent.disconnect());
+    }
+    /**
+     * Execute a multi-agent workflow
+     */
+    async kickoff(options) {
+        const { task, process = 'sequential' } = options;
+        if (process === 'sequential') {
+            // Execute tasks sequentially through agents
+            let result = task;
+            for (const agent of this.agents) {
+                const taskResult = await agent.execute({
+                    description: result,
+                });
+                result = taskResult.output || result;
+            }
+            return result;
+        }
+        else {
+            // Hierarchical - first agent coordinates others
+            const manager = this.agents[0];
+            return await manager.execute({
+                description: task,
+                allowDelegation: true,
+            });
+        }
+    }
+    /**
+     * Get all agents
+     */
+    getAgents() {
+        return this.agents;
+    }
+}
+exports.LemmaCrew = LemmaCrew;
+exports.default = LemmaCrewAgent;
+// Lemma /v2 Verifiable Memory API — a separate surface from LemmaCrewAgent
+// above (that talks to the WebSocket orchestration router). See memory.ts.
+__exportStar(require("./memory"), exports);

package/sdks/crewai/dist/crewai/src/memory.d.ts

@@ -0,0 +1,36 @@
+import type { LemmaClientOptions } from '../../ts/src/index';
+import type { MemoryState, VerifiedResult } from '../../ts/src/types';
+export interface LemmaMemoryToolConfig extends Omit<LemmaClientOptions, 'apiKey'> {
+    apiKey: string;
+    rootDir?: string;
+}
+export interface LemmaMemoryRecallResult {
+    state: MemoryState;
+    staleFiles?: string[];
+    results: VerifiedResult[];
+}
+export type LemmaMemoryToolInput = {
+    action: 'remember';
+    text: string;
+    filePaths?: string[];
+} | {
+    action: 'recall';
+    query: string;
+    filePaths?: string[];
+};
+/**
+ * A CrewAI-style tool: `name`, `description`, and an async `func` an agent
+ * calls directly. `func` never collapses the result to a string — a
+ * `'recall'` call returns `{ state, staleFiles, results }`, so the crew can
+ * branch on `state === 'stale'` instead of parsing prose.
+ */
+export declare class LemmaMemoryTool {
+    readonly name = "lemma_memory";
+    readonly description: string;
+    private readonly client;
+    private readonly rootDir;
+    constructor(config: LemmaMemoryToolConfig);
+    func(input: LemmaMemoryToolInput): Promise<{
+        id: string;
+    } | LemmaMemoryRecallResult>;
+}

package/sdks/crewai/dist/crewai/src/memory.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LemmaMemoryTool = void 0;
+/**
+ * Lemma memory tool for CrewAI (Lane H).
+ *
+ * Separate surface from `LemmaCrewConfig`/task-execution code in `index.ts`
+ * (that talks to the WebSocket orchestration router, an unrelated pre-existing
+ * product surface) — this wraps the `/v2` Verifiable Memory API on top of
+ * `@nxuss/lemma-sdk`. Shaped as a CrewAI-style tool: `name` + `description`
+ * + an async `func`, the calling convention CrewAI tools use so an agent can
+ * invoke it directly — and, per the plan, `func('recall', ...)` returns
+ * `state` as a first-class field, never hidden behind prose the agent has to
+ * re-interpret.
+ */
+const index_1 = require("../../ts/src/index");
+const STATE_SEVERITY = {
+    contradicted: 3,
+    stale: 2,
+    unverified: 1,
+    fresh: 0,
+};
+function worstState(results) {
+    if (results.length === 0)
+        return 'unverified';
+    return results.reduce((worst, r) => (STATE_SEVERITY[r.state] > STATE_SEVERITY[worst] ? r.state : worst), 'fresh');
+}
+/**
+ * A CrewAI-style tool: `name`, `description`, and an async `func` an agent
+ * calls directly. `func` never collapses the result to a string — a
+ * `'recall'` call returns `{ state, staleFiles, results }`, so the crew can
+ * branch on `state === 'stale'` instead of parsing prose.
+ */
+class LemmaMemoryTool {
+    constructor(config) {
+        this.name = 'lemma_memory';
+        this.description = 'Store and recall verifiable memories about this codebase. Every recall returns a `state` ' +
+            '(fresh/stale/unverified/contradicted) proven against the current code — never a guess.';
+        const { rootDir, ...clientOptions } = config;
+        this.client = new index_1.LemmaClient(clientOptions);
+        this.rootDir = rootDir ?? process.cwd();
+    }
+    async func(input) {
+        if (input.action === 'remember') {
+            const evidence = (0, index_1.collectEvidence)({ rootDir: this.rootDir, files: input.filePaths ?? [] });
+            const res = await this.client.remember({
+                claims: [{ text: input.text, filePaths: input.filePaths }],
+                evidence,
+            });
+            return { id: res.id };
+        }
+        const evidence = (0, index_1.collectEvidence)({ rootDir: this.rootDir, files: input.filePaths ?? [] });
+        const res = await this.client.recall({ query: input.query, currentEvidence: evidence });
+        return {
+            state: worstState(res.results),
+            staleFiles: res.results.flatMap((r) => r.staleFiles ?? []),
+            results: res.results,
+        };
+    }
+}
+exports.LemmaMemoryTool = LemmaMemoryTool;

package/sdks/crewai/dist/ts/src/client.d.ts

@@ -0,0 +1,39 @@
+import type { CreateMemoryRequest, CreateMemoryResponse, RecallRequest, RecallResponse, VerifyRequest, VerifyResponse, ForgetResponse, ScrubRequest, ScrubResponse, UsageResponse } from './types';
+export interface LemmaClientOptions {
+    apiKey: string;
+    /** Defaults to the production /v2 base URL. Point at a local server in dev. */
+    baseUrl?: string;
+    /** Per-request timeout. Defaults to 10s. */
+    timeoutMs?: number;
+    /** Retries for 429 (honoring Retry-After) and transient network/5xx failures. Defaults to 3. */
+    maxRetries?: number;
+    /** Injectable for tests; defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Injectable for tests; avoids real sleeps in the backoff test. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare class LemmaClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    private readonly sleep;
+    constructor(options: LemmaClientOptions);
+    /** Store a memory: claims + the evidence they're grounded in (see `collectEvidence`). */
+    remember(request: CreateMemoryRequest): Promise<CreateMemoryResponse>;
+    /** Search; every result comes back with a verified `state`, never a guess. */
+    recall(request: RecallRequest): Promise<RecallResponse>;
+    /** Batch-resolve freshness for known ids without a search round-trip. */
+    verify(request: VerifyRequest): Promise<VerifyResponse>;
+    /** Permanently forget a memory, scoped to your tenant. */
+    forget(id: string): Promise<ForgetResponse>;
+    /** Stateless secret-scrubbing pass over text or a serialized tool-call. */
+    scrub(request: ScrubRequest): Promise<ScrubResponse>;
+    /** Real, counted usage for your tenant — never an estimate. */
+    usage(): Promise<UsageResponse>;
+    /** Masked — never prints the raw key, including via `console.log`. */
+    toString(): string;
+    private request;
+}
+export default LemmaClient;

package/sdks/crewai/dist/ts/src/client.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LemmaClient = void 0;
+const errors_1 = require("./errors");
+const DEFAULT_BASE_URL = 'https://api.lemma.dev/v2';
+const DEFAULT_TIMEOUT_MS = 10000;
+const DEFAULT_MAX_RETRIES = 3;
+/** Cap for exponential backoff on transient (network/5xx) failures. */
+const MAX_BACKOFF_MS = 8000;
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isRetryableStatus(status) {
+    return status === 429 || status >= 500;
+}
+/** LemmaClient never logs or exposes the raw key past construction. */
+function maskKey(key) {
+    if (key.length <= 12)
+        return '***';
+    return `${key.slice(0, 8)}...${key.slice(-4)}`;
+}
+class LemmaClient {
+    constructor(options) {
+        if (!options.apiKey) {
+            throw new errors_1.LemmaSdkError({ code: 'invalid_request', message: 'apiKey is required' });
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.sleep = options.sleep ?? defaultSleep;
+    }
+    /** Store a memory: claims + the evidence they're grounded in (see `collectEvidence`). */
+    async remember(request) {
+        return this.request('POST', '/memories', request);
+    }
+    /** Search; every result comes back with a verified `state`, never a guess. */
+    async recall(request) {
+        return this.request('POST', '/recall', request);
+    }
+    /** Batch-resolve freshness for known ids without a search round-trip. */
+    async verify(request) {
+        return this.request('POST', '/verify', request);
+    }
+    /** Permanently forget a memory, scoped to your tenant. */
+    async forget(id) {
+        return this.request('DELETE', `/memories/${encodeURIComponent(id)}`);
+    }
+    /** Stateless secret-scrubbing pass over text or a serialized tool-call. */
+    async scrub(request) {
+        return this.request('POST', '/scrub', request);
+    }
+    /** Real, counted usage for your tenant — never an estimate. */
+    async usage() {
+        return this.request('GET', '/usage');
+    }
+    /** Masked — never prints the raw key, including via `console.log`. */
+    toString() {
+        return `LemmaClient(baseUrl=${this.baseUrl}, apiKey=${maskKey(this.apiKey)})`;
+    }
+    /** Node's console.log/util.inspect path — masked for the same reason as toString(). */
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return this.toString();
+    }
+    async request(method, path, body) {
+        let attempt = 0;
+        while (true) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            let res;
+            try {
+                res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                    method,
+                    headers: {
+                        Authorization: `Bearer ${this.apiKey}`,
+                        'Content-Type': 'application/json',
+                    },
+                    body: body !== undefined ? JSON.stringify(body) : undefined,
+                    signal: controller.signal,
+                });
+            }
+            catch (err) {
+                clearTimeout(timer);
+                const isAbort = err instanceof Error && err.name === 'AbortError';
+                if (attempt < this.maxRetries) {
+                    await this.sleep(backoffMs(attempt));
+                    attempt++;
+                    continue;
+                }
+                throw new errors_1.LemmaSdkError({
+                    code: isAbort ? 'timeout' : 'network_error',
+                    message: isAbort ? `request timed out after ${this.timeoutMs}ms` : `network error: ${err.message}`,
+                });
+            }
+            clearTimeout(timer);
+            if (res.ok) {
+                return (await res.json());
+            }
+            const bodyJson = (await res.json().catch(() => null));
+            const apiError = bodyJson?.error;
+            if (isRetryableStatus(res.status) && attempt < this.maxRetries) {
+                const retryAfterHeader = res.headers.get('Retry-After');
+                const waitMs = retryAfterHeader ? Number(retryAfterHeader) * 1000 : backoffMs(attempt);
+                await this.sleep(Number.isFinite(waitMs) && waitMs > 0 ? waitMs : backoffMs(attempt));
+                attempt++;
+                continue;
+            }
+            throw new errors_1.LemmaSdkError({
+                code: apiError?.code ?? 'internal',
+                message: apiError?.message ?? `request failed with status ${res.status}`,
+                status: res.status,
+                field: apiError?.field,
+                retryAfter: res.headers.get('Retry-After') ? Number(res.headers.get('Retry-After')) : undefined,
+            });
+        }
+    }
+}
+exports.LemmaClient = LemmaClient;
+/** Exponential backoff (200ms, 400ms, 800ms, ...) capped at MAX_BACKOFF_MS. */
+function backoffMs(attempt) {
+    return Math.min(200 * 2 ** attempt, MAX_BACKOFF_MS);
+}
+exports.default = LemmaClient;

package/sdks/crewai/dist/ts/src/errors.d.ts

@@ -0,0 +1,19 @@
+import type { LemmaErrorCode } from './types';
+/**
+ * Typed error thrown by every LemmaClient method. Carries the API's stable
+ * `code` so callers can branch on it instead of parsing `message`.
+ */
+export declare class LemmaSdkError extends Error {
+    readonly code: LemmaErrorCode | 'network_error' | 'timeout';
+    readonly status?: number;
+    readonly field?: string;
+    /** Present on `rate_limited` — seconds the server asked the client to wait. */
+    readonly retryAfter?: number;
+    constructor(opts: {
+        code: LemmaErrorCode | 'network_error' | 'timeout';
+        message: string;
+        status?: number;
+        field?: string;
+        retryAfter?: number;
+    });
+}

package/sdks/crewai/dist/ts/src/errors.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LemmaSdkError = void 0;
+/**
+ * Typed error thrown by every LemmaClient method. Carries the API's stable
+ * `code` so callers can branch on it instead of parsing `message`.
+ */
+class LemmaSdkError extends Error {
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'LemmaSdkError';
+        this.code = opts.code;
+        this.status = opts.status;
+        this.field = opts.field;
+        this.retryAfter = opts.retryAfter;
+    }
+}
+exports.LemmaSdkError = LemmaSdkError;

package/sdks/crewai/dist/ts/src/evidence.d.ts

@@ -0,0 +1,30 @@
+import type { Evidence } from './types';
+/** sha256 of a whole file's utf8 content. `'MISSING'` if it can't be read. */
+export declare function hashFile(rootDir: string, relPath: string): string;
+/** Token-stream normalization: strips comments/whitespace, keeps semantics. */
+export declare function normalizeForFreshness(source: string): string;
+/** Raw + normalized sha256 pair for one symbol. `'MISSING'`/`'MISSING'` if unreadable or not found. */
+export declare function hashSymbol(rootDir: string, relPath: string, symbolName: string): {
+    raw: string;
+    normalized: string;
+};
+export interface CollectEvidenceOptions {
+    /** Directory relative paths are resolved against. Defaults to `process.cwd()`. */
+    rootDir?: string;
+    /** Relative file paths to hash whole. */
+    files?: string[];
+    /** Symbols to hash (raw + normalized), one file per symbol. */
+    symbols?: Array<{
+        filePath: string;
+        symbolName: string;
+    }>;
+    branch?: string;
+    commit?: string;
+}
+/**
+ * Builds an `Evidence` bundle the way a client is expected to: hash the files
+ * and symbols it's about to make claims about, right before sending them.
+ * Identical algorithm to the local MCP Brain's `LocalFsResolver` — see the
+ * module doc.
+ */
+export declare function collectEvidence(options: CollectEvidenceOptions): Evidence;