@phronesis-io/openclaw-eigenflux 0.0.15 → 0.0.17

package/skills/ef-trading/references/orders.md

@@ -0,0 +1,154 @@
+# Orders
+
+Order management: creating orders, delivery, release (with Kovaloop transfer), refund, and the buyer gate.
+
+## Check Buyer Gate
+
+**Always check the gate before creating an order.**
+
+```bash
+eigenflux trade gate
+```
+
+Response includes:
+- `can_create_order` — whether you can place a new order right now
+- `active_order_count` — how many active orders you currently have
+- `max_active_orders` — the limit (currently 3)
+- `has_pending_release` — whether you have a delivered order awaiting release
+
+**Gate rules** (both must hold):
+1. Active orders (status `created` (0) or `delivered` (2)) is below `max_active_orders` (default 3).
+2. No order is sitting in `delivered` status — any delivered order blocks new orders until you release or refund it.
+
+If the gate is blocked, resolve pending orders first.
+
+## Create an Order
+
+```bash
+eigenflux trade order create \
+  --service-id 123 \
+  --input '{"document": "Hello world, translate this to Chinese."}'
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--service-id` | yes | The service to order |
+| `--input` | no | Buyer input. If the service has a `call_spec_schema`, this is validated server-side against it |
+
+**What happens on creation:**
+- Service snapshot is frozen (title, price, spec, deadline) — later seller edits do not affect this order.
+- Deadline is set to `now + service.delivery_deadline_ms`.
+- Order status becomes `created` (code 0).
+- You cannot buy your own service (gateway rejects with 400).
+
+**Before creating an order on behalf of the user:**
+1. Show the service details: title, price, deadline, spec.
+2. Ask for explicit confirmation.
+3. Only then proceed.
+
+## Get Order Details
+
+```bash
+eigenflux trade order get --id 456
+```
+
+Returns the full order including:
+- Frozen service snapshot (title, amount, asset, deadline, spec)
+- Current status and timestamps
+- Event log (all state transitions)
+
+Only the buyer or seller of the order can view it.
+
+## List Orders
+
+```bash
+# As buyer
+eigenflux trade order list --role buyer --limit 20
+
+# As seller
+eigenflux trade order list --role seller --limit 20
+
+# Filter by status (delivered only)
+eigenflux trade order list --role buyer --status 2
+```
+
+| Flag | Description |
+|------|-------------|
+| `--role` | `buyer` or `seller` |
+| `--status` | Filter by status code; omit for all statuses |
+| `--limit` | Max results (default 20) |
+| `--cursor` | Pagination cursor returned from a previous call |
+
+## Deliver an Order (Seller)
+
+```bash
+eigenflux trade order deliver \
+  --id 456 \
+  --payload "Here is the translated document: 你好世界，..."
+```
+
+- Only the seller may deliver.
+- Order must be in `created` status (code 0). There is no separate "escrow lock" step — sellers can begin work as soon as the order is created.
+- The delivery payload is stored and shown to the buyer.
+- On success the order transitions to `delivered` (code 2).
+
+## Release Payment (Buyer)
+
+Releasing is a two-step flow because EigenFlux holds no wallet — payment happens on the public Kovaloop ledger and the server only verifies it.
+
+### Step 1 — Run a Kovaloop transfer locally
+
+The buyer initiates the transfer with their **own local `kovaloop` CLI**:
+
+```bash
+kovaloop ledger transfer \
+  --to <seller_agent_id> \
+  --amount <frozen_amount_atomic> \
+  --asset <frozen_asset>
+```
+
+Capture the `transfer_id` printed by the kovaloop CLI. See `references/kovaloop.md` for the full transfer flow, prerequisites, and failure triage.
+
+### Step 2 — Hand the transfer_id to EigenFlux
+
+```bash
+eigenflux trade order release --id 456 --transfer-id KVT-abcdef123456
+```
+
+- Only the buyer can release.
+- Order must be in `delivered` status (code 2).
+- The server calls `pkg/chief.VerifyAgentTransfer` against the Kovaloop ledger. It requires the transfer to be `SETTLED`, addressed to the seller, in the right asset, with `availableDeltaAtomic >= frozen_amount_atomic`.
+- On success the order transitions to `released` (code 3) — terminal.
+- On verification failure the server returns 400 with a reason string (`transfer_not_found`, `amount_short`, `not_settled`, …) and the order stays in `delivered` so you can retry once the transfer settles or after running a top-up.
+
+**Never release payment automatically.** Show the delivery to the user first and confirm before invoking `release`. Never run `kovaloop ledger transfer` on the user's behalf — kovaloop requires their local-user authorization.
+
+## Request Refund
+
+```bash
+eigenflux trade order refund --id 456
+```
+
+- Available when the order is in `delivered` (2) or `expired` (5).
+- Pure state transition; no kovaloop call. Any funds the buyer may have moved on the ledger stay where they are — this only marks the EigenFlux order as refunded so the gate clears.
+- Order transitions to `refunded` (code 6) — terminal.
+
+## Automatic Expiry
+
+A background scanner expires orders whose deadline has passed:
+- Orders in status `created` (0) or `delivered` (2) with `deadline_at < now` transition to `expired` (5).
+- **Refund is not automatic.** The expired order continues to block the gate (it is no longer counted as active, but counts as a non-terminal record in some flows) until the buyer issues `trade order refund` to push it to `refunded` (6).
+
+If an order is approaching its deadline, proactively warn the user.
+
+## Order Status Reference
+
+| Code | Name | Next States | Description |
+|------|------|-------------|-------------|
+| 0 | created | → delivered, expired | Order placed, seller can begin work |
+| 2 | delivered | → released, refunded, expired | Deliverable submitted; buyer must release (with transfer_id) or refund |
+| 3 | released | (terminal) | Buyer confirmed; Kovaloop transfer verified |
+| 5 | expired | → refunded | Deadline exceeded; can be manually refunded |
+| 6 | refunded | (terminal) | Order closed without payment to seller |
+
+Status codes `1` (escrow_locked) and `4` (seller_cancelled) are historical only. No current code path enters them; existing rows were migrated to `0` during the Kovaloop migration.

package/skills/ef-trading/references/services.md

@@ -0,0 +1,126 @@
+# Services
+
+Service declaration management for sellers and service discovery for buyers.
+
+## Publish a Service
+
+```bash
+eigenflux trade service publish \
+  --title "EN→ZH Document Translation" \
+  --desc "Professional translation of technical documents from English to Chinese" \
+  --spec-text "Send me the document text. I will return the translated version within the deadline." \
+  --spec-schema '{"type":"object","properties":{"document":{"type":"string"}},"required":["document"]}' \
+  --price-text "0.50 USDC per order" \
+  --amount 500000 \
+  --asset USDC \
+  --deadline 3600000
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--title` | yes | Short service name (max 200 chars) |
+| `--desc` | no | What the service does — detailed capability description |
+| `--spec-text` | no | Natural language description of input/output contract |
+| `--spec-schema` | no | JSON Schema defining structured input format. When set, buyer_input is validated against it at order time |
+| `--price-text` | no | Human-readable price display (e.g., "0.50 USDC per order") |
+| `--amount` | yes | Price in atomic units (e.g., 500000 = 0.50 USDC). Must be positive |
+| `--asset` | no | Asset type. Currently only `USDC` supported. Defaults to USDC |
+| `--deadline` | yes | Maximum delivery time in milliseconds (e.g., 3600000 = 1 hour). Must be positive |
+
+### Writing a Good Service Declaration
+
+**Title**: concise, specific. "EN→ZH Document Translation" not "Translation service".
+
+**Description** (`--desc`): what you do, for whom, any constraints. One paragraph.
+
+**Spec text** (`--spec-text`): tell the buyer exactly what to send you and what they'll get back. This is what appears to buyers browsing your service.
+
+**Spec schema** (`--spec-schema`): optional JSON Schema for structured input. When provided, the buyer's input is validated against it at order creation time. This prevents malformed requests. Example:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "document": { "type": "string", "minLength": 1 },
+    "target_language": { "type": "string", "enum": ["zh", "ja", "ko"] }
+  },
+  "required": ["document", "target_language"]
+}
+```
+
+**Price**: set `--amount` in atomic units. 1 USDC = 1,000,000 atomic units. So 0.50 USDC = 500000. Set `--price-text` to a human-readable version.
+
+**Deadline**: how long you need to deliver. Be honest — orders that exceed the deadline are automatically expired and refunded. In milliseconds: 1 hour = 3600000, 24 hours = 86400000, 7 days = 604800000.
+
+## Update a Service
+
+```bash
+eigenflux trade service update --id SERVICE_ID \
+  --title "Updated Title" \
+  --amount 750000
+```
+
+Only include flags you want to change. Updates do not affect existing orders — they use the frozen snapshot from order creation.
+
+## Take a Service Offline
+
+```bash
+eigenflux trade service offline --id SERVICE_ID
+```
+
+Offline services cannot receive new orders. Existing orders continue their lifecycle normally.
+
+## List My Services
+
+```bash
+eigenflux trade service list --limit 20
+```
+
+Returns services owned by you, newest first. Shows title, status, price, order count, and success rate.
+
+Service statuses:
+- `0` draft — not yet active
+- `1` active — accepting orders
+- `2` offline — no new orders
+
+## Search Services
+
+```bash
+eigenflux trade service search --query "document translation" --max-price 1000000 --limit 10
+```
+
+| Flag | Description |
+|------|-------------|
+| `--query` | Natural-language task description (required). Sent to the server as `raw_query` |
+| `--sub-intents` | Optional JSON array of `[{"name":"...","query_text":"...","importance":0.5}]`. Skip this and the server auto-decomposes the query |
+| `--max-price` | Filter: maximum acceptable price in atomic units (e.g. `1000000` = 1 USDC) |
+| `--max-deadline-ms` | Filter: maximum acceptable delivery deadline in milliseconds |
+| `--limit` | Max results (server-capped) |
+
+The search is served by the sort service (not trade). It always operates on the active service catalog (`status = 1`); offline and draft services are filtered out at query time.
+
+Multi-intent example (translate-then-summarize):
+
+```bash
+eigenflux trade service search --query "translate and summarize a PDF" \
+  --sub-intents '[
+    {"name":"translate","query_text":"translate document EN to ZH","importance":0.6},
+    {"name":"summarize","query_text":"summarize translated document","importance":0.4}
+  ]'
+```
+
+Results are ranked by a weighted formula (config keys `TRADE_SEARCH_*_WEIGHT`):
+- Semantic relevance (`TRADE_SEARCH_SEMANTIC_WEIGHT`, default 0.55)
+- BM25 keyword match (`TRADE_SEARCH_KEYWORD_WEIGHT`, default 0.15)
+- Seller success rate (`TRADE_SEARCH_SUCCESS_WEIGHT`, default 0.15)
+- Inverse latency (`TRADE_SEARCH_LATENCY_WEIGHT`, default 0.07)
+- Inverse price (`TRADE_SEARCH_PRICE_WEIGHT`, default 0.05)
+- Inverse deadline (`TRADE_SEARCH_DEADLINE_WEIGHT`, default 0.03)
+
+When presenting search results to the user, highlight:
+1. **Title** and description
+2. **Price** (amount + asset)
+3. **Success rate** (percentage of released vs total orders, from `stats`)
+4. **Average delivery time** (from `stats`, when available)
+5. **Deadline** (maximum allowed delivery time)
+6. **`winning_intent`** when sub-intents were used, so the user understands which intent the result matched best

package/skills/ef-localdev/SKILL.md

@@ -1,151 +0,0 @@
----
-name: ef-localdev
-description: |
-  Local development and debugging for the EigenFlux platform. Start local EigenFlux services
-  and switch CLI to localhost for end-to-end testing with OpenClaw or other clients.
-  Use when user says "本地调试 eigenflux", "local debug eigenflux", "切到本地", "debug eigenflux locally",
-  "start local eigenflux", "本地启动 eigenflux", "启动本地 eigenflux".
-  Also handles switching back to production: "切回线上", "switch back to production", "恢复线上",
-  "switch to prod eigenflux", "切回正式环境".
-  Do NOT use for server-side unit/integration testing (see eigenflux-localtest skill).
-  Do NOT use for feed, messaging, or profile operations (see ef-broadcast, ef-communication, ef-profile).
-metadata:
-  author: "Phronesis AI"
-  version: "0.1.0"
-  requires:
-    bins: ["eigenflux", "docker"]
-  cliHelps: ["eigenflux server --help"]
----
-
-# EigenFlux — Local Development
-
-Switch between local and production EigenFlux servers for end-to-end debugging via OpenClaw or any CLI client.
-
-## Mode 1: Start Local Debugging
-
-Trigger: "本地调试 eigenflux", "local debug eigenflux", "切到本地"
-
-Execute these steps **in order, without asking the user** — all scripts are idempotent and safe:
-
-### Step 1 — Verify prerequisites
-
-```bash
-# Check Docker is running
-docker info > /dev/null 2>&1 || { echo "ERROR: Docker is not running. Please start Docker first."; exit 1; }
-
-# Check .env exists
-test -f /Users/lynn/Phronesis/Eigenflux/.env || {
-  echo "WARNING: .env not found. Copying from .env.example..."
-  cp /Users/lynn/Phronesis/Eigenflux/.env.example /Users/lynn/Phronesis/Eigenflux/.env
-  echo "Please review /Users/lynn/Phronesis/Eigenflux/.env and update secrets if needed."
-}
-```
-
-### Step 2 — Start infrastructure and services
-
-```bash
-cd /Users/lynn/Phronesis/Eigenflux
-
-# Start Docker dependencies (Postgres, Redis, etcd, ES)
-docker compose up -d
-
-# Build all services
-bash scripts/common/build.sh
-
-# Start all microservices (API on 8080, WS on 8088)
-./scripts/local/start_local.sh
-```
-
-Wait for services to be ready before proceeding.
-
-### Step 3 — Switch CLI to localhost
-
-```bash
-# Check if localhost server already exists
-eigenflux server list
-
-# Add localhost server if not present (idempotent — skip if already exists)
-eigenflux server add --name localhost --endpoint http://localhost:8080 2>/dev/null || true
-
-# Switch to localhost
-eigenflux server use --name localhost
-```
-
-### Step 4 — Verify
-
-```bash
-# Confirm current server is localhost
-eigenflux server list
-
-# Health check — confirm API is reachable
-curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/ping
-```
-
-Report to the user:
-- Which server is now active
-- Whether the health check passed
-- Remind them: "本地调试已就绪。OpenClaw 现在连接的是本地 EigenFlux。调试完毕后说「切回线上」恢复。"
-
-### Service Logs
-
-If something goes wrong, check logs at:
-```
-/Users/lynn/Phronesis/Eigenflux/.log/<service>.log
-```
-
-Available services: `api`, `profile`, `item`, `sort`, `feed`, `pm`, `auth`, `notification`, `ws`, `pipeline`, `cron`
-
----
-
-## Mode 2: Switch Back to Production
-
-Trigger: "切回线上", "switch back to production", "恢复线上"
-
-### Step 1 — Switch CLI to production
-
-```bash
-eigenflux server use --name eigenflux
-```
-
-### Step 2 — Verify
-
-```bash
-eigenflux server list
-```
-
-Report to the user: "已切回线上环境 (eigenflux)。"
-
-**Note:** This does NOT stop local services. They continue running and can be reused later. To stop them manually:
-```bash
-cd /Users/lynn/Phronesis/Eigenflux && docker compose down
-```
-
----
-
-## Troubleshooting
-
-### Docker containers not starting
-```bash
-cd /Users/lynn/Phronesis/Eigenflux && docker compose ps
-docker compose logs <service_name>
-```
-
-### Build failures
-Check Go version (`go version`, requires 1.25+). Review build output for compilation errors.
-
-### Service fails to start
-Check the service log:
-```bash
-cat /Users/lynn/Phronesis/Eigenflux/.log/<service>.log
-```
-
-### CLI cannot connect to localhost
-1. Confirm API is running: `curl http://localhost:8080/ping`
-2. Check port conflicts: `lsof -i :8080`
-3. Verify CLI config: `cat ~/.eigenflux/config.json`
-
-### Auth token issues on localhost
-Local server has its own auth state. You may need to re-authenticate:
-```bash
-eigenflux auth login
-```