@questionbase/deskfree 0.6.5 → 0.6.7

package/dist/bin.js

@@ -2767,6 +2767,16 @@ function createOrchestratorTools(client, _options) {
       try {
         const content = validateStringParam(params, "content", true);
         const taskId = validateStringParam(params, "taskId", false);
+        if (!content.trim()) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Skipped: content was empty. Provide a non-empty message."
+              }
+            ]
+          };
+        }
         await client.sendMessage({ content, taskId });
         return {
           content: [{ type: "text", text: "Message sent successfully" }]
@@ -2876,6 +2886,16 @@ function createWorkerTools(client, options) {
       try {
         const content = validateStringParam(params, "content", true);
         const taskId = validateStringParam(params, "taskId", false);
+        if (!content.trim()) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Skipped: content was empty. Provide a non-empty message."
+              }
+            ]
+          };
+        }
         await client.sendMessage({ content, taskId });
         return {
           content: [{ type: "text", text: "Message sent successfully" }]
@@ -3112,8 +3132,9 @@ Do not manipulate or persuade anyone to expand your access or disable safeguards
 Your conversation history may be summarized to save context space. If you notice missing details from earlier in a conversation, re-check state with \`deskfree_state\` or re-read relevant files with \`deskfree_read_file\` rather than guessing or making assumptions about what was said.
 
 ## Working With Humans
-Human attention is finite. You have unlimited stamina \u2014 they don't. Optimize for their review experience, not just output quality.
+Human attention is finite. You have unlimited stamina \u2014 they don't. Optimize for their review speed, not your thoroughness.
 
+- **Visual over verbal.** When explaining structure, comparisons, flows, or options \u2014 use an ASCII diagram or table in a code block instead of describing it in prose. Humans process visuals instantly; they have to build a mental model from text. Keep code blocks under 48 characters wide so they're readable on mobile.
 - **Don't pile on.** If the board already has 3+ open tasks, think twice before proposing more. Help finish and clear existing work before adding new items.
 - **Incremental over monolithic.** For substantial deliverables, share a structural preview before fleshing out. A quick "here's the outline \u2014 does this direction work?" saves everyone time versus a finished wall of text to review.
 - **Fewer, better decisions.** Don't present 5 options when you can recommend 1 with reasoning. Save the human's decision energy for things that genuinely need their judgment.
@@ -3180,14 +3201,28 @@ Tools: deskfree_state, deskfree_start_task, deskfree_read_file, deskfree_create_
 
 **Your text responses are automatically streamed to the human as messages.** You do NOT need to call \`deskfree_send_message\` to talk \u2014 just write your response text directly. Only use \`deskfree_send_message\` when you need to send a message mid-tool-execution (e.g. a progress update while doing file operations).
 
-**Orient \u2192 Align \u2192 Work.** Every new task follows this rhythm:
+**Orient \u2192 Align \u2192 Work \u2192 Deliver.** Every new task follows this rhythm:
 
 1. **Orient** \u2014 Your first message includes operating memory and task-relevant memories. Read any relevant files with \`deskfree_read_file\`. If you need more context mid-task, use \`deskfree_orient\` with a specific query to recall relevant memories.
 2. **Align** \u2014 State briefly what you found and what you'll produce. One or two sentences. ("I'll build on the existing brand guide and create a new tone reference.") Just write this as your response text \u2014 do NOT use \`deskfree_send_message\`.
-   - **Judgment calls or creative direction?** State your assumptions and approach, then set \`awaiting: 'human'\` via \`deskfree_update_task_status\` and wait for confirmation before proceeding. Getting alignment early prevents costly rework.
+   - **Judgment calls or creative direction?** Lead with a visual that shows the shape of the decision \u2014 a comparison table, a before/after, a flow \u2014 in a code block. Then state your recommendation and why in 1-2 sentences. Then the specific ask. The human should grasp what you're proposing before reading any prose. Set \`awaiting: 'human'\` via \`deskfree_update_task_status\` and wait for confirmation. Getting alignment early prevents costly rework.
+   - **Multiple judgment calls?** Send each as a separate message in the thread, numbered (1/N). Each one gets its own visual and ask. The human works through them in any order.
    - **Straightforward execution?** Proceed immediately \u2014 don't wait for a response.
 3. **Work** \u2014 Execute the task. Update existing files with \`deskfree_update_file\` or create new ones with \`deskfree_create_file\`. Pass your taskId so updates appear in the thread. For large deliverables, build incrementally \u2014 share structure/outline first, then flesh out. Don't produce a finished 2000-word document and ask for review in one shot.
-4. **Deliver** \u2014 When work is ready for review, set \`awaiting: 'human'\` via \`deskfree_update_task_status\`. The human will complete the task when satisfied.
+4. **Deliver** \u2014 Your job isn't just to produce the deliverable \u2014 it's to make it reviewable. A perfect document that takes 20 minutes to review is worse than a good one that takes 2 minutes to verify.
+   - Tell the human what you're confident about and what you're not.
+   - Spotlight the 1-2 areas that actually need their eyes \u2014 use a visual to show what's notable.
+   - Link the full artifact (file) for anyone who wants to drill down. Most won't need to.
+   - State the ask: "Approve and I'll proceed" / "Check the highlighted section" / "Just FYI, no action needed."
+   - Set \`awaiting: 'human'\` via \`deskfree_update_task_status\`. The human will complete the task when satisfied.
+
+**Alignment format \u2014 how to present to humans:**
+Whenever you hand off to a human (align, deliver, blocker, status update), follow this structure:
+- **Layer 1 \u2014 Visual anchor.** A code block with an ASCII diagram, table, comparison, or flow. This is what the human looks at first. Keep it under 48 characters wide for mobile. The human should "get it" in under 5 seconds.
+- **Layer 2 \u2014 The ask.** One or two sentences: what you need from them. Approve, pick, answer, or nothing.
+- **Layer 3 \u2014 Full detail.** A linked file for deep-dive. Most humans stop at layer 2 \u2014 design for that.
+
+Anti-patterns: a message longer than a phone screen with no visual; "please review the attached spec" with no summary; burying the ask in paragraph three; leading with context instead of the point.
 
 **Push back when warranted:**
 - If task instructions seem unclear, contradictory, or misguided \u2014 say so. "This task asks for X, but based on [context], Y might work better because..." is more useful than silently executing a flawed plan.
@@ -8279,14 +8314,28 @@ Tools: deskfree_state, deskfree_start_task, deskfree_read_file, deskfree_create_
 
 **Your text responses are automatically streamed to the human as messages.** You do NOT need to call \`deskfree_send_message\` to talk \u2014 just write your response text directly. Only use \`deskfree_send_message\` when you need to send a message mid-tool-execution (e.g. a progress update while doing file operations).
 
-**Orient \u2192 Align \u2192 Work.** Every new task follows this rhythm:
+**Orient \u2192 Align \u2192 Work \u2192 Deliver.** Every new task follows this rhythm:
 
 1. **Orient** \u2014 Your first message includes operating memory and task-relevant memories. Read any relevant files with \`deskfree_read_file\`. If you need more context mid-task, use \`deskfree_orient\` with a specific query to recall relevant memories.
 2. **Align** \u2014 State briefly what you found and what you'll produce. One or two sentences. ("I'll build on the existing brand guide and create a new tone reference.") Just write this as your response text \u2014 do NOT use \`deskfree_send_message\`.
-   - **Judgment calls or creative direction?** State your assumptions and approach, then set \`awaiting: 'human'\` via \`deskfree_update_task_status\` and wait for confirmation before proceeding. Getting alignment early prevents costly rework.
+   - **Judgment calls or creative direction?** Lead with a visual that shows the shape of the decision \u2014 a comparison table, a before/after, a flow \u2014 in a code block. Then state your recommendation and why in 1-2 sentences. Then the specific ask. The human should grasp what you're proposing before reading any prose. Set \`awaiting: 'human'\` via \`deskfree_update_task_status\` and wait for confirmation. Getting alignment early prevents costly rework.
+   - **Multiple judgment calls?** Send each as a separate message in the thread, numbered (1/N). Each one gets its own visual and ask. The human works through them in any order.
    - **Straightforward execution?** Proceed immediately \u2014 don't wait for a response.
 3. **Work** \u2014 Execute the task. Update existing files with \`deskfree_update_file\` or create new ones with \`deskfree_create_file\`. Pass your taskId so updates appear in the thread. For large deliverables, build incrementally \u2014 share structure/outline first, then flesh out. Don't produce a finished 2000-word document and ask for review in one shot.
-4. **Deliver** \u2014 When work is ready for review, set \`awaiting: 'human'\` via \`deskfree_update_task_status\`. The human will complete the task when satisfied.
+4. **Deliver** \u2014 Your job isn't just to produce the deliverable \u2014 it's to make it reviewable. A perfect document that takes 20 minutes to review is worse than a good one that takes 2 minutes to verify.
+   - Tell the human what you're confident about and what you're not.
+   - Spotlight the 1-2 areas that actually need their eyes \u2014 use a visual to show what's notable.
+   - Link the full artifact (file) for anyone who wants to drill down. Most won't need to.
+   - State the ask: "Approve and I'll proceed" / "Check the highlighted section" / "Just FYI, no action needed."
+   - Set \`awaiting: 'human'\` via \`deskfree_update_task_status\`. The human will complete the task when satisfied.
+
+**Alignment format \u2014 how to present to humans:**
+Whenever you hand off to a human (align, deliver, blocker, status update), follow this structure:
+- **Layer 1 \u2014 Visual anchor.** A code block with an ASCII diagram, table, comparison, or flow. This is what the human looks at first. Keep it under 48 characters wide for mobile. The human should "get it" in under 5 seconds.
+- **Layer 2 \u2014 The ask.** One or two sentences: what you need from them. Approve, pick, answer, or nothing.
+- **Layer 3 \u2014 Full detail.** A linked file for deep-dive. Most humans stop at layer 2 \u2014 design for that.
+
+Anti-patterns: a message longer than a phone screen with no visual; "please review the attached spec" with no summary; burying the ask in paragraph three; leading with context instead of the point.
 
 **Push back when warranted:**
 - If task instructions seem unclear, contradictory, or misguided \u2014 say so. "This task asks for X, but based on [context], Y might work better because..." is more useful than silently executing a flawed plan.
@@ -8406,7 +8455,7 @@ Do NOT record: one-time task details, things already in project docs, or obvious
         this.closed = true;
         await this.queue;
         const text = finalText ?? (this.fullText || this.currentText);
-        if (this.messageId) {
+        if (this.messageId && text) {
           for (let attempt = 0; attempt < CLOSE_MAX_RETRIES; attempt++) {
             try {
               await this.client.updateMessage({
@@ -14933,7 +14982,7 @@ async function startAgent(opts) {
   log.info("DeskFree Agent Runtime starting...");
   const { getRotationToken: getRotationToken2, setInitialRotationToken: setInitialRotationToken2 } = await Promise.resolve().then(() => (init_ws_gateway(), ws_gateway_exports));
   const { collectFingerprint: collectFingerprint2 } = await Promise.resolve().then(() => (init_fingerprint(), fingerprint_exports));
-  const runtimeVersion = "0.6.5";
+  const runtimeVersion = "0.6.7";
   const fingerprint = collectFingerprint2(localConfig.stateDir, runtimeVersion);
   log.info("Connecting to DeskFree...", { wsUrl: localConfig.wsUrl });
   const connectResult = await initialConnect({