@joshski/dust 0.1.78 → 0.1.80

package/dist/agent-events.d.ts

@@ -40,4 +40,15 @@ export interface EventMessage {
  * is forwarded as a claude-event.
  */
 export declare function rawEventToAgentEvent(rawEvent: Record<string, unknown>): AgentSessionEvent;
+/**
+ * Create a heartbeat throttler that limits agent-session-activity events
+ * to at most once per interval (default: 5 seconds).
+ *
+ * The returned callback converts raw Claude events to AgentSessionEvents,
+ * throttling stream_event heartbeats while forwarding all other events.
+ */
+export declare function createHeartbeatThrottler(onAgentEvent: (event: AgentSessionEvent) => void, options?: {
+    intervalMs?: number;
+    now?: () => number;
+}): (rawEvent: Record<string, unknown>) => void;
 export declare function formatAgentEvent(event: AgentSessionEvent): string | null;

package/dist/artifacts/index.d.ts

@@ -18,7 +18,9 @@ export interface TaskGraph {
 }
 export { CAPTURE_IDEA_PREFIX, findAllWorkflowTasks, parseOpenQuestions };
 export type { IdeaInProgress };
+export type ArtifactType = 'ideas' | 'tasks' | 'principles' | 'facts';
 export interface ArtifactsRepository {
+    artifactPath(type: ArtifactType, slug: string): string;
     parseIdea(options: {
         slug: string;
     }): Promise<Idea>;
@@ -63,4 +65,4 @@ export interface ArtifactsRepository {
     buildTaskGraph(): Promise<TaskGraph>;
 }
 export declare function buildArtifactsRepository(fileSystem: FileSystem, dustPath: string): ArtifactsRepository;
-export declare function buildReadOnlyArtifactsRepository(fileSystem: ReadableFileSystem, dustPath: string): Pick<ArtifactsRepository, 'parseIdea' | 'listIdeas' | 'parsePrinciple' | 'listPrinciples' | 'parseFact' | 'listFacts' | 'parseTask' | 'listTasks' | 'findWorkflowTaskForIdea' | 'parseCaptureIdeaTask' | 'buildTaskGraph'>;
+export declare function buildReadOnlyArtifactsRepository(fileSystem: ReadableFileSystem, dustPath: string): Pick<ArtifactsRepository, 'artifactPath' | 'parseIdea' | 'listIdeas' | 'parsePrinciple' | 'listPrinciples' | 'parseFact' | 'listFacts' | 'parseTask' | 'listTasks' | 'findWorkflowTaskForIdea' | 'parseCaptureIdeaTask' | 'buildTaskGraph'>;

package/dist/artifacts.js

@@ -548,6 +548,9 @@ async function parseCaptureIdeaTask(fileSystem, dustPath, taskSlug) {
 // lib/artifacts/index.ts
 function buildArtifactsRepository(fileSystem, dustPath) {
   return {
+    artifactPath(type, slug) {
+      return `${dustPath}/${type}/${slug}.md`;
+    },
     async parseIdea(options) {
       return parseIdea(fileSystem, dustPath, options.slug);
     },
@@ -635,6 +638,9 @@ function buildArtifactsRepository(fileSystem, dustPath) {
 }
 function buildReadOnlyArtifactsRepository(fileSystem, dustPath) {
   return {
+    artifactPath(type, slug) {
+      return `${dustPath}/${type}/${slug}.md`;
+    },
     async parseIdea(options) {
       return parseIdea(fileSystem, dustPath, options.slug);
     },

package/dist/bucket/repository-loop.d.ts

@@ -5,6 +5,9 @@
  * for a single repository.
  */
 import type { AgentSessionEvent, EventMessage } from '../agent-events';
+import { type run as claudeRun, type RunnerDependencies } from '../claude/run';
+import type { OutputSink } from '../claude/types';
+import { type LoopEmitFn, type SendAgentEventFn } from '../cli/commands/loop';
 import type { SendEventFn } from './events';
 import { type LogBuffer } from './log-buffer';
 import type { RepositoryDependencies, RepositoryState } from './repository';
@@ -40,6 +43,45 @@ export declare function buildEventMessage(parameters: {
  * Extracted for testability (v8 coverage limitation on inline callbacks).
  */
 export declare function createWakeUpHandler(repoState: RepositoryState, resolve: () => void): () => void;
+/** Mutable state shared across loop iteration callbacks. */
+export interface LoopState {
+    partialLine: string;
+    sequence: number;
+    agentSessionId: string | undefined;
+}
+/**
+ * Create an OutputSink that buffers stdout and logs complete lines.
+ */
+export declare function createBufferStdoutSink(loopState: LoopState, logBuffer: LogBuffer): OutputSink;
+/**
+ * Create a run function that redirects Claude output to a log buffer.
+ */
+export declare function createBufferRun(run: RepositoryDependencies['run'], bufferSinkDeps: RunnerDependencies): typeof claudeRun;
+/** No-op postEvent for LoopDependencies. */
+export declare function noOpPostEvent(): Promise<void>;
+/**
+ * Create a handler that logs formatted loop events to a log buffer.
+ */
+export declare function createLoopEventHandler(logBuffer: LogBuffer): LoopEmitFn;
+/**
+ * Create a handler that logs formatted agent events and sends them over WebSocket.
+ */
+export declare function createAgentEventHandler(parameters: {
+    repoState: RepositoryState;
+    sendEvent?: SendEventFn;
+    sessionId?: string;
+    repoName: string;
+    loopState: LoopState;
+}): SendAgentEventFn;
+/**
+ * Create a cancel handler that aborts the given controller.
+ */
+export declare function createCancelHandler(abortController: AbortController): () => void;
+/**
+ * Set up the fallback timeout for the no-tasks wait.
+ * Resolves the wait if this exact handler is still active after the timeout.
+ */
+export declare function setupFallbackTimeout(repoState: RepositoryState, sleep: RepositoryDependencies['sleep'], resolve: () => void, wakeUpForThisWait: () => void): void;
 /**
  * Run the async loop for a single repository.
  */

package/dist/bucket/repository.d.ts

@@ -16,6 +16,7 @@ export interface Repository {
     gitUrl: string;
     url: string;
     id: number;
+    agentProvider?: string;
 }
 export interface RepositoryState {
     repository: Repository;

package/dist/claude/types.d.ts

@@ -47,6 +47,16 @@ export interface OutputSink {
     write(text: string): void;
     line(text: string): void;
 }
+export interface DockerSpawnConfig {
+    /** Docker image tag to use */
+    imageTag: string;
+    /** Path to the repository (used for volume mounts) */
+    repoPath: string;
+    /** Home directory for credential mounts */
+    homeDir: string;
+    /** Whether .gitconfig exists (for optional mount) */
+    hasGitconfig: boolean;
+}
 export interface SpawnOptions {
     cwd?: string;
     allowedTools?: string[];
@@ -57,5 +67,7 @@ export interface SpawnOptions {
     dangerouslySkipPermissions?: boolean;
     env?: Record<string, string>;
     signal?: AbortSignal;
+    /** When set, spawn claude inside a Docker container */
+    docker?: DockerSpawnConfig;
 }
 export type RawEventCallback = (event: RawEvent) => void;

package/dist/cli/commands/loop.d.ts

@@ -18,6 +18,8 @@
 import { spawn as nodeSpawn } from 'node:child_process';
 import { type AgentSessionEvent, type EventMessage } from '../../agent-events';
 import { run as claudeRun } from '../../claude/run';
+import type { DockerSpawnConfig } from '../../claude/types';
+import { type DockerDependencies } from '../../docker/docker-agent';
 import type { CommandDependencies, CommandResult } from '../types';
 import { type UnblockedTask } from './next';
 export interface LoopWarningEvent {
@@ -53,7 +55,23 @@ export interface LoopEndedEvent {
     type: 'loop.ended';
     maxIterations: number;
 }
-export type LoopEvent = LoopWarningEvent | LoopStartedEvent | LoopSyncingEvent | LoopSyncSkippedEvent | LoopCheckingTasksEvent | LoopNoTasksEvent | LoopTasksFoundEvent | LoopIterationCompleteEvent | LoopEndedEvent;
+export interface LoopDockerDetectedEvent {
+    type: 'loop.docker_detected';
+    imageTag: string;
+}
+export interface LoopDockerBuildingEvent {
+    type: 'loop.docker_building';
+    imageTag: string;
+}
+export interface LoopDockerBuiltEvent {
+    type: 'loop.docker_built';
+    imageTag: string;
+}
+export interface LoopDockerErrorEvent {
+    type: 'loop.docker_error';
+    error: string;
+}
+export type LoopEvent = LoopWarningEvent | LoopStartedEvent | LoopSyncingEvent | LoopSyncSkippedEvent | LoopCheckingTasksEvent | LoopNoTasksEvent | LoopTasksFoundEvent | LoopIterationCompleteEvent | LoopEndedEvent | LoopDockerDetectedEvent | LoopDockerBuildingEvent | LoopDockerBuiltEvent | LoopDockerErrorEvent;
 export type LoopEmitFn = (event: LoopEvent) => void;
 export declare function formatLoopEvent(event: LoopEvent): string | null;
 export type PostEventFn = (url: string, payload: EventMessage) => Promise<void>;
@@ -64,6 +82,8 @@ export interface LoopDependencies {
     postEvent: PostEventFn;
     agentType?: string;
     fetch?: typeof fetch;
+    /** Optional overrides for Docker dependency functions (for testing) */
+    dockerDeps?: Partial<DockerDependencies>;
 }
 export declare function createPostEvent(fetchFn: typeof fetch): PostEventFn;
 export declare function createDefaultDependencies(): LoopDependencies;
@@ -85,6 +105,8 @@ interface IterationOptions {
     signal?: AbortSignal;
     logger?: LogFn;
     repositoryId?: string;
+    /** Docker spawn config when running in Docker mode */
+    docker?: DockerSpawnConfig;
 }
 export declare function runOneIteration(dependencies: CommandDependencies, loopDependencies: LoopDependencies, onLoopEvent: LoopEmitFn, onAgentEvent?: SendAgentEventFn, options?: IterationOptions): Promise<IterationResult>;
 export declare function parseMaxIterations(commandArguments: string[]): number;

package/dist/cli/types.d.ts

@@ -1,6 +1,7 @@
 /**
  * Common types for CLI commands
  */
+import type { CommandEvent } from '../command-events';
 import type { FileSystem, GlobScanner } from '../filesystem/types';
 export type { FileSystem, GlobScanner, ReadableFileSystem, } from '../filesystem/types';
 export interface CommandContext {
@@ -8,6 +9,7 @@ export interface CommandContext {
     stdout: (message: string) => void;
     stdoutInline?: (message: string) => void;
     stderr: (message: string) => void;
+    emitEvent?: (event: CommandEvent) => void;
 }
 export interface CommandResult {
     exitCode: number;

package/dist/codex/event-parser.d.ts

@@ -0,0 +1,13 @@
+import type { ClaudeEvent, RawEvent } from '../claude/types';
+/**
+ * Parse a raw Codex JSON event into ClaudeEvent types.
+ *
+ * Codex `exec --json` emits JSONL with these event types:
+ * - { type: "item.completed", item: { type: "agent_message", text: "..." } } → text output
+ * - { type: "item.completed", item: { type: "command_execution", command, aggregated_output, exit_code } } → tool use + result
+ * - { type: "item.completed", item: { type: "reasoning", text: "..." } } → skipped (internal thinking)
+ * - { type: "item.started", item: { type: "command_execution", command } } → skipped (in-progress)
+ * - { type: "turn.started" } / { type: "turn.completed" } → skipped
+ * - { type: "thread.started" } → skipped
+ */
+export declare function parseCodexRawEvent(raw: RawEvent): Generator<ClaudeEvent>;

package/dist/codex/run.d.ts

@@ -0,0 +1,16 @@
+import { createStdoutSink as defaultCreateStdoutSink } from '../claude/streamer';
+import type { RawEventCallback, SpawnOptions } from '../claude/types';
+import { spawnCodex as defaultSpawnCodex } from './spawn-codex';
+import { streamCodexEvents as defaultStreamCodexEvents } from './streamer';
+interface RunOptions {
+    spawnOptions?: SpawnOptions;
+    onRawEvent?: RawEventCallback;
+}
+export interface RunnerDependencies {
+    spawnCodex: typeof defaultSpawnCodex;
+    createStdoutSink: typeof defaultCreateStdoutSink;
+    streamCodexEvents: typeof defaultStreamCodexEvents;
+}
+export declare const defaultRunnerDependencies: RunnerDependencies;
+export declare function run(prompt: string, options?: SpawnOptions | RunOptions, dependencies?: RunnerDependencies): Promise<void>;
+export {};

package/dist/codex/spawn-codex.d.ts

@@ -0,0 +1,9 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { createInterface as nodeCreateInterface } from 'node:readline';
+import type { RawEvent, SpawnOptions } from '../claude/types';
+export interface EventSourceDependencies {
+    spawn: typeof nodeSpawn;
+    createInterface: typeof nodeCreateInterface;
+}
+export declare const defaultDependencies: EventSourceDependencies;
+export declare function spawnCodex(prompt: string, options?: SpawnOptions, dependencies?: EventSourceDependencies): AsyncGenerator<RawEvent>;

package/dist/codex/streamer.d.ts

@@ -0,0 +1,6 @@
+import type { OutputSink, RawEvent, RawEventCallback } from '../claude/types';
+/**
+ * Process a stream of raw Codex events and write output to the sink.
+ * Uses the shared processEvent logic with Codex-specific event parsing.
+ */
+export declare function streamCodexEvents(events: AsyncIterable<RawEvent>, sink: OutputSink, onRawEvent?: RawEventCallback): Promise<void>;

package/dist/command-events.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Command event types for the dust back channel protocol.
+ *
+ * These types define structured events emitted by dust commands
+ * to a file descriptor specified by DUST_EVENTS_FD. Events are
+ * written as newline-delimited JSON using the CommandEventMessage envelope.
+ */
+/**
+ * Events emitted by dust commands.
+ */
+export type CommandEvent = {
+    type: 'check-started';
+    name: string;
+} | {
+    type: 'check-passed';
+    name: string;
+    durationMs: number;
+} | {
+    type: 'check-failed';
+    name: string;
+    durationMs: number;
+    output?: string;
+} | {
+    type: 'facts-listed';
+    facts: Array<{
+        path: string;
+        title: string;
+    }>;
+} | {
+    type: 'ideas-listed';
+    ideas: Array<{
+        path: string;
+        title: string;
+        status: string;
+    }>;
+} | {
+    type: 'principles-listed';
+    principles: Array<{
+        path: string;
+        title: string;
+    }>;
+} | {
+    type: 'tasks-listed';
+    tasks: Array<{
+        path: string;
+        title: string;
+        blockedBy: string[];
+    }>;
+};
+/**
+ * Wire format for command events, following the same pattern as EventMessage.
+ */
+export interface CommandEventMessage {
+    sequence: number;
+    timestamp: string;
+    event: CommandEvent;
+}
+/**
+ * Creates an event emitter function that writes command events to a callback.
+ * Each event is wrapped in a CommandEventMessage envelope with sequence and timestamp.
+ */
+export declare function createEventEmitter(writeEvent: (message: CommandEventMessage) => void): (event: CommandEvent) => void;

package/dist/docker/docker-agent.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Docker-based agent execution for dust loop.
+ *
+ * When a repository contains a .dust/Dockerfile, the agent runs inside
+ * a Docker container instead of directly on the host. This provides
+ * isolation and lets each project define its ideal agent environment.
+ */
+import type { spawn as nodeSpawn } from 'node:child_process';
+import type os from 'node:os';
+interface DockerConfig {
+    /** Path to the repository */
+    repoPath: string;
+    /** Docker image tag to use (e.g., 'dust-agent-myrepo') */
+    imageTag: string;
+}
+export interface DockerDependencies {
+    spawn: typeof nodeSpawn;
+    homedir: typeof os.homedir;
+    existsSync: (path: string) => boolean;
+}
+/**
+ * Check if Docker is available on the system.
+ */
+export declare function isDockerAvailable(dependencies: DockerDependencies): Promise<boolean>;
+/**
+ * Generate a deterministic Docker image tag from the repository path.
+ * Uses the repository directory name, sanitized for Docker tag requirements.
+ */
+export declare function generateImageTag(repoPath: string): string;
+type BuildResult = {
+    success: true;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Build a Docker image from the repository's .dust/Dockerfile.
+ */
+export declare function buildDockerImage(config: DockerConfig, dependencies: DockerDependencies): Promise<BuildResult>;
+/**
+ * Check if a Dockerfile exists at .dust/Dockerfile in the repository.
+ */
+export declare function hasDockerfile(repoPath: string, dependencies: DockerDependencies): boolean;
+export {};