@code-yeongyu/senpi 2026.9.2 → 2026.9.3-2

package/docs/rpc.md

@@ -62,10 +62,14 @@ On Windows, listeners and clients deterministically map the logical socket path
 `\\.\pipe\senpi-rpc-<sha256[:32]>`. Callers keep using the same `unix://` CLI value; the logical path remains the
 ownership and settings identity, and callers never construct the pipe name themselves.
 
-Socket event visibility is an all-sessions broadcast: every connected client receives lifecycle and agent events from
-every open session, each tagged with its routing `sessionId`. Correlated responses and extension UI requests are sent
-only to the connection that issued the command. This lets a non-owner observe a foreign turn without requiring a
-separate subscription protocol.
+Socket event visibility is attachment-scoped for session content: each connection receives agent output only from sessions
+attached to that connection, with every record tagged by its routing `sessionId`. Content-free lifecycle records
+(`agent_start`, `agent_settled`, `agent_idle`, `session_opened`, and `session_closed`) are broadcast to all registered
+connections, including the supervisor's unattached observer, so host lifecycle accounting remains accurate without exposing
+session content. Correlated responses and dialog extension UI
+requests (select, confirm, input, and editor) are requester-only; other extension UI state records go to the session's
+attached connections. To observe a foreign session, open it by its existing
+`sessionPath`; the host attaches that connection during `open_session`.
 
 ### Client information and rendered components
 
@@ -175,7 +179,7 @@ so they hold even for embedders and hand-started hosts that have no supervisor.
 | --- | --- | --- | --- |
 | `get_protocol_info` | - | `{ protocolVersion: 1, serverVersion: string, capabilities: string[], mode: "classic"\|"multi" }` | Answered in BOTH modes; side-effect-free; the capability probe. Multi-session hosts include `multi_session` plus the negotiated launch capabilities. |
 | `open_session` | `sessionPath?`, `cwd?`, `provider?`, `modelId?`, `thinkingLevel?`, `permissionPreset?` (all optional; paths MUST be absolute) | `{ sessionId, state: RpcSessionState, attached?: true }` | `sessionPath` = today's `--session` semantics (open-if-exists else create persisting there, `session-manager.ts:926-940`); `provider`/`modelId` applied only on create (resume restores the session's model — mirrors `SenpiSessionRuntime.ts:198-200`); params form the immutable launch profile (D8). When the path is already held by a fully-open session, the open ATTACHES to it: same routing handle, `attached: true`, one more attachment counted; the runtime is torn down only when the last attachment closes. Fails with `too_many_sessions` at the occupancy cap (see [Shared host occupancy](#shared-host-occupancy-idle-eviction-session-cap-empty-host-exit)); idle sessions past the eviction window are closed by the host itself. |
-| `close_session` | `sessionId` | `{}` | Aborts active work, awaits agent idle + settled persistence, flushes queued events, detaches subscriptions; its response is the LAST record tagged with that handle — no events after (test-pinned). |
+| `close_session` | `sessionId` | `{}` | Aborts active work, awaits agent idle + settled persistence for up to the host grace window (default 10s), then force-releases the session; its response is the LAST record tagged with that handle for the first closer — no events after (test-pinned). A concurrent close joins the same teardown and receives its own successful response. |
 | `list_sessions` | - | `{ sessions: [{ sessionId, durableSessionId, sessionPath, cwd, name, status }] }` | Includes `opening`/`closing` entries with their status. |
 | every existing command | + `sessionId` (REQUIRED in multi mode) | unchanged | Routed to that session. |
 
@@ -206,7 +210,7 @@ Strict FIFO per session; one total stdout order; cross-session order unspecified
 
 ### Duplicate/idempotency
 
-Duplicate `open_session` while a path reservation is held by a fully-open session → ATTACH (`attached: true`, same handle); while held by an `opening`/`closing` entry → `session_path_in_use`. `close_session` releases one attachment; the runtime is disposed only when the last attachment closes. `close_session` on unknown/already-closed → `unknown_session` error. Request `id`s are client-owned; the server echoes them without dedup.
+Duplicate `open_session` while a path reservation is held by a fully-open session → ATTACH (`attached: true`, same handle); while held by an `opening`/`closing` entry → `session_path_in_use`. `close_session` releases one attachment; the runtime is disposed only when the last attachment closes. A close for an entry already `closing` joins its in-flight teardown. `close_session` on unknown/already-closed → `unknown_session` error. The grace window is configurable by the host through `SENPI_RPC_CLOSE_GRACE_MS`. Request `id`s are client-owned; the server echoes them without dedup.
 
 ## Protocol Overview
 
@@ -1705,6 +1709,37 @@ Emitted when an extension throws an error.
 }
 ```
 
+## OAuth login
+
+Logins are fire-command-then-subscribe: the command answers as soon as the flow has started, and the URL plus the terminal result arrive as events.
+
+- `login_start` `{provider}`: responds immediately with `success: true` (flow started). A second `login_start` for the same provider aborts the earlier attempt.
+- `auth_login_url` `{provider, url}`: the URL (or device-code verification URL) the user must open.
+- `auth_login_end` `{provider, success, error?}`: exactly one per login; `error` is a non-secret message.
+- `login_cancel` `{provider}`: aborts the in-flight login; the client then sees `auth_login_end` with `success: false`.
+
+Some providers need input mid-flow (a pasted authorization code, a text or secret value, a choice between accounts). Those prompts reuse the extension UI dialog channel described in the next section:
+
+- `text`, `secret`, and `manual_code` prompts arrive as an `extension_ui_request` with `method: "input"`. `title` is the provider's prompt message and `placeholder` is present when the provider supplied one.
+- `select` prompts arrive with `method: "select"`; `options` holds the option labels.
+
+Answer with `extension_ui_response` `{id, value}`. For `select`, `value` is the chosen label and is mapped back to the option id in-process. Sending `{id, cancelled: true}` cancels the login, and `auth_login_end` reports `success: false` with `error: "Login cancelled"`.
+
+A client that never answers loses nothing. The browser/callback completion path still finishes the login, and the pending request is released when the login ends or is cancelled, so an open dialog never blocks completion. Secrets don't cross the wire in either direction: only the prompt message, placeholder, and labels are emitted, and the answer is consumed in-process and never echoed.
+
+Example exchange (Anthropic, user pastes the code instead of finishing in the browser):
+
+```jsonl
+{"id": "login-1", "type": "login_start", "provider": "anthropic"}
+{"id": "login-1", "type": "response", "command": "login_start", "success": true}
+{"type": "auth_login_url", "provider": "anthropic", "url": "https://claude.ai/oauth/authorize?..."}
+{"type": "extension_ui_request", "id": "uuid-7", "method": "input", "title": "Complete login in your browser, or paste the authorization code / redirect URL here:", "placeholder": "http://localhost:53692/callback"}
+{"type": "extension_ui_response", "id": "uuid-7", "value": "<pasted code>"}
+{"type": "auth_login_end", "provider": "anthropic", "success": true}
+```
+
+If the user completes the flow in the browser instead, the same `extension_ui_request` is emitted, no response is needed, and `auth_login_end` arrives on its own.
+
 ## Extension UI Protocol
 
 Extensions can request user interaction via `ctx.ui.select()`, `ctx.ui.confirm()`, etc. In RPC mode, these are translated into a request/response sub-protocol on top of the base command/event flow.

package/docs/settings.md

@@ -212,14 +212,14 @@ Set `PI_SKIP_VERSION_CHECK=1` to disable the senpi version update check. Use `--
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
 | `retry.enabled` | boolean | `true` | Enable automatic agent-level retry on transient errors |
-| `retry.maxRetries` | number | `3` | Maximum agent-level retry attempts |
+| `retry.maxRetries` | number | `5` | Maximum agent-level retry attempts |
 | `retry.baseDelayMs` | number | `2000` | Base delay for agent-level exponential backoff (2s, 4s, 8s) |
 | `retry.modelFallback` | boolean | `true` | Let eligible retry failures advance through configured per-model fallback chains |
 | `retry.fallbackChains` | `Record<string, string[]>` | `{}` | Ordered exact model-selector to fallback-selector chains |
 | `retry.fallbackRevertPolicy` | `"cooldown-expiry"` \| `"never"` | `"cooldown-expiry"` | Automatic primary-model restoration policy |
 | `retry.abortServerSideFallback` | boolean | `true` | Abort a turn when the provider substitutes a different model after a classifier decline |
 | `retry.provider.timeoutMs` | number | `300000` | Provider/SDK request timeout and stream idle timeout in milliseconds |
-| `retry.provider.streamStartTimeoutMs` | number | `90000` | Maximum wait for the first provider stream event; `0` disables |
+| `retry.provider.streamStartTimeoutMs` | number | `300000` | Maximum wait for the first provider stream event; `0` disables |
 | `retry.provider.streamRetryTimeoutMs` | number | `30000` | First-request liveness cap after a known provider stream/transport timeout; `0` disables the cap |
 | `retry.provider.maxRetries` | number | `0` | Provider/SDK retry attempts |
 | `retry.provider.maxRetryDelayMs` | number | `60000` | Max server-requested delay honored on the same model before the fallback chain engages (60s) |
@@ -236,11 +236,11 @@ Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explic
 {
   "retry": {
     "enabled": true,
-    "maxRetries": 3,
+    "maxRetries": 5,
     "baseDelayMs": 2000,
     "provider": {
       "timeoutMs": 3600000,
-      "streamStartTimeoutMs": 90000,
+      "streamStartTimeoutMs": 300000,
       "streamRetryTimeoutMs": 30000,
       "maxRetries": 0,
       "maxRetryDelayMs": 60000
@@ -399,8 +399,6 @@ Windows paths in JSON must use forward slashes or escaped backslashes:
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
 | `defaultTools` | string[] | - | Built-in tools enabled initially. When omitted, Pi uses its standard defaults |
-| `experimental.bashEvalOnly` | boolean | `false` | Route `bash` and `powershell` through eval cells only; the tools leave the model's direct tool list |
-| `experimental.workflowEvalOnly` | boolean | `false` | Route the workflow (dag) tool through eval cells only; the tool leaves the model direct tool list |
 
 `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`:
 
@@ -420,37 +418,17 @@ On Windows, select `powershell` instead of `bash`, or include both:
 
 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.
 
-With `experimental.bashEvalOnly` enabled, the `bash` and `powershell` tools disappear from the model's direct tool list and run only inside eval cells:
+#### Eval-only tools
 
-```json
-{
-  "experimental": {
-    "bashEvalOnly": true
-  }
-}
-```
+Whenever the `eval` tool is available (codemode loaded), `bash`, `powershell`, `workflow` and `monitor` leave the model's direct tool list and run only inside eval cells:
 
 ```js
 const { output } = await tool.bash({ command: "ls -la" });
-```
-
-Hooks and permission checks apply unchanged to shell commands run this way. If the model hallucinates a direct `bash` or `powershell` call anyway, the call returns a hint redirecting it to an eval cell. When the `eval` tool is unavailable (codemode not loaded), the policy auto-disables and both tools stay on the direct tool list, so shell access is never lost.
-
-With `experimental.workflowEvalOnly` enabled, the `workflow` (dag) tool disappears from the model's direct tool list and runs only inside eval cells:
-
-```json
-{
-  "experimental": {
-    "workflowEvalOnly": true
-  }
-}
-```
-
-```js
 const snapshot = await tool.workflow({ action: "snapshot", run_id });
+await tool.monitor({ description: "build", command: "bun run build", filter: "^done" });
 ```
 
-Hooks and permission checks apply unchanged to workflow operations run this way. When the `eval` tool is unavailable (codemode not loaded), the policy auto-disables and the workflow tool stays on the direct tool list, so workflow access is never lost.
+This is the default and has no setting. Hooks and permission checks apply unchanged to calls made this way, and the prompt surfaces that document these tools render the `tool.<name>(` form to match. If the model attempts a direct call anyway, the call returns a hint naming the eval form. When the `eval` tool is unavailable (codemode not loaded, or a child agent whose allowlist omits it), the policy stays inert and all four tools remain directly callable, so shell, workflow and monitor access is never lost.
 
 ### Sessions
 

package/docs/terminal-tools.md

@@ -12,7 +12,7 @@ platform/runtime).
 |------|---------|
 | `bash` | Run a command in a PTY. `run_in_background: true` starts a persistent session and returns a `bash_id` immediately. Foreground `timeout` (seconds) is a kill deadline. |
 | `bash_output` | Peek at a session without blocking: new output since the last read, or the status line. `filter` regex-filters lines; `view: "screen"` returns the rendered xterm grid. |
-| `monitor` | Watch a long-running command (`description`, `command`, `filter?`, `timeout_ms?`, `persistent?`) and inject matching PTY output lines as coalesced events. While watches are live, the interactive footer shows a brief `watching …` status (descriptions, count, paused markers). |
+| `monitor` | Watch a change and inject it as coalesced events, passing `command` XOR `path`: a long-running command (`description`, `command`, `filter?`, `timeout_ms?`, `persistent?`) injects matching PTY output lines, while a file (`description`, `path`, `event?`) fires once natively. While watches are live, the interactive footer shows a brief `watching …` status (descriptions, count, paused markers). |
 | `bash_input` | Send stdin (`input`) or named keys (`keys: ["ctrl+c"]`, `["enter"]`, `["up"]`) to steer a REPL or interrupt a process. |
 | `bash_resize` | Resize a session's PTY (`cols`, `rows`) so full-screen TUIs reflow. |
 | `kill_bash` | Tree-kill one session (`bash_id`) or all (`all: true`), leaving no orphans. |
@@ -80,17 +80,33 @@ monitor({ description: "PR checks",
 Expected event: the verdict line when checks settle, then the summary. Merge on
 pass, pull the failing job's log on fail. The command exits by itself.
 
-### File or port transition
+### File transition (native file branch)
 
 ```js
 monitor({ description: "artifact written",
-  command: "until test -f dist/app.tar.gz; do sleep 2; done; printf 'READY\n'",
+  path: "dist/app.tar.gz",
+  event: "create" })
+```
+
+One file, watched natively — no shell, no poll loop. `create` (the default)
+fires only when the file appears after registration; to watch a file that
+already exists, pass `event: "modify"`. Registration needs the parent directory
+(`dist/` here) to exist already, and the target must be a regular file, not a
+symlink — when the build creates the directory too, keep a command poll loop
+like the port recipe below. This branch is XOR with `command` and takes no
+`filter` and no `persistent`. Expected event: one hit when the file lands, then
+the watch is done. Consume the artifact.
+
+### Port transition
+
+```js
+monitor({ description: "postgres up",
+  command: "until nc -z localhost 5432; do sleep 1; done; printf 'READY\n'",
   filter: "^READY$" })
 ```
 
-Same shape works for ports: `until nc -z localhost 5432; do sleep 1; done;
-printf 'READY\n'`. Expected event: `READY`, then exit. Consume the artifact
-or connect.
+A port has no native watch, so the sleep loop belongs inside the command.
+Expected event: `READY`, then exit. Connect.
 
 ### Child-agent sentinel watch
 
@@ -113,6 +129,10 @@ results and integrate. Exits on its own; no cleanup.
 | Expecting `filter` to stop the command | `filter` gates events only; make the command exit on the condition |
 | `persistent: true` with `timeout_ms` | The timeout is ignored when persistent; pick one |
 | Sentinel printed without a trailing newline | Sentinels must be newline-terminated: `printf 'READY\n'` |
+| Polling `test -f` in a command to await one file | Use the file branch: `monitor({ description, path, event? })` |
+| `event: "create"` on a file that already exists | `create` fires only on appearance; use `event: "modify"` |
+| `path` whose parent directory the build has yet to create | Registration fails; poll for it with a `command` watch instead |
+| Passing `command` and `path` in one call | They are XOR; pick the branch that matches what you await |
 | Monitoring sub-minute deterministic work | Run it directly in the foreground |
 | Rearming a monitor that was never paused | Rearm only a `bash_id` named in a pause notice |
 

package/docs/windows.md

@@ -30,7 +30,7 @@ Or enable both while comparing behavior:
 
 The `!` and `!!` editor commands still use Bash.
 
-With `experimental.bashEvalOnly` enabled, both `bash` and `powershell` run only inside eval cells; see [Settings](settings.md#tools).
+Whenever the `eval` tool is available, both `bash` and `powershell` run only inside eval cells; see [Settings](settings.md#tools).
 
 ## Custom Bash Path
 

package/node_modules/@anthropic-ai/claude-agent-sdk/bridge.d.ts

@@ -158,12 +158,29 @@ export type AttachBridgeSessionOptions = {
      * then answers with a "not supported in this context" error.
      */
     onStopTask?: (taskId: string) => Promise<void>;
+    /**
+     * `background_tasks` from claude.ai — the client's Ctrl+B. With a
+     * toolUseId, background the single foreground task that tool_use block
+     * started and return whether one was found; without, background every
+     * foreground task and return true. May answer asynchronously (e.g. by
+     * delegating to `Query.backgroundTasks()`); a rejection is sent as an
+     * error reply. Omit if the host has no task registry — the CLI then
+     * answers with a "not supported in this context" error.
+     */
+    onBackgroundTasks?: (toolUseId: string | undefined) => boolean | Promise<boolean>;
     onSetModel?: (model: string | undefined) => {
         ok: true;
+        notices?: string[];
+    } | {
+        ok: false;
+        error: string;
+    } | void | Promise<{
+        ok: true;
+        notices?: string[];
     } | {
         ok: false;
         error: string;
-    } | void;
+    }>;
     onSetMaxThinkingTokens?: (tokens: number | null | undefined, thinkingDisplay?: 'summarized' | 'omitted' | null) => void;
     /**
      * `set_permission_mode` from claude.ai. Return an error verdict to send