# packages/coding-agent `@code-yeongyu/senpi` is the user-facing CLI and the highest-conflict upstream fork surface. Use the extension API before editing `src/core/`. ## STRUCTURE ```text src/cli.ts, cli-main.ts, main.ts Bootstrap, args, mode dispatch src/bun-runtime.ts Bun-vs-Node runtime selection for bun-installed CLI (`SENPI_RUNTIME` pin) src/bun/cli.ts, src/bun/register-cursor-agent.ts Bun-binary entry; static cursor-agent module install src/package-manager-cli.ts install/update/config subcommands (incl. `senpi update --models`) src/core/agent-session.ts Session lifecycle and runtime src/core/cursor-exec-bridge.ts Maps Cursor exec frames to session tools (cursorExecHandlers wiring) src/core/cursor-exec-bridge-session.ts Per-session Cursor exec bridge state src/core/agent-abort-provenance.ts Abort ownership across retries and event dispatch src/core/agent-settled-delivery.ts Cancellable extension messages after settlement src/core/dynamic-prompt/ Dynamic system-prompt assembly + workstation facts src/core/model-runtime.ts Model runtime bootstrap src/core/model-config.ts Per-model config resolution src/core/models-store.ts Persisted model store src/core/provider-composer.ts Provider payload composition src/core/remote-catalog-provider.ts Remote model-catalog fetch src/core/runtime-credentials.ts Credential resolution and refresh src/core/auth-providers.ts Provider auth registration src/core/provider-timeout-retry.ts Provider timeout/retry policy src/core/retry-fallback/ Model fallback chains + billing classification src/core/project-trust.ts, trust-manager.ts Project trust decisions src/core/resource-loader.ts Bundled extension/resource resolution src/core/session-resident-store.ts Session-resident state store src/core/session-discovery.ts, session-record.ts, session-summary*.ts Session listing, record shape, summary cache/LRU src/core/extensions/ Public extension API and loader src/core/extensions/builtin/ In-tree fork extensions; bundled extensions (e.g. codemode) resolved via resource-loader.ts src/core/tools/ Upstream-parity built-in tools src/core/compaction/ Core compaction mechanics src/modes/interactive/ TUI mode and components src/modes/app-server/ App-server transport and RPC registry; runtime.ts wiring, search/ fuzzy file search src/modes/rpc/ JSONL RPC mode/client/types, shared Unix-socket multi-session host, ensureHost handshake, lifecycle supervisor/watchdog, and the ordered command surface (get_commands / commands_changed) src/modes/print-mode.ts One-shot mode test/suite/harness.ts Preferred faux-provider harness test/ Test domains, fixtures, QA, integration gates examples/ Extension and SDK examples src/changes.md Root fork-change record ``` ## WHERE TO LOOK | Task | First choice | |---|---| | Add tool, command, flag, or hook | `src/core/extensions/builtin/` | | Change extension contract | `src/core/extensions/types.ts` and `src/core/extensions/changes.md` | | Change session lifecycle | `src/core/agent-session.ts` | | Change model/provider/catalog/auth runtime | `src/core/model-runtime.ts` + related `model-*/provider-*` modules | | Change keybinding | `src/core/keybindings.ts` | | Change interactive UI | `src/modes/interactive/` | | Change RPC/app-server | matching directory under `src/modes/` | | Add regression | `test/suite/regressions/` | | Add or update an example | `examples/` and the matching public docs | ## CONVENTIONS - Extension discovery includes builtin, project, user, settings, and CLI paths; preserve load, bind, event, reload, and shutdown ordering. - Use `pi.registerTool()`, `pi.registerCommand()`, and `pi.registerFlag()` before adding core surfaces. - Keybindings are configurable through `KEYBINDINGS`; never match hardcoded key literals. - Public extension API changes require the nearest `changes.md` entry. Read `docs/extensions.md` before claiming a hook is missing. - Keep branding consistent: package `@code-yeongyu/senpi`, binary `senpi`, config directory `.senpi`. - Preserve the inlined UUIDv7 implementation; do not add a `uuid` dependency. - Do not run real providers in tests. Use `test/suite/harness.ts` and the faux provider. - RPC-mode JSONL is bounded and strict: LF-only framing, `MAX_RPC_LINE_CHARACTERS` 16 MiB line ceiling with oversized-record resynchronization, and `MAX_RPC_MESSAGE_CHARACTERS` 1,000,000-character message limit (`src/modes/rpc/jsonl.ts`, `src/modes/rpc/rpc-input-validation.ts`); preserve those bounds. App-server outbound stdio waits for stdout backpressure (`transports/stdio.ts`) and WebSocket closes slow clients at queue cap (`transports/websocket-connection-handler.ts`); app-server inbound NDJSON readers are not size-bounded — preserve those contracts. - The RPC command surface (`get_commands`, post-baseline `commands_changed`, `command_invocation`/`skill_invocation` metadata) is owned by `src/modes/rpc/`; the suppressed initial `commands_changed` (baseline digest starts `undefined`) is intentional — see `src/modes/rpc/AGENTS.md`. - MCP token/log storage preserves restricted directory/file permissions; do not widen inherited child environments. RPC child stderr is currently emitted and embedded raw, so treat diagnostics as potentially secret-bearing and do not claim redaction without implementing it. ## ANTI-PATTERNS - Implementing extension-capable features in core. - Editing `src/core/slash-commands.ts` for fork-only commands. - Hardcoding keys, spending tokens in tests, or using real API credentials. - Running release-only `prepublishOnly` as a repair command. - Editing generated distribution output. ## VALIDATION - Run changed test files from this package; issue regressions use `-.test.ts`. - Code changes require root `npm run check` plus the applicable `senpi-qa` CLI channel and saved evidence. - Interactive changes also follow `src/modes/interactive/AGENTS.md`; extension/tool changes follow their nearest child guide. - App-server, test, and example changes follow their local `AGENTS.md` files. - Keep `src/changes.md`, nested `changes.md`, public docs, and examples aligned with fork behavior. --- Generated: 2026-08-22 | Commit: `a5eed4453`