freddie AGENTS.md

Freddie — Agent Guide

Instructions for AI coding assistants working on Freddie. Present-tense rules only — history lives in git log and CHANGELOG.md.

Preferred mechanism for multi-step tool graphs is run_flow — use it spontaneously; it reduces turns. Direct tool calls remain legal for single steps.

Substrate (do not reimplement)

Status: freddie depends on @earendil-works/pi-tui only — @earendil-works/pi-ai was removed (73 transitive packages) since freddie's real LLM path always routed through acptoapi, never pi-ai; pi-ai's only freddie-side usage was the now-deleted src/agent/pi-bridge.js, whose callLLM export had zero internal consumers. @earendil-works/pi-coding-agent and @earendil-works/pi-agent-core are not installed — AgentSession, SessionManager, SettingsManager, DefaultResourceLoader, ModelRuntime, runPrintMode/runRpcMode are not in use anywhere in this codebase. The agent turn loop (src/agent/machine.js), session store (src/sessions.js), settings (src/config.js), skills loader (src/skills/index.js), and plugin/extension system (src/host/*) are freddie-original code, not thin wrappers over that package. The correct npm scope for that package is @earendil-works/pi-coding-agent (not @mariozechner/pi-coding-agent, a stale scope). Adoption tradeoffs and the compaction-module's SessionEntry[] shape requirement are evaluated in memory (recall "Freddie pi-coding-agent substrate adoption tradeoffs") — conclusion: no swap reduces freddie's maintenance surface, src/agent/compress/*'s own policy remains pragmatic.

• @earendil-works/pi-coding-agent (not yet a dependency) — agent + tools + interactive TUI, if adopted. Exports AgentSession/createAgentSession, SessionManager, SettingsManager, DefaultResourceLoader, ModelRuntime, defineTool, InteractiveMode, runPrintMode, runRpcMode, createEventBus.
• @earendil-works/pi-agent-core (not yet a dependency) — lower-level Agent/agentLoop/runAgentLoop/streamProxy, a dependency of pi-coding-agent itself.
• @earendil-works/pi-tui — TUI primitives (Ink-equivalent), actually installed. src/tui/index.js::launchTui() dynamically imports it and, on a real TTY, constructs src/tui/app.js::runTui() directly on top of pi-tui's own TuiMainScreen/ProcessTerminal/Editor/Container primitives (not InteractiveMode — that class lives in pi-coding-agent, which is not installed; freddie's TUI is a from-scratch shell built on pi-tui's lower-level building blocks). TUI is pi-tui's shared TypeScript interface only (no runtime constructor — typeof TUI === 'undefined' at runtime); the concrete, constructible renderer classes are TuiMainScreen (preserves terminal scrollback, differential re-render — what app.js uses, matching pi-tui's own README Quick Start example almost verbatim) and TuiAltScreen (application-owned fixed viewport in the alternate screen buffer, with setLayoutRoot/VStack/HStack/ScrollView, mouse-driven selection, in-app search — a heavier feature set app.js does not need). Falls back to src/cli/interactive.js's plain readline REPL on non-TTY stdio, a pi-tui import failure, a runTui() throw, or (Windows only) when process.env.TMUX is set — see the psmux/tmux constraint below. plugins/core/core-cli/plugin.js's run CLI command calls launchTui(), not interactive() directly — the rich TUI must stay reachable from the actual freddie run command, not just as a library export. pi-tui is a fully independent package (zero shared dependencies with pi-ai, confirmed directly against its own package.json) — its removal was never on the table alongside pi-ai's.
• pi-tui Windows tmux/psmux raw-mode incompatibility (enableWindowsVTInput/SetConsoleMode breaking keyboard input in a pty pane, launchTui()'s TMUX-env routing-around) — see rs-learn (recall "Freddie pi-tui Windows tmux psmux raw-mode defect").
• floosie — ProcessorMachine (xstate). Use for gateway pipelines. Compose, don't fork.
• anentrypoint-design — webjsx + ripple-ui. All GUI for freddie and thebird lives here. Source lives in its own repo (AnEntrypoint/design), vendored as a git submodule at ./design in this repo for easy editing; freddie's runtime code consumes it via the github:AnEntrypoint/design npm dep spec (default branch, no ref pin, no npm registry involved) — the submodule does not change any import path. For local SDK iteration, edit ./design, rebuild via node scripts/build.mjs inside it, then push to main (CI commits the rebuilt dist/) to flow the change to every consumer. Do NOT add React.
• acptoapi — THE LLM SDK (see "acptoapi is THE SDK" below). Source lives in its own repo (AnEntrypoint/acptoapi), vendored as a git submodule at ./acptoapi in this repo for easy editing; freddie's package.json pins it via github:AnEntrypoint/acptoapi (see Versioning below) — the submodule does not change that. Edit ./acptoapi, then push to main to flow the change downstream.
• xstate v5 — every long-lived state machine (agent turns, gateway lifecycle, approvals).