@nxuss/lemma 1.18.1 → 1.18.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxuss/lemma",
-  "version": "1.18.1",
+  "version": "1.18.2",
   "description": "Intelligent AI Gateway for IDEs & Agents — Semantic cache, Privacy Firewall, Infrastructure Command Center, and Autonomous Cost-Optimization.",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -179,6 +179,7 @@
     "express": "^4.18.2",
     "openai": "^6.37.0",
     "pg": "^8.11.0",
+    "shell-quote": "^1.10.0",
     "socket.io": "^4.7.2",
     "typescript": "^5.3.3",
     "uuid": "^14.0.0"
@@ -195,6 +196,7 @@
     "@types/jest": "^29.5.11",
     "@types/node": "^20.11.0",
     "@types/pg": "^8.20.0",
+    "@types/shell-quote": "^1.7.5",
     "@types/uuid": "^10.0.0",
     "@types/ws": "^8.5.10",
     "jest": "^29.7.0",

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

@@ -0,0 +1,131 @@
+/**
+ * Lemma Crew Configuration
+ */
+export interface LemmaCrewConfig {
+    /** WebSocket URL of the Lemma router */
+    routerUrl: string;
+    /** Agent ID */
+    agentId: string;
+    /** Agent role (CrewAI concept) */
+    role: string;
+    /** Agent goal */
+    goal: string;
+    /** Agent backstory */
+    backstory?: string;
+    /** Capabilities this agent provides */
+    capabilities?: string[];
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /** Allow task delegation */
+    allowDelegation?: boolean;
+}
+/**
+ * Task execution request
+ */
+export interface TaskRequest {
+    description: string;
+    expectedOutput?: string;
+    context?: any;
+    allowDelegation?: boolean;
+}
+/**
+ * Task execution result
+ */
+export interface TaskResult {
+    success: boolean;
+    output?: string;
+    error?: string;
+    executionTime: number;
+    cached?: boolean;
+    similarity?: number;
+}
+/**
+ * CrewAI Agent integrated with Lemma Router
+ */
+export declare class LemmaCrewAgent {
+    private ws;
+    private config;
+    private connected;
+    private pendingTasks;
+    constructor(config: LemmaCrewConfig);
+    /**
+     * Connect to Lemma router
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from router
+     */
+    disconnect(): void;
+    /**
+     * Execute a task
+     */
+    execute(task: TaskRequest): Promise<TaskResult>;
+    /**
+     * Handle incoming message from router
+     */
+    private handleMessage;
+    /**
+     * Handle task assignment from router
+     */
+    private handleTaskAssign;
+    /**
+     * Handle task response from router
+     */
+    private handleTaskResponse;
+    /**
+     * Perform task (override in subclasses)
+     */
+    protected performTask(description: string, parameters: any): Promise<string>;
+    /**
+     * Send message to router
+     */
+    private send;
+    /**
+     * Log message if verbose
+     */
+    private log;
+    /**
+     * Get agent info
+     */
+    getInfo(): {
+        agentId: string;
+        role: string;
+        goal: string;
+        backstory: string;
+        capabilities: string[];
+    };
+}
+/**
+ * Lemma Crew - Multi-agent orchestration
+ */
+export interface LemmaCrewOptions {
+    routerUrl: string;
+    agents: Omit<LemmaCrewConfig, 'routerUrl'>[];
+    verbose?: boolean;
+}
+export declare class LemmaCrew {
+    private agents;
+    private config;
+    constructor(config: LemmaCrewOptions);
+    /**
+     * Connect all agents
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect all agents
+     */
+    disconnect(): void;
+    /**
+     * Execute a multi-agent workflow
+     */
+    kickoff(options: {
+        task: string;
+        process?: 'sequential' | 'hierarchical';
+    }): Promise<any>;
+    /**
+     * Get all agents
+     */
+    getAgents(): LemmaCrewAgent[];
+}
+export default LemmaCrewAgent;
+export * from './memory';

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;