36 Commits

• fix(hooks): deep copy messages in context event before passing to hooks

  The context event handler documentation promised a deep copy but the
  implementation passed the original array reference. This could cause
  hooks to accidentally mutate session messages.
  
  Uses structuredClone() for fast native deep copying.

  Mario Zechner · 2026-01-04 18:13:30 +01:00
  ddf8bfceee
• 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
• fix: remove inline imports and debug logging

  - Convert all inline import() types to top-level imports
  - Remove debug console.error statements from plan-mode hook

  Helmut Januschka · 2026-01-04 18:13:29 +01:00
  277d7bd83b
• 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
• 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 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
• feat(coding-agent): update AgentSession for steer()/followUp() API

  - Rename queueMessage to steer(), add followUp()
  - Split _pendingMessages into _steeringMessages and _followUpMessages
  - Update sendHookMessage to accept deliverAs option
  - Rename hasQueuedMessages to hasPendingMessages
  - Rename queuedMessageCount to pendingMessageCount
  - Update clearQueue() return type to { steering, followUp }
  - Update UI to show steering vs follow-up messages differently
  
  WIP: settings-manager, sdk, interactive-mode, rpc-mode still need updates

  Mario Zechner · 2026-01-03 00:13:25 +01:00
  58c423ba36
• 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
• 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 setEditorText/getEditorText to hook UI context, improve custom() API

  - Add setEditorText() and getEditorText() to HookUIContext for prompt generator pattern
  - custom() now accepts async factories for fire-and-forget work
  - Add CancellableLoader component to tui package
  - Add BorderedLoader component for hooks with cancel UI
  - Export HookAPI, HookContext, HookFactory from main package
  - Update all examples to import from packages instead of relative paths
  - Update hooks.md and custom-tools.md documentation
  
  fixes #350

  Mario Zechner · 2026-01-01 00:04:56 +01:00
  6f7c10e323
• Remove hook execution timeouts

  - Remove timeout logic from HookRunner
  - Remove hookTimeout from Settings interface
  - Remove getHookTimeout/setHookTimeout methods
  - Update CHANGELOG.md and hooks.md
  
  Timeouts were inconsistently applied and caused issues with
  legitimate slow operations (LLM calls, user prompts). Users can
  use Ctrl+C to abort hung hooks.

  Mario Zechner · 2025-12-31 12:57:54 +01:00
  88e39471ea
• Rework custom tools API with CustomToolContext

  - CustomAgentTool renamed to CustomTool
  - ToolAPI renamed to CustomToolAPI
  - ToolContext renamed to CustomToolContext
  - ToolSessionEvent renamed to CustomToolSessionEvent
  - Added CustomToolContext parameter to execute() and onSession()
  - CustomToolFactory now returns CustomTool<any, any> for type compatibility
  - dispose() replaced with onSession({ reason: 'shutdown' })
  - Added wrapCustomTool() to convert CustomTool to AgentTool
  - Session exposes setToolUIContext() instead of leaking internals
  - Fix ToolExecutionComponent to sync with toolOutputExpanded state
  - Update all custom tool examples for new API

  Mario Zechner · 2025-12-31 12:05:24 +01:00
  568150f18b
• refactor(coding-agent): fix compaction for branched sessions, consolidate hook context types

  Compaction API:
  - prepareCompaction() now takes (pathEntries, settings) only
  - CompactionPreparation restructured: removed cutPoint/messagesToKeep/boundaryStart, added turnPrefixMessages/isSplitTurn/previousSummary/fileOps/settings
  - compact() now takes (preparation, model, apiKey, customInstructions?, signal?)
  - Fixed token overflow by using getPath() instead of getEntries()
  
  Hook types:
  - HookEventContext renamed to HookContext
  - HookCommandContext removed, RegisteredCommand.handler takes (args, ctx)
  - HookContext now includes model field
  - SessionBeforeCompactEvent: removed previousCompactions/model, added branchEntries
  - SessionBeforeTreeEvent: removed model (use ctx.model)
  - HookRunner.initialize() added for modes to set up callbacks

  Mario Zechner · 2025-12-31 02:24:24 +01:00
  ddda8b124c
• feat(coding-agent): implement /tree command for session tree navigation

  - Add TreeSelectorComponent with ASCII tree visualization
  - Add AgentSession.navigateTree() for switching branches
  - Add session_before_tree/session_tree hook events
  - Add SessionManager.resetLeaf() for navigating to root
  - Change leafId from string to string|null for consistency with parentId
  - Support optional branch summarization when switching
  - Update buildSessionContext() to handle null leafId
  - Add /tree to slash commands in interactive mode

  Mario Zechner · 2025-12-30 22:42:22 +01:00
  4958271dd3
• refactor(hooks): split session events into individual typed events

  Major changes:
  - Replace monolithic SessionEvent with reason discriminator with individual
    event types: session_start, session_before_switch, session_switch,
    session_before_new, session_new, session_before_branch, session_branch,
    session_before_compact, session_compact, session_shutdown
  - Each event has dedicated result type (SessionBeforeSwitchResult, etc.)
  - HookHandler type now allows bare return statements (void in return type)
  - HookAPI.on() has proper overloads for each event with correct typing
  
  Additional fixes:
  - AgentSession now always subscribes to agent in constructor (was only
    subscribing when external subscribe() called, breaking internal handlers)
  - Standardize on undefined over null throughout codebase
  - HookUIContext methods return undefined instead of null
  - SessionManager methods return undefined instead of null
  - Simplify hook exports to 'export type * from types.js'
  - Add detailed JSDoc for skipConversationRestore vs cancel
  - Fix createBranchedSession to rebuild index in persist mode
  - newSession() now returns the session file path
  
  Updated all example hooks, tests, and emission sites to use new event types.

  Mario Zechner · 2025-12-30 22:42:22 +01:00
  d6283f99dc
• Implement before_agent_start hook event

  - Add BeforeAgentStartEvent and BeforeAgentStartEventResult types
  - Add emitBeforeAgentStart to HookRunner
  - Call in AgentSession.prompt() before agent.prompt()
  - Hook can return a message to inject into context (persisted + visible)
  - Add test hook demonstrating custom message rendering and before_agent_start

  Mario Zechner · 2025-12-30 22:42:22 +01:00
  57146de202
• WIP: Major cleanup - move Attachment to consumers, simplify agent API

  - Removed Attachment from agent package (now in web-ui/coding-agent)
  - Agent.prompt now takes (text, images?: ImageContent[])
  - Removed transports from web-ui (duplicate of agent package)
  - Updated coding-agent to use local message types
  - Updated mom package for new agent API
  
  Remaining: Fix AgentInterface.ts to compose UserMessageWithAttachments

  Mario Zechner · 2025-12-30 22:42:20 +01:00
  6ddc7418da
• Wire context event to preprocessor for per-LLM-call execution

  - Change from contextTransform (runs once at agent start) to preprocessor
  - preprocessor runs before EACH LLM call inside the agent loop
  - ContextEvent now uses Message[] (pi-ai format) instead of AppMessage[]
  - Deep copy handled by pi-ai preprocessor, not Agent
  
  This enables:
  - Pruning rules applied on every turn (not just agent start)
  - /prune during long agent loop takes effect immediately
  - Compaction can use same transforms (future work)

  Mario Zechner · 2025-12-30 22:42:20 +01:00
  a2515cf43f
• Add context event for non-destructive message modification before LLM calls

  - Add contextTransform option to Agent (runs before messageTransformer)
  - Deep copy messages before passing to contextTransform (modifications are ephemeral)
  - Add ContextEvent and ContextEventResult types
  - Add emitContext() to HookRunner (chains multiple handlers)
  - Wire up in sdk.ts when creating Agent with hooks
  
  Enables dynamic context pruning: hooks can modify messages sent to LLM
  without changing session data. See discussion #330.

  Mario Zechner · 2025-12-30 22:42:20 +01:00
  77fe3f1a13
• Add ui.custom() for custom hook components with keyboard focus

  - Add custom() to HookUIContext: returns { close, requestRender }
  - Component receives keyboard input via handleInput()
  - CustomMessageComponent default rendering now limits to 5 lines when collapsed
  - Add snake.ts example hook with /snake command

  Mario Zechner · 2025-12-30 22:42:19 +01:00
  14ad8d6228
• Refactor: shared exec utility, rename CustomMessageRenderer to HookMessageRenderer

  - Extract execCommand to src/core/exec.ts, shared by hooks and custom-tools
  - Rename CustomMessageRenderer -> HookMessageRenderer
  - Rename registerCustomMessageRenderer -> registerMessageRenderer
  - Renderer now receives HookMessage instead of CustomMessageEntry
  - CustomMessageComponent now has setExpanded() and responds to Ctrl+E toggle
  - Re-export ExecOptions/ExecResult from exec.ts for backward compatibility

  Mario Zechner · 2025-12-30 22:42:19 +01:00
  a8866d7a83
• Move exec to HookAPI, sessionManager/modelRegistry to HookEventContext

  Breaking changes:
  - HookEventContext now has sessionManager and modelRegistry (moved from SessionEventBase)
  - HookAPI now has exec() method (moved from HookEventContext/HookCommandContext)
  - HookRunner constructor takes sessionManager and modelRegistry as required params
  - Session events no longer include sessionManager/modelRegistry fields
  
  Hook code migration:
  - event.sessionManager -> ctx.sessionManager
  - event.modelRegistry -> ctx.modelRegistry
  - ctx.exec() -> pi.exec()
  
  Updated:
  - src/core/hooks/types.ts - type changes
  - src/core/hooks/runner.ts - constructor, createContext
  - src/core/hooks/loader.ts - add exec to HookAPI
  - src/core/sdk.ts - pass sessionManager/modelRegistry to HookRunner
  - src/core/agent-session.ts - remove sessionManager/modelRegistry from events
  - src/modes/* - remove setSessionFile calls, update events
  - examples/hooks/* - update to new API

  Mario Zechner · 2025-12-30 22:42:19 +01:00
  29fec7848e
• Move hook command execution to AgentSession.prompt()

  Hook commands registered via pi.registerCommand() are now handled in
  AgentSession.prompt() alongside file-based slash commands. This:
  
  - Removes duplicate tryHandleHookCommand from interactive-mode and rpc-mode
  - All modes (interactive, RPC, print) share the same command handling logic
  - AgentSession._tryExecuteHookCommand() builds CommandContext using:
    - UI context from hookRunner (set by mode)
    - sessionManager, modelRegistry from AgentSession
    - sendMessage via sendHookMessage
    - exec via exported execCommand
  - Handler returning string uses it as prompt, undefined returns early
  
  Also:
  - Export execCommand from hooks/runner.ts
  - Add getUIContext() and getHasUI() to HookRunner
  - Make HookRunner.emitError() public for error reporting

  Mario Zechner · 2025-12-30 22:42:18 +01:00
  c8d9382aaa
• Hook API: replace send() with sendMessage(), add appendEntry() and registerCommand()

  Breaking changes to Hook API:
  - pi.send(text, attachments?) replaced with pi.sendMessage(message, triggerTurn?)
    - Creates CustomMessageEntry instead of user messages
    - Properly handles queuing during streaming via agent loop
    - Supports optional turn triggering when idle
  - New pi.appendEntry(customType, data?) for hook state persistence
  - New pi.registerCommand(name, options) for custom slash commands
  - Handler types renamed: SendHandler -> SendMessageHandler, new AppendEntryHandler
  
  Implementation:
  - AgentSession.sendHookMessage() handles all three cases:
    - Streaming: queues message with _hookData marker, agent loop processes it
    - Not streaming + triggerTurn: appends to state/session, calls agent.continue()
    - Not streaming + no trigger: appends to state/session only
  - message_end handler routes based on _hookData presence to correct persistence
  - HookRunner gains getRegisteredCommands() and getCommand() methods
  
  New types: HookMessage<T>, RegisteredCommand, CommandContext

  Mario Zechner · 2025-12-30 22:42:18 +01:00
  ba185b0571
• Add CustomMessageEntry rendering infrastructure

  - Add renderCustomMessage to HookAPI for registering custom renderers
  - Add CustomMessageRenderer type and CustomMessageRenderOptions
  - Store customMessageRenderers in LoadedHook
  - Add getCustomMessageRenderer(customType) to HookRunner
  - SessionContext.entries now aligned with messages (same length, corresponding indices)
  
  TUI can now correlate messages with their source entries to identify
  custom_message entries and use hook-provided renderers.

  Mario Zechner · 2025-12-30 22:42:18 +01:00
  11a7845ceb
• Improve compaction hooks: add signal, no timeout, SessionManager cleanup, docs
  Mario Zechner · 2025-12-24 13:54:05 +01:00
  705ba5d4f2
• Add before/after session events with cancellation support

  - Merge branch event into session with before_branch/branch reasons
  - Add before_switch, before_clear, shutdown reasons
  - before_* events can be cancelled with { cancel: true }
  - Update RPC commands to return cancelled status
  - Add shutdown event on process exit
  - New example hooks: confirm-destructive, dirty-repo-guard, auto-commit-on-exit
  
  fixes #278

  Mario Zechner · 2025-12-22 18:18:38 +01:00
  42d7d9d9b6
• Refactor subagent tool, fix custom tool discovery, fix JSON mode stdout flush

  Breaking changes:
  - Custom tools now require index.ts entry point in subdirectory
    (e.g., tools/mytool/index.ts instead of tools/mytool.ts)
  
  Subagent tool improvements:
  - Refactored to use Message[] from ai package instead of custom types
  - Extracted agent discovery to separate agents.ts module
  - Added parallel mode streaming (shows progress from all tasks)
  - Added turn count to usage stats footer
  - Removed redundant Query section from scout output
  
  Fixes:
  - JSON mode stdout flush: Fixed race condition where pi --mode json
    could exit before all output was written, causing consumers to
    miss final events
  
  Also:
  - Added signal/timeout support to pi.exec() for custom tools and hooks
  - Renamed pi-pods bin to avoid conflict with pi

  Mario Zechner · 2025-12-19 04:54:02 +01:00
  4fb3af93fb
• Add hooks system with pi.send() for external message injection

  - Hook discovery from ~/.pi/agent/hooks/, .pi/hooks/, --hook flag
  - Events: session_start, session_switch, agent_start/end, turn_start/end, tool_call, tool_result, branch
  - tool_call can block execution, tool_result can modify results
  - pi.send(text, attachments?) to inject messages from external sources
  - UI primitives: ctx.ui.select/confirm/input/notify
  - Context: ctx.exec(), ctx.cwd, ctx.sessionFile, ctx.hasUI
  - Docs shipped with npm package and binary builds
  - System prompt references docs folder

  Mario Zechner · 2025-12-10 00:50:30 +01:00
  7c553acd1e
• feat(coding-agent): implement hooks system

  - Add hooks infrastructure in core/hooks/ (loader, runner, types)
  - HookUIContext interface with mode-specific implementations
  - Interactive mode: TUI-based selector/input/confirm dialogs
  - RPC mode: JSON protocol for hook UI requests/responses
  - Print mode: no-op UI context (hooks run but can't prompt)
  - AgentSession.branch() now async, returns { selectedText, skipped }
  - Settings: hooks[] and hookTimeout configuration
  - Export hook types from package for hook authors
  
  Based on PR #147 proposal, adapted for new architecture.

  Mario Zechner · 2025-12-09 22:17:12 +01:00
  04d59f31ea