network-ai 5.10.2 → 5.11.0

package/dist/esm/lib/console-ui.js

@@ -0,0 +1,276 @@
+"use strict";
+/**
+ * Console UI — Interactive terminal dashboard for Network-AI
+ *
+ * A TUI (text user interface) built with Node.js builtins (readline + ANSI
+ * escape codes). Zero external dependencies.
+ *
+ * Features:
+ *   - Live event feed with timestamped entries
+ *   - Status bar (agents, budget, FSM state)
+ *   - Command input with auto-completion
+ *   - Approval prompts (approve/deny inline)
+ *   - Color-coded output
+ *
+ * @module ConsoleUI
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsoleUI = exports.ansi = void 0;
+const readline_1 = require("readline");
+const events_1 = require("events");
+// ============================================================================
+// ANSI HELPERS
+// ============================================================================
+const ESC = '\x1b[';
+/** ANSI color/style codes */
+exports.ansi = {
+    reset: `${ESC}0m`,
+    bold: `${ESC}1m`,
+    dim: `${ESC}2m`,
+    italic: `${ESC}3m`,
+    underline: `${ESC}4m`,
+    // Foreground
+    black: `${ESC}30m`,
+    red: `${ESC}31m`,
+    green: `${ESC}32m`,
+    yellow: `${ESC}33m`,
+    blue: `${ESC}34m`,
+    magenta: `${ESC}35m`,
+    cyan: `${ESC}36m`,
+    white: `${ESC}37m`,
+    gray: `${ESC}90m`,
+    // Background
+    bgBlack: `${ESC}40m`,
+    bgRed: `${ESC}41m`,
+    bgGreen: `${ESC}42m`,
+    bgYellow: `${ESC}43m`,
+    bgBlue: `${ESC}44m`,
+    bgMagenta: `${ESC}45m`,
+    bgCyan: `${ESC}46m`,
+    bgWhite: `${ESC}47m`,
+    // Cursor
+    clearScreen: `${ESC}2J${ESC}H`,
+    clearLine: `${ESC}2K`,
+    cursorHome: `${ESC}H`,
+    hideCursor: `${ESC}?25l`,
+    showCursor: `${ESC}?25h`,
+};
+/** Apply color to text */
+function color(text, ...codes) {
+    return codes.join('') + text + exports.ansi.reset;
+}
+/** Format a timestamp for display */
+function timeStamp() {
+    const now = new Date();
+    const h = String(now.getHours()).padStart(2, '0');
+    const m = String(now.getMinutes()).padStart(2, '0');
+    const s = String(now.getSeconds()).padStart(2, '0');
+    return `${h}:${m}:${s}`;
+}
+// ============================================================================
+// CONSOLE UI
+// ============================================================================
+/**
+ * Interactive terminal UI for Network-AI agent runtime.
+ *
+ * @example
+ * ```typescript
+ * const ui = new ConsoleUI({ title: 'Network-AI', version: '4.13.1' });
+ * ui.command('status', (args, ui) => { ui.log('All systems operational'); });
+ * ui.command('approve', async (args, ui) => { ... });
+ * await ui.start();
+ * ```
+ */
+class ConsoleUI extends events_1.EventEmitter {
+    opts;
+    rl = null;
+    commands = new Map();
+    feed = [];
+    status = {
+        version: '0.0.0',
+        agents: { active: 0, total: 0 },
+        budget: { usedPercent: 0 },
+        fsm: { state: 'idle' },
+        pendingApprovals: 0,
+    };
+    running = false;
+    constructor(opts = {}) {
+        super();
+        this.opts = {
+            title: opts.title ?? 'Network-AI',
+            version: opts.version ?? '0.0.0',
+            prompt: opts.prompt ?? '> ',
+            maxFeedEntries: opts.maxFeedEntries ?? 200,
+            input: opts.input ?? process.stdin,
+            output: opts.output ?? process.stdout,
+        };
+        this.status.version = this.opts.version;
+        // Register built-in commands
+        this.command('help', (_args, ui) => { ui.showHelp(); }, 'Show available commands');
+        this.command('clear', (_args, ui) => { ui.clearFeed(); }, 'Clear the event feed');
+        this.command('exit', () => { this.stop(); }, 'Exit the console');
+        this.command('quit', () => { this.stop(); }, 'Exit the console');
+    }
+    /** Register a command handler */
+    command(name, handler, description = '') {
+        this.commands.set(name.toLowerCase(), { handler, description });
+    }
+    /** Update the status bar */
+    updateStatus(partial) {
+        Object.assign(this.status, partial);
+    }
+    /** Add an entry to the live feed */
+    log(message, level = 'info') {
+        const icons = {
+            info: color('ℹ', exports.ansi.cyan),
+            warn: color('⚠', exports.ansi.yellow),
+            error: color('✗', exports.ansi.red),
+            success: color('✓', exports.ansi.green),
+            approval: color('⏳', exports.ansi.magenta),
+        };
+        const entry = {
+            time: timeStamp(),
+            icon: icons[level],
+            message,
+            level,
+        };
+        this.feed.push(entry);
+        if (this.feed.length > this.opts.maxFeedEntries) {
+            this.feed.shift();
+        }
+        this.emit('feed', entry);
+        // Print inline if running
+        if (this.running) {
+            this.writeFeedEntry(entry);
+        }
+    }
+    /** Get all feed entries */
+    getFeed() {
+        return this.feed;
+    }
+    /** Clear the feed */
+    clearFeed() {
+        this.feed = [];
+        if (this.running) {
+            this.write(exports.ansi.clearScreen);
+            this.renderHeader();
+            this.renderPrompt();
+        }
+    }
+    /** Get current status */
+    getStatus() {
+        return { ...this.status };
+    }
+    /** Start the interactive console */
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.rl = (0, readline_1.createInterface)({
+            input: this.opts.input,
+            output: this.opts.output,
+            prompt: this.opts.prompt,
+            terminal: true,
+        });
+        this.renderHeader();
+        this.renderPrompt();
+        this.rl.on('line', async (line) => {
+            const trimmed = line.trim();
+            if (trimmed) {
+                await this.handleInput(trimmed);
+            }
+            if (this.running) {
+                this.renderPrompt();
+            }
+        });
+        this.rl.on('close', () => {
+            this.running = false;
+            this.emit('exit');
+        });
+        return new Promise((resolve) => {
+            this.once('exit', resolve);
+        });
+    }
+    /** Stop the console */
+    stop() {
+        this.running = false;
+        if (this.rl) {
+            this.rl.close();
+            this.rl = null;
+        }
+        this.write(color('\nGoodbye.\n', exports.ansi.dim));
+        this.emit('exit');
+    }
+    /** Whether the console is currently running */
+    get isRunning() { return this.running; }
+    /** Show the help text */
+    showHelp() {
+        this.write('\n' + color('  Available Commands:', exports.ansi.bold, exports.ansi.cyan) + '\n');
+        for (const [name, { description }] of this.commands) {
+            const desc = description ? color(` — ${description}`, exports.ansi.dim) : '';
+            this.write(`    ${color(name, exports.ansi.green)}${desc}\n`);
+        }
+        this.write('\n');
+    }
+    /** Render the header/status bar */
+    renderHeader() {
+        const s = this.status;
+        const divider = color('─'.repeat(60), exports.ansi.dim);
+        this.write('\n');
+        this.write(`  ${color(this.opts.title, exports.ansi.bold, exports.ansi.cyan)} ` +
+            color(`v${s.version}`, exports.ansi.dim) + '\n');
+        this.write(divider + '\n');
+        this.write(`  Agents: ${color(String(s.agents.active), exports.ansi.green)}/${s.agents.total}` +
+            `  │  Budget: ${this.budgetColor(s.budget.usedPercent)}` +
+            `  │  FSM: ${color(s.fsm.state, exports.ansi.yellow)}` +
+            (s.pendingApprovals > 0
+                ? `  │  ${color(`${s.pendingApprovals} pending`, exports.ansi.magenta, exports.ansi.bold)}`
+                : '') +
+            '\n');
+        this.write(divider + '\n');
+    }
+    // ------- Internals -------
+    write(text) {
+        const out = this.opts.output;
+        out.write(text);
+    }
+    renderPrompt() {
+        if (this.rl) {
+            this.rl.prompt();
+        }
+    }
+    writeFeedEntry(entry) {
+        const time = color(`[${entry.time}]`, exports.ansi.dim);
+        this.write(`\r${exports.ansi.clearLine}  ${time} ${entry.icon} ${entry.message}\n`);
+    }
+    budgetColor(pct) {
+        const text = `${pct}%`;
+        if (pct >= 80)
+            return color(text, exports.ansi.red, exports.ansi.bold);
+        if (pct >= 50)
+            return color(text, exports.ansi.yellow);
+        return color(text, exports.ansi.green);
+    }
+    async handleInput(input) {
+        const parts = input.split(/\s+/);
+        const cmd = parts[0].toLowerCase();
+        const args = parts.slice(1).join(' ');
+        const handler = this.commands.get(cmd);
+        if (!handler) {
+            this.write(color(`  Unknown command: ${cmd}. Type 'help' for available commands.\n`, exports.ansi.red));
+            this.emit('unknown-command', cmd, args);
+            return;
+        }
+        try {
+            await handler.handler(args, this);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.write(color(`  Error: ${msg}\n`, exports.ansi.red));
+        }
+        this.emit('command', cmd, args);
+    }
+}
+exports.ConsoleUI = ConsoleUI;
+//# sourceMappingURL=console-ui.js.map

package/dist/esm/lib/console-ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-ui.js","sourceRoot":"","sources":["../../../lib/console-ui.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/context-throttler.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * Context Throttler — Metadata-Driven Blackboard Pruning for Network-AI
+ *
+ * Prevents "context pollution" by ensuring agents only receive the subset of
+ * Blackboard state that is relevant to their declared scope metadata.
+ *
+ * Before an LLM call the orchestrator passes the full blackboard snapshot and
+ * the agent's `scopeMetadata` tags to `filterState()`. Keys that do not match
+ * any tag are pruned, keeping the system prompt lean regardless of how large
+ * the shared state grows.
+ *
+ * Zero external dependencies — pure TypeScript functions.
+ *
+ * @module ContextThrottler
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextThrottler = void 0;
+exports.filterState = filterState;
+// ============================================================================
+// PURE FILTER FUNCTION
+// ============================================================================
+/**
+ * Prune a blackboard state snapshot to only include keys matching an agent's
+ * scope metadata tags.
+ *
+ * This is the core primitive — stateless and dependency-free. Use it directly
+ * or via {@link ContextThrottler} for the OOP interface.
+ *
+ * @param agentId - Agent identifier (used only in the returned result metadata)
+ * @param state - Full blackboard snapshot (key → value)
+ * @param scopeMetadata - Tags declaring what the agent cares about
+ * @param options - Matching behaviour overrides
+ *
+ * @example
+ * ```typescript
+ * import { filterState } from 'network-ai';
+ *
+ * const pruned = filterState('tax-agent', fullBlackboard, ['financials', 'tax']);
+ * // pruned.filteredState only contains keys containing "financials" or "tax"
+ * ```
+ */
+function filterState(agentId, state, scopeMetadata, options = {}) {
+    const { caseSensitive = false, exactMatch = false, maxKeys = 0 } = options;
+    // Wildcard — keep everything
+    if (scopeMetadata.includes('*') || scopeMetadata.length === 0) {
+        const allKeys = Object.keys(state);
+        return {
+            filteredState: { ...state },
+            retainedKeys: allKeys,
+            prunedKeys: [],
+            agentId,
+            scopeMetadata,
+        };
+    }
+    const normalizedTags = caseSensitive
+        ? scopeMetadata
+        : scopeMetadata.map((t) => t.toLowerCase());
+    const retainedKeys = [];
+    const prunedKeys = [];
+    for (const key of Object.keys(state)) {
+        const normalizedKey = caseSensitive ? key : key.toLowerCase();
+        const matches = exactMatch
+            ? normalizedTags.includes(normalizedKey)
+            : normalizedTags.some((tag) => normalizedKey.includes(tag));
+        if (matches) {
+            retainedKeys.push(key);
+        }
+        else {
+            prunedKeys.push(key);
+        }
+    }
+    // Apply hard cap
+    const cappedKeys = maxKeys > 0 ? retainedKeys.slice(0, maxKeys) : retainedKeys;
+    const extraPruned = maxKeys > 0 ? retainedKeys.slice(maxKeys) : [];
+    const filteredState = {};
+    for (const key of cappedKeys) {
+        filteredState[key] = state[key];
+    }
+    return {
+        filteredState,
+        retainedKeys: cappedKeys,
+        prunedKeys: [...prunedKeys, ...extraPruned],
+        agentId,
+        scopeMetadata,
+    };
+}
+// ============================================================================
+// CONTEXT THROTTLER (OOP interface)
+// ============================================================================
+/**
+ * ContextThrottler provides a stateful interface for the `filterState`
+ * primitive and maintains per-agent scope registrations.
+ *
+ * @example
+ * ```typescript
+ * const throttler = new ContextThrottler();
+ * throttler.registerScope('tax-agent', ['financials', 'tax', 'regulations']);
+ * throttler.registerScope('hr-agent',  ['employees', 'salaries']);
+ *
+ * const result = throttler.filter('tax-agent', fullBlackboard);
+ * // result.filteredState only has the keys relevant to the tax agent
+ * ```
+ */
+class ContextThrottler {
+    scopes = new Map();
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /**
+     * Register a scope for an agent. Overwrites any existing registration.
+     * @param agentId - Agent identifier
+     * @param scopeMetadata - Tags for this agent (use `['*']` to opt out of filtering)
+     */
+    registerScope(agentId, scopeMetadata) {
+        if (!agentId || typeof agentId !== 'string') {
+            throw new Error('agentId must be a non-empty string');
+        }
+        this.scopes.set(agentId, scopeMetadata);
+    }
+    /**
+     * Remove a registered scope.
+     */
+    deregisterScope(agentId) {
+        this.scopes.delete(agentId);
+    }
+    /**
+     * Return the registered scope for an agent, or undefined if not registered.
+     */
+    getScope(agentId) {
+        return this.scopes.get(agentId);
+    }
+    /**
+     * Filter a blackboard snapshot for a specific agent using its registered
+     * scope. If no scope is registered for the agent, all keys are retained
+     * (equivalent to `['*']`).
+     *
+     * @param agentId - Agent to filter for
+     * @param state - Full blackboard snapshot
+     * @param overrideScope - Override the registered scope for this call only
+     */
+    filter(agentId, state, overrideScope) {
+        const scope = overrideScope ?? this.scopes.get(agentId) ?? ['*'];
+        return filterState(agentId, state, scope, this.options);
+    }
+    /**
+     * Filter and return only the `filteredState` object (convenience wrapper).
+     */
+    filterToState(agentId, state, overrideScope) {
+        return this.filter(agentId, state, overrideScope).filteredState;
+    }
+    /**
+     * Filter a full state snapshot for every registered agent.
+     * Returns a Map of agentId → ThrottleResult.
+     */
+    filterAll(state) {
+        const results = new Map();
+        for (const [agentId] of this.scopes) {
+            results.set(agentId, this.filter(agentId, state));
+        }
+        return results;
+    }
+    /** Number of registered agent scopes. */
+    get size() {
+        return this.scopes.size;
+    }
+}
+exports.ContextThrottler = ContextThrottler;
+//# sourceMappingURL=context-throttler.js.map

package/dist/esm/lib/context-throttler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-throttler.js","sourceRoot":"","sources":["../../../lib/context-throttler.ts"],"names":[],"mappings":"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"}