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

package/README.md

@@ -15,7 +15,7 @@ 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_suggest_tasks                                           │
 │   deskfree_create_activity                                       │
 │   deskfree_update_activity                                       │
 │   deskfree_classify_task                                         │
@@ -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,21 +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;
 }
-/**
- * Response from the tasks.create bot endpoint.
- *
- * The backend mutation (`trpc.bot.tasks.create`) returns the Task object
- * directly (not wrapped in `{ task: ... }`).
- */
-type CreateTaskResponse = Task;
 interface CompleteTaskInput {
     taskId: string;
     outcome: 'done' | 'blocked';
+    summary?: string;
 }
 interface WorkspaceStateTask {
     taskId: string;
@@ -459,10 +472,28 @@ interface WorkspaceStateTask {
     status: 'bot' | 'human' | 'done';
     isWorking?: boolean;
     instructions?: string | null;
-    deliverable?: string | null;
+    fileId?: string | null;
+    fileName?: string | null;
     createdAt: string;
     updatedAt: string;
 }
+interface Initiative {
+    id: string;
+    title: string;
+    status: 'suggested' | 'active' | 'paused';
+    content: string;
+    contentVersion: number;
+    taskCount: number;
+    activeTaskCount: number;
+}
+interface WorkspaceFile {
+    fileId: string;
+    name: string;
+    description: string;
+    contentFormat: string;
+    version: number;
+    updatedAt: string;
+}
 interface WorkspaceState {
     tasks: WorkspaceStateTask[];
     recentlyDone: WorkspaceStateTask[];
@@ -471,7 +502,10 @@ interface WorkspaceState {
         taskId: string;
         taskNumber: number;
         title: string;
+        initiativeId?: string | null;
     }>;
+    initiatives: Initiative[];
+    files: WorkspaceFile[];
 }
 interface EvaluationTaskMessage {
     messageId: string;
@@ -487,6 +521,11 @@ interface ClaimEvaluationResponse {
     waysOfWorking: string | null;
     currentVersion: number;
     messages: EvaluationTaskMessage[];
+    initiative?: {
+        id: string;
+        title: string;
+        content: string;
+    } | null;
 }
 
 /** Enhanced error class for DeskFree API errors with user-friendly messages */
@@ -528,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;
@@ -542,10 +581,6 @@ declare class DeskFreeClient {
             contentType: string;
             size: number;
         }>;
-        suggestions?: Array<{
-            title: string;
-            instructions?: string;
-        }>;
     }): Promise<{
         messageId: string;
         content: string;
@@ -558,29 +593,39 @@ declare class DeskFreeClient {
     }): Promise<MessagesResponse>;
     /** Obtain a one-time WebSocket authentication ticket for real-time notifications. */
     getWsTicket(): Promise<WsTicketResponse>;
-    /** Create a new task, optionally with a recurring schedule. */
-    createTask(input: {
-        title: string;
-        instructions?: string;
-        isRecurring?: boolean;
-        recurringSchedule?: {
-            frequency: 'daily' | 'weekly' | 'biweekly' | 'monthly';
-            dayOfWeek?: number;
-            dayOfMonth?: number;
-            time: string;
-            timezone?: string;
-        };
-    }): Promise<CreateTaskResponse>;
     /** Claim a task so the bot can begin working on it. Returns enriched context. */
     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';
@@ -627,16 +672,24 @@ 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<{
+    /** Suggest tasks via the dedicated bot/tasks.suggest endpoint. */
+    suggestTasksDedicated(input: {
+        suggestions: Array<{
             title: string;
             instructions?: string;
+            estimatedTokens?: number;
+            initiativeId?: string;
+            scheduledFor?: string;
+        }>;
+        parentTaskId?: string;
+        initiativeSuggestions?: Array<{
+            title: string;
+            content: string;
+            taskRefs?: number[];
         }>;
-        taskId?: string;
     }): Promise<{
-        messageId: string;
-        content: string;
+        suggestionIds: string[];
+        initiativeSuggestionIds?: string[];
     }>;
     /**
      * Claim a pending evaluation for a task. Atomically sets isWorking=true where
@@ -647,17 +700,24 @@ declare class DeskFreeClient {
     }): Promise<ClaimEvaluationResponse | null>;
     /**
      * Submit the result of a ways-of-working evaluation.
-     * If hasChanges is true and updatedContent is provided, inserts a new version.
+     * Dual output: globalWoW (applies everywhere) and initiative (applies to the task's initiative).
      * Clears evaluationPending and isWorking on the task.
      */
     submitEvaluation(input: {
         taskId: string;
-        updatedContent?: string;
         reasoning: string;
-        hasChanges: boolean;
+        globalWoW: {
+            hasChanges: boolean;
+            updatedContent?: string;
+        };
+        initiative: {
+            hasChanges: boolean;
+            updatedContent?: string;
+        };
     }): Promise<{
         success: boolean;
-        version?: number;
+        globalVersion?: number;
+        initiativeVersion?: number;
     }>;
     /**
      * Lightweight health check that verifies connectivity and authentication.
@@ -725,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 CreateTaskResponse, type DeskFreeChannelConfig, DeskFreeClient, DeskFreeError, type EvaluationTaskMessage, type FinalizedMsgContext, 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 };