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

package/dist/index.js

@@ -3857,19 +3857,12 @@ var DeskFreeClient = class {
     return this.request("POST", "messages.update", input);
   }
   /**
-   * 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
    */
   async sendMessage(input) {
-    if (!input.content && !input.suggestions) {
-      throw new DeskFreeError(
-        "client",
-        "content",
-        "content or suggestions is required",
-        "Missing required parameter: provide content or suggestions."
-      );
-    }
+    this.requireNonEmpty(input.content, "content");
     return this.request("POST", "messages.send", input);
   }
   /** Fetch paginated message history for a conversation. */
@@ -3894,11 +3887,25 @@ var DeskFreeClient = class {
     this.requireNonEmpty(input.taskId, "taskId");
     return this.request("POST", "tasks.claim", input);
   }
-  /** Update the deliverable (markdown or HTML content) for a task. */
-  async updateDeliverable(input) {
+  /** Fetch a lightweight task summary by ID. Read-only, no side effects. */
+  async getTask(input) {
     this.requireNonEmpty(input.taskId, "taskId");
-    this.requireNonEmpty(input.deliverable, "deliverable");
-    return this.request("POST", "tasks.updateDeliverable", input);
+    return this.request("GET", "tasks.get", input);
+  }
+  /** Update the content of an existing file. */
+  async updateFile(input) {
+    this.requireNonEmpty(input.fileId, "fileId");
+    this.requireNonEmpty(input.content, "content");
+    return this.request("POST", "files.update", input);
+  }
+  /** Create a new persistent file. */
+  async createFile(input) {
+    this.requireNonEmpty(input.name, "name");
+    return this.request("POST", "files.create", input);
+  }
+  /** List all files for this bot (metadata only, no content). */
+  async listFiles() {
+    return this.request("GET", "files.list", {});
   }
   /** Send an agent status update to DeskFree. */
   async statusUpdate(input) {
@@ -3923,21 +3930,6 @@ var DeskFreeClient = class {
     this.requireNonEmpty(input.taskId, "taskId");
     return this.request("POST", "tasks.complete", input);
   }
-  /** Suggest new tasks for the human to review and approve (via messages.send with suggestions). */
-  async suggestTasks(input) {
-    if (!input.tasks || input.tasks.length === 0) {
-      throw new DeskFreeError(
-        "client",
-        "tasks",
-        "tasks array is required and cannot be empty",
-        "Missing required parameter: tasks. Please provide at least one task to suggest."
-      );
-    }
-    return this.sendMessage({
-      suggestions: input.tasks,
-      taskId: input.taskId
-    });
-  }
   /** Suggest tasks via the dedicated bot/tasks.suggest endpoint. */
   async suggestTasksDedicated(input) {
     if (!input.suggestions || input.suggestions.length === 0) {
@@ -4429,6 +4421,20 @@ async function fetchAndSaveMedia(attachment) {
     }
   }
 }
+var MAX_INSTRUCTIONS_LENGTH = 500;
+function truncateAtWord(text, maxLen) {
+  if (text.length <= maxLen) return text;
+  const truncated = text.slice(0, maxLen);
+  const lastSpace = truncated.lastIndexOf(" ");
+  return (lastSpace > 0 ? truncated.slice(0, lastSpace) : truncated) + "\u2026";
+}
+function buildBodyForAgent(task, content) {
+  let prefix = `[Task thread: "${task.title}" | status: ${task.status}]`;
+  if (task.instructions) {
+    prefix += "\n" + truncateAtWord(task.instructions, MAX_INSTRUCTIONS_LENGTH);
+  }
+  return prefix + "\n\n" + content;
+}
 async function deliverMessageToAgent(ctx, message, client) {
   const runtime = getDeskFreeRuntime();
   const log = ctx.log ?? runtime.logging.createLogger("deskfree:deliver");
@@ -4471,9 +4477,20 @@ async function deliverMessageToAgent(ctx, message, client) {
       );
     }
   }
+  let bodyForAgent;
+  if (message.taskId) {
+    try {
+      const task = await client.getTask({ taskId: message.taskId });
+      bodyForAgent = buildBodyForAgent(task, message.content);
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      log.warn(`Failed to fetch task context for ${message.taskId}: ${errMsg}`);
+    }
+  }
   const msgCtx = runtime.channel.reply.finalizeInboundContext({
     Body: message.content,
     RawBody: message.content,
+    ...bodyForAgent ? { BodyForAgent: bodyForAgent } : {},
     ChatType: "dm",
     Provider: "deskfree",
     Surface: "deskfree",
@@ -4585,6 +4602,7 @@ var wrapper_default = import_websocket.default;
 // src/gateway.ts
 var activeTaskId = null;
 var completedTaskId = null;
+var inboundThreadId = null;
 function setActiveTaskId(taskId) {
   if (taskId === null && activeTaskId !== null) {
     completedTaskId = activeTaskId;
@@ -4592,15 +4610,19 @@ function setActiveTaskId(taskId) {
   activeTaskId = taskId;
 }
 function getActiveTaskId() {
-  return activeTaskId ?? completedTaskId;
+  return activeTaskId ?? completedTaskId ?? inboundThreadId;
 }
 function clearCompletedTaskId() {
   completedTaskId = null;
 }
+function setInboundThreadId(taskId) {
+  inboundThreadId = taskId;
+}
 var PING_INTERVAL_MS = 5 * 60 * 1e3;
 var POLL_FALLBACK_INTERVAL_MS = 30 * 1e3;
 var WS_CONNECTION_TIMEOUT_MS = 30 * 1e3;
 var WS_PONG_TIMEOUT_MS = 10 * 1e3;
+var NOTIFY_DEBOUNCE_MS = 200;
 var BACKOFF_INITIAL_MS = 2e3;
 var BACKOFF_MAX_MS = 3e4;
 var BACKOFF_FACTOR = 1.8;
@@ -4824,6 +4846,7 @@ async function runWebSocketConnection(opts) {
     let pingInterval;
     let connectionTimer;
     let pongTimer;
+    let notifyDebounceTimer;
     let isConnected = false;
     const cleanup = () => {
       if (pingInterval !== void 0) {
@@ -4838,6 +4861,10 @@ async function runWebSocketConnection(opts) {
         clearTimeout(pongTimer);
         pongTimer = void 0;
       }
+      if (notifyDebounceTimer !== void 0) {
+        clearTimeout(notifyDebounceTimer);
+        notifyDebounceTimer = void 0;
+      }
     };
     connectionTimer = setTimeout(() => {
       if (!isConnected) {
@@ -4918,15 +4945,21 @@ async function runWebSocketConnection(opts) {
           return;
         }
         if (msg.action === "notify") {
-          enqueuePoll(
-            client,
-            ctx,
-            () => cursor,
-            (c) => {
-              cursor = c ?? cursor;
-            },
-            log
-          );
+          if (notifyDebounceTimer !== void 0) {
+            clearTimeout(notifyDebounceTimer);
+          }
+          notifyDebounceTimer = setTimeout(() => {
+            notifyDebounceTimer = void 0;
+            enqueuePoll(
+              client,
+              ctx,
+              () => cursor,
+              (c) => {
+                cursor = c ?? cursor;
+              },
+              log
+            );
+          }, NOTIFY_DEBOUNCE_MS);
         } else if (msg.action === "pong") {
           if (pongTimer !== void 0) {
             clearTimeout(pongTimer);
@@ -5123,6 +5156,7 @@ async function pollAndDeliver(client, ctx, cursor, log, account) {
         continue;
       }
       clearCompletedTaskId();
+      setInboundThreadId(message.taskId ?? null);
       await deliverMessageToAgent(ctx, message, client);
       deliveredMessageIds.add(message.messageId);
       deliveredCount++;
@@ -7767,66 +7801,72 @@ var ORCHESTRATOR_TOOLS = {
   },
   START_TASK: {
     name: "deskfree_start_task",
-    description: "Claim a bot task (isWorking=false) and start working. Returns full context (instructions, deliverable, message history).",
+    description: "Claim a bot task (isWorking=false) and start working. Returns full context (instructions, message history, and fileContext if the task has a linked file \u2014 use the file content as working context).",
     parameters: Type.Object({
       taskId: Type.String({ description: "Task UUID to claim" })
     })
   },
-  UPDATE_DELIVERABLE: {
-    name: "deskfree_update_deliverable",
-    description: 'Update task deliverable. Build incrementally as you work. Use format="html" when delivering rich web content (reports, dashboards, interactive pages); use format="markdown" (default) for everything else.',
+  UPDATE_FILE: {
+    name: "deskfree_update_file",
+    description: `Update a file's content. Use this to save work to a persistent file linked to your task. Call incrementally as you build content. Use format="html" for rich web content; use format="markdown" (default) for everything else.`,
     parameters: Type.Object({
-      taskId: Type.String({ description: "Task UUID" }),
-      deliverable: Type.String({
-        description: "Deliverable content (markdown or HTML depending on format)"
+      fileId: Type.String({ description: "File ID to update" }),
+      content: Type.String({
+        description: "Full file content (replaces previous)"
       }),
-      format: Type.Optional(
+      contentFormat: Type.Optional(
         Type.Union([Type.Literal("markdown"), Type.Literal("html")], {
-          description: '"markdown" (default) for text/documents, "html" for rich web content. HTML is rendered in a sandboxed iframe.'
+          description: '"markdown" (default) for text/documents, "html" for rich web content.'
+        })
+      )
+    })
+  },
+  CREATE_FILE: {
+    name: "deskfree_create_file",
+    description: "Create a new persistent file. Use when your task produces a document that should persist beyond the task lifecycle (reports, specs, runbooks, etc.).",
+    parameters: Type.Object({
+      name: Type.String({ description: "File name (max 200 chars)" }),
+      description: Type.Optional(
+        Type.String({
+          description: "Brief description of the file's purpose (max 2000 chars)"
+        })
+      ),
+      content: Type.Optional(
+        Type.String({ description: "Initial file content" })
+      ),
+      contentFormat: Type.Optional(
+        Type.Union([Type.Literal("markdown"), Type.Literal("html")], {
+          description: '"markdown" (default) or "html"'
         })
       )
     })
   },
   COMPLETE_TASK: {
     name: "deskfree_complete_task",
-    description: 'Finish a task. Outcome "done" = work complete for review. Outcome "blocked" = need human input. Both move to human.',
+    description: 'Finish a task. Outcome "done" = work complete (summary required). Outcome "blocked" = need human input. Both move to human.',
     parameters: Type.Object({
       taskId: Type.String({ description: "Task UUID" }),
       outcome: Type.Union([Type.Literal("done"), Type.Literal("blocked")], {
         description: '"done" = work complete, "blocked" = need human input'
-      })
+      }),
+      summary: Type.Optional(
+        Type.String({
+          description: 'Brief summary of what was accomplished (required for outcome "done", max 2000 chars)'
+        })
+      )
     })
   },
   SEND_MESSAGE: {
     name: "deskfree_send_message",
-    description: "Send a message in the task thread (progress update, question, status report). Can also suggest follow-up tasks for human review by providing the suggestions parameter instead of content.",
+    description: "Send a message in the task thread (progress update, question, status report).",
     parameters: Type.Object({
-      content: Type.Optional(
-        Type.String({
-          description: "Message content. Required unless suggestions is provided."
-        })
-      ),
+      content: Type.String({
+        description: "Message content."
+      }),
       taskId: Type.Optional(
         Type.String({
           description: "Task UUID (optional if context provides it)"
         })
-      ),
-      suggestions: Type.Optional(
-        Type.Array(
-          Type.Object({
-            title: Type.String({ description: "Task title (max 200 chars)" }),
-            instructions: Type.Optional(
-              Type.String({
-                description: "Detailed instructions for the suggested task"
-              })
-            )
-          }),
-          {
-            description: "Suggest tasks for human review (1-10). The human will see approve/reject buttons for each. Provide this instead of content.",
-            minItems: 1,
-            maxItems: 10
-          }
-        )
       )
     })
   },
@@ -7849,15 +7889,35 @@ var ORCHESTRATOR_TOOLS = {
               description: "Estimated token cost \u2014 consider files to read, reasoning, output"
             })
           ),
-          dependsOn: Type.Optional(
-            Type.Array(Type.String(), {
-              description: "Task IDs this suggestion depends on (blocks claiming until those are done)"
-            })
-          ),
           initiativeId: Type.Optional(
             Type.String({
               description: "Link to existing initiative ID \u2014 set when this task belongs to an active initiative"
             })
+          ),
+          scheduledFor: Type.Optional(
+            Type.String({
+              description: "ISO-8601 date for when this task should become available. Use for future-dated or recurring work."
+            })
+          ),
+          fileId: Type.Optional(
+            Type.String({
+              description: "Link to an existing file ID \u2014 the bot will receive the file content when claiming this task"
+            })
+          ),
+          newFile: Type.Optional(
+            Type.Object(
+              {
+                name: Type.String({ description: "File name (max 200 chars)" }),
+                description: Type.Optional(
+                  Type.String({
+                    description: "Brief description of the file's purpose"
+                  })
+                )
+              },
+              {
+                description: "Create a new file and link it to this task \u2014 use when the task will produce a persistent document"
+              }
+            )
           )
         }),
         {
@@ -7889,7 +7949,7 @@ var ORCHESTRATOR_TOOLS = {
           {
             description: 'Propose new initiatives (optional). Created with "suggested" status \u2014 human approves or rejects independently.',
             minItems: 1,
-            maxItems: 10
+            maxItems: 5
           }
         )
       )
@@ -7944,9 +8004,12 @@ var ORCHESTRATOR_TOOLS = {
   }
 };
 var WORKER_TOOLS = {
-  UPDATE_DELIVERABLE: ORCHESTRATOR_TOOLS.UPDATE_DELIVERABLE,
+  UPDATE_FILE: ORCHESTRATOR_TOOLS.UPDATE_FILE,
+  CREATE_FILE: ORCHESTRATOR_TOOLS.CREATE_FILE,
   COMPLETE_TASK: ORCHESTRATOR_TOOLS.COMPLETE_TASK,
   SEND_MESSAGE: ORCHESTRATOR_TOOLS.SEND_MESSAGE,
+  SUGGEST_TASKS: ORCHESTRATOR_TOOLS.SUGGEST_TASKS,
+  CLAIM_EVALUATION: ORCHESTRATOR_TOOLS.CLAIM_EVALUATION,
   SUBMIT_EVALUATION: ORCHESTRATOR_TOOLS.SUBMIT_EVALUATION
 };
 var CHANNEL_META = {
@@ -8506,20 +8569,20 @@ var deskFreePlugin = {
 // src/context.ts
 var DESKFREE_AGENT_DIRECTIVE = `## DeskFree \u2014 The Work Loop
 Always read the deskfree skill (SKILL.md) at startup. Follow the suggest-first work loop:
-1. **Check state** \u2192 \`deskfree_state\` \u2014 see what needs attention, read ways of working.
-2. **Suggest tasks** \u2192 \`deskfree_suggest_tasks\` \u2014 ALL work requires human-approved tasks first.
-3. **Claim a task** \u2192 \`deskfree_start_task\` \u2014 read instructions + parent context carefully.
-4. **Do the work** \u2192 \`deskfree_update_deliverable\` incrementally from the start.
+1. **Check state** \u2192 \`deskfree_state\` \u2014 see what needs attention, read ways of working, check files.
+2. **Suggest tasks** \u2192 \`deskfree_suggest_tasks\` \u2014 ALL work requires human-approved tasks first. Use \`newFile\` to pre-create a file for tasks that will produce persistent documents.
+3. **Claim a task** \u2192 \`deskfree_start_task\` \u2014 read instructions + parent context. If task has a linked file, its content is in \`fileContext\`.
+4. **Do the work** \u2192 use \`deskfree_update_file\` to save work to linked files incrementally. Create new files with \`deskfree_create_file\` when needed.
 5. **Suggest follow-ups** \u2192 if work reveals more to do, suggest them (strongest when you have full context).
-6. **Complete** \u2192 \`deskfree_complete_task\` \u2014 deliverable required for "done".
+6. **Complete** \u2192 \`deskfree_complete_task\` \u2014 summary required for outcome "done".
 7. **Evaluate** \u2192 check \`pendingEvaluations\` and update ways of working.
 
 Key principles:
-- You're building a chain. Your instructions become someone else's brief. Your deliverable becomes someone else's context.
+- You're building a chain. Your instructions become someone else's brief. Your file output becomes someone else's context.
 - Write instructions as if briefing a contractor who has never seen the codebase.
-- MUST update deliverable before completing with outcome "done".
+- MUST provide summary when completing with outcome "done".
 - Estimate token cost per suggestion \u2014 consider files to read, reasoning, output.
-- Sub-agents get 4 tools: update_deliverable, complete_task, send_message, submit_evaluation.`;
+- Sub-agents get 7 tools: update_file, create_file, complete_task, send_message, suggest_tasks, claim_evaluation, submit_evaluation.`;
 function getDeskFreeContext() {
   return `${DESKFREE_AGENT_DIRECTIVE}
 
@@ -8558,15 +8621,7 @@ function formatTaskResponse(task, summary, nextActions) {
     content: [
       {
         type: "text",
-        text: JSON.stringify(
-          {
-            summary,
-            nextActions,
-            task
-          },
-          null,
-          2
-        )
+        text: JSON.stringify({ summary, nextActions, task }, null, 2)
       }
     ]
   };
@@ -8577,11 +8632,7 @@ function formatConfirmation(summary, nextActions, data) {
       {
         type: "text",
         text: JSON.stringify(
-          {
-            summary,
-            nextActions,
-            ...data ? { data } : {}
-          },
+          { summary, nextActions, ...data ? { data } : {} },
           null,
           2
         )
@@ -8642,14 +8693,7 @@ function errorResult(err) {
     content: [
       {
         type: "text",
-        text: JSON.stringify(
-          {
-            error: true,
-            message: rawMessage
-          },
-          null,
-          2
-        )
+        text: JSON.stringify({ error: true, message: rawMessage }, null, 2)
       }
     ],
     isError: true
@@ -8666,9 +8710,7 @@ function validateStringParam(params, key, required) {
   }
   const value = params[key];
   if (value == null) {
-    if (required) {
-      throw new Error(`Required parameter '${key}' is missing`);
-    }
+    if (required) throw new Error(`Required parameter '${key}' is missing`);
     return void 0;
   }
   if (typeof value !== "string") {
@@ -8690,9 +8732,7 @@ function validateEnumParam(params, key, allowedValues, required) {
   }
   const value = params[key];
   if (value == null) {
-    if (required) {
-      throw new Error(`Required parameter '${key}' is missing`);
-    }
+    if (required) throw new Error(`Required parameter '${key}' is missing`);
     return void 0;
   }
   if (typeof value !== "string") {
@@ -8708,6 +8748,298 @@ function validateEnumParam(params, key, allowedValues, required) {
   }
   return value;
 }
+function parseSuggestions(raw) {
+  if (!Array.isArray(raw) || raw.length === 0) {
+    throw new Error('Parameter "suggestions" must be a non-empty array');
+  }
+  return raw.map((s, i) => {
+    if (typeof s !== "object" || s === null) {
+      throw new Error(`suggestions[${i}] must be an object`);
+    }
+    const item = s;
+    const title = item["title"];
+    if (typeof title !== "string" || title.trim() === "") {
+      throw new Error(`suggestions[${i}].title must be a non-empty string`);
+    }
+    let newFile;
+    if (item["newFile"] && typeof item["newFile"] === "object") {
+      const nf = item["newFile"];
+      if (typeof nf["name"] === "string" && nf["name"].trim()) {
+        newFile = {
+          name: nf["name"].trim(),
+          description: typeof nf["description"] === "string" ? nf["description"] : void 0
+        };
+      }
+    }
+    return {
+      title: title.trim(),
+      instructions: typeof item["instructions"] === "string" ? item["instructions"] : void 0,
+      estimatedTokens: typeof item["estimatedTokens"] === "number" ? item["estimatedTokens"] : void 0,
+      initiativeId: typeof item["initiativeId"] === "string" ? item["initiativeId"] : void 0,
+      scheduledFor: typeof item["scheduledFor"] === "string" ? item["scheduledFor"] : void 0,
+      fileId: typeof item["fileId"] === "string" ? item["fileId"] : void 0,
+      newFile
+    };
+  });
+}
+function parseInitiativeSuggestions(raw) {
+  if (!Array.isArray(raw) || raw.length === 0) return void 0;
+  return raw.map((s, i) => {
+    if (typeof s !== "object" || s === null) {
+      throw new Error(`initiativeSuggestions[${i}] must be an object`);
+    }
+    const item = s;
+    const title = item["title"];
+    if (typeof title !== "string" || title.trim() === "") {
+      throw new Error(
+        `initiativeSuggestions[${i}].title must be a non-empty string`
+      );
+    }
+    const content = item["content"];
+    if (typeof content !== "string") {
+      throw new Error(`initiativeSuggestions[${i}].content must be a string`);
+    }
+    return {
+      title: title.trim(),
+      content,
+      taskRefs: Array.isArray(item["taskRefs"]) ? item["taskRefs"] : void 0
+    };
+  });
+}
+function parseEvaluationSection(raw, name) {
+  if (typeof raw !== "object" || raw === null) {
+    throw new Error(`Parameter "${name}" must be an object`);
+  }
+  const obj = raw;
+  if (typeof obj["hasChanges"] !== "boolean") {
+    throw new Error(`Parameter "${name}.hasChanges" must be a boolean`);
+  }
+  return {
+    hasChanges: obj["hasChanges"],
+    updatedContent: typeof obj["updatedContent"] === "string" ? obj["updatedContent"] : void 0
+  };
+}
+function makeUpdateFileHandler(client) {
+  return async (_id, params) => {
+    try {
+      const fileId = validateStringParam(params, "fileId", true);
+      const content = validateStringParam(params, "content", true);
+      const contentFormat = validateEnumParam(
+        params,
+        "contentFormat",
+        ["markdown", "html"],
+        false
+      );
+      await client.updateFile({ fileId, content, contentFormat });
+      return formatConfirmation(`Updated file ${fileId}`, [
+        "File content has been saved",
+        "Complete the task with deskfree_complete_task when ready"
+      ]);
+    } catch (err) {
+      return errorResult(err);
+    }
+  };
+}
+function makeCreateFileHandler(client) {
+  return async (_id, params) => {
+    try {
+      const name = validateStringParam(params, "name", true);
+      const description = validateStringParam(params, "description", false);
+      const content = validateStringParam(params, "content", false);
+      const contentFormat = validateEnumParam(
+        params,
+        "contentFormat",
+        ["markdown", "html"],
+        false
+      );
+      const result = await client.createFile({
+        name,
+        description,
+        content,
+        contentFormat
+      });
+      return formatConfirmation(
+        `Created file "${name}"`,
+        [
+          `File ID: ${result.fileId}`,
+          "Use deskfree_update_file to update its content"
+        ],
+        result
+      );
+    } catch (err) {
+      return errorResult(err);
+    }
+  };
+}
+function makeCompleteTaskHandler(client) {
+  return async (_id, params) => {
+    try {
+      const taskId = validateStringParam(params, "taskId", true);
+      const outcome = validateEnumParam(
+        params,
+        "outcome",
+        ["done", "blocked"],
+        true
+      );
+      const summary = validateStringParam(params, "summary", false);
+      const result = await client.completeTask({ taskId, outcome, summary });
+      setActiveTaskId(null);
+      const summaryVerb = outcome === "done" ? "completed" : "blocked";
+      const icon = outcome === "done" ? "\u2705" : "\u{1F6AB}";
+      await client.sendMessage({
+        content: `${icon} Task ${summaryVerb}: "${result.title}"`
+      }).catch(() => {
+      });
+      return formatTaskResponse(
+        result,
+        `Task "${result.title}" marked as ${summaryVerb} \u2014 waiting for human`,
+        [
+          outcome === "done" ? "Human will review your work summary" : "Human will review the blocker and provide guidance",
+          "Use deskfree_state to check for other tasks"
+        ]
+      );
+    } catch (err) {
+      return errorResult(err);
+    }
+  };
+}
+function makeSendMessageHandler(client) {
+  return async (_id, params) => {
+    try {
+      const content = validateStringParam(params, "content", true);
+      const taskId = validateStringParam(params, "taskId", false);
+      await client.sendMessage({ content, taskId });
+      return formatConfirmation(
+        `Message sent${taskId ? ` to task ${taskId}` : ""}`,
+        [
+          "Message delivered to the human",
+          taskId ? "Continue working on the task or wait for response" : "Check for response with task messages"
+        ]
+      );
+    } catch (err) {
+      return errorResult(err);
+    }
+  };
+}
+function makeSuggestTasksHandler(client) {
+  return async (_id, params) => {
+    try {
+      const suggestions = parseSuggestions(params?.suggestions);
+      const parentTaskId = validateStringParam(params, "parentTaskId", false);
+      const initiativeSuggestions = parseInitiativeSuggestions(
+        params?.initiativeSuggestions
+      );
+      const result = await client.suggestTasksDedicated({
+        suggestions,
+        parentTaskId,
+        initiativeSuggestions
+      });
+      const initiativeCount = initiativeSuggestions?.length ?? 0;
+      const summaryParts = [
+        `Suggested ${suggestions.length} task${suggestions.length === 1 ? "" : "s"} for human approval`,
+        ...initiativeCount > 0 ? [
+          `and ${initiativeCount} initiative${initiativeCount === 1 ? "" : "s"}`
+        ] : []
+      ];
+      return formatConfirmation(
+        summaryParts.join(" "),
+        [
+          'Tasks created with "suggested" status \u2014 human will approve or reject each',
+          ...initiativeCount > 0 ? [
+            "Initiative suggestions created \u2014 human will approve or reject independently"
+          ] : [],
+          "Use deskfree_state to check for approved tasks"
+        ],
+        result
+      );
+    } catch (err) {
+      return errorResult(err);
+    }
+  };
+}
+function makeClaimEvaluationHandler(client) {
+  return async (_id, params) => {
+    try {
+      const taskId = validateStringParam(params, "taskId", true);
+      const result = await client.claimEvaluation({ taskId });
+      if (!result) {
+        return formatConfirmation(
+          "Evaluation already claimed by another process",
+          ["Use deskfree_state to check for other pending evaluations"]
+        );
+      }
+      const state = await client.getState().catch(() => null);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                summary: `Claimed evaluation for task "${result.task.title}"`,
+                nextActions: [
+                  "Review the task messages, current global ways of working, and initiative content (if present)",
+                  "Decide what to update: globalWoW (universal patterns), initiative (area-specific learnings), both, or neither",
+                  "Call deskfree_submit_evaluation with your analysis"
+                ],
+                task: result.task,
+                waysOfWorking: result.waysOfWorking,
+                currentVersion: result.currentVersion,
+                messages: result.messages,
+                ...result.initiative ? { initiative: result.initiative } : {},
+                ...state ? { workspaceState: state } : {}
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    } catch (err) {
+      return errorResult(err);
+    }
+  };
+}
+function makeSubmitEvaluationHandler(client, followUpHint) {
+  return async (_id, params) => {
+    try {
+      const taskId = validateStringParam(params, "taskId", true);
+      const reasoning = validateStringParam(params, "reasoning", true);
+      const globalWoW = parseEvaluationSection(params?.globalWoW, "globalWoW");
+      const initiative = parseEvaluationSection(
+        params?.initiative,
+        "initiative"
+      );
+      const result = await client.submitEvaluation({
+        taskId,
+        reasoning,
+        globalWoW,
+        initiative
+      });
+      const parts = [];
+      if (globalWoW.hasChanges)
+        parts.push(`global WoW \u2192 v${result.globalVersion}`);
+      if (initiative.hasChanges && result.initiativeVersion !== void 0) {
+        parts.push(`initiative \u2192 v${result.initiativeVersion}`);
+      }
+      const messageContent = parts.length > 0 ? `\u{1F4DD} Updated ${parts.join(", ")}: ${reasoning}` : `\u{1F4DD} No updates to ways of working: ${reasoning}`;
+      await client.sendMessage({ content: messageContent, taskId }).catch(() => {
+      });
+      const summaryParts = [];
+      if (globalWoW.hasChanges)
+        summaryParts.push(`global WoW v${result.globalVersion}`);
+      if (initiative.hasChanges && result.initiativeVersion !== void 0) {
+        summaryParts.push(`initiative v${result.initiativeVersion}`);
+      }
+      return formatConfirmation(
+        summaryParts.length > 0 ? `Evaluation complete \u2014 updated ${summaryParts.join(", ")}` : "Evaluation complete \u2014 no changes needed",
+        [followUpHint],
+        result
+      );
+    } catch (err) {
+      return errorResult(err);
+    }
+  };
+}
 function createOrchestratorTools(api) {
   const account = resolveAccountFromConfig(api);
   if (!account) return null;
@@ -8742,8 +9074,10 @@ function createOrchestratorTools(api) {
                     summary: `Claimed task "${result.title}" \u2014 full context loaded`,
                     nextActions: [
                       "Read the instructions and message history carefully",
-                      "Update deliverable incrementally with deskfree_update_deliverable",
-                      "Complete with deskfree_complete_task when done"
+                      ...result.fileContext ? [
+                        `Task has a linked file "${result.fileContext.name}" (ID: ${result.fileContext.fileId}) \u2014 use deskfree_update_file to save your work to it`
+                      ] : [],
+                      "Complete with deskfree_complete_task when done (summary required)"
                     ],
                     task: result
                   },
@@ -8759,304 +9093,35 @@ function createOrchestratorTools(api) {
       }
     },
     {
-      ...ORCHESTRATOR_TOOLS.UPDATE_DELIVERABLE,
-      async execute(_id, params) {
-        try {
-          const taskId = validateStringParam(params, "taskId", true);
-          const deliverable = validateStringParam(params, "deliverable", true);
-          const format = validateEnumParam(
-            params,
-            "format",
-            ["markdown", "html"],
-            false
-          );
-          await client.updateDeliverable({ taskId, deliverable, format });
-          return formatConfirmation(`Updated deliverable for task ${taskId}`, [
-            "Deliverable has been saved",
-            "Complete with deskfree_complete_task when ready"
-          ]);
-        } catch (err) {
-          return errorResult(err);
-        }
-      }
+      ...ORCHESTRATOR_TOOLS.UPDATE_FILE,
+      execute: makeUpdateFileHandler(client)
+    },
+    {
+      ...ORCHESTRATOR_TOOLS.CREATE_FILE,
+      execute: makeCreateFileHandler(client)
     },
     {
       ...ORCHESTRATOR_TOOLS.COMPLETE_TASK,
-      async execute(_id, params) {
-        try {
-          const taskId = validateStringParam(params, "taskId", true);
-          const outcome = validateEnumParam(
-            params,
-            "outcome",
-            ["done", "blocked"],
-            true
-          );
-          const result = await client.completeTask({ taskId, outcome });
-          setActiveTaskId(null);
-          const summaryVerb = outcome === "done" ? "completed" : "blocked";
-          const icon = outcome === "done" ? "\u2705" : "\u{1F6AB}";
-          await client.sendMessage({
-            content: `${icon} Task ${summaryVerb}: "${result.title}"`
-          }).catch(() => {
-          });
-          return formatTaskResponse(
-            result,
-            `Task "${result.title}" marked as ${summaryVerb} \u2014 waiting for human`,
-            [
-              outcome === "done" ? "Human will review the deliverable" : "Human will review the blocker and provide guidance",
-              "Use deskfree_state to check for other tasks"
-            ]
-          );
-        } catch (err) {
-          return errorResult(err);
-        }
-      }
+      execute: makeCompleteTaskHandler(client)
     },
     {
       ...ORCHESTRATOR_TOOLS.SEND_MESSAGE,
-      async execute(_id, params) {
-        try {
-          const content = validateStringParam(params, "content", false);
-          const taskId = validateStringParam(params, "taskId", false);
-          const rawSuggestions = params?.suggestions;
-          let suggestions;
-          if (Array.isArray(rawSuggestions) && rawSuggestions.length > 0) {
-            suggestions = rawSuggestions.map((t, i) => {
-              if (typeof t !== "object" || t === null) {
-                throw new Error(`suggestions[${i}] must be an object`);
-              }
-              const item = t;
-              const title = item["title"];
-              if (typeof title !== "string" || title.trim() === "") {
-                throw new Error(
-                  `suggestions[${i}].title must be a non-empty string`
-                );
-              }
-              const instructions = item["instructions"];
-              return {
-                title: title.trim(),
-                instructions: typeof instructions === "string" ? instructions : void 0
-              };
-            });
-          }
-          if (!content && !suggestions) {
-            throw new Error(
-              'Either "content" or "suggestions" parameter is required'
-            );
-          }
-          if (suggestions) {
-            await client.sendMessage({ suggestions, taskId });
-            return formatConfirmation(
-              `Suggested ${suggestions.length} task${suggestions.length === 1 ? "" : "s"} for human review`,
-              [
-                "The human will see approve/reject buttons for each suggestion",
-                "Continue working on the current task"
-              ]
-            );
-          }
-          await client.sendMessage({ content, taskId });
-          return formatConfirmation(
-            `Message sent${taskId ? ` to task ${taskId}` : ""}`,
-            [
-              "Message delivered to the human",
-              taskId ? "Continue working on the task or wait for response" : "Check for response with task messages"
-            ]
-          );
-        } catch (err) {
-          return errorResult(err);
-        }
-      }
+      execute: makeSendMessageHandler(client)
     },
     {
       ...ORCHESTRATOR_TOOLS.SUGGEST_TASKS,
-      async execute(_id, params) {
-        try {
-          const rawSuggestions = params?.suggestions;
-          if (!Array.isArray(rawSuggestions) || rawSuggestions.length === 0) {
-            throw new Error(
-              'Parameter "suggestions" must be a non-empty array'
-            );
-          }
-          const suggestions = rawSuggestions.map((s, i) => {
-            if (typeof s !== "object" || s === null) {
-              throw new Error(`suggestions[${i}] must be an object`);
-            }
-            const item = s;
-            const title = item["title"];
-            if (typeof title !== "string" || title.trim() === "") {
-              throw new Error(
-                `suggestions[${i}].title must be a non-empty string`
-              );
-            }
-            return {
-              title: title.trim(),
-              instructions: typeof item["instructions"] === "string" ? item["instructions"] : void 0,
-              estimatedTokens: typeof item["estimatedTokens"] === "number" ? item["estimatedTokens"] : void 0,
-              dependsOn: Array.isArray(item["dependsOn"]) ? item["dependsOn"] : void 0,
-              initiativeId: typeof item["initiativeId"] === "string" ? item["initiativeId"] : void 0
-            };
-          });
-          const parentTaskId = validateStringParam(
-            params,
-            "parentTaskId",
-            false
-          );
-          const rawInitiativeSuggestions = params?.initiativeSuggestions;
-          let initiativeSuggestions;
-          if (Array.isArray(rawInitiativeSuggestions) && rawInitiativeSuggestions.length > 0) {
-            initiativeSuggestions = rawInitiativeSuggestions.map(
-              (s, i) => {
-                if (typeof s !== "object" || s === null) {
-                  throw new Error(`initiativeSuggestions[${i}] must be an object`);
-                }
-                const item = s;
-                const title = item["title"];
-                if (typeof title !== "string" || title.trim() === "") {
-                  throw new Error(
-                    `initiativeSuggestions[${i}].title must be a non-empty string`
-                  );
-                }
-                const content = item["content"];
-                if (typeof content !== "string") {
-                  throw new Error(
-                    `initiativeSuggestions[${i}].content must be a string`
-                  );
-                }
-                return {
-                  title: title.trim(),
-                  content,
-                  taskRefs: Array.isArray(item["taskRefs"]) ? item["taskRefs"] : void 0
-                };
-              }
-            );
-          }
-          const result = await client.suggestTasksDedicated({
-            suggestions,
-            parentTaskId,
-            initiativeSuggestions
-          });
-          const initiativeCount = initiativeSuggestions?.length ?? 0;
-          const summaryParts = [
-            `Suggested ${suggestions.length} task${suggestions.length === 1 ? "" : "s"} for human approval`,
-            ...initiativeCount > 0 ? [
-              `and ${initiativeCount} initiative${initiativeCount === 1 ? "" : "s"}`
-            ] : []
-          ];
-          return formatConfirmation(
-            summaryParts.join(" "),
-            [
-              'Tasks created with "suggested" status \u2014 human will approve or reject each',
-              ...initiativeCount > 0 ? ["Initiative suggestions created \u2014 human will approve or reject independently"] : [],
-              "Use deskfree_state to check for approved tasks"
-            ],
-            result
-          );
-        } catch (err) {
-          return errorResult(err);
-        }
-      }
+      execute: makeSuggestTasksHandler(client)
     },
     {
       ...ORCHESTRATOR_TOOLS.CLAIM_EVALUATION,
-      async execute(_id, params) {
-        try {
-          const taskId = validateStringParam(params, "taskId", true);
-          const result = await client.claimEvaluation({ taskId });
-          if (!result) {
-            return formatConfirmation(
-              "Evaluation already claimed by another process",
-              ["Use deskfree_state to check for other pending evaluations"]
-            );
-          }
-          return {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify(
-                  {
-                    summary: `Claimed evaluation for task "${result.task.title}"`,
-                    nextActions: [
-                      "Review the task messages, current global ways of working, and initiative content (if present)",
-                      "Decide what to update: globalWoW (universal patterns), initiative (area-specific learnings), both, or neither",
-                      "Call deskfree_submit_evaluation with your analysis"
-                    ],
-                    task: result.task,
-                    waysOfWorking: result.waysOfWorking,
-                    currentVersion: result.currentVersion,
-                    messages: result.messages,
-                    ...result.initiative ? { initiative: result.initiative } : {}
-                  },
-                  null,
-                  2
-                )
-              }
-            ]
-          };
-        } catch (err) {
-          return errorResult(err);
-        }
-      }
+      execute: makeClaimEvaluationHandler(client)
     },
     {
       ...ORCHESTRATOR_TOOLS.SUBMIT_EVALUATION,
-      async execute(_id, params) {
-        try {
-          const taskId = validateStringParam(params, "taskId", true);
-          const reasoning = validateStringParam(params, "reasoning", true);
-          const rawGlobalWoW = params?.globalWoW;
-          if (typeof rawGlobalWoW !== "object" || rawGlobalWoW === null) {
-            throw new Error('Parameter "globalWoW" must be an object');
-          }
-          const globalWoWObj = rawGlobalWoW;
-          if (typeof globalWoWObj["hasChanges"] !== "boolean") {
-            throw new Error('Parameter "globalWoW.hasChanges" must be a boolean');
-          }
-          const globalWoW = {
-            hasChanges: globalWoWObj["hasChanges"],
-            updatedContent: typeof globalWoWObj["updatedContent"] === "string" ? globalWoWObj["updatedContent"] : void 0
-          };
-          const rawInitiative = params?.initiative;
-          if (typeof rawInitiative !== "object" || rawInitiative === null) {
-            throw new Error('Parameter "initiative" must be an object');
-          }
-          const initiativeObj = rawInitiative;
-          if (typeof initiativeObj["hasChanges"] !== "boolean") {
-            throw new Error('Parameter "initiative.hasChanges" must be a boolean');
-          }
-          const initiative = {
-            hasChanges: initiativeObj["hasChanges"],
-            updatedContent: typeof initiativeObj["updatedContent"] === "string" ? initiativeObj["updatedContent"] : void 0
-          };
-          const result = await client.submitEvaluation({
-            taskId,
-            reasoning,
-            globalWoW,
-            initiative
-          });
-          const parts = [];
-          if (globalWoW.hasChanges) {
-            parts.push(`global WoW \u2192 v${result.globalVersion}`);
-          }
-          if (initiative.hasChanges && result.initiativeVersion !== void 0) {
-            parts.push(`initiative \u2192 v${result.initiativeVersion}`);
-          }
-          const messageContent = parts.length > 0 ? `\u{1F4DD} Updated ${parts.join(", ")}: ${reasoning}` : `\u{1F4DD} No updates to ways of working: ${reasoning}`;
-          await client.sendMessage({ content: messageContent, taskId }).catch(() => {
-          });
-          const summaryParts = [];
-          if (globalWoW.hasChanges) summaryParts.push(`global WoW v${result.globalVersion}`);
-          if (initiative.hasChanges && result.initiativeVersion !== void 0) {
-            summaryParts.push(`initiative v${result.initiativeVersion}`);
-          }
-          return formatConfirmation(
-            summaryParts.length > 0 ? `Evaluation complete \u2014 updated ${summaryParts.join(", ")}` : "Evaluation complete \u2014 no changes needed",
-            ["Use deskfree_state to check for other pending evaluations"],
-            result
-          );
-        } catch (err) {
-          return errorResult(err);
-        }
-      }
+      execute: makeSubmitEvaluationHandler(
+        client,
+        "Use deskfree_state to check for other pending evaluations"
+      )
     }
   ];
 }