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
This commit is contained in:
Mario Zechner 2025-12-27 00:52:10 +01:00
parent d43a5e47a1
commit ba185b0571
13 changed files with 412 additions and 77 deletions

View file

@ -122,10 +122,67 @@ Behavior:
- [x] `appendCustomMessageEntry(customType, content, display, details?)` in SessionManager
- [x] `buildSessionContext()` includes custom_message entries as user messages
- [x] Exported from main index
- [ ] TUI rendering:
- [x] TUI rendering:
- `display: false` - hidden entirely
- `display: true` - baseline renderer (content with different bg/fg color)
- Custom renderer defined by the hook that contributes it (future)
- `display: true` - rendered with purple styling (customMessageBg, customMessageText, customMessageLabel theme colors)
- [x] `registerCustomMessageRenderer(customType, renderer)` in HookAPI for custom renderers
- [x] Renderer returns inner Component, TUI wraps in styled Box
### Hook API Changes
**Renamed:**
- `renderCustomMessage()``registerCustomMessageRenderer()`
**New: `sendMessage()`**
Replaces `send()`. Always creates CustomMessageEntry, never user messages.
```typescript
type HookMessage<T = unknown> = Pick<CustomMessageEntry<T>, 'customType' | 'content' | 'display' | 'details'>;
sendMessage(message: HookMessage, triggerTurn?: boolean): void;
```
Behavior:
- If streaming → queue, append after turn ends (never triggers turn)
- If idle AND `triggerTurn: true` → append and trigger turn
- If idle AND `triggerTurn: false` (default) → just append, no turn
- TUI updates if `display: true`
For hook state (CustomEntry), use `sessionManager.appendCustomEntry()` directly.
**New: `registerCommand()`**
```typescript
interface CommandContext {
args: string; // Everything after /commandname
session: LimitedAgentSession; // No prompt(), use sendMessage()
ui: HookUIContext;
exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
}
registerCommand(name: string, options: {
description?: string;
handler: (ctx: CommandContext) => Promise<string | void>;
}): void;
```
Handler return:
- `void` - command completed
- `string` - text to send as prompt (like file-based slash commands)
**New: `ui.custom()`**
For arbitrary hook UI with keyboard focus:
```typescript
interface HookUIContext {
// ... existing: select, confirm, input, notify
/** Show custom component with keyboard focus. Call done() when finished. */
custom(component: Component, done: () => void): void;
}
```
See also: `CustomEntry<T>` for storing hook state that does NOT participate in context.