hydra-os-cli 0.1.0

package/README.md

@@ -0,0 +1,274 @@
+# hydra-os-cli
+
+Terminal user interface for the Hydra multi-agent workflow orchestrator. Monitor workflows, approve decisions, and manage agents from your terminal.
+
+Built with [Ink](https://github.com/vadimdemedes/ink) (React for CLI), TypeScript, and Zustand.
+
+## Install
+
+```bash
+npm install -g hydra-os-cli
+```
+
+Or run without installing:
+
+```bash
+npx hydra-os-cli doctor --json
+```
+
+## Prerequisites
+
+- Node.js 18+
+- Hydra API running on `http://localhost:7070` (or configured via `~/.hydra/config.yaml`)
+- Temporal server running on `localhost:7233`
+
+## CLI Usage
+
+```
+hydra-os                                Launch interactive TUI (default)
+hydra-os --attach <workflow-id>         Launch and attach to a running workflow
+hydra-os --theme <name>                 Launch with a specific theme
+hydra-os status <workflow-id>           Check workflow status (non-interactive)
+hydra-os status <workflow-id> --json    Output status as JSON
+hydra-os list                           List all workflows (non-interactive)
+hydra-os list --json                    Output workflow list as JSON
+hydra-os doctor                         Run service health checks (non-interactive)
+hydra-os doctor --json                  Output health checks as JSON
+```
+
+### JSON Output
+
+All non-interactive commands support `--json` for scriptable output:
+
+```bash
+# Pipe workflow list to jq
+hydra-os list --json | jq '.[].status'
+
+# Check a specific workflow programmatically
+hydra-os status wf-abc123 --json | jq '.status.phase'
+
+# Health check in CI
+hydra-os doctor --json | jq '.api.status'
+```
+
+### Examples
+
+```bash
+# Start the interactive TUI
+hydra-os
+
+# Attach to a workflow on launch
+hydra-os --attach wf-abc123
+
+# Check a workflow from the command line without entering the TUI
+hydra-os status wf-abc123
+
+# List all workflows
+hydra-os list
+
+# Health check all services
+hydra-os doctor
+```
+
+### Development Mode
+
+```bash
+cd apps/tui
+npm install
+npm run dev
+```
+
+## Interactive Commands
+
+Once inside the TUI, type slash commands in the input bar. Press `Tab` to autocomplete.
+
+### Core
+
+| Command    | Description                                    |
+|------------|------------------------------------------------|
+| `/help`    | Show all available commands                    |
+| `/clear`   | Clear chat output                              |
+| `/doctor`  | Health check (API, Temporal, Qdrant, workers)  |
+
+### Workflow
+
+| Command                          | Description                          |
+|----------------------------------|--------------------------------------|
+| `/start <description>`           | Start a new workflow from natural language |
+| `/status [workflow-id]`          | Show workflow status (defaults to active) |
+| `/list`                          | List all workflows                   |
+| `/attach <workflow-id>`          | Attach to a workflow's live SSE stream |
+| `/detach`                        | Detach from live stream              |
+| `/approve [workflow-id]`         | Approve pending approval             |
+| `/deny [workflow-id] [feedback]` | Deny pending approval with optional feedback |
+| `/pause [workflow-id]`           | Pause a running workflow             |
+| `/resume [workflow-id]`          | Resume a paused workflow             |
+| `/cancel confirm [workflow-id]`  | Cancel a workflow (requires `confirm`) |
+
+### Agent
+
+| Command          | Description                          |
+|------------------|--------------------------------------|
+| `/agents`        | List all agent roles and their status |
+| `/agent <role>`  | Show details for a specific agent role |
+
+### Config
+
+| Command   | Description                            |
+|-----------|----------------------------------------|
+| `/roles`  | Show role catalog from config/roles.yaml |
+
+## Keyboard Shortcuts
+
+| Key      | Action               |
+|----------|----------------------|
+| `Ctrl+P` | Toggle side panels   |
+| `Ctrl+D` | Exit                 |
+| `Tab`    | Autocomplete command |
+
+## Layout
+
+The TUI uses a split-pane layout:
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ Hydra TUI v0.1.0                        ● IDLE          │
+├───────────────────────────────────┬──────────────────────┤
+│                                   │ Agents               │
+│  Chat / Command Output            │  ○ pm.prd    pending │
+│                                   │  ⏳ eng.init running │
+│                                   │  ...                 │
+│                                   ├──────────────────────┤
+│                                   │ Artifacts            │
+│                                   │  📄 prd.md           │
+│                                   ├──────────────────────┤
+│                                   │ Memory               │
+│                                   │  3 decisions, 7 facts│
+├───────────────────────────────────┴──────────────────────┤
+│ > /start Build a REST API for user auth                  │
+├──────────────────────────────────────────────────────────┤
+│ no workflow    —    tokens: 0    $0.00    0s             │
+└──────────────────────────────────────────────────────────┘
+```
+
+Toggle the right panel with `Ctrl+P` for a full-width chat view.
+
+## Configuration
+
+The TUI reads configuration from `~/.hydra/config.yaml` with sensible defaults. No config file is required — everything works out of the box for local development.
+
+### Config File
+
+Create `~/.hydra/config.yaml`:
+
+```yaml
+temporal:
+  address: localhost:7233
+  namespace: default
+
+api:
+  url: http://localhost:7070
+
+qdrant:
+  url: http://localhost:6333
+
+tui:
+  theme: dark          # dark, light, solarized, monokai, hydra
+  layout: split        # split, full
+  rightPanel: true
+  vimMode: false
+  maxHistory: 1000     # max chat messages kept in memory
+  spinnerStyle: dots   # dots, line, arc, bounce
+
+workflow:
+  defaultModel: claude-sonnet-4-5-20250929
+  autoApproveReads: true
+  qualityThreshold: 28
+  costWarning: 5.0     # warn when workflow cost exceeds this ($)
+
+notifications:
+  sound: true
+  desktop: true
+  idleAlert: 300       # seconds before idle alert
+```
+
+### Environment Variable Overrides
+
+Environment variables take precedence over the config file:
+
+| Variable           | Overrides         | Example                      |
+|--------------------|-------------------|------------------------------|
+| `TEMPORAL_ADDRESS` | `temporal.address` | `localhost:7233`            |
+| `HYDRA_API_URL`    | `api.url`          | `http://localhost:7070`     |
+| `QDRANT_URL`       | `qdrant.url`       | `http://localhost:6333`     |
+| `HYDRA_THEME`      | `tui.theme`        | `dark`                      |
+
+```bash
+# Example: connect to a remote API
+HYDRA_API_URL=http://192.168.1.50:7070 npm run dev
+```
+
+## Development
+
+```bash
+# Typecheck
+npm run typecheck
+
+# Run tests
+npm test
+
+# Build to dist/
+npm run build
+```
+
+### Project Structure
+
+```
+src/
+  cli.tsx              CLI entry point (Commander)
+  app.tsx              Main Ink application component
+  store.ts             Zustand state store
+  config.ts            Config loading and validation (Zod)
+  sse.ts               SSE streaming with reconnection
+  clients/
+    api.ts             REST API client
+    temporal.ts        Temporal client (stub)
+    qdrant.ts          Qdrant client (stub)
+  commands/
+    registry.ts        Command registry with autocomplete
+    index.ts           Command registration
+    core.ts            /help, /clear, /doctor
+    workflow.ts         /start, /status, /list, /approve, ...
+    agent.ts           /agents, /agent
+    config.ts          /roles, /config, /theme
+    artifact.ts        Artifact commands (Phase 3)
+    memory.ts          Memory commands (Phase 3)
+    session.ts         Session commands (Phase 4)
+  widgets/
+    header.tsx         Header bar
+    chat-panel.tsx     Chat message display (windowed)
+    agent-panel.tsx    Agent status panel
+    artifact-tree.tsx  Artifact tree view
+    memory-panel.tsx   Memory stats panel
+    input-bar.tsx      Input with Tab autocomplete
+    status-bar.tsx     Footer status bar
+    timeline.tsx       Workflow timeline
+    health-check.tsx   Health check display
+    approval-modal.tsx Approval modal
+  screens/
+    main.tsx           Main screen (re-exports App)
+    help.tsx           Help screen
+    workflow-detail.tsx Workflow detail view
+    workflow-list.tsx  Workflow list view
+```
+
+## Typical Workflow
+
+1. Launch the TUI: `npm run dev`
+2. Check services are healthy: `/doctor`
+3. Start a workflow: `/start Build a user authentication system with JWT`
+4. Watch progress via the agent panel and chat stream
+5. Attach to live updates if not already streaming: `/attach <workflow-id>`
+6. Approve when prompted: `/approve`
+7. Check final status: `/status`
+8. List all workflows: `/list`

package/dist/app.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Main Hydra TUI application.
+ *
+ * Renders the split-pane layout with chat panel, agent panel,
+ * artifact tree, memory panel, input bar, and status bar.
+ */
+interface AppProps {
+    attachWorkflow?: string;
+    themeName?: string;
+}
+export declare function App({ attachWorkflow, themeName }: AppProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/app.js

@@ -0,0 +1,127 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Main Hydra TUI application.
+ *
+ * Renders the split-pane layout with chat panel, agent panel,
+ * artifact tree, memory panel, input bar, and status bar.
+ */
+import { useState, useEffect, useRef, useCallback } from "react";
+import { Box, useApp, useInput } from "ink";
+import { Header } from "./widgets/header.js";
+import { ChatPanel } from "./widgets/chat-panel.js";
+import { AgentPanel } from "./widgets/agent-panel.js";
+import { ArtifactTree } from "./widgets/artifact-tree.js";
+import { MemoryPanel } from "./widgets/memory-panel.js";
+import { InputBar } from "./widgets/input-bar.js";
+import { StatusBar } from "./widgets/status-bar.js";
+import { useStore } from "./store.js";
+import { loadConfig } from "./config.js";
+import { getApiClient } from "./clients/api.js";
+import { registerAllCommands, getCommand } from "./commands/index.js";
+function toDisplayStatus(apiStatus) {
+    switch (apiStatus) {
+        case "active": return "running";
+        case "idle": return "pending";
+        case "completed": return "done";
+        case "waiting": return "waiting";
+        case "error":
+        case "failed": return "failed";
+        default: return "pending";
+    }
+}
+export function App({ attachWorkflow, themeName = "dark" }) {
+    const { exit } = useApp();
+    const [showRightPanel, setShowRightPanel] = useState(true);
+    const apiRef = useRef(null);
+    const commandsRegistered = useRef(false);
+    // Zustand selectors
+    const messages = useStore((s) => s.messages);
+    const activeWorkflowId = useStore((s) => s.activeWorkflowId);
+    const agents = useStore((s) => s.agents);
+    const activeWorkflow = useStore((s) => s.activeWorkflow);
+    const apiStatus = useStore((s) => s.apiStatus);
+    // Initialize on mount
+    useEffect(() => {
+        const config = loadConfig();
+        const store = useStore.getState();
+        store.setApiUrl(config.api.url);
+        apiRef.current = getApiClient(config.api.url);
+        if (!commandsRegistered.current) {
+            registerAllCommands();
+            commandsRegistered.current = true;
+        }
+        // Initial health check
+        store.setApiStatus("connecting");
+        apiRef.current.healthCheck().then(() => store.setApiStatus("connected"), () => store.setApiStatus("error"));
+        // Cleanup SSE on unmount
+        return () => {
+            useStore.getState().abortAllSse();
+        };
+    }, []);
+    // Attach to workflow when prop changes
+    useEffect(() => {
+        if (attachWorkflow) {
+            useStore.getState().setActiveWorkflowId(attachWorkflow);
+        }
+    }, [attachWorkflow]);
+    useInput((input, key) => {
+        if (key.ctrl && input === "p") {
+            setShowRightPanel((prev) => !prev);
+        }
+        if (key.ctrl && input === "d") {
+            useStore.getState().abortAllSse();
+            exit();
+        }
+    });
+    const handleCommand = useCallback(async (text) => {
+        const store = useStore.getState();
+        const api = apiRef.current ?? getApiClient();
+        if (text.startsWith("/")) {
+            const parts = text.slice(1).split(/\s+/);
+            const cmdName = parts[0];
+            const args = parts.slice(1);
+            const cmd = getCommand(cmdName);
+            if (!cmd) {
+                store.addMessage({ role: "error", content: `Unknown command: /${cmdName}. Type /help for available commands.` });
+                return;
+            }
+            store.addMessage({ role: "user", content: text });
+            try {
+                await cmd.handler({ store, api, args });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                store.addMessage({ role: "error", content: `Command error: ${msg}` });
+            }
+        }
+        else {
+            store.addMessage({ role: "user", content: text });
+            store.addMessage({
+                role: "system",
+                content: "Use /start <description> to start a workflow, or /help for all commands.",
+            });
+        }
+    }, []);
+    // Derive agent panel data with safe status mapping
+    const agentStatuses = agents.map((a) => ({
+        role: a.role_id,
+        status: toDisplayStatus(a.status),
+        duration: undefined,
+    }));
+    // Derive artifact data
+    const artifacts = (activeWorkflow?.artifacts ?? []).map((a) => ({
+        path: typeof a === "object" ? a.path ?? "" : String(a),
+        type: "file",
+    }));
+    // Derive workflow status for header
+    const workflowStatus = activeWorkflowId
+        ? (apiStatus === "connected" ? "RUNNING" : "WAITING")
+        : "IDLE";
+    // Derive metrics for status bar
+    const metrics = activeWorkflow?.metrics;
+    const tokenCount = Number(metrics?.total_tokens ?? 0);
+    const cost = Number(metrics?.total_cost ?? 0);
+    const elapsed = Number(metrics?.total_duration_minutes ?? 0) * 60;
+    const currentAgent = agents.find((a) => a.status === "active")?.role_id;
+    return (_jsxs(Box, { flexDirection: "column", width: "100%", height: "100%", children: [_jsx(Header, { workflowId: activeWorkflowId ?? undefined, workflowStatus: workflowStatus, themeName: themeName }), _jsxs(Box, { flexGrow: 1, flexDirection: "row", children: [_jsx(Box, { flexGrow: 1, flexDirection: "column", borderStyle: "single", children: _jsx(ChatPanel, { messages: messages }) }), showRightPanel && (_jsxs(Box, { width: 30, flexDirection: "column", children: [_jsx(Box, { borderStyle: "single", flexGrow: 1, children: _jsx(AgentPanel, { workflowId: activeWorkflowId ?? undefined, agents: agentStatuses }) }), _jsx(Box, { borderStyle: "single", height: 8, children: _jsx(ArtifactTree, { workflowId: activeWorkflowId ?? undefined, artifacts: artifacts }) }), _jsx(Box, { borderStyle: "single", height: 6, children: _jsx(MemoryPanel, {}) })] }))] }), _jsx(InputBar, { onSubmit: handleCommand }), _jsx(StatusBar, { workflowId: activeWorkflowId ?? undefined, currentAgent: currentAgent, tokenCount: tokenCount, cost: cost, elapsed: elapsed })] }));
+}

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for the Hydra TUI.
+ *
+ * Usage:
+ *   hydra                          Interactive TUI (default)
+ *   hydra --attach wf-abc123       Attach to a running workflow
+ *   hydra exec "Build auth system" Start workflow non-interactively
+ *   hydra status [workflow-id]     Check workflow status
+ *   hydra list                     List all workflows
+ *   hydra doctor                   Health check
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * CLI entry point for the Hydra TUI.
+ *
+ * Usage:
+ *   hydra                          Interactive TUI (default)
+ *   hydra --attach wf-abc123       Attach to a running workflow
+ *   hydra exec "Build auth system" Start workflow non-interactively
+ *   hydra status [workflow-id]     Check workflow status
+ *   hydra list                     List all workflows
+ *   hydra doctor                   Health check
+ */
+import { Command } from "commander";
+import { render } from "ink";
+import { App } from "./app.js";
+import { loadConfig } from "./config.js";
+import { getApiClient } from "./clients/api.js";
+function createApiFromConfig() {
+    const config = loadConfig();
+    return getApiClient(config.api.url);
+}
+const program = new Command();
+program
+    .name("hydra")
+    .description("Hydra TUI — multi-agent workflow orchestrator")
+    .version("0.1.0")
+    .option("--attach <workflow-id>", "Attach to a running workflow")
+    .option("--theme <name>", "Theme (dark, light, solarized, monokai, hydra)")
+    .action(async (opts) => {
+    const instance = render(_jsx(App, { attachWorkflow: opts.attach, themeName: opts.theme ?? "dark" }));
+    await instance.waitUntilExit();
+});
+program
+    .command("exec <description>")
+    .description("Start a workflow non-interactively and print results")
+    .action((_description) => {
+    console.log("Non-interactive mode not yet implemented.");
+    process.exit(0);
+});
+program
+    .command("status [workflow-id]")
+    .description("Show workflow status")
+    .option("--json", "Output as JSON")
+    .action(async (workflowId, opts) => {
+    const api = createApiFromConfig();
+    if (!workflowId) {
+        console.error("Usage: hydra status <workflow-id>");
+        process.exit(1);
+    }
+    try {
+        const resp = await api.getWorkflowStatus(workflowId);
+        if (opts.json) {
+            console.log(JSON.stringify(resp, null, 2));
+            process.exit(0);
+        }
+        const status = resp.status;
+        console.log(`Workflow: ${workflowId}`);
+        if (typeof status === "object" && status !== null) {
+            const s = status;
+            if (s.phase)
+                console.log(`Phase: ${s.phase}`);
+            if (s.current_phase)
+                console.log(`Current phase: ${s.current_phase}`);
+            if (s.waiting_for_approval)
+                console.log("** Waiting for approval **");
+            if (s.total_cost != null)
+                console.log(`Cost: $${Number(s.total_cost).toFixed(4)}`);
+            if (Array.isArray(s.steps)) {
+                console.log("\nSteps:");
+                for (const step of s.steps) {
+                    const st = step;
+                    const icon = st.status === "completed" ? "  ✓" : st.status === "running" ? "  ⏳" : "  ○";
+                    console.log(`${icon} ${st.role ?? st.name ?? "step"} [${st.status}]`);
+                }
+            }
+        }
+        else {
+            console.log(`Status: ${JSON.stringify(status, null, 2)}`);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${msg}`);
+        process.exit(1);
+    }
+    process.exit(0);
+});
+program
+    .command("list")
+    .description("List all workflows")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    const api = createApiFromConfig();
+    try {
+        const tasks = await api.listTasks({ limit: 50 });
+        if (opts.json) {
+            console.log(JSON.stringify(tasks, null, 2));
+            process.exit(0);
+        }
+        if (tasks.length === 0) {
+            console.log("No workflows found.");
+            process.exit(0);
+        }
+        console.log("ID                           | Status      | Type             | Step");
+        console.log("-".repeat(80));
+        for (const t of tasks) {
+            const id = t.workflow_id.slice(0, 28).padEnd(28);
+            const status = (t.status ?? "unknown").padEnd(11);
+            const type = (t.workflow_type ?? "").slice(0, 16).padEnd(16);
+            const step = t.current_step ?? "";
+            console.log(`${id} | ${status} | ${type} | ${step}`);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${msg}`);
+        process.exit(1);
+    }
+    process.exit(0);
+});
+program
+    .command("doctor")
+    .description("Run health checks on all Hydra services")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    const api = createApiFromConfig();
+    const checks = {};
+    let exitCode = 0;
+    try {
+        const health = await api.healthCheck();
+        checks.api = { status: health.status ?? "ok", version: health.version ?? null };
+        try {
+            const agentsResp = await api.getAgents();
+            checks.temporal = { status: "connected", roles: agentsResp.agents.length };
+        }
+        catch {
+            checks.temporal = { status: "unreachable" };
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        checks.api = { status: "unreachable", error: msg };
+        exitCode = 1;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(checks, null, 2));
+        process.exit(exitCode);
+    }
+    const apiCheck = checks.api;
+    if (apiCheck.status === "unreachable") {
+        console.error(`API: unreachable (${apiCheck.error})`);
+    }
+    else {
+        console.log(`API: ${apiCheck.status}`);
+        if (apiCheck.version)
+            console.log(`Version: ${apiCheck.version}`);
+    }
+    const temporalCheck = checks.temporal;
+    if (temporalCheck) {
+        if (temporalCheck.status === "connected") {
+            console.log(`Temporal: connected (${temporalCheck.roles} roles)`);
+        }
+        else {
+            console.log("Temporal: unreachable");
+        }
+    }
+    process.exit(exitCode);
+});
+program
+    .command("resume [session-name]")
+    .description("Resume a saved TUI session")
+    .action((_sessionName) => {
+    console.log("Resume command not yet implemented.");
+    process.exit(0);
+});
+program.parse();