@questionbase/deskfree 0.3.0-alpha.4 → 0.3.0-alpha.41

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 or blocked, manage goals, 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
 
@@ -15,29 +15,30 @@ Agents can pick up tasks, post progress updates, mark work as done or blocked, m
 │   deskfree_state             Inbound messages from humans        │
 │   deskfree_start_task        Outbound replies from agent         │
 │   deskfree_complete_task     Real-time notifications             │
-│   deskfree_create_task                                           │
-│   deskfree_create_goal                                           │
-│   deskfree_update_goal                                           │
-│   deskfree_update_deliverable                                    │
 │   deskfree_send_message                                          │
+│   deskfree_propose                                               │
+│   deskfree_update_file                                           │
+│   deskfree_create_file                                           │
+│   deskfree_claim_evaluation                                      │
+│   deskfree_submit_evaluation                                     │
 └──────────┬───────────────────────────┬───────────────────────────┘
            │                           │
            ▼                           ▼
 ┌──────────────────────────────────────────────────────────────────┐
 │                      DeskFree Backend                           │
 │                                                                  │
-│   Tasks          Goals          Messages        WebSocket Gateway │
-│   ──────         ─────          ────────        ─────────────────│
-│   State machine  Hierarchical   1:1 bot↔user   DynamoDB-backed  │
-│   RLS-scoped     organization   Threaded by     Thin notifs      │
-│   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 and goal 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
@@ -116,20 +117,38 @@ Edit your OpenClaw config file (`~/.openclaw/config.json5`):
 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 ──[start_task]──> working_on_it ──[complete_task(done)]──> waiting_for_human
-                                       │                                        │
-                                       └──[complete_task(blocked)]──>           │
-                                                                     human approves/declines
-                                                                                │
-                                                                         [approve] → done
+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