757 Commits

• 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
• Add reference to #330 (Dynamic Context Pruning) in plan

  Documents why context event was added and notes the type
  inconsistency between ContextEvent (AgentMessage[]) and
  ContextEventResult (Message[])

  Mario Zechner · 2025-12-30 22:42:22 +01:00
  bbdc350394
• Add investigation item for context event vs before_agent_start

  Reference: #324
  
  Documents:
  - Current context event behavior (AgentMessage[], transient)
  - Proposed before_agent_start event (persistent, TUI visible)
  - Key differences table
  - Open design questions
  - Need to verify AgentMessage vs Message abstraction level

  Mario Zechner · 2025-12-30 22:42:22 +01:00
  ae614f93e3
• Mark Hook API Changes as complete in plan
  Mario Zechner · 2025-12-30 22:42:21 +01:00
  1721bb8398
• Add BranchSummaryMessageComponent, unify styling with hook messages

  - CompactionSummaryMessageComponent now extends Box, uses customMessageBg
  - New BranchSummaryMessageComponent for branch summaries
  - Both use same background color as HookMessageComponent for consistency
  - Added Spacer before compaction/branch components in chat

  Mario Zechner · 2025-12-30 22:42:21 +01:00
  4ff5f61ffc
• Use exhaustive switch on message.role throughout coding-agent

  - addMessageToChat: exhaustive switch for all AgentMessage roles
  - renderSessionContext: delegates to addMessageToChat, special handling for assistant tool calls and tool results
  - export-html formatMessage: exhaustive switch for all AgentMessage roles
  - Removed isHookMessage, isBashExecutionMessage type guards in favor of role checks
  - Fixed imports and removed unused getLatestCompactionEntry

  Mario Zechner · 2025-12-30 22:42:21 +01:00
  b921298af7
• Fix hook message duplication in TUI

  Two bugs:
  1. createCustomMessage was returning role: 'user' instead of preserving
     the hook message structure (role: 'hookMessage', customType, etc.)
  2. rebuildChatFromMessages wasn't clearing the container before rebuilding

  Mario Zechner · 2025-12-30 22:42:21 +01:00
  ecef601d19
• 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
• Fix import path in hook-message.ts
  Mario Zechner · 2025-12-30 22:42:20 +01:00
  1113c95931
• Fix messageTransformer to normalize HookMessage string content to array

  HookMessage.content can be string or array, but LLM Message.content
  must be an array. This was causing 'messages: at least one message
  is required' errors when hooks sent string content.

  Mario Zechner · 2025-12-30 22:42:20 +01:00
  574f1cba3d
• 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 context event TODO with dynamic context pruning example

  Reference: https://github.com/badlogic/pi-mono/discussions/330

  Mario Zechner · 2025-12-30 22:42:20 +01:00
  9e165d1d81
• Fix snake border alignment using visibleWidth for proper ANSI length calculation
  Mario Zechner · 2025-12-30 22:42:20 +01:00
  6977bc73ca
• Snake: add full border frame and pause/resume with session persistence

  - Full box border around title, game area, and instructions
  - ESC pauses and saves state to session via pi.appendEntry()
  - Resume shows 'PAUSED - press any key to continue'
  - Q quits and clears saved state
  - High score persists across games

  Mario Zechner · 2025-12-30 22:42:20 +01:00
  b47151a04f
• Fix snake velocity: render cells as 2 chars wide for square aspect

  Terminal cells are ~2:1 aspect ratio, so movement appeared faster
  vertically. Now each game cell is 2 characters wide.

  Mario Zechner · 2025-12-30 22:42:19 +01:00
  5ae33defd3
• Improve snake game visuals

  - Rounded box corners (╭╮╰╯)
  - Better characters: ● head, ○ body, ◆ food, · empty
  - Colored title with emoji
  - Dimmed borders and help text
  - Bold highlights for score and controls

  Mario Zechner · 2025-12-30 22:42:19 +01:00
  516c0ea8bc
• 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
• Fix snake.ts: use key helpers from pi-tui for ESC and arrow keys
  Mario Zechner · 2025-12-30 22:42:19 +01:00
  165fb58b39
• 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
• Fix tests for sessionManager/modelRegistry on context

  - compaction-hooks-example.test.ts: get sessionManager/modelRegistry from ctx
  - compaction-hooks.test.ts:
    - Pass sessionManager/modelRegistry to HookRunner constructor
    - Remove setSessionFile call
    - Update tests to use session.sessionManager instead of event.sessionManager

  Mario Zechner · 2025-12-30 22:42:19 +01:00
  5fee9005b7
• 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
• Fix CHANGELOG: CommandContext -> HookCommandContext
  Mario Zechner · 2025-12-30 22:42:19 +01:00
  7ed8e2e9fc
• Update plan: move exec to HookAPI, sessionManager/modelRegistry to contexts

  - exec() moves from HookEventContext/HookCommandContext to HookAPI
  - sessionManager/modelRegistry move from SessionEventBase to HookEventContext
  - HookCommandContext keeps sessionManager/modelRegistry (command handlers need them)
  - Both sendMessage and exec accessed via pi closure in command handlers

  Mario Zechner · 2025-12-30 22:42:19 +01:00
  e25aef0594
• Update plan: HookCommandContext without sendMessage (use pi closure)
  Mario Zechner · 2025-12-30 22:42:19 +01:00
  09e7e9196c
• Expand documentation and examples sections in session-tree plan
  Mario Zechner · 2025-12-30 22:42:19 +01:00
  60130a4c53
• Add documentation tasks to session-tree plan
  Mario Zechner · 2025-12-30 22:42:19 +01:00
  ccfa1ac3bb
• Document HookAppMessage and Agent.prompt(AppMessage) in CHANGELOG
  Mario Zechner · 2025-12-30 22:42:19 +01:00
  cf211b13e8
• Add Agent.prompt(AppMessage) overload for custom message types

  Instead of using continue() which validates roles, prompt() now accepts
  an AppMessage directly. This allows hook messages with role: 'hookMessage'
  to trigger proper agent loop with message events.
  
  - Add overloads: prompt(AppMessage) and prompt(string, attachments?)
  - sendHookMessage uses prompt(appMessage) instead of appendMessage+continue

  Mario Zechner · 2025-12-30 22:42:19 +01:00
  a6322fda59
• Handle hookMessage role in message_start event handler
  Mario Zechner · 2025-12-30 22:42:19 +01:00
  02f2c50155
• Use proper HookAppMessage type instead of _hookData marker

  Following the same pattern as BashExecutionMessage:
  - HookAppMessage has role: 'hookMessage' with customType, content, display, details
  - isHookAppMessage() type guard for checking message type
  - messageTransformer converts to user message for LLM context
  - TUI checks isHookAppMessage() for rendering as CustomMessageComponent
  
  This makes the API clean for anyone building on AgentSession - they can
  use the type guard instead of knowing about internal marker fields.

  Mario Zechner · 2025-12-30 22:42:19 +01:00
  75a9c3c714
• Add emitLastMessage flag to agent.continue()

  When calling continue() with emitLastMessage=true, the agent loop
  emits message_start/message_end events for the last message in context.
  This allows messages added outside the loop (e.g., hook messages via
  sendHookMessage) to trigger proper TUI rendering.
  
  Changes across packages:
  - packages/ai: agentLoopContinue() accepts emitLastMessage parameter
  - packages/agent: Agent.continue(), transports updated to pass flag
  - packages/coding-agent: sendHookMessage passes true when triggerTurn

  Mario Zechner · 2025-12-30 22:42:19 +01:00
  357bd946c2
• 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
• Update CHANGELOG with CustomMessageEntry and hook rendering API
  Mario Zechner · 2025-12-30 22:42:18 +01:00
  d43a5e47a1
• Wire up hook custom message renderers to TUI

  - CustomMessageComponent accepts optional CustomMessageRenderer
  - If hook provides a renderer, call it and use returned Component inside Box
  - Falls back to default rendering (label + Markdown) if no renderer or null returned
  - renderSessionContext gets renderer from hookRunner and passes to component

  Mario Zechner · 2025-12-30 22:42:18 +01:00
  ba11622d0c
• Add TUI rendering for CustomMessageEntry

  - Add CustomMessageComponent with purple-tinted styling
  - Add theme colors: customMessageBg, customMessageText, customMessageLabel
  - Rename renderMessages to renderSessionContext taking SessionContext directly
  - renderInitialMessages now gets context from sessionManager
  - Skip rendering for display: false entries

  Mario Zechner · 2025-12-30 22:42:18 +01:00
  7b94ddf36b
• Fix: compaction now handles branch_summary and custom_message entries

  - Add getMessageFromEntry helper to extract AppMessage from any context-producing entry
  - Update findValidCutPoints to treat branch_summary/custom_message as valid cut points
  - Update findTurnStartIndex to recognize branch_summary/custom_message as turn starters
  - Update all message extraction loops to use getMessageFromEntry

  Mario Zechner · 2025-12-30 22:42:18 +01:00
  beb804cda0
• Fix: handle branch_summary in kept messages before compaction
  Mario Zechner · 2025-12-30 22:42:18 +01:00
  754f55e3f6
• 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
• Fix CustomMessageEntry content type to match UserMessage

  content: string | (TextContent | ImageContent)[]
  
  This matches the UserMessage type from pi-ai, so content can be
  passed directly to AppMessage without conversion.

  Mario Zechner · 2025-12-30 22:42:18 +01:00
  3ecaaa5937
• Add CustomMessageEntry for hook-injected messages in LLM context

  - CustomMessageEntry<T> type with customType, content, display, details
  - appendCustomMessageEntry() in SessionManager
  - buildSessionContext() includes custom_message entries as user messages
  - Exported CustomEntry and CustomMessageEntry from main index
  
  CustomEntry is for hook state (not in context).
  CustomMessageEntry is for hook-injected content (in context).

  Mario Zechner · 2025-12-30 22:42:18 +01:00
  9da36e5ac6
• 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
• Make CompactionEntry and CompactionResult generic with details field

  - CompactionEntry<T> and CompactionResult<T> now have optional details?: T
  - appendCompaction() accepts optional details parameter
  - Hooks can return compaction.details to store custom data
  - Enables structured compaction with ArtifactIndex (see #314)
  - Fix CompactionResult export location (now from compaction.ts)
  - Update plan with remaining compaction refactor items

  Mario Zechner · 2025-12-30 22:42:18 +01:00
  d96375b5e5
• Improve CustomEntry docs and make it generic

  - Add detailed doc comment explaining purpose (hook state persistence)
  - Make CustomEntry<T = unknown> generic
  - Clarify difference from CustomMessageEntry in plan
  - Update changelog

  Mario Zechner · 2025-12-30 22:42:18 +01:00
  efb1036d8e
• 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