@aitherium/shell-cli 1.1.0 → 1.11.0

package/dist/mcp-client.js

@@ -0,0 +1,202 @@
+/**
+ * Minimal MCP StreamableHTTP client.
+ *
+ * Talks JSON-RPC to a remote MCP gateway (e.g. https://mcp.aitherium.com/mcp)
+ * using the MCP "Streamable HTTP" transport: each request is a POST whose
+ * response is either a single `application/json` body or a `text/event-stream`
+ * carrying the JSON-RPC reply. No external deps — mirrors client.ts's thin SSE
+ * style so the bundle still compiles via `bun build --compile`.
+ *
+ * Why this exists: the shell's chat backend (genesisUrl) speaks a REST
+ * `/tools/call`, but the cloud gateway (config.mcpUrl) speaks the MCP protocol
+ * at `/mcp`. When mcpUrl is set we route tool discovery + invocation here so
+ * AitherNode's tools work in-REPL against the cloud workspace.
+ */
+import { getActiveToken } from './auth.js';
+const PROTOCOL_VERSION = '2025-06-18';
+const CLIENT_INFO = { name: 'aither-shell', version: '1.7.3' };
+export class McpHttpClient {
+    url;
+    token;
+    sessionId = null;
+    nextId = 1;
+    initialized = false;
+    initInFlight = null;
+    constructor(url, token) {
+        // Strip trailing slashes only — keep the `/mcp` path intact.
+        this.url = url.replace(/\/+$/, '');
+        this.token = token ?? null;
+    }
+    /** Send a JSON-RPC request (or notification) and return its `result`. */
+    async rpc(method, params, isNotification = false) {
+        const id = isNotification ? undefined : this.nextId++;
+        const body = { jsonrpc: '2.0', method };
+        if (params !== undefined)
+            body.params = params;
+        if (id !== undefined)
+            body.id = id;
+        const headers = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json, text/event-stream',
+            'MCP-Protocol-Version': PROTOCOL_VERSION,
+        };
+        if (this.token) {
+            headers['Authorization'] = `Bearer ${this.token}`;
+            headers['X-API-Key'] = this.token;
+        }
+        if (this.sessionId)
+            headers['Mcp-Session-Id'] = this.sessionId;
+        let resp;
+        try {
+            resp = await fetch(this.url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(60_000),
+            });
+        }
+        catch (err) {
+            throw new Error(`MCP gateway unreachable (${method}): ${err?.message || err}`);
+        }
+        // The initialize response assigns the session id for subsequent calls.
+        const sid = resp.headers.get('mcp-session-id');
+        if (sid)
+            this.sessionId = sid;
+        if (isNotification)
+            return undefined; // 202 Accepted, no JSON-RPC reply
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => '');
+            if (resp.status === 401 || resp.status === 403) {
+                throw new Error(`MCP auth failed (HTTP ${resp.status}) — run \`/login\` or check your token.`);
+            }
+            throw new Error(`MCP ${method} failed: HTTP ${resp.status} ${text.slice(0, 200)}`);
+        }
+        const ctype = resp.headers.get('content-type') || '';
+        const message = ctype.includes('text/event-stream')
+            ? await this.readSseForId(resp, id)
+            : await resp.json();
+        if (message?.error) {
+            const e = message.error;
+            throw new Error(`MCP ${method} error: ${e?.message || JSON.stringify(e)}`);
+        }
+        return message?.result;
+    }
+    /** Read an SSE response body and return the JSON-RPC message matching `id`. */
+    async readSseForId(resp, id) {
+        const stream = resp.body;
+        if (!stream)
+            throw new Error('No MCP response body');
+        const reader = stream.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                buffer = buffer.replace(/\r\n/g, '\n');
+                const parts = buffer.split('\n\n');
+                buffer = parts.pop() || '';
+                for (const part of parts) {
+                    for (const line of part.split('\n')) {
+                        if (!line.startsWith('data:'))
+                            continue;
+                        const payload = line.slice(line.indexOf(':') + 1).trim();
+                        if (!payload)
+                            continue;
+                        try {
+                            const msg = JSON.parse(payload);
+                            // Skip server-initiated requests/notifications; we want our reply.
+                            if (msg && msg.id === id)
+                                return msg;
+                        }
+                        catch {
+                            /* keep-alive or partial — ignore */
+                        }
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        throw new Error(`MCP stream ended without a reply for id ${id}`);
+    }
+    /** Initialize the MCP session (idempotent, single-flight). */
+    async connect() {
+        if (this.initialized)
+            return;
+        if (this.initInFlight)
+            return this.initInFlight;
+        this.initInFlight = (async () => {
+            await this.rpc('initialize', {
+                protocolVersion: PROTOCOL_VERSION,
+                capabilities: {},
+                clientInfo: CLIENT_INFO,
+            });
+            // Best-effort "initialized" notification — some servers require it.
+            try {
+                await this.rpc('notifications/initialized', undefined, true);
+            }
+            catch {
+                /* non-fatal */
+            }
+            this.initialized = true;
+        })();
+        try {
+            await this.initInFlight;
+        }
+        finally {
+            this.initInFlight = null;
+        }
+    }
+    /** List the tools the authenticated caller is entitled to. */
+    async listTools() {
+        await this.connect();
+        const result = await this.rpc('tools/list', {});
+        return (result?.tools || []);
+    }
+    /** Invoke a tool by name. Returns the MCP `{content, isError}` result. */
+    async callTool(name, args = {}) {
+        await this.connect();
+        return (await this.rpc('tools/call', { name, arguments: args }));
+    }
+    /** Cheap reachability + auth check. */
+    async ping() {
+        try {
+            await this.connect();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+// ── Singleton keyed by (url, token) ───────────────────────────────────────
+// The REPL reuses one session per endpoint; a token/endpoint change rebuilds it.
+let _client = null;
+let _key = '';
+/**
+ * Return a remote MCP client for the active config, or null when no MCP
+ * gateway URL is configured (local/Genesis mode uses the chat backend's
+ * REST /tools/call instead).
+ */
+export function getRemoteMcpClient(config) {
+    if (!config?.mcpUrl)
+        return null;
+    // Prefer the live token from ~/.aither/auth.json so an in-REPL /login or
+    // /logout re-keys the client; fall back to the token captured at load time.
+    const token = getActiveToken() ?? config.authToken ?? null;
+    const key = `${config.mcpUrl}::${token || ''}`;
+    if (_client && _key === key)
+        return _client;
+    _client = new McpHttpClient(config.mcpUrl, token);
+    _key = key;
+    return _client;
+}
+/** Drop the cached client (e.g. after logout/endpoint change). */
+export function resetRemoteMcpClient() {
+    _client = null;
+    _key = '';
+}

package/dist/relay.d.ts

@@ -0,0 +1,96 @@
+/**
+ * AitherRelay client — native IRC-style group chat (humans + agents) over the
+ * relay WebSocket (`/ws/chat`, served by CommunicationCore). Agents joined to a
+ * channel respond in-line (server-side `_trigger_group_chat`), so this is the
+ * same multiagent room model as the DaoOS room.
+ *
+ * Protocol (client → server):
+ *   { type: 'join',    channel, nick, token }
+ *   { type: 'message', channel, content }
+ *   { type: 'typing',  channel }
+ *   { type: 'command', command: '/part', channel }
+ * (server → client): history | message | join | part | userlist | typing | error | system
+ *
+ * Auth: the token rides in the join payload (the relay resolves identity from
+ * it) — no custom WS headers needed, so the platform global WebSocket works.
+ */
+export interface RelayMessage {
+    channel: string;
+    nick: string;
+    content: string;
+    agent?: boolean;
+    timestamp?: number | string;
+    id?: string;
+}
+export interface RelayUser {
+    nick: string;
+    is_agent?: boolean;
+    status?: string;
+}
+export type RelayStatus = 'connecting' | 'open' | 'reconnecting' | 'closed';
+export interface RelayHandlers {
+    onStatus?: (status: RelayStatus, detail?: string) => void;
+    onHistory?: (channel: string, messages: RelayMessage[]) => void;
+    onMessage?: (msg: RelayMessage) => void;
+    onJoin?: (nick: string, channel: string, isAgent?: boolean) => void;
+    onPart?: (nick: string, channel: string) => void;
+    onUserlist?: (channel: string, users: RelayUser[]) => void;
+    onTyping?: (nick: string, channel: string) => void;
+    onError?: (message: string) => void;
+}
+export interface RelayChannel {
+    name: string;
+    topic?: string;
+    mode?: string;
+    user_count?: number;
+}
+/** Resolve the relay WS URL: AITHER_RELAY_URL override, else local CommunicationCore. */
+export declare function resolveRelayUrl(): string;
+export declare class RelayClient {
+    private ws;
+    private readonly url;
+    private readonly token?;
+    readonly nick: string;
+    private channel;
+    private readonly handlers;
+    private closedByUser;
+    private backoff;
+    private outbox;
+    constructor(opts: {
+        url?: string;
+        token?: string;
+        nick: string;
+        handlers: RelayHandlers;
+    });
+    get currentChannel(): string;
+    /** Join payload. When authenticated, OMIT the requested nick — the relay
+     *  rejects a join whose nick doesn't match the token's identity nick. Letting
+     *  the server pick the identity nick avoids that hard failure. Anonymous
+     *  sessions send their chosen nick. */
+    private joinPayload;
+    /** HTTP base for the relay REST API (derive from the ws url). */
+    private httpBase;
+    private authHeaders;
+    /** List channels via REST for the picker. `scope` selects platform (default —
+     *  public + the channels you can access, including workspace channels you're a
+     *  member of), 'community', or 'workspace:<slug>'. Anonymous sessions get the
+     *  public global/platform channels. Never throws. */
+    listChannels(scope?: string): Promise<RelayChannel[]>;
+    /** Fetch messages OLDER than `beforeTimestamp` (ISO) for scrollback. Returns
+     *  them oldest→newest. Never throws. */
+    loadOlder(beforeTimestamp: string, limit?: number): Promise<RelayMessage[]>;
+    /** Connect and join `channel`. Reconnects with backoff until disconnect(). */
+    connect(channel: string): void;
+    private open;
+    private scheduleReconnect;
+    private onData;
+    /** Switch channels (server sends fresh history + userlist). */
+    join(channel: string): void;
+    /** Send a chat message to the current channel. Queues if the socket is mid-
+     *  reconnect so nothing is silently dropped (flushed on the next open). */
+    send(content: string): void;
+    typing(): void;
+    part(channel?: string): void;
+    disconnect(): void;
+    private sendRaw;
+}

package/dist/relay.js

@@ -0,0 +1,234 @@
+/**
+ * AitherRelay client — native IRC-style group chat (humans + agents) over the
+ * relay WebSocket (`/ws/chat`, served by CommunicationCore). Agents joined to a
+ * channel respond in-line (server-side `_trigger_group_chat`), so this is the
+ * same multiagent room model as the DaoOS room.
+ *
+ * Protocol (client → server):
+ *   { type: 'join',    channel, nick, token }
+ *   { type: 'message', channel, content }
+ *   { type: 'typing',  channel }
+ *   { type: 'command', command: '/part', channel }
+ * (server → client): history | message | join | part | userlist | typing | error | system
+ *
+ * Auth: the token rides in the join payload (the relay resolves identity from
+ * it) — no custom WS headers needed, so the platform global WebSocket works.
+ */
+/** Resolve the relay WS URL: AITHER_RELAY_URL override, else local CommunicationCore. */
+export function resolveRelayUrl() {
+    const env = process.env.AITHER_RELAY_URL;
+    if (env)
+        return env.replace(/\/+$/, '');
+    // Local default — CommunicationCore serves the relay (root-mounted) on 8205,
+    // TLS-only, so wss://. The shell sets NODE_TLS_REJECT_UNAUTHORIZED=0 for the
+    // self-signed localhost cert. Point at wss://irc.aitherium.com/ws/chat for the
+    // hosted relay via AITHER_RELAY_URL.
+    return 'wss://127.0.0.1:8205/ws/chat';
+}
+export class RelayClient {
+    ws = null;
+    url;
+    token;
+    nick;
+    channel = '#general';
+    handlers;
+    closedByUser = false;
+    backoff = 1000;
+    outbox = []; // messages typed while the socket is down
+    constructor(opts) {
+        this.url = (opts.url || resolveRelayUrl()).replace(/\/+$/, '');
+        this.token = opts.token;
+        this.nick = opts.nick;
+        this.handlers = opts.handlers;
+    }
+    get currentChannel() { return this.channel; }
+    /** Join payload. When authenticated, OMIT the requested nick — the relay
+     *  rejects a join whose nick doesn't match the token's identity nick. Letting
+     *  the server pick the identity nick avoids that hard failure. Anonymous
+     *  sessions send their chosen nick. */
+    joinPayload(channel) {
+        const p = { type: 'join', channel };
+        if (this.token)
+            p.token = this.token;
+        else
+            p.nick = this.nick;
+        return p;
+    }
+    /** HTTP base for the relay REST API (derive from the ws url). */
+    httpBase() {
+        return this.url.replace(/^ws/, 'http').replace(/\/ws\/chat$/, '');
+    }
+    authHeaders() {
+        const h = { Accept: 'application/json' };
+        if (this.token)
+            h['Authorization'] = `Bearer ${this.token}`;
+        return h;
+    }
+    /** List channels via REST for the picker. `scope` selects platform (default —
+     *  public + the channels you can access, including workspace channels you're a
+     *  member of), 'community', or 'workspace:<slug>'. Anonymous sessions get the
+     *  public global/platform channels. Never throws. */
+    async listChannels(scope = 'platform') {
+        try {
+            const u = `${this.httpBase()}/v1/channels?scope=${encodeURIComponent(scope)}&nick=${encodeURIComponent(this.nick)}`;
+            const r = await fetch(u, { headers: this.authHeaders(), signal: AbortSignal.timeout(6000) });
+            if (!r.ok)
+                return [];
+            const data = await r.json();
+            const raw = Array.isArray(data) ? data : (data.channels || data.items || []);
+            return raw.map((c) => ({
+                name: typeof c === 'string' ? c : (c.name || c.channel || c.id),
+                topic: c.topic,
+                mode: c.mode,
+                user_count: c.user_count ?? c.users ?? c.member_count,
+            })).filter((c) => c.name);
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Fetch messages OLDER than `beforeTimestamp` (ISO) for scrollback. Returns
+     *  them oldest→newest. Never throws. */
+    async loadOlder(beforeTimestamp, limit = 50) {
+        try {
+            const ch = this.channel.replace(/^#/, '');
+            const u = `${this.httpBase()}/v1/channels/${encodeURIComponent(ch)}/messages`
+                + `?limit=${limit}&before=${encodeURIComponent(beforeTimestamp)}`;
+            const r = await fetch(u, { headers: this.authHeaders(), signal: AbortSignal.timeout(8000) });
+            if (!r.ok)
+                return [];
+            const data = await r.json();
+            const msgs = (Array.isArray(data) ? data : (data.messages || []));
+            return msgs.slice().sort((a, b) => String(a.timestamp).localeCompare(String(b.timestamp)));
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Connect and join `channel`. Reconnects with backoff until disconnect(). */
+    connect(channel) {
+        this.channel = channel || this.channel;
+        this.closedByUser = false;
+        this.open();
+    }
+    open() {
+        const WS = globalThis.WebSocket;
+        if (!WS) {
+            this.handlers.onError?.('WebSocket unavailable (needs Node 22+/bun).');
+            return;
+        }
+        this.handlers.onStatus?.('connecting');
+        let ws;
+        try {
+            ws = new WS(this.url);
+        }
+        catch (e) {
+            this.handlers.onError?.(`relay connect failed: ${e?.message || e}`);
+            this.scheduleReconnect();
+            return;
+        }
+        this.ws = ws;
+        ws.addEventListener('open', () => {
+            this.backoff = 1000;
+            this.handlers.onStatus?.('open');
+            this.sendRaw(this.joinPayload(this.channel));
+            // Flush anything typed while we were down (after the rejoin).
+            if (this.outbox.length) {
+                const pending = this.outbox.splice(0);
+                for (const content of pending)
+                    this.sendRaw({ type: 'message', channel: this.channel, content });
+            }
+        });
+        ws.addEventListener('message', (ev) => this.onData(ev.data));
+        ws.addEventListener('close', () => {
+            this.ws = null;
+            if (this.closedByUser)
+                this.handlers.onStatus?.('closed');
+            else
+                this.scheduleReconnect();
+        });
+        ws.addEventListener('error', () => { });
+    }
+    scheduleReconnect() {
+        if (this.closedByUser)
+            return;
+        this.handlers.onStatus?.('reconnecting');
+        const wait = this.backoff;
+        this.backoff = Math.min(this.backoff * 2, 15000);
+        setTimeout(() => { if (!this.closedByUser)
+            this.open(); }, wait);
+    }
+    onData(raw) {
+        let d;
+        try {
+            d = JSON.parse(String(raw));
+        }
+        catch {
+            return;
+        }
+        switch (d.type) {
+            case 'history':
+                this.handlers.onHistory?.(d.channel, (d.messages || []));
+                break;
+            case 'message':
+                this.handlers.onMessage?.(d);
+                break;
+            case 'join':
+                this.handlers.onJoin?.(d.nick, d.channel, d.is_agent);
+                break;
+            case 'part':
+                this.handlers.onPart?.(d.nick, d.channel);
+                break;
+            case 'userlist':
+                this.handlers.onUserlist?.(d.channel, (d.users || []));
+                break;
+            case 'typing':
+                this.handlers.onTyping?.(d.nick, d.channel);
+                break;
+            case 'error':
+            case 'system':
+                this.handlers.onError?.(d.message || d.content || 'relay error');
+                break;
+            default:
+                break;
+        }
+    }
+    /** Switch channels (server sends fresh history + userlist). */
+    join(channel) {
+        this.channel = channel.startsWith('#') ? channel : `#${channel}`;
+        this.sendRaw(this.joinPayload(this.channel));
+    }
+    /** Send a chat message to the current channel. Queues if the socket is mid-
+     *  reconnect so nothing is silently dropped (flushed on the next open). */
+    send(content) {
+        const c = (content || '').trim();
+        if (!c)
+            return;
+        const open = this.ws && this.ws.readyState === 1 /* OPEN */;
+        if (open)
+            this.sendRaw({ type: 'message', channel: this.channel, content: c });
+        else {
+            this.outbox.push(c);
+            if (this.outbox.length > 100)
+                this.outbox.shift();
+        }
+    }
+    typing() { this.sendRaw({ type: 'typing', channel: this.channel }); }
+    part(channel) {
+        this.sendRaw({ type: 'command', command: '/part', channel: channel || this.channel });
+    }
+    disconnect() {
+        this.closedByUser = true;
+        try {
+            this.ws?.close();
+        }
+        catch { /* */ }
+        this.ws = null;
+    }
+    sendRaw(obj) {
+        try {
+            this.ws?.send(JSON.stringify(obj));
+        }
+        catch { /* dropped; reconnect will rejoin */ }
+    }
+}

package/dist/renderer.d.ts

@@ -2,6 +2,9 @@
  * Terminal renderer — banners, streaming tokens, markdown, tables.
  */
 import type { SSEEvent } from './client.js';
+export declare const TRACE_FULL: boolean;
+/** Wrap text in an OSC 8 clickable hyperlink for terminals that support it. */
+export declare function osc8Link(url: string, label?: string): string;
 export declare function renderBanner(info: {
     genesis: string;
     genesisOnline?: boolean;
@@ -21,11 +24,21 @@ export declare function renderBanner(info: {
  * and render as clickable OSC 8 terminal hyperlinks.
  */
 export declare function resolveImagePath(relativePath: string): string;
+/** Strip OSC-8 hyperlink escapes (blessed/TUI can't render them → raw `]8;;`). */
+export declare function stripOsc8(text: string): string;
+/** Open a local image in the OS default viewer (detached). Best-effort. */
+export declare function openLocalImage(p: string): void;
+/** Scan answer text for generated-image markdown and open any LOCAL ones in the
+ *  OS viewer (so the user actually SEES the image — the TUI can't render it
+ *  inline). Opt out with AITHER_AUTO_OPEN_IMAGES=0. */
+export declare function autoOpenImagesFromText(text: string): void;
 export declare function renderMarkdown(text: string): string;
 export interface StreamRenderer {
     onEvent(event: SSEEvent): void;
     getContent(): string;
-    finish(): void;
+    /** End-of-turn cleanup. `aborted` = the user interrupted (Ctrl+C) — skip
+     *  the "stream ended before completion" warning in that case. */
+    finish(aborted?: boolean): void;
     /** Full trace of all events received during this session prompt. */
     getTrace(): SSEEvent[];
     /** Session profile for persistence and future reference. */
@@ -55,43 +68,53 @@ export interface SessionArtifact {
     size: number;
     language: string;
     retrieve_cmd: string;
+    download_url: string;
     timestamp: string;
 }
 export declare function getSessionArtifacts(): SessionArtifact[];
 export declare function clearSessionArtifacts(): void;
+/** Register a locally-saved file as a session artifact (so /get + /artifacts find it). */
+export declare function addSessionArtifact(a: {
+    path: string;
+    size?: number;
+    language?: string;
+}): number;
 export declare function createStreamRenderer(sessionId?: string, prompt?: string, steeringBar?: SteeringBar): StreamRenderer;
 export declare function formatTable(headers: string[], rows: string[][]): string;
 /**
- * Keeps a visible input line at the bottom of the terminal while
- * stream output prints above.  Works on Windows Terminal (no ANSI
- * scroll regions).
+ * Keeps a fixed input bar at the bottom of the terminal while
+ * stream output scrolls above.  Uses DECSTBM (Set Scrolling Region)
+ * to physically separate the output area from the bar — no stdout
+ * monkey-patching, no erase/redraw races.
  *
- * How it works:
- *   1. Intercepts process.stdout.write
- *   2. Before each write: erase the bar line so output doesn't collide
- *   3. After each write: redraw the bar on a fresh line below output
- *   4. User keystrokes update the bar's displayed text in real time
- *   5. On Enter, the bar clears and the repl routes to /chat/steer
+ * Layout:
+ *   Rows 1 to (rows-3):  SCROLL REGION — all output, tokens, spinners
+ *   Row (rows-2):         Status spinner (e.g., "generation...")
+ *   Row (rows-1):         Separator line ────────
+ *   Row (rows):           [steer] > input
  *
- * The bar line looks like:
- *   ── [steer] > what the user is typing_
+ * Output cannot collide with the bar because they occupy different
+ * terminal regions.
  */
 export declare class SteeringBar {
     private _active;
     private _inputText;
     private _statusText;
-    private _origWrite;
-    private _barDrawn;
-    private _debounceTimer;
     private _spinFrame;
     private _spinTimer;
+    private _tokenMode;
+    private _resizeHandler;
+    private _resizeTimer;
+    private _lastRows;
     private static readonly _SPIN_CHARS;
     get active(): boolean;
     get inputText(): string;
     activate(): void;
+    /** Debounced, artifact-free resize repaint. */
+    private _handleResize;
     deactivate(): void;
-    /** Schedule a single debounced redraw. All state changes route here. */
-    private _scheduleRedraw;
+    /** Set scroll region and draw bar, preserving cursor position. */
+    private _setupRegion;
     /** Show spinner + status text in the bar (replaces ora when bar is active). */
     setStatus(text: string): void;
     /** Clear status text. */
@@ -100,5 +123,12 @@ export declare class SteeringBar {
     setInput(text: string): void;
     /** Clear input after steer send. */
     clearInput(): void;
+    enterTokenMode(): void;
+    exitTokenMode(): void;
+    /**
+     * Draw the fixed bottom bar — single atomic write.
+     * Uses absolute positioning outside the scroll region, then restores
+     * cursor back into the scroll region.
+     */
     private _drawBar;
 }