@code-yeongyu/senpi 2026.8.23 → 2026.8.25

package/docs/sdk.md

@@ -519,7 +519,7 @@ const { session } = await createAgentSession({ resourceLoader: loader });
 
 Specify which built-in tools to enable:
 
-- Built-in tool names: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`
+- Built-in tool names: `read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, `ls`
 - Default built-ins: `read`, `bash`, `edit`, `write`
 - `noTools: "all"` disables all tools
 - `noTools: "builtin"` disables default built-ins while keeping extension and custom tools enabled
@@ -540,6 +540,11 @@ const { session } = await createAgentSession({
   tools: ["read", "bash", "grep"],
 });
 
+// Use PowerShell instead of Bash on Windows
+const { session } = await createAgentSession({
+  tools: ["read", "powershell", "edit", "write"],
+});
+
 // Disable one tool while keeping the rest available
 const { session } = await createAgentSession({
   excludeTools: ["ask_question"],
@@ -1196,7 +1201,7 @@ SettingsManager
 // Tool factories
 createCodingTools
 createReadOnlyTools
-createReadTool, createBashTool, createEditTool, createWriteTool
+createReadTool, createBashTool, createPowerShellTool, createEditTool, createWriteTool
 createGrepTool, createFindTool, createLsTool
 
 // Types

package/docs/settings.md

@@ -400,7 +400,7 @@ Windows paths in JSON must use forward slashes or escaped backslashes:
 |---------|------|---------|-------------|
 | `defaultTools` | string[] | - | Built-in tools enabled initially. When omitted, Pi uses its standard defaults |
 
-`defaultTools` selects the built-in tools enabled at startup. Extension and SDK custom tools remain enabled:
+`defaultTools` selects the built-in tools enabled at startup. Extension and SDK custom tools remain enabled. Available built-ins are `read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, and `ls`:
 
 ```json
 {
@@ -408,6 +408,14 @@ Windows paths in JSON must use forward slashes or escaped backslashes:
 }
 ```
 
+On Windows, select `powershell` instead of `bash`, or include both:
+
+```json
+{
+  "defaultTools": ["read", "powershell", "edit", "write"]
+}
+```
+
 An empty array starts with no built-in tools while preserving extension and SDK custom tools. `--tools` replaces this behavior with a strict allowlist for all tools, `--no-tools` disables all tools, and `--no-builtin-tools` disables the built-in defaults. `--exclude-tools` filters the resulting list. A project `defaultTools` array replaces the global array.
 
 ### Sessions

package/docs/terminal-setup.md

@@ -120,7 +120,15 @@ Add to `keybindings.json`:
 
 ## Windows Terminal
 
-Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file) to forward the modified Enter keys pi uses:
+Pi uses Windows-style keybindings when running natively on Windows or in WSL:
+
+- `Alt+V` pastes an image or clipboard text.
+- `Ctrl+F` searches the transcript in fullscreen mode, and `Ctrl+Up`/`Ctrl+Down` jump between marked messages.
+- `Alt+P` cycles to the previous model.
+- `Ctrl+Z` undoes editing on native Windows; WSL uses `Alt+Z` so `Ctrl+Z` can suspend pi.
+- `Ctrl+Q` queues a follow-up message and `Alt+Q` restores queued messages.
+
+Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file) to forward `Shift+Enter` for inserting a new line:
 
 ```json
 {
@@ -128,20 +136,14 @@ Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file) to forward
     {
       "command": { "action": "sendInput", "input": "\u001b[13;2u" },
       "keys": "shift+enter"
-    },
-    {
-      "command": { "action": "sendInput", "input": "\u001b[13;3u" },
-      "keys": "alt+enter"
     }
   ]
 }
 ```
 
-- `Shift+Enter` inserts a new line.
-- Windows Terminal binds `Alt+Enter` to fullscreen by default. That prevents pi from receiving `Alt+Enter` for follow-up queueing.
-- Remapping `Alt+Enter` to `sendInput` forwards the real key chord to pi instead.
+Windows Terminal binds `Alt+Enter` to fullscreen by default. To use it instead of pi's `Ctrl+Q` default for follow-up queueing, configure Windows Terminal to send the key and bind `app.message.followUp` to `alt+enter` in pi.
 
-If you already have an `actions` array, add the objects to it. If the old fullscreen behavior persists, fully close and reopen Windows Terminal.
+If you already have an `actions` array, add the object to it. Fully close and reopen Windows Terminal after changing its settings.
 
 ## xfce4-terminal, terminator
 

package/docs/usage.md

@@ -165,7 +165,7 @@ If you use pi for open source work and want to publish sessions for model, promp
 ## CLI Reference
 
 ```bash
-senpi [options] [@files...] [messages...]
+senpi [options] [--] [@files...] [messages...]
 ```
 
 ### Package Commands
@@ -295,6 +295,9 @@ senpi "List all .ts files in src/"
 # Non-interactive
 senpi -p "Summarize this codebase"
 
+# Prompt beginning with a dash
+senpi -p -- "- Summarize these points"
+
 # Non-interactive with piped stdin
 cat README.md | senpi -p "Summarize this text"
 

package/docs/windows.md

@@ -1,6 +1,6 @@
 # Windows Setup
 
-Pi requires a bash shell on Windows. Checked locations (in order):
+Pi uses Git Bash by default on Windows. Checked locations (in order):
 
 1. Custom path from `~/.senpi/agent/settings.json`
 2. Git Bash (`C:\Program Files\Git\bin\bash.exe`)
@@ -8,7 +8,29 @@ Pi requires a bash shell on Windows. Checked locations (in order):
 
 For most users, [Git for Windows](https://git-scm.com/download/win) is sufficient.
 
-## Custom Shell Path
+## PowerShell Tool
+
+The optional `powershell` tool runs commands through `pwsh.exe` when available, otherwise Windows PowerShell. It starts PowerShell with `-NoProfile -NonInteractive -ExecutionPolicy Bypass`. Administrator-enforced execution policies can still take precedence.
+
+Use `defaultTools` to replace the model-facing `bash` tool:
+
+```json
+{
+  "defaultTools": ["read", "powershell", "edit", "write"]
+}
+```
+
+Or enable both while comparing behavior:
+
+```json
+{
+  "defaultTools": ["read", "bash", "powershell", "edit", "write"]
+}
+```
+
+The `!` and `!!` editor commands still use Bash.
+
+## Custom Bash Path
 
 ```json
 {

package/examples/AGENTS.md

@@ -5,16 +5,28 @@ Runnable examples for the public Senpi SDK and extension API. Examples are docum
 ## STRUCTURE
 
 ```text
-extensions/        Tools, commands, UI, providers, hooks, resources
-extensions/*/      Multi-file examples and nested private workspaces
-sdk/               Programmatic SDK usage
-rpc-extension-ui.ts RPC-compatible extension UI example
-extensions/kimi-deferred-tools.ts  Deferred tool discovery/activation example
+extensions/          Single-file extension catalog (70+ files) + multi-file dirs
+extensions/*/        Multi-file examples; several are private nested workspaces
+sdk/                 Numbered SDK programs (01-minimal.ts ... 13-session-runtime.ts)
+rpc-extension-ui.ts  RPC-mode extension UI as standalone JSONL child process
 ```
 
+## WHERE TO LOOK
+
+| Task | First choice |
+|---|---|
+| Tool/flag/command/shortcut registration | `extensions/tools.ts`, `commands.ts`, `dynamic-tools.ts` |
+| Custom provider, OAuth, streaming | `extensions/custom-provider-anthropic/` |
+| UI widgets, overlays, editors | `extensions/overlay-*.ts`, `modal-editor.ts`, `widget-placement.ts` |
+| Session-entry persistence | `extensions/todo.ts`, `bookmark.ts`, `handoff.ts` |
+| Safety guards | `extensions/permission-gate.ts`, `protected-paths.ts`, `sandbox/` |
+| Full SDK composition | `sdk/12-full-control.ts`, `sdk/13-session-runtime.ts` |
+
+Largest examples carry real complexity, not toy scope: `extensions/overlay-qa-tests.ts` (~1.5k LOC), `extensions/subagent/index.ts` (~1k), `extensions/tic-tac-toe.ts` (~1k), `extensions/custom-provider-anthropic/index.ts` (~600). See `extensions/AGENTS.md` for the catalog map.
+
 ## CONVENTIONS
 
-- Import public package surfaces such as `@code-yeongyu/senpi` and `@earendil-works/pi-ai`; do not reach into `packages/coding-agent/src/core/` internals.
+- Import public package surfaces — `@code-yeongyu/senpi` (newer alias), `@earendil-works/pi-coding-agent` (lower level), `@earendil-works/pi-ai`/`pi-tui` — never `packages/coding-agent/src/core/` internals.
 - Keep examples small enough to teach one pattern, while preserving real error, cleanup, cancellation, and persistence behavior where relevant.
 - Extension factories have no top-level runtime side effects. Register work through the public `pi.*` API and lifecycle events.
 - New interactive examples should use configurable keybindings and themed TUI helpers. Existing demos may keep fixed controls when the control scheme is part of the example. Direct terminal writes belong only in examples explicitly teaching a terminal protocol; ordinary SDK examples may use normal stdout.
@@ -23,6 +35,9 @@ extensions/kimi-deferred-tools.ts  Deferred tool discovery/activation example
 - Deferred-tool examples preserve the Kimi flow: expose search first, activate via `pi.setActiveTools()`, and register lifecycle work in `session_start`.
 - Stateful examples persist reconstructable state in session entries or tool-result details so fork/resume behavior remains valid.
 - Nested example packages are private workspaces with exact-pinned dependencies. Treat their manifests and lock impact as production dependency changes.
+- Kebab-case filenames and slash-command names; camelCase named exports; one example per file default-exporting its extension factory.
+- UI examples guard on `ctx.hasUI` and clean up timers/child processes on `session_shutdown`; stateful atomic tools (games, questionnaires) set `executionMode: "sequential"`.
+- Tool schemas use TypeBox; handlers follow the `(toolCallId, params, signal, onUpdate, ctx)` shape.
 
 ## DOCUMENTATION CONTRACT
 

package/examples/extensions/AGENTS.md

@@ -0,0 +1,50 @@
+# packages/coding-agent/examples/extensions
+
+Flat catalog of executable extension examples plus multi-file extension packages. Own file because it is the densest `pi.*` registration surface in the repo (score 14: 110+ files, 10 subdirs, heavy symbol/export density). Load any single file with `senpi -e <path>.ts`; per-example docs live in `README.md`.
+
+## STRUCTURE
+
+```text
+*.ts                        Single-file examples, one pattern each (kebab-case)
+subagent/                   Subagent tool: single/parallel/chain dispatch (~1k LOC)
+custom-provider-anthropic/  OAuth + Anthropic-compatible streaming provider
+custom-provider-gitlab-duo/ Provider against GitLab Duo
+gondolin/                   Route built-in tools + `!` commands into a Gondolin micro-VM
+sandbox/                    OS-level sandboxing via @anthropic-ai/sandbox-runtime
+plan-mode/                  Read-only planning mode (generated instructions)
+openai-codex-usage/         Codex usage tracking
+dynamic-resources/          Dynamic resource examples
+with-deps/                  Extension with its own private dependency manifest
+doom-overlay/               WASM Doom rendered as live overlay; doom/build/ is generated
+```
+
+## WHERE TO LOOK
+
+| Task | First choice |
+|---|---|
+| Register tool/command/flag/shortcut/renderer | `tools.ts`, `commands.ts`, `dynamic-tools.ts`, `custom-header.ts` |
+| Built-in tool override or rendering | `minimal-mode.ts`, `built-in-tool-renderer.ts` |
+| Overlays, focus, geometry | `overlay-test.ts`, `overlay-qa-tests.ts`, `widget-placement.ts` |
+| Provider auth/payload | `custom-provider-anthropic/`, `provider-payload.ts` |
+| Persistent state via session entries | `todo.ts`, `tic-tac-toe.ts`, `bookmark.ts`, `handoff.ts` |
+| Prompt/preset/config files | `preset.ts`, `prompt-customizer.ts`, `system-prompt-header.ts` |
+| Games / keyboard input | `snake.ts`, `space-invaders.ts`, `tic-tac-toe.ts` |
+| Deferred-tool activation (Kimi flow) | `kimi-deferred-tools.ts` |
+| RPC/UI child process | `../rpc-extension-ui.ts`, `rpc-demo.ts` |
+
+## CONVENTIONS
+
+- Event seams used across examples: `session_start`/`session_shutdown`, `turn_*`, `agent_*`, `before_agent_start`, `tool_call`/`tool_result`, `input`, `user_bash`, `model_select`.
+- Presets read `~/.senpi/agent/presets.json` then `<cwd>/.senpi/presets.json`; project file wins. `provider-payload.ts` writes under `CONFIG_DIR_NAME`.
+- `overlay-qa-tests.ts` is a runtime QA extension (many overlay commands, timers, spawned streaming processes), not a conventional test target.
+
+## ANTI-PATTERNS
+
+- Custom tools MUST truncate output (`truncated-tool.ts` demonstrates ripgrep wrapping with 50KB/2000-line caps).
+- Games never expose the user's cursor and never split a tool-call sequence across responses.
+- Never leave timers or child processes alive past `session_shutdown`.
+- Shell/process-delegating examples (`ssh.ts`, `interactive-shell.ts`, `inline-bash.ts`, `auto-commit-on-exit.ts`, `git-merge-and-resolve.ts`) cross trust boundaries; adopt deliberately, never as boilerplate.
+
+---
+
+Parent: `examples/AGENTS.md` (import rules, factory discipline, validation).