@questionbase/deskfree 0.3.0-alpha.19 → 0.3.0-alpha.20

package/dist/index.js

@@ -3687,12 +3687,39 @@ var DeskFreeError = class _DeskFreeError extends Error {
         status
       );
     }
-    if (status >= 500) {
+    if (status === 400) {
       return new _DeskFreeError(
-        "server",
+        "client",
         procedure,
-        `Server error: ${status} ${statusText} \u2014 ${responseText}`,
-        "DeskFree service is temporarily unavailable. Please try again in a few minutes.",
+        `Bad request: ${status} ${statusText} \u2014 ${responseText}`,
+        "The request was invalid. Please check your input parameters and try again.",
+        status
+      );
+    }
+    if (status === 404) {
+      return new _DeskFreeError(
+        "client",
+        procedure,
+        `Resource not found: ${status} ${statusText} \u2014 ${responseText}`,
+        procedure.includes("task") ? "The specified task was not found or is not available. Use deskfree_state to see available tasks." : "The requested resource was not found. Please check your input and try again.",
+        status
+      );
+    }
+    if (status === 409) {
+      return new _DeskFreeError(
+        "client",
+        procedure,
+        `Conflict: ${status} ${statusText} \u2014 ${responseText}`,
+        procedure.includes("start_task") || procedure.includes("claim") ? "The resource is already in use by another process. Use deskfree_state to see current status and try a different resource." : "The request conflicts with the current state of the resource. Please refresh and try again.",
+        status
+      );
+    }
+    if (status === 422) {
+      return new _DeskFreeError(
+        "client",
+        procedure,
+        `Validation failed: ${status} ${statusText} \u2014 ${responseText}`,
+        "The request data failed validation. Please check all required fields and data formats.",
         status
       );
     }
@@ -3705,12 +3732,22 @@ var DeskFreeError = class _DeskFreeError extends Error {
         status
       );
     }
-    if (status === 400) {
+    if (status >= 500 && status < 600) {
+      const serverErrorMessage = status === 502 || status === 503 ? "DeskFree service is temporarily unavailable due to maintenance or high load. Please try again in a few minutes." : status === 504 ? "The request timed out on the server. This may be due to high load. Please try again with a smaller request or wait a few minutes." : "DeskFree service encountered an internal error. Please try again in a few minutes.";
+      return new _DeskFreeError(
+        "server",
+        procedure,
+        `Server error: ${status} ${statusText} \u2014 ${responseText}`,
+        serverErrorMessage,
+        status
+      );
+    }
+    if (status >= 400 && status < 500) {
       return new _DeskFreeError(
         "client",
         procedure,
-        `Bad request: ${status} ${statusText} \u2014 ${responseText}`,
-        "The request was invalid. Please check your input and try again.",
+        `Client error: ${status} ${statusText} \u2014 ${responseText}`,
+        "The request was not accepted by the server. Please check your input and try again.",
         status
       );
     }
@@ -3820,12 +3857,19 @@ var DeskFreeClient = class {
     return this.request("POST", "messages.update", input);
   }
   /**
-   * Send a text message (with optional attachments) to a DeskFree conversation.
+   * Send a text message (with optional attachments or suggestions) to a DeskFree conversation.
    *
-   * @param input - Message content, optional userId, taskId, and attachments
+   * @param input - Message content, optional userId, taskId, attachments, and suggestions
    */
   async sendMessage(input) {
-    this.requireNonEmpty(input.content, "content");
+    if (!input.content && !input.suggestions) {
+      throw new DeskFreeError(
+        "client",
+        "content",
+        "content or suggestions is required",
+        "Missing required parameter: provide content or suggestions."
+      );
+    }
     return this.request("POST", "messages.send", input);
   }
   /** Fetch paginated message history for a conversation. */
@@ -3844,28 +3888,6 @@ var DeskFreeClient = class {
   async getWsTicket() {
     return this.request("POST", "messages.wsTicket", {});
   }
-  // ── Activities ──────────────────────────────────────────────
-  /** Create a new activity — a knowledge container for a type of work. */
-  async createActivity(input) {
-    this.requireNonEmpty(input.name, "name");
-    return this.request("POST", "activities.create", input);
-  }
-  /** Update an activity's name, description, or instructions. */
-  async updateActivity(input) {
-    this.requireNonEmpty(input.activityId, "activityId");
-    return this.request("POST", "activities.update", input);
-  }
-  /** Find activities relevant to a task. Returns scored matches. */
-  async classifyTask(input) {
-    this.requireNonEmpty(input.taskTitle, "taskTitle");
-    return this.request("POST", "activities.classify", input);
-  }
-  /** Link a task to an activity and record learnings. */
-  async learnFromTask(input) {
-    this.requireNonEmpty(input.taskId, "taskId");
-    this.requireNonEmpty(input.activityId, "activityId");
-    return this.request("POST", "activities.learn", input);
-  }
   // ── Tasks ─────────────────────────────────────────────────
   /** Create a new task, optionally with a recurring schedule. */
   async createTask(input) {
@@ -3877,7 +3899,7 @@ var DeskFreeClient = class {
     this.requireNonEmpty(input.taskId, "taskId");
     return this.request("POST", "tasks.claim", input);
   }
-  /** Update the deliverable (markdown content) for a task. */
+  /** Update the deliverable (markdown or HTML content) for a task. */
   async updateDeliverable(input) {
     this.requireNonEmpty(input.taskId, "taskId");
     this.requireNonEmpty(input.deliverable, "deliverable");
@@ -3891,14 +3913,6 @@ var DeskFreeClient = class {
   async reportError(input) {
     return this.request("POST", "agent.reportError", input);
   }
-  /** Get short-lived AWS credentials for S3 workspace access. */
-  async workspaceCredentials() {
-    return this.request("POST", "workspace.credentials", {});
-  }
-  /** Notify DeskFree that workspace files have changed locally. */
-  async workspaceRead(input) {
-    return this.request("GET", "workspace.read", input);
-  }
   /** Get full workspace snapshot — active tasks and recently done. */
   async getState() {
     return this.request("GET", "state.get", {});
@@ -3909,12 +3923,12 @@ var DeskFreeClient = class {
     this.requireNonEmpty(input.model, "model");
     return this.request("POST", "tasks.reportUsage", input);
   }
-  /** Complete a task with an outcome. Moves task to waiting_for_human. */
+  /** Complete a task with an outcome. Moves task to human. */
   async completeTask(input) {
     this.requireNonEmpty(input.taskId, "taskId");
     return this.request("POST", "tasks.complete", input);
   }
-  /** Suggest new tasks for the human to review and approve. */
+  /** Suggest new tasks for the human to review and approve (via messages.send with suggestions). */
   async suggestTasks(input) {
     if (!input.tasks || input.tasks.length === 0) {
       throw new DeskFreeError(
@@ -3924,7 +3938,28 @@ var DeskFreeClient = class {
         "Missing required parameter: tasks. Please provide at least one task to suggest."
       );
     }
-    return this.request("POST", "taskSuggestions.create", input);
+    return this.sendMessage({
+      suggestions: input.tasks,
+      taskId: input.taskId
+    });
+  }
+  /**
+   * Claim a pending evaluation for a task. Atomically sets isWorking=true where
+   * evaluationPending=true and isWorking=false. Returns null if already claimed.
+   */
+  async claimEvaluation(input) {
+    this.requireNonEmpty(input.taskId, "taskId");
+    return this.request("POST", "waysOfWorking.claim", input);
+  }
+  /**
+   * Submit the result of a ways-of-working evaluation.
+   * If hasChanges is true and updatedContent is provided, inserts a new version.
+   * Clears evaluationPending and isWorking on the task.
+   */
+  async submitEvaluation(input) {
+    this.requireNonEmpty(input.taskId, "taskId");
+    this.requireNonEmpty(input.reasoning, "reasoning");
+    return this.request("POST", "waysOfWorking.evaluate", input);
   }
   /**
    * Lightweight health check that verifies connectivity and authentication.
@@ -4528,29 +4563,8 @@ var PLUGIN_VERSION = JSON.parse(
   readFileSync(resolve(__dirname, "..", "package.json"), "utf-8")
 ).version;
 
-// src/workspace.ts
-import { readdirSync, readFileSync as readFileSync2, statSync } from "fs";
-import { join as join2, relative } from "path";
-var MAX_FILE_SIZE = 100 * 1024;
-function resolveWorkspacePath(cfg) {
-  try {
-    const agents = cfg.agents;
-    if (!agents) return null;
-    const defaults = agents.defaults;
-    if (!defaults) return null;
-    const workspace = defaults.workspace;
-    if (typeof workspace === "string" && workspace.length > 0) {
-      return workspace;
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
 // src/gateway.ts
-import { spawn } from "child_process";
-import { mkdirSync, readFileSync as readFileSync3, writeFileSync } from "fs";
+import { mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { dirname as dirname2 } from "path";
 
 // ../node_modules/ws/wrapper.mjs
@@ -4576,65 +4590,6 @@ function getActiveTaskId() {
 function clearCompletedTaskId() {
   completedTaskId = null;
 }
-async function runS3CommandWithCredentials(client, buildCommand, workspacePath, log) {
-  try {
-    const creds = await client.workspaceCredentials();
-    const command = buildCommand(creds.s3Uri);
-    const env = {
-      ...process.env,
-      AWS_ACCESS_KEY_ID: creds.accessKeyId,
-      AWS_SECRET_ACCESS_KEY: creds.secretAccessKey,
-      AWS_SESSION_TOKEN: creds.sessionToken,
-      AWS_DEFAULT_REGION: creds.region
-    };
-    return new Promise((resolve2, reject) => {
-      const child = spawn("aws", command, {
-        env,
-        cwd: workspacePath,
-        stdio: "pipe"
-      });
-      let stdout = "";
-      let stderr = "";
-      child.stdout?.on("data", (data) => {
-        stdout += data.toString();
-      });
-      child.stderr?.on("data", (data) => {
-        stderr += data.toString();
-      });
-      child.on("close", (code) => {
-        if (code === 0) {
-          log.info(`S3 command succeeded: ${command.join(" ")}`);
-          if (stdout.trim()) {
-            log.debug(`S3 stdout: ${stdout.trim()}`);
-          }
-          resolve2(true);
-        } else {
-          log.warn(`S3 command failed (exit ${code}): ${command.join(" ")}`);
-          if (stderr.trim()) {
-            log.warn(`S3 stderr: ${stderr.trim()}`);
-          }
-          reject(
-            new Error(
-              `AWS CLI command failed with exit code ${code}: ${stderr}`
-            )
-          );
-        }
-      });
-      child.on("error", (err) => {
-        log.warn(`S3 command spawn error: ${err.message}`);
-        reject(err);
-      });
-    });
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    log.warn(`Failed to get S3 credentials or run command: ${message}`);
-    reportError("warn", `S3 workspace command failed: ${message}`, {
-      component: "gateway",
-      event: "workspace_sync_failed"
-    });
-    return false;
-  }
-}
 var PING_INTERVAL_MS = 5 * 60 * 1e3;
 var POLL_FALLBACK_INTERVAL_MS = 30 * 1e3;
 var WS_CONNECTION_TIMEOUT_MS = 30 * 1e3;
@@ -4709,14 +4664,14 @@ function enqueuePoll(client, ctx, getCursor, setCursor, log, account) {
   const accountId = ctx.accountId;
   const prev = pollChains.get(accountId) ?? Promise.resolve();
   const next = prev.then(async () => {
-    const newCursor = await pollAndDeliver(
+    const result = await pollAndDeliver(
       client,
       ctx,
       getCursor(),
       log,
       account
     );
-    if (newCursor) setCursor(newCursor);
+    if (result.cursor) setCursor(result.cursor);
   }).catch((err) => {
     const message = err instanceof Error ? err.message : String(err);
     log.error(`Poll error: ${message}`);
@@ -4753,7 +4708,7 @@ function loadCursor(ctx) {
     const cursorPath = resolvePluginStorePath(
       `cursors/${ctx.accountId}/cursor`
     );
-    return readFileSync3(cursorPath, "utf-8").trim() || null;
+    return readFileSync2(cursorPath, "utf-8").trim() || null;
   } catch {
     return null;
   }
@@ -4930,34 +4885,6 @@ async function runWebSocketConnection(opts) {
         const msg = err instanceof Error ? err.message : String(err);
         log.warn(`Failed to send statusUpdate: ${msg}`);
       });
-      try {
-        const cfg = getDeskFreeRuntime().config.loadConfig();
-        const workspacePath = resolveWorkspacePath(
-          cfg
-        );
-        if (workspacePath) {
-          const success = await runS3CommandWithCredentials(
-            client,
-            (s3Uri) => ["s3", "sync", ".", s3Uri, "--only-show-errors"],
-            workspacePath,
-            log
-          );
-          if (success) {
-            log.info(
-              `Workspace sync: uploaded files from ${workspacePath} to S3`
-            );
-          } else {
-            log.warn("Workspace sync: failed to upload files to S3");
-          }
-        } else {
-          log.debug(
-            "Workspace sync: no workspace path configured (agents.defaults.workspace)"
-          );
-        }
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        log.warn(`Workspace sync failed: ${msg}`);
-      }
       enqueuePoll(
         client,
         ctx,
@@ -4984,85 +4911,6 @@ async function runWebSocketConnection(opts) {
           return;
         }
         if (msg.action === "notify") {
-          const notifyMsg = msg;
-          if (notifyMsg.hint === "workspace.fileChanged") {
-            const paths = notifyMsg.paths ?? [];
-            log.info(
-              `Workspace file(s) changed by human: ${paths.join(", ") || "(all)"}`
-            );
-            try {
-              const cfg = getDeskFreeRuntime().config.loadConfig();
-              const workspacePath = resolveWorkspacePath(
-                cfg
-              );
-              if (workspacePath && paths.length > 0) {
-                for (const filePath of paths) {
-                  try {
-                    const success = await runS3CommandWithCredentials(
-                      client,
-                      (s3Uri) => [
-                        "s3",
-                        "cp",
-                        `${s3Uri}/${filePath}`,
-                        filePath,
-                        "--only-show-errors"
-                      ],
-                      workspacePath,
-                      log
-                    );
-                    if (success) {
-                      log.info(`Updated local file: ${filePath}`);
-                    } else {
-                      log.warn(
-                        `Failed to download workspace file: ${filePath}`
-                      );
-                    }
-                  } catch (err) {
-                    const errMsg = err instanceof Error ? err.message : String(err);
-                    log.warn(
-                      `Failed to download workspace file ${filePath}: ${errMsg}`
-                    );
-                  }
-                }
-              } else if (!workspacePath) {
-                log.warn(
-                  "Cannot sync workspace files: workspace path not configured"
-                );
-              }
-            } catch (err) {
-              const errMsg = err instanceof Error ? err.message : String(err);
-              log.warn(`Workspace file change handling failed: ${errMsg}`);
-            }
-          }
-          if (notifyMsg.hint === "workspace.uploadRequested") {
-            log.info("Workspace upload requested");
-            try {
-              const cfg = getDeskFreeRuntime().config.loadConfig();
-              const workspacePath = resolveWorkspacePath(
-                cfg
-              );
-              if (workspacePath) {
-                const success = await runS3CommandWithCredentials(
-                  client,
-                  (s3Uri) => ["s3", "sync", ".", s3Uri, "--only-show-errors"],
-                  workspacePath,
-                  log
-                );
-                if (success) {
-                  log.info(`Workspace upload: synced ${workspacePath} to S3`);
-                } else {
-                  log.warn("Workspace upload: failed to sync to S3");
-                }
-              } else {
-                log.warn(
-                  "Cannot upload workspace: workspace path not configured"
-                );
-              }
-            } catch (err) {
-              const errMsg = err instanceof Error ? err.message : String(err);
-              log.warn(`Workspace upload failed: ${errMsg}`);
-            }
-          }
           enqueuePoll(
             client,
             ctx,
@@ -5176,11 +5024,9 @@ async function runPollingFallback(opts) {
   log.info("Running in polling fallback mode.");
   let consecutiveFailures = 0;
   while (!ctx.abortSignal.aborted && iterations < maxIterations) {
-    const newCursor = await pollAndDeliver(client, ctx, cursor, log);
-    if (newCursor) {
-      cursor = newCursor;
-      consecutiveFailures = 0;
-    } else if (newCursor === null && cursor) {
+    const result = await pollAndDeliver(client, ctx, cursor, log);
+    if (result.ok) {
+      if (result.cursor) cursor = result.cursor;
       consecutiveFailures = 0;
     } else {
       consecutiveFailures++;
@@ -5244,9 +5090,9 @@ async function pollAndDeliver(client, ctx, cursor, log, account) {
         const msg = err instanceof Error ? err.message : String(err);
         log.warn(`Failed to send welcome message: ${msg}`);
       }
-      return response.cursor ?? SEED;
+      return { cursor: response.cursor ?? SEED, ok: true };
     }
-    if (response.items.length === 0) return null;
+    if (response.items.length === 0) return { cursor: null, ok: true };
     const newItems = response.items.filter(
       (m) => !deliveredMessageIds.has(m.messageId)
     );
@@ -5257,7 +5103,7 @@ async function pollAndDeliver(client, ctx, cursor, log, account) {
       if (response.cursor) {
         saveCursor(ctx, response.cursor, log);
       }
-      return response.cursor;
+      return { cursor: response.cursor, ok: true };
     }
     log.info(
       `Received ${newItems.length} new message(s) (${response.items.length - newItems.length} duplicate(s) skipped).`
@@ -5287,7 +5133,7 @@ async function pollAndDeliver(client, ctx, cursor, log, account) {
     if (response.cursor) {
       saveCursor(ctx, response.cursor, log);
     }
-    return response.cursor;
+    return { cursor: response.cursor, ok: true };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log.warn(`Poll failed: ${message}`);
@@ -5295,7 +5141,7 @@ async function pollAndDeliver(client, ctx, cursor, log, account) {
       component: "gateway",
       event: "poll_failed"
     });
-    return null;
+    return { cursor: null, ok: false };
   }
 }
 
@@ -7909,68 +7755,12 @@ var Type = type_exports2;
 var ORCHESTRATOR_TOOLS = {
   STATE: {
     name: "deskfree_state",
-    description: "Get full workspace state \u2014 all activities, tasks, recently done tasks. Use to assess what needs attention.",
+    description: "Get full workspace state \u2014 all tasks, recently done tasks. Use to assess what needs attention.",
     parameters: Type.Object({})
   },
-  CREATE_ACTIVITY: {
-    name: "deskfree_create_activity",
-    description: "Create an activity \u2014 a knowledge container for a type of work. Activities accumulate learnings from tasks. Returns the created activity.",
-    parameters: Type.Object({
-      name: Type.String({ description: "Activity name (max 200 chars)" }),
-      description: Type.Optional(
-        Type.String({
-          description: "What this activity covers"
-        })
-      ),
-      instructions: Type.Optional(
-        Type.String({
-          description: "Initial instructions/knowledge for this activity"
-        })
-      )
-    })
-  },
-  UPDATE_ACTIVITY: {
-    name: "deskfree_update_activity",
-    description: "Update an activity's name, description, or instructions.",
-    parameters: Type.Object({
-      activityId: Type.String({ description: "Activity ID to update" }),
-      name: Type.Optional(
-        Type.String({ description: "New name (max 200 chars)" })
-      ),
-      description: Type.Optional(
-        Type.String({ description: "Updated description" })
-      ),
-      instructions: Type.Optional(
-        Type.String({ description: "Updated instructions" })
-      )
-    })
-  },
-  CLASSIFY_TASK: {
-    name: "deskfree_classify_task",
-    description: "Find activities relevant to a task. Returns matching activities whose instructions should inform the task.",
-    parameters: Type.Object({
-      taskTitle: Type.String({ description: "Task title to classify" }),
-      taskInstructions: Type.Optional(
-        Type.String({ description: "Task instructions for better matching" })
-      )
-    })
-  },
-  LEARN_FROM_TASK: {
-    name: "deskfree_learn_from_task",
-    description: "After completing a task, link it to an activity and record what was learned. Appends new instructions to the activity.",
-    parameters: Type.Object({
-      taskId: Type.String({ description: "Task UUID" }),
-      activityId: Type.String({ description: "Activity ID to learn into" }),
-      additionalInstructions: Type.Optional(
-        Type.String({
-          description: "New learnings to append to the activity instructions"
-        })
-      )
-    })
-  },
   CREATE_TASK: {
     name: "deskfree_create_task",
-    description: "Create a new task (starts as ready_for_bot).",
+    description: "Create a new task (starts as bot).",
     parameters: Type.Object({
       title: Type.String({ description: "Task title (max 200 chars)" }),
       instructions: Type.Optional(
@@ -7980,22 +7770,29 @@ var ORCHESTRATOR_TOOLS = {
   },
   START_TASK: {
     name: "deskfree_start_task",
-    description: "Claim a ready_for_bot task and start working. Returns full context (instructions, deliverable, message history).",
+    description: "Claim a bot task (isWorking=false) and start working. Returns full context (instructions, deliverable, message history).",
     parameters: Type.Object({
       taskId: Type.String({ description: "Task UUID to claim" })
     })
   },
   UPDATE_DELIVERABLE: {
     name: "deskfree_update_deliverable",
-    description: "Update task deliverable markdown. Build incrementally as you work.",
+    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.',
     parameters: Type.Object({
       taskId: Type.String({ description: "Task UUID" }),
-      deliverable: Type.String({ description: "Markdown deliverable content" })
+      deliverable: Type.String({
+        description: "Deliverable content (markdown or HTML depending on format)"
+      }),
+      format: 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.'
+        })
+      )
     })
   },
   COMPLETE_TASK: {
     name: "deskfree_complete_task",
-    description: 'Finish a task. Outcome "done" = work complete for review. Outcome "blocked" = need human input. Both move to waiting_for_human.',
+    description: 'Finish a task. Outcome "done" = work complete for review. 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")], {
@@ -8005,38 +7802,58 @@ var ORCHESTRATOR_TOOLS = {
   },
   SEND_MESSAGE: {
     name: "deskfree_send_message",
-    description: "Send a message in the task thread (progress update, question, status report).",
+    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.",
     parameters: Type.Object({
-      content: Type.String({ description: "Message content" }),
+      content: Type.Optional(
+        Type.String({
+          description: "Message content. Required unless suggestions is provided."
+        })
+      ),
       taskId: Type.Optional(
         Type.String({
           description: "Task UUID (optional if context provides it)"
         })
+      ),
+      suggestions: Type.Optional(
+        Type.Array(
+          Type.Object({
+            title: Type.String({ description: "Task title (max 200 chars)" }),
+            instructions: Type.Optional(
+              Type.String({
+                description: "Detailed instructions for the suggested task"
+              })
+            )
+          }),
+          {
+            description: "Suggest tasks for human review (1-10). The human will see approve/reject buttons for each. Provide this instead of content.",
+            minItems: 1,
+            maxItems: 10
+          }
+        )
       )
     })
   },
-  SUGGEST_TASKS: {
-    name: "deskfree_suggest_tasks",
-    description: "Suggest new tasks for the human to review and approve. Use when you notice work that should be done but is outside your current task scope. The human will see approve/reject buttons for each suggestion.",
+  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.",
     parameters: Type.Object({
-      tasks: Type.Array(
-        Type.Object({
-          title: Type.String({ description: "Task title (max 200 chars)" }),
-          instructions: Type.Optional(
-            Type.String({
-              description: "Detailed instructions for the suggested task"
-            })
-          )
-        }),
-        {
-          description: "List of tasks to suggest (1-10)",
-          minItems: 1,
-          maxItems: 10
-        }
-      ),
-      taskId: Type.Optional(
+      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.",
+    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"
+      }),
+      updatedContent: Type.Optional(
         Type.String({
-          description: "Current task UUID \u2014 links suggestions to the task you are working on"
+          description: "Full updated ways-of-working markdown (required if hasChanges=true)"
         })
       )
     })
@@ -8046,8 +7863,7 @@ var WORKER_TOOLS = {
   UPDATE_DELIVERABLE: ORCHESTRATOR_TOOLS.UPDATE_DELIVERABLE,
   COMPLETE_TASK: ORCHESTRATOR_TOOLS.COMPLETE_TASK,
   SEND_MESSAGE: ORCHESTRATOR_TOOLS.SEND_MESSAGE,
-  SUGGEST_TASKS: ORCHESTRATOR_TOOLS.SUGGEST_TASKS,
-  LEARN_FROM_TASK: ORCHESTRATOR_TOOLS.LEARN_FROM_TASK
+  SUBMIT_EVALUATION: ORCHESTRATOR_TOOLS.SUBMIT_EVALUATION
 };
 var CHANNEL_META = {
   name: "DeskFree",
@@ -8079,6 +7895,131 @@ var STATUS_MESSAGES = {
 function getChannelConfig(cfg) {
   return cfg?.channels?.deskfree ?? null;
 }
+function validateStringField(value, fieldName) {
+  if (!value) {
+    return { trimmed: "", error: `${fieldName} is required` };
+  }
+  if (typeof value !== "string") {
+    return { trimmed: "", error: `${fieldName} must be a string` };
+  }
+  const trimmed = value.trim();
+  if (trimmed !== value) {
+    return {
+      trimmed: "",
+      error: `${fieldName} must not have leading or trailing whitespace`
+    };
+  }
+  return { trimmed };
+}
+function isLocalDevelopmentHost(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname.endsWith(".local") || hostname.endsWith(".localhost") || /^192\.168\./.test(hostname) || /^10\./.test(hostname) || /^172\.(1[6-9]|2\d|3[01])\./.test(hostname);
+}
+function validateBotToken(value) {
+  const { trimmed, error } = validateStringField(value, "Bot token");
+  if (error) return error;
+  if (!trimmed.startsWith("bot_")) {
+    return 'Bot token must start with "bot_" (check your DeskFree bot configuration)';
+  }
+  if (trimmed.length < 10) {
+    return "Bot token appears to be incomplete (minimum 10 characters expected)";
+  }
+  if (trimmed.length > 200) {
+    return "Bot token appears to be invalid (maximum 200 characters expected)";
+  }
+  if (!/^bot_[a-zA-Z0-9_-]+$/.test(trimmed)) {
+    return 'Bot token contains invalid characters. Only alphanumeric, underscore, and dash are allowed after "bot_"';
+  }
+  if (trimmed.includes(" ") || trimmed.includes("\n") || trimmed.includes("	")) {
+    return "Bot token contains whitespace characters. Please copy the token exactly as shown in DeskFree.";
+  }
+  if (trimmed === "bot_your_token_here" || trimmed === "bot_example") {
+    return "Please replace the placeholder with your actual bot token from DeskFree";
+  }
+  return null;
+}
+function validateApiUrl(value) {
+  const { trimmed, error } = validateStringField(value, "API URL");
+  if (error) return error;
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Invalid URL format";
+    return `API URL must be a valid URL: ${message}`;
+  }
+  if (url.protocol !== "https:") {
+    return "API URL must use HTTPS protocol for security. Make sure your DeskFree deployment supports HTTPS.";
+  }
+  if (!url.hostname) {
+    return "API URL must have a valid hostname";
+  }
+  if (isLocalDevelopmentHost(url.hostname)) {
+    if (process.env.NODE_ENV === "production") {
+      return "API URL cannot use localhost or private IP addresses in production. Please use a publicly accessible URL.";
+    }
+  }
+  if (url.hostname.includes("..") || url.hostname.startsWith(".")) {
+    return "API URL hostname appears to be malformed. Please check for typos.";
+  }
+  if (url.pathname && url.pathname !== "/" && !url.pathname.includes("/api") && !url.pathname.includes("/v1")) {
+  }
+  return null;
+}
+function validateWebSocketUrl(value) {
+  const { trimmed, error } = validateStringField(value, "WebSocket URL");
+  if (error) return error;
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Invalid URL format";
+    return `WebSocket URL must be a valid URL: ${message}`;
+  }
+  if (!["ws:", "wss:"].includes(url.protocol)) {
+    return "WebSocket URL must use ws:// or wss:// protocol";
+  }
+  if (!url.hostname) {
+    return "WebSocket URL must have a valid hostname";
+  }
+  if (isLocalDevelopmentHost(url.hostname)) {
+    if (process.env.NODE_ENV === "production") {
+      return "WebSocket URL cannot use localhost or private IP addresses in production. Please use a publicly accessible URL.";
+    }
+  }
+  if (url.protocol === "ws:" && !isLocalDevelopmentHost(url.hostname)) {
+  }
+  if (url.hostname.includes("..") || url.hostname.startsWith(".")) {
+    return "WebSocket URL hostname appears to be malformed. Please check for typos.";
+  }
+  return null;
+}
+function validateUserId(value) {
+  const { trimmed, error } = validateStringField(value, "User ID");
+  if (error) return error;
+  const normalizedUserId = trimmed.toUpperCase();
+  if (normalizedUserId !== trimmed) {
+    return "User ID should be uppercase (will be automatically converted)";
+  }
+  if (!/^[UBPT][A-Z0-9]{10}$/.test(normalizedUserId)) {
+    if (normalizedUserId.length !== 11) {
+      return `User ID must be exactly 11 characters long (got: ${normalizedUserId.length}). Example: U9QF3C6X1A`;
+    }
+    const prefix = normalizedUserId.charAt(0);
+    if (!"UBPT".includes(prefix)) {
+      return `User ID must start with U (user), B (bot), P (project), or T (team). Got: "${prefix}". Check your DeskFree account settings.`;
+    }
+    if (!/^[A-Z0-9]+$/.test(normalizedUserId.slice(1))) {
+      return "User ID contains invalid characters. Only letters A-Z and numbers 0-9 are allowed after the prefix.";
+    }
+    return "User ID must be a valid DeskFree ID format: one letter (U/B/P/T) + 10 alphanumeric characters (e.g. U9QF3C6X1A)";
+  }
+  if (["U0000000000", "B0000000000", "P0000000000", "T0000000000"].includes(
+    normalizedUserId
+  )) {
+    return "Please replace the placeholder with your actual User ID from DeskFree account settings";
+  }
+  return null;
+}
 var deskFreePlugin = {
   id: "deskfree",
   meta: CHANNEL_META,
@@ -8265,102 +8206,14 @@ var deskFreePlugin = {
     },
     validateInput(params) {
       const { input } = params;
-      if (!input.botToken) {
-        return "Bot token is required";
-      }
-      if (typeof input.botToken !== "string") {
-        return "Bot token must be a string";
-      }
-      const botTokenTrimmed = input.botToken.trim();
-      if (botTokenTrimmed !== input.botToken) {
-        return "Bot token must not have leading or trailing whitespace";
-      }
-      if (!botTokenTrimmed.startsWith("bot_")) {
-        return 'Bot token must start with "bot_"';
-      }
-      if (botTokenTrimmed.length < 10) {
-        return "Bot token appears to be too short (minimum 10 characters)";
-      }
-      if (botTokenTrimmed.length > 100) {
-        return "Bot token appears to be too long (maximum 100 characters)";
-      }
-      if (!/^bot_[a-zA-Z0-9_-]+$/.test(botTokenTrimmed)) {
-        return 'Bot token contains invalid characters (only alphanumeric, underscore, and dash allowed after "bot_")';
-      }
-      if (!input.apiUrl) {
-        return "API URL is required";
-      }
-      if (typeof input.apiUrl !== "string") {
-        return "API URL must be a string";
-      }
-      const apiUrlTrimmed = input.apiUrl.trim();
-      if (apiUrlTrimmed !== input.apiUrl) {
-        return "API URL must not have leading or trailing whitespace";
-      }
-      try {
-        const apiUrl = new URL(apiUrlTrimmed);
-        if (apiUrl.protocol !== "https:") {
-          return "API URL must use HTTPS protocol for security";
-        }
-        if (!apiUrl.hostname) {
-          return "API URL must have a valid hostname";
-        }
-        if (apiUrl.hostname === "localhost" || apiUrl.hostname === "127.0.0.1") {
-          return "API URL cannot use localhost (use a publicly accessible URL)";
-        }
-        if (apiUrl.pathname && !apiUrl.pathname.endsWith("/")) {
-        }
-      } catch (err) {
-        const message = err instanceof Error ? err.message : "Invalid URL format";
-        return `API URL must be a valid URL: ${message}`;
-      }
-      if (!input.wsUrl) {
-        return "WebSocket URL is required";
-      }
-      if (typeof input.wsUrl !== "string") {
-        return "WebSocket URL must be a string";
-      }
-      const wsUrlTrimmed = input.wsUrl.trim();
-      if (wsUrlTrimmed !== input.wsUrl) {
-        return "WebSocket URL must not have leading or trailing whitespace";
-      }
-      try {
-        const wsUrl = new URL(wsUrlTrimmed);
-        if (!["ws:", "wss:"].includes(wsUrl.protocol)) {
-          return "WebSocket URL must use ws:// or wss:// protocol";
-        }
-        if (!wsUrl.hostname) {
-          return "WebSocket URL must have a valid hostname";
-        }
-        if (wsUrl.hostname === "localhost" || wsUrl.hostname === "127.0.0.1") {
-          return "WebSocket URL cannot use localhost (use a publicly accessible URL)";
-        }
-        if (wsUrl.protocol === "ws:" && wsUrl.hostname !== "localhost") {
-        }
-      } catch (err) {
-        const message = err instanceof Error ? err.message : "Invalid URL format";
-        return `WebSocket URL must be a valid URL: ${message}`;
-      }
-      if (!input.userId) {
-        return "User ID is required";
-      }
-      if (typeof input.userId !== "string") {
-        return "User ID must be a string";
-      }
-      const userIdTrimmed = input.userId.trim().toUpperCase();
-      if (userIdTrimmed !== input.userId.toUpperCase()) {
-        return "User ID must not have leading or trailing whitespace and should be uppercase";
-      }
-      if (!/^[UBPT][A-Z0-9]{10}$/.test(userIdTrimmed)) {
-        const prefix = userIdTrimmed.charAt(0);
-        if (!"UBPT".includes(prefix)) {
-          return "User ID must start with U, B, P, or T (got: " + prefix + ")";
-        }
-        if (userIdTrimmed.length !== 11) {
-          return `User ID must be exactly 11 characters long (got: ${userIdTrimmed.length})`;
-        }
-        return "User ID must be a valid DeskFree ID format: one letter (U/B/P/T) + 10 alphanumeric characters (e.g. U9QF3C6X1A)";
-      }
+      const botTokenError = validateBotToken(input.botToken);
+      if (botTokenError) return botTokenError;
+      const apiUrlError = validateApiUrl(input.apiUrl);
+      if (apiUrlError) return apiUrlError;
+      const wsUrlError = validateWebSocketUrl(input.wsUrl);
+      if (wsUrlError) return wsUrlError;
+      const userIdError = validateUserId(input.userId);
+      if (userIdError) return userIdError;
       return null;
     }
   },
@@ -8570,11 +8423,11 @@ var deskFreePlugin = {
 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. Activities are memory \u2014 use \`deskfree_classify_task\` to find relevant knowledge, \`deskfree_learn_from_task\` to record learnings.
+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 5 tools: update_deliverable, complete_task, send_message, suggest_tasks, learn_from_task.`;
+6. Sub-agents get 4 tools: update_deliverable, complete_task, send_message (also supports suggestions), submit_evaluation.`;
 function getDeskFreeContext() {
   return `${DESKFREE_AGENT_DIRECTIVE}
 
@@ -8781,121 +8634,6 @@ function createOrchestratorTools(api) {
         }
       }
     },
-    {
-      ...ORCHESTRATOR_TOOLS.CREATE_ACTIVITY,
-      async execute(_id, params) {
-        try {
-          const name = validateStringParam(params, "name", true);
-          const description = validateStringParam(params, "description", false);
-          const instructions = validateStringParam(
-            params,
-            "instructions",
-            false
-          );
-          const result = await client.createActivity({
-            name,
-            description,
-            instructions
-          });
-          return formatConfirmation(
-            `Created activity "${result.activity.name}" (${result.activity.id})`,
-            [
-              "Activity is ready to accumulate learnings from tasks",
-              "Use deskfree_classify_task to match tasks to this activity"
-            ],
-            result.activity
-          );
-        } catch (err) {
-          return errorResult(err);
-        }
-      }
-    },
-    {
-      ...ORCHESTRATOR_TOOLS.UPDATE_ACTIVITY,
-      async execute(_id, params) {
-        try {
-          const activityId = validateStringParam(params, "activityId", true);
-          const name = validateStringParam(params, "name", false);
-          const description = validateStringParam(params, "description", false);
-          const instructions = validateStringParam(
-            params,
-            "instructions",
-            false
-          );
-          const result = await client.updateActivity({
-            activityId,
-            name,
-            description,
-            instructions
-          });
-          return formatConfirmation(
-            `Updated activity "${result.activity.name}"`,
-            ["Activity instructions updated"],
-            result.activity
-          );
-        } catch (err) {
-          return errorResult(err);
-        }
-      }
-    },
-    {
-      ...ORCHESTRATOR_TOOLS.CLASSIFY_TASK,
-      async execute(_id, params) {
-        try {
-          const taskTitle = validateStringParam(params, "taskTitle", true);
-          const taskInstructions = validateStringParam(
-            params,
-            "taskInstructions",
-            false
-          );
-          const result = await client.classifyTask({
-            taskTitle,
-            taskInstructions
-          });
-          return formatConfirmation(
-            `Found ${result.matches.length} matching activit${result.matches.length === 1 ? "y" : "ies"}`,
-            result.matches.length > 0 ? [
-              "Use activity instructions to inform the task",
-              "After completing the task, use deskfree_learn_from_task to record learnings"
-            ] : [
-              "No matching activities found \u2014 consider creating one with deskfree_create_activity"
-            ],
-            { matches: result.matches, suggestNew: result.suggestNew }
-          );
-        } catch (err) {
-          return errorResult(err);
-        }
-      }
-    },
-    {
-      ...ORCHESTRATOR_TOOLS.LEARN_FROM_TASK,
-      async execute(_id, params) {
-        try {
-          const taskId = validateStringParam(params, "taskId", true);
-          const activityId = validateStringParam(params, "activityId", true);
-          const additionalInstructions = validateStringParam(
-            params,
-            "additionalInstructions",
-            false
-          );
-          const result = await client.learnFromTask({
-            taskId,
-            activityId,
-            additionalInstructions
-          });
-          return formatConfirmation(
-            `Recorded learnings to activity "${result.activity.name}"`,
-            [
-              "Activity instructions have been updated with new learnings",
-              "Future tasks matching this activity will benefit from these learnings"
-            ],
-            result.activity
-          );
-        } catch (err) {
-          return errorResult(err);
-        }
-      }
-    },
     {
       ...ORCHESTRATOR_TOOLS.CREATE_TASK,
       async execute(_id, params) {
@@ -8965,7 +8703,13 @@ function createOrchestratorTools(api) {
         try {
           const taskId = validateStringParam(params, "taskId", true);
           const deliverable = validateStringParam(params, "deliverable", true);
-          await client.updateDeliverable({ taskId, deliverable });
+          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"
@@ -9011,8 +8755,44 @@ function createOrchestratorTools(api) {
       ...ORCHESTRATOR_TOOLS.SEND_MESSAGE,
       async execute(_id, params) {
         try {
-          const content = validateStringParam(params, "content", true);
+          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}` : ""}`,
@@ -9027,37 +8807,73 @@ function createOrchestratorTools(api) {
       }
     },
     {
-      ...ORCHESTRATOR_TOOLS.SUGGEST_TASKS,
+      ...ORCHESTRATOR_TOOLS.CLAIM_EVALUATION,
       async execute(_id, params) {
         try {
-          const rawTasks = params?.tasks;
-          if (!Array.isArray(rawTasks) || rawTasks.length === 0) {
-            throw new Error('Parameter "tasks" must be a non-empty array');
+          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 tasks = rawTasks.map((t, i) => {
-            if (typeof t !== "object" || t === null) {
-              throw new Error(`tasks[${i}] must be an object`);
-            }
-            const task = t;
-            const title = task["title"];
-            if (typeof title !== "string" || title.trim() === "") {
-              throw new Error(`tasks[${i}].title must be a non-empty string`);
-            }
-            const instructions = task["instructions"];
-            return {
-              title: title.trim(),
-              instructions: typeof instructions === "string" ? instructions : void 0
-            };
+          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);
+        }
+      }
+    },
+    {
+      ...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(() => {
           });
-          const taskId = validateStringParam(params, "taskId", false);
-          const result = await client.suggestTasks({ tasks, taskId });
           return formatConfirmation(
-            `Suggested ${result.suggested} task${result.suggested === 1 ? "" : "s"} for human review`,
-            [
-              "The human will see approve/reject buttons for each suggestion",
-              "Continue working on the current task"
-            ],
-            { suggestionIds: result.suggestionIds }
+            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);