git:20260831.a99450d to git:20260912.2086f4d

# 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 `<issue>-<slug>.test.ts`.

- Code changes require root `bun 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`