@joshski/dust 0.1.102 → 0.1.103

package/.dust/principles/{enable-flow-state.md → agentic-flow-state.md}

@@ -1,14 +1,18 @@
-# Enable Flow State
+# Agentic Flow State
 
 Flow is the mental state where work becomes effortless - where you're fully immersed, losing track of time, operating at peak performance. Psychologist Mihaly Csikszentmihalyi identified three conditions that create flow: clear goals, immediate feedback, and challenge-skill balance.
 
+For AI agents, achieving flow state means staying engaged and productive without interruption. Agents enter flow when they have optimal context, comprehensive guard rails, and minimal friction. Context window optimization ensures agents have exactly what they need without cognitive overload. In-session guard rails prevent agents from straying off course or making mistakes that break their momentum.
+
 Dust's design targets these conditions directly:
 
 - **Clear goals**: Task files and lightweight planning give you a concrete target. You know exactly what you're building next.
 - **Immediate feedback**: Fast feedback loops let you see results quickly. Each change confirms you're on track or shows you what to adjust.
 - **Challenge-skill balance**: Small units of work and agent autonomy keep you in the zone - challenged enough to stay engaged, supported enough to succeed.
+- **Context window efficiency**: Progressive disclosure and artifact summarization ensure agents have the right context without overflow.
+- **Comprehensive guard rails**: Lint rules, type checks, and automated validation catch mistakes before they compound.
 
-Everything dust does serves flow. When developers stay in flow, they produce better work, sustain their energy, and enjoy the process.
+Everything dust does serves flow. When agents stay in flow, they produce better work, sustain their momentum, and complete tasks autonomously.
 
 ## Parent Principle
 

package/.dust/principles/human-ai-collaboration.md

@@ -8,7 +8,7 @@ Today's AI coding tools keep humans in a tight loop with agents. Dust is designe
 
 ## Parent Principle
 
-- [Enable Flow State](enable-flow-state.md)
+- [Agentic Flow State](agentic-flow-state.md)
 
 ## Sub-Principles
 

package/.dust/principles/maintainable-codebase.md

@@ -6,7 +6,7 @@ This principle governs how we develop and maintain dust itself, separate from th
 
 ## Parent Principle
 
-- [Enable Flow State](enable-flow-state.md)
+- [Agentic Flow State](agentic-flow-state.md)
 
 ## Sub-Principles
 

package/dist/agent-events.d.ts

@@ -50,6 +50,7 @@ export interface EventMessage {
     repository: string;
     repoId?: number;
     agentSessionId?: string;
+    traceId?: string;
     event: AgentSessionEvent;
 }
 /**

package/dist/bucket/repository.d.ts

@@ -67,6 +67,10 @@ export interface RepositoryDependencies {
     revealFamily?: (familyName: string) => void;
     /** Shell runner for pre-flight commands (install, check) */
     shellRunner?: import('../cli/process-runner').ShellRunner;
+    /** Force Docker mode using bundled default Dockerfile */
+    forceDocker?: boolean;
+    /** Force Apple Container mode using bundled default Dockerfile */
+    forceAppleContainer?: boolean;
 }
 /**
  * Start (or restart) the per-repository loop and keep lifecycle state accurate.

package/dist/claude/types.d.ts

@@ -48,6 +48,10 @@ export interface OutputSink {
     line(text: string): void;
 }
 export interface DockerSpawnConfig {
+    /** CLI command for running containers (e.g., 'docker', 'container') */
+    runCommand?: string;
+    /** Hostname or IP the container uses to reach the host */
+    hostAddress?: string;
     /** Docker image tag to use */
     imageTag: string;
     /** Path to the repository (used for volume mounts) */

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

@@ -1,8 +1,12 @@
-import type { RawEvent, SpawnOptions } from '../claude/types';
+import type { DockerSpawnConfig, RawEvent, SpawnOptions } from '../claude/types';
 import type { CreateReadlineForEvents, SpawnForEvents } from '../process/spawn-contract';
 export interface EventSourceDependencies {
     spawn: SpawnForEvents;
     createInterface: CreateReadlineForEvents;
 }
 export declare const defaultDependencies: EventSourceDependencies;
+/**
+ * Build docker run arguments for spawning codex in a container.
+ */
+export declare function buildDockerRunArguments(docker: DockerSpawnConfig, codexArguments: string[], env: Record<string, string>): string[];
 export declare function spawnCodex(prompt: string, options?: SpawnOptions, dependencies?: EventSourceDependencies): AsyncGenerator<RawEvent>;

package/dist/command-events.d.ts

@@ -53,10 +53,11 @@ export type CommandEvent = {
 export interface CommandEventMessage {
     sequence: number;
     timestamp: string;
+    traceId?: 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;
+export declare function createEventEmitter(writeEvent: (message: CommandEventMessage) => void, traceId?: string): (event: CommandEvent) => void;

package/dist/container/apple-container-runtime.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Apple Container implementation of the ContainerRuntime interface.
+ *
+ * Apple's container project (https://github.com/apple/container) runs Linux
+ * containers as lightweight VMs on Apple Silicon (macOS 26+). It uses
+ * OCI-compatible images, so existing Dockerfiles work without modification.
+ */
+import type { ContainerRuntime } from './runtime';
+/**
+ * Apple Container runtime implementation.
+ */
+export declare const appleContainerRuntime: ContainerRuntime;

package/dist/container/docker-runtime.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Docker implementation of the ContainerRuntime interface.
+ */
+import type { ContainerDependencies, ContainerRuntime } from './runtime';
+/**
+ * Get the path to the bundled default Dockerfile.
+ */
+export declare function getDefaultDockerfilePath(): string;
+/**
+ * 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;
+/**
+ * Check if a Dockerfile exists at .dust/config/container/Dockerfile.
+ */
+export declare function hasDockerfile(repoPath: string, dependencies: ContainerDependencies): boolean;
+/**
+ * Docker runtime implementation.
+ */
+export declare const dockerRuntime: ContainerRuntime;

package/dist/container/runtime.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Container runtime abstraction for dust agent execution.
+ *
+ * This module defines a provider-agnostic interface for container runtimes,
+ * allowing dust to support multiple container technologies (Docker, Apple
+ * Container, etc.) while keeping the agent orchestration logic decoupled.
+ */
+import type { spawn as nodeSpawn } from 'node:child_process';
+import type os from 'node:os';
+/**
+ * Dependencies injected into container runtime operations.
+ * Keeps the runtime implementations pure by externalizing I/O.
+ */
+export interface ContainerDependencies {
+    spawn: typeof nodeSpawn;
+    homedir: typeof os.homedir;
+    existsSync: (path: string) => boolean;
+}
+/**
+ * Configuration for building a container image.
+ */
+export interface BuildConfig {
+    /** Path to the repository root */
+    repoPath: string;
+    /** Tag to apply to the built image */
+    imageTag: string;
+    /** Optional path to a custom Dockerfile */
+    dockerfilePath?: string;
+}
+/**
+ * Result of a container image build operation.
+ */
+export type BuildResult = {
+    success: true;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Configuration for running a container.
+ */
+export interface RunConfig {
+    imageTag: string;
+    repoPath: string;
+    homeDir: string;
+    gitProxyUrl?: string;
+    claudeApiProxyUrl?: string;
+    settingsFilePath?: string;
+}
+/**
+ * Abstract interface for container runtimes.
+ *
+ * Each runtime implementation provides the same capabilities through
+ * its native CLI tools. The interface is designed for:
+ * - Pure functions where possible (buildRunArgs)
+ * - Dependency injection for I/O operations (isAvailable, buildImage)
+ */
+export interface ContainerRuntime {
+    /** Unique identifier for this runtime */
+    name: 'docker' | 'apple-container';
+    /** Check if the runtime CLI is available on the system */
+    isAvailable: (dependencies: ContainerDependencies) => Promise<boolean>;
+    /** Build an image from a Dockerfile */
+    buildImage: (config: BuildConfig, dependencies: ContainerDependencies) => Promise<BuildResult>;
+    /** The CLI command for running containers (e.g., 'docker', 'container') */
+    runCommand: string;
+    /** Hostname or IP the container uses to reach the host (e.g., 'host.docker.internal', '192.168.64.1') */
+    hostAddress: string;
+    /** Map dust's run options to CLI arguments */
+    buildRunArgs: (config: RunConfig) => string[];
+}

package/dist/container/select-runtime.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Runtime selection logic for container execution.
+ *
+ * Selects the appropriate container runtime based on CLI flags.
+ */
+import type { ContainerRuntime } from './runtime';
+interface RuntimeFlags {
+    docker: boolean;
+    appleContainer: boolean;
+}
+type RuntimeSelectionResult = {
+    success: true;
+    runtime: ContainerRuntime | null;
+    forceContainer: boolean;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Select container runtime based on CLI flags.
+ *
+ * Returns:
+ * - `{ success: true, runtime: ContainerRuntime, forceContainer: true }` when a runtime flag is set
+ * - `{ success: true, runtime: null, forceContainer: false }` when no flags are set (use Dockerfile detection)
+ * - `{ success: false, error: string }` when both flags are set (mutually exclusive)
+ */
+export declare function selectContainerRuntime(flags: RuntimeFlags): RuntimeSelectionResult;
+export {};

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

@@ -1,47 +1,33 @@
 /**
  * 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.
+ * When a repository contains a .dust/config/container/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.
+ *
+ * This module re-exports utilities from the container abstraction layer
+ * and provides the high-level prepareDockerConfig orchestration function.
  */
-import type { spawn as nodeSpawn } from 'node:child_process';
-import type os from 'node:os';
-interface DockerConfig {
-    /** Path to the repository */
+import type { ContainerDependencies, ContainerRuntime } from '../container/runtime';
+import { generateImageTag, getDefaultDockerfilePath, hasDockerfile } from '../container/docker-runtime';
+export type { ContainerDependencies as DockerDependencies } from '../container/runtime';
+export { generateImageTag, getDefaultDockerfilePath, hasDockerfile };
+export declare function isDockerAvailable(dependencies: ContainerDependencies): Promise<boolean>;
+export declare function buildDockerImage(config: {
     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 = {
+    dockerfilePath?: string;
+}, dependencies: ContainerDependencies): Promise<{
     success: true;
 } | {
     success: false;
     error: string;
-};
+}>;
 /**
- * Build a Docker image from the repository's .dust/Dockerfile.
+ * Check if a Dockerfile exists at the legacy .dust/Dockerfile location.
  */
-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;
-type DockerPrepareEvent = {
+export declare function hasLegacyDockerfile(repoPath: string, dependencies: ContainerDependencies): boolean;
+type ContainerPrepareEvent = {
     type: 'loop.docker_detected';
     imageTag: string;
 } | {
@@ -54,26 +40,31 @@ type DockerPrepareEvent = {
     type: 'loop.docker_error';
     error: string;
 };
-interface DockerSpawnConfig {
+interface ContainerSpawnConfig {
     imageTag: string;
     repoPath: string;
     homeDir: string;
 }
-type PrepareDockerConfigResult = {
-    config: DockerSpawnConfig;
+type PrepareContainerConfigResult = {
+    config: ContainerSpawnConfig;
 } | {
     error: string;
 } | Record<string, never>;
+interface PrepareContainerOptions {
+    forceContainer?: boolean;
+}
 /**
- * Prepare Docker configuration for agent execution.
+ * Prepare container configuration with a specific runtime.
  *
- * Checks for a .dust/Dockerfile, verifies Docker availability, builds the image,
- * and returns the spawn configuration. Emits events throughout the process.
+ * When runtime is null, defaults to Docker runtime (for Dockerfile detection mode).
+ */
+export declare function prepareContainerConfigWithRuntime(repoPath: string, dependencies: ContainerDependencies, onEvent: (event: ContainerPrepareEvent) => void, runtime: ContainerRuntime | null, options?: PrepareContainerOptions): Promise<PrepareContainerConfigResult>;
+/**
+ * Prepare Docker configuration for agent execution.
  *
- * Returns:
- * - `{ config: DockerSpawnConfig }` on success
- * - `{ error: string }` on failure (Docker not available or build failed)
- * - `{}` if no Dockerfile exists
+ * This is a thin wrapper around prepareContainerConfig that uses the Docker
+ * runtime. Kept for backward compatibility with existing callers.
  */
-export declare function prepareDockerConfig(repoPath: string, dependencies: DockerDependencies, onEvent: (event: DockerPrepareEvent) => void): Promise<PrepareDockerConfigResult>;
-export {};
+export declare function prepareDockerConfig(repoPath: string, dependencies: ContainerDependencies, onEvent: (event: ContainerPrepareEvent) => void, options?: {
+    forceDocker?: boolean;
+}): Promise<PrepareContainerConfigResult>;