66 Commits

• fix: export type guard functions at runtime, fixes #397
  Mario Zechner · 2026-01-02 10:37:28 +01:00
  c10d99d2de
• 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
• Remove unnecessary comments from types
  Mario Zechner · 2026-01-02 00:39:54 +01:00
  5c37fe27c6
• Add Clawd summary comments to hook and custom tool types
  Mario Zechner · 2026-01-02 00:32:38 +01:00
  a433e524a0
• 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 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
• Fix hook tool_result event not emitted for tool errors

  Tools are supposed to throw on error. What needs fixing is that we need to report tool_result for erroneous tool executions as well.
  
  Fixes #374

  Mario Zechner · 2025-12-31 17:12:55 +01:00
  02d0d6e192
• Change branch() to use entryId instead of entryIndex

  - AgentSession.branch(entryId: string) now takes entry ID
  - SessionBeforeBranchEvent.entryId replaces entryIndex
  - getUserMessagesForBranching() returns entryId
  - Update RPC types and client
  - Update UserMessageSelectorComponent
  - Update hook examples and tests
  - Update docs (hooks.md, sdk.md)

  Mario Zechner · 2025-12-31 13:47:34 +01:00
  8e1e99ca05
• 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
• Add ReadonlySessionManager and refactor branch summarization

  - Add ReadonlySessionManager interface to session-manager.ts
  - Re-export from hooks/index.ts
  - Add collectEntriesForBranchSummary() to extract entries for summarization
  - Don't stop at compaction boundaries (include their summaries as context)
  - Add token budget support to prepareBranchEntries()
  - Walk entries newest-to-oldest to prioritize recent context
  - Use options object for generateBranchSummary()
  - Handle compaction entries as context summaries
  - Export new types: CollectEntriesResult, GenerateBranchSummaryOptions

  Mario Zechner · 2025-12-30 22:42:23 +01:00
  08fab16e2d
• Refactor: move compaction code to src/core/compaction/

  - Move compaction.ts to src/core/compaction/compaction.ts
  - Extract branch summarization to src/core/compaction/branch-summarization.ts
  - Add index.ts to re-export all compaction utilities
  - Update all imports across the codebase

  Mario Zechner · 2025-12-30 22:42:23 +01:00
  fd13b53b1c
• Fix branch summarization abort handling and tree navigation

  - Check response.stopReason instead of catching errors for abort detection
  - Return result object from _generateBranchSummary instead of throwing
  - Fix summary attachment: attach to navigation target position, not old branch
  - Support root-level summaries (parentId=null) in branchWithSummary
  - Remove setTimeout hack for re-showing tree selector on abort

  Mario Zechner · 2025-12-30 22:42:23 +01:00
  01dae9ebcc
• 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
• Add ReadonlySessionManager type for hooks

  Hooks now receive ReadonlySessionManager in contexts, which only
  exposes read methods. Writes must go through pi.sendMessage() or
  pi.appendEntry().

  Mario Zechner · 2025-12-30 22:42:22 +01:00
  38d65dfe59
• Remove allowDuringStreaming flag - commands always run immediately

  Hook commands now always execute immediately, even during streaming.
  If a command needs to interact with the LLM, it uses pi.sendMessage()
  which handles queueing automatically.
  
  This simplifies the API and eliminates the issue of queued slash
  commands being sent to the LLM instead of executing.

  Mario Zechner · 2025-12-30 22:42:22 +01:00
  575c875475
• Rename immediate -> allowDuringStreaming for hook commands
  Mario Zechner · 2025-12-30 22:42:22 +01:00
  f8352bb7d7
• 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
• WIP: Refactor agent package - not compiling

  - Renamed AppMessage to AgentMessage throughout
  - New agent-loop.ts with AgentLoopContext, AgentLoopConfig
  - Removed transport abstraction, Agent now takes streamFn directly
  - Extracted streamProxy to proxy.ts utility
  - Removed agent-loop from pi-ai (now in agent package)
  - Updated consumers (coding-agent, mom) for AgentMessage rename
  - Tests updated but some consumers still need migration
  
  Known issues:
  - AgentTool, AgentToolResult not exported from pi-ai
  - Attachment not exported from pi-agent-core
  - ProviderTransport removed but still referenced
  - messageTransformer -> convertToLlm migration incomplete
  - CustomMessages declaration merging not working properly

  Mario Zechner · 2025-12-30 22:42:20 +01:00
  a055fd4481
• Cleanup: unify HookMessage naming and simplify SessionContext

  - Rename HookAppMessage to HookMessage, isHookAppMessage to isHookMessage
  - Remove entries array from SessionContext (use isHookMessage type guard instead)
  - HookMessage.content now accepts string directly (not just array)
  - Fix streamMessage type in AgentState (AppMessage, not Message)
  - Rename CustomMessageComponent to HookMessageComponent
  - Fix test hook to use pi.sendMessage

  Mario Zechner · 2025-12-30 22:42:20 +01:00
  204d27581b
• 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 immediate flag to hook commands for non-queued execution

  Commands with immediate: true run right away even during streaming.
  Used for UI-only commands like /snake that don't interact with LLM.

  Mario Zechner · 2025-12-30 22:42:19 +01:00
  818196d2c3
• 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
• Update plan: HookCommandContext without sendMessage (use pi closure)
  Mario Zechner · 2025-12-30 22:42:19 +01:00
  09e7e9196c
• Hook commands: remove string return, use sendMessage() for prompting

  - Command handler now returns Promise<void> instead of Promise<string | undefined>
  - To trigger LLM response, use sendMessage() with triggerTurn: true
  - Simplify _tryExecuteHookCommand to return boolean
  
  Added example hook and slash command in .pi/:
  - .pi/hooks/test-command.ts - /greet command using sendMessage
  - .pi/commands/review.md - file-based /review command

  Mario Zechner · 2025-12-30 22:42:18 +01:00
  30cd723411
• 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
• Refactor SessionEventBase to pass sessionManager and modelRegistry

  Breaking changes to hook types:
  - SessionEventBase now passes sessionManager and modelRegistry directly
  - before_compact: passes preparation, previousCompactions (newest first)
  - before_switch: has targetSessionFile; switch: has previousSessionFile
  - Removed resolveApiKey (use modelRegistry.getApiKey())
  - getSessionFile() returns string | undefined for in-memory sessions
  
  Updated:
  - All session event emissions in agent-session.ts
  - Hook examples (custom-compaction.ts, auto-commit-on-exit.ts, confirm-destructive.ts)
  - Tests (compaction-hooks.test.ts, compaction-hooks-example.test.ts)
  - export-html.ts guards for in-memory sessions

  Mario Zechner · 2025-12-30 22:42:18 +01:00
  9bba388ec5
• Use CompactionResult type for hook compaction return value

  - Import CompactionResult in hooks/types.ts
  - Replace inline type with CompactionResult for SessionEventResult.compaction
  - Add labels feature to changelog

  Mario Zechner · 2025-12-30 22:42:18 +01:00
  e841942377
• Session tree structure with id/parentId linking

  - Add TreeNode base type with id, parentId, timestamp
  - Add *Content types for clean input/output separation
  - Entry types are now TreeNode & *Content intersections
  - SessionManager assigns id/parentId on save, tracks leafId
  - Add migrateSessionEntries() for v1 to v2 conversion
  - Migration runs on load, rewrites file
  - buildSessionContext() uses tree traversal from leaf
  - Compaction returns CompactionResult (content only)
  - Hooks return compaction content, not full entries
  - Add firstKeptEntryId to before_compact hook event
  - Update mom package for tree fields
  - Better error messages for compaction failures

  Mario Zechner · 2025-12-30 22:42:17 +01:00
  c58d5f20a4
• Fix jiti alias for typebox subpath imports in custom tools/hooks

  fixes #311

  Mario Zechner · 2025-12-25 18:07:42 +01:00
  66d19ac9c8
• Rename /clear to /new, update hook events to before_new/new

  Closes #305 - took direct rename approach instead of alias system
  
  Thanks @mitsuhiko for the nudge!

  Mario Zechner · 2025-12-25 04:15:10 +01:00
  454ea1d36a
• Improve compaction hooks: add signal, no timeout, SessionManager cleanup, docs
  Mario Zechner · 2025-12-24 13:54:05 +01:00
  705ba5d4f2
• Add previousSummary to before_compact hook event
  Mario Zechner · 2025-12-24 12:47:12 +01:00
  403faafdbe
• Improve before_compact hook: add messagesToKeep, replace apiKey with resolveApiKey
  Mario Zechner · 2025-12-24 12:41:22 +01:00
  d9a542763a
• Add resolveApiKey to before_compact hook event
  Mario Zechner · 2025-12-24 12:28:51 +01:00
  43a5447a80
• Add before_compact hook event (closes #281) (#285)

  * Add before_compact hook event (closes #281)
  
  * Add compact hook event and documentation
  
  - Add compact event that fires after compaction completes
  - Update hooks.md with lifecycle diagram, field docs, and example
  - Add CHANGELOG entry
  - Add comprehensive test coverage (10 tests) for before_compact and compact events
  - Tests cover: event emission, cancellation, custom entry, error handling, multiple hooks

  Nico Bailon · 2025-12-24 11:26:29 +01:00
  1e1a92ea47
• docs: fix outdated custom tools paths and add missing header shortcut (#283)

  * docs: fix custom tools example paths to use index.ts structure
  
  * fix: add missing ctrl+g shortcut to startup header
  
  * docs: fix /session -> /resume for session switching references

  Aliou Diallo · 2025-12-23 03:29:31 +01:00
  7470dde1e9