@nxuss/lemma 1.18.1 → 1.18.2

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;

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

@@ -0,0 +1,175 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashFile = hashFile;
+exports.normalizeForFreshness = normalizeForFreshness;
+exports.hashSymbol = hashSymbol;
+exports.collectEvidence = collectEvidence;
+/**
+ * Client-side evidence hashing.
+ *
+ * Ports the exact algorithm `LocalFsResolver` and `getSymbolSurgicalContext`
+ * use in the main repo (`src/subconscious/freshness/LocalFsResolver.ts`,
+ * `src/utils/SymbolSurgicalContext.ts`), so a memory stored via this SDK and
+ * one stored via the local MCP Brain hash identically. Kept honest by
+ * `tests/unit/lane-g-evidence.test.ts`, which imports both implementations on
+ * the same fixture file and asserts the hashes match byte for byte — this is
+ * not a claim taken on faith.
+ *
+ * A file that can't be read, or a symbol that can't be found, hashes to the
+ * literal string `'MISSING'` — same fail-loud convention as `LocalFsResolver`
+ * — rather than silently omitting the claim.
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const ts = __importStar(require("typescript"));
+function sha256(content) {
+    return crypto_1.default.createHash('sha256').update(content, 'utf8').digest('hex');
+}
+function resolvePath(rootDir, relPath) {
+    return path_1.default.isAbsolute(relPath) ? relPath : path_1.default.resolve(rootDir, relPath);
+}
+/** sha256 of a whole file's utf8 content. `'MISSING'` if it can't be read. */
+function hashFile(rootDir, relPath) {
+    const abs = resolvePath(rootDir, relPath);
+    try {
+        return sha256(fs_1.default.readFileSync(abs, 'utf8'));
+    }
+    catch {
+        return 'MISSING';
+    }
+}
+/**
+ * Same traversal `SymbolSurgicalContext.findSymbolNode` uses: a top-level
+ * function/class/interface/type-alias/enum declaration named `name`, or the
+ * variable statement declaring an identifier named `name`.
+ */
+function findSymbolNode(sourceFile, name) {
+    let targetNode = null;
+    function walk(node) {
+        if (targetNode)
+            return;
+        if (ts.isFunctionDeclaration(node) && node.name && node.name.text === name) {
+            targetNode = node;
+            return;
+        }
+        if (ts.isClassDeclaration(node) && node.name && node.name.text === name) {
+            targetNode = node;
+            return;
+        }
+        if (ts.isInterfaceDeclaration(node) && node.name && node.name.text === name) {
+            targetNode = node;
+            return;
+        }
+        if (ts.isTypeAliasDeclaration(node) && node.name && node.name.text === name) {
+            targetNode = node;
+            return;
+        }
+        if (ts.isEnumDeclaration(node) && node.name && node.name.text === name) {
+            targetNode = node;
+            return;
+        }
+        if (ts.isVariableStatement(node)) {
+            for (const decl of node.declarationList.declarations) {
+                if (ts.isIdentifier(decl.name) && decl.name.text === name) {
+                    targetNode = node;
+                    return;
+                }
+            }
+        }
+        ts.forEachChild(node, walk);
+    }
+    walk(sourceFile);
+    return targetNode;
+}
+/** Token-stream normalization: strips comments/whitespace, keeps semantics. */
+function normalizeForFreshness(source) {
+    const scanner = ts.createScanner(ts.ScriptTarget.Latest, /* skipTrivia */ true, ts.LanguageVariant.Standard, source);
+    const tokens = [];
+    let kind = scanner.scan();
+    while (kind !== ts.SyntaxKind.EndOfFileToken) {
+        tokens.push(scanner.getTokenText());
+        kind = scanner.scan();
+    }
+    return tokens.join(' ');
+}
+/** Raw + normalized sha256 pair for one symbol. `'MISSING'`/`'MISSING'` if unreadable or not found. */
+function hashSymbol(rootDir, relPath, symbolName) {
+    const abs = resolvePath(rootDir, relPath);
+    try {
+        const src = fs_1.default.readFileSync(abs, 'utf8');
+        const sf = ts.createSourceFile(abs, src, ts.ScriptTarget.Latest, true);
+        const node = findSymbolNode(sf, symbolName);
+        if (!node)
+            return { raw: 'MISSING', normalized: 'MISSING' };
+        const implementation = node.getText();
+        return { raw: sha256(implementation), normalized: sha256(normalizeForFreshness(implementation)) };
+    }
+    catch {
+        return { raw: 'MISSING', normalized: 'MISSING' };
+    }
+}
+/**
+ * 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.
+ */
+function collectEvidence(options) {
+    const rootDir = options.rootDir ?? process.cwd();
+    const files = {};
+    const symbols = {};
+    const symbolsNormalized = {};
+    for (const relPath of options.files ?? []) {
+        files[relPath] = hashFile(rootDir, relPath);
+    }
+    for (const { filePath, symbolName } of options.symbols ?? []) {
+        const key = `${filePath}::${symbolName}`;
+        const { raw, normalized } = hashSymbol(rootDir, filePath, symbolName);
+        symbols[key] = raw;
+        symbolsNormalized[key] = normalized;
+    }
+    return {
+        files,
+        symbols,
+        symbolsNormalized,
+        ...(options.branch ? { branch: options.branch } : {}),
+        ...(options.commit ? { commit: options.commit } : {}),
+    };
+}

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

@@ -0,0 +1,4 @@
+export { LemmaClient, type LemmaClientOptions } from './client';
+export { collectEvidence, hashFile, hashSymbol, normalizeForFreshness, type CollectEvidenceOptions } from './evidence';
+export { LemmaSdkError } from './errors';
+export * from './types';

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

@@ -0,0 +1,27 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LemmaSdkError = exports.normalizeForFreshness = exports.hashSymbol = exports.hashFile = exports.collectEvidence = exports.LemmaClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "LemmaClient", { enumerable: true, get: function () { return client_1.LemmaClient; } });
+var evidence_1 = require("./evidence");
+Object.defineProperty(exports, "collectEvidence", { enumerable: true, get: function () { return evidence_1.collectEvidence; } });
+Object.defineProperty(exports, "hashFile", { enumerable: true, get: function () { return evidence_1.hashFile; } });
+Object.defineProperty(exports, "hashSymbol", { enumerable: true, get: function () { return evidence_1.hashSymbol; } });
+Object.defineProperty(exports, "normalizeForFreshness", { enumerable: true, get: function () { return evidence_1.normalizeForFreshness; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "LemmaSdkError", { enumerable: true, get: function () { return errors_1.LemmaSdkError; } });
+__exportStar(require("./types"), exports);

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

@@ -0,0 +1,112 @@
+/**
+ * Wire types for the Lemma /v2 API.
+ *
+ * Mirrors `src/contracts/api-v2.types.ts` and `src/contracts/evidence.ts` in the
+ * main repo (the SDK is published standalone, so it can't import from `src/`
+ * directly — this file is the SDK's own copy of the same shapes). Kept in sync
+ * by `tests/unit/lane-g-evidence.test.ts`, which imports the real contract
+ * types from the main repo and structurally checks this file against them.
+ */
+/** Hash of a whole file: path (as the client refers to it) → sha256 hex. */
+export type FileHashes = Record<string, string>;
+/** Hash pair for one symbol: key is `<path>::<symbolName>`. */
+export type SymbolHashes = Record<string, string>;
+export interface Evidence {
+    files: FileHashes;
+    symbols: SymbolHashes;
+    /** Symbols hashed after stripping comments/whitespace (semantic diff). */
+    symbolsNormalized: SymbolHashes;
+    branch?: string;
+    commit?: string;
+}
+/**
+ * Verifiability state of a memory or claim.
+ *
+ *   fresh   — every tracked path hashes identical to what was stored.
+ *   stale   — a tracked path hashed differently (staleFiles names which).
+ *   unverified — the verifier cannot prove validity (no current evidence, or a
+ *                tracked path was omitted). NEVER `fresh` by guess.
+ *   contradicted — two stored claims about the same subject now diverge.
+ */
+export type MemoryState = 'fresh' | 'stale' | 'unverified' | 'contradicted';
+export interface MemoryClaim {
+    id: string;
+    text: string;
+    fileHashes?: FileHashes;
+    symbolHashes?: SymbolHashes;
+    symbolNormalizedHashes?: SymbolHashes;
+}
+export interface VerifiedResult {
+    id: string;
+    state: MemoryState;
+    staleFiles?: string[];
+    cosmeticChanges?: string[];
+    memory?: unknown;
+}
+export interface CreateMemoryRequest {
+    claims: Array<{
+        text: string;
+        filePaths?: string[];
+        symbols?: Array<{
+            filePath: string;
+            symbolName: string;
+        }>;
+    }>;
+    evidence: Evidence;
+    derivedFrom?: string[];
+}
+export interface CreateMemoryResponse {
+    id: string;
+    claims: MemoryClaim[];
+}
+export interface RecallRequest {
+    query: string;
+    currentEvidence?: Evidence;
+    limit?: number;
+}
+export interface RecallResponse {
+    results: VerifiedResult[];
+    query: string;
+}
+export interface VerifyRequest {
+    ids: string[];
+    currentEvidence: Evidence;
+}
+export interface VerifyResponse {
+    results: VerifiedResult[];
+}
+export interface ForgetResponse {
+    forged: string[];
+}
+export interface ScrubFinding {
+    type: string;
+    offset: number;
+    length: number;
+}
+export interface ScrubRequest {
+    text?: string;
+    toolCallJson?: string;
+    mode?: 'mask' | 'detect';
+}
+export interface ScrubResponse {
+    text?: string;
+    toolCallJson?: string;
+    findings: ScrubFinding[];
+}
+export interface UsageStat {
+    measurement: 'counted';
+    value: number;
+}
+export interface UsageResponse {
+    metrics: Record<string, UsageStat>;
+    excludedEvents: number;
+}
+export type LemmaErrorCode = 'unauthenticated' | 'invalid_request' | 'quota_exceeded' | 'not_found' | 'forbidden' | 'rate_limited' | 'not_implemented' | 'internal';
+export interface LemmaApiErrorBody {
+    error: {
+        code: LemmaErrorCode;
+        status: number;
+        message: string;
+        field?: string;
+    };
+}

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

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Wire types for the Lemma /v2 API.
+ *
+ * Mirrors `src/contracts/api-v2.types.ts` and `src/contracts/evidence.ts` in the
+ * main repo (the SDK is published standalone, so it can't import from `src/`
+ * directly — this file is the SDK's own copy of the same shapes). Kept in sync
+ * by `tests/unit/lane-g-evidence.test.ts`, which imports the real contract
+ * types from the main repo and structurally checks this file against them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });