agent/pi - pi - Penguin

feat(coding-agent): ResourceLoader, package management, and /reload command (#645 )

- Add ResourceLoader interface and DefaultResourceLoader implementation
- Add PackageManager for npm/git extension sources with install/remove/update
- Add session.reload() and session.bindExtensions() APIs
- Add /reload command in interactive mode
- Add CLI flags: --skill, --theme, --prompt-template, --no-themes, --no-prompt-templates
- Add pi install/remove/update commands for extension management
- Refactor settings.json to use arrays for skills, prompts, themes
- Remove legacy SkillsSettings source flags and filters
- Update SDK examples and documentation for ResourceLoader pattern
- Add theme registration and loadThemeFromPath for dynamic themes
- Add getShellEnv to include bin dir in PATH for bash commands

Mario Zechner · 2026-01-22 13:49:38 +01:00

b846a4bfcf

feat(coding-agent): Add widget placement option (#850 )

* Add widget placement for extension widgets

* Remove changelog entry for widget placement

* Keep no-op widget signature

* Move widget render before attach

Marc Krenn · 2026-01-19 15:54:24 +01:00

abb1775ff7

feat(coding-agent): add extension compaction helpers

Mario Zechner · 2026-01-17 11:40:39 +01:00

9d3f8117a4

feat(coding-agent): export VERSION and update custom-header example (#798 )

Co-authored-by: Jian Zhang <jzhang@yanhuangdata.com>

Jian Zhang · 2026-01-17 10:54:00 +01:00

fc538f6ca1

feat(coding-agent): export keyHint utilities for extensions (#802 )

Danila Poyarkov · 2026-01-17 10:51:03 +01:00

58eec55154

feat(coding-agent): export getShellConfig for extensions (#766 )

Danila Poyarkov · 2026-01-16 12:01:46 +01:00

c5cf74e032

feat(coding-agent): add input event for extension input interception (#761 )

* feat(coding-agent): add input event for extension input interception

Extensions can now intercept, transform, or handle user input before the
agent processes it. Three result types: continue (pass through), transform
(modify text/images), handled (respond without LLM). Handlers chain
transforms and short-circuit on handled. Source field identifies origin.

* fix: make source public, use if/else over ternary

* fix: remove response field, extension handles own UI

Nico Bailon · 2026-01-16 02:41:56 +01:00

3e5d91f287

Centralize frontmatter parsing + parse frontmatter with yaml library (#728 )

* Add frontmatter utility and tidy coding agent prompts

* Add frontmatter parsing utilities and tests

* Parse frontmatter with YAML parser

* Simplify frontmatter parsing utilities

* strip body in 1 place

* Improve frontmatter parsing error handling

* Normalize multiline skill and select-list descriptions

Richard Gill · 2026-01-16 00:31:53 +01:00

ce7e73b503

feat(coding-agent): export getAgentDir for extensions (#749 )

Danila Poyarkov · 2026-01-15 17:16:56 +01:00

eacd33602b

feat: export highlightCode and getLanguageFromPath for extensions (#703 )

Danila Poyarkov · 2026-01-14 00:08:16 +01:00

9137c0c947

fix: extension loading in Bun binary (#681 )

- Remove loader exports from index.ts to break circular dependency
- Static import of index.js in loader.ts for virtualModules
- Add @mariozechner/pi-agent-core to virtualModules
- Update @mariozechner/jiti to 2.6.5 (bundles babel for Bun binary)
- Update SDK docs to use correct extension terminology

Mario Zechner · 2026-01-13 21:19:41 +01:00

843f235251

Change getAllTools() to return ToolInfo[] instead of string[]

Breaking change: pi.getAllTools() now returns Array<{ name, description }>
instead of string[]. Extensions needing just names can use .map(t => t.name).

Removes redundant getToolInfo() method added in original PR.

Fixes #647

Mario Zechner · 2026-01-12 17:18:43 +01:00

1367a76ee8

feat(coding-agent): add session naming via /name command and extension API

- Add SessionInfoEntry type for session metadata
- Add /name <name> command to set session display name
- Add pi.setSessionName() and pi.getSessionName() extension API
- Session selector shows name (in warning color) instead of first message when set
- Session name included in fuzzy search
- /session command displays name when set

closes #650

Mario Zechner · 2026-01-12 16:56:39 +01:00

8f95a13e07

Rename /branch command to /fork

- RPC: branch -> fork, get_branch_messages -> get_fork_messages
- SDK: branch() -> fork(), getBranchMessages() -> getForkMessages()
- AgentSession: branch() -> fork(), getUserMessagesForBranching() -> getUserMessagesForForking()
- Extension events: session_before_branch -> session_before_fork, session_branch -> session_fork
- Settings: doubleEscapeAction 'branch' -> 'fork'

fixes #641

Mario Zechner · 2026-01-11 23:12:31 +01:00

df3f5f41c0

feat(coding-agent): add FooterDataProvider for git branch and extension statuses

Expose data that extensions cannot otherwise access: git branch and
extension statuses from setStatus(). Token stats, model info, etc.
remain computable via ctx.sessionManager and ctx.model.

Nico Bailon · 2026-01-09 07:39:30 -08:00

7b902612e9

feat(coding-agent): add user_bash event and theme API extensions

- user_bash event for intercepting ! and !! commands (#528)
- Extensions can return { operations } or { result } to redirect/replace
- executeBashWithOperations() for custom BashOperations execution
- session.recordBashResult() for extensions handling bash themselves
- Theme API: getAllThemes(), getTheme(), setTheme() on ctx.ui
- mac-system-theme.ts example: sync with macOS dark/light mode
- Updated ssh.ts to use user_bash event

Mario Zechner · 2026-01-08 21:50:56 +01:00

121823c74d

Allow extensions to modify system prompt in before_agent_start

- Add systemPrompt to BeforeAgentStartEvent so extensions can see current prompt
- Change systemPromptAppend to systemPrompt in BeforeAgentStartEventResult for full replacement
- Extensions can now chain modifications (each sees the result of previous)
- Update ssh.ts to replace local cwd with remote cwd in system prompt
- Update pirate.ts, claude-rules.ts, preset.ts to use new API

fixes #575

Mario Zechner · 2026-01-08 19:54:34 +01:00

17cb328ca1

feat(coding-agent): add pluggable operations for remote tool execution

Adds optional operations parameter to create*Tool functions enabling
delegation to remote systems (SSH, containers, etc.):

- ReadOperations: readFile, access, detectImageMimeType
- WriteOperations: writeFile, mkdir
- EditOperations: readFile, writeFile, access
- BashOperations: exec (with streaming, signal, timeout)

Add ssh.ts example demonstrating --ssh flag for remote execution.
Built-in renderers used automatically for overrides without custom renderers.

fixes #564

Mario Zechner · 2026-01-08 19:32:25 +01:00

9ed88646a8

feat(coding-agent): export run mode utilities with options interfaces

- Add PrintModeOptions interface, update runPrintMode signature
- Export InteractiveMode, InteractiveModeOptions, runPrintMode, PrintModeOptions, runRpcMode from main package
- Document run modes in docs/sdk.md with usage examples
- Update CHANGELOG

Mario Zechner · 2026-01-08 01:53:24 +01:00

e483521075

refactor(coding-agent): simplify extension runtime architecture

- Replace per-extension closures with shared ExtensionRuntime
- Split context actions: ExtensionContextActions (required) + ExtensionCommandContextActions (optional)
- Rename LoadedExtension to Extension, remove setter methods
- Change runner.initialize() from options object to positional params
- Derive hasUI from uiContext presence (no separate param)
- Add warning when extensions override built-in tools
- RPC and print modes now provide full command context actions

BREAKING CHANGE: Extension system types and initialization API changed.
See CHANGELOG.md for migration details.

Mario Zechner · 2026-01-07 23:50:18 +01:00

cb3ac0ba9e

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

Export all UI components for extensions

Mario Zechner · 2026-01-06 23:09:58 +01:00

c35a18b2b3

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

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

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): add tools.ts example hook for interactive tool enable/disable

- /tools command opens SettingsList-based selector for all loaded tools
- Space/Enter toggles individual tools between enabled/disabled
- Changes apply immediately on toggle (like /settings)
- Tool selection persisted to session via appendEntry()
- State restored from current branch on session_start, session_tree, session_branch
- Uses getBranch() to respect branch-specific tool configuration
- Export getSettingsListTheme and getSelectListTheme for hooks to use

Mario Zechner · 2026-01-04 18:13:30 +01:00

892acedb6b

Merge pull request #402 from mitsuhiko/image-resize

Added automatic image resizing

Mario Zechner · 2026-01-03 00:39:26 +01:00

e82af9da47

fix(coding-agent): export Theme and ThemeColor for hooks to use proper types

Mario Zechner · 2026-01-03 00:13:26 +01:00

8c227052d3

Added automatic image resizing

Armin Ronacher · 2026-01-02 12:01:56 +01:00

4a32af2532

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 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

Export serializeConversation and document in compaction.md

Shows how to convert messages to text for custom summarization.

Mario Zechner · 2025-12-31 13:21:55 +01:00

75269add96

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

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

Improve branch summarization with preparation and file ops extraction

- Add prepareBranchEntries() to extract messages and file operations
- Extract read/write/edit operations from tool calls
- Append static file operations section to summary
- Improve prompt for branch summarization
- Skip toolResult messages (context already in assistant message)
- Export new types: BranchPreparation, FileOperations

Mario Zechner · 2025-12-30 22:42:23 +01:00

5cbaf2be88

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

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

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

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

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

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

Session tree: simplify types, add branching API, comprehensive tests

Types:
- SessionEntryBase with type field, extended by all entry types
- CustomEntry for hooks (type: 'custom', customType, data)
- Remove XXXContent types and TreeNode (redundant)

API:
- Rename saveXXX to appendXXX with JSDoc explaining tree semantics
- Rename branchInPlace to branch() with better docs
- Add createBranchedSession(leafId) replacing index-based version
- Add getTree() returning SessionTreeNode[] for tree traversal
- Add appendCustomEntry(customType, data) for hooks

Tests:
- tree-traversal.test.ts: 28 tests covering append, getPath, getTree,
  branch, branchWithSummary, createBranchedSession
- save-entry.test.ts: custom entry integration

Docs:
- Class-level JSDoc explaining append-only tree model
- Method docs explaining leaf advancement and branching
- CHANGELOG.md entry for all changes

Mario Zechner · 2025-12-30 22:42:18 +01:00

6f94e24629

Refactor session manager: migration chain, validation, tests

- Add migrateV1ToV2/migrateToCurrentVersion for extensible migrations
- createSummaryMessage now takes timestamp from entry
- loadEntriesFromFile validates session header
- findMostRecentSession only returns valid session files (reads first 512 bytes)
- Remove ConversationEntry alias
- Fix mom context.ts TreeNode type

Tests:
- migration.test.ts: v1 migration, idempotency
- build-context.test.ts: 14 tests covering trivial, compaction, branches
- file-operations.test.ts: loadEntriesFromFile, findMostRecentSession

Mario Zechner · 2025-12-30 22:42:18 +01:00

beb70f126d

Fix SessionEntry type to exclude SessionHeader

- SessionEntry now only contains conversation entries (messages, compaction, etc.)
- SessionHeader is separate, not part of SessionEntry
- FileEntry = SessionHeader | SessionEntry (for file storage)
- getEntries() filters out header, returns SessionEntry[]
- Added getHeader() for accessing session metadata
- Updated compaction and tests to not expect header in entries
- Updated mom package to use FileEntry for internal storage

Mario Zechner · 2025-12-30 22:42:17 +01:00

9478a3c1f5

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

Refactor OAuth/API key handling: AuthStorage and ModelRegistry

- Add AuthStorage class for credential storage (auth.json)
- Add ModelRegistry class for model management with API key resolution
- Add discoverAuthStorage() and discoverModels() discovery functions
- Add migration from legacy oauth.json and settings.json apiKeys to auth.json
- Remove configureOAuthStorage, defaultGetApiKey, findModel, discoverAvailableModels
- Remove apiKeys from Settings type and SettingsManager methods
- Rename getOAuthPath to getAuthPath
- Update SDK, examples, docs, tests, and mom package

Fixes #296

Mario Zechner · 2025-12-25 03:48:36 +01:00

54018b6cc0

WIP: Rename model-config.ts to models-json.ts

- loadCustomModels now takes file path instead of agentDir

Mario Zechner · 2025-12-25 01:15:17 +01:00

1c31d91c83

Improve compaction hooks: add signal, no timeout, SessionManager cleanup, docs

Mario Zechner · 2025-12-24 13:54:05 +01:00

705ba5d4f2

74 Commits