@questionbase/deskfree 0.3.0-alpha.20 → 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. */
@@ -3889,21 +3882,30 @@ var DeskFreeClient = class {
     return this.request("POST", "messages.wsTicket", {});
   }
   // ── Tasks ─────────────────────────────────────────────────
-  /** Create a new task, optionally with a recurring schedule. */
-  async createTask(input) {
-    this.requireNonEmpty(input.title, "title");
-    return this.request("POST", "tasks.create", input);
-  }
   /** Claim a task so the bot can begin working on it. Returns enriched context. */
   async claimTask(input) {
     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) {
@@ -3928,20 +3930,17 @@ 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) {
+  /** Suggest tasks via the dedicated bot/tasks.suggest endpoint. */
+  async suggestTasksDedicated(input) {
+    if (!input.suggestions || input.suggestions.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."
+        "suggestions",
+        "suggestions array is required and cannot be empty",
+        "Missing required parameter: suggestions."
       );
     }
-    return this.sendMessage({
-      suggestions: input.tasks,
-      taskId: input.taskId
-    });
+    return this.request("POST", "tasks.suggest", input);
   }
   /**
    * Claim a pending evaluation for a task. Atomically sets isWorking=true where
@@ -3953,7 +3952,7 @@ var DeskFreeClient = class {
   }
   /**
    * 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.
    */
   async submitEvaluation(input) {
@@ -4422,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");
@@ -4464,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",
@@ -4578,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;
@@ -4585,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;
@@ -4817,6 +4846,7 @@ async function runWebSocketConnection(opts) {
     let pingInterval;
     let connectionTimer;
     let pongTimer;
+    let notifyDebounceTimer;
     let isConnected = false;
     const cleanup = () => {
       if (pingInterval !== void 0) {
@@ -4831,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) {
@@ -4911,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);
@@ -5116,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++;
@@ -7755,79 +7796,160 @@ var Type = type_exports2;
 var ORCHESTRATOR_TOOLS = {
   STATE: {
     name: "deskfree_state",
-    description: "Get full workspace state \u2014 all tasks, recently done tasks. Use to assess what needs attention.",
+    description: "Get full workspace state \u2014 all tasks, recently done tasks, active initiatives. Use to assess what needs attention.",
     parameters: Type.Object({})
   },
-  CREATE_TASK: {
-    name: "deskfree_create_task",
-    description: "Create a new task (starts as bot).",
-    parameters: Type.Object({
-      title: Type.String({ description: "Task title (max 200 chars)" }),
-      instructions: Type.Optional(
-        Type.String({ description: "Detailed instructions for the task" })
-      )
-    })
-  },
   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(
+      content: Type.String({
+        description: "Message content."
+      }),
+      taskId: Type.Optional(
         Type.String({
-          description: "Message content. Required unless suggestions is provided."
+          description: "Task UUID (optional if context provides it)"
         })
+      )
+    })
+  },
+  SUGGEST_TASKS: {
+    name: "deskfree_suggest_tasks",
+    description: 'Suggest tasks for human approval. Tasks are created with "suggested" status \u2014 the human approves or rejects each one. Use this to propose work before starting. Include detailed instructions as if briefing a contractor.',
+    parameters: Type.Object({
+      suggestions: Type.Array(
+        Type.Object({
+          title: Type.String({
+            description: "Task title \u2014 short, action-oriented (max 200 chars)"
+          }),
+          instructions: Type.Optional(
+            Type.String({
+              description: "Detailed instructions: what to do, why, what done looks like, known constraints"
+            })
+          ),
+          estimatedTokens: Type.Optional(
+            Type.Number({
+              description: "Estimated token cost \u2014 consider files to read, reasoning, output"
+            })
+          ),
+          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"
+              }
+            )
+          )
+        }),
+        {
+          description: "Array of task suggestions (1-20)",
+          minItems: 1,
+          maxItems: 20
+        }
       ),
-      taskId: Type.Optional(
+      parentTaskId: Type.Optional(
         Type.String({
-          description: "Task UUID (optional if context provides it)"
+          description: "Parent task ID \u2014 set when suggesting follow-ups from within a task"
         })
       ),
-      suggestions: Type.Optional(
+      initiativeSuggestions: 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"
+            title: Type.String({
+              description: "Initiative title (max 200 chars)"
+            }),
+            content: Type.String({
+              description: "Initiative content markdown \u2014 current state, approach, and next priorities"
+            }),
+            taskRefs: Type.Optional(
+              Type.Array(Type.Number(), {
+                description: "Indexes into suggestions[] to auto-link when this initiative is approved"
               })
             )
           }),
           {
-            description: "Suggest tasks for human review (1-10). The human will see approve/reject buttons for each. Provide this instead of content.",
+            description: 'Propose new initiatives (optional). Created with "suggested" status \u2014 human approves or rejects independently.',
             minItems: 1,
-            maxItems: 10
+            maxItems: 5
           }
         )
       )
@@ -7835,34 +7957,59 @@ var ORCHESTRATOR_TOOLS = {
   },
   CLAIM_EVALUATION: {
     name: "deskfree_claim_evaluation",
-    description: "Claim a pending ways-of-working evaluation for a task. Returns the task, its message history, and current ways_of_working content so you can decide whether updates are needed. Returns null if already claimed by another process.",
+    description: "Claim a pending ways-of-working evaluation for a task. Returns the task, its message history, current global ways_of_working, and initiative data (if the task belongs to an initiative). Returns null if already claimed by another process.",
     parameters: Type.Object({
       taskId: Type.String({ description: "Task UUID to claim evaluation for" })
     })
   },
   SUBMIT_EVALUATION: {
     name: "deskfree_submit_evaluation",
-    description: "Submit the result of a ways-of-working evaluation. Provide reasoning explaining your analysis. If the task revealed new patterns or learnings worth capturing, set hasChanges=true and provide updatedContent with the full updated markdown. Otherwise set hasChanges=false.",
+    description: "Submit the result of a ways-of-working evaluation. Provide reasoning explaining your analysis. Evaluation has two independent outputs: globalWoW (applies everywhere) and initiative (applies to the specific initiative this task belongs to). Set hasChanges=true and provide updatedContent for each output you want to update.",
     parameters: Type.Object({
       taskId: Type.String({ description: "Task UUID being evaluated" }),
       reasoning: Type.String({
-        description: "Explanation of your evaluation \u2014 what you analyzed and why you did or did not update the ways of working"
-      }),
-      hasChanges: Type.Boolean({
-        description: "Whether the ways of working should be updated"
+        description: "Explanation of your evaluation \u2014 what you analyzed and why you did or did not update the ways of working and/or initiative content"
       }),
-      updatedContent: Type.Optional(
-        Type.String({
-          description: "Full updated ways-of-working markdown (required if hasChanges=true)"
-        })
+      globalWoW: Type.Object(
+        {
+          hasChanges: Type.Boolean({
+            description: "Whether the global ways of working should be updated"
+          }),
+          updatedContent: Type.Optional(
+            Type.String({
+              description: "Full updated global ways-of-working markdown (required if hasChanges=true)"
+            })
+          )
+        },
+        {
+          description: "Global ways-of-working update \u2014 patterns that apply across all work"
+        }
+      ),
+      initiative: Type.Object(
+        {
+          hasChanges: Type.Boolean({
+            description: "Whether the initiative content should be updated (ignored if task has no initiative)"
+          }),
+          updatedContent: Type.Optional(
+            Type.String({
+              description: "Full updated initiative content markdown (required if hasChanges=true)"
+            })
+          )
+        },
+        {
+          description: "Initiative content update \u2014 what was learned about this specific area of focus. Ignored if the task has no initiative_id."
+        }
       )
     })
   }
 };
 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 = {
@@ -8420,14 +8567,22 @@ var deskFreePlugin = {
 };
 
 // src/context.ts
-var DESKFREE_AGENT_DIRECTIVE = `## DeskFree
-Always read the deskfree skill (SKILL.md) at startup. Follow its workflow for task tracking and messaging.
-1. ALL work requires a task \u2014 use \`deskfree_create_task\` then \`deskfree_start_task\`.
-2. Ways of Working is your evolving playbook \u2014 it's injected automatically via state.get. When tasks are approved by humans, you'll evaluate them and update the ways of working.
-3. Build deliverables incrementally \u2014 use \`deskfree_update_deliverable\` from the start.
-4. Always complete tasks \u2014 use \`deskfree_complete_task\` with outcome "done" or "blocked".
-5. Auto-threading works \u2014 messages sent while a task is active are threaded automatically.
-6. Sub-agents get 4 tools: update_deliverable, complete_task, send_message (also supports suggestions), submit_evaluation.`;
+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, 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 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 file output becomes someone else's context.
+- Write instructions as if briefing a contractor who has never seen the codebase.
+- MUST provide summary when completing with outcome "done".
+- Estimate token cost per suggestion \u2014 consider files to read, reasoning, output.
+- 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}
 
@@ -8466,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)
       }
     ]
   };
@@ -8485,11 +8632,7 @@ function formatConfirmation(summary, nextActions, data) {
       {
         type: "text",
         text: JSON.stringify(
-          {
-            summary,
-            nextActions,
-            ...data ? { data } : {}
-          },
+          { summary, nextActions, ...data ? { data } : {} },
           null,
           2
         )
@@ -8550,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
@@ -8574,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") {
@@ -8598,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") {
@@ -8616,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;
@@ -8634,37 +9058,6 @@ function createOrchestratorTools(api) {
         }
       }
     },
-    {
-      ...ORCHESTRATOR_TOOLS.CREATE_TASK,
-      async execute(_id, params) {
-        try {
-          const title = validateStringParam(params, "title", true);
-          const instructions = validateStringParam(
-            params,
-            "instructions",
-            false
-          );
-          const task = await client.createTask({
-            title,
-            instructions
-          });
-          await client.sendMessage({
-            content: `\u{1F4CB} Created task: "${task.title}"`
-          }).catch(() => {
-          });
-          return formatTaskResponse(
-            task,
-            `Created task "${task.title}" with ID ${task.taskId}`,
-            [
-              "Claim and start this task with deskfree_start_task",
-              "Or check workspace state with deskfree_state"
-            ]
-          );
-        } catch (err) {
-          return errorResult(err);
-        }
-      }
-    },
     {
       ...ORCHESTRATOR_TOOLS.START_TASK,
       async execute(_id, params) {
@@ -8681,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
                   },
@@ -8698,187 +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,
+      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 and current ways of working",
-                      "Decide if patterns/learnings should update ways of working",
-                      "Call deskfree_submit_evaluation with your analysis"
-                    ],
-                    task: result.task,
-                    waysOfWorking: result.waysOfWorking,
-                    currentVersion: result.currentVersion,
-                    messages: result.messages
-                  },
-                  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 hasChanges = params?.hasChanges;
-          if (typeof hasChanges !== "boolean") {
-            throw new Error('Parameter "hasChanges" must be a boolean');
-          }
-          const updatedContent = validateStringParam(
-            params,
-            "updatedContent",
-            false
-          );
-          const result = await client.submitEvaluation({
-            taskId,
-            reasoning,
-            hasChanges,
-            updatedContent
-          });
-          const messageContent = hasChanges ? `\u{1F4DD} Updated ways of working (v${result.version}): ${reasoning}` : `\u{1F4DD} No updates to ways of working: ${reasoning}`;
-          await client.sendMessage({ content: messageContent, taskId }).catch(() => {
-          });
-          return formatConfirmation(
-            hasChanges ? `Ways of working updated to v${result.version}` : "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"
+      )
     }
   ];
 }