@aitherium/shell-cli 1.1.0

package/dist/client.js

@@ -0,0 +1,528 @@
+/**
+ * AitherShell HTTP + SSE client.
+ * Pure Node.js — no browser APIs, no React.
+ *
+ * Works against any AitherOS-compatible backend:
+ *   - Genesis (full AitherOS stack)
+ *   - ADK server (standalone agent via `adk serve`)
+ *   - Any server implementing /chat/stream SSE protocol
+ *
+ * Chat routing is handled by the backend's /chat/stream endpoint.
+ * This client is a thin SSE consumer — no trivial intercept,
+ * no fallback chains, no Veil dependency.
+ */
+export class GenesisClient {
+    baseUrl;
+    _authToken = null;
+    _tenantId = null;
+    _userId = null;
+    _backend = null;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+    }
+    /** Probe the backend and detect its type (Genesis vs ADK vs unknown). */
+    async detectBackend() {
+        if (this._backend)
+            return this._backend;
+        const info = { type: 'unknown', name: 'offline' };
+        try {
+            const r = await fetch(`${this.baseUrl}/health`, {
+                headers: { Accept: 'application/json' },
+                signal: AbortSignal.timeout(5000),
+            });
+            if (!r.ok) {
+                this._backend = info;
+                return info;
+            }
+            const data = await r.json();
+            // Genesis health returns generation_ready, vllm_slots_available, tracked_services
+            // ADK health returns agent, llm_backend, version
+            if (data.generation_ready !== undefined || data.tracked_services !== undefined) {
+                info.type = 'genesis';
+                info.name = 'Genesis';
+                info.generationReady = data.generation_ready;
+                info.slotsAvailable = data.vllm_slots_available;
+                // Fetch richer status from Genesis /status
+                try {
+                    const statusData = await this.getStatus();
+                    if (statusData) {
+                        info.services = statusData.tracked_services ?? statusData.count;
+                    }
+                }
+                catch { }
+                // Fetch agent count
+                try {
+                    const agentData = await this.getAgents();
+                    if (agentData?.agents)
+                        info.agents = agentData.agents.length;
+                }
+                catch { }
+                // LLM status
+                try {
+                    const llmData = await this.getLLMStatus();
+                    if (llmData)
+                        info.llmBackend = llmData.model || llmData.default_model;
+                }
+                catch { }
+            }
+            else if (data.agent !== undefined || data.llm_backend !== undefined) {
+                info.type = 'adk';
+                info.name = data.agent || 'agent';
+                info.agent = data.agent;
+                info.version = data.version;
+                info.llmBackend = data.llm_backend;
+                // ADK /agents for count
+                try {
+                    const agentData = await this.getAgents();
+                    if (agentData?.agents)
+                        info.agents = agentData.agents.length;
+                }
+                catch { }
+            }
+            else {
+                // Unknown backend that responds to /health
+                info.type = 'unknown';
+                info.name = data.name || data.service || 'server';
+            }
+        }
+        catch {
+            // Backend unreachable
+        }
+        this._backend = info;
+        return info;
+    }
+    /** Get cached backend info (call detectBackend first). */
+    get backend() { return this._backend; }
+    /** Set auth token for all subsequent requests. */
+    setAuthToken(token, tenantId, userId) {
+        this._authToken = token;
+        if (tenantId !== undefined)
+            this._tenantId = tenantId ?? null;
+        if (userId !== undefined)
+            this._userId = userId ?? null;
+    }
+    /** Build auth headers for requests. */
+    authHeaders() {
+        const headers = {};
+        if (this._authToken) {
+            headers['Authorization'] = `Bearer ${this._authToken}`;
+            // PAT/ACTA keys also go in X-API-Key for billing middleware
+            if (this._authToken.startsWith('aither_sk_live_') || this._authToken.startsWith('aither_pat_')) {
+                headers['X-API-Key'] = this._authToken;
+            }
+        }
+        if (this._tenantId) {
+            headers['X-Tenant-ID'] = this._tenantId;
+        }
+        if (this._userId) {
+            headers['X-User-ID'] = this._userId;
+        }
+        return headers;
+    }
+    /* ── Streaming chat — POST /chat/stream (SSE) ───────────── */
+    async *streamChat(message, opts = {}) {
+        const body = {
+            message,
+            persona: opts.agent || 'aither',
+            ...(opts.mentions && opts.mentions.length > 1 ? { mentions: opts.mentions } : {}),
+            session_id: opts.sessionId,
+            ...(opts.model ? { model: opts.model } : {}),
+            is_local: true,
+            llm_priority: opts.priority || 'user',
+            ...(opts.clarificationResponse ? { clarification_response: opts.clarificationResponse } : {}),
+            ...(opts.sessionContext ? { session_context: opts.sessionContext } : {}),
+            ...(opts.effort ? { effort_level: opts.effort } : {}),
+            ...(opts.safetyLevel ? { safety_level: opts.safetyLevel } : {}),
+            ...(opts.privateMode ? { private_mode: true } : {}),
+            ...(opts.attachments?.length ? { attachments: opts.attachments } : {}),
+            ...(opts.maxEffort != null ? { max_effort: opts.maxEffort } : {}),
+        };
+        let response;
+        const MAX_RETRIES = 3;
+        const RETRY_DELAY_MS = 2000;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                response = await fetch(`${this.baseUrl}/chat/stream`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-Caller-Type': 'PLATFORM',
+                        ...this.authHeaders(),
+                    },
+                    body: JSON.stringify(body),
+                    signal: opts.signal,
+                });
+            }
+            catch (err) {
+                throw new Error(`Cannot connect to Genesis: ${err.message}`);
+            }
+            // Retry on 503 — but distinguish "still starting" from "pool exhausted"
+            if (response.status === 503 && attempt < MAX_RETRIES) {
+                const text503 = await response.text().catch(() => '');
+                let parsed503 = {};
+                try {
+                    parsed503 = JSON.parse(text503);
+                }
+                catch { }
+                if (parsed503.preflight_rejected || parsed503.detail === 'preflight_capacity_zero') {
+                    // Pool exhausted — don't retry, tell user immediately
+                    const retryIn = parsed503.retry_after_s || 30;
+                    throw new Error(`\x1b[33mSystem busy\x1b[0m — LLM pool exhausted (0 available slots). ` +
+                        `Try again in ~${retryIn}s.\n` +
+                        `  The pool auto-recovers. If this persists, run: /pool reset`);
+                }
+                await new Promise(r => setTimeout(r, RETRY_DELAY_MS));
+                continue;
+            }
+            break;
+        }
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            let detail = `HTTP ${response.status}`;
+            let parsed = {};
+            try {
+                parsed = JSON.parse(text);
+                detail = parsed.detail || parsed.error || detail;
+            }
+            catch { /* use status */ }
+            if (response.status === 503) {
+                if (parsed.preflight_rejected || parsed.generation_ready === false) {
+                    throw new Error(`System busy — LLM pool exhausted. Try again in ~${parsed.retry_after_s || 30}s.`);
+                }
+                throw new Error(`Genesis is still starting up — try again in a few seconds (${detail})`);
+            }
+            throw new Error(detail);
+        }
+        yield* this.readSSE(response);
+    }
+    /* ── Session steering — inject input into active session ──── */
+    async steer(sessionId, message, action = 'append') {
+        try {
+            const r = await fetch(`${this.baseUrl}/chat/steer`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', 'X-Caller-Type': 'PLATFORM', ...this.authHeaders() },
+                body: JSON.stringify({ session_id: sessionId, message, action }),
+                signal: AbortSignal.timeout(5000),
+            });
+            return r.ok ? await r.json() : { ok: false, error: `HTTP ${r.status}` };
+        }
+        catch (err) {
+            return { ok: false, error: err?.message || 'steer failed' };
+        }
+    }
+    /* ── Non-streaming chat ───────────────────────────────────── */
+    async chat(message, opts = {}) {
+        const res = await fetch(`${this.baseUrl}/chat`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Caller-Type': 'PLATFORM',
+                ...this.authHeaders(),
+            },
+            body: JSON.stringify({
+                message,
+                session_id: opts.sessionId,
+                persona: opts.agent,
+                include_context: true,
+                is_local: true,
+                llm_priority: 'user',
+            }),
+        });
+        return res.json();
+    }
+    /* ── REST endpoints ───────────────────────────────────────── */
+    async getStatus() {
+        return this.get('/status');
+    }
+    async getServices() {
+        return this.get('/services');
+    }
+    async getAgents() {
+        return this.get('/agents');
+    }
+    async forgeDispatch(task, opts = {}) {
+        const res = await fetch(`${this.baseUrl}/forge/dispatch/sync`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...this.authHeaders() },
+            body: JSON.stringify({
+                task,
+                agent: opts.agent,
+                effort_level: opts.effort ?? 5,
+                mode: 'execute',
+                parent_agent: 'system',
+            }),
+        });
+        return res.json();
+    }
+    async getLogs(limit = 20, level, service) {
+        const params = new URLSearchParams({ limit: String(limit) });
+        if (level)
+            params.set('level', level);
+        if (service)
+            params.set('service', service);
+        return this.get(`/chronicle/logs?${params}`);
+    }
+    async getLLMStatus() {
+        try {
+            const candidates = [process.env.AITHER_LLM_URL, 'https://localhost:8150', 'http://localhost:8150'].filter(Boolean);
+            for (const base of candidates) {
+                try {
+                    const r = await fetch(`${base}/health`, { signal: AbortSignal.timeout(3000) });
+                    if (r.ok)
+                        return r.json();
+                }
+                catch { }
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async getGpuStatus() {
+        try {
+            const candidates = [process.env.AITHER_LLM_URL, 'https://localhost:8150', 'http://localhost:8150'].filter(Boolean);
+            for (const base of candidates) {
+                try {
+                    const r = await fetch(`${base}/reasoning/exclusive/status`, { signal: AbortSignal.timeout(2000) });
+                    if (r.ok)
+                        return r.json();
+                }
+                catch { }
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async getLLMModels() {
+        try {
+            const candidates = [process.env.AITHER_LLM_URL, 'https://localhost:8150', 'http://localhost:8150'].filter(Boolean);
+            for (const base of candidates) {
+                try {
+                    const r = await fetch(`${base}/models`, { signal: AbortSignal.timeout(3000) });
+                    if (r.ok)
+                        return r.json();
+                }
+                catch { }
+            }
+            return { models: [] };
+        }
+        catch {
+            return { models: [] };
+        }
+    }
+    /* ── Helpers ──────────────────────────────────────────────── */
+    async parseErrorResponse(r) {
+        const text = await r.text().catch(() => '');
+        try {
+            const data = JSON.parse(text);
+            return { error: data.detail || data.error || `HTTP ${r.status}`, status: r.status };
+        }
+        catch {
+            return { error: text || `HTTP ${r.status}`, status: r.status };
+        }
+    }
+    async getDetailed(path) {
+        try {
+            const r = await fetch(`${this.baseUrl}${path}`, {
+                headers: { ...this.authHeaders() },
+                signal: AbortSignal.timeout(5000),
+            });
+            if (!r.ok)
+                return this.parseErrorResponse(r);
+            return r.json();
+        }
+        catch (err) {
+            return { error: err?.message || 'Request failed', status: 0 };
+        }
+    }
+    async postDetailed(path, body = {}) {
+        try {
+            const r = await fetch(`${this.baseUrl}${path}`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', 'X-Caller-Type': 'PLATFORM', ...this.authHeaders() },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(15000),
+            });
+            if (!r.ok)
+                return this.parseErrorResponse(r);
+            return r.json();
+        }
+        catch (err) {
+            return { error: err?.message || 'Request failed', status: 0 };
+        }
+    }
+    async get(path) {
+        const result = await this.getDetailed(path);
+        return result?.error ? null : result;
+    }
+    async post(path, body = {}) {
+        const result = await this.postDetailed(path, body);
+        return result?.error ? null : result;
+    }
+    async put(path, body = {}) {
+        try {
+            const r = await fetch(`${this.baseUrl}${path}`, {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json', 'X-Caller-Type': 'PLATFORM', ...this.authHeaders() },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(15000),
+            });
+            if (!r.ok) {
+                const text = await r.text().catch(() => '');
+                try {
+                    return { error: JSON.parse(text).detail || `HTTP ${r.status}` };
+                }
+                catch {
+                    return { error: `HTTP ${r.status}` };
+                }
+            }
+            return r.json();
+        }
+        catch {
+            return null;
+        }
+    }
+    async patch(path, body = {}) {
+        try {
+            const r = await fetch(`${this.baseUrl}${path}`, {
+                method: 'PATCH',
+                headers: { 'Content-Type': 'application/json', 'X-Caller-Type': 'PLATFORM', ...this.authHeaders() },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(15000),
+            });
+            if (!r.ok) {
+                const text = await r.text().catch(() => '');
+                try {
+                    return { error: JSON.parse(text).detail || `HTTP ${r.status}` };
+                }
+                catch {
+                    return { error: `HTTP ${r.status}` };
+                }
+            }
+            return r.json();
+        }
+        catch {
+            return null;
+        }
+    }
+    async delete(path) {
+        try {
+            const r = await fetch(`${this.baseUrl}${path}`, {
+                method: 'DELETE',
+                headers: { 'X-Caller-Type': 'PLATFORM', ...this.authHeaders() },
+                signal: AbortSignal.timeout(15000),
+            });
+            if (!r.ok) {
+                const text = await r.text().catch(() => '');
+                try {
+                    return { error: JSON.parse(text).detail || `HTTP ${r.status}` };
+                }
+                catch {
+                    return { error: `HTTP ${r.status}` };
+                }
+            }
+            return r.json();
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Read SSE stream from a fetch Response.
+     * Mirrors shell-core's parseSSEChunk / createSSEReader.
+     */
+    async *readSSE(response) {
+        const body = response.body;
+        if (!body)
+            throw new Error('No response body');
+        const reader = body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        const CHUNK_TIMEOUT_MS = 120_000; // 120s between chunks
+        const WARN_TIMEOUT_MS = 60_000; // warn after 60s of silence
+        let lastChunkAt = Date.now();
+        let warningSent = false;
+        try {
+            while (true) {
+                // Race reader.read() against a timeout so the client never hangs
+                // if the backend stalls (e.g. reasoning model cold-start, 404 retry loop).
+                const readPromise = reader.read();
+                const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('SSE chunk timeout')), CHUNK_TIMEOUT_MS));
+                // Intermediate warning if no data for 60s
+                let warnTimer = null;
+                if (!warningSent) {
+                    warnTimer = setTimeout(() => {
+                        warningSent = true;
+                    }, WARN_TIMEOUT_MS);
+                }
+                let result;
+                try {
+                    result = await Promise.race([readPromise, timeoutPromise]);
+                    if (warnTimer)
+                        clearTimeout(warnTimer);
+                }
+                catch {
+                    if (warnTimer)
+                        clearTimeout(warnTimer);
+                    // Timeout — emit a typed timeout event (not a hard error) so the
+                    // renderer and REPL can check if the agent is still processing.
+                    const silentMs = Date.now() - lastChunkAt;
+                    yield { type: 'stream_timeout', data: { type: 'stream_timeout', timeout_ms: CHUNK_TIMEOUT_MS, silent_ms: silentMs } };
+                    break;
+                }
+                lastChunkAt = Date.now();
+                const { done, value } = result;
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                // Normalize \r\n → \n (SSE servers may use either)
+                buffer = buffer.replace(/\r\n/g, '\n');
+                const parts = buffer.split('\n\n');
+                buffer = parts.pop() || '';
+                for (const part of parts) {
+                    if (!part.trim())
+                        continue;
+                    const event = this.parseBlock(part);
+                    if (event)
+                        yield event;
+                }
+            }
+            if (buffer.trim()) {
+                const event = this.parseBlock(buffer);
+                if (event)
+                    yield event;
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    parseBlock(block) {
+        let eventType;
+        let eventData = null;
+        for (const line of block.split('\n')) {
+            if (line.startsWith('event: ')) {
+                eventType = line.slice(7).trim();
+            }
+            else if (line.startsWith('data: ')) {
+                try {
+                    eventData = JSON.parse(line.slice(6));
+                }
+                catch {
+                    eventData = { raw: line.slice(6).trim() };
+                }
+            }
+        }
+        if (!eventData)
+            return null;
+        if (eventType && !eventData.type)
+            eventData.type = eventType;
+        return {
+            type: eventData.type || eventType || 'unknown',
+            data: eventData,
+        };
+    }
+}

package/dist/command-registry.d.ts

@@ -0,0 +1,71 @@
+/**
+ * CommandRegistry — Score-based command matching and dynamic loading.
+ *
+ * Loads commands from:
+ *   1. commands.json (static definitions — immediate, offline fallback)
+ *   2. Genesis /shell/commands (aggregated catalog — all sources)
+ *   3. Genesis /shell/commands/mcp (MCP tools as callable commands)
+ *   4. Built-in handlers from commands.ts
+ *
+ * At REPL startup, loadDynamicCommands() fetches from Genesis and merges
+ * new commands into the registry. Static commands.json is never manually
+ * edited again — it serves as an offline fallback only.
+ */
+import type { GenesisClient } from './client.js';
+import type { ShellConfig } from './config.js';
+export interface CommandEntry {
+    name: string;
+    category: string;
+    description: string;
+    aliases: string[];
+    subcommands: string[];
+    source: string;
+    handler?: (client: GenesisClient, args: string, config: ShellConfig) => Promise<void>;
+    genesisEndpoint?: string;
+}
+interface DynamicCommandEntry {
+    name: string;
+    category: string;
+    description: string;
+    aliases: string[];
+    subcommands?: string[];
+    source: string;
+    genesis_endpoint?: string;
+    params?: any[];
+}
+export declare class CommandRegistry {
+    private commands;
+    private aliasMap;
+    private dynamicLoaded;
+    /** MCP tools discovered from Genesis — callable via /tools/call. */
+    private mcpTools;
+    constructor();
+    private loadFromJSON;
+    /**
+     * Fetch the unified command catalog from Genesis /shell/commands.
+     * Merges discovered commands into the registry without overwriting
+     * existing handlers. Call once at REPL startup.
+     */
+    loadDynamicCommands(client: GenesisClient): Promise<number>;
+    /** Get all discovered MCP tools. */
+    getMcpTools(): DynamicCommandEntry[];
+    /** Check if an MCP tool exists by name. */
+    getMcpTool(name: string): DynamicCommandEntry | undefined;
+    /** Register a built-in handler for a command. */
+    registerHandler(name: string, handler: CommandEntry['handler']): void;
+    /** Resolve a command name (handles aliases). */
+    resolve(input: string): CommandEntry | undefined;
+    /** Get all command names (including aliases). */
+    allNames(): string[];
+    /** Get all commands. */
+    allCommands(): CommandEntry[];
+    /** Whether dynamic commands have been loaded from Genesis. */
+    isDynamicLoaded(): boolean;
+    /** Score-based fuzzy matching for tab completion. */
+    match(partial: string, limit?: number): string[];
+    /** Get commands by category. */
+    byCategory(): Map<string, CommandEntry[]>;
+    get size(): number;
+}
+export declare function getCommandRegistry(): CommandRegistry;
+export {};