loki-mode 5.7.2 → 5.7.3

package/VERSION

@@ -1 +1 @@
-5.7.2
+5.7.3

package/api/README.md

@@ -0,0 +1,297 @@
+# Loki Mode API
+
+HTTP/SSE API layer for Loki Mode autonomous agent orchestration.
+
+## Quick Start
+
+```bash
+# Start the API server
+loki serve
+
+# Or directly
+./autonomy/serve.sh
+
+# With options
+loki serve --port 9000 --host 0.0.0.0
+```
+
+## Requirements
+
+- **Deno** 1.40+ (for running the server)
+- **Loki Mode** installed and configured
+
+Install Deno:
+```bash
+curl -fsSL https://deno.land/install.sh | sh
+# or
+brew install deno
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOKI_API_PORT` | `8420` | Server port |
+| `LOKI_API_HOST` | `localhost` | Server host |
+| `LOKI_API_TOKEN` | none | API token for remote access |
+| `LOKI_DIR` | auto | Loki installation directory |
+| `LOKI_DEBUG` | false | Enable debug output |
+
+### Command Line Options
+
+```
+--port, -p <port>   Port to listen on
+--host <host>       Host to bind to
+--no-cors           Disable CORS
+--no-auth           Disable authentication
+--generate-token    Generate a secure API token
+```
+
+## Authentication
+
+By default, the API only accepts requests from localhost without authentication.
+
+For remote access:
+```bash
+# Generate a token
+export LOKI_API_TOKEN=$(loki serve --generate-token)
+
+# Start server allowing remote connections
+loki serve --host 0.0.0.0
+
+# Connect from another machine
+curl -H "Authorization: Bearer $LOKI_API_TOKEN" http://server:8420/health
+```
+
+## API Endpoints
+
+### Health
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Health check |
+| GET | `/health/ready` | Readiness probe |
+| GET | `/health/live` | Liveness probe |
+| GET | `/api/status` | Detailed status |
+
+### Sessions
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/sessions` | Start new session |
+| GET | `/api/sessions` | List all sessions |
+| GET | `/api/sessions/:id` | Get session details |
+| POST | `/api/sessions/:id/stop` | Stop session |
+| POST | `/api/sessions/:id/input` | Inject human input |
+| DELETE | `/api/sessions/:id` | Delete session record |
+
+### Tasks
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/sessions/:id/tasks` | List session tasks |
+| GET | `/api/tasks` | List all tasks |
+| GET | `/api/tasks/active` | Get running tasks |
+| GET | `/api/tasks/queue` | Get queued tasks |
+
+### Events (SSE)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/events` | SSE event stream |
+| GET | `/api/events/history` | Get event history |
+| GET | `/api/events/stats` | Event statistics |
+
+## SSE Event Types
+
+### Session Events
+- `session:started` - Session started
+- `session:paused` - Session paused
+- `session:resumed` - Session resumed
+- `session:stopped` - Session stopped
+- `session:completed` - Session completed successfully
+- `session:failed` - Session failed
+
+### Phase Events
+- `phase:started` - Phase started
+- `phase:completed` - Phase completed
+- `phase:failed` - Phase failed
+
+### Task Events
+- `task:created` - Task created
+- `task:started` - Task started
+- `task:progress` - Task progress update
+- `task:completed` - Task completed
+- `task:failed` - Task failed
+
+### Agent Events
+- `agent:spawned` - Agent spawned
+- `agent:output` - Agent output
+- `agent:completed` - Agent completed
+- `agent:failed` - Agent failed
+
+### Log Events
+- `log:debug` - Debug log
+- `log:info` - Info log
+- `log:warn` - Warning log
+- `log:error` - Error log
+
+### Other Events
+- `metrics:update` - Metrics update
+- `input:requested` - Human input requested
+- `heartbeat` - Keep-alive heartbeat
+
+## Usage Examples
+
+### Start a Session
+
+```bash
+curl -X POST http://localhost:8420/api/sessions \
+  -H "Content-Type: application/json" \
+  -d '{"provider": "claude", "prdPath": "./docs/prd.md"}'
+```
+
+### Subscribe to Events
+
+```javascript
+const events = new EventSource('http://localhost:8420/api/events');
+
+events.addEventListener('task:completed', (e) => {
+  const event = JSON.parse(e.data);
+  console.log(`Task completed: ${event.data.title}`);
+});
+
+events.addEventListener('log:error', (e) => {
+  const event = JSON.parse(e.data);
+  console.error(`Error: ${event.data.message}`);
+});
+
+events.onerror = (err) => {
+  console.error('Connection error:', err);
+};
+```
+
+### Using the TypeScript Client
+
+```typescript
+import { LokiClient } from './api/client.ts';
+
+const client = new LokiClient('http://localhost:8420');
+
+// Start a session
+const { sessionId } = await client.startSession({
+  provider: 'claude',
+  prdPath: './docs/prd.md'
+});
+
+// Subscribe to events
+const unsubscribe = client.subscribe((event) => {
+  console.log(`${event.type}: ${JSON.stringify(event.data)}`);
+});
+
+// Get session status
+const status = await client.getSession(sessionId);
+console.log(`Status: ${status.session.status}`);
+
+// Stop session
+await client.stopSession(sessionId);
+
+// Cleanup
+unsubscribe();
+client.close();
+```
+
+### Filter Events
+
+```bash
+# Filter by session
+curl "http://localhost:8420/api/events?sessionId=session_123"
+
+# Filter by event types
+curl "http://localhost:8420/api/events?types=task:completed,task:failed"
+
+# Filter log level
+curl "http://localhost:8420/api/events?minLevel=warn"
+
+# Replay recent history
+curl "http://localhost:8420/api/events?history=50"
+```
+
+## Development
+
+### Run Tests
+
+```bash
+deno test --allow-all api/server_test.ts
+```
+
+### Run with Hot Reload
+
+```bash
+deno run --watch --allow-all api/server.ts
+```
+
+### Type Check
+
+```bash
+deno check api/server.ts
+```
+
+## Architecture
+
+```
+api/
+  server.ts           # Main HTTP server
+  client.ts           # TypeScript client SDK
+  mod.ts              # Module exports
+  openapi.yaml        # OpenAPI specification
+  routes/
+    sessions.ts       # Session endpoints
+    tasks.ts          # Task endpoints
+    events.ts         # SSE streaming
+    health.ts         # Health checks
+  services/
+    cli-bridge.ts     # CLI integration
+    state-watcher.ts  # File system watcher
+    event-bus.ts      # Event distribution
+  middleware/
+    auth.ts           # Authentication
+    cors.ts           # CORS handling
+    error.ts          # Error handling
+  types/
+    api.ts            # API types
+    events.ts         # Event types
+```
+
+## State Synchronization
+
+The API watches the `.loki/` directory for state changes:
+
+- `sessions/{id}/session.json` - Session state
+- `sessions/{id}/tasks.json` - Task list
+- `sessions/{id}/phase.json` - Current phase
+- `sessions/{id}/agents.json` - Active agents
+- `state.json` - Global state
+
+Changes are detected via file watching and emitted as SSE events.
+
+## Error Codes
+
+| Code | HTTP Status | Description |
+|------|-------------|-------------|
+| `BAD_REQUEST` | 400 | Invalid request |
+| `UNAUTHORIZED` | 401 | Missing/invalid auth |
+| `FORBIDDEN` | 403 | Permission denied |
+| `NOT_FOUND` | 404 | Resource not found |
+| `CONFLICT` | 409 | State conflict |
+| `VALIDATION_ERROR` | 422 | Validation failed |
+| `INTERNAL_ERROR` | 500 | Server error |
+| `SESSION_NOT_FOUND` | 404 | Session not found |
+| `SESSION_ALREADY_RUNNING` | 409 | Session running |
+| `PROVIDER_NOT_AVAILABLE` | 503 | Provider unavailable |
+
+## License
+
+MIT

package/api/client.ts

@@ -0,0 +1,377 @@
+/**
+ * Loki Mode API Client
+ *
+ * TypeScript/JavaScript client for interacting with the Loki Mode API.
+ * Works in browsers, Node.js, and Deno.
+ *
+ * Usage:
+ *   const client = new LokiClient("http://localhost:8420");
+ *   const session = await client.startSession({ provider: "claude" });
+ *   client.subscribe((event) => console.log(event));
+ */
+
+import type {
+  Session,
+  Task,
+  StartSessionRequest,
+  StartSessionResponse,
+  SessionStatusResponse,
+  HealthResponse,
+} from "./types/api.ts";
+import type { AnySSEEvent, EventFilter, EventType } from "./types/events.ts";
+
+export interface ClientConfig {
+  baseUrl: string;
+  token?: string;
+  timeout?: number;
+}
+
+export class LokiClient {
+  private baseUrl: string;
+  private token?: string;
+  private timeout: number;
+  private eventSource: EventSource | null = null;
+  private eventCallbacks: ((event: AnySSEEvent) => void)[] = [];
+
+  constructor(config: string | ClientConfig) {
+    if (typeof config === "string") {
+      this.baseUrl = config.replace(/\/$/, "");
+      this.timeout = 30000;
+    } else {
+      this.baseUrl = config.baseUrl.replace(/\/$/, "");
+      this.token = config.token;
+      this.timeout = config.timeout || 30000;
+    }
+  }
+
+  /**
+   * Make an authenticated request
+   */
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<T> {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+
+    if (this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({
+          error: response.statusText,
+          code: "UNKNOWN",
+        }));
+        throw new LokiApiClientError(
+          error.error || response.statusText,
+          error.code || "UNKNOWN",
+          response.status
+        );
+      }
+
+      return response.json();
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err instanceof LokiApiClientError) {
+        throw err;
+      }
+      throw new LokiApiClientError(
+        err instanceof Error ? err.message : "Request failed",
+        "NETWORK_ERROR"
+      );
+    }
+  }
+
+  // ============================================================
+  // Health Endpoints
+  // ============================================================
+
+  /**
+   * Check API health
+   */
+  async health(): Promise<HealthResponse> {
+    return this.request<HealthResponse>("GET", "/health");
+  }
+
+  /**
+   * Get detailed status
+   */
+  async status(): Promise<Record<string, unknown>> {
+    return this.request<Record<string, unknown>>("GET", "/api/status");
+  }
+
+  // ============================================================
+  // Session Endpoints
+  // ============================================================
+
+  /**
+   * Start a new session
+   */
+  async startSession(
+    options: StartSessionRequest = {}
+  ): Promise<StartSessionResponse> {
+    return this.request<StartSessionResponse>("POST", "/api/sessions", options);
+  }
+
+  /**
+   * List all sessions
+   */
+  async listSessions(): Promise<{ sessions: Session[]; total: number }> {
+    return this.request<{ sessions: Session[]; total: number }>(
+      "GET",
+      "/api/sessions"
+    );
+  }
+
+  /**
+   * Get session details
+   */
+  async getSession(sessionId: string): Promise<SessionStatusResponse> {
+    return this.request<SessionStatusResponse>(
+      "GET",
+      `/api/sessions/${sessionId}`
+    );
+  }
+
+  /**
+   * Stop a session
+   */
+  async stopSession(
+    sessionId: string
+  ): Promise<{ sessionId: string; status: string; message: string }> {
+    return this.request<{ sessionId: string; status: string; message: string }>(
+      "POST",
+      `/api/sessions/${sessionId}/stop`
+    );
+  }
+
+  /**
+   * Inject human input into a session
+   */
+  async injectInput(
+    sessionId: string,
+    input: string,
+    context?: string
+  ): Promise<{ sessionId: string; message: string }> {
+    return this.request<{ sessionId: string; message: string }>(
+      "POST",
+      `/api/sessions/${sessionId}/input`,
+      { input, context }
+    );
+  }
+
+  // ============================================================
+  // Task Endpoints
+  // ============================================================
+
+  /**
+   * List tasks for a session
+   */
+  async getTasks(
+    sessionId: string,
+    options: { status?: string; limit?: number; offset?: number } = {}
+  ): Promise<{ tasks: Task[]; pagination: unknown }> {
+    const params = new URLSearchParams();
+    if (options.status) params.set("status", options.status);
+    if (options.limit) params.set("limit", String(options.limit));
+    if (options.offset) params.set("offset", String(options.offset));
+
+    const query = params.toString();
+    return this.request<{ tasks: Task[]; pagination: unknown }>(
+      "GET",
+      `/api/sessions/${sessionId}/tasks${query ? `?${query}` : ""}`
+    );
+  }
+
+  /**
+   * Get active tasks across all sessions
+   */
+  async getActiveTasks(): Promise<{ tasks: Task[]; count: number }> {
+    return this.request<{ tasks: Task[]; count: number }>(
+      "GET",
+      "/api/tasks/active"
+    );
+  }
+
+  /**
+   * Get queued tasks
+   */
+  async getQueuedTasks(): Promise<{ tasks: Task[]; count: number }> {
+    return this.request<{ tasks: Task[]; count: number }>(
+      "GET",
+      "/api/tasks/queue"
+    );
+  }
+
+  // ============================================================
+  // SSE Event Streaming
+  // ============================================================
+
+  /**
+   * Subscribe to real-time events
+   */
+  subscribe(
+    callback: (event: AnySSEEvent) => void,
+    filter: EventFilter = {}
+  ): () => void {
+    this.eventCallbacks.push(callback);
+
+    // Connect if not already connected
+    if (!this.eventSource) {
+      this.connectEventSource(filter);
+    }
+
+    // Return unsubscribe function
+    return () => {
+      const index = this.eventCallbacks.indexOf(callback);
+      if (index > -1) {
+        this.eventCallbacks.splice(index, 1);
+      }
+
+      // Disconnect if no more subscribers
+      if (this.eventCallbacks.length === 0) {
+        this.disconnectEventSource();
+      }
+    };
+  }
+
+  /**
+   * Connect to SSE endpoint
+   */
+  private connectEventSource(filter: EventFilter): void {
+    const params = new URLSearchParams();
+    if (filter.sessionId) params.set("sessionId", filter.sessionId);
+    if (filter.types) params.set("types", filter.types.join(","));
+    if (filter.minLevel) params.set("minLevel", filter.minLevel);
+
+    const query = params.toString();
+    const url = `${this.baseUrl}/api/events${query ? `?${query}` : ""}`;
+
+    this.eventSource = new EventSource(url);
+
+    // Handle all event types
+    const eventTypes: EventType[] = [
+      "session:started",
+      "session:paused",
+      "session:resumed",
+      "session:stopped",
+      "session:completed",
+      "session:failed",
+      "phase:started",
+      "phase:completed",
+      "phase:failed",
+      "task:created",
+      "task:started",
+      "task:progress",
+      "task:completed",
+      "task:failed",
+      "agent:spawned",
+      "agent:output",
+      "agent:completed",
+      "agent:failed",
+      "log:info",
+      "log:warn",
+      "log:error",
+      "log:debug",
+      "metrics:update",
+      "input:requested",
+      "heartbeat",
+    ];
+
+    for (const eventType of eventTypes) {
+      this.eventSource.addEventListener(eventType, (e: MessageEvent) => {
+        try {
+          const event = JSON.parse(e.data) as AnySSEEvent;
+          for (const callback of this.eventCallbacks) {
+            callback(event);
+          }
+        } catch {
+          console.warn("Failed to parse SSE event:", e.data);
+        }
+      });
+    }
+
+    this.eventSource.onerror = (err) => {
+      console.error("SSE connection error:", err);
+      // Reconnect after delay
+      setTimeout(() => {
+        if (this.eventCallbacks.length > 0) {
+          this.disconnectEventSource();
+          this.connectEventSource(filter);
+        }
+      }, 5000);
+    };
+  }
+
+  /**
+   * Disconnect from SSE endpoint
+   */
+  private disconnectEventSource(): void {
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+  }
+
+  /**
+   * Get event history
+   */
+  async getEventHistory(
+    filter: EventFilter = {},
+    limit = 100
+  ): Promise<{ events: AnySSEEvent[]; count: number }> {
+    const params = new URLSearchParams();
+    if (filter.sessionId) params.set("sessionId", filter.sessionId);
+    if (filter.types) params.set("types", filter.types.join(","));
+    params.set("limit", String(limit));
+
+    return this.request<{ events: AnySSEEvent[]; count: number }>(
+      "GET",
+      `/api/events/history?${params.toString()}`
+    );
+  }
+
+  /**
+   * Close all connections
+   */
+  close(): void {
+    this.disconnectEventSource();
+    this.eventCallbacks = [];
+  }
+}
+
+/**
+ * API Client Error
+ */
+export class LokiApiClientError extends Error {
+  code: string;
+  status?: number;
+
+  constructor(message: string, code: string, status?: number) {
+    super(message);
+    this.name = "LokiApiClientError";
+    this.code = code;
+    this.status = status;
+  }
+}
+
+// Export default instance factory
+export function createClient(config: string | ClientConfig): LokiClient {
+  return new LokiClient(config);
+}