@questionbase/deskfree 0.3.0-alpha.3 → 0.3.0-alpha.31

package/README.md

@@ -2,7 +2,7 @@
 
 OpenClaw plugin that connects AI agents to [DeskFree](https://github.com/deskfree) — a task management platform built for human-AI collaboration.
 
-Agents can pick up tasks, post progress updates, mark work as done, and exchange messages with humans — all through a structured workflow with human oversight gates.
+Agents can pick up tasks, post progress updates, mark work as done or blocked, manage activities (knowledge containers), and exchange messages with humans — all through a structured workflow with human oversight gates.
 
 ## How it works
 
@@ -12,27 +12,33 @@ Agents can pick up tasks, post progress updates, mark work as done, and exchange
 │                                                                  │
 │   Tools (HTTP)               Channel (WebSocket + polling)       │
 │   ─────────────              ──────────────────────────────      │
-│   get_next_task              Inbound messages from humans        │
-│   comment / done / giveup    Outbound replies from agent         │
-│   list_tasks / create_task   Real-time notifications             │
+│   deskfree_state             Inbound messages from humans        │
+│   deskfree_start_task        Outbound replies from agent         │
+│   deskfree_complete_task     Real-time notifications             │
+│   deskfree_send_message                                          │
+│   deskfree_propose                                               │
+│   deskfree_update_file                                           │
+│   deskfree_create_file                                           │
+│   deskfree_claim_evaluation                                      │
+│   deskfree_submit_evaluation                                     │
 └──────────┬───────────────────────────┬───────────────────────────┘
            │                           │
            ▼                           ▼
 ┌──────────────────────────────────────────────────────────────────┐
 │                      DeskFree Backend                           │
 │                                                                  │
-│   Tasks          Messages        WebSocket Gateway               │
-│   ──────         ────────        ─────────────────               │
-│   State machine  1:1 bot↔user   DynamoDB-backed                 │
-│   RLS-scoped     Threaded by     Thin notifications              │
-│   Atomic claims  task             + polling fallback             │
+│   Tasks          Files           Messages        WebSocket Gateway│
+│   ──────         ─────           ────────        ─────────────── │
+│   State machine  Persistent      1:1 bot↔user   DynamoDB-backed  │
+│   RLS-scoped     documents       Threaded by     Thin notifs      │
+│   Atomic claims  Versioned       task            + polling fallback│
 └──────────────────────────────────────────────────────────────────┘
 ```
 
 The plugin registers three things with OpenClaw:
 
 1. **Channel** — bidirectional messaging between DeskFree users and the agent
-2. **Tools** — 8 task management tools the agent can call
+2. **Tools** — 9 task, file, and messaging tools the agent can call
 3. **Skill** — workflow knowledge that teaches the agent how to use the tools correctly
 
 ## Install
@@ -108,20 +114,41 @@ Edit your OpenClaw config file (`~/.openclaw/config.json5`):
 
 ## Task workflow
 
-Tasks follow a strict state machine. The agent claims a task, works on it, and either completes or gives it up — always returning control to a human.
+Tasks follow a strict state machine. The agent claims a task, works on it, and completes it (done or blocked) — always returning control to a human.
 
 ```
-ready_for_bot ──[get_next_task]──> working_on_it ──[done]──> waiting_for_human
-                                         │
-                                         └───[giveup]──> waiting_for_human
+pending ──[start_task]──> active ──[complete_task(review)]──> review ──[bot completes]──> done
+                                  └──[complete_task(done)]──> done
+                                  └──[complete_task(blocked)]──> review
 ```
 
-See [docs/tools.md](docs/tools.md) for the full tool reference and [docs/architecture.md](docs/architecture.md) for how the system works under the hood.
+See `skills/deskfree/references/tools.md` for the full tool reference.
+
+### Message Flow
+
+**Inbound (human → agent):** WebSocket sends thin notification (`hint: "message.new"`) → plugin fetches full message via HTTP. Fallback: polls every 30s if WebSocket is unavailable.
+
+**Outbound (agent → human):** Supports streaming (progressive deltas via `streamChunk`, finalized via `updateMessage`) and non-streaming (direct `POST messages.send`). Text chunked at 2000 chars when streaming is not active.
+
+### WebSocket Gateway
+
+1. Request ticket: `POST messages.wsTicket` → one-time ticket (30s expiry)
+2. Connect: `wss://...?ticket=<ticket>`
+3. Keep alive: ping every 5 min (API Gateway idle timeout = 10 min)
+4. Reconnect: exponential backoff (2s → 30s) on disconnect
+5. Cursor persisted to `deskfree/{accountId}/cursor` for resume after restart
+
+### Plugin Registration
+
+```
+register(api)
+  ├─ setDeskFreeRuntime(api.runtime)     // runtime singleton
+  ├─ api.registerChannel(deskFreePlugin) // messaging channel
+  └─ api.registerTool(factory)           // task management tools
+```
 
 ## Documentation
 
-- **[Architecture](docs/architecture.md)** — system design, message flow, WebSocket gateway
-- **[Tools reference](docs/tools.md)** — all 8 agent tools with parameters and behavior
 - **[Publishing](PUBLISH.md)** — how to release new versions
 
 ## License