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

package/README.md

@@ -126,12 +126,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):** Messages chunked at 2000 chars → `POST messages.send` per chunk.
+
+### 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,23 @@ 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;
 }
 interface CompleteTaskInput {
     taskId: string;
     outcome: 'done' | 'blocked';
+    summary?: string;
 }
 interface WorkspaceStateTask {
     taskId: string;
@@ -452,7 +472,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 +486,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 +505,7 @@ interface WorkspaceState {
         initiativeId?: string | null;
     }>;
     initiatives: Initiative[];
+    files: WorkspaceFile[];
 }
 interface EvaluationTaskMessage {
     messageId: string;
@@ -537,13 +567,13 @@ declare class DeskFreeClient {
         content: string;
     }>;
     /**
-     * Send a text message (with optional attachments or suggestions) to a DeskFree conversation.
+     * 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 +581,6 @@ declare class DeskFreeClient {
             contentType: string;
             size: number;
         }>;
-        suggestions?: Array<{
-            title: string;
-            instructions?: string;
-        }>;
     }): Promise<{
         messageId: string;
         content: string;
@@ -571,12 +597,35 @@ declare class DeskFreeClient {
     claimTask(input: {
         taskId: 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,25 +672,14 @@ 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: {
-        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;
             instructions?: string;
             estimatedTokens?: number;
-            dependsOn?: string[];
             initiativeId?: string;
+            scheduledFor?: string;
         }>;
         parentTaskId?: string;
         initiativeSuggestions?: Array<{
@@ -747,4 +785,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 };