noumen — coding agents are products. This is the library.

Every event type emitted during an agent run, including text streaming, tool calls, usage tracking, and errors.

thread.run() returns an AsyncGenerator<StreamEvent>. Each event has a type field that determines its shape. Your application handles these events to build UIs, log activity, or track costs.

Event reference

Core streaming

Event	Fields	Description
`text_delta`	`text`	Incremental text token from the model
`thinking_delta`	`text`	Incremental thinking/reasoning token (extended thinking)
`tool_use_start`	`toolName`, `toolUseId`	Model is calling a tool
`tool_use_delta`	`input`	Incremental tool call arguments (JSON fragment)
`tool_result`	`toolUseId`, `toolName`, `result`	Tool execution completed
`message_complete`	`message`	Full assistant message assembled
`error`	`error`	An error occurred

Usage and cost

Event	Fields	Description
`usage`	`usage`, `model`	Token usage for a single model call
`turn_complete`	`usage`, `model`, `callCount`	Accumulated usage for the full agent turn
`cost_update`	`summary`	Updated cost summary after a model call

Permissions

Event	Fields	Description
`permission_request`	`toolName`, `input`, `message`	Tool call requires user approval
`permission_granted`	`toolName`, `input`	Permission was granted for a tool call
`permission_denied`	`toolName`, `input`, `message`	Permission was denied for a tool call
`denial_limit_exceeded`	`consecutiveDenials`, `totalDenials`	Denial tracking limits hit; agent should stop retrying

Compaction

Event	Fields	Description
`compact_start`	—	Auto-compaction started
`compact_complete`	—	Auto-compaction finished
`microcompact_complete`	`tokensFreed`	Microcompaction freed tokens from tool results
`tool_result_truncated`	`toolCallId`, `originalChars`, `truncatedChars`	A tool result was truncated by the budget system

Retry

Event	Fields	Description
`retry_attempt`	`attempt`, `maxRetries`, `delayMs`, `error`	A retryable error occurred; waiting before retry
`retry_exhausted`	`attempts`, `error`	All retry attempts failed

Subagents and user input

Event	Fields	Description
`subagent_start`	`toolUseId`, `prompt`	A subagent is being spawned
`subagent_end`	`toolUseId`, `result`	A subagent finished
`user_input_request`	`toolUseId`, `question`	The agent is asking the user a question

Session and recovery

Event	Fields	Description
`session_resumed`	`sessionId`, `messageCount`	A previous session was restored
`checkpoint_snapshot`	`messageId`	A file checkpoint was taken before edits
`recovery_filtered`	`filterName`, `removedCount`	Corrupt entries were filtered during session restore
`interrupted_turn_detected`	`kind`	A previous turn was interrupted (`interrupted_tool` or `interrupted_prompt`)

Memory and tracing

Event	Fields	Description
`memory_update`	`created`, `updated`, `deleted`	Memories were extracted from the conversation
`span_start`	`name`, `spanId`	An OpenTelemetry-compatible span started
`span_end`	`name`, `spanId`, `durationMs`, `error?`	A span ended
`git_operation`	`operation`, `details`	A git operation was detected (`commit`, `push`, `pr_create`, `merge`, `rebase`)

Structured output and limits

Event	Fields	Description
`structured_output`	`data`, `schema`	Structured output was produced matching the requested schema
`max_turns_reached`	`maxTurns`, `turnCount`	The agent hit the maxTurns limit and stopped

Handling events

for await (const event of thread.run("Fix the bug")) {
  switch (event.type) {
    case "text_delta":
      // Stream text to the UI
      process.stdout.write(event.text);
      break;

    case "tool_use_start":
      console.log(`Calling ${event.toolName}...`);
      break;

    case "tool_result":
      if (event.result.isError) {
        console.error(`Tool error: ${event.result.content}`);
      }
      break;

    case "message_complete":
      // Full message is available
      console.log("\nDone:", event.message.content);
      break;

    case "usage":
      // Per-call token usage
      console.log(`Tokens: ${event.usage.total_tokens} (${event.model})`);
      break;

    case "turn_complete":
      // Accumulated across all model calls in this turn
      console.log(`Turn total: ${event.usage.total_tokens} tokens, ${event.callCount} calls`);
      break;

    case "error":
      console.error("Agent error:", event.error.message);
      break;
  }
}

Text streaming

text_delta events arrive as the model generates tokens. Concatenating all text values gives you the full response text, which also appears in the message_complete event.

Tool call flow

During a tool loop, events flow in this order:

tool_use_start -- the model requests a tool call
tool_use_delta (zero or more) -- incremental JSON argument fragments
tool_result -- the tool has been executed
The model may make another tool call (repeat from 1) or produce text

Token usage

Two usage-related events are emitted:

`usage`

Emitted after each individual model call completes. Useful for real-time cost tracking during tool loops where the model is called multiple times.

{
  type: "usage";
  usage: {
    prompt_tokens: number;
    completion_tokens: number;
    total_tokens: number;
  };
  model: string;
}

`turn_complete`

Emitted once at the end of the full agent turn, after message_complete. Contains usage accumulated across all model calls in the turn.

{
  type: "turn_complete";
  usage: {
    prompt_tokens: number;
    completion_tokens: number;
    total_tokens: number;
  };
  model: string;
  callCount: number;
}

The callCount tells you how many times the model was called during this turn. A simple text response has callCount: 1. A response that involved two tool calls has callCount: 3 (initial call + two follow-ups after tool results).

Abort

You can abort a running agent at any time:

const gen = thread.run("Do something");

// Start consuming events
for await (const event of gen) {
  if (shouldStop) {
    thread.abort();
    break;
  }
}

RunOptions

Pass options to thread.run():

const controller = new AbortController();

for await (const event of thread.run("prompt", {
  signal: controller.signal,
})) {
  // handle events
}

Option	Type	Description
`signal`	`AbortSignal`	Abort signal for cancellation
`maxTurns`	`number`	Maximum number of agent turns before stopping. Emits `max_turns_reached` when hit.
`outputFormat`	`OutputFormat`	Request structured JSON output from the model (JSON schema or JSON object mode).
`structuredOutputMode`	`"alongside_tools" \| "final_response"`	When to apply structured output: during tool use or only on the final response.

Stream Events