505 Commits

• feat(coding-agent): add ctx.ui.setEditorComponent() extension API

  - Add setEditorComponent() to ctx.ui for custom editor components
  - Add CustomEditor base class for extensions (handles app keybindings)
  - Add keybindings parameter to ctx.ui.custom() factory (breaking change)
  - Add modal-editor.ts example (vim-like modes)
  - Add rainbow-editor.ts example (animated text highlighting)
  - Update docs: extensions.md, tui.md Pattern 7
  - Clean up terminal on TUI render errors

  Mario Zechner · 2026-01-07 16:11:49 +01:00
  09471ebc7d
• feat(coding-agent): add timeout option to extension dialogs with live countdown

  Extension UI dialogs (select, confirm, input) now support a timeout option
  that auto-dismisses with a live countdown display. Simpler alternative to
  manually managing AbortSignal for timed dialogs.
  
  Also adds ExtensionUIDialogOptions type export and updates RPC mode to
  forward timeout to clients.

  Nico Bailon · 2026-01-06 21:49:27 -08:00
  77477f6166
• Add AbortSignal support to extension UI dialogs

  Closes #474

  Nico Bailon · 2026-01-06 15:01:15 -08:00
  9771fa1e44
• Add ExtensionAPI methods, preset example, and TUI documentation improvements

  - ExtensionAPI: setModel(), getThinkingLevel(), setThinkingLevel() methods
  - New preset.ts example with plan/implement presets for model/thinking/tools switching
  - Export all UI components from pi-coding-agent for extension use
  - docs/tui.md: Common Patterns section with copy-paste code for SelectList, BorderedLoader, SettingsList, setStatus, setWidget, setFooter
  - docs/tui.md: Key Rules section for extension UI development
  - docs/extensions.md: Exhaustive example links for all ExtensionAPI methods and events
  - System prompt now references docs/tui.md for TUI development
  
  Fixes #509, relates to #347

  Mario Zechner · 2026-01-06 23:24:23 +01:00
  59d8b7948c
• Export truncation utilities for custom tools, add truncated-tool example

  - Export truncateHead, truncateTail, truncateLine, formatSize, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES from package
  - Add examples/extensions/truncated-tool.ts showing proper output truncation with custom rendering
  - Document output truncation best practices in docs/extensions.md

  Mario Zechner · 2026-01-06 22:13:08 +01:00
  7c99ea54bf
• Extensions: add pi.sendUserMessage() for sending user messages

  Adds sendUserMessage() to the extension API, allowing extensions to send
  actual user messages (role: user) rather than custom messages. Unlike
  sendMessage(), this always triggers a turn and behaves as if the user
  typed the message.
  
  - Add SendUserMessageHandler type and sendUserMessage() to ExtensionAPI
  - Wire handler through loader, runner, and all modes
  - Implement via prompt() with expandPromptTemplates: false
  - Add send-user-message.ts example with /ask, /steer, /followup commands
  - Document in extensions.md
  
  fixes #483

  Mario Zechner · 2026-01-06 13:40:24 +01:00
  7210086677
• Add ctx.ui.setFooter() for extensions to replace footer component

  Extensions can now replace the built-in footer with a custom component:
  - setFooter(factory) replaces with custom component
  - setFooter(undefined) restores built-in footer
  
  Includes example extension demonstrating context usage display.
  
  Closes #481

  Mario Zechner · 2026-01-06 12:39:45 +01:00
  f023af0dab
• docs: clarify SDK extension discovery and settings.json support
  Mario Zechner · 2026-01-05 18:00:32 +01:00
  3129e2ac10
• Add extensions option to createAgentSession SDK

  - Accept ExtensionFactory[] for inline extensions (merged with discovery)
  - Mark preloadedExtensions as @internal (CLI implementation detail)
  - Update sdk.md with inline extension example
  - Update CHANGELOG

  Mario Zechner · 2026-01-05 03:38:56 +01:00
  79cb8f0906
• Add customTools option back to createAgentSession SDK

  - Accepts ToolDefinition[] directly (simplified from old { path?, tool } format)
  - Tools are combined with extension-registered tools
  - Updated sdk.md documentation
  - Updated CHANGELOG

  Mario Zechner · 2026-01-05 03:34:36 +01:00
  8da793b1ba
• Improve Custom Components docs: explain editor replacement, simplify example
  Mario Zechner · 2026-01-05 03:09:02 +01:00
  6bd5e419a6
• Document setWidget Component support
  Mario Zechner · 2026-01-05 03:07:11 +01:00
  a5741df69a
• Add Custom UI section, update CHANGELOG migration docs

  - Add ## Custom UI section consolidating dialogs, widgets, custom components, message rendering, theme colors
  - Simplify ctx.ui and pi.registerMessageRenderer in other sections to reference Custom UI
  - Update CHANGELOG to reflect auto-migration of commands/ to prompts/

  Mario Zechner · 2026-01-05 03:06:39 +01:00
  0919ec5417
• Restructure extensions.md: add Custom Tools section, improve sendMessage docs

  - Add ## Custom Tools section with Tool Definition, Multiple Tools, Custom Rendering
  - Expand pi.sendMessage docs with deliverAs mode explanations
  - Add Extension Styles subsection (single file, dir, package.json)
  - Expand ExtensionCommandContext with waitForIdle, newSession, branch, navigateTree
  - Replace lodash with zod in examples
  - Various fixes and reorganization

  Mario Zechner · 2026-01-05 03:04:19 +01:00
  0e41b9c2a2
• Add table of contents to extensions.md
  Mario Zechner · 2026-01-05 02:51:45 +01:00
  e4f8215f97
• Show UI context methods in extension quick start example
  Mario Zechner · 2026-01-05 02:49:52 +01:00
  3e38fce541
• Add npm deployment to package.json benefits
  Mario Zechner · 2026-01-05 02:48:40 +01:00
  3f60de8929
• Add note about npm dependencies in extensions
  Mario Zechner · 2026-01-05 02:48:18 +01:00
  c8cfef7225
• Improve extension discovery docs with multi-entry package.json example
  Mario Zechner · 2026-01-05 02:47:52 +01:00
  f4a3724b7e
• Add migration for commands->prompts, warn about deprecated hooks/tools dirs

  - Auto-migrate commands/ to prompts/ on startup
  - Warn if hooks/ or tools/ directories contain custom extensions
  - Show deprecation warnings in interactive mode with keypress to continue
  - Update CHANGELOG and docs with full migration guide

  Mario Zechner · 2026-01-05 02:41:08 +01:00
  91cca23d23
• Merge hooks and custom-tools into unified extensions system (#454)

  Breaking changes:
  - Settings: 'hooks' and 'customTools' arrays replaced with 'extensions'
  - CLI: '--hook' and '--tool' flags replaced with '--extension' / '-e'
  - API: HookMessage renamed to CustomMessage, role 'hookMessage' to 'custom'
  - API: FileSlashCommand renamed to PromptTemplate
  - API: discoverSlashCommands() renamed to discoverPromptTemplates()
  - Directories: commands/ renamed to prompts/ for prompt templates
  
  Migration:
  - Session version bumped to 3 (auto-migrates v2 sessions)
  - Old 'hookMessage' role entries converted to 'custom'
  
  Structural changes:
  - src/core/hooks/ and src/core/custom-tools/ merged into src/core/extensions/
  - src/core/slash-commands.ts renamed to src/core/prompt-templates.ts
  - examples/hooks/ and examples/custom-tools/ merged into examples/extensions/
  - docs/hooks.md and docs/custom-tools.md merged into docs/extensions.md
  
  New test coverage:
  - test/extensions-runner.test.ts (10 tests)
  - test/extensions-discovery.test.ts (26 tests)
  - test/prompt-templates.test.ts

  Mario Zechner · 2026-01-05 01:43:35 +01:00
  c6fc084534
• Fix event bus async error handling, clear pending messages on session switch, improve SDK docs

  - event-bus.ts: await async handlers to catch errors properly
  - agent-session.ts: clear _pendingNextTurnMessages on newSession/switchSession/branch
  - sdk.ts: make eventBus first (required) param for discoverHooks/discoverCustomTools
  - docs/sdk.md: document eventBus sharing pattern for hook/tool communication

  Mario Zechner · 2026-01-04 22:04:50 +01:00
  be330fdd9c
• docs(coding-agent): fix event bus docs - handlers persist, remove redundant note
  Mario Zechner · 2026-01-04 21:39:13 +01:00
  024ec33bf2
• docs(coding-agent): update event bus docs - async errors now caught automatically
  Mario Zechner · 2026-01-04 21:37:16 +01:00
  99a539baa4
• feat(coding-agent): add event bus for tool/hook communication (#431)

  * feat(coding-agent): add event bus for tool/hook communication
  
  Adds pi.events API enabling custom tools and hooks to communicate via
  pub/sub. Tools can emit events, hooks can listen. Shared EventBus instance
  created per session in createAgentSession().
  
  - EventBus interface with emit() and on() methods
  - on() returns unsubscribe function
  - Threaded through hook and tool loaders
  - Documented in hooks.md and custom-tools.md
  
  * fix(coding-agent): wrap event handlers to catch errors
  
  * docs: note async handler error handling for event bus
  
  * feat(coding-agent): add sendMessage to tools, nextTurn delivery mode
  
  - Custom tools now have pi.sendMessage() for direct agent notifications
  - New deliverAs: 'nextTurn' queues messages for next user prompt
  - Fix: hooks and tools now share the same eventBus (was isolated before)
  
  * fix(coding-agent): nextTurn delivery should always queue, even when streaming

  Nico Bailon · 2026-01-04 21:36:19 +01:00
  9c9e6822e3
• feat(hooks): expose setTitle to HookUIContext (#446)
  Aliou Diallo · 2026-01-04 20:55:52 +01:00
  5cb7af1ddc
• docs: update CHANGELOG and hooks.md with missing items

  - tools.ts example hook
  - Multiple messages from before_agent_start
  - getSettingsListTheme/getSelectListTheme optional theme param
  - Hook error stack traces

  Mario Zechner · 2026-01-04 19:01:35 +01:00
  5318b42bd2
• feat(hooks): add systemPromptAppend to before_agent_start, full tool registry

  - before_agent_start handlers can return systemPromptAppend to dynamically
    append text to the system prompt for that turn
  - Multiple hooks' systemPromptAppend strings are concatenated
  - Multiple hooks' messages are now all injected (not just first)
  - Tool registry now contains ALL built-in tools (read, bash, edit, write,
    grep, find, ls) regardless of --tools flag
  - --tools only sets initially active tools, hooks can enable any via
    setActiveTools()
  - System prompt automatically rebuilds when tools change, updating tool
    descriptions and guidelines
  - Add pirate.ts example hook demonstrating systemPromptAppend
  - Update hooks.md with systemPromptAppend documentation

  Mario Zechner · 2026-01-04 18:21:26 +01:00
  e4dd21a3b2
• refactor: address PR feedback - merge setWidget, use KeyId for shortcuts

  1. Merge setWidget and setWidgetComponent into single overloaded method
     - Accepts either string[] or component factory function
     - Uses single Map<string, Component> internally
     - String arrays wrapped in Container with Text components
  
  2. Use KeyId type for registerShortcut instead of plain string
     - Import Key from @mariozechner/pi-tui
     - Update plan-mode example to use Key.shift('p')
     - Type-safe shortcut registration
  
  3. Fix tool API docs
     - Both built-in and custom tools can be enabled/disabled
     - Removed incorrect 'custom tools always active' statement
  
  4. Use matchesKey instead of matchShortcut (already done in rebase)

  Helmut Januschka · 2026-01-04 18:13:30 +01:00
  8ecb1d6c0b
• feat(hooks): add setWidgetComponent for custom TUI components

  - New ctx.ui.setWidgetComponent(key, factory) method
  - Allows custom Component to render as widget without taking focus
  - Unlike custom(), widget components render inline above editor
  - Components are disposed when cleared or replaced
  - Falls back to no-op in RPC/print modes

  Helmut Januschka · 2026-01-04 18:13:29 +01:00
  ce88ebcd68
• fix(widgets): add max line limit and document multi-hook behavior

  - Limit total widget lines to 10 to prevent viewport overflow/flicker
  - Show '... (widget truncated)' when limit exceeded
  - Document that multiple hooks stack widgets vertically
  - Add caution about keeping widgets small

  Helmut Januschka · 2026-01-04 18:13:29 +01:00
  9b53b89bd5
• refactor(hooks): address PR feedback

  - Rename getTools/setTools to getActiveTools/setActiveTools
  - Add getAllTools to enumerate all configured tools
  - Remove text_delta event (use turn_end/agent_end instead)
  - Add shortcut conflict detection:
    - Skip shortcuts that conflict with built-in shortcuts (with warning)
    - Log warnings when hooks register same shortcut (last wins)
  - Add note about prompt cache invalidation in setActiveTools
  - Update plan-mode hook to use agent_end for [DONE:id] parsing

  Helmut Januschka · 2026-01-04 18:13:29 +01:00
  4ecf3f9422
• feat(hooks): add text_delta event for streaming text monitoring

  - New text_delta hook event fires for each chunk of streaming text
  - Enables real-time monitoring of agent output
  - Plan-mode hook now updates todo progress as [DONE:id] tags stream in
  - Each todo item has unique ID for reliable tracking

  Helmut Januschka · 2026-01-04 18:13:28 +01:00
  d1eea3ac4e
• feat(hooks): add setWidget API for multi-line status displays

  - ctx.ui.setWidget(key, lines) for multi-line displays above editor
  - Widgets appear below 'Working...' indicator, above editor
  - Supports ANSI styling including strikethrough
  - Added theme.strikethrough() method
  - Plan-mode hook now shows todo list with checkboxes
  - Completed items show checked box and strikethrough text

  Helmut Januschka · 2026-01-04 18:13:28 +01:00
  dc44816051
• feat(coding-agent): add hook API for CLI flags, shortcuts, and tool control

  Hook API additions:
  - pi.getTools() / pi.setTools(toolNames) - dynamically enable/disable tools
  - pi.registerFlag(name, options) / pi.getFlag(name) - register custom CLI flags
  - pi.registerShortcut(shortcut, options) - register keyboard shortcuts
  
  Plan mode hook (examples/hooks/plan-mode.ts):
  - /plan command or Shift+P shortcut to toggle
  - --plan CLI flag to start in plan mode
  - Read-only tools: read, bash, grep, find, ls
  - Bash restricted to non-destructive commands (blocks rm, mv, git commit, etc.)
  - Interactive prompt after each response: execute, stay, or refine
  - Shows plan indicator in footer when active
  - State persists across sessions

  Helmut Januschka · 2026-01-04 18:13:28 +01:00
  c956a726ed
• WIP: Add hook API for dynamic tool control with plan-mode hook example

  - Add pi.getTools() and pi.setTools(toolNames) to HookAPI
  - Hooks can now enable/disable tools dynamically
  - Changes take effect on next agent turn
  
  New example hook: plan-mode.ts
  - Claude Code-style read-only exploration mode
  - /plan command toggles plan mode on/off
  - Plan mode tools: read, bash, grep, find, ls
  - Edit/write tools disabled in plan mode
  - Injects context telling agent about restrictions
  - After each response, prompts to execute/stay/refine
  - State persists across sessions

  Helmut Januschka · 2026-01-04 18:13:28 +01:00
  059292ead1
• Update tui.md docs: replace isXxx() with matchesKey() and Key helper
  Mario Zechner · 2026-01-03 23:10:22 +01:00
  22abf50d85
• Fix slash commands and hook commands during streaming

  - Hook commands now execute immediately during streaming (they manage their own LLM interaction via pi.sendMessage())
  - File-based slash commands are expanded and queued via steer/followUp during streaming
  - prompt() accepts new streamingBehavior option ('steer' or 'followUp') for explicit queueing during streaming
  - steer() and followUp() now expand file-based slash commands and error on hook commands
  - RPC prompt command accepts optional streamingBehavior field
  - Updated docs: rpc.md, sdk.md, CHANGELOG.md
  
  fixes #420

  Mario Zechner · 2026-01-03 15:36:54 +01:00
  e9cf3c1835
• docs: update README.md, hooks.md, and CHANGELOG for steer()/followUp() API

  - Fix settings-selector descriptions to explain one-at-a-time vs all
  - Update README.md message queuing section, settings example, and table
  - Update hooks.md: hasPendingMessages, sendMessage options, triggerTurn example
  - Add Theme/ThemeColor export and hasPendingMessages rename to CHANGELOG

  Mario Zechner · 2026-01-03 00:19:07 +01:00
  9f2e6ac5eb
• Add todo hook companion to todo custom tool

  - /todos command displays all todos on current branch with custom UI
  - Update hooks.md to clarify components must not be wrapped in Box/Container
  - Cross-reference tool and hook in example READMEs

  Mario Zechner · 2026-01-03 00:13:25 +01:00
  74dc5e7c49
• Update docs for ctx.ui.editor() and handoff example

  - Added ctx.ui.editor() to hooks.md and custom-tools.md
  - Added ctx.ui.editor() to CHANGELOG.md
  - Added handoff.ts to examples/hooks/README.md

  Mario Zechner · 2026-01-02 01:26:21 +01:00
  02175d908b
• fix(coding-agent): prevent full re-renders during write tool streaming

  Move line count from header to footer to avoid changing the first line
  during streaming, which was triggering full screen re-renders in the
  TUI's differential rendering logic.

  Mario Zechner · 2026-01-02 01:11:06 +01:00
  d51770a63d
• Add agent state methods to CustomToolContext and fix abort signature

  CustomToolContext now has:
  - isIdle() - check if agent is streaming
  - hasQueuedMessages() - check if user has queued messages
  - abort() - abort current operation (fire-and-forget)
  
  Changed abort() signature from Promise<void> to void in both
  HookContext and CustomToolContext. The abort is fire-and-forget:
  it calls session.abort() without awaiting, so the abort signal
  is set immediately while waitForIdle() runs in the background.
  
  Fixes #388

  Mario Zechner · 2026-01-02 00:31:23 +01:00
  03159d2f4b
• Split HookContext and HookCommandContext to prevent deadlocks

  HookContext (all events):
  - isIdle() - read-only state check
  - hasQueuedMessages() - read-only state check
  - abort() - fire-and-forget, does not wait
  
  HookCommandContext (slash commands only):
  - waitForIdle() - waits for agent to finish
  - newSession(options?) - create new session
  - branch(entryId) - branch from entry
  - navigateTree(targetId, options?) - navigate session tree
  
  Session control methods moved from HookAPI (pi.*) to HookCommandContext (ctx.*)
  because they can deadlock when called from event handlers that run inside
  the agent loop (tool_call, tool_result, context events).

  Mario Zechner · 2026-01-02 00:24:58 +01:00
  0d9fddec1e
• Add session management and agent state methods to hooks API

  HookAPI additions:
  - pi.newSession(options?) - create new session with optional setup callback
  - pi.branch(entryId) - branch from a specific entry
  - pi.navigateTree(targetId, options?) - navigate the session tree
  
  HookContext additions:
  - ctx.isIdle() - check if agent is streaming
  - ctx.waitForIdle() - wait for agent to finish
  - ctx.abort() - abort current operation
  - ctx.hasQueuedMessages() - check for queued user messages
  
  These enable hooks to programmatically manage sessions (handoff, templates)
  and check agent state before showing interactive UI.
  
  Fixes #388

  Mario Zechner · 2026-01-01 23:56:24 +01:00
  ccdd7bd283
• Consolidate session events: remove session_before_new/session_new, add reason field to switch events

  - Remove session_before_new and session_new hook events
  - Add reason: 'new' | 'resume' to session_before_switch and session_switch events
  - Remove 'new' reason from custom tool onSession (use 'switch' for both /new and /resume)
  - Rename reset() to newSession(options?) in AgentSession
  - Add NewSessionOptions with optional parentSession for lineage tracking
  - Rename branchedFrom to parentSession in SessionHeader
  - Rename RPC reset command to new_session with optional parentSession
  - Update example hooks to use new event structure
  - Update documentation and changelog
  
  Based on discussion in #293

  Mario Zechner · 2026-01-01 23:31:26 +01:00
  484d7e06bb
• Add theme-configurable HTML export colors (from PR #387)

  - Add optional 'export' section to theme JSON with pageBg, cardBg, infoBg
  - If not specified, colors are auto-derived from userMessageBg
  - Add export colors to dark.json and light.json
  - Update theme-schema.json and TypeBox schema
  - Add documentation to docs/theme.md
  - Add margin-top back to tool-output for spacing between header and content

  Mario Zechner · 2026-01-01 22:21:40 +01:00
  6267720660
• Add ctx.ui.theme getter for styling status text with theme colors

  - Add theme property to HookUIContext interface
  - Implement in interactive, RPC, and no-op contexts
  - Add status-line.ts example hook
  - Document styling with theme colors in hooks.md

  Mario Zechner · 2026-01-01 21:58:01 +01:00
  dccdf91b8c
• Hooks can render custom status (#385)

  * Add ctx.ui.setStatus(key, text) API for hooks to display status in footer
  
  - Add setStatus to HookUIContext interface
  - Implement in interactive mode (FooterComponent)
  - Implement in RPC mode (fire-and-forget)
  - Add no-op implementations for headless contexts
  - Multiple statuses displayed on single line, sorted by key
  - Supports ANSI styling (hooks handle their own colors)
  
  * Remove setStatus from changelog for now
  
  * Fix hook status API to follow TUI rules
  
  - Sanitize status text: replace newlines, tabs, carriage returns with spaces
  - Truncate combined status line to terminal width using truncateToWidth
  - Update JSDoc to document sanitization and truncation behavior
  - Remove unused createHookUIContext method
  - Add missing setStatus to test mock
  
  * Add setStatus to changelog
  
  * Use dim ellipsis for hook status truncation for consistency with footer style
  
  ---------
  
  Co-authored-by: Mario Zechner <badlogicgames@gmail.com>

  Prateek Sunal · 2026-01-01 21:35:37 +01:00
  9b2aa4a683
• Add thinkingText theme token, fix streaming toggle bug

  - Add configurable thinkingText color for thinking blocks (defaults to muted)
  - Make 'Thinking...' label italic when collapsed
  - Fix Ctrl+T during streaming hiding the current message
  - Track streamingMessage to properly re-render on toggle
  
  Based on #366 by @paulbettner

  Mario Zechner · 2026-01-01 00:25:04 +01:00
  506e63a969