@joshski/dust 0.1.40 → 0.1.42

package/dist/agent-events.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared agent event types for the dust event protocol.
+ *
+ * These types define the transport-agnostic event format used by both
+ * the HTTP (loop) and WebSocket (bucket) paths.
+ */
+export type AgentSessionEvent = {
+    type: 'agent-session-started';
+    title: string;
+    prompt: string;
+    agentType: string;
+    purpose: string;
+} | {
+    type: 'agent-session-ended';
+    success: boolean;
+    error?: string;
+} | {
+    type: 'agent-session-activity';
+} | {
+    type: 'claude-event';
+    rawEvent: Record<string, unknown>;
+};
+export interface EventMessage {
+    sequence: number;
+    timestamp: string;
+    sessionId: string;
+    repository: string;
+    agentSessionId?: string;
+    event: AgentSessionEvent;
+}
+/**
+ * Convert a raw Claude streaming event to an AgentSessionEvent.
+ * stream_event types become activity heartbeats; everything else
+ * is forwarded as a claude-event.
+ */
+export declare function rawEventToAgentEvent(rawEvent: Record<string, unknown>): AgentSessionEvent;
+/**
+ * Format an AgentSessionEvent for console output.
+ * Returns null for events that should not be displayed.
+ */
+export declare function formatAgentEvent(event: AgentSessionEvent): string | null;

package/dist/dust.js

@@ -336,8 +336,12 @@ async function manageGitHooks(dependencies) {
 }
 
 // lib/cli/commands/agent.ts
-async function agent(dependencies) {
+async function agent(dependencies, env = process.env) {
   const { context, fileSystem, settings } = dependencies;
+  if (env.DUST_SKIP_AGENT === "1") {
+    context.stdout("You're running in an automated loop - proceeding to implement the assigned task.");
+    return { exitCode: 0 };
+  }
   const hooksInstalled = await manageGitHooks(dependencies);
   const vars = await templateVariablesWithInstructions(context.cwd, fileSystem, settings, hooksInstalled);
   context.stdout(loadTemplate("agent-greeting", vars));
@@ -1114,9 +1118,10 @@ async function run(prompt, options = {}, dependencies = defaultRunnerDependencie
 import { spawn as nodeSpawn2 } from "node:child_process";
 
 // lib/cli/commands/focus.ts
-function buildImplementationInstructions(bin, hooksInstalled) {
+function buildImplementationInstructions(bin, hooksInstalled, taskTitle) {
   const steps = [];
   let step = 1;
+  steps.push(`Note: Do NOT run \`${bin} agent\`.`, "");
   steps.push(`${step}. Run \`${bin} check\` to verify the project is in a good state`);
   step++;
   steps.push(`${step}. Implement the task`);
@@ -1125,7 +1130,8 @@ function buildImplementationInstructions(bin, hooksInstalled) {
     steps.push(`${step}. Run \`${bin} check\` before committing`);
     step++;
   }
-  steps.push(`${step}. Create a single atomic commit that includes:`, "   - All implementation changes", "   - Deletion of the completed task file", "   - Updates to any facts that changed", "   - Deletion of the idea file that spawned this task (if remaining scope exists, create new ideas for it)", "", '   Use the task title as the commit message. Task titles are written in imperative form, which is the recommended style for git commit messages. Do not add prefixes like "Complete task:" - use the title directly.', "", '   Example: If the task title is "Add validation for user input", the commit message should be:', "   ```", "   Add validation for user input", "   ```", "");
+  const commitMessageLine = taskTitle ? `   Use this exact commit message: "${taskTitle}". Do not add any prefix.` : '   Use the task title as the commit message. Do not add prefixes like "Complete task:" - use the title directly.';
+  steps.push(`${step}. Create a single atomic commit that includes:`, "   - All implementation changes", "   - Deletion of the completed task file", "   - Updates to any facts that changed", "   - Deletion of the idea file that spawned this task (if remaining scope exists, create new ideas for it)", "", commitMessageLine, "");
   step++;
   steps.push(`${step}. Push your commit to the remote repository`);
   steps.push("");
@@ -1251,8 +1257,6 @@ function formatLoopEvent(event) {
       return `\uD83D\uDCCB Completed iteration ${event.iteration}/${event.maxIterations}`;
     case "loop.ended":
       return `\uD83C\uDFC1 Reached max iterations (${event.maxIterations}). Exiting.`;
-    case "loop.start_agent":
-      return null;
   }
 }
 async function defaultPostEvent(url, payload) {
@@ -1330,11 +1334,9 @@ async function runOneIteration(dependencies, loopDependencies, onLoopEvent, onAg
       type: "loop.sync_skipped",
       reason: pullResult.message
     });
-    onAgentEvent?.({
-      type: "agent-session-started",
-      title: "Resolving git conflict"
-    });
-    const prompt2 = `git pull failed with the following error:
+    const prompt2 = `Note: Do NOT run \`dust agent\`.
+
+git pull failed with the following error:
 
 ${pullResult.message}
 
@@ -1344,13 +1346,19 @@ Please resolve this issue. Common approaches:
 3. After resolving, commit any changes and push to remote
 
 Make sure the repository is in a clean state and synced with remote before finishing.`;
-    onLoopEvent({ type: "loop.start_agent", prompt: prompt2 });
+    onAgentEvent?.({
+      type: "agent-session-started",
+      title: "Resolving git conflict",
+      prompt: prompt2,
+      agentType: "claude",
+      purpose: "git-conflict"
+    });
     try {
       await run2(prompt2, {
         spawnOptions: {
           cwd: context.cwd,
           dangerouslySkipPermissions: true,
-          env: { DUST_UNATTENDED: "1" }
+          env: { DUST_UNATTENDED: "1", DUST_SKIP_AGENT: "1" }
         },
         onRawEvent
       });
@@ -1374,33 +1382,35 @@ Make sure the repository is in a clean state and synced with remote before finis
   }
   const task = tasks[0];
   onLoopEvent({ type: "loop.tasks_found" });
-  onAgentEvent?.({
-    type: "agent-session-started",
-    title: task.title ?? task.path
-  });
   const taskContent = await dependencies.fileSystem.readFile(`${dependencies.context.cwd}/${task.path}`);
   const { dustCommand, installCommand = "npm install" } = dependencies.settings;
-  const instructions = buildImplementationInstructions(dustCommand, true);
+  const instructions = buildImplementationInstructions(dustCommand, true, task.title ?? undefined);
   const prompt = `Run \`${installCommand}\` to install dependencies, then implement the following task.
 
-## Task: ${task.title}
-
 The following is the contents of the task file \`${task.path}\`:
 
+----------
 ${taskContent}
+----------
 
 When the task is complete, delete the task file \`${task.path}\`.
 
 ## Instructions
 
 ${instructions}`;
-  onLoopEvent({ type: "loop.start_agent", prompt });
+  onAgentEvent?.({
+    type: "agent-session-started",
+    title: task.title ?? task.path,
+    prompt,
+    agentType: "claude",
+    purpose: "task"
+  });
   try {
     await run2(prompt, {
       spawnOptions: {
         cwd: context.cwd,
         dangerouslySkipPermissions: true,
-        env: { DUST_UNATTENDED: "1" }
+        env: { DUST_UNATTENDED: "1", DUST_SKIP_AGENT: "1" }
       },
       onRawEvent
     });
@@ -1489,7 +1499,14 @@ function parseRepository(data) {
   if (typeof data === "object" && data !== null && "name" in data && "gitUrl" in data) {
     const repositoryData = data;
     if (typeof repositoryData.name === "string" && typeof repositoryData.gitUrl === "string") {
-      return { name: repositoryData.name, gitUrl: repositoryData.gitUrl };
+      const repo = {
+        name: repositoryData.name,
+        gitUrl: repositoryData.gitUrl
+      };
+      if (typeof repositoryData.url === "string") {
+        repo.url = repositoryData.url;
+      }
+      return repo;
     }
   }
   return null;
@@ -1790,6 +1807,7 @@ function createTerminalUIState() {
     selectedIndex: -1,
     logBuffers: new Map,
     agentStatuses: new Map,
+    repositoryUrls: new Map,
     scrollOffset: 0,
     autoScroll: true,
     width: 80,
@@ -1801,7 +1819,7 @@ function updateDimensions(state, width, height) {
   state.width = width;
   state.height = height;
 }
-function addRepository2(state, name, logBuffer) {
+function addRepository2(state, name, logBuffer, url) {
   if (!state.repositories.includes(name)) {
     state.repositories.push(name);
     state.repositories.sort((a, b) => {
@@ -1814,6 +1832,9 @@ function addRepository2(state, name, logBuffer) {
     state.agentStatuses.set(name, "idle");
   }
   state.logBuffers.set(name, logBuffer);
+  if (url) {
+    state.repositoryUrls.set(name, url);
+  }
 }
 function removeRepository2(state, name) {
   const index = state.repositories.indexOf(name);
@@ -1821,6 +1842,7 @@ function removeRepository2(state, name) {
     state.repositories.splice(index, 1);
     state.logBuffers.delete(name);
     state.agentStatuses.delete(name);
+    state.repositoryUrls.delete(name);
     if (state.selectedIndex >= state.repositories.length) {
       state.selectedIndex = state.repositories.length - 1;
     }
@@ -1967,7 +1989,7 @@ function renderTabs(state) {
   return rows.map((row) => row.map((t) => t.text).join("|"));
 }
 function renderHelpLine() {
-  return `${ANSI.DIM}[←→] select  [↑↓] scroll  [PgUp/PgDn] page  [g/G] top/bottom  [q] quit${ANSI.RESET}`;
+  return `${ANSI.DIM}[←→] select  [↑↓] scroll  [PgUp/PgDn] page  [g/G] top/bottom  [o] open  [q] quit${ANSI.RESET}`;
 }
 function renderSeparator(width) {
   return "─".repeat(width);
@@ -2050,7 +2072,7 @@ function parseSGRMouse(key) {
     return null;
   return Number.parseInt(match[1], 10);
 }
-function handleKeyInput(state, key) {
+function handleKeyInput(state, key, options) {
   const mouseButton = parseSGRMouse(key);
   if (mouseButton !== null) {
     if (mouseButton === 64) {
@@ -2094,6 +2116,19 @@ function handleKeyInput(state, key) {
     case KEYS.END:
       scrollToBottom(state);
       break;
+    case "o": {
+      if (state.selectedIndex === -1) {
+        break;
+      }
+      const repoName = state.repositories[state.selectedIndex];
+      if (!repoName)
+        break;
+      const url = state.repositoryUrls.get(repoName);
+      if (url && options?.openBrowser) {
+        options.openBrowser(url);
+      }
+      break;
+    }
   }
   return false;
 }
@@ -2265,7 +2300,9 @@ function syncUIWithRepoList(state, repos) {
           buffer = createLogBuffer();
           state.logBuffers.set(repo.name, buffer);
         }
-        addRepository2(state.ui, repo.name, buffer);
+        addRepository2(state.ui, repo.name, buffer, repo.url);
+      } else if (repo.url) {
+        state.ui.repositoryUrls.set(repo.name, repo.url);
       }
     }
   }
@@ -2429,10 +2466,10 @@ function setupTUI(state, bucketDeps) {
     }
   };
 }
-function createKeypressHandler(useTUI, state, onQuit) {
+function createKeypressHandler(useTUI, state, onQuit, options) {
   if (useTUI) {
     return (key) => {
-      const shouldQuit = handleKeyInput(state.ui, key);
+      const shouldQuit = handleKeyInput(state.ui, key, options);
       if (shouldQuit)
         onQuit();
     };
@@ -2442,9 +2479,10 @@ function createKeypressHandler(useTUI, state, onQuit) {
       onQuit();
   };
 }
-async function resolveToken(commandArgs, authDeps, context) {
-  if (commandArgs[0]) {
-    return commandArgs[0];
+async function resolveToken(authDeps, context) {
+  const envToken = process.env.DUST_BUCKET_TOKEN;
+  if (envToken) {
+    return envToken;
   }
   const stored = await loadStoredToken(authDeps.fileSystem, authDeps.getHomeDir());
   if (stored) {
@@ -2462,8 +2500,8 @@ async function resolveToken(commandArgs, authDeps, context) {
   }
 }
 async function bucket(dependencies, bucketDeps = createDefaultBucketDependencies()) {
-  const { arguments: commandArgs, context, fileSystem } = dependencies;
-  const token = await resolveToken(commandArgs, bucketDeps.auth, context);
+  const { context, fileSystem } = dependencies;
+  const token = await resolveToken(bucketDeps.auth, context);
   if (!token) {
     return { exitCode: 1 };
   }
@@ -2504,7 +2542,7 @@ async function bucket(dependencies, bucketDeps = createDefaultBucketDependencies
       };
       const onKey = createKeypressHandler(useTUI, state, () => {
         doShutdown();
-      });
+      }, { openBrowser: bucketDeps.auth.openBrowser });
       cleanupKeypress = bucketDeps.setupKeypress(onKey);
       cleanupSignals = bucketDeps.setupSignals(() => {
         doShutdown();

package/dist/ideas.d.ts

@@ -0,0 +1,25 @@
+import type { FileSystem } from './cli/types';
+export interface IdeaOption {
+    name: string;
+    description: string;
+}
+export interface IdeaOpenQuestion {
+    question: string;
+    options: IdeaOption[];
+}
+export interface Idea {
+    slug: string;
+    title: string;
+    openingSentence: string | null;
+    content: string;
+    openQuestions: IdeaOpenQuestion[];
+}
+/**
+ * Parses the ## Open Questions section from idea markdown content.
+ * Extracts each ### question heading and its #### option children.
+ */
+export declare function parseOpenQuestions(content: string): IdeaOpenQuestion[];
+/**
+ * Parses an idea markdown file into a structured Idea object.
+ */
+export declare function parseIdea(fileSystem: FileSystem, dustPath: string, slug: string): Promise<Idea>;

package/dist/markdown/markdown-utilities.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared markdown utilities for dust CLI commands
+ */
+/**
+ * Extracts the title from markdown content (first H1 heading)
+ */
+export declare function extractTitle(content: string): string | null;
+/**
+ * Pattern for matching markdown links: [text](url)
+ * Note: Create a new RegExp with 'g' flag for global matching:
+ * `new RegExp(MARKDOWN_LINK_PATTERN.source, 'g')`
+ */
+export declare const MARKDOWN_LINK_PATTERN: RegExp;
+/**
+ * Extracts the first sentence from the first paragraph after the H1 heading.
+ * Returns null if no valid opening paragraph exists.
+ *
+ * A valid opening paragraph:
+ * - Appears on the first non-blank line after the H1 heading
+ * - Is a plain paragraph (not a heading, list item, or code block)
+ * - Starts with a sentence that ends in `.` `?` or `!`
+ */
+export declare function extractOpeningSentence(content: string): string | null;

package/dist/types.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public type definitions for downstream consumers of @joshski/dust.
+ *
+ * Import from '@joshski/dust/types' to get typed bindings for
+ * the event protocol, workflow tasks, and idea structures.
+ */
+export type { AgentSessionEvent, EventMessage } from './agent-events';
+export type { Idea, IdeaOpenQuestion, IdeaOption } from './ideas';
+export type { CreateIdeaTransitionTaskResult, DecomposeIdeaOptions, IdeaInProgress, OpenQuestionResponse, ParsedCaptureIdeaTask, WorkflowTaskMatch, WorkflowTaskType, } from './workflow-tasks';

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@joshski/dust",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "description": "Flow state for AI coding agents",
   "type": "module",
   "bin": {
     "dust": "./dist/dust.js"
   },
   "exports": {
+    "./types": {
+      "types": "./dist/types.d.ts"
+    },
     "./workflow-tasks": {
       "import": "./dist/workflow-tasks.js",
       "types": "./dist/workflow-tasks.d.ts"