AgentUse: Open-source agent runtime

Failure classification

Terminal execution errors retain their broad code and human-readable message. New failures also carry an evidence-based cause, shared by the runtime, CLI JSON output, API run responses, and plugin error events. Session-list responses expose it as errorCause; full session records use error.cause.

Cause	Meaning
`run_deadline`	The execution deadline fired. Broad code remains `TIMEOUT`.
`user_stopped`, `user_interrupt`	Explicit stop or CLI interruption.
`client_disconnect`	The attached client disconnected mid-run. Broad code is `CLIENT_DISCONNECT`.
`interrupted_unknown`	An abort without evidence of its source. Not a timeout.
`model_stall`	No model progress or model-step hard limit. `phase` and optional `attempts` provide detail.
`model_transport`	The model stream connection dropped. May include `attempts`.
`provider_rate_limit`, `provider_overloaded`	HTTP 429 or a structured provider overload response.
`provider_timeout`, `provider_server`	Provider request timeout or another provider server error, not the run deadline.
`provider_content_filter`	The provider’s content filter truncated the response. Broad code is `CONTENT_FILTER`.
`provider_request`, `provider_permission`	Other provider request failure or HTTP 403.
`authentication`, `configuration`	Authentication or validated configuration failure.
`resume_state`	An approved run could not be resumed. The broad code is the specific resume failure.
`worker_interrupted`, `worker_protocol`	Worker loss or an unreadable worker response.
`request_deadline`	The daemon stopped waiting for a worker response. Does not prove the run stopped.
`unknown`	No more specific classification is supported by the evidence.

Causes are additive. Consumers must tolerate missing or future values. Historical errors are not rewritten or guessed from message text. INCOMPLETE remains an agent-declared outcome, not a crash: its cause is the blocker kind (missing_tool, no_access, waiting_on_human, and so on), with error.subject naming the stuck thing and error.causeSource (runtime, approval, agent, or inferred) saying how it was established. agentuse sessions list --json exposes these as errorCause and errorCauseSource. Failure classification does not change retry policy or imply that replaying a run with prior side effects is safe.

Reviewer-rejected incomplete runs

A human rejection can leave a run error/INCOMPLETE while automatically setting dismissedAt, which removes it from attention queues without erasing history. An incomplete report_outcome accepts an optional rejectionOnly boolean: set it to true when a human rejection in the run or a delegated child is the sole blocker. The runtime verifies the recorded human decision and leaves the run visible if any descendant is still active or has an independent failure. Machine review rejections and manually dismissed failures do not establish human rejection. When independent failures remain, set rejectionOnly: false and describe those unresolved failures in reason, rather than repeating the rejected action. Older declarations without the field retain same-session rejection handling; propagating dismissal to a parent requires an explicit rejection-only declaration. Existing historical sessions are not rewritten.

Directory Structure

Sessions are stored under AGENTUSE_DATA_DIR, which defaults through XDG conventions to ~/.local/share/agentuse:

~/.local/share/agentuse/
└── project/
    └── {git-hash}/           # Per-project isolation (or "global" for non-git)
        └── session/
            └── {sessionID}-{agentName}/
                ├── session.json
                └── {messageID}/
                    ├── message.json
                    └── part/
                        ├── {partID}.json
                        └── ...

Path Components

Component	Description
`{git-hash}`	First 16 chars of SHA-256 hash of git root path
`{sessionID}`	ULID (time-sortable unique ID)
`{agentName}`	Sanitized agent name (lowercase, alphanumeric)
`{messageID}`	ULID for message exchange
`{partID}`	ULID for individual parts

Subagent Sessions

When an agent invokes subagents, their sessions are nested:

{sessionID}-{agentName}/
├── session.json
├── {messageID}/
└── subagent/
    └── {subSessionID}-{subAgentName}/
        ├── session.json
        ├── {messageID}/
        └── subagent/
            └── {nestedSessionID}-{nestedAgentName}/
                ├── session.json
                └── ...

Each descendant repeats the same structure beneath its direct parent. The stored parentSessionID preserves that hierarchy for recursive delegation and lets session views render important nested work in context.

Data Schemas

SessionInfo

Stored in session.json at the root of each session directory.

interface SessionInfo {
  id: string;                    // ULID
  parentSessionID?: string;      // For subagent sessions

  agent: {
    name: string;                // Agent name from YAML
    filePath?: string;           // Path to .agentuse file
    description?: string;        // Agent description
    isSubAgent: boolean;         // True if subagent execution
  };

  model: string;                 // e.g., "anthropic:claude-sonnet-5"
  version: string;               // AgentUse version
  mock?: boolean;                // True when the run executed in mock mode

  config: {
    timeout?: number;            // Timeout in seconds
    maxSteps?: number;           // Max steps configured
    mcpServers?: string[];       // MCP server names
    subagents?: Array<{
      path: string;
      name?: string;
    }>;
  };

  project: {
    root: string;                // Project root directory
    cwd: string;                 // Working directory
  };

  time: {
    created: number;             // Unix timestamp (ms)
    updated: number;             // Unix timestamp (ms)
  };
}

Message

Stored in {messageID}/message.json. Contains both user input and assistant response.

interface Message {
  id: string;                    // Message exchange ID
  sessionID: string;

  time: {
    created: number;             // When user sent message
    completed?: number;          // When assistant finished
  };

  user: {
    prompt: {
      task: string;              // From .agentuse markdown body
      user?: string;             // From CLI args (optional)
    };
  };

  assistant: {
    system: string[];            // System prompts used
    modelID: string;
    providerID: string;
    mode: string;                // 'build', 'plan', etc.
    path: {
      cwd: string;
      root: string;
    };
    cost: number;
    tokens: {
      input: number;
      output: number;
      reasoning: number;
      cache: {
        read: number;
        write: number;
      };
    };
    error?: {
      message: string;
      type?: string;
      stack?: string;
    };
  };
}

Parts

Stored in {messageID}/part/{partID}.json. Each part represents a discrete unit of content.

Base Fields

All parts include these fields:

interface PartBase {
  id: string;        // Part ID (ULID)
  sessionID: string; // Session this part belongs to
  messageID: string; // Message this part belongs to
}

Part Types

Type	Description
`text`	Text output from the model
`reasoning`	Internal reasoning/thinking content
`tool`	Tool call with input, output, status, duration
`file`	File references
`agent`	Subagent invocations
`step-start`	Step boundary markers
`step-finish`	Step completion with token counts

TextPart

interface TextPart extends PartBase {
  type: 'text';
  text: string;
  synthetic?: boolean;
  time?: {
    start: number;
    end?: number;
  };
}

ReasoningPart

interface ReasoningPart extends PartBase {
  type: 'reasoning';
  text: string;
  metadata?: Record<string, unknown>;
  time: {
    start: number;
    end?: number;
  };
}

ToolPart

interface ToolPart extends PartBase {
  type: 'tool';
  callID: string;    // Tool call ID from AI SDK
  tool: string;      // Tool name
  state: ToolState;
}

type ToolState =
  | { status: 'pending' }
  | {
      status: 'running';
      input: unknown;
      title?: string;
      metadata?: Record<string, unknown>;
      time: { start: number };
    }
  | {
      status: 'completed';
      input: unknown;
      output: unknown;
      title?: string;
      metadata?: Record<string, unknown>;
      time: { start: number; end: number };
    }
  | {
      status: 'error';
      input: unknown;
      error: string;
      metadata?: Record<string, unknown>;
      time: { start: number; end: number };
    };

FilePart

interface FilePart extends PartBase {
  type: 'file';
  mime: string;
  filename?: string;
  url: string;
  source?: {
    type: 'file' | 'symbol';
    path: string;
    text?: {
      value: string;
      start: number;
      end: number;
    };
  };
}

AgentPart

interface AgentPart extends PartBase {
  type: 'agent';
  name: string;
  source?: {
    value: string;
    start: number;
    end: number;
  };
}

StepStartPart

interface StepStartPart extends PartBase {
  type: 'step-start';
}

StepFinishPart

interface StepFinishPart extends PartBase {
  type: 'step-finish';
  cost: number;
  tokens: {
    input: number;
    output: number;
    reasoning: number;
    cache: {
      read: number;
      write: number;
    };
  };
}

The mock flag is what keeps test runs out of the operational views. It is set by agentuse test and agentuse run --mock, and absent on a normal run. agentuse sessions show surfaces it as a warning line so a fabricated result is never mistaken for a real one:

Mock:        ⚠ mock run: some or all tool results were fabricated, not executed

List views mark the same sessions with a trailing · mock.

Testing Agents - Validating an agent in mock mode
Session Logs Guide - How to use the sessions CLI
Environment Variables - Configure storage location

Getting Started

Building

Running

Reference

Session Storage

Failure classification

Reviewer-rejected incomplete runs

Directory Structure

Path Components

Subagent Sessions

Data Schemas

SessionInfo

Message

Parts

Base Fields

Part Types

TextPart

ReasoningPart

ToolPart

FilePart

AgentPart

StepStartPart

StepFinishPart

​Failure classification

​Reviewer-rejected incomplete runs

​Directory Structure

​Path Components

​Subagent Sessions

​Data Schemas

​SessionInfo

​Message

​Parts

​Base Fields

​Part Types

​TextPart

​ReasoningPart

​ToolPart

​FilePart

​AgentPart

​StepStartPart

​StepFinishPart

​Related

Failure classification

Reviewer-rejected incomplete runs

Directory Structure

Path Components

Subagent Sessions

Data Schemas

SessionInfo

Message

Parts

Base Fields

Part Types

TextPart

ReasoningPart

ToolPart

FilePart

AgentPart

StepStartPart

StepFinishPart

Related