@questionbase/deskfree 0.3.0-alpha.21 → 0.3.0-alpha.23

package/README.md

@@ -15,31 +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_suggest_tasks                                           │
-│   deskfree_create_activity                                       │
-│   deskfree_update_activity                                       │
-│   deskfree_classify_task                                         │
-│   deskfree_learn_from_task                                       │
-│   deskfree_update_deliverable                                    │
-│   deskfree_send_message (+ task suggestions)                     │
+│   deskfree_send_message                                          │
+│   deskfree_propose                                               │
+│   deskfree_update_file                                           │
+│   deskfree_create_file                                           │
+│   deskfree_claim_evaluation                                      │
+│   deskfree_submit_evaluation                                     │
 └──────────┬───────────────────────────┬───────────────────────────┘
            │                           │
            ▼                           ▼
 ┌──────────────────────────────────────────────────────────────────┐
 │                      DeskFree Backend                           │
 │                                                                  │
-│   Tasks          Activities      Messages        WebSocket Gateway│
-│   ──────         ──────────      ────────        ─────────────── │
-│   State machine  Knowledge       1:1 bot↔user   DynamoDB-backed  │
-│   RLS-scoped     containers      Threaded by     Thin notifs      │
-│   Atomic claims  Learn loop      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** — 10 task, activity, and messaging 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
@@ -126,12 +125,33 @@ bot ──[start_task]──> bot (is_working) ──[complete_task(done)]──
                                                                          [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.
+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

package/dist/index.d.ts

@@ -426,8 +426,19 @@ interface Task {
     botId?: string | null;
     createdById: string;
     reason?: string | null;
-    deliverable?: string | null;
-    deliverableFormat?: 'markdown' | 'html' | null;
+    fileId?: string | null;
+    fileName?: string | null;
+}
+interface TaskSummary {
+    taskId: string;
+    title: string;
+    status: 'bot' | 'human' | 'done';
+    instructions: string | null;
+    isWorking: boolean;
+    fileId: string | null;
+    fileName: string | null;
+    createdAt: string;
+    updatedAt: string;
 }
 interface TaskMessage {
     messageId: string;
@@ -437,14 +448,30 @@ interface TaskMessage {
     createdAt: string;
     userName?: string | null;
 }
+interface FileContext {
+    fileId: string;
+    name: string;
+    description: string;
+    content: string;
+    contentFormat: string;
+    version: number;
+}
 interface TaskWithContext extends Task {
     instructions: string;
-    deliverable: string;
     messages: TaskMessage[];
+    fileContext: FileContext | null;
+    skillContext?: Array<{
+        skillId: string;
+        name: string;
+        displayName: string;
+        instructions: string;
+        criticalSection: string;
+    }>;
 }
 interface CompleteTaskInput {
     taskId: string;
     outcome: 'done' | 'blocked';
+    summary?: string;
 }
 interface WorkspaceStateTask {
     taskId: string;
@@ -452,7 +479,8 @@ interface WorkspaceStateTask {
     status: 'bot' | 'human' | 'done';
     isWorking?: boolean;
     instructions?: string | null;
-    deliverable?: string | null;
+    fileId?: string | null;
+    fileName?: string | null;
     createdAt: string;
     updatedAt: string;
 }
@@ -465,6 +493,14 @@ interface Initiative {
     taskCount: number;
     activeTaskCount: number;
 }
+interface WorkspaceFile {
+    fileId: string;
+    name: string;
+    description: string;
+    contentFormat: string;
+    version: number;
+    updatedAt: string;
+}
 interface WorkspaceState {
     tasks: WorkspaceStateTask[];
     recentlyDone: WorkspaceStateTask[];
@@ -476,6 +512,7 @@ interface WorkspaceState {
         initiativeId?: string | null;
     }>;
     initiatives: Initiative[];
+    files: WorkspaceFile[];
 }
 interface EvaluationTaskMessage {
     messageId: string;
@@ -537,13 +574,24 @@ declare class DeskFreeClient {
         content: string;
     }>;
     /**
-     * Send a text message (with optional attachments or suggestions) to a DeskFree conversation.
+     * Send a streaming chunk (delta only) for an in-progress message.
+     * Broadcasts delta over WS and stores full content in DynamoDB for crash recovery.
+     */
+    streamChunk(input: {
+        messageId: string;
+        delta: string;
+        fullContent: string;
+    }): Promise<{
+        messageId: string;
+    }>;
+    /**
+     * Send a text message to a DeskFree conversation.
      *
-     * @param input - Message content, optional userId, taskId, attachments, and suggestions
+     * @param input - Message content, optional userId, taskId, attachments
      */
     sendMessage(input: {
         userId?: string;
-        content?: string;
+        content: string;
         taskId?: string;
         attachments?: Array<{
             s3Key: string;
@@ -551,10 +599,6 @@ declare class DeskFreeClient {
             contentType: string;
             size: number;
         }>;
-        suggestions?: Array<{
-            title: string;
-            instructions?: string;
-        }>;
     }): Promise<{
         messageId: string;
         content: string;
@@ -562,6 +606,7 @@ declare class DeskFreeClient {
     /** Fetch paginated message history for a conversation. */
     listMessages(input: {
         userId?: string;
+        taskId?: string;
         cursor?: string | null;
         limit?: number;
     }): Promise<MessagesResponse>;
@@ -570,13 +615,37 @@ declare class DeskFreeClient {
     /** Claim a task so the bot can begin working on it. Returns enriched context. */
     claimTask(input: {
         taskId: string;
+        runnerId?: string;
     }): Promise<TaskWithContext>;
-    /** Update the deliverable (markdown or HTML content) for a task. */
-    updateDeliverable(input: {
+    /** Fetch a lightweight task summary by ID. Read-only, no side effects. */
+    getTask(input: {
         taskId: string;
-        deliverable: string;
-        format?: 'markdown' | 'html';
+    }): Promise<TaskSummary>;
+    /** Update the content of an existing file. */
+    updateFile(input: {
+        fileId: string;
+        content: string;
+        contentFormat?: 'markdown' | 'html';
     }): Promise<void>;
+    /** Create a new persistent file. */
+    createFile(input: {
+        name: string;
+        description?: string;
+        content?: string;
+        contentFormat?: 'markdown' | 'html';
+    }): Promise<{
+        fileId: string;
+        name: string;
+    }>;
+    /** List all files for this bot (metadata only, no content). */
+    listFiles(): Promise<Array<{
+        fileId: string;
+        name: string;
+        description: string;
+        contentFormat: string;
+        version: number;
+        updatedAt: string;
+    }>>;
     /** Send an agent status update to DeskFree. */
     statusUpdate(input: {
         status: 'idle' | 'working' | 'responding';
@@ -623,35 +692,35 @@ declare class DeskFreeClient {
     completeTask(input: CompleteTaskInput): Promise<Task & {
         outcome: 'done' | 'blocked';
     }>;
-    /** Suggest new tasks for the human to review and approve (via messages.send with suggestions). */
-    suggestTasks(input: {
+    /** Reopen a completed/human task back to bot status for further work. */
+    reopenTask(input: {
+        taskId: string;
+        reason?: string;
+    }): Promise<Task>;
+    /** Propose a plan — creates a proposal message with plan metadata. No DB rows until human approves. */
+    proposePlan(input: {
         tasks: Array<{
-            title: string;
-            instructions?: string;
-        }>;
-        taskId?: string;
-    }): Promise<{
-        messageId: string;
-        content: string;
-    }>;
-    /** Suggest tasks via the dedicated bot/tasks.suggest endpoint. */
-    suggestTasksDedicated(input: {
-        suggestions: Array<{
-            title: string;
+            title?: string;
             instructions?: string;
+            substeps?: string[];
+            file?: {
+                type: 'existing';
+                existingId: string;
+            } | {
+                type: 'new';
+                name: string;
+                description?: string;
+            };
             estimatedTokens?: number;
-            dependsOn?: string[];
-            initiativeId?: string;
+            scheduledFor?: string;
         }>;
-        parentTaskId?: string;
-        initiativeSuggestions?: Array<{
+        initiative?: string | {
             title: string;
             content: string;
-            taskRefs?: number[];
-        }>;
+        };
+        context?: string;
     }): Promise<{
-        suggestionIds: string[];
-        initiativeSuggestionIds?: string[];
+        messageId: string;
     }>;
     /**
      * Claim a pending evaluation for a task. Atomically sets isWorking=true where
@@ -747,4 +816,4 @@ declare const plugin: {
     register(api: OpenClawPluginApi): void;
 };
 
-export { type AnyAgentTool, type ChannelAccountSnapshot, type ChannelCapabilities, type ChannelConfigAdapter, type ChannelGatewayAdapter, type ChannelGatewayContext, type ChannelLogoutContext, type ChannelLogoutResult, type ChannelMessagingAdapter, type ChannelMessagingTargetResolver, type ChannelMeta, type ChannelOnboardingAdapter, type ChannelOnboardingResult, type ChannelOnboardingStatus, type ChannelOutboundAdapter, type ChannelOutboundContext, type ChannelPlugin, type ChannelProbeResult, type ChannelSecurityAdapter, type ChannelSecurityDmPolicy, type ChannelSetupAdapter, type ChannelStatusAdapter, type ChannelStatusIssue, type ChatMessage, type ChatMessageAttachment, type ClaimEvaluationResponse, type CompleteTaskInput, type DeskFreeChannelConfig, DeskFreeClient, DeskFreeError, type EvaluationTaskMessage, type FinalizedMsgContext, type Initiative, type MessagesResponse, OfflineQueue, type OpenClawConfig, type OpenClawPluginApi, type OpenClawPluginToolContext, type OpenClawPluginToolFactory, type OpenClawPluginToolOptions, type OutboundDeliveryResult, type PluginHookAgentContext, type PluginHookBeforeAgentStartEvent, type PluginHookBeforeAgentStartResult, type PluginHookHandlerMap, type PluginHookName, type PluginLogger, type PluginRuntime, type ReplyDispatcher, type ResolvedDeskFreeAccount, type Task, type TaskMessage, type TaskWithContext, type WizardPrompter, type WorkspaceState, type WorkspaceStateTask, type WsNotification, type WsTicketResponse, plugin as default, reportError };
+export { type AnyAgentTool, type ChannelAccountSnapshot, type ChannelCapabilities, type ChannelConfigAdapter, type ChannelGatewayAdapter, type ChannelGatewayContext, type ChannelLogoutContext, type ChannelLogoutResult, type ChannelMessagingAdapter, type ChannelMessagingTargetResolver, type ChannelMeta, type ChannelOnboardingAdapter, type ChannelOnboardingResult, type ChannelOnboardingStatus, type ChannelOutboundAdapter, type ChannelOutboundContext, type ChannelPlugin, type ChannelProbeResult, type ChannelSecurityAdapter, type ChannelSecurityDmPolicy, type ChannelSetupAdapter, type ChannelStatusAdapter, type ChannelStatusIssue, type ChatMessage, type ChatMessageAttachment, type ClaimEvaluationResponse, type CompleteTaskInput, type DeskFreeChannelConfig, DeskFreeClient, DeskFreeError, type EvaluationTaskMessage, type FileContext, type FinalizedMsgContext, type Initiative, type MessagesResponse, OfflineQueue, type OpenClawConfig, type OpenClawPluginApi, type OpenClawPluginToolContext, type OpenClawPluginToolFactory, type OpenClawPluginToolOptions, type OutboundDeliveryResult, type PluginHookAgentContext, type PluginHookBeforeAgentStartEvent, type PluginHookBeforeAgentStartResult, type PluginHookHandlerMap, type PluginHookName, type PluginLogger, type PluginRuntime, type ReplyDispatcher, type ResolvedDeskFreeAccount, type Task, type TaskMessage, type TaskSummary, type TaskWithContext, type WizardPrompter, type WorkspaceFile, type WorkspaceState, type WorkspaceStateTask, type WsNotification, type WsTicketResponse, plugin as default, reportError };