@joshski/dust 0.1.90 → 0.1.92

package/dist/bucket/tool-execution-protocol.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Tool execution protocol types for the WebSocket messages between
+ * dust clients and dustbucket servers.
+ *
+ * These types define the wire format. Both sides must agree on this protocol.
+ * Import from '@joshski/dust/types' for downstream implementations.
+ */
+/**
+ * Client-to-server message requesting tool execution.
+ *
+ * Sent over the bucket WebSocket when an agent invokes `dust bucket tool <name>`.
+ * The `tool` field identifies the server-defined tool by name.
+ * The `arguments` field contains named parameters matching the tool definition.
+ * The `repositoryId` identifies the repository context (numeric server-side ID).
+ */
+export interface ToolExecutionRequestMessage {
+    type: 'tool-execution-request';
+    requestId: string;
+    tool: string;
+    repositoryId: number;
+    arguments: Record<string, unknown>;
+}
+export interface ToolExecutionSuccessResult {
+    type: 'success';
+    data: unknown;
+}
+export interface ToolExecutionToolNotFoundResult {
+    type: 'tool-not-found';
+    message: string;
+}
+export interface ToolExecutionErrorResult {
+    type: 'error';
+    message: string;
+}
+export type ToolExecutionResult = ToolExecutionSuccessResult | ToolExecutionToolNotFoundResult | ToolExecutionErrorResult;
+/**
+ * Server-to-client message with the result of a tool execution request.
+ *
+ * The `requestId` correlates this response to the original request.
+ * The `result` is a discriminated union on the `type` field.
+ */
+export interface ToolExecutionResultMessage {
+    type: 'tool-execution-result';
+    requestId: string;
+    result: ToolExecutionResult;
+}
+export declare function isToolExecutionResultMessage(payload: unknown): payload is ToolExecutionResultMessage;
+export declare function isToolExecutionRequestMessage(payload: unknown): payload is ToolExecutionRequestMessage;

package/dist/dust.js

@@ -500,7 +500,7 @@ async function loadSettings(cwd, fileSystem) {
 }
 
 // lib/version.ts
-var DUST_VERSION = "0.1.90";
+var DUST_VERSION = "0.1.92";
 
 // lib/session.ts
 var DUST_UNATTENDED = "DUST_UNATTENDED";
@@ -2072,6 +2072,7 @@ import { spawn as nodeSpawn5 } from "node:child_process";
 import { accessSync, statSync } from "node:fs";
 import { chmod, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { homedir as homedir2 } from "node:os";
+import { basename as basename2, resolve } from "node:path";
 
 // lib/bucket/auth.ts
 import { join as join5 } from "node:path";
@@ -4570,8 +4571,11 @@ function formatToolsSection(tools) {
     return "";
   }
   const lines = [];
+  lines.push("");
   lines.push("## Available Tools");
   lines.push("");
+  lines.push("Use these tools where it makes sense in the execution of this task:");
+  lines.push("");
   for (const tool of tools) {
     lines.push(formatTool(tool));
     lines.push("");
@@ -5440,6 +5444,18 @@ var SGR_MOUSE_RE2 = new RegExp(String.raw`^\x1b\[<(\d+);\d+;\d+[Mm]$`);
 function isRecord3(value) {
   return typeof value === "object" && value !== null;
 }
+function isValidResultType(value) {
+  return value === "success" || value === "tool-not-found" || value === "error";
+}
+function isValidResult(value) {
+  if (!isRecord3(value))
+    return false;
+  if (!isValidResultType(value.type))
+    return false;
+  if (value.type === "success")
+    return true;
+  return typeof value.message === "string";
+}
 function isToolExecutionResultMessage(payload) {
   if (!isRecord3(payload))
     return false;
@@ -5448,16 +5464,7 @@ function isToolExecutionResultMessage(payload) {
   if (typeof payload.requestId !== "string" || payload.requestId.length === 0) {
     return false;
   }
-  if (payload.status !== "success" && payload.status !== "tool-not-found" && payload.status !== "error") {
-    return false;
-  }
-  if (payload.output !== undefined && typeof payload.output !== "string") {
-    return false;
-  }
-  if (payload.error !== undefined && typeof payload.error !== "string") {
-    return false;
-  }
-  return true;
+  return isValidResult(payload.result);
 }
 
 // lib/cli/commands/bucket.ts
@@ -5594,7 +5601,7 @@ function createDefaultBucketDependencies() {
     getTerminalSize: defaultGetTerminalSize,
     writeStdout: defaultWriteStdout,
     isTTY: process.stdout.isTTY ?? false,
-    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    sleep: (ms) => new Promise((resolve2) => setTimeout(resolve2, ms)),
     getReposDir: () => getReposDir(process.env, homedir2()),
     auth: {
       createServer: createLocalServer,
@@ -5738,8 +5745,8 @@ function createTUIContext(state, context, useTUI) {
 function waitForConnection(token, bucketDeps) {
   const wsUrl = getWebSocketUrl();
   const ws = bucketDeps.createWebSocket(wsUrl, token);
-  return new Promise((resolve, reject) => {
-    ws.onopen = () => resolve(ws);
+  return new Promise((resolve2, reject) => {
+    ws.onopen = () => resolve2(ws);
     ws.onerror = (error) => reject(new Error(error.message));
     ws.onclose = (event) => reject(new Error(`Connection closed (code ${event.code})`));
   });
@@ -6134,35 +6141,73 @@ async function bucketWorker(dependencies, bucketDeps = createDefaultBucketDepend
   } catch {
     state.ui.connectedHost = wsUrl;
   }
+  function findRepoPathByRepositoryId(repositories, repositoryId) {
+    for (const repoState of repositories.values()) {
+      if (repoState.repository.id === repositoryId) {
+        return repoState.path;
+      }
+    }
+    return;
+  }
   let tuiHandle;
   let cleanupKeypress;
   let cleanupSignals;
-  const forwardToolExecution = (request) => {
+  const forwardToolExecution = async (request) => {
     const ws = state.ws;
     if (!ws || ws.readyState !== WS_OPEN) {
       log10(`tool execution rejected: ${request.toolName} (WebSocket not connected)`);
-      return Promise.resolve({
+      return {
         status: "error",
         error: "Bucket session is not connected"
-      });
+      };
     }
     const requestId = crypto.randomUUID();
+    const repoPath = findRepoPathByRepositoryId(state.repositories, Number(request.repositoryId));
+    const toolDef = state.tools.find((t) => t.name === request.toolName);
+    const namedArgs = {};
+    if (toolDef) {
+      for (let i = 0;i < toolDef.parameters.length && i < request.arguments.length; i++) {
+        const param = toolDef.parameters[i];
+        const value = request.arguments[i];
+        if (param.type === "file" && typeof value === "string") {
+          const filePath = repoPath ? resolve(repoPath, value) : value;
+          try {
+            const data = await readFile(filePath);
+            namedArgs[param.name] = {
+              filename: basename2(value),
+              data: data.toString("base64")
+            };
+          } catch {
+            return {
+              status: "error",
+              error: `Unable to read file: ${value}`
+            };
+          }
+        } else {
+          namedArgs[param.name] = value;
+        }
+      }
+    } else {
+      for (let i = 0;i < request.arguments.length; i++) {
+        namedArgs[`arg${i}`] = request.arguments[i];
+      }
+    }
     const message = {
       type: "tool-execution-request",
       requestId,
-      toolName: request.toolName,
-      arguments: request.arguments,
-      repositoryId: request.repositoryId
+      tool: request.toolName,
+      repositoryId: Number(request.repositoryId),
+      arguments: namedArgs
     };
     log10(`forwarding tool execution: ${request.toolName} requestId=${requestId}`);
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       const timeoutId = setTimeout(() => {
         pendingToolExecutions.delete(requestId);
         log10(`tool execution timed out: ${request.toolName} requestId=${requestId}`);
         reject(new Error("Timed out waiting for tool execution result"));
       }, 30000);
       pendingToolExecutions.set(requestId, {
-        resolve,
+        resolve: resolve2,
         reject,
         timeoutId
       });
@@ -6180,10 +6225,10 @@ async function bucketWorker(dependencies, bucketDeps = createDefaultBucketDepend
     if (useTUI) {
       tuiHandle = setupTUI(state, bucketDeps);
     }
-    await new Promise((resolve) => {
+    await new Promise((resolve2) => {
       const doShutdown = async () => {
         await shutdown(state, bucketDeps, context);
-        resolve();
+        resolve2();
       };
       const onKey = createKeypressHandler(useTUI, state, () => {
         doShutdown();
@@ -6198,14 +6243,30 @@ async function bucketWorker(dependencies, bucketDeps = createDefaultBucketDepend
           log10(`received tool execution result for unknown requestId=${message.requestId}`);
           return;
         }
-        log10(`received tool execution result: requestId=${message.requestId} status=${message.status}`);
+        const resultType = message.result.type;
+        log10(`received tool execution result: requestId=${message.requestId} status=${resultType}`);
         clearTimeout(pending.timeoutId);
         pendingToolExecutions.delete(message.requestId);
-        pending.resolve({
-          status: message.status,
-          output: message.output,
-          error: message.error
-        });
+        switch (message.result.type) {
+          case "success":
+            pending.resolve({
+              status: "success",
+              output: typeof message.result.data === "string" ? message.result.data : JSON.stringify(message.result.data)
+            });
+            break;
+          case "tool-not-found":
+            pending.resolve({
+              status: "tool-not-found",
+              error: message.result.message
+            });
+            break;
+          case "error":
+            pending.resolve({
+              status: "error",
+              error: message.result.message
+            });
+            break;
+        }
       }, forwardToolExecution);
       if (!useTUI) {
         context.stdout("   Press q or Ctrl+C to exit");
@@ -6372,7 +6433,7 @@ function createGitRunner(spawnFn) {
 }
 var defaultGitRunner = createGitRunner(spawn);
 function runBufferedProcess(spawnFn, command, commandArguments, cwd, shell, timeoutMs) {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const proc = spawnFn(command, commandArguments, { cwd, shell });
     const chunks = [];
     let resolved = false;
@@ -6384,7 +6445,7 @@ function runBufferedProcess(spawnFn, command, commandArguments, cwd, shell, time
         proc.stdout?.destroy();
         proc.stderr?.destroy();
         proc.unref();
-        resolve({
+        resolve2({
           exitCode: 1,
           output: chunks.join(""),
           timedOut: true
@@ -6402,14 +6463,14 @@ function runBufferedProcess(spawnFn, command, commandArguments, cwd, shell, time
         return;
       if (timer !== undefined)
         clearTimeout(timer);
-      resolve({ exitCode: code ?? 1, output: chunks.join("") });
+      resolve2({ exitCode: code ?? 1, output: chunks.join("") });
     });
     proc.on("error", (error) => {
       if (resolved)
         return;
       if (timer !== undefined)
         clearTimeout(timer);
-      resolve({ exitCode: 1, output: error.message });
+      resolve2({ exitCode: 1, output: error.message });
     });
   });
 }
@@ -6870,7 +6931,7 @@ function validateWorkflowTaskBodySection(filePath, content, ideasPath, fileSyste
 }
 
 // lib/lint/validators/link-validator.ts
-import { dirname as dirname3, resolve } from "node:path";
+import { dirname as dirname3, resolve as resolve2 } from "node:path";
 var SEMANTIC_RULES = [
   {
     section: "## Principles",
@@ -6895,14 +6956,22 @@ function validateLinks(filePath, content, fileSystem) {
     while (match) {
       const linkTarget = match[2];
       if (!linkTarget.startsWith("http://") && !linkTarget.startsWith("https://") && !linkTarget.startsWith("#")) {
-        const targetPath = linkTarget.split("#")[0];
-        const resolvedPath = resolve(fileDir, targetPath);
-        if (!fileSystem.exists(resolvedPath)) {
+        if (linkTarget.startsWith("/")) {
           violations.push({
             file: filePath,
-            message: `Broken link: "${linkTarget}"`,
+            message: `Absolute link not allowed: "${linkTarget}" (use a relative path instead)`,
             line: i + 1
           });
+        } else {
+          const targetPath = linkTarget.split("#")[0];
+          const resolvedPath = resolve2(fileDir, targetPath);
+          if (!fileSystem.exists(resolvedPath)) {
+            violations.push({
+              file: filePath,
+              message: `Broken link: "${linkTarget}"`,
+              line: i + 1
+            });
+          }
         }
       }
       match = linkPattern.exec(line);
@@ -6948,7 +7017,7 @@ function validateSemanticLinks(filePath, content) {
         continue;
       }
       const targetPath = linkTarget.split("#")[0];
-      const resolvedPath = resolve(fileDir, targetPath);
+      const resolvedPath = resolve2(fileDir, targetPath);
       if (!resolvedPath.includes(rule.requiredPath)) {
         violations.push({
           file: filePath,
@@ -6999,7 +7068,7 @@ function validatePrincipleHierarchyLinks(filePath, content) {
         continue;
       }
       const targetPath = linkTarget.split("#")[0];
-      const resolvedPath = resolve(fileDir, targetPath);
+      const resolvedPath = resolve2(fileDir, targetPath);
       if (!resolvedPath.includes("/.dust/principles/")) {
         violations.push({
           file: filePath,
@@ -7014,7 +7083,7 @@ function validatePrincipleHierarchyLinks(filePath, content) {
 }
 
 // lib/lint/validators/principle-hierarchy.ts
-import { dirname as dirname4, resolve as resolve2 } from "node:path";
+import { dirname as dirname4, resolve as resolve3 } from "node:path";
 var REQUIRED_PRINCIPLE_HEADINGS = ["## Parent Principle", "## Sub-Principles"];
 function validatePrincipleHierarchySections(filePath, content) {
   const violations = [];
@@ -7049,7 +7118,7 @@ function extractPrincipleRelationships(filePath, content) {
       const linkTarget = match[2];
       if (!linkTarget.startsWith("#") && !linkTarget.startsWith("http://") && !linkTarget.startsWith("https://")) {
         const targetPath = linkTarget.split("#")[0];
-        const resolvedPath = resolve2(fileDir, targetPath);
+        const resolvedPath = resolve3(fileDir, targetPath);
         if (resolvedPath.includes("/.dust/principles/")) {
           if (currentSection === "## Parent Principle") {
             parentPrinciples.push(resolvedPath);
@@ -7701,7 +7770,7 @@ async function init(dependencies) {
 }
 
 // lib/cli/commands/list.ts
-import { basename as basename2 } from "node:path";
+import { basename as basename3 } from "node:path";
 function workflowTypeToStatus(type) {
   switch (type) {
     case "refine-idea":
@@ -7734,7 +7803,7 @@ async function buildPrincipleHierarchy(principlesPath, fileSystem) {
     const filePath = `${principlesPath}/${file}`;
     const content = await fileSystem.readFile(filePath);
     relationships.push(extractPrincipleRelationships(filePath, content));
-    const title = extractTitle(content) || basename2(file, ".md");
+    const title = extractTitle(content) || basename3(file, ".md");
     titleMap.set(filePath, title);
   }
   const relMap = new Map;
@@ -7752,7 +7821,7 @@ async function buildPrincipleHierarchy(principlesPath, fileSystem) {
     }
     return {
       filePath,
-      title: titleMap.get(filePath) || basename2(filePath, ".md"),
+      title: titleMap.get(filePath) || basename3(filePath, ".md"),
       children
     };
   }

package/dist/types.d.ts

@@ -10,3 +10,5 @@ export type { ArtifactType, TaskGraph, TaskGraphNode } from './artifacts/index';
 export type { Task } from './artifacts/tasks';
 export type { CreateIdeaTransitionTaskResult, DecomposeIdeaOptions, IdeaInProgress, OpenQuestionResponse, ParsedCaptureIdeaTask, WorkflowTaskMatch, WorkflowTaskType, } from './artifacts/workflow-tasks';
 export type { Repository } from './bucket/repository';
+export type { ToolExecutionErrorResult, ToolExecutionRequestMessage, ToolExecutionResult, ToolExecutionResultMessage, ToolExecutionSuccessResult, ToolExecutionToolNotFoundResult, } from './bucket/tool-execution-protocol';
+export { isToolExecutionRequestMessage, isToolExecutionResultMessage, } from './bucket/tool-execution-protocol';

package/dist/validation.js

@@ -451,14 +451,22 @@ function validateLinks(filePath, content, fileSystem) {
     while (match) {
       const linkTarget = match[2];
       if (!linkTarget.startsWith("http://") && !linkTarget.startsWith("https://") && !linkTarget.startsWith("#")) {
-        const targetPath = linkTarget.split("#")[0];
-        const resolvedPath = resolve(fileDir, targetPath);
-        if (!fileSystem.exists(resolvedPath)) {
+        if (linkTarget.startsWith("/")) {
           violations.push({
             file: filePath,
-            message: `Broken link: "${linkTarget}"`,
+            message: `Absolute link not allowed: "${linkTarget}" (use a relative path instead)`,
             line: i + 1
           });
+        } else {
+          const targetPath = linkTarget.split("#")[0];
+          const resolvedPath = resolve(fileDir, targetPath);
+          if (!fileSystem.exists(resolvedPath)) {
+            violations.push({
+              file: filePath,
+              message: `Broken link: "${linkTarget}"`,
+              line: i + 1
+            });
+          }
         }
       }
       match = linkPattern.exec(line);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joshski/dust",
-  "version": "0.1.90",
+  "version": "0.1.92",
   "description": "Flow state for AI coding agents",
   "type": "module",
   "bin": {