@questionbase/deskfree 0.3.0-alpha.39 → 0.3.0-alpha.40

package/dist/index.d.ts

@@ -468,6 +468,7 @@ interface TaskWithContext extends Task {
 }
 interface CompleteTaskInput {
     taskId: string;
+    humanApproved: boolean;
     learnings?: {
         reasoning: string;
         globalWoW?: string;
@@ -600,6 +601,14 @@ declare class DeskFreeClient {
     getTask(input: {
         taskId: string;
     }): Promise<TaskSummary>;
+    /** Update task step progress. */
+    updateSteps(input: {
+        taskId: string;
+        steps: Array<{
+            label: string;
+            status: 'pending' | 'in_progress' | 'done';
+        }>;
+    }): Promise<void>;
     /** Update the content of an existing file. */
     updateFile(input: {
         fileId: string;

package/dist/index.js

@@ -4025,6 +4025,11 @@ var DeskFreeClient = class {
     this.requireNonEmpty(input.taskId, "taskId");
     return this.request("GET", "tasks.get", input);
   }
+  /** Update task step progress. */
+  async updateSteps(input) {
+    this.requireNonEmpty(input.taskId, "taskId");
+    return this.request("POST", "tasks.updateSteps", input);
+  }
   /** Update the content of an existing file. */
   async updateFile(input) {
     this.requireNonEmpty(input.fileId, "fileId");
@@ -8209,9 +8214,21 @@ var ORCHESTRATOR_TOOLS = {
           }),
           instructions: Type.Optional(
             Type.String({
-              description: "3-8 bullet points max in simple markdown (bold, lists, inline code \u2014 no # headers). What to do, what done looks like, key constraints. Under 500 words. Skip context the worker can infer from the title."
+              description: "Optional background context or constraints. Keep brief \u2014 steps carry the main structure."
             })
           ),
+          steps: Type.Optional(
+            Type.Array(
+              Type.String({
+                description: "Short action phrase (max 300 chars)"
+              }),
+              {
+                description: "3-8 step labels as short action phrases. These become the visual progress tracker for the worker.",
+                minItems: 1,
+                maxItems: 20
+              }
+            )
+          ),
           file: Type.Optional(
             Type.Union(
               [
@@ -8292,6 +8309,9 @@ var SHARED_TOOLS = {
     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" }),
+      humanApproved: Type.Boolean({
+        description: "Must be true. Confirms the human reviewed and approved completion. Backend validates a human message exists after your last ask."
+      }),
       learnings: Type.Optional(
         Type.Object(
           {
@@ -8397,9 +8417,21 @@ var SHARED_TOOLS = {
           }),
           instructions: Type.Optional(
             Type.String({
-              description: "3-8 bullet points max in simple markdown (bold, lists, inline code \u2014 no # headers). What to do, what done looks like, key constraints. Under 500 words. Skip context the worker can infer from the title."
+              description: "Optional background context or constraints. Keep brief \u2014 steps carry the main structure."
             })
           ),
+          steps: Type.Optional(
+            Type.Array(
+              Type.String({
+                description: "Short action phrase (max 300 chars)"
+              }),
+              {
+                description: "3-8 step labels as short action phrases. These become the visual progress tracker for the worker.",
+                minItems: 1,
+                maxItems: 20
+              }
+            )
+          ),
           file: Type.Optional(
             Type.Union(
               [
@@ -8473,6 +8505,31 @@ var WORKER_TOOLS = {
     })
   },
   UPDATE_FILE: SHARED_TOOLS.UPDATE_FILE,
+  UPDATE_STEPS: {
+    name: "deskfree_update_steps",
+    description: "Update step progress for your current task. Send the full step list each time (full replacement). Call this as you work through steps to show progress.",
+    parameters: Type.Object({
+      taskId: Type.String({ description: "Task UUID" }),
+      steps: Type.Array(
+        Type.Object({
+          label: Type.String({ description: "Step label (max 300 chars)" }),
+          status: Type.Union(
+            [
+              Type.Literal("pending"),
+              Type.Literal("in_progress"),
+              Type.Literal("done")
+            ],
+            { description: "Current status of this step" }
+          )
+        }),
+        {
+          description: "Full step list with current statuses (1-20 items)",
+          minItems: 1,
+          maxItems: 20
+        }
+      )
+    })
+  },
   COMPLETE_TASK: SHARED_TOOLS.COMPLETE_TASK,
   SEND_MESSAGE: SHARED_TOOLS.SEND_MESSAGE,
   PROPOSE: SHARED_TOOLS.PROPOSE,
@@ -8938,22 +8995,25 @@ You are the orchestrator. Your job: turn human intent into approved tasks, then
 
 You do NOT claim tasks, complete tasks, or do work directly \u2014 you have no access to deskfree_start_task or deskfree_complete_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 just confirmation or deferred \u2014 leave it for now.
-- Write task instructions as 3-8 bullet points max (bold, lists, inline code \u2014 no # headers). What to do, what done looks like, key constraints. Under 500 words \u2014 brief a contractor, not write a spec.
+- Propose tasks with 3-8 steps (short action phrases). Steps are the visual progress tracker for the worker. Add brief instructions only for context or constraints the steps don't capture.
 - Estimate token cost per task \u2014 consider files to read, reasoning, output.
 - One initiative per proposal \u2014 make multiple calls for multiple initiatives.
 - Initiative titles should reflect aspirations and outcomes, not activities. "AI Thought Leadership on LinkedIn" over "LinkedIn Content."
 - Initiative descriptions should be 2-3 sentences that make the human think "wow, this will enable my dreams." Reflect their ambition back to them. No headers, no phases, no formal structure. Aspirational, not operational.`;
 var DESKFREE_WORKER_DIRECTIVE = `## DeskFree Worker
 You are a worker sub-agent. Call \`deskfree_start_task\` with your taskId to claim and load context.
-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. Build up incrementally \u2014 start with structure/outline, then flesh out. Send an "ask" for review before going deep. The human should see the shape before the details.
-- 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" only if you have genuine new knowledge. WoW updates should be surgical \u2014 add or modify only the relevant section, do not restate existing content. Reasoning should be 1-2 sentences. Pass "followUps" as brief handoffs (title + 2-3 bullets each).
-- 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.`;
+Tools: deskfree_start_task, deskfree_update_steps, deskfree_update_file, deskfree_complete_task, deskfree_send_message, deskfree_propose.
+
+**After claiming a task, your first message should be how you plan to approach it.** Work one step at a time and share progress naturally \u2014 like updating a coworker.
+
+- Claim your task first with deskfree_start_task \u2014 this loads steps, messages, and file context.
+- Use deskfree_update_steps to update step progress as you work. Send the full step list each time with updated statuses.
+- Save work to linked files with deskfree_update_file. Build up incrementally \u2014 start with structure/outline, then flesh out.
+- Use deskfree_send_message with type "notify" for progress updates. Keep it brief \u2014 1-3 sentences.
+- Use deskfree_send_message with type "ask" when you need human input OR when work is ready for review. Terminate after sending an ask.
+- Only complete (deskfree_complete_task with humanApproved: true) after the human has confirmed in the thread. Never self-complete without human response.
+- When completing: pass "learnings" only for genuine new knowledge. Pass "followUps" as brief handoffs.
+- On 409 or 404 errors: STOP. Do not retry. 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;
@@ -9091,6 +9151,9 @@ function trimTaskContext(result) {
   if (raw["substeps"]) {
     trimmed.substeps = raw["substeps"];
   }
+  if (raw["steps"]) {
+    trimmed.steps = raw["steps"];
+  }
   if (raw["parentContext"]) {
     trimmed.parentContext = raw["parentContext"];
   }
@@ -9309,6 +9372,36 @@ function parseInitiative(raw) {
   }
   return void 0;
 }
+function makeUpdateStepsHandler(client) {
+  return async (_id, params) => {
+    try {
+      const taskId = validateStringParam(params, "taskId", true);
+      const rawSteps = params["steps"];
+      if (!Array.isArray(rawSteps) || rawSteps.length === 0) {
+        throw new Error("steps must be a non-empty array");
+      }
+      const steps = rawSteps.map((s) => {
+        if (typeof s !== "object" || s === null) throw new Error("Invalid step");
+        const obj = s;
+        const label = typeof obj["label"] === "string" ? obj["label"].trim() : "";
+        const status = typeof obj["status"] === "string" ? obj["status"] : "pending";
+        if (!label) throw new Error("Step label is required");
+        if (!["pending", "in_progress", "done"].includes(status)) {
+          throw new Error(`Invalid step status: ${status}`);
+        }
+        return { label, status };
+      });
+      await client.updateSteps({ taskId, steps });
+      const doneCount = steps.filter((s) => s.status === "done").length;
+      return formatConfirmation(
+        `Updated steps for task ${taskId} (${doneCount}/${steps.length} done)`,
+        ["Step progress saved \u2014 continue working"]
+      );
+    } catch (err) {
+      return errorResult(err);
+    }
+  };
+}
 function makeUpdateFileHandler(client) {
   return async (_id, params) => {
     try {
@@ -9356,8 +9449,10 @@ function makeCompleteTaskHandler(client) {
         }).filter((item) => item.title.length > 0);
         if (parsed.length > 0) followUps = parsed;
       }
+      const humanApproved = params["humanApproved"] === true;
       const result = await client.completeTask({
         taskId,
+        humanApproved,
         learnings,
         followUps
       });
@@ -9567,6 +9662,7 @@ ${s.criticalSection}`
         return errorResult(err);
       }
     }),
+    createTool(WORKER_TOOLS.UPDATE_STEPS, makeUpdateStepsHandler(client)),
     createTool(WORKER_TOOLS.UPDATE_FILE, makeUpdateFileHandler(client)),
     createTool(WORKER_TOOLS.COMPLETE_TASK, makeCompleteTaskHandler(client)),
     createTool(WORKER_TOOLS.SEND_MESSAGE, makeSendMessageHandler(client)),