Atomic starts
  │
  ├─► session_start / resources_discover (trust-safe interactive bootstrap, when needed)
  ├─► project_trust (user/global and CLI extensions only, before project resources load)
  ├─► session_start { reason: "startup" } (extensions not already started)
  ├─► resources_discover { reason: "startup" }
  └─► after the transcript renders: session_recovery_restore / session_recovery_replay
      │
      ▼
user sends prompt ─────────────────────────────────────────┐
  │                                                        │
  ├─► (extension commands checked first, bypass if found)  │
  ├─► input (can intercept, transform, or handle)          │
  ├─► (skill/template expansion if not handled)            │
  ├─► before_agent_start (can inject message, modify system prompt)
  ├─► agent_start                                          │
  ├─► message_start / message_update / message_end         │
  │                                                        │
  │   ┌─── turn (repeats while LLM calls tools) ───┐       │
  │   │                                            │       │
  │   ├─► turn_start                               │       │
  │   ├─► context (can modify conversation messages)   │
  │   ├─► context_with_system (can modify the full transcript)
  │   ├─► before_provider_request (can inspect or replace payload)
  │   ├─► after_provider_response (status + headers, before stream consume)
  │   ├─► provider_stream_event (each parsed provider event, before normalization)
  │   │                                            │       │
  │   │   LLM responds, may call tools:            │       │
  │   │     ├─► tool_execution_start               │       │
  │   │     ├─► tool_call (can block)              │       │
  │   │     ├─► tool_execution_update              │       │
  │   │     ├─► tool_result (can modify)           │       │
  │   │     └─► tool_execution_end                 │       │
  │   │                                            │       │
  │   ├─► turn_end (can append entries and continue)       │
  │   └─► post-tool threshold preflight            │       │
  │       (may compact before the next provider request)   │
  ├─► agent_end                                            │
  ├─► retry backoff or final-attempt recovery (when selected)
  │   └─► fresh agent_start on successful recovery         │
  ├─► agent_before_settle (can append entries and continue)│
  └─► agent_settled (final, notification only)             │
                                                           │
user sends another prompt ◄────────────────────────────────┘

/new (new session) or /resume (switch session)
  ├─► session_before_switch (can cancel)
  ├─► session_shutdown
  ├─► session_start { reason: "new" | "resume", previousSessionId? }
  ├─► resources_discover { reason: "startup" }
  └─► after the transcript renders (resume only):
      ├─► session_recovery_restore
      └─► session_recovery_replay (only when interrupted deliveries are pending)

/fork or /clone
  ├─► session_before_fork (can cancel)
  ├─► session_shutdown
  ├─► session_start { reason: "fork", previousSessionId }
  └─► resources_discover { reason: "startup" }

/compact or auto-compaction
  ├─► compaction_start / compaction_end (verbatim line-compaction status)
  ├─► session_before_compact (can cancel or provide compactedText)
  ├─► session_compact (after the compaction boundary is persisted)
  └─► session_compact_failed (failure or cancellation)

/tree navigation
  ├─► session_before_tree (can cancel or customize)
  └─► session_tree

/model or CTRL+P (model selection/cycling)
  ├─► thinking_level_select (if model change changes/clamps thinking level)
  └─► model_select

thinking level changes (settings, keybinding, pi.setThinkingLevel())
  └─► thinking_level_select

prompt cache warming (when enabled)
  └─► cache_warming_decision (can return `{ action: "warm" | "stop" }`)

exit (CTRL+C, CTRL+D, SIGHUP, SIGTERM)
  └─► session_shutdown

pi.on("project_trust", async (event, ctx) => {
  // event.cwd - current working directory
  // ctx has a limited trust context: cwd, mode, hasUI, and select/confirm/input/notify UI helpers
  if (ctx.hasUI && await ctx.ui.confirm("Trust project?", event.cwd)) {
    return { trusted: "yes", remember: true };
  }
  return { trusted: "undecided" };
});

pi.on("resources_discover", async (event, _ctx) => {
  // event.cwd - current working directory
  // event.reason - "startup" | "reload"
  return {
    skillPaths: ["/path/to/skills"],
    promptPaths: ["/path/to/prompts"],
    themePaths: ["/path/to/themes"],
  };
});

pi.on("session_start", async (event, ctx) => {
  // event.reason - "startup" | "reload" | "new" | "resume" | "fork"
  // event.previousSessionId - present for "new", "resume", and "fork"
  ctx.ui.notify(`Session: ${ctx.sessionManager.getSessionId()}`, "info");
});

pi.on("session_recovery_restore", async (event, ctx) => {
  // event.reason - "startup" | "resume" | "workflow_stage_resume"
  return { notices: ["Worker reviewer could not be restored and is gone."] };
});

pi.on("session_recovery_replay", async (event, ctx) => {
  // event.pending - [{ entryId, customType, content, details, timestamp, stageAdmissionKey?, delivery }]
  const stale = event.pending.filter((entry) => entry.customType === "my-extension:worker-note");
  return { decisions: stale.map((entry) => ({ entryId: entry.entryId, action: "drop" })) };
});

pi.on("session_info_changed", async (event, ctx) => {
  // event.name - current normalized name, or undefined if cleared
  ctx.ui.notify(`Session renamed: ${event.name ?? "(none)"}`, "info");
});

pi.on("session_before_switch", async (event, ctx) => {
  // event.reason - "new" or "resume"
  // event.targetSessionId - session we're switching to (only for "resume")

  if (event.reason === "new") {
    const ok = await ctx.ui.confirm("Clear?", "Delete all messages?");
    if (!ok) return { cancel: true };
  }
});

pi.on("session_before_fork", async (event, ctx) => {
  // event.entryId - ID of the selected entry
  // event.position - "before" for /fork, "at" for /clone
  return { cancel: true }; // Cancel fork/clone
  // OR
  return { skipConversationRestore: true }; // Reserved for future conversation restore control
});

pi.on("session_before_compact", async (event) => {
  const { preparation, branchEntries, parameters, reason, signal } = event;

  // preparation.region.lines - unnumbered compactable transcript lines
  // preparation.firstKeptEntryId - fixed start of the exact tail, or null when the tail is empty
  // preparation.tokensBefore - whole-context token estimate
  // parameters - compression_ratio, preserve_recent, query
  // branchEntries - raw entries on the active branch
  // reason - "manual" | "threshold" | "overflow"
  // preparation is a deep-frozen clone

  if (signal.aborted) return { cancel: true };

  // Cancel compaction:
  return { cancel: true };

  // Or replace only the prepared region. Whitespace-only text is rejected.
  return {
    compactedText: preparation.region.lines.slice(0, 40).join("\n"),
  };
});

pi.on("session_compact", async (event) => {
  // event.result - VerbatimCompactionResult (text, boundary, stats, parameters, rung)
  // event.compactionEntry - saved CompactionEntry with strategy "verbatim-lines"
  // event.fromExtension - true when session_before_compact provided compactedText
  // Observe-only: errors are isolated after persistence.
});

pi.on("session_compact_failed", async (event) => {
  // event.reason - "manual" | "threshold" | "overflow"
  // event.errorMessage - absent for cancellation
  // event.aborted / event.willRetry - terminal state
  // event.fromExtension - whether extension-provided text was active
});

pi.on("session_before_tree", async (event, ctx) => {
  const { preparation, signal } = event;
  return { cancel: true };
  // OR provide custom summary:
  return { summary: { summary: "...", details: {} } };
});

pi.on("session_tree", async (event, ctx) => {
  // event.newLeafId, oldLeafId, summaryEntry, fromExtension
});

pi.on("session_shutdown", async (event, ctx) => {
  // event.reason - "quit" | "reload" | "new" | "resume" | "fork"
  // event.targetSessionId - destination session for session replacement flows
  // event.fromSignal - true when a "quit" came from a host SIGTERM/SIGHUP, not an explicit quit
  // Cleanup, save state, etc.
});

pi.on("before_agent_start", async (event, ctx) => {
  if (event.messageType === "user") {
    // event.prompt - user's prompt text
    // event.images - attached images (if any)
  } else {
    // event.message - starting custom message
  }
  // event.systemPrompt - current chained system prompt for this handler
  //   (includes changes from earlier before_agent_start handlers)
  // event.systemPromptOptions - structured options used to build the system prompt
  //   .customPrompt - prompt prefix from --system-prompt, SYSTEM.md, or custom templates
  //   .forceSystemPrompt - optional exact replacement for the complete prompt
  //   .selectedTools - tools currently active in the prompt
  //   .toolSnippets - one-line descriptions for each tool
  //   .toolGuidelines - guideline bullets keyed by tool name
  //   .sections - custom XML-wrapped sections keyed by tag name
  //   .promptGuidelines - custom guideline bullets
  //   .appendSystemPrompt - text from --append-system-prompt flags
  //   .cwd - working directory
  //   .contextFiles - AGENTS.md files and other loaded context files
  //   .skills - loaded skills

  return {
    // Inject a persistent message (stored in session, sent to LLM)
    message: {
      customType: "my-extension",
      content: "Additional context for the LLM",
      display: true,
    },
    // Replace the system prompt for this turn (chained across extensions)
    systemPrompt: event.systemPrompt + "\n\nExtra instructions for this turn...",
  };
});

pi.on("agent_start", async (_event, ctx) => {});
pi.on("agent_end", async (event, ctx) => {
  // event.messages - messages from this low-level run
});

let addedReviewReminder = false;
pi.on("agent_before_settle", async (event, ctx) => {
  if (addedReviewReminder) return;
  addedReviewReminder = true;
  return {
    entries: [...event.entries, {
      type: "custom_message",
      customType: "review-reminder",
      content: "Review the final diff before replying.",
      display: false,
    }],
    continue: true,
  };
});

pi.on("agent_settled", async (_event, ctx) => {
  // ctx.isIdle() is true; runs requested here start after all settled handlers finish.
});

pi.on("ui_prompt_start", (event) => {
  // event.reason - "ui_prompt" | "project_trust"
  // event.kind - "select" | "confirm" | "input" | "editor" | "custom"
  // event.title - prompt title when available
});

pi.on("ui_prompt_end", (event) => {
  // Atomic is no longer waiting on this outer prompt span.
});

pi.on("turn_start", async (event, ctx) => {
  // event.turnIndex, event.timestamp
});

let replacedResponse = false;
pi.on("turn_end", async (event, ctx) => {
  // event.turnIndex, event.message, event.toolResults
  // event.messageEntryId, event.toolResultEntryIds, event.outcome
  // event.entries contains the structural entries proposed so far.
  if (replacedResponse || event.outcome !== "completed" || event.toolResults.length > 0) return;
  replacedResponse = true;
  return {
    entries: [
      ...event.entries,
      { type: "context_edit", targetId: event.messageEntryId, replacement: null },
      {
        type: "custom_message",
        customType: "replacement-instruction",
        content: "Answer again using the persisted user request.",
        display: false,
      },
    ],
    continue: true,
  };
});

pi.on("message_start", async (event, ctx) => {
  // event.message
});

pi.on("message_update", async (event, ctx) => {
  // event.assistantMessageEvent (token-by-token delta; no cumulative message)
});

pi.on("message_end", async (event, ctx) => {
  if (event.message.role !== "assistant") return;

  return {
    message: {
      ...event.message,
      usage: {
        ...event.message.usage,
        cost: {
          ...event.message.usage.cost,
          total: 0.123,
        },
      },
    },
  };
});

pi.on("tool_execution_start", async (event, ctx) => {
  // event.toolCallId, event.toolName, event.args
});

pi.on("tool_execution_update", async (event, ctx) => {
  // event.toolCallId, event.toolName, event.args, event.partialResult
});

pi.on("tool_execution_end", async (event, ctx) => {
  // event.toolCallId, event.toolName, event.result, event.isError, event.durationMs
});

pi.on("context", async (event, ctx) => {
  // event.messages - deep copy without system messages, safe to modify
  const filtered = event.messages.filter(m => !shouldPrune(m));
  return { messages: filtered };
});

import { getCurrentSystemMessage } from "@bastani/pi-ai";

pi.on("context_with_system", async (event, ctx) => {
  const cut = findCutIndex(event.messages);
  // Fold the dropped prefix so its prompt and tool state survives as the new head.
  const head = getCurrentSystemMessage(event.messages.slice(0, cut));
  return { messages: head ? [head, ...event.messages.slice(cut)] : event.messages.slice(cut) };
});

pi.on("before_provider_headers", (event, ctx) => {
  event.headers["x-session-id"] = ctx.sessionManager.getSessionId();
  delete event.headers["x-remove-me"];
});

pi.on("before_provider_request", (event, ctx) => {
  console.log(JSON.stringify(event.payload, null, 2));

  // Optional: replace payload
  // return { ...event.payload, temperature: 0 };
});

pi.on("after_provider_response", (event, ctx) => {
  // event.status - HTTP status code
  // event.headers - normalized response headers
  if (event.status === 429) {
    console.log("rate limited", event.headers["retry-after"]);
  }
});

pi.on("provider_stream_event", (event, ctx) => {
  // event.provider, event.api, event.model - the model that produced the event
  // event.data - the parsed provider event (read-only)
  const chunk = event.data as Record<string, unknown>;
  if (chunk.openrouter_metadata) console.log(chunk.openrouter_metadata);
});

pi.on("model_select", async (event, ctx) => {
  // event.model - newly selected model
  // event.previousModel - previous model (undefined if first selection)
  // event.source - "set" | "cycle" | "restore"

  const prev = event.previousModel
    ? `${event.previousModel.provider}/${event.previousModel.id}`
    : "none";
  const next = `${event.model.provider}/${event.model.id}`;

  ctx.ui.notify(`Model changed (${event.source}): ${prev} -> ${next}`, "info");
});

pi.on("thinking_level_select", async (event, ctx) => {
  // event.level - newly selected thinking level
  // event.previousLevel - previous thinking level

  ctx.ui.setStatus("thinking", `thinking: ${event.level}`);
});

import { isToolCallEventType } from "@bastani/atomic";

pi.on("tool_call", async (event, ctx) => {
  // event.toolName - "bash", "powershell", "read", "write", "edit", "find", "search", etc.
  // event.toolCallId
  // event.input - tool parameters (mutable)

  // Built-in tools: no type params needed
  if (isToolCallEventType("bash", event)) {
    // event.input is { command: string; timeout?: number }
    event.input.command = `source ~/.profile\n${event.input.command}`;

    if (event.input.command.includes("rm -rf")) {
      return { block: true, reason: "Dangerous command", terminate: true };
    }
  }

  if (isToolCallEventType("powershell", event)) {
    // event.input is typed as PowerShellToolInput
    event.input.command = `$ErrorActionPreference = "Stop"\n${event.input.command}`;
  }

  if (isToolCallEventType("read", event)) {
    // event.input is { path: string }
    console.log(`Reading: ${event.input.path}`);
  }

  if (isToolCallEventType("search", event)) {
    // event.input is typed as SearchToolInput
    event.input.paths ??= ".";
  }
});

// my-extension.ts
export type MyToolInput = Static<typeof myToolSchema>;

import { isToolCallEventType } from "@bastani/atomic";
import type { MyToolInput } from "my-extension";

pi.on("tool_call", (event) => {
  if (isToolCallEventType<"my_tool", MyToolInput>("my_tool", event)) {
    event.input.action;  // typed
  }
});

import { isBashToolResult, isPowerShellToolResult, isSearchToolResult } from "@bastani/atomic";

pi.on("tool_result", async (event, ctx) => {
  // event.toolName, event.toolCallId, event.input
  // event.content, event.details, event.isError

  if (isBashToolResult(event)) {
    // event.details is typed as BashToolDetails
  }

  if (isPowerShellToolResult(event)) {
    // event.details is typed as PowerShellToolDetails | undefined
  }

  if (isSearchToolResult(event)) {
    // event.details is typed as SearchToolDetails | undefined
  }

  const response = await fetch("https://example.com/summarize", {
    method: "POST",
    body: JSON.stringify({ content: event.content }),
    signal: ctx.signal,
  });

  // Modify result:
  return { content: [...], details: {...}, isError: false };
});

import { createLocalBashOperations } from "@bastani/atomic";

pi.on("user_bash", (event, ctx) => {
  // event.command - the bash command
  // event.excludeFromContext - true if !! prefix
  // event.cwd - working directory

  // Option 1: Provide custom operations (e.g., SSH)
  return { operations: remoteBashOps };

  // Option 2: Wrap atomic's built-in local bash backend
  const local = createLocalBashOperations();
  return {
    operations: {
      exec(command, cwd, options) {
        return local.exec(`source ~/.profile\n${command}`, cwd, options);
      }
    }
  };

  // Option 3: Full replacement - return result directly
  return { result: { output: "...", exitCode: 0, cancelled: false, truncated: false } };
});

pi.on("input", async (event, ctx) => {
  // event.text - raw input (before skill/template expansion)
  // event.images - attached images, if any
  // event.source - "interactive" (typed), "rpc" (API), or "extension" (via sendUserMessage)

  // Transform: rewrite input before expansion
  if (event.text.startsWith("?quick "))
    return { action: "transform", text: `Respond briefly: ${event.text.slice(7)}` };

  // Handle: respond without LLM (extension shows its own feedback)
  if (event.text === "ping") {
    ctx.ui.notify("pong", "info");
    return { action: "handled" };
  }

  // Route by source: skip processing for extension-injected messages
  if (event.source === "extension") return { action: "continue" };

  // Intercept skill commands before expansion
  if (event.text.startsWith("/skill:")) {
    // Could transform, block, or let pass through
  }

  return { action: "continue" };  // Default: pass through to expansion
});

import type { ExtensionAPI, WorkflowActivitySubscription, WorkflowRootActivity } from "@bastani/atomic";

export default function (pi: ExtensionAPI) {
  let lease: WorkflowActivitySubscription | undefined;
  const roots = new Map<string, WorkflowRootActivity>();

  pi.on("session_start", (_event, ctx) => {
    lease?.dispose();
    lease = ctx.observeWorkflowActivity((frame) => {
      if (frame.kind === "snapshot") {
        roots.clear();
        if (frame.availability !== "ready") {
          // Unknown activity must not be interpreted as idle.
          return;
        }
        for (const root of frame.roots) roots.set(root.rootRunId, root);
      } else if (frame.kind === "changed") {
        roots.set(frame.root.rootRunId, frame.root);
      } else {
        roots.delete(frame.rootRunId);
      }
    });
  });
  pi.on("session_shutdown", () => lease?.dispose());
  pi.on("workflow_stage_completed", (event) => {
    // Canonical nested identity, not the display name.
    console.log(event.eventId, event.target.stageId, event.delivery);
  });
}