@yamo/memory-mesh 2.0.1

package/lib/utils/handoff-validator.js

@@ -0,0 +1,85 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Handoff Package Validator
+ * Verifies that a handoff package is complete and valid.
+ */
+class HandoffValidator {
+    constructor(packagePath) {
+        this.packagePath = packagePath;
+        this.requiredFiles = [
+            'context.md',
+            'memory.json',
+            'metadata.json'
+        ];
+    }
+
+    validate() {
+        /** @type {{valid: boolean, errors: string[], warnings: string[], summary: string}} */
+        const result = {
+            valid: true,
+            errors: [],
+            warnings: [],
+            summary: ''
+        };
+
+        if (!fs.existsSync(this.packagePath)) {
+            result.valid = false;
+            result.errors.push(`Package path not found: ${this.packagePath}`);
+            return result;
+        }
+
+        // Check required files
+        for (const file of this.requiredFiles) {
+            const filePath = path.join(this.packagePath, file);
+            if (!fs.existsSync(filePath)) {
+                result.valid = false;
+                result.errors.push(`Missing required file: ${file}`);
+            }
+        }
+
+        // Validate metadata
+        const metadataPath = path.join(this.packagePath, 'metadata.json');
+        if (fs.existsSync(metadataPath)) {
+            try {
+                const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+                if (!metadata.timestamp) result.warnings.push('Metadata missing timestamp');
+                if (!metadata.source) result.warnings.push('Metadata missing source');
+            } catch (e) {
+                result.valid = false;
+                result.errors.push('Invalid metadata.json format');
+            }
+        }
+
+        result.summary = result.valid 
+            ? `✅ Package valid with ${result.warnings.length} warnings` 
+            : `❌ Package invalid with ${result.errors.length} errors`;
+
+        return result;
+    }
+}
+
+// CLI usage
+if (process.argv[1] === import.meta.url) {
+    const pkgPath = process.argv[2] || '.';
+    const validator = new HandoffValidator(pkgPath);
+    const result = validator.validate();
+
+    if (!result.valid) {
+        console.log(result.summary);
+        console.log('\n❌ Errors found:');
+        result.errors.forEach(err => console.log(`   - ${err}`));
+        process.exit(1);
+    } else {
+        console.log(result.summary);
+        console.log('\n✅ Handoff package is valid!');
+        
+        if (result.warnings.length > 0) {
+            console.log('\n⚠️  Warnings:');
+            result.warnings.forEach(warn => console.log(`   - ${warn}`));
+        }
+    }
+}
+
+export default HandoffValidator;

package/lib/utils/index.js

@@ -0,0 +1,4 @@
+export { default as HandoffValidator } from './handoff-validator.js';
+export { Spinner, ProgressBar, MultiSpinner } from './spinner.js';
+export { StreamingClient, StreamingLLM } from './streaming-client.js';
+export { sanitizeErrorMessage, sanitizeErrorForLogging, withSanitizedErrors } from './error-sanitizer.js';

package/lib/utils/spinner.js

@@ -0,0 +1,190 @@
+/**
+ * Spinner and Progress Indicators
+ */
+
+import { fileURLToPath } from 'url';
+
+class Spinner {
+    constructor(text = 'Loading...', options = {}) {
+        this.text = text;
+        // @ts-ignore
+        this.frames = options.frames || ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+        // @ts-ignore
+        this.interval = options.interval || 80;
+        // @ts-ignore
+        this.stream = options.stream || process.stderr;
+        // @ts-ignore
+        this.color = options.color || '\x1b[36m';
+        this.frameIndex = 0;
+        this.timer = null;
+        this.isSpinning = false;
+    }
+
+    start() {
+        if (this.isSpinning) return this;
+        this.isSpinning = true;
+        this.frameIndex = 0;
+        this.stream.write('\x1B[?25l');
+        this.timer = setInterval(() => {
+            const frame = this.frames[this.frameIndex];
+            this.stream.write(`\r${this.color}${frame}\x1b[0m ${this.text}`);
+            this.frameIndex = (this.frameIndex + 1) % this.frames.length;
+        }, this.interval);
+        return this;
+    }
+
+    update(text) {
+        this.text = text;
+        return this;
+    }
+
+    succeed(text) {
+        return this.stop('\x1b[32m✔\x1b[0m', text);
+    }
+
+    fail(text) {
+        return this.stop('\x1b[31m✖\x1b[0m', text);
+    }
+
+    warn(text) {
+        return this.stop('\x1b[33m⚠\x1b[0m', text);
+    }
+
+    info(text) {
+        return this.stop('\x1b[36mℹ\x1b[0m', text);
+    }
+
+    /**
+     * @param {string|null} symbol
+     * @param {string|null} text
+     */
+    stop(symbol = null, text = null) {
+        if (!this.isSpinning) return this;
+        if (this.timer) {
+            // @ts-ignore
+            clearInterval(this.timer);
+        }
+        this.isSpinning = false;
+        this.stream.write('\r\x1b[K');
+        this.stream.write('\x1B[?25h');
+        if (symbol && text) {
+            this.stream.write(`${symbol} ${text}\n`);
+        } else if (text) {
+            this.stream.write(`${text}\n`);
+        }
+        return this;
+    }
+
+    clear() {
+        if (!this.isSpinning) return this;
+        if (this.timer) {
+            // @ts-ignore
+            clearInterval(this.timer);
+        }
+        this.isSpinning = false;
+        this.stream.write('\r\x1b[K');
+        this.stream.write('\x1B[?25h');
+        return this;
+    }
+}
+
+class ProgressBar {
+    constructor(total, options = {}) {
+        this.total = total;
+        this.current = 0;
+        // @ts-ignore
+        this.width = options.width || 40;
+        // @ts-ignore
+        this.stream = options.stream || process.stderr;
+        // @ts-ignore
+        this.format = options.format || ':bar :percent :current/:total';
+        // @ts-ignore
+        this.complete = options.complete || '█';
+        // @ts-ignore
+        this.incomplete = options.incomplete || '░';
+        // @ts-ignore
+        this.renderThrottle = options.renderThrottle || 16;
+        this.lastRender = 0;
+    }
+
+    tick(amount = 1) {
+        this.current = Math.min(this.current + amount, this.total);
+        const now = Date.now();
+        if (now - this.lastRender < this.renderThrottle && this.current < this.total) {
+            return this;
+        }
+        this.lastRender = now;
+        this.render();
+        return this;
+    }
+
+    render() {
+        const percent = Math.floor((this.current / this.total) * 100);
+        const completeLength = Math.floor(this.width * (this.current / this.total));
+        const incompleteLength = this.width - completeLength;
+        const bar = this.complete.repeat(completeLength) + this.incomplete.repeat(incompleteLength);
+        // @ts-ignore
+        let output = this.format.replace(':bar', bar).replace(':percent', `${percent}%`).replace(':current', String(this.current)).replace(':total', String(this.total));
+        this.stream.write(`\r${output}`);
+        if (this.current >= this.total) {
+            this.stream.write('\n');
+        }
+        return this;
+    }
+
+    update(current) {
+        this.current = Math.min(current, this.total);
+        this.render();
+        return this;
+    }
+}
+
+class MultiSpinner {
+    constructor() {
+        this.spinners = new Map();
+        this.stream = process.stderr;
+    }
+
+    add(key, text, status = 'pending') {
+        this.spinners.set(key, { text, status, startTime: Date.now() });
+        this.render();
+        return this;
+    }
+
+    update(key, status, text = null) {
+        const spinner = this.spinners.get(key);
+        if (spinner) {
+            spinner.status = status;
+            if (text) spinner.text = text;
+            this.render();
+        }
+        return this;
+    }
+
+    succeed(key, text) { return this.update(key, 'success', text); }
+    fail(key, text) { return this.update(key, 'fail', text); }
+    warn(key, text) { return this.update(key, 'warn', text); }
+
+    render() {
+        this.stream.write('\r\x1b[K');
+        const lines = [];
+        for (const [key, spinner] of this.spinners) {
+            // @ts-ignore
+            const symbol = { pending: '\x1b[36m⋯\x1b[0m', success: '\x1b[32m✔\x1b[0m', fail: '\x1b[31m✖\x1b[0m', warn: '\x1b[33m⚠\x1b[0m' }[spinner.status];
+            const duration = ((Date.now() - spinner.startTime) / 1000).toFixed(1);
+            lines.push(`${symbol} ${spinner.text} (${duration}s)`);
+        }
+        this.stream.write(lines.join('\n'));
+        if (lines.length > 1) {
+            this.stream.write(`\x1b[${lines.length - 1}A`);
+        }
+        return this;
+    }
+
+    done() {
+        this.stream.write('\n'.repeat(this.spinners.size));
+        return this;
+    }
+}
+
+export { Spinner, ProgressBar, MultiSpinner };

package/lib/utils/streaming-client.js

@@ -0,0 +1,128 @@
+import { fileURLToPath } from 'url';
+import https from "https";
+
+/**
+ * Streaming LLM Client
+ */
+class StreamingClient {
+    constructor(config) {
+        this.config = config;
+        this.buffer = '';
+    }
+
+    stream(payload, onToken, onComplete, onError) {
+        const url = new URL(this.config.endpoint);
+        
+        /** @type {any} */
+        const options = {
+            hostname: url.hostname,
+            path: url.pathname,
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.config.apiKey}`,
+                'Accept': 'text/event-stream'
+            },
+            rejectUnauthorized: true,
+            minVersion: 'TLSv1.2'
+        };
+
+        const req = https.request(options, (res) => {
+            let fullResponse = '';
+            res.on('data', (chunk) => {
+                this.buffer += chunk.toString();
+                const lines = this.buffer.split('\n');
+                this.buffer = lines.pop() || '';
+                for (const line of lines) {
+                    if (line.startsWith('data: ')) {
+                        const data = line.slice(6);
+                        if (data === '[DONE]') continue;
+                        try {
+                            const parsed = JSON.parse(data);
+                            const token = this.extractToken(parsed, this.config.schema);
+                            if (token) {
+                                fullResponse += token;
+                                onToken(token, parsed);
+                            }
+                        } catch (e) { /* ignore */ }
+                    }
+                }
+            });
+            res.on('end', () => { if (onComplete) onComplete(fullResponse); });
+            res.on('error', (e) => { if (onError) onError(e); });
+        });
+
+        req.on('error', (e) => { if (onError) onError(e); });
+        req.setTimeout(60000, () => {
+            req.destroy();
+            if (onError) onError(new Error('Timeout'));
+        });
+        req.write(JSON.stringify({ ...payload, stream: true }));
+        req.end();
+        return req;
+    }
+
+    extractToken(data, schema) {
+        switch (schema) {
+            case 'openai': return data.choices?.[0]?.delta?.content || '';
+            default: return data.choices?.[0]?.delta?.content || data.delta?.text || '';
+        }
+    }
+
+    async request(payload) {
+        return new Promise((resolve, reject) => {
+            const url = new URL(this.config.endpoint);
+            
+            /** @type {any} */
+            const options = {
+                hostname: url.hostname,
+                path: url.pathname,
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.config.apiKey}`
+                },
+                rejectUnauthorized: true,
+                minVersion: 'TLSv1.2'
+            };
+            const req = https.request(options, (res) => {
+                let data = '';
+                res.on('data', (chunk) => data += chunk);
+                res.on('end', () => {
+                    try { resolve(JSON.parse(data)); } catch (e) { reject(e); }
+                });
+            });
+            req.on('error', reject);
+            req.write(JSON.stringify(payload));
+            req.end();
+        });
+    }
+}
+
+class StreamingLLM {
+    constructor(config) {
+        this.client = new StreamingClient(config);
+        this.config = config;
+    }
+
+    async streamToConsole(payload, options = {}) {
+        // @ts-ignore
+        const prefix = options.prefix || '';
+        return new Promise((resolve, reject) => {
+            let tokens = [];
+            this.client.stream(payload, (token) => {
+                process.stdout.write(token);
+                // @ts-ignore
+                tokens.push(token);
+            }, (full) => {
+                process.stdout.write('\n');
+                resolve({ content: full, tokens: tokens.length });
+            }, (e) => {
+                process.stdout.write('\n');
+                reject(e);
+            });
+        });
+    }
+}
+
+export { StreamingClient, StreamingLLM };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@yamo/memory-mesh",
+  "version": "2.0.1",
+  "description": "Portable semantic memory system with Layer 0 Scrubber for YAMO agents",
+  "type": "module",
+  "main": "lib/memory/index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "memory-mesh": "./bin/memory_mesh.js",
+    "scrubber": "./bin/scrubber.js"
+  },
+  "files": [
+    "lib/",
+    "bin/",
+    "skills/",
+    "index.d.ts"
+  ],
+  "scripts": {
+    "test": "npm run type-check",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@lancedb/lancedb": "^0.23.0",
+    "@xenova/transformers": "^2.17.0",
+    "apache-arrow": "^17.0.0",
+    "onnxruntime-node": "^1.18.0"
+  },
+  "author": "Soverane Labs",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "cohere-ai": "^7.20.0",
+    "openai": "^6.16.0",
+    "typescript": "^5.9.3"
+  }
+}