@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/serve/screen-reader.js

@@ -0,0 +1,228 @@
+/**
+ * ScreenReader — PTY screen state parser for Orchestrator-over-PTY
+ *
+ * Parses raw PTY byte streams into structured, LLM-readable screen state.
+ * Uses @xterm/headless as the VT100/ANSI state machine so all escape
+ * sequences (colour, cursor movement, clear-screen, etc.) are handled
+ * correctly without a DOM.
+ *
+ * @issue #754
+ * @see src/serve/pty-bridge.ts — PTY WebSocket bridge
+ */
+import { EventEmitter } from 'events';
+import { createRequire } from 'module';
+// @xterm/headless is an optional dependency. Load it once at module level
+// using createRequire so we can import the CJS bundle from ESM.
+const _require = createRequire(import.meta.url);
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let XtermTerminal;
+try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const xterm = _require('@xterm/headless');
+    XtermTerminal = xterm.Terminal;
+}
+catch {
+    // Will be checked at construction time
+}
+// ============================================================
+// Prompt detection patterns
+// ============================================================
+/** Patterns that indicate the terminal is waiting for input. */
+const PROMPT_PATTERNS = [
+    /[$#>%]\s*$/, // bash/zsh/sh: ends with $ # > %
+    /^\s*\?\s+/, // inquirer: starts with ?
+    /\[y\/n\]/i, // yes/no confirmation
+    /\[y\/N\]/, // yes/no (default No)
+    /\[Y\/n\]/, // yes/no (default Yes)
+    /\(yes\/no\)/i, // SSH-style yes/no
+    /\(y\/n\)/i, // generic y/n
+];
+// ============================================================
+// ScreenReader
+// ============================================================
+export class ScreenReader {
+    terminal;
+    _rows;
+    _cols;
+    emitter;
+    disposed = false;
+    constructor(opts) {
+        if (!XtermTerminal) {
+            throw new Error('@xterm/headless is required for ScreenReader. Install it: npm install @xterm/headless');
+        }
+        this._rows = opts?.rows ?? 24;
+        this._cols = opts?.cols ?? 80;
+        this.emitter = new EventEmitter();
+        // Suppress Node.js MaxListenersExceededWarning for tests with many awaitChange calls
+        this.emitter.setMaxListeners(100);
+        this.terminal = new XtermTerminal({
+            rows: this._rows,
+            cols: this._cols,
+            allowProposedApi: true,
+            scrollback: 1000,
+            logLevel: 'error',
+        });
+    }
+    /** Feed raw PTY data into the parser */
+    write(data) {
+        if (this.disposed)
+            return;
+        const coreWriteSync = this.terminal._core?.writeSync;
+        if (coreWriteSync) {
+            coreWriteSync.call(this.terminal._core, data);
+            this.emitter.emit('change');
+            return;
+        }
+        this.terminal.write(data, () => {
+            // Fired after xterm has processed the write through its state machine
+            this.emitter.emit('change');
+        });
+    }
+    /** Get current parsed screen state */
+    getState() {
+        const buf = this.terminal.buffer.active;
+        const viewportRows = this.terminal.rows;
+        const viewportCols = this.terminal.cols;
+        // ---- visible text grid ----
+        const text = [];
+        for (let r = 0; r < viewportRows; r++) {
+            const line = buf.getLine(buf.viewportY + r);
+            if (!line) {
+                text.push(Array(viewportCols).fill(''));
+                continue;
+            }
+            const row = [];
+            for (let c = 0; c < viewportCols; c++) {
+                const cell = line.getCell(c);
+                row.push(cell?.getChars() ?? '');
+            }
+            text.push(row);
+        }
+        // ---- cursor ----
+        const cursor = {
+            row: buf.cursorY,
+            col: buf.cursorX,
+        };
+        // ---- scrollback ----
+        // baseY is the line index of the first viewport row in the full buffer.
+        // Lines 0..(baseY-1) are scrollback content.
+        const scrollback = [];
+        const scrollbackStart = Math.max(0, buf.baseY - 50); // keep last 50 scrollback lines
+        for (let r = scrollbackStart; r < buf.baseY; r++) {
+            const line = buf.getLine(r);
+            if (line) {
+                const lineStr = line.translateToString(true);
+                scrollback.push(lineStr);
+            }
+        }
+        // ---- summary ----
+        const summary = buildSummary(text);
+        // ---- prompt detection ----
+        const { prompt_detected, prompt_text } = detectPrompt(text, cursor);
+        return { text, cursor, scrollback, summary, prompt_detected, prompt_text };
+    }
+    /**
+     * Wait for the next screen change, with timeout.
+     * Resolves with updated ScreenState when write() causes a change,
+     * or with the current state if the timeout elapses first.
+     */
+    awaitChange(opts) {
+        const timeoutMs = opts?.timeout ?? 5000;
+        return new Promise((resolve) => {
+            if (this.disposed) {
+                resolve(this.getState());
+                return;
+            }
+            let timer = null;
+            const handler = () => {
+                if (timer)
+                    clearTimeout(timer);
+                resolve(this.getState());
+            };
+            this.emitter.once('change', handler);
+            timer = setTimeout(() => {
+                this.emitter.removeListener('change', handler);
+                resolve(this.getState());
+            }, timeoutMs);
+        });
+    }
+    /**
+     * Flush all pending writes through xterm's internal write queue.
+     * Enqueues an empty write and resolves when its callback fires, which
+     * guarantees all previously queued writes have been processed.
+     */
+    flush() {
+        return new Promise((resolve) => {
+            if (this.disposed) {
+                resolve();
+                return;
+            }
+            this.terminal.write('', () => resolve());
+        });
+    }
+    /** Get human-readable summary of visible screen */
+    getSummary() {
+        return buildSummary(this.getState().text);
+    }
+    /** Clean up resources */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.emitter.removeAllListeners();
+        try {
+            this.terminal.dispose();
+        }
+        catch {
+            // ignore errors during cleanup
+        }
+    }
+}
+// ============================================================
+// Helpers
+// ============================================================
+/**
+ * Build a human-readable summary from the visible text grid.
+ * Trailing rows that are entirely empty are stripped.
+ */
+function buildSummary(text) {
+    const lines = text.map((row) => row.join('').trimEnd());
+    // Remove trailing blank lines
+    let lastNonEmpty = lines.length - 1;
+    while (lastNonEmpty >= 0 && lines[lastNonEmpty].trim() === '') {
+        lastNonEmpty--;
+    }
+    return lines.slice(0, lastNonEmpty + 1).join('\n');
+}
+/**
+ * Heuristic prompt detection.
+ * Examines the last non-empty visible line and the line at cursor position.
+ */
+function detectPrompt(text, cursor) {
+    // Gather candidate lines: the cursor row and the last non-empty row
+    const candidates = [];
+    // Line where cursor currently sits
+    if (cursor.row >= 0 && cursor.row < text.length) {
+        const cursorLine = text[cursor.row].join('').trimEnd();
+        if (cursorLine)
+            candidates.push(cursorLine);
+    }
+    // Last non-empty visible line
+    for (let r = text.length - 1; r >= 0; r--) {
+        const line = text[r].join('').trimEnd();
+        if (line) {
+            if (!candidates.includes(line))
+                candidates.push(line);
+            break;
+        }
+    }
+    for (const line of candidates) {
+        for (const pattern of PROMPT_PATTERNS) {
+            if (pattern.test(line)) {
+                return { prompt_detected: true, prompt_text: line };
+            }
+        }
+    }
+    return { prompt_detected: false };
+}
+//# sourceMappingURL=screen-reader.js.map

package/dist/src/serve/stack-adapters.js

@@ -0,0 +1,68 @@
+/**
+ * Per-stack executor adapters (#1546).
+ *
+ * A Mission conductor (mission-conductor.ts) fans worker cycles out across
+ * *heterogeneous* agentic stacks. Each stack advertises itself on the existing
+ * executor registry via a `runtime:<name>` capability — the convention proven
+ * in slice 1 (see test/unit/serve/agent-router.test.ts "cross-stack Mission
+ * dispatch"). A StackAdapter is the conductor-side description of how a worker
+ * cycle maps onto that stack's NATIVE long-running primitive, plus the runtime
+ * capability token the conductor filters on — so the conductor dispatches and
+ * captures results uniformly regardless of which stack runs the worker.
+ *
+ * The adapter does NOT run the worker. The registered executor on that stack
+ * runs it via `aiwg serve`'s dispatch transport (dispatch-router + the WS event
+ * stream). The adapter keeps the conductor stack-agnostic: it owns only the
+ * `runtime:<name>` token and the native-primitive description.
+ *
+ * @implements #1546
+ */
+function makeAdapter(runtime, primitive) {
+    const runtimeCapability = `runtime:${runtime}`;
+    return {
+        runtime,
+        runtimeCapability,
+        primitive,
+        invoke(prompt) {
+            // prompt is carried by the dispatch payload; the descriptor records the
+            // mechanism so the conductor's ledger is identical-shape across stacks.
+            const trimmed = prompt.length > 60 ? `${prompt.slice(0, 57)}...` : prompt;
+            return {
+                runtimeCapability,
+                primitive,
+                describe: `dispatch worker to ${runtime} executor via ${primitive} (${trimmed})`,
+            };
+        },
+    };
+}
+/** Codex executor adapter — a dispatched worker drives Codex `/goal` (or `/aiwg-mission`, #1544). */
+export const codexAdapter = makeAdapter('codex', '/goal');
+/** Claude Code executor adapter — a dispatched worker drives the Workflow tool / subagents. */
+export const claudeCodeAdapter = makeAdapter('claude-code', 'workflow-tool');
+/** Built-in adapters for the two stacks the cross-stack proof exercises. */
+export const BUILTIN_STACK_ADAPTERS = [codexAdapter, claudeCodeAdapter];
+/**
+ * Registry of per-stack adapters. Operators can register additional stacks
+ * (the `runtime:<name>` convention is open-ended); a Mission can then dispatch
+ * workers to any registered runtime.
+ */
+export class StackAdapterRegistry {
+    byRuntime = new Map();
+    constructor(adapters = BUILTIN_STACK_ADAPTERS) {
+        for (const a of adapters)
+            this.byRuntime.set(a.runtime, a);
+    }
+    register(adapter) {
+        this.byRuntime.set(adapter.runtime, adapter);
+    }
+    get(runtime) {
+        return this.byRuntime.get(runtime);
+    }
+    has(runtime) {
+        return this.byRuntime.has(runtime);
+    }
+    runtimes() {
+        return [...this.byRuntime.keys()];
+    }
+}
+//# sourceMappingURL=stack-adapters.js.map

package/dist/src/serve/telemetry.js

@@ -0,0 +1,143 @@
+/**
+ * Telemetry Event Schema and In-Memory Store
+ *
+ * Defines the canonical event types emitted by the agent loop, MC conductor,
+ * and ralph launcher. Events are stored in-memory per session and forwarded
+ * to the browser via WebSocket push. Persisted to fortemi-react IndexedDB
+ * on the browser side (#717).
+ *
+ * Emission points:
+ *   - src/cli/handlers/ralph-launcher.ts → iteration.*, gate.*, tokens.used
+ *   - src/cli/handlers/mc.ts → session.*, mission.*, agent.*
+ *
+ * @issue #716
+ * @see #717 — fortemi-react storage layer (browser)
+ */
+// ============================================================
+// In-Memory Event Store
+// ============================================================
+const MAX_EVENTS_PER_SESSION = 10_000;
+export class TelemetryStore {
+    events = new Map();
+    listeners = new Set();
+    /** Ingest a new event */
+    ingest(event) {
+        const list = this.events.get(event.sessionId) ?? [];
+        list.push(event);
+        // Trim oldest events when exceeding limit
+        if (list.length > MAX_EVENTS_PER_SESSION) {
+            list.splice(0, list.length - MAX_EVENTS_PER_SESSION);
+        }
+        this.events.set(event.sessionId, list);
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch { /* ignore listener errors */ }
+        }
+    }
+    /** Get all events for a session, optionally filtered by type */
+    query(sessionId, opts = {}) {
+        let events = this.events.get(sessionId) ?? [];
+        if (opts.types?.length) {
+            events = events.filter((e) => opts.types.includes(e.type));
+        }
+        if (opts.since) {
+            events = events.filter((e) => e.timestamp >= opts.since);
+        }
+        if (opts.limit) {
+            events = events.slice(-opts.limit);
+        }
+        return events;
+    }
+    /** Get aggregate metrics for a session */
+    metrics(sessionId) {
+        const events = this.events.get(sessionId) ?? [];
+        let totalInput = 0;
+        let totalOutput = 0;
+        const tokensByModel = {};
+        let iterations = 0;
+        let gatePasses = 0;
+        let gateFails = 0;
+        let scopeDone = 0;
+        let scopeTotal = 0;
+        let activeAgents = 0;
+        for (const e of events) {
+            if (e.type === 'tokens.used') {
+                const p = e.payload;
+                totalInput += p.input;
+                totalOutput += p.output;
+                const m = tokensByModel[p.model] ?? { input: 0, output: 0 };
+                m.input += p.input;
+                m.output += p.output;
+                tokensByModel[p.model] = m;
+            }
+            else if (e.type === 'iteration.complete') {
+                iterations++;
+            }
+            else if (e.type === 'gate.pass') {
+                gatePasses++;
+            }
+            else if (e.type === 'gate.fail') {
+                gateFails++;
+            }
+            else if (e.type === 'scope.unit.complete') {
+                const p = e.payload;
+                scopeDone = p.done;
+                scopeTotal = p.total;
+            }
+            else if (e.type === 'agent.spawn') {
+                activeAgents++;
+            }
+            else if (e.type === 'agent.complete') {
+                activeAgents = Math.max(0, activeAgents - 1);
+            }
+        }
+        const passRate = gatePasses + gateFails > 0
+            ? Math.round((gatePasses / (gatePasses + gateFails)) * 100)
+            : null;
+        return {
+            sessionId,
+            totalInputTokens: totalInput,
+            totalOutputTokens: totalOutput,
+            tokensByModel,
+            iterations,
+            gatePasses,
+            gateFails,
+            passRate,
+            scopeDone,
+            scopeTotal,
+            activeAgents,
+        };
+    }
+    /** Subscribe to new events (returns unsubscribe fn) */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    /** Clear all events for a session */
+    clear(sessionId) {
+        this.events.delete(sessionId);
+    }
+    /** Get all known session IDs */
+    sessions() {
+        return [...this.events.keys()];
+    }
+}
+// Singleton store
+export const telemetryStore = new TelemetryStore();
+// ============================================================
+// Event Factory
+// ============================================================
+let eventCounter = 0;
+export function createEvent(type, sessionId, payload, missionId) {
+    return {
+        id: `evt-${Date.now()}-${++eventCounter}`,
+        sessionId,
+        missionId,
+        timestamp: new Date().toISOString(),
+        type,
+        payload,
+    };
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/src/skills/adapters/clawhub.js

@@ -0,0 +1,250 @@
+/**
+ * ClawHub Registry Adapter
+ *
+ * Connects to the ClawHub REST API at clawhub.ai for
+ * community skill discovery and publishing.
+ *
+ * Supports both the ClawHub web API and the `clawhub` CLI
+ * if installed. Falls back gracefully when neither is available.
+ *
+ * @implements #539
+ * @see https://clawhub.ai
+ * @see https://docs.openclaw.ai/tools/clawhub
+ */
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { getProviderDefinition, resolveProviderPathValue, } from '../../providers/provider-definitions.js';
+const CLAWHUB_API_BASE = 'https://clawhub.ai/api/v1';
+function resolveSkillFallbackPath(target, projectDir, name) {
+    const definition = getProviderDefinition(target);
+    if (!definition)
+        return path.join(projectDir, `.${target}/skills`, name);
+    const basePath = definition.skillNamespace.pathType === 'home-dir'
+        ? `~/${definition.skillNamespace.skillsBaseDir}`
+        : definition.skillNamespace.skillsBaseDir;
+    return path.join(resolveProviderPathValue(basePath, projectDir), name);
+}
+/**
+ * Attempt a ClawHub API request
+ */
+async function clawHubFetch(endpoint) {
+    try {
+        const response = await fetch(`${CLAWHUB_API_BASE}${endpoint}`, {
+            headers: { 'Accept': 'application/json' },
+            signal: AbortSignal.timeout(10000),
+        });
+        if (!response.ok)
+            return null;
+        return await response.json();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Try clawhub CLI command
+ */
+function runClawHub(args) {
+    try {
+        return execSync(`clawhub ${args}`, {
+            encoding: 'utf-8',
+            timeout: 30000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+export class ClawHubAdapter {
+    id = 'clawhub';
+    name = 'ClawHub Registry';
+    available = null;
+    async isAvailable() {
+        if (this.available !== null)
+            return this.available;
+        // Check CLI
+        const cliAvailable = runClawHub('--version 2>/dev/null') !== null;
+        if (cliAvailable) {
+            this.available = true;
+            return true;
+        }
+        // Check API
+        const apiResult = await clawHubFetch('/health');
+        this.available = apiResult !== null;
+        return this.available;
+    }
+    async search(query) {
+        // Try API
+        const apiResult = await clawHubFetch(`/skills/search?q=${encodeURIComponent(query)}`);
+        if (apiResult && Array.isArray(apiResult.results)) {
+            return apiResult.results.map((s) => ({
+                name: s.name,
+                description: s.description || '',
+                source: 'clawhub',
+                package: s.package || s.author,
+                platforms: s.platforms || [],
+                installed: false,
+            }));
+        }
+        // Try CLI
+        const cliOutput = runClawHub(`search "${query}" --json 2>/dev/null`);
+        if (cliOutput) {
+            try {
+                const parsed = JSON.parse(cliOutput);
+                if (Array.isArray(parsed)) {
+                    return parsed.map((s) => ({
+                        name: s.name,
+                        description: s.description || '',
+                        source: 'clawhub',
+                        package: s.package || s.author,
+                        platforms: s.platforms || [],
+                        installed: false,
+                    }));
+                }
+            }
+            catch {
+                // Fall through
+            }
+        }
+        return [];
+    }
+    async info(name) {
+        // Try API
+        const apiResult = await clawHubFetch(`/skills/${encodeURIComponent(name)}`);
+        if (apiResult && apiResult.name) {
+            return {
+                name: apiResult.name,
+                description: apiResult.description || '',
+                source: 'clawhub',
+                package: apiResult.package || apiResult.author,
+                platforms: apiResult.platforms || [],
+                version: apiResult.version,
+                triggers: apiResult.triggers || [],
+                tools: apiResult.tools || [],
+                installed: false,
+            };
+        }
+        // Try CLI
+        const cliOutput = runClawHub(`info "${name}" --json 2>/dev/null`);
+        if (cliOutput) {
+            try {
+                const parsed = JSON.parse(cliOutput);
+                return {
+                    name: parsed.name || name,
+                    description: parsed.description || '',
+                    source: 'clawhub',
+                    package: parsed.package || parsed.author,
+                    platforms: parsed.platforms || [],
+                    version: parsed.version,
+                    triggers: parsed.triggers || [],
+                    installed: false,
+                };
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return undefined;
+    }
+    async list() {
+        // Try API
+        const apiResult = await clawHubFetch('/skills?limit=200');
+        if (apiResult && Array.isArray(apiResult.results)) {
+            return apiResult.results.map((s) => ({
+                name: s.name,
+                description: s.description || '',
+                source: 'clawhub',
+                package: s.package || s.author,
+                platforms: s.platforms || [],
+                installed: false,
+            }));
+        }
+        // Try CLI
+        const cliOutput = runClawHub('list --json 2>/dev/null');
+        if (cliOutput) {
+            try {
+                const parsed = JSON.parse(cliOutput);
+                if (Array.isArray(parsed)) {
+                    return parsed.map((s) => ({
+                        name: s.name,
+                        description: s.description || '',
+                        source: 'clawhub',
+                        package: s.package || s.author,
+                        platforms: s.platforms || [],
+                        installed: false,
+                    }));
+                }
+            }
+            catch {
+                // Fall through
+            }
+        }
+        return [];
+    }
+    async install(name, options) {
+        const target = options.target || 'claude';
+        // Determine target directory
+        let targetDir;
+        try {
+            const { PlatformSkillResolver } = await import('../../smiths/skillsmith/platform-resolver.js');
+            targetDir = PlatformSkillResolver.getSkillPath(target, options.projectDir, name);
+        }
+        catch {
+            targetDir = resolveSkillFallbackPath(target, options.projectDir, name);
+        }
+        // Try CLI install (downloads to a temp location, then we copy)
+        const cliResult = runClawHub(`install "${name}" --output "${targetDir}" 2>/dev/null`);
+        if (cliResult !== null)
+            return;
+        // Try API download
+        const apiResult = await clawHubFetch(`/skills/${encodeURIComponent(name)}/download`);
+        if (apiResult && apiResult.content) {
+            fs.mkdirSync(targetDir, { recursive: true });
+            const skillMdPath = path.join(targetDir, 'SKILL.md');
+            fs.writeFileSync(skillMdPath, apiResult.content, 'utf-8');
+            return;
+        }
+        throw new Error(`Could not install '${name}' from ClawHub. ` +
+            `Ensure the skill exists at https://clawhub.ai and the API is accessible.`);
+    }
+    async publish(packageDir) {
+        // Ensure clawhub.json exists — generate from manifest.json if missing
+        const clawHubManifestPath = path.join(packageDir, 'clawhub.json');
+        if (!fs.existsSync(clawHubManifestPath)) {
+            const manifestPath = path.join(packageDir, 'manifest.json');
+            if (fs.existsSync(manifestPath)) {
+                const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                const pkgJsonPath = path.resolve(packageDir, '..', '..', '..', '..', 'package.json');
+                let version = '0.0.0';
+                try {
+                    const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+                    version = pkg.version || version;
+                }
+                catch {
+                    // Use default version
+                }
+                const clawHubManifest = {
+                    name: manifest.name || path.basename(packageDir),
+                    version,
+                    description: manifest.description || '',
+                    homepage: 'https://aiwg.io',
+                    repository: 'https://github.com/jmagly/aiwg',
+                    skills: './skills',
+                    tags: manifest.tags || manifest.keywords || [],
+                    license: 'MIT',
+                    author: 'AIWG Contributors',
+                };
+                fs.writeFileSync(clawHubManifestPath, JSON.stringify(clawHubManifest, null, 2) + '\n', 'utf-8');
+            }
+        }
+        // Try CLI publish
+        const cliResult = runClawHub(`publish "${packageDir}" 2>/dev/null`);
+        if (cliResult !== null)
+            return;
+        throw new Error('ClawHub publish requires the clawhub CLI. ' +
+            'Install it from https://docs.openclaw.ai/tools/clawhub');
+    }
+}
+//# sourceMappingURL=clawhub.js.map