loki-mode 9.8.1 → 9.12.0

package/docs/openclaw-integration.md

@@ -1,572 +1,52 @@
 # OpenClaw Integration
 
-Multi-agent coordination protocol integration for Loki Mode (v5.38.0).
+**Status: skeleton. Not a shipped feature.**
 
-## Overview
+An earlier version of this page documented an OpenClaw coordination protocol
+with `loki openclaw` subcommands, `/api/openclaw/*` REST endpoints,
+`LOKI_OPENCLAW_*` environment variables, a `.loki/config.yaml` `openclaw:`
+block, and `loki_openclaw_*` Prometheus metrics. **None of that exists in the
+source.** It has been removed rather than left in place:
 
-OpenClaw is a standardized protocol for multi-agent coordination across different AI systems. Loki Mode's OpenClaw bridge enables:
+- `grep -c openclaw autonomy/loki` returns `0` -- there is no `loki openclaw`
+  command in the CLI dispatch, and no `--openclaw` flag anywhere in
+  `autonomy/` or `loki-ts/src/`.
+- `grep -rn "api/openclaw" dashboard/server.py loki-ts/src/` returns nothing --
+  none of the documented REST endpoints are implemented.
+- No `LOKI_OPENCLAW_*` variable is read by any runtime code.
 
-- **Cross-system orchestration** - Coordinate Loki Mode agents with other agent frameworks
-- **Standardized communication** - Common message format for agent-to-agent communication
-- **Shared task queues** - Distribute work across multiple orchestrators
-- **State synchronization** - Keep agent state consistent across systems
+## What actually exists
 
-Compatible with:
-- AutoGPT
-- MetaGPT
-- CrewAI
-- LangGraph agents
-- Custom agent frameworks implementing the OpenClaw protocol
+Two real things, neither of which is a Loki CLI feature:
 
-## Quick Start
+**1. A file-watching bridge skeleton** at `integrations/openclaw/bridge/`. It
+watches a `.loki` directory, maps Loki events to an OpenClaw gateway message
+shape (`schema_map.py`), and prints the mapped JSON to stdout. Its own module
+docstring states the limitation plainly:
 
-```bash
-# Enable OpenClaw bridge
-export LOKI_OPENCLAW_ENABLED=true
-export LOKI_OPENCLAW_ENDPOINT=http://openclaw-server:8080
-
-# Start with OpenClaw integration
-loki start --openclaw ./prd.md
-```
-
-## Configuration
-
-### Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `LOKI_OPENCLAW_ENABLED` | `false` | Enable OpenClaw bridge |
-| `LOKI_OPENCLAW_ENDPOINT` | - | OpenClaw server endpoint URL (required) |
-| `LOKI_OPENCLAW_AGENT_ID` | `loki-{pid}` | Unique agent ID for this Loki instance |
-| `LOKI_OPENCLAW_NAMESPACE` | `default` | Namespace for multi-tenant deployments |
-| `LOKI_OPENCLAW_HEARTBEAT` | `30` | Heartbeat interval in seconds |
-| `LOKI_OPENCLAW_TIMEOUT` | `120` | Message timeout in seconds |
-
-### Configuration File
-
-```yaml
-# .loki/config.yaml
-openclaw:
-  enabled: true
-  endpoint: http://openclaw-server:8080
-  agent_id: loki-primary
-  namespace: production
-  heartbeat_interval: 30
-  message_timeout: 120
-  features:
-    task_sharing: true
-    state_sync: true
-    capabilities_discovery: true
-```
-
-## OpenClaw Protocol
-
-### Message Format
-
-OpenClaw uses JSON messages over HTTP/WebSocket:
-
-```json
-{
-  "protocol_version": "1.0",
-  "message_type": "task_offer",
-  "agent_id": "loki-12345",
-  "namespace": "default",
-  "timestamp": "2026-02-15T14:30:00Z",
-  "payload": {
-    "task_id": "task-abc123",
-    "task_type": "code_review",
-    "priority": "high",
-    "deadline": "2026-02-15T16:00:00Z",
-    "requirements": {
-      "model": "opus",
-      "skills": ["code_review", "security_audit"]
-    }
-  }
-}
-```
-
-### Message Types
-
-| Type | Direction | Description |
-|------|-----------|-------------|
-| `register` | Loki → OpenClaw | Agent registration with capabilities |
-| `heartbeat` | Loki → OpenClaw | Keep-alive signal |
-| `task_offer` | OpenClaw → Loki | Task offered for execution |
-| `task_accept` | Loki → OpenClaw | Accept task offer |
-| `task_reject` | Loki → OpenClaw | Reject task offer |
-| `task_update` | Loki → OpenClaw | Progress update |
-| `task_complete` | Loki → OpenClaw | Task completion |
-| `state_sync` | Bidirectional | State synchronization |
-| `capability_query` | OpenClaw → Loki | Query agent capabilities |
-
-## Agent Registration
-
-When OpenClaw bridge starts, Loki Mode registers with the OpenClaw server:
-
-```json
-{
-  "message_type": "register",
-  "agent_id": "loki-12345",
-  "payload": {
-    "name": "Loki Mode",
-    "version": "5.42.2",
-    "provider": "claude",
-    "capabilities": [
-      "full_stack_development",
-      "code_review",
-      "testing",
-      "deployment",
-      "business_operations"
-    ],
-    "agent_types": [
-      "eng-frontend", "eng-backend", "eng-qa",
-      "ops-devops", "ops-sre", "biz-marketing"
-    ],
-    "max_concurrent_tasks": 10,
-    "supported_models": ["opus", "sonnet", "haiku"]
-  }
-}
-```
-
-## Task Coordination
-
-### Receiving Tasks
-
-Loki Mode receives tasks from OpenClaw:
-
-```json
-{
-  "message_type": "task_offer",
-  "payload": {
-    "task_id": "external-task-123",
-    "task_type": "code_review",
-    "description": "Review authentication module",
-    "files": ["src/auth.py", "tests/test_auth.py"],
-    "priority": "high",
-    "deadline": "2026-02-15T16:00:00Z"
-  }
-}
-```
-
-Loki Mode evaluates and responds:
-
-```json
-{
-  "message_type": "task_accept",
-  "payload": {
-    "task_id": "external-task-123",
-    "assigned_agent": "review-code",
-    "estimated_duration": 600
-  }
-}
-```
-
-### Offering Tasks
-
-Loki Mode can offer tasks to other agents via OpenClaw:
-
-```json
-{
-  "message_type": "task_offer",
-  "payload": {
-    "task_id": "loki-task-456",
-    "task_type": "data_analysis",
-    "description": "Analyze user behavior logs",
-    "requirements": {
-      "skills": ["data_science", "ml"],
-      "estimated_cost": 0.50
-    }
-  }
-}
-```
-
-## State Synchronization
-
-### Shared State
-
-Loki Mode synchronizes key state with OpenClaw:
-
-- Active agents and their status
-- Task queue (pending, in-progress, completed)
-- Session metadata (iteration, cost, uptime)
-- Resource utilization (memory, CPU, tokens)
-
-```json
-{
-  "message_type": "state_sync",
-  "payload": {
-    "session_status": "running",
-    "iteration": 42,
-    "agents_active": 12,
-    "tasks_pending": 5,
-    "tasks_in_progress": 8,
-    "tasks_completed": 127,
-    "cost_usd": 2.34
-  }
-}
-```
-
-### Conflict Resolution
-
-When state conflicts occur:
-
-1. **Last-write-wins** - Default strategy
-2. **Merge** - For additive operations (task queue append)
-3. **Reject** - For conflicting updates (agent status)
-
-## Capability Discovery
-
-Other agents can query Loki Mode's capabilities:
-
-```json
-{
-  "message_type": "capability_query",
-  "payload": {
-    "query_type": "supports_task_type",
-    "task_type": "frontend_development"
-  }
-}
-```
-
-Response:
-
-```json
-{
-  "message_type": "capability_response",
-  "payload": {
-    "supported": true,
-    "agent_types": ["eng-frontend"],
-    "confidence": 0.95,
-    "estimated_cost": 0.10
-  }
-}
-```
-
-## API Endpoints
-
-Loki Mode exposes OpenClaw endpoints on the dashboard server:
-
-```bash
-# Get OpenClaw status
-GET http://localhost:57374/api/openclaw/status
-
-# Send message to OpenClaw server
-POST http://localhost:57374/api/openclaw/send
-{
-  "message_type": "task_offer",
-  "payload": {...}
-}
-
-# Query capabilities
-GET http://localhost:57374/api/openclaw/capabilities
-
-# Get received messages
-GET http://localhost:57374/api/openclaw/messages?limit=50
-```
-
-## CLI Commands
-
-```bash
-# Check OpenClaw connection status
-loki openclaw status
-
-# Send test message
-loki openclaw test
-
-# List received messages
-loki openclaw messages
-
-# Query registered agents
-loki openclaw agents
-
-# Disconnect from OpenClaw
-loki openclaw disconnect
-```
-
-## Examples
-
-### Multi-System Workflow
-
-```
-MetaGPT (Planning)
-    ↓
-    Sends task via OpenClaw
-    ↓
-Loki Mode (Implementation)
-    ↓
-    Sends result via OpenClaw
-    ↓
-AutoGPT (Testing)
-    ↓
-    Sends report via OpenClaw
-    ↓
-CrewAI (Deployment)
-```
-
-### Task Distribution
-
-```yaml
-# Distribute tasks across multiple Loki instances
-openclaw:
-  enabled: true
-  endpoint: http://openclaw-lb:8080
-  features:
-    task_sharing: true
-
-# Loki instance 1 (frontend)
-agents:
-  - eng-frontend
-  - eng-mobile
-
-# Loki instance 2 (backend)
-agents:
-  - eng-backend
-  - eng-database
-
-# Loki instance 3 (ops)
-agents:
-  - ops-devops
-  - ops-sre
-```
-
-### Cross-Framework Integration
-
-```python
-# AutoGPT sending task to Loki via OpenClaw
-import requests
-
-openclaw_url = "http://openclaw-server:8080/tasks"
-task = {
-    "task_type": "code_review",
-    "description": "Review API implementation",
-    "files": ["api/routes.py"],
-    "target_agent": "loki-12345"
-}
-
-response = requests.post(openclaw_url, json=task)
-print(f"Task sent: {response.json()}")
-
-# Wait for completion
-task_id = response.json()["task_id"]
-while True:
-    status = requests.get(f"{openclaw_url}/{task_id}").json()
-    if status["status"] == "completed":
-        print(f"Result: {status['result']}")
-        break
-    time.sleep(10)
-```
-
-## OpenClaw Server Setup
-
-### Docker Deployment
-
-```yaml
-# docker-compose.yml
-version: '3.8'
-services:
-  openclaw-server:
-    image: openclaw/server:latest
-    ports:
-      - "8080:8080"
-    environment:
-      - OPENCLAW_LOG_LEVEL=info
-      - OPENCLAW_AUTH_ENABLED=false
-    volumes:
-      - openclaw-data:/data
+> NOTE: This is a foundation/skeleton. The WebSocket gateway client is not yet
+> implemented. Currently logs mapped events to stdout as JSON for testing.
+> The --gateway flag is accepted but has no effect until the WebSocket client
+> is built in a future phase.
 
-  loki-mode-1:
-    image: asklokesh/loki-mode:latest
-    environment:
-      - LOKI_OPENCLAW_ENABLED=true
-      - LOKI_OPENCLAW_ENDPOINT=http://openclaw-server:8080
-      - LOKI_OPENCLAW_AGENT_ID=loki-frontend
-    depends_on:
-      - openclaw-server
-
-  loki-mode-2:
-    image: asklokesh/loki-mode:latest
-    environment:
-      - LOKI_OPENCLAW_ENABLED=true
-      - LOKI_OPENCLAW_ENDPOINT=http://openclaw-server:8080
-      - LOKI_OPENCLAW_AGENT_ID=loki-backend
-    depends_on:
-      - openclaw-server
-
-volumes:
-  openclaw-data:
-```
-
-### Kubernetes Deployment
-
-```yaml
-apiVersion: v1
-kind: Service
-metadata:
-  name: openclaw-server
-spec:
-  selector:
-    app: openclaw
-  ports:
-    - port: 8080
----
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: openclaw-server
-spec:
-  replicas: 3
-  selector:
-    matchLabels:
-      app: openclaw
-  template:
-    metadata:
-      labels:
-        app: openclaw
-    spec:
-      containers:
-      - name: openclaw
-        image: openclaw/server:latest
-        ports:
-        - containerPort: 8080
-        env:
-        - name: OPENCLAW_REDIS_URL
-          value: redis://redis:6379
-```
-
-## Security
-
-### Authentication
+Run it directly, not through `loki`:
 
 ```bash
-# Enable OpenClaw authentication
-export LOKI_OPENCLAW_AUTH_TOKEN=your-secret-token
-
-# Or use mutual TLS
-export LOKI_OPENCLAW_TLS_CERT=/path/to/client-cert.pem
-export LOKI_OPENCLAW_TLS_KEY=/path/to/client-key.pem
-export LOKI_OPENCLAW_TLS_CA=/path/to/ca-cert.pem
-```
-
-### Authorization
-
-```yaml
-openclaw:
-  authorization:
-    enabled: true
-    allowed_agents:
-      - autogpt-production
-      - metagpt-staging
-    allowed_namespaces:
-      - production
-      - staging
-```
-
-### Encryption
-
-```bash
-# Use HTTPS for OpenClaw endpoint
-export LOKI_OPENCLAW_ENDPOINT=https://openclaw-server:8443
-
-# Enable message encryption
-export LOKI_OPENCLAW_ENCRYPT_MESSAGES=true
-export LOKI_OPENCLAW_ENCRYPTION_KEY=your-encryption-key
+python -m integrations.openclaw.bridge --loki-dir .loki
 ```
 
-## Monitoring
-
-### Metrics
-
-OpenClaw bridge exposes metrics:
-
-```
-loki_openclaw_connected{agent_id="loki-12345"} 1
-loki_openclaw_messages_sent_total{type="task_offer"} 42
-loki_openclaw_messages_received_total{type="task_accept"} 38
-loki_openclaw_tasks_completed_total 35
-loki_openclaw_latency_seconds{operation="send"} 0.015
-```
-
-### Health Checks
-
-```bash
-# Check OpenClaw connection
-curl http://localhost:57374/api/openclaw/health
-
-# Response
-{
-  "connected": true,
-  "server": "http://openclaw-server:8080",
-  "last_heartbeat": "2026-02-15T14:30:00Z",
-  "latency_ms": 15,
-  "messages_pending": 0
-}
-```
-
-## Troubleshooting
-
-### Connection Issues
-
-```bash
-# Test OpenClaw server connectivity
-curl http://openclaw-server:8080/health
-
-# Check Loki OpenClaw status
-loki openclaw status
-
-# View connection logs
-loki enterprise audit tail --event openclaw.connect
-
-# Reconnect manually
-loki openclaw reconnect
-```
-
-### Message Delivery Failures
-
-```bash
-# Check message queue
-loki openclaw messages --status failed
-
-# Retry failed messages
-loki openclaw retry
-
-# View OpenClaw logs
-docker logs openclaw-server
-```
-
-### Performance Issues
-
-```bash
-# Check message latency
-curl http://localhost:57374/metrics | grep loki_openclaw_latency
-
-# Monitor message queue size
-loki openclaw status | grep messages_pending
-
-# Increase heartbeat interval to reduce traffic
-export LOKI_OPENCLAW_HEARTBEAT=60
-```
-
-## Best Practices
-
-1. **Use namespaces** to isolate environments (dev, staging, production)
-2. **Enable authentication** in production deployments
-3. **Monitor message latency** and set appropriate timeouts
-4. **Implement retry logic** for transient failures
-5. **Use task priorities** for critical workloads
-6. **Set up health checks** for automatic reconnection
-7. **Log all OpenClaw messages** for audit trail
-
-## Limitations
+**2. An OpenClaw skill package** at `integrations/openclaw/`, which you copy
+into an OpenClaw workspace so an OpenClaw agent can invoke the ordinary
+`loki start` / `loki status --json` CLI on your behalf. See
+[`integrations/openclaw/README.md`](../integrations/openclaw/README.md) for the
+install steps and the two helper scripts (`poll-status.sh`,
+`format-progress.sh`).
 
-- OpenClaw protocol is still evolving (v1.0 spec)
-- Not all agent frameworks support OpenClaw yet
-- Message size limited to 1MB
-- Synchronous task completion only (async planned for v2.0)
-- No built-in conflict resolution for complex state updates
+## If you need real multi-agent coordination today
 
-## See Also
+Use the surfaces that are actually implemented and tested:
 
-- [Agent Types](../references/agent-types.md) - 41 Loki Mode agent types
-- [GitHub Integration](../skills/github-integration.md) - Issue and PR automation
-- [Enterprise Features](../wiki/Enterprise-Features.md) - Multi-project orchestration
-- [API Reference](../wiki/API-Reference.md) - Complete API documentation
+- The MCP server (`loki mcp`) exposes Loki's tools to any MCP client.
+- `.loki/events.jsonl` is the durable event stream the bridge skeleton reads;
+  anything that can tail a JSONL file can consume it.
+- `loki status --json` is the supported programmatic status surface.

package/docs/show-hn-post.md

@@ -10,9 +10,9 @@ I built Loki Mode because I got tired of the copy-paste loop between AI coding a
 
 **What it does:** You give it a Product Requirements Document. It breaks the work into tasks across 41 specialized agent roles organized into 8 domains (engineering, operations, business, data, product, growth, review, orchestration) -- prompt-defined specifications the orchestrator adopts per phase, with parallel review (blind council) and optional worktree streams on Claude Code, sequential on other providers -- and runs every iteration through a self-verification loop called RARV: Reason, Act, Reflect, Verify. The idea is that the system catches its own mistakes before you have to.
 
-**Quality gates:** 9 automated gates including 3-reviewer blind review (agents review each other's work without seeing prior reviews), anti-sycophancy checks (a devil's advocate pass on unanimous approvals), and mock/mutation detection. These are not foolproof, but they catch a surprising number of issues that single-pass generation misses.
+**Quality gates:** 8 automated gates including 3-reviewer blind review (agents review each other's work without seeing prior reviews), anti-sycophancy checks (a devil's advocate pass on unanimous approvals), and mock/mutation detection. These are not foolproof, but they catch a surprising number of issues that single-pass generation misses.
 
-**Multi-provider:** Runs on Claude Code (full parallel agent support), OpenAI Codex CLI, or Google Gemini CLI. Codex and Gemini run in degraded sequential mode -- no parallel agents, no Task tool. Claude Code is the primary target.
+**Multi-provider:** Runs on Claude Code (full parallel agent support), Cline, OpenAI Codex CLI, Aider, or opencode. Everything other than Claude Code runs in degraded sequential mode -- no parallel agents, no Task tool. Claude Code is the primary target. (The Google Gemini CLI provider was removed in v7.5.18 after Google deprecated it upstream.)
 
 **Memory:** 3-tier system (episodic, semantic, procedural) so the system can learn from previous runs. Optional vector search with sentence-transformers if you want similarity-based retrieval.