@questionbase/deskfree 0.3.0-alpha.9 → 0.4.0

package/package.json

@@ -1,64 +1,54 @@
 {
   "name": "@questionbase/deskfree",
-  "version": "0.3.0-alpha.9",
-  "description": "OpenClaw channel plugin for DeskFree — turns DeskFree into a messaging platform for OpenClaw AI agents",
+  "version": "0.4.0",
+  "description": "DeskFree agent runtime — connect AI agents to DeskFree projects",
   "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/questionbase/deskfree.git",
+    "directory": "packages/runtime"
   },
-  "openclaw": {
-    "extensions": [
-      "./dist/index.js"
-    ]
+  "keywords": [
+    "deskfree",
+    "agent",
+    "ai",
+    "project-management"
+  ],
+  "bin": {
+    "deskfree-agent": "dist/bin.js"
   },
   "files": [
-    "dist/",
-    "openclaw.plugin.json",
-    "skills/"
+    "dist/"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "tsc": "tsc --noEmit",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
   "publishConfig": {
     "access": "public"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/questionbase/deskfree.git"
+  "engines": {
+    "node": ">=18.0.0"
   },
-  "peerDependencies": {
-    "openclaw": ">=0.1.0"
+  "scripts": {
+    "build": "tsup",
+    "start": "node dist/bin.js",
+    "dev": "tsx src/bin.ts",
+    "tsc": "tsc --noEmit",
+    "test": "vitest run"
   },
   "dependencies": {
-    "@sinclair/typebox": "^0.34.0",
-    "ws": "^8.18.0"
+    "@anthropic-ai/claude-agent-sdk": "^0.2.71",
+    "@aws-sdk/client-bedrock-runtime": "^3.700.0",
+    "zod": "4.3.6"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "0.78.0",
+    "@deskfree/core": "*",
+    "@sinclair/typebox": "^0.34.48",
+    "@types/node": "^22.0.0",
     "@types/ws": "^8.5.0",
-    "tsup": "8.5.1",
-    "typescript": "^5.9.0",
-    "vitest": "^4.0.18"
-  },
-  "keywords": [
-    "openclaw",
-    "deskfree",
-    "channel",
-    "plugin",
-    "ai",
-    "agent"
-  ],
-  "license": "MIT"
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "ws": "^8.18.0"
+  }
 }

package/README.md

@@ -1,137 +0,0 @@
-# @questionbase/deskfree
-
-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.
-
-## How it works
-
-```
-┌──────────────────────────────────────────────────────────────────┐
-│                        OpenClaw Agent                            │
-│                                                                  │
-│   Tools (HTTP)               Channel (WebSocket + polling)       │
-│   ─────────────              ──────────────────────────────      │
-│   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 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│
-└──────────────────────────────────────────────────────────────────┘
-```
-
-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
-3. **Skill** — workflow knowledge that teaches the agent how to use the tools correctly
-
-## Install
-
-```bash
-openclaw plugins install @questionbase/deskfree
-```
-
-Requires OpenClaw >= 0.1.0.
-
-This installs the plugin to `~/.openclaw/extensions/deskfree/` and enables it automatically.
-
-### Verify
-
-```bash
-openclaw plugins list
-openclaw plugins info deskfree
-```
-
-## Configuration
-
-After installation, configure the DeskFree channel. You can either:
-
-### Option A: Interactive setup
-
-Run the OpenClaw onboarding wizard — it will detect the unconfigured DeskFree channel and prompt for credentials.
-
-### Option B: Manual config
-
-Edit your OpenClaw config file (`~/.openclaw/config.json5`):
-
-**Single account (most common):**
-```json5
-{
-  channels: {
-    deskfree: {
-      botToken: "bot_...",
-      apiUrl: "https://api.example.com/v1/bot",
-      wsUrl: "wss://ws.example.com"
-    }
-  }
-}
-```
-
-**Multiple accounts:**
-```json5
-{
-  channels: {
-    deskfree: {
-      accounts: {
-        "my-bot": {
-          botToken: "bot_...",
-          apiUrl: "https://api.example.com/v1/bot",
-          wsUrl: "wss://ws.example.com"
-        }
-      }
-    }
-  }
-}
-```
-
-| Field | Description |
-|-------|-------------|
-| `botToken` | Bot authentication token (starts with `bot_`) |
-| `apiUrl` | DeskFree bot API base URL (the `/v1/bot` tRPC endpoint) |
-| `wsUrl` | WebSocket gateway URL for real-time notifications |
-
-### Getting credentials
-
-1. Create a bot in your DeskFree instance
-2. Copy the bot token from the bot settings page
-3. Your DeskFree admin can provide the API and WebSocket URLs
-
-## Task workflow
-
-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
-```
-
-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.
-
-## 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
-
-MIT

package/openclaw.plugin.json

@@ -1,8 +0,0 @@
-{
-  "id": "deskfree",
-  "name": "DeskFree",
-  "description": "Channel plugin and agent tools for DeskFree project management",
-  "configSchema": { "type": "object", "additionalProperties": true },
-  "channels": ["deskfree"],
-  "skills": ["./skills"]
-}

package/skills/deskfree/SKILL.md

@@ -1,243 +0,0 @@
----
-name: deskfree
-description: >
-  DeskFree task management and human-AI collaboration workflows.
-  Use when: creating goals/tasks, managing work items, updating deliverables,
-  communicating with humans through DeskFree, checking workspace state,
-  handling task lifecycle (start → work → complete → review).
-  Do NOT use for: general project management advice without DeskFree tools,
-  OpenClaw configuration or gateway setup, non-DeskFree platforms (Jira, Asana, etc.),
-  direct file/code operations (use standard tools for those, create DeskFree tasks for tracking).
-version: 4.0.0
-metadata: { 'openclaw': { 'emoji': '🏠' } }
----
-
-# DeskFree Workflow Guide
-
-## ⚠️ Critical — Read First
-
-### State Machine (memorize this)
-
-```
-create_task → ready_for_bot → [start_task] → working_on_it → [complete_task] → waiting_for_human
-                   ↑                                                                |
-                   |                    human approves/declines                     |
-                   └────────────────────────────────────────────────────────────────┘
-                                                                                    |
-                                                                               [approve] → done
-```
-
-- `complete_task` outcome `done` = work complete for review
-- `complete_task` outcome `blocked` = need human input (send message FIRST explaining why)
-- Both outcomes move to `waiting_for_human` — the human triages from there
-
-### Three Rules That Break Everything If Ignored
-
-1. **Always self-task.** Create a DeskFree task before starting ANY work. Tasks are cheap — invisible work is expensive. No exceptions.
-2. **Always check state first.** Call `deskfree_state` before creating tasks or goals. Prevents duplicates, shows what needs attention.
-3. **Always complete tasks.** Never leave a task in `working_on_it`. End with `deskfree_complete_task` — outcome `done` or `blocked`.
-
-### Auto-Threading
-
-After `deskfree_start_task`, ALL your outbound messages automatically thread into that task. No need to pass `taskId` to `deskfree_send_message`. After `deskfree_complete_task`, auto-threading stops.
-
-The task sidebar is your human's window into your work — every message appears there in real-time.
-
----
-
-## Validation Gates
-
-### Pre-Flight (before ANY work)
-
-- [ ] Called `deskfree_state` — confirmed it returned data (not empty/error)
-- [ ] Checked for existing goals/tasks that match intent — no duplicates
-- [ ] Created a task with clear, action-oriented title (max 200 chars)
-- [ ] Called `deskfree_start_task` — confirmed task moved to `working_on_it`
-
-### Mid-Work
-
-- [ ] Deliverable started immediately after starting task (not waiting until end)
-- [ ] `deskfree_update_deliverable` succeeded (no error response)
-- [ ] If blocked: sent message explaining WHY before calling `complete_task` with `blocked`
-
-### Pre-Completion
-
-- [ ] Deliverable is non-empty and meaningful (not just headers/placeholders)
-- [ ] Deliverable is well-structured markdown that stands alone
-- [ ] Called `deskfree_complete_task` — confirmed task moved to `waiting_for_human`
-- [ ] If sub-agent: terminated after completion (one task per sub-agent)
-
----
-
-## Goals vs Tasks
-
-| Signal | Action |
-|---|---|
-| Multi-step objective ("grow my LinkedIn") | **Goal** → break into 3-5 tasks |
-| Single deliverable ("write a blog post") | **Task** only |
-| Vague ambition ("help me with marketing") | **Goal** → clarify via tasks |
-| Quick fix ("fix this bug") | **Task** only |
-
-### Goal Management
-
-- Create goals with `deskfree_create_goal` for multi-step objectives
-- Link tasks to goals via `goalId` parameter in `deskfree_create_task`
-- **Drip tasks:** Max 3 pending tasks per goal. Create next when one completes.
-- **Stale goals (48h no activity):** Create a task or message the human
-- Mark completed with `deskfree_update_goal` when all objectives met
-
----
-
-## Task Workflow
-
-### Orchestrator Flow (main session)
-
-```
-1. deskfree_state              → assess workspace
-2. deskfree_create_task        → create with clear title + instructions
-3. deskfree_start_task         → claim it (returns full context)
-4. deskfree_update_deliverable → build incrementally as you work
-5. deskfree_complete_task      → outcome "done" or "blocked"
-```
-
-### Sub-Agent Flow (recommended for tasks > 5 min)
-
-```
-Orchestrator: deskfree_create_task → deskfree_start_task → spawn sub-agent with full task context
-Sub-agent:    deskfree_update_deliverable (incrementally) → deskfree_complete_task → terminate
-```
-
-Sub-agents have **3 tools only:** `deskfree_update_deliverable`, `deskfree_complete_task`, `deskfree_send_message`. They cannot create goals, create tasks, or read workspace state.
-
-### When to Use Main vs Sub-Agent
-
-| Main session | Sub-agent |
-|---|---|
-| Quick tasks (< 5 min) | Research, reports, analysis |
-| Interactive/back-and-forth | Code development, debugging |
-| Urgent fixes | Long operations (> 10 min) |
-| | Background work while human may message |
-
----
-
-## Messaging
-
-**Normal replies:** Just respond — the channel handles routing automatically. No tool needed.
-
-**Use `deskfree_send_message` only for:**
-- Progress updates during task execution
-- Questions needing human input mid-task
-- Status reports for long-running tasks
-
-**Never use it for:** Normal conversation replies (channel handles those).
-
----
-
-## Decision Tree
-
-### Heartbeat / Proactive Check
-
-1. `deskfree_state` → get workspace snapshot
-2. Active goals without pending tasks? → `deskfree_create_task` for next step
-3. `ready_for_bot` tasks? → `deskfree_start_task` + spawn sub-agents
-4. Goals stale 48h? → Create task or nudge human
-5. `working_on_it` with no active sub-agent? → Complete as blocked or resume
-
-### Human Gives You Work
-
-1. `deskfree_state` → check existing goals/tasks
-2. `deskfree_create_task` → clear title + instructions
-3. `deskfree_start_task` → claim it
-4. Work → `deskfree_update_deliverable` incrementally
-5. `deskfree_complete_task` → outcome `done` or `blocked`
-
----
-
-## Tools Reference
-
-> **Full parameter details:** See `references/tools.md`
-
-### Orchestrator (8 tools)
-
-| Tool | What it does |
-|---|---|
-| `deskfree_state` | Full workspace snapshot — goals, tasks, recently done |
-| `deskfree_create_goal` | Create high-level objective |
-| `deskfree_update_goal` | Update goal status/title/description |
-| `deskfree_create_task` | Create task (→ `ready_for_bot`), optionally link to goal |
-| `deskfree_start_task` | Claim task → `working_on_it`, returns full context |
-| `deskfree_update_deliverable` | Build deliverable markdown incrementally |
-| `deskfree_complete_task` | Mark done or blocked → `waiting_for_human` |
-| `deskfree_send_message` | Message in task thread |
-
-### Worker (3 tools — sub-agents only)
-
-`deskfree_update_deliverable`, `deskfree_complete_task`, `deskfree_send_message`
-
----
-
-## Deliverable Best Practices
-
-Structure deliverables as **standalone markdown documents:**
-
-```markdown
-# Task Title
-
-## Summary
-Brief overview of what was accomplished.
-
-## Key Findings / Results
-- Main points with supporting detail
-
-## Details
-Detailed analysis, implementation notes, etc.
-
-## Next Steps (if applicable)
-- Follow-up actions, outstanding questions
-```
-
-**Build incrementally** — start with outline immediately after `deskfree_start_task`, fill sections as you go, polish before completing. A half-complete deliverable is infinitely better than none.
-
----
-
-## Error Handling
-
-| Error | Cause | Action |
-|---|---|---|
-| `deskfree_state` returns empty | No goals or tasks exist | Create a goal or task if appropriate. **Do NOT retry in a loop.** |
-| 404 on `deskfree_start_task` | Task not `ready_for_bot` or doesn't exist | Another bot claimed it. Call `deskfree_state`, try a different task. |
-| 404 on `deskfree_complete_task` | Task not `working_on_it` | Already completed or released. Check state. |
-| 409 on `deskfree_start_task` | Race condition — another bot claimed it | Call `deskfree_state`, pick a different task. |
-| 401 Unauthorized | Bot token invalid or expired | Check channel configuration. Do not retry. |
-| `deskfree_update_deliverable` fails | Task not in `working_on_it` or network error | Verify task state with `deskfree_state`. If task was released, re-claim or abort. |
-| `deskfree_create_goal` fails | Validation error (title too long, etc.) | Check parameter constraints. Title max 200 chars. |
-| Sub-agent spawn fails | Resource limits, config error | Complete task as `blocked` with explanation. Do not leave in `working_on_it`. |
-| WebSocket disconnected | Network issue | Plugin auto-reconnects with backoff. Messages fall back to HTTP polling. No action needed. |
-
-### Recovery Pattern
-
-If anything goes wrong mid-task:
-1. Send a message explaining what happened (`deskfree_send_message`)
-2. Save whatever partial deliverable you have (`deskfree_update_deliverable`)
-3. Complete as `blocked` (`deskfree_complete_task` with outcome `blocked`)
-4. **Never leave a task stranded in `working_on_it`**
-
----
-
-## Task Title Examples
-
-**Good (short, scannable, action-oriented):**
-- "Research competitor HumanLayer"
-- "Deploy staging hotfix"
-- "Write API docs for /users endpoint"
-
-**Bad (verbose, unclear):**
-- "Do some research on a competitor called HumanLayer and write up findings"
-- "There's a bug in staging that needs fixing"
-
----
-
-## Human Review Outcomes
-
-- **Approve** → task moves to `done`. Work accepted.
-- **Decline / request changes** → task returns to `ready_for_bot` with feedback. Restart it.

package/skills/deskfree/references/tools.md

@@ -1,102 +0,0 @@
-# DeskFree Tools — Full Parameter Reference
-
-## Orchestrator Tools (8)
-
-### `deskfree_state`
-Get full workspace snapshot — all goals with tasks, unlinked tasks, recently done.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| *(none)* | — | — | — |
-
-**Returns:** Goals array (each with nested tasks), unlinked tasks, recently completed tasks.
-
----
-
-### `deskfree_create_goal`
-Create a high-level objective to break into tasks.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `title` | string | Yes | Goal title (max 200 chars) |
-| `description` | string | No | What the user wants to achieve — the big picture |
-
-**Returns:** Created goal object with ID.
-
----
-
-### `deskfree_update_goal`
-Update a goal's status, title, or description.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `goalId` | string | Yes | Goal ID to update |
-| `title` | string | No | New title (max 200 chars) |
-| `description` | string | No | Updated description |
-| `status` | string | No | New status: `active`, `paused`, `completed`, `archived` |
-
----
-
-### `deskfree_create_task`
-Create a new task (starts as `ready_for_bot`). Optionally link to a goal.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `title` | string | Yes | Task title (max 200 chars) |
-| `instructions` | string | No | Detailed instructions for the task |
-| `goalId` | string | No | Link this task to a goal |
-
----
-
-### `deskfree_start_task`
-Claim a `ready_for_bot` task → moves to `working_on_it`. Returns full context.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `taskId` | string | Yes | Task UUID to claim |
-
-**Returns:** Full task context — instructions, current deliverable, message history. Use this to populate sub-agent spawn prompts.
-
-**Errors:** 404 if task not `ready_for_bot` or doesn't exist. 409 if already claimed.
-
----
-
-### `deskfree_update_deliverable`
-Update task deliverable. Build incrementally as you work.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `taskId` | string | Yes | Task UUID |
-| `deliverable` | string | Yes | Full markdown deliverable content (replaces previous) |
-
-**Note:** Each call replaces the entire deliverable. Always send the complete current version, not just new additions.
-
----
-
-### `deskfree_complete_task`
-Finish a task → moves to `waiting_for_human`.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `taskId` | string | Yes | Task UUID |
-| `outcome` | string | Yes | `done` (work complete) or `blocked` (need human input) |
-
-**Important:** If `blocked`, send a message explaining WHY before calling this.
-
----
-
-### `deskfree_send_message`
-Send a message in the task thread.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `content` | string | Yes | Message content |
-| `taskId` | string | No | Task UUID (optional — auto-threaded to active task if omitted) |
-
----
-
-## Worker Tools (3 — sub-agents only)
-
-Sub-agents receive: `deskfree_update_deliverable`, `deskfree_complete_task`, `deskfree_send_message`
-
-They **cannot** use: `deskfree_state`, `deskfree_create_goal`, `deskfree_update_goal`, `deskfree_create_task`, `deskfree_start_task`