@questionbase/deskfree 0.3.0-alpha.36 → 0.3.0-alpha.37

package/dist/index.d.ts

@@ -418,7 +418,7 @@ interface WsNotification {
 interface Task {
     taskId: string;
     title: string;
-    status: 'pending' | 'active' | 'review' | 'done';
+    status: 'open' | 'done';
     instructions?: string;
     createdAt: string;
     updatedAt: string;
@@ -431,7 +431,7 @@ interface Task {
 interface TaskSummary {
     taskId: string;
     title: string;
-    status: 'pending' | 'active' | 'review' | 'done';
+    status: 'open' | 'done';
     instructions: string | null;
     fileId: string | null;
     fileName: string | null;
@@ -468,13 +468,20 @@ interface TaskWithContext extends Task {
 }
 interface CompleteTaskInput {
     taskId: string;
-    outcome: 'done' | 'blocked';
-    summary?: string;
+    learnings?: {
+        reasoning: string;
+        globalWoW?: string;
+        initiativeContent?: string;
+    };
+    followUps?: Array<{
+        title: string;
+        instructions?: string;
+    }>;
 }
 interface WorkspaceStateTask {
     taskId: string;
     title: string;
-    status: 'pending' | 'active' | 'review' | 'done';
+    status: 'open' | 'done';
     instructions?: string | null;
     fileId?: string | null;
     fileName?: string | null;
@@ -564,6 +571,7 @@ declare class DeskFreeClient {
         userId?: string;
         content: string;
         taskId?: string;
+        messageType?: 'ask' | 'notify';
         attachments?: Array<{
             s3Key: string;
             name: string;
@@ -659,10 +667,8 @@ declare class DeskFreeClient {
     }): Promise<{
         success: boolean;
     }>;
-    /** Complete a task with an outcome. Moves task to human. */
-    completeTask(input: CompleteTaskInput): Promise<Task & {
-        outcome: 'done' | 'blocked';
-    }>;
+    /** Complete a task. Marks it as done. */
+    completeTask(input: CompleteTaskInput): Promise<Task>;
     /** Reopen a completed/human task back to bot status for further work. */
     reopenTask(input: {
         taskId: string;
@@ -701,20 +707,10 @@ declare class DeskFreeClient {
             content: string;
         };
         context?: string;
+        taskId?: string;
     }): Promise<{
         messageId: string;
     }>;
-    /** Update ways of working and/or initiative content based on learnings. */
-    updateKnowledge(input: {
-        globalWoW?: string;
-        initiativeId?: string;
-        initiativeContent?: string;
-        reasoning: string;
-    }): Promise<{
-        success: boolean;
-        globalVersion?: number;
-        initiativeVersion?: number;
-    }>;
     /**
      * Lightweight health check that verifies connectivity and authentication.
      *

package/dist/index.js

@@ -3932,7 +3932,7 @@ var DeskFreeClient = class {
     this.requireNonEmpty(input.model, "model");
     return this.request("POST", "tasks.reportUsage", input);
   }
-  /** Complete a task with an outcome. Moves task to human. */
+  /** Complete a task. Marks it as done. */
   async completeTask(input) {
     this.requireNonEmpty(input.taskId, "taskId");
     return this.request("POST", "tasks.complete", input);
@@ -3966,11 +3966,6 @@ var DeskFreeClient = class {
     }
     return this.request("POST", "tasks.propose", input);
   }
-  /** Update ways of working and/or initiative content based on learnings. */
-  async updateKnowledge(input) {
-    this.requireNonEmpty(input.reasoning, "reasoning");
-    return this.request("POST", "waysOfWorking.update", input);
-  }
   /**
    * Lightweight health check that verifies connectivity and authentication.
    *
@@ -4492,10 +4487,10 @@ function buildBodyForAgent(task, content, recentMessages) {
   return prefix + "\n\n" + content;
 }
 function resolveTaskRouting(task, hasAttachments) {
-  if (task.status === "active") {
+  if (task.status === "open") {
     return { target: "runner" };
   }
-  if (hasAttachments && (task.status === "review" || task.status === "done")) {
+  if (hasAttachments && task.status === "done") {
     return { target: "auto-reopen" };
   }
   return { target: "orchestrator" };
@@ -7982,7 +7977,7 @@ var ORCHESTRATOR_TOOLS = {
   },
   REOPEN_TASK: {
     name: "deskfree_reopen_task",
-    description: "Reopen a completed or human-side task back to bot status. Use when a human message in a task thread indicates more work is needed. The task becomes available for a worker to claim.",
+    description: "Reopen a task (from review or done) back to pending. Use when more work is needed on a task. Works on both completed and in-review tasks.",
     parameters: Type.Object({
       taskId: Type.String({ description: "Task UUID to reopen" }),
       reason: Type.Optional(
@@ -7992,30 +7987,6 @@ var ORCHESTRATOR_TOOLS = {
       )
     })
   },
-  UPDATE_KNOWLEDGE: {
-    name: "deskfree_update_knowledge",
-    description: "Update ways of working and/or initiative content based on learnings from completed tasks.",
-    parameters: Type.Object({
-      globalWoW: Type.Optional(
-        Type.String({
-          description: "Full updated global ways-of-working markdown content"
-        })
-      ),
-      initiativeId: Type.Optional(
-        Type.String({
-          description: "Initiative ID to update"
-        })
-      ),
-      initiativeContent: Type.Optional(
-        Type.String({
-          description: "Full updated initiative content markdown (required if initiativeId provided)"
-        })
-      ),
-      reasoning: Type.String({
-        description: "Explanation of why these updates were made and what was learned"
-      })
-    })
-  },
   SEND_MESSAGE: {
     name: "deskfree_send_message",
     description: "Send a message to the human. Keep it short \u2014 1-3 sentences. No walls of text.",
@@ -8124,6 +8095,11 @@ var ORCHESTRATOR_TOOLS = {
           minItems: 1,
           maxItems: 20
         }
+      ),
+      taskId: Type.Optional(
+        Type.String({
+          description: "Task ID to thread this proposal into (for follow-up proposals from within a task)"
+        })
       )
     })
   }
@@ -8146,36 +8122,63 @@ var SHARED_TOOLS = {
   },
   COMPLETE_TASK: {
     name: "deskfree_complete_task",
-    description: "Finish a task. Transitions to review/done status based on outcome.",
+    description: "Mark a task as done. Only call when truly finished and human confirmed. Pass learnings to update knowledge atomically with completion. Pass followUps to propose next tasks.",
     parameters: Type.Object({
       taskId: Type.String({ description: "Task UUID" }),
-      outcome: Type.Union(
-        [
-          Type.Literal("review"),
-          Type.Literal("done"),
-          Type.Literal("blocked"),
-          Type.Literal("cancelled")
-        ],
-        {
-          description: '"review" = ready for human review, "done" = work complete, "blocked" = need human input, "cancelled" = task cancelled'
-        }
-      ),
-      summary: Type.Optional(
-        Type.String({
-          description: "1-2 sentence summary of what was done and the outcome."
-        })
-      ),
       learnings: Type.Optional(
-        Type.String({
-          description: "Key insights, patterns, or lessons learned from completing this task. Used to improve future work."
-        })
+        Type.Object(
+          {
+            reasoning: Type.String({
+              description: "Why these updates matter \u2014 what was learned from this task"
+            }),
+            globalWoW: Type.Optional(
+              Type.String({
+                description: "Full updated global Ways of Working markdown content (full replacement, not diff)"
+              })
+            ),
+            initiativeId: Type.Optional(
+              Type.String({
+                description: "Initiative ID to update"
+              })
+            ),
+            initiativeContent: Type.Optional(
+              Type.String({
+                description: "Full updated initiative content markdown (full replacement, not diff)"
+              })
+            )
+          },
+          {
+            description: "Knowledge updates to apply atomically with task completion. Include only if there are genuine learnings to record."
+          }
+        )
+      ),
+      followUps: Type.Optional(
+        Type.Array(
+          Type.Object({
+            title: Type.String({
+              description: "Follow-up task title (max 200 chars)"
+            }),
+            instructions: Type.Optional(
+              Type.String({
+                description: "Instructions for the follow-up task"
+              })
+            )
+          }),
+          {
+            description: "Follow-up tasks to propose for human approval (max 10). Use when the work revealed clear next steps.",
+            maxItems: 10
+          }
+        )
       )
     })
   },
   SEND_MESSAGE: {
     name: "deskfree_send_message",
-    description: "Send a message in the task thread. Keep it short \u2014 1-3 sentences. No walls of text.",
+    description: "Send a message in the task thread. Keep it short \u2014 1-3 sentences.",
     parameters: Type.Object({
+      type: Type.Union([Type.Literal("notify"), Type.Literal("ask")], {
+        description: "notify = progress update (quiet, collapsible). ask = needs human attention (surfaces to main thread). Terminate after sending an ask."
+      }),
       content: Type.String({
         description: "Message content."
       }),
@@ -8280,6 +8283,11 @@ var SHARED_TOOLS = {
           minItems: 1,
           maxItems: 20
         }
+      ),
+      taskId: Type.Optional(
+        Type.String({
+          description: "Task ID to thread this proposal into (for follow-up proposals from within a task)"
+        })
       )
     })
   }
@@ -8305,7 +8313,9 @@ var WORKER_TOOLS = {
     name: "deskfree_read_skill_section",
     description: "Load full instructions for a skill. Use after deskfree_start_task when you need the complete skill guide beyond the critical section summary.",
     parameters: Type.Object({
-      skillId: Type.String({ description: "Skill ID to load instructions for" })
+      skillId: Type.String({
+        description: "Skill ID to load instructions for"
+      })
     })
   }
 };
@@ -8884,8 +8894,8 @@ You are the orchestrator. Your job: turn human intent into approved tasks, then
 
 **Match the human's energy.** Short message \u2192 short reply. Casual tone \u2192 casual response. Don't over-explain, don't lecture, don't pad responses.
 
-You do NOT claim tasks or do work directly. Sub-agents handle execution.
-- When a human writes in a task thread, you receive it with recent context. Use \`deskfree_reopen_task\` if it needs more work.
+You do NOT claim tasks or do work directly \u2014 you have no access to deskfree_start_task. Spawn a sub-agent for each approved task and pass it the taskId.
+- When a human writes in a task thread, decide: does it need bot action? If yes \u2192 reopen and spawn sub-agent. If it's confirmation ("looks good") \u2192 complete the task. If deferred ("I'll check later") \u2192 leave it.
 - Write task instructions as rich markdown (bold, lists, inline code \u2014 no # headers). Brief a contractor who has never seen the codebase.
 - Estimate token cost per task \u2014 consider files to read, reasoning, output.
 - One initiative per proposal \u2014 make multiple calls for multiple initiatives.
@@ -8896,10 +8906,12 @@ You are a worker sub-agent. Call \`deskfree_start_task\` with your taskId to cla
 Tools: deskfree_start_task, deskfree_update_file, deskfree_complete_task, deskfree_send_message, deskfree_propose.
 - Claim your task first with deskfree_start_task \u2014 this loads instructions, messages, and file context.
 - Save work to linked files with deskfree_update_file (incrementally).
-- Complete with deskfree_complete_task when done (summary required for outcome "done"). Include learnings if applicable.
-- If you need human input to proceed, send a message explaining what you need, then complete with outcome "review" \u2014 this marks the task as needing attention.
-- Propose follow-up tasks with deskfree_propose if you discover more work.
-- Keep messages and file updates concise. Write like a senior colleague giving a status update \u2014 not a report. 1-3 sentences for messages unless the human asked for detail.`;
+- Use deskfree_send_message with type "notify" for progress updates \u2014 what you're doing, what you found. Keep it brief.
+- Use deskfree_send_message with type "ask" when you need human input OR when your work is done for review. This surfaces to the main thread. Terminate after sending an ask.
+- When completing: pass "learnings" to deskfree_complete_task if you have knowledge updates (WoW or initiative content). Pass "followUps" if the work revealed clear next steps. Knowledge updates and proposals happen atomically with completion \u2014 no separate tool calls needed.
+- Only complete when the human has confirmed or no review is needed.
+- Write like a senior colleague giving a status update \u2014 not a report. 1-3 sentences for messages.
+- On 409 or 404 errors: STOP. Do not retry the same taskId. Call deskfree_state to find available tasks.`;
 function getDeskFreeContext(sessionKey) {
   const isWorker = sessionKey && (sessionKey.includes(":sub:") || sessionKey.includes(":spawn:") || sessionKey.includes(":run:"));
   const directive = isWorker ? DESKFREE_WORKER_DIRECTIVE : DESKFREE_AGENT_DIRECTIVE;
@@ -9108,9 +9120,9 @@ function suggestionForErrorType(type, statusCode) {
       if (statusCode === 429)
         return "Too many requests. Wait a moment before trying again.";
       if (statusCode === 409)
-        return "Try calling deskfree_state to see available tasks.";
+        return "STOP \u2014 this task is already claimed or completed. Do NOT retry. Call deskfree_state to find available tasks.";
       if (statusCode === 404)
-        return "Use deskfree_state to see all available tasks and verify the taskId.";
+        return "STOP \u2014 task not found or not in claimable state. Do NOT retry. Call deskfree_state to find available tasks.";
       return "Check your input parameters and try again.";
     default:
       return "";
@@ -9280,34 +9292,46 @@ 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 evaluation = params?.evaluation;
+      let learnings;
+      if (params["learnings"] && typeof params["learnings"] === "object") {
+        const raw = params["learnings"];
+        const reasoning = typeof raw["reasoning"] === "string" ? raw["reasoning"] : "";
+        if (reasoning.trim()) {
+          learnings = {
+            reasoning,
+            globalWoW: typeof raw["globalWoW"] === "string" && raw["globalWoW"].trim() ? raw["globalWoW"] : void 0,
+            initiativeContent: typeof raw["initiativeContent"] === "string" && raw["initiativeContent"].trim() ? raw["initiativeContent"] : void 0
+          };
+        }
+      }
+      let followUps;
+      if (Array.isArray(params["followUps"]) && params["followUps"].length > 0) {
+        const parsed = params["followUps"].filter((item) => typeof item === "object" && item !== null).map((item) => {
+          const obj = item;
+          const title = typeof obj["title"] === "string" ? obj["title"].trim() : "";
+          const instructions = typeof obj["instructions"] === "string" ? obj["instructions"] : void 0;
+          return { title, instructions };
+        }).filter((item) => item.title.length > 0);
+        if (parsed.length > 0) followUps = parsed;
+      }
       const result = await client.completeTask({
         taskId,
-        outcome,
-        summary,
-        ...evaluation ? { evaluation } : {}
+        learnings,
+        followUps
       });
       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(() => {
-      });
+      const actions = ["Use deskfree_state to check for other tasks"];
+      if (learnings?.globalWoW) actions.unshift("Ways of Working updated");
+      if (learnings?.initiativeContent)
+        actions.unshift("Initiative content updated");
+      if (followUps)
+        actions.unshift(
+          `${followUps.length} follow-up task(s) proposed for human approval`
+        );
       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"
-        ]
+        `Task "${result.title}" marked as done \u2705`,
+        actions
       );
     } catch (err) {
       return errorResult(err);
@@ -9333,13 +9357,16 @@ function makeSendMessageHandler(client) {
     try {
       const content = validateStringParam(params, "content", true);
       const taskId = validateStringParam(params, "taskId", false);
-      await client.sendMessage({ content, taskId });
+      const messageType = validateEnumParam(
+        params,
+        "type",
+        ["notify", "ask"],
+        true
+      );
+      await client.sendMessage({ content, taskId, messageType });
       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"
-        ]
+        `Message sent (${messageType})${taskId ? ` to task ${taskId}` : ""}`,
+        messageType === "ask" ? ["Message surfaced to human \u2014 terminate and wait for response"] : ["Progress update sent \u2014 continue working"]
       );
     } catch (err) {
       return errorResult(err);
@@ -9352,6 +9379,7 @@ function makeProposeHandler(client) {
       const tasks = parseProposeTasks(params?.tasks);
       const context = validateStringParam(params, "context", false);
       const initiative = parseInitiative(params?.initiative);
+      const taskId = validateStringParam(params, "taskId", false);
       const result = await client.proposePlan({
         tasks: tasks.map((t) => ({
           title: t.title,
@@ -9362,7 +9390,8 @@ function makeProposeHandler(client) {
           scheduledFor: t.scheduledFor
         })),
         initiative,
-        context: context ?? void 0
+        context: context ?? void 0,
+        taskId: taskId ?? void 0
       });
       return formatConfirmation(
         `Proposed ${tasks.length} task${tasks.length === 1 ? "" : "s"} for human approval`,
@@ -9435,41 +9464,6 @@ function createOrchestratorTools(api) {
       ...ORCHESTRATOR_TOOLS.REOPEN_TASK,
       execute: makeReopenTaskHandler(client)
     },
-    {
-      ...ORCHESTRATOR_TOOLS.UPDATE_KNOWLEDGE,
-      async execute(_id, params) {
-        try {
-          const globalWoW = validateStringParam(params, "globalWoW", false);
-          const initiativeId = validateStringParam(
-            params,
-            "initiativeId",
-            false
-          );
-          const initiativeContent = validateStringParam(
-            params,
-            "initiativeContent",
-            false
-          );
-          const reasoning = validateStringParam(params, "reasoning", true);
-          const result = await client.updateKnowledge({
-            globalWoW,
-            initiativeId,
-            initiativeContent,
-            reasoning
-          });
-          return {
-            content: [
-              {
-                type: "text",
-                text: `Knowledge updated successfully: ${JSON.stringify(result, null, 2)}`
-              }
-            ]
-          };
-        } catch (err) {
-          return errorResult(err);
-        }
-      }
-    },
     {
       ...ORCHESTRATOR_TOOLS.SEND_MESSAGE,
       execute: makeSendMessageHandler(client)
@@ -9498,7 +9492,10 @@ function createWorkerTools(api) {
           cachedSkillContext.clear();
           if (result.skillContext?.length) {
             for (const s of result.skillContext) {
-              cachedSkillContext.set(s.skillId, { displayName: s.displayName, instructions: s.instructions });
+              cachedSkillContext.set(s.skillId, {
+                displayName: s.displayName,
+                instructions: s.instructions
+              });
             }
             skillInstructions = result.skillContext.map(
               (s) => `
@@ -9566,15 +9563,24 @@ ${s.criticalSection}`
           const skillId = validateStringParam(params, "skillId", true);
           const cached = cachedSkillContext.get(skillId);
           if (!cached) {
-            return { content: [{ type: "text", text: `Skill ${skillId} not found in current task context. Available: ${[...cachedSkillContext.keys()].join(", ") || "none"}` }] };
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Skill ${skillId} not found in current task context. Available: ${[...cachedSkillContext.keys()].join(", ") || "none"}`
+                }
+              ]
+            };
           }
           return {
-            content: [{
-              type: "text",
-              text: `## ${cached.displayName} \u2014 Full Instructions
+            content: [
+              {
+                type: "text",
+                text: `## ${cached.displayName} \u2014 Full Instructions
 
 ${cached.instructions}`
-            }]
+              }
+            ]
           };
         } catch (err) {
           return errorResult(err);