@senpiper/sp-agent 0.1.6 → 0.1.9

package/node_modules/@senpiper/sp-agent-extensions/CONCURRENT_SESSIONS.md

@@ -0,0 +1,68 @@
+# Concurrent SP sessions
+
+SP supports independent concurrent sessions within one instance. Browser selection does not replace the terminal session or stop another web session.
+
+## Wire contract
+
+Send these commands to any authenticated descriptor belonging to the instance:
+
+| Command | Parameters | Result |
+|---|---|---|
+| `create_session` | `{ "cwd": "/absolute/project/path" }` | `{ "sessionId": "..." }` |
+| `resume_session` | `{ "sessionFile": "/absolute/session.jsonl" }` | `{ "sessionId": "..." }` |
+| `delete_session` | `{ "sessionId": "...", "sessionFile": "/absolute/session.jsonl", "confirmed": true }`, `sessionFile` optional | `{ "sessionId": "...", "deleted": true }` |
+
+The result is returned only after the child descriptor is published in the existing discovery directory. Find it by `sessionId`, authenticate with its token, and use the existing state, transcript, subscription, prompt, steer, follow-up, abort, model, thinking, title, and question commands. Each descriptor retains its own generation and replay sequence. No envelope or descriptor format changed.
+
+`state.capabilities.newSession` and `resumeSession` are true when the SP distribution supplies its instance manager. An extension loaded without that manager keeps these capabilities false.
+
+Repeated resumes of the same file return the existing session ID, including concurrent requests and symlink aliases. Resuming the terminal's current file returns the terminal session ID without opening another writer. Requests racing a terminal acquisition fail and may be retried after it settles.
+
+Browser switching is client-local. Disconnecting from B and subscribing to C leaves A and B running. The web process must never construct a second writer for a live descriptor.
+
+## Ownership and lifetime
+
+`packages/sp-agent/src/sdk.ts` supplies the verified SP factory. It uses the same required-extension identity, provider policy, and resource ownership checks as `createSpAgentSession`; the bridge does not recreate provider policy.
+
+`SpSessionManager` reserves canonical file paths synchronously before opening files or awaiting construction. Failed construction releases the reservation. Hard-linked files are rejected to avoid alternate names bypassing ownership.
+
+The terminal runtime registers its existing writer rather than reopening its file. Generic runtime hooks hold a terminal acquisition lease across resume/import, including extension cancellation and replacement failure. They block terminal resume or import into a web-owned file before it can be opened or overwritten. Ownership of an outgoing terminal file is released after its writer is disposed.
+
+The instance manager outlives terminal new, resume, fork, and reload operations. Child sessions have separate SDK services, agents, command queues, extension instances, and question owners. Managed web questions wait for bridge answers without displaying a dialog in the terminal. Answers and abort bypass slow commands on the same child.
+
+Explicit manager disposal and terminal quit stop bridges, cancel questions, abort child turns, emit shutdown, dispose sessions, and flush settings. Signal handlers run the same cleanup. A synchronous process-exit fallback removes owned descriptors and sockets. SDK hosts must await `dispose()` for graceful cleanup. SIGKILL cannot run cleanup.
+
+## Permanent deletion and writer leases
+
+`capabilities.deleteSession` is true only when the native SP distribution deletion provider is active. The extension alone advertises false and rejects the command. Deletion never starts an SDK writer for inactive history.
+
+For a managed child, deletion checks prompt preflight, active runs, queued messages, questions, compaction, retries, bash, and pending bridge commands. A busy child returns `busy`; deletion does not abort it to make it eligible. The owner gates new mutations, retains its existing file reservation, disposes only that child, and unlinks only that JSONL. Parent, descendant, sibling, and terminal sessions remain untouched. Deleting the current terminal session returns `terminal_root`. Run `/new` in that terminal first; deletion never shuts down the whole instance.
+
+Inactive history must be inside the canonical configured history root. CLI configuration includes `--session-dir`, the session-directory environment override, and the configured settings fallback. SDK managers default to `$SP_CODING_AGENT_DIR/sessions` or `SP_CODING_AGENT_SESSION_DIR`; hosts using a different history root must call `setHistoryRoot()` explicitly. An arbitrary selected session's parent directory does not become an authorized history root. Explicit paths must be canonical absolute `.jsonl` paths to regular files with one hard link. Symlink aliases, escapes, mismatched header IDs, and ambiguous ID-only lookups are rejected. Header validation is bounded to 1 MiB and does not repair files.
+
+The generic `MainOptions.sessionWriterLeaseProvider` hook runs before CLI session opening. The SP SDK installs the same provider on import, before callers construct persistent `SessionManager`s. Passing a persistent manager constructed before SP participation is rejected. New files, resume, import destinations, branch creation, and JSONL export use the provider. Each persistent manager retains its lease until disposal, not merely until resume finishes. Failed construction releases its lease. Disposed or transaction-reserved writers reject further writes.
+
+All participating processes use exclusive, non-expiring files under `.sp-writer-leases` beside the JSONL directory. Locks are independent of the JSONL inode and canonicalize aliases. A managed deletion retains the exact existing lease through writer disposal and unlink, with no unlock/relock gap. A deletion tombstone prevents a previously selected resume path from recreating the deleted file. Normal disposal and process exit release leases. A paused process never loses its lease to a heartbeat timeout.
+
+Crash-orphaned locks fail closed. There is no automatic stale-lock takeover. If an SP process is killed without exit cleanup, stop all SP processes using that history before an operator removes its orphan `.lock` files. Do not remove `.deleted` tombstones or live locks. This availability tradeoff prevents paused writers from resuming after deletion.
+
+Self-deletion preserves bridge connections until its success or error response drains, while rejecting new commands. Other deletions close target sockets during shutdown. Client disconnection does not cancel deletion or release the transaction reservation early.
+
+### Required cutover
+
+After installing this version, **restart every SP instance**, including terminal, print/RPC, managed-session, and SDK hosts. Updating files on disk does not upgrade a running writer. The owner rejects discoverable live legacy SP descriptors without `writerLeaseVersion: 1`, even when they currently select another session. PID checks are limited to these discoverable owners; deletion does not attempt to prove the absence of every OS writer.
+
+The guarantee covers cooperating updated SP writers. Arbitrary external programs, nonparticipating SDK hosts, old processes that were not restarted and are not discoverable, and direct filesystem writes are outside it. Do not use native deletion during a mixed-version cutover.
+
+Read-only web history browsing must not acquire writer leases. Use `SessionManager.open(path, undefined, undefined, { readOnly: true })` or `openReadonly(path)`. These paths do not repair or migrate files on disk and cannot persist mutations. Live browser commands still go through the native owner. Fork and arbitrary extension UI dialogs remain outside the web protocol.
+
+## Focused validation
+
+No builds or real provider calls are required:
+
+```sh
+cd packages/sp-agent
+node ../../node_modules/vitest/dist/cli.js --run --config test/concurrent-vitest.config.ts test/concurrent-sessions.test.ts test/writer-leases.test.ts
+```
+
+The tests use source runtime aliases and the faux provider. They exercise concurrent terminal/web turns, wire creation/resume, independent questions, terminal replacement and reload, acquisition races, failed construction, import exclusion, and shutdown.

package/node_modules/@senpiper/sp-agent-extensions/TERMINAL_WEB_BRIDGE.md

@@ -1,6 +1,6 @@
 # SP terminal web bridge protocol
 
-Interactive `sp` sessions expose their live state through a same-user Unix socket. The terminal process remains the only owner of the `AgentSession` and JSONL file. A web client must send all live commands through this socket. It must not open or resume the same session through another session manager.
+Interactive `sp` sessions expose their live state through same-user Unix sockets. The SP process owns the terminal session and any independent web sessions it creates. Each has its own descriptor, `AgentSession`, and JSONL writer. A web client must send live commands through the corresponding socket, not open another writer.
 
 ## Discovery
 
@@ -30,7 +30,7 @@ The bridge replies with `type: "hello"` and `ok: true`, or sends `authentication
 {"v":1,"type":"request","id":"req-1","generation":1,"command":"state","params":{}}
 ```
 
-A response repeats `id` and has either `ok: true` with `result`, or `ok: false` with `{ "code", "message" }`. Request IDs cannot be reused on one connection. A session generation change closes existing clients. Requests that carry an old generation receive `stale_generation`.
+A response repeats `id` and has either `ok: true` with `result`, or `ok: false` with `{ "code", "message" }`. Responses can arrive out of request order. Reads, question answers, and abort bypass slow model or title commands. Request IDs cannot be reused on one connection. A session generation change closes existing clients. Requests that carry an old generation receive `stale_generation`.
 
 ## Commands
 
@@ -42,25 +42,142 @@ A response repeats `id` and has either `ok: true` with `result`, or `ok: false`
 | `models` | none | Returns the models available within the terminal session's model scope. |
 | `generate_title` | none | Generates an English title with the active SP Gateway model and applies it through the terminal owner. |
 | `subscribe` | `afterSequence` | Replays retained events after the sequence and subscribes to new events. Returns `event_gap` if the requested point is no longer retained. |
-| `prompt` | `text`, optional `expandPromptTemplates` | Starts a turn while idle. |
-| `steer` | `text` | Steers the active turn. Fails while idle. |
-| `follow_up` | `text` | Queues a follow-up for the active turn. Fails while idle. |
+| `prompt` | `text`, optional `images`, optional `expandPromptTemplates` | Starts a turn while idle. Text may be omitted with images. |
+| `steer` | `text`, optional `images` | Steers the active turn. Fails while idle. Text may be omitted with images. |
+| `follow_up` | `text`, optional `images` | Queues a follow-up for the active turn. Fails while idle. Text may be omitted with images. |
 | `abort` | none | Aborts the active turn. Fails while idle. |
+| `respond_to_question` | `interactionId`, `response` | Answers or cancels the pending `ask_user_question` question. Works during the active turn. |
 | `set_thinking` | `level` | Changes thinking while idle. Pi clamps the value to model support. |
 | `set_model` | `provider`, `modelId` | Changes to an available, credentialed model within the current session scope while idle. |
+| `create_session` | `cwd`, an existing absolute directory | Creates an independent web session and returns `{ sessionId }` after publishing its descriptor. |
+| `resume_session` | `sessionFile`, an absolute path | Acquires an independent web session or returns its existing `{ sessionId }`. Returns the terminal ID for its current file without reopening it. |
+| `delete_session` | `sessionId`, optional canonical absolute `sessionFile`, `confirmed: true` | Permanently deletes only the selected idle managed child or inactive history file. Returns `{ sessionId, deleted: true }`. |
 
-The bridge does not support new, resume, fork, direct JSONL mutation, credential changes, or arbitrary model construction. The `state` capability object reports these limits.
+Creation and resume require the instance-owned factory supplied by SP. `state.capabilities.newSession` and `resumeSession` advertise availability. Browser selection and disconnection do not stop runs. See [concurrent sessions](CONCURRENT_SESSIONS.md) for acquisition and lifetime rules. Fork, direct JSONL mutation, credential changes, and arbitrary model construction remain unsupported.
+
+`state.capabilities.deleteSession` is true only with the native deletion provider. Deletion rejects busy, queued, or question-owning targets. The current terminal root returns `terminal_root`; the user must run `/new` there first. Explicit confirmation is mandatory. `writer_owned`, `legacy_owner`, `invalid_path`, `invalid_session`, and `session_deleted` describe ownership, cutover, validation, and tombstone failures. Filesystem failures can also be returned. No descendants or sibling sessions are deleted. Self-delete responses drain before their socket closes, and disconnecting does not cancel the transaction.
+
+Restart **all SP instances after installation** before using deletion. Updated writers share lifetime leases; discoverable live legacy owners are rejected. External/nonparticipating SDK and direct filesystem writers are outside the guarantee. See the required cutover and orphan-lock procedure in [concurrent sessions](CONCURRENT_SESSIONS.md).
 
 Events use `type: "event"` and include `generation`, monotonic `sequence`, `category`, `event`, and `payload`. Categories cover session, agent, message, tool, model, and thinking lifecycle events. The replay buffer and client count are bounded. The bridge disconnects clients that exceed frame or output-buffer limits.
 
-## pi-web sidecar
+Replay retains at most 256 events and 32 MiB of encoded frames, advertised as `capabilities.eventStream.replayLimit` and `replayByteLimit`. An event that exceeds the frame limit is replaced at the same sequence with `event: "event_gap"`, `category: "session"`, and `payload: {"type":"event_gap","code":"event_gap","resyncRequired":true}`. The bridge then closes live subscribers so clients recover even without marker support. Clients must handle this marker as the existing `event_gap` reset path, fetch a fresh snapshot and its remaining transcript pages, then subscribe after that snapshot's sequence. Subscriptions crossing an omitted event, an evicted prefix, or a future sequence fail with `event_gap`, never a successful replay acknowledgement. Payloads that fit, including `agent_end.messages`, remain unchanged.
+
+## User images
+
+Native terminal and managed web owners advertise `capabilities.images: true` in `state` and `snapshot.state`. This means the bridge supports image delivery, not that every selected model supports vision. Clients must not send attachments to older owners without this capability.
+
+All three user-message commands accept an additive `params.images` array:
+
+```json
+{"text":"Describe this screenshot","images":[{"mimeType":"image/png","data":"canonical base64 image bytes"}]}
+```
+
+Each image must contain only `mimeType` and `data`. MIME types are exactly `image/png`, `image/jpeg`, `image/webp`, or `image/gif`. Data must be nonempty canonical standard base64, padded when needed. Paths, URLs, data URLs, URL-safe base64, whitespace, invalid padding, and extra image fields are rejected with `invalid_params`. Validation checks the MIME label and base64 encoding, not decoded image format or dimensions. The bridge never reads an attachment path.
+
+`capabilities.imageLimits` contains:
+
+```json
+{"mimeTypes":["image/png","image/jpeg","image/webp","image/gif"],"maxImages":8,"maxBase64BytesPerImage":4194304,"maxBase64BytesTotal":8388608}
+```
+
+Limits count the base64 ASCII bytes, not decoded bytes. These correspond to at most 3 MiB decoded per image and 6 MiB decoded in total. The default frame limit and per-client outgoing buffer limit are now 10 MiB each, up from 1 MiB. The full UTF-8 JSON envelope plus newline must fit `descriptor.frame.maxBytes`, which can be configured lower. Frontends must compress or reject oversized pastes, check both image budgets and the serialized frame budget, and retain the draft on rejection. The bridge does not compress or truncate attachments. An invalid image rejects the entire command before sending any text or images. Image-budget violations return `invalid_params`; oversized incoming frames disconnect the client.
+
+With nonempty images, `text` may be absent, empty, or whitespace-only. When supplied it must be a string of at most 100,000 UTF-8 bytes. Without images, the existing nonblank text requirement and string sender remain unchanged, including when `images` is `[]`.
+
+The owner sends text first, if present, followed by image parts through the SDK's actual `pi.sendUserMessage` content array: `{type:"image", mimeType, data}`. Image-only input sends an image-only array. No second session or direct JSONL write is involved. `prompt` still opts into command dispatch and skill/template expansion only when `expandPromptTemplates === true`; otherwise text remains literal. `steer` and `follow_up` retain their existing delivery options and do not enable expansion. An accepted response acknowledges dispatch, not successful provider inference.
+
+Snapshot and transcript pages are byte-budgeted against the complete response envelope, including snapshot state, escaped request ID, and newline. A page may contain fewer entries than requested. `nextCursor` advances by the number actually included; fetch remaining pages until it is `null`. Entries and image data are never truncated or split. If the envelope or a single entry cannot fit, the request fails explicitly with `frame_too_large`. There is no chunked transcript or image transport. Title generation replaces image parts with type/MIME placeholders before serializing and truncating its text context; persisted images remain unchanged.
+
+## Active branch metadata
+
+Every successful `state` response includes `result.session.activeLeafId`. Every successful `snapshot` response includes `result.state.session.activeLeafId`. The field is always present and has type `string | null`. The bridge reads it directly from the current terminal context's `ctx.sessionManager.getLeafId()` on each request. It is not cached in the discovery descriptor or inferred from the last recorded entry.
+
+For example, these are partial response bodies for a selected older branch:
+
+```json
+{"result":{"session":{"activeLeafId":"older-branch-leaf"}}}
+{"result":{"state":{"session":{"activeLeafId":"older-branch-leaf"}}}}
+```
+
+`null` means the owner has no selected entry, including an empty session or a selection before the first entry. It can occur while recorded entries still exist. Clients must distinguish explicit `null` from an absent field on an older bridge. An absent field means the selected leaf is unknown, not that the latest recorded entry is selected.
+
+The ID identifies a session entry, not necessarily a message or the last entry in file order. To reconstruct the selected branch, follow that entry's `parentId` chain to `null`, then reverse the chain. With an explicit `null` leaf, the selected chain is empty. Do not substitute the newest recorded branch. If the selected entry or an ancestor is not loaded, fetch further bounded transcript pages before resolving the branch.
+
+Transcript behavior is unchanged. `snapshot.transcript` contains the first at most 100 entries from `getEntries()` in recorded order, across all branches. `transcript` uses a zero-based entry-offset `cursor`, default `0`, and a `limit`, default `50`, capped at `100`. Its result remains `{ cursor, nextCursor, total, entries }`; `nextCursor` is `null` at the end. `session.entryCount` and transcript `total` count all recorded entries, not just the selected branch. The leaf may lie outside the first page. Frame and output-buffer limits still apply, and an oversized response returns `frame_too_large`.
+
+Tree navigation can change the leaf without changing entry count or generation. Subsequent `state` and `snapshot` reads reflect the current selection. The existing `session_tree` event retains its payload, including `oldLeafId` and `newLeafId`; clients can refresh state after it. Session replacement uses the existing generation change, disconnect, rediscovery, and reauthentication flow. Reads in the new generation use the replacement context's leaf, including `null`.
+
+Active branch metadata uses `sp-terminal-bridge-v1`, with envelope `v: 1` and descriptor version `1` unchanged. Older clients may ignore it. Transcript page shapes are unchanged. Reading branch metadata does not mutate the branch or create a session.
+
+Reads describe current state, not an immutable multi-request transcript snapshot. Subscribe after the snapshot's sequence to recover intervening retained events. Refresh state after branch changes or an `event_gap`, and discard old-generation data after a switch. Pagination alone does not freeze the selected leaf.
+
+## Questions
+
+`state.pendingQuestion` and `snapshot.state.pendingQuestion` are `null` when no question is pending. `capabilities.respondToQuestion` advertises support. A pending question has this shape:
+
+```json
+{
+  "interactionId": "fresh UUID for this question",
+  "toolCallId": "original tool call ID",
+  "questionIndex": 0,
+  "questionCount": 2,
+  "question": {
+    "header": "Runtime",
+    "question": "Which runtime?",
+    "options": [
+      {"label": "Node", "description": "Node runtime", "preview": "optional markdown"},
+      {"label": "Bun", "description": "Bun runtime"}
+    ],
+    "multiSelect": false
+  }
+}
+```
+
+`questionIndex` is zero-based. `header`, `preview`, and `multiSelect` are optional. An absent `multiSelect` means single-select. Custom text is always allowed.
+
+The bridge publishes replayable events with category `interaction`:
+
+- `question_pending`: payload `{ "type": "question_pending", "pendingQuestion": ... }`.
+- `question_resolved`: payload `{ "type": "question_resolved", "interactionId", "toolCallId", "questionIndex", "source", "cancelled", "answer"? }`. Source is `terminal`, `web`, `abort`, or `error`. The optional answer uses the tool's canonical answer shape.
+
+Answer through the authenticated connection with the current generation:
+
+```json
+{"v":1,"type":"request","id":"answer-1","generation":1,"command":"respond_to_question","params":{"interactionId":"UUID from pendingQuestion","response":{"kind":"option","option":"Node"}}}
+```
+
+Supported response shapes:
+
+| Response | Meaning |
+|---|---|
+| `{ "kind": "option", "option": "Node" }` | One exact option label for a single-select question. |
+| `{ "kind": "multi", "selected": ["Tests", "Lint"], "notes": "optional text" }` | Unique exact labels for a multi-select question. An empty list is valid. |
+| `{ "kind": "custom", "text": "Another answer" }` | Custom answer to either question type. Empty or whitespace-only text records no input. |
+| `{ "kind": "cancel" }` | Declines the remaining questionnaire, retaining earlier answers in tool details. |
+
+Unexpected fields, invalid labels, duplicate selections, wrong selection kinds, and non-string text fail with `invalid_params` without consuming the question. Text and notes are limited to 100,000 UTF-16 code units, also subject to the frame byte limit. The terminal derives question text, option previews, and answer indices; clients cannot supply them.
+
+Successful responses return `{ "accepted": true }`. The next `question_pending` event can arrive before that acknowledgement; do not clear a newer question when the response arrives. Each question has a fresh interaction ID, even if a tool call ID is reused. Terminal and web share one pending interaction. The first accepted answer consumes it synchronously and dismisses any terminal selector or custom-input dialog using its public abort signal. Later responses with that ID return `stale_interaction`, including retries from another connection. Request IDs alone are not interaction IDs.
+
+Questions stay pending across web disconnects. Read a snapshot on reconnect and subscribe after its sequence to close the snapshot/subscription race. Process events in sequence order; only clear a displayed question when a resolved event matches its interaction ID. Abort, session shutdown, reload, and generation replacement cancel the questionnaire rather than restoring it. No question is reconstructed from JSONL, and no second session is created.
+
+This protocol covers `ask_user_question`, not arbitrary extension UI prompts such as login or onboarding. Oversized question events follow the existing frame limit; terminal dialogs remain available, but the web snapshot can return `frame_too_large`. The bridge does not split questions into multiple frames.
+
+## SP Web sidecar
 
 The extension starts one detached sidecar per configured SP agent directory and reuses its private PID record while that process is alive. Configuration:
 
 | Variable | Meaning |
 |---|---|
-| `SP_PI_WEB_EXECUTABLE` | Executable path or name. Defaults to `pi-web`. |
-| `SP_PI_WEB_ARGS_JSON` | JSON string array of arguments. The launcher does not use a shell. |
-| `SP_PI_WEB_DISABLE` | `1`, `true`, or `yes` disables launch. |
+| `SP_WEB_EXECUTABLE` | Explicit executable path or name, overriding installed package resolution. |
+| `SP_WEB_ARGS_JSON` | JSON string array of arguments. The launcher does not use a shell. |
+| `SP_WEB_DISABLE` | `1`, `true`, or `yes` disables launch. |
+
+Each `SP_WEB_*` setting takes precedence over its old `SP_PI_WEB_*` alias, including an explicitly empty value. Without an executable override, the launcher resolves `@senpiper/sp-web/bin/sp-web.js` from the extension module, then from the SP executable location. The current source pins `@senpiper/sp-web@0.1.1` as a normal registry dependency, installed automatically by the same global SP install command, not bundled in the SP tarball. The resolved absolute entry runs with the current Node executable, or external `node` from PATH when SP runs under Bun. Compiled Bun's executable anchor locates the npm dependency tree even when its module URL is virtual. Resolution does not use the project working directory or a global `pi-web` command.
+
+Standalone archives without the npm package fall back to `sp-web` on PATH. Missing executables produce a warning with `SP_WEB_EXECUTABLE` setup guidance. Bun launches of the installed entry require external Node on PATH. A successful launch result records a spawned PID, not HTTP readiness.
+
+The launcher always adds `--no-open`, sets `SP_WEB_NO_OPEN=1` and `SP_TERMINAL_BRIDGE_ONLY=1`, and passes `SP_TERMINAL_BRIDGE_DISCOVERY_DIR` and `SP_TERMINAL_BRIDGE_PROTOCOL` to the child. SP Web must use the authenticated descriptors for live commands, never construct another writer for the same session.
 
-The launcher always adds `--no-open`, sets `PI_WEB_NO_OPEN=1`, and passes `SP_TERMINAL_BRIDGE_DISCOVERY_DIR` and `SP_TERMINAL_BRIDGE_PROTOCOL` to the child. A bridge-aware pi-web build must use the descriptors for live commands. Stock pi-web versions that ignore these variables cannot safely control a live terminal session.
+The canonical process record is `sp-web-sidecar.json`. Live records under either that name or `pi-web-sidecar.json` are reused without rewriting them or restarting their processes. The cooperative lock remains `pi-web-sidecar.lock`; new launches also mirror their private PID record to `pi-web-sidecar.json` so older launchers reuse them. Both process records are `0600` and neither represents a session writer. This launcher migration does not change writer leases, IPC authentication, question ownership, or historical JSONL.

package/node_modules/@senpiper/sp-agent-extensions/dist/ask-user.d.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ToolDefinition } from "@senpiper/pi-coding-agent";
 import { type Static, Type } from "typebox";
+import { QuestionInteraction } from "./question-interaction.ts";
 export declare const MAX_QUESTIONS = 4;
 export declare const MIN_OPTIONS = 2;
 export declare const MAX_OPTIONS = 4;
@@ -68,7 +69,7 @@ export declare function buildAskUserQuestionResponse(details: AskUserQuestionToo
     }[];
     details: AskUserQuestionToolDetails;
 };
-export declare function createAskUserQuestionToolDefinition(): ToolDefinition<typeof AskUserSchema, AskUserQuestionToolDetails>;
+export declare function createAskUserQuestionToolDefinition(interaction?: QuestionInteraction): ToolDefinition<typeof AskUserSchema, AskUserQuestionToolDetails>;
 export declare function registerAskUserQuestion(pi: ExtensionAPI): void;
 export {};
 //# sourceMappingURL=ask-user.d.ts.map

package/node_modules/@senpiper/sp-agent-extensions/dist/ask-user.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ask-user.d.ts","sourceRoot":"","sources":["../src/ask-user.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAoB,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhG,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE5C,eAAO,MAAM,aAAa,IAAI,CAAC;AAC/B,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AASnC,eAAO,MAAM,mBAAmB;;;;EAI9B,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;EAKhC,CAAC;AAEH,eAAO,MAAM,aAAa;;;;;;;;;;;EAExB,CAAC;AAEH,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AACpE,MAAM,MAAM,oBAAoB,GAC7B,OAAO,GACP,SAAS,GACT,cAAc,GACd,oBAAoB,GACpB,kBAAkB,GAClB,gBAAgB,GAChB,oBAAoB,GACpB,wBAAwB,GACxB,gBAAgB,GAChB,mBAAmB,CAAC;AAEvB,MAAM,WAAW,qBAAqB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,0BAA0B;IAC1C,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,WAAW,CAAC,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D;AAED,KAAK,gBAAgB,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,wBAAwB,CAAA;CAAE,GAC7C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAQ/D,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAyFhF;AAwED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,0BAA0B;;;;;;EAU/E;AAED,wBAAgB,mCAAmC,IAAI,cAAc,CACpE,OAAO,aAAa,EACpB,0BAA0B,CAC1B,CA0EA;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,YAAY,QAEvD","sourcesContent":["import type { ExtensionAPI, ExtensionContext, ToolDefinition } from \"@senpiper/pi-coding-agent\";\nimport { Text } from \"@senpiper/pi-coding-agent/runtime-deps\";\nimport { type Static, Type } from \"typebox\";\n\nexport const MAX_QUESTIONS = 4;\nexport const MIN_OPTIONS = 2;\nexport const MAX_OPTIONS = 4;\nexport const MAX_HEADER_LENGTH = 16;\nexport const MAX_LABEL_LENGTH = 60;\n\nconst CUSTOM_ANSWER = \"Type something.\";\nconst RESERVED_LABELS = new Set([\"Other\", CUSTOM_ANSWER, \"Next\"]);\nconst DECLINE_MESSAGE = \"User declined to answer questions\";\nconst ENVELOPE_PREFIX = \"User has answered your questions:\";\nconst ENVELOPE_SUFFIX = \"You can now continue with the user's answers in mind.\";\nconst NO_INPUT = \"(no input)\";\n\nexport const AskUserOptionSchema = Type.Object({\n\tlabel: Type.String({ minLength: 1, maxLength: MAX_LABEL_LENGTH }),\n\tdescription: Type.String({ minLength: 1 }),\n\tpreview: Type.Optional(Type.String()),\n});\n\nexport const AskUserQuestionSchema = Type.Object({\n\tquestion: Type.String({ minLength: 1 }),\n\theader: Type.Optional(Type.String({ minLength: 1, maxLength: MAX_HEADER_LENGTH })),\n\toptions: Type.Array(AskUserOptionSchema, { minItems: MIN_OPTIONS, maxItems: MAX_OPTIONS }),\n\tmultiSelect: Type.Optional(Type.Boolean()),\n});\n\nexport const AskUserSchema = Type.Object({\n\tquestions: Type.Array(AskUserQuestionSchema, { minItems: 1, maxItems: MAX_QUESTIONS }),\n});\n\nexport type AskUserQuestionToolInput = Static<typeof AskUserSchema>;\nexport type AskUserQuestionError =\n\t| \"no_ui\"\n\t| \"aborted\"\n\t| \"no_questions\"\n\t| \"too_many_questions\"\n\t| \"invalid_question\"\n\t| \"invalid_option\"\n\t| \"duplicate_question\"\n\t| \"duplicate_option_label\"\n\t| \"reserved_label\"\n\t| \"invalid_selection\";\n\nexport interface AskUserQuestionAnswer {\n\tquestionIndex: number;\n\tquestion: string;\n\tkind: \"option\" | \"custom\" | \"multi\";\n\tanswer: string | null;\n\tselected?: string[];\n\tnotes?: string;\n\tpreview?: string;\n}\n\nexport interface AskUserQuestionToolDetails {\n\tanswers: AskUserQuestionAnswer[];\n\tcancelled: boolean;\n\terror?: AskUserQuestionError;\n\tcancelledAt?: { questionIndex: number; question: string };\n}\n\ntype ValidationResult =\n\t| { ok: true; value: AskUserQuestionToolInput }\n\t| { ok: false; error: AskUserQuestionError; message: string };\n\ntype JsonRecord = Record<string, unknown>;\n\nfunction isRecord(value: unknown): value is JsonRecord {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nexport function validateAskUserQuestionEnvelope(value: unknown): ValidationResult {\n\tif (!isRecord(value) || !Array.isArray(value.questions) || value.questions.length === 0) {\n\t\treturn { ok: false, error: \"no_questions\", message: \"Error: At least one question is required\" };\n\t}\n\tif (value.questions.length > MAX_QUESTIONS) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\terror: \"too_many_questions\",\n\t\t\tmessage: `Error: At most ${MAX_QUESTIONS} questions are allowed`,\n\t\t};\n\t}\n\n\tconst questions: AskUserQuestionToolInput[\"questions\"] = [];\n\tconst questionTexts = new Set<string>();\n\tfor (const rawQuestion of value.questions) {\n\t\tif (!isRecord(rawQuestion) || typeof rawQuestion.question !== \"string\" || !rawQuestion.question.trim()) {\n\t\t\treturn { ok: false, error: \"invalid_question\", message: \"Error: Every question requires non-empty text\" };\n\t\t}\n\t\tconst question = rawQuestion.question.trim();\n\t\tif (questionTexts.has(question)) {\n\t\t\treturn { ok: false, error: \"duplicate_question\", message: \"Error: Question text must be unique\" };\n\t\t}\n\t\tquestionTexts.add(question);\n\t\tconst header = rawQuestion.header;\n\t\tif (\n\t\t\theader !== undefined &&\n\t\t\t(typeof header !== \"string\" || !header.trim() || header.trim().length > MAX_HEADER_LENGTH)\n\t\t) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: \"invalid_question\",\n\t\t\t\tmessage: `Error: Question headers must be 1-${MAX_HEADER_LENGTH} characters`,\n\t\t\t};\n\t\t}\n\t\tif (\n\t\t\t!Array.isArray(rawQuestion.options) ||\n\t\t\trawQuestion.options.length < MIN_OPTIONS ||\n\t\t\trawQuestion.options.length > MAX_OPTIONS\n\t\t) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: \"invalid_option\",\n\t\t\t\tmessage: `Error: Each question requires ${MIN_OPTIONS}-${MAX_OPTIONS} options`,\n\t\t\t};\n\t\t}\n\t\tif (rawQuestion.multiSelect !== undefined && typeof rawQuestion.multiSelect !== \"boolean\") {\n\t\t\treturn { ok: false, error: \"invalid_question\", message: \"Error: multiSelect must be a boolean\" };\n\t\t}\n\n\t\tconst labels = new Set<string>();\n\t\tconst options: AskUserQuestionToolInput[\"questions\"][number][\"options\"] = [];\n\t\tfor (const rawOption of rawQuestion.options) {\n\t\t\tif (\n\t\t\t\t!isRecord(rawOption) ||\n\t\t\t\ttypeof rawOption.label !== \"string\" ||\n\t\t\t\t!rawOption.label.trim() ||\n\t\t\t\trawOption.label.trim().length > MAX_LABEL_LENGTH ||\n\t\t\t\ttypeof rawOption.description !== \"string\" ||\n\t\t\t\t!rawOption.description.trim() ||\n\t\t\t\t(rawOption.preview !== undefined && typeof rawOption.preview !== \"string\")\n\t\t\t) {\n\t\t\t\treturn {\n\t\t\t\t\tok: false,\n\t\t\t\t\terror: \"invalid_option\",\n\t\t\t\t\tmessage: \"Error: Every option requires a valid label and description\",\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst label = rawOption.label.trim();\n\t\t\tif (RESERVED_LABELS.has(label)) {\n\t\t\t\treturn { ok: false, error: \"reserved_label\", message: `Error: Option label is reserved (${label})` };\n\t\t\t}\n\t\t\tif (labels.has(label)) {\n\t\t\t\treturn { ok: false, error: \"duplicate_option_label\", message: \"Error: Option labels must be unique\" };\n\t\t\t}\n\t\t\tlabels.add(label);\n\t\t\toptions.push({\n\t\t\t\tlabel,\n\t\t\t\tdescription: rawOption.description.trim(),\n\t\t\t\tpreview: rawOption.preview,\n\t\t\t});\n\t\t}\n\t\tquestions.push({\n\t\t\tquestion,\n\t\t\theader: typeof header === \"string\" ? header.trim() : undefined,\n\t\t\toptions,\n\t\t\tmultiSelect: rawQuestion.multiSelect,\n\t\t});\n\t}\n\treturn { ok: true, value: { questions } };\n}\n\nfunction toolResult(text: string, details: AskUserQuestionToolDetails) {\n\treturn { content: [{ type: \"text\" as const, text }], details };\n}\n\nfunction questionTitle(question: AskUserQuestionToolInput[\"questions\"][number]) {\n\tconst title = `${question.header ? `[${question.header}] ` : \"\"}${question.question}`;\n\tconst previews = question.options.flatMap((option, index) =>\n\t\toption.preview?.trim() ? [`--- ${index + 1}. ${option.label} preview ---\\n${option.preview.slice(0, 600)}`] : [],\n\t);\n\treturn previews.length > 0 ? `${title}\\n\\n${previews.join(\"\\n\\n\")}` : title;\n}\n\nfunction displayOptions(question: AskUserQuestionToolInput[\"questions\"][number]) {\n\treturn new Map(\n\t\tquestion.options.map((option, index) => [`${index + 1}. ${option.label} — ${option.description}`, option]),\n\t);\n}\n\nasync function askQuestion(\n\tctx: ExtensionContext,\n\tquestion: AskUserQuestionToolInput[\"questions\"][number],\n\tquestionIndex: number,\n): Promise<AskUserQuestionAnswer | undefined> {\n\tconst byDisplay = displayOptions(question);\n\tif (!question.multiSelect) {\n\t\tconst choice = await ctx.ui.select(questionTitle(question), [...byDisplay.keys(), CUSTOM_ANSWER]);\n\t\tif (choice === undefined) return undefined;\n\t\tif (choice === CUSTOM_ANSWER) {\n\t\t\tconst answer = await ctx.ui.input(question.question, \"Type your answer\");\n\t\t\tif (answer === undefined) return undefined;\n\t\t\treturn { questionIndex, question: question.question, kind: \"custom\", answer: answer.trim() || null };\n\t\t}\n\t\tconst option = byDisplay.get(choice);\n\t\tif (!option) return undefined;\n\t\treturn {\n\t\t\tquestionIndex,\n\t\t\tquestion: question.question,\n\t\t\tkind: \"option\",\n\t\t\tanswer: option.label,\n\t\t\tpreview: option.preview?.trim() || undefined,\n\t\t};\n\t}\n\n\tconst choices = await ctx.ui.multiSelect(questionTitle(question), [...byDisplay.keys(), CUSTOM_ANSWER]);\n\tif (choices === undefined) return undefined;\n\tconst customSelected = choices.includes(CUSTOM_ANSWER);\n\tconst selected: string[] = [];\n\tfor (const choice of choices) {\n\t\tif (choice === CUSTOM_ANSWER) continue;\n\t\tconst option = byDisplay.get(choice);\n\t\tif (!option) return undefined;\n\t\tif (!selected.includes(option.label)) selected.push(option.label);\n\t}\n\tlet notes: string | undefined;\n\tif (customSelected) {\n\t\tconst custom = await ctx.ui.input(question.question, \"Type another answer or note\");\n\t\tif (custom === undefined) return undefined;\n\t\tnotes = custom.trim() || undefined;\n\t}\n\tif (selected.length === 0 && customSelected) {\n\t\treturn { questionIndex, question: question.question, kind: \"custom\", answer: notes ?? null };\n\t}\n\treturn { questionIndex, question: question.question, kind: \"multi\", answer: null, selected, notes };\n}\n\nfunction answerScalar(answer: AskUserQuestionAnswer) {\n\tif (answer.kind === \"multi\") return answer.selected?.length ? answer.selected.join(\", \") : NO_INPUT;\n\treturn answer.answer || NO_INPUT;\n}\n\nexport function buildAskUserQuestionResponse(details: AskUserQuestionToolDetails) {\n\tif (details.cancelled || details.answers.length === 0) return toolResult(DECLINE_MESSAGE, details);\n\tconst segments = details.answers.map((answer) => {\n\t\tconst suffixes = [\n\t\t\tanswer.preview ? `selected preview: ${answer.preview}` : undefined,\n\t\t\tanswer.notes ? `user notes: ${answer.notes}` : undefined,\n\t\t].filter((entry): entry is string => entry !== undefined);\n\t\treturn `\"${answer.question}\"=\"${answerScalar(answer)}\".${suffixes.length ? ` ${suffixes.join(\". \")}.` : \"\"}`;\n\t});\n\treturn toolResult(`${ENVELOPE_PREFIX} ${segments.join(\" \")} ${ENVELOPE_SUFFIX}`, details);\n}\n\nexport function createAskUserQuestionToolDefinition(): ToolDefinition<\n\ttypeof AskUserSchema,\n\tAskUserQuestionToolDetails\n> {\n\treturn {\n\t\tname: \"ask_user_question\",\n\t\tlabel: \"Ask User Question\",\n\t\tdescription:\n\t\t\t\"Ask the user up to four structured questions with single-select, multi-select, custom answers, and optional markdown previews.\",\n\t\tpromptSnippet: `Ask up to ${MAX_QUESTIONS} structured questions when requirements are ambiguous`,\n\t\tpromptGuidelines: [\n\t\t\t\"Use ask_user_question when concrete user decisions are required before implementation.\",\n\t\t\t`Group related questions into one ask_user_question call and provide ${MIN_OPTIONS}-${MAX_OPTIONS} concise options for each.`,\n\t\t\t\"Use multiSelect when choices are not mutually exclusive, and use option previews for code, configuration, or layout comparisons.\",\n\t\t],\n\t\tparameters: AskUserSchema,\n\t\texecutionMode: \"sequential\",\n\t\tasync execute(_toolCallId, params, signal, _onUpdate, ctx) {\n\t\t\tif (!ctx.hasUI) {\n\t\t\t\treturn toolResult(\"UI is unavailable; ask the questions in plain chat text.\", {\n\t\t\t\t\tanswers: [],\n\t\t\t\t\tcancelled: true,\n\t\t\t\t\terror: \"no_ui\",\n\t\t\t\t});\n\t\t\t}\n\t\t\tconst validation = validateAskUserQuestionEnvelope(params);\n\t\t\tif (!validation.ok) {\n\t\t\t\treturn toolResult(validation.message, {\n\t\t\t\t\tanswers: [],\n\t\t\t\t\tcancelled: true,\n\t\t\t\t\terror: validation.error,\n\t\t\t\t});\n\t\t\t}\n\t\t\tconst answers: AskUserQuestionAnswer[] = [];\n\t\t\tfor (const [questionIndex, question] of validation.value.questions.entries()) {\n\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\treturn toolResult(\"The questionnaire was aborted.\", {\n\t\t\t\t\t\tanswers,\n\t\t\t\t\t\tcancelled: true,\n\t\t\t\t\t\terror: \"aborted\",\n\t\t\t\t\t\tcancelledAt: { questionIndex, question: question.question },\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\tconst answer = await askQuestion(ctx, question, questionIndex);\n\t\t\t\tif (!answer) {\n\t\t\t\t\treturn buildAskUserQuestionResponse({\n\t\t\t\t\t\tanswers,\n\t\t\t\t\t\tcancelled: true,\n\t\t\t\t\t\tcancelledAt: { questionIndex, question: question.question },\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\tanswers.push(answer);\n\t\t\t}\n\t\t\treturn buildAskUserQuestionResponse({ answers, cancelled: false });\n\t\t},\n\t\trenderCall(args, theme) {\n\t\t\tconst count = Array.isArray(args.questions) ? args.questions.length : 0;\n\t\t\treturn new Text(\n\t\t\t\t`${theme.fg(\"toolTitle\", theme.bold(\"ask_user_question \"))}${theme.fg(\"muted\", `${count} question${count === 1 ? \"\" : \"s\"}`)}`,\n\t\t\t\t0,\n\t\t\t\t0,\n\t\t\t);\n\t\t},\n\t\trenderResult(result, _options, theme) {\n\t\t\tif (result.details.cancelled) {\n\t\t\t\tconst at = result.details.cancelledAt ? ` at question ${result.details.cancelledAt.questionIndex + 1}` : \"\";\n\t\t\t\treturn new Text(theme.fg(\"warning\", `Questionnaire cancelled${at}`), 0, 0);\n\t\t\t}\n\t\t\treturn new Text(\n\t\t\t\tresult.details.answers\n\t\t\t\t\t.map((answer) => `${theme.fg(\"success\", \"✓\")} ${answer.question}: ${answerScalar(answer)}`)\n\t\t\t\t\t.join(\"\\n\"),\n\t\t\t\t0,\n\t\t\t\t0,\n\t\t\t);\n\t\t},\n\t};\n}\n\nexport function registerAskUserQuestion(pi: ExtensionAPI) {\n\tpi.registerTool(createAskUserQuestionToolDefinition());\n}\n"]}
+{"version":3,"file":"ask-user.d.ts","sourceRoot":"","sources":["../src/ask-user.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAoB,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhG,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAA0B,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAExF,eAAO,MAAM,aAAa,IAAI,CAAC;AAC/B,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AASnC,eAAO,MAAM,mBAAmB;;;;EAI9B,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;EAKhC,CAAC;AAEH,eAAO,MAAM,aAAa;;;;;;;;;;;EAExB,CAAC;AAEH,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AACpE,MAAM,MAAM,oBAAoB,GAC7B,OAAO,GACP,SAAS,GACT,cAAc,GACd,oBAAoB,GACpB,kBAAkB,GAClB,gBAAgB,GAChB,oBAAoB,GACpB,wBAAwB,GACxB,gBAAgB,GAChB,mBAAmB,CAAC;AAEvB,MAAM,WAAW,qBAAqB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,0BAA0B;IAC1C,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,WAAW,CAAC,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D;AAED,KAAK,gBAAgB,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,wBAAwB,CAAA;CAAE,GAC7C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAQ/D,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAyFhF;AA0ED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,0BAA0B;;;;;;EAU/E;AAED,wBAAgB,mCAAmC,CAClD,WAAW,sBAA4B,GACrC,cAAc,CAAC,OAAO,aAAa,EAAE,0BAA0B,CAAC,CAuFlE;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,YAAY,QAKvD","sourcesContent":["import type { ExtensionAPI, ExtensionContext, ToolDefinition } from \"@senpiper/pi-coding-agent\";\nimport { Text } from \"@senpiper/pi-coding-agent/runtime-deps\";\nimport { type Static, Type } from \"typebox\";\nimport { getQuestionInteraction, QuestionInteraction } from \"./question-interaction.ts\";\n\nexport const MAX_QUESTIONS = 4;\nexport const MIN_OPTIONS = 2;\nexport const MAX_OPTIONS = 4;\nexport const MAX_HEADER_LENGTH = 16;\nexport const MAX_LABEL_LENGTH = 60;\n\nconst CUSTOM_ANSWER = \"Type something.\";\nconst RESERVED_LABELS = new Set([\"Other\", CUSTOM_ANSWER, \"Next\"]);\nconst DECLINE_MESSAGE = \"User declined to answer questions\";\nconst ENVELOPE_PREFIX = \"User has answered your questions:\";\nconst ENVELOPE_SUFFIX = \"You can now continue with the user's answers in mind.\";\nconst NO_INPUT = \"(no input)\";\n\nexport const AskUserOptionSchema = Type.Object({\n\tlabel: Type.String({ minLength: 1, maxLength: MAX_LABEL_LENGTH }),\n\tdescription: Type.String({ minLength: 1 }),\n\tpreview: Type.Optional(Type.String()),\n});\n\nexport const AskUserQuestionSchema = Type.Object({\n\tquestion: Type.String({ minLength: 1 }),\n\theader: Type.Optional(Type.String({ minLength: 1, maxLength: MAX_HEADER_LENGTH })),\n\toptions: Type.Array(AskUserOptionSchema, { minItems: MIN_OPTIONS, maxItems: MAX_OPTIONS }),\n\tmultiSelect: Type.Optional(Type.Boolean()),\n});\n\nexport const AskUserSchema = Type.Object({\n\tquestions: Type.Array(AskUserQuestionSchema, { minItems: 1, maxItems: MAX_QUESTIONS }),\n});\n\nexport type AskUserQuestionToolInput = Static<typeof AskUserSchema>;\nexport type AskUserQuestionError =\n\t| \"no_ui\"\n\t| \"aborted\"\n\t| \"no_questions\"\n\t| \"too_many_questions\"\n\t| \"invalid_question\"\n\t| \"invalid_option\"\n\t| \"duplicate_question\"\n\t| \"duplicate_option_label\"\n\t| \"reserved_label\"\n\t| \"invalid_selection\";\n\nexport interface AskUserQuestionAnswer {\n\tquestionIndex: number;\n\tquestion: string;\n\tkind: \"option\" | \"custom\" | \"multi\";\n\tanswer: string | null;\n\tselected?: string[];\n\tnotes?: string;\n\tpreview?: string;\n}\n\nexport interface AskUserQuestionToolDetails {\n\tanswers: AskUserQuestionAnswer[];\n\tcancelled: boolean;\n\terror?: AskUserQuestionError;\n\tcancelledAt?: { questionIndex: number; question: string };\n}\n\ntype ValidationResult =\n\t| { ok: true; value: AskUserQuestionToolInput }\n\t| { ok: false; error: AskUserQuestionError; message: string };\n\ntype JsonRecord = Record<string, unknown>;\n\nfunction isRecord(value: unknown): value is JsonRecord {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nexport function validateAskUserQuestionEnvelope(value: unknown): ValidationResult {\n\tif (!isRecord(value) || !Array.isArray(value.questions) || value.questions.length === 0) {\n\t\treturn { ok: false, error: \"no_questions\", message: \"Error: At least one question is required\" };\n\t}\n\tif (value.questions.length > MAX_QUESTIONS) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\terror: \"too_many_questions\",\n\t\t\tmessage: `Error: At most ${MAX_QUESTIONS} questions are allowed`,\n\t\t};\n\t}\n\n\tconst questions: AskUserQuestionToolInput[\"questions\"] = [];\n\tconst questionTexts = new Set<string>();\n\tfor (const rawQuestion of value.questions) {\n\t\tif (!isRecord(rawQuestion) || typeof rawQuestion.question !== \"string\" || !rawQuestion.question.trim()) {\n\t\t\treturn { ok: false, error: \"invalid_question\", message: \"Error: Every question requires non-empty text\" };\n\t\t}\n\t\tconst question = rawQuestion.question.trim();\n\t\tif (questionTexts.has(question)) {\n\t\t\treturn { ok: false, error: \"duplicate_question\", message: \"Error: Question text must be unique\" };\n\t\t}\n\t\tquestionTexts.add(question);\n\t\tconst header = rawQuestion.header;\n\t\tif (\n\t\t\theader !== undefined &&\n\t\t\t(typeof header !== \"string\" || !header.trim() || header.trim().length > MAX_HEADER_LENGTH)\n\t\t) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: \"invalid_question\",\n\t\t\t\tmessage: `Error: Question headers must be 1-${MAX_HEADER_LENGTH} characters`,\n\t\t\t};\n\t\t}\n\t\tif (\n\t\t\t!Array.isArray(rawQuestion.options) ||\n\t\t\trawQuestion.options.length < MIN_OPTIONS ||\n\t\t\trawQuestion.options.length > MAX_OPTIONS\n\t\t) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: \"invalid_option\",\n\t\t\t\tmessage: `Error: Each question requires ${MIN_OPTIONS}-${MAX_OPTIONS} options`,\n\t\t\t};\n\t\t}\n\t\tif (rawQuestion.multiSelect !== undefined && typeof rawQuestion.multiSelect !== \"boolean\") {\n\t\t\treturn { ok: false, error: \"invalid_question\", message: \"Error: multiSelect must be a boolean\" };\n\t\t}\n\n\t\tconst labels = new Set<string>();\n\t\tconst options: AskUserQuestionToolInput[\"questions\"][number][\"options\"] = [];\n\t\tfor (const rawOption of rawQuestion.options) {\n\t\t\tif (\n\t\t\t\t!isRecord(rawOption) ||\n\t\t\t\ttypeof rawOption.label !== \"string\" ||\n\t\t\t\t!rawOption.label.trim() ||\n\t\t\t\trawOption.label.trim().length > MAX_LABEL_LENGTH ||\n\t\t\t\ttypeof rawOption.description !== \"string\" ||\n\t\t\t\t!rawOption.description.trim() ||\n\t\t\t\t(rawOption.preview !== undefined && typeof rawOption.preview !== \"string\")\n\t\t\t) {\n\t\t\t\treturn {\n\t\t\t\t\tok: false,\n\t\t\t\t\terror: \"invalid_option\",\n\t\t\t\t\tmessage: \"Error: Every option requires a valid label and description\",\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst label = rawOption.label.trim();\n\t\t\tif (RESERVED_LABELS.has(label)) {\n\t\t\t\treturn { ok: false, error: \"reserved_label\", message: `Error: Option label is reserved (${label})` };\n\t\t\t}\n\t\t\tif (labels.has(label)) {\n\t\t\t\treturn { ok: false, error: \"duplicate_option_label\", message: \"Error: Option labels must be unique\" };\n\t\t\t}\n\t\t\tlabels.add(label);\n\t\t\toptions.push({\n\t\t\t\tlabel,\n\t\t\t\tdescription: rawOption.description.trim(),\n\t\t\t\tpreview: rawOption.preview,\n\t\t\t});\n\t\t}\n\t\tquestions.push({\n\t\t\tquestion,\n\t\t\theader: typeof header === \"string\" ? header.trim() : undefined,\n\t\t\toptions,\n\t\t\tmultiSelect: rawQuestion.multiSelect,\n\t\t});\n\t}\n\treturn { ok: true, value: { questions } };\n}\n\nfunction toolResult(text: string, details: AskUserQuestionToolDetails) {\n\treturn { content: [{ type: \"text\" as const, text }], details };\n}\n\nfunction questionTitle(question: AskUserQuestionToolInput[\"questions\"][number]) {\n\tconst title = `${question.header ? `[${question.header}] ` : \"\"}${question.question}`;\n\tconst previews = question.options.flatMap((option, index) =>\n\t\toption.preview?.trim() ? [`--- ${index + 1}. ${option.label} preview ---\\n${option.preview.slice(0, 600)}`] : [],\n\t);\n\treturn previews.length > 0 ? `${title}\\n\\n${previews.join(\"\\n\\n\")}` : title;\n}\n\nfunction displayOptions(question: AskUserQuestionToolInput[\"questions\"][number]) {\n\treturn new Map(\n\t\tquestion.options.map((option, index) => [`${index + 1}. ${option.label} — ${option.description}`, option]),\n\t);\n}\n\nasync function askQuestion(\n\tctx: ExtensionContext,\n\tquestion: AskUserQuestionToolInput[\"questions\"][number],\n\tquestionIndex: number,\n\tsignal: AbortSignal,\n): Promise<AskUserQuestionAnswer | undefined> {\n\tif (signal.aborted) return undefined;\n\tconst byDisplay = displayOptions(question);\n\tif (!question.multiSelect) {\n\t\tconst choice = await ctx.ui.select(questionTitle(question), [...byDisplay.keys(), CUSTOM_ANSWER], { signal });\n\t\tif (signal.aborted || choice === undefined) return undefined;\n\t\tif (choice === CUSTOM_ANSWER) {\n\t\t\tconst answer = await ctx.ui.input(question.question, \"Type your answer\", { signal });\n\t\t\tif (signal.aborted || answer === undefined) return undefined;\n\t\t\treturn { questionIndex, question: question.question, kind: \"custom\", answer: answer.trim() || null };\n\t\t}\n\t\tconst option = byDisplay.get(choice);\n\t\tif (!option) return undefined;\n\t\treturn {\n\t\t\tquestionIndex,\n\t\t\tquestion: question.question,\n\t\t\tkind: \"option\",\n\t\t\tanswer: option.label,\n\t\t\tpreview: option.preview?.trim() || undefined,\n\t\t};\n\t}\n\n\tconst choices = await ctx.ui.multiSelect(questionTitle(question), [...byDisplay.keys(), CUSTOM_ANSWER], { signal });\n\tif (signal.aborted || choices === undefined) return undefined;\n\tconst customSelected = choices.includes(CUSTOM_ANSWER);\n\tconst selected: string[] = [];\n\tfor (const choice of choices) {\n\t\tif (choice === CUSTOM_ANSWER) continue;\n\t\tconst option = byDisplay.get(choice);\n\t\tif (!option) return undefined;\n\t\tif (!selected.includes(option.label)) selected.push(option.label);\n\t}\n\tlet notes: string | undefined;\n\tif (customSelected) {\n\t\tconst custom = await ctx.ui.input(question.question, \"Type another answer or note\", { signal });\n\t\tif (signal.aborted || custom === undefined) return undefined;\n\t\tnotes = custom.trim() || undefined;\n\t}\n\tif (selected.length === 0 && customSelected) {\n\t\treturn { questionIndex, question: question.question, kind: \"custom\", answer: notes ?? null };\n\t}\n\treturn { questionIndex, question: question.question, kind: \"multi\", answer: null, selected, notes };\n}\n\nfunction answerScalar(answer: AskUserQuestionAnswer) {\n\tif (answer.kind === \"multi\") return answer.selected?.length ? answer.selected.join(\", \") : NO_INPUT;\n\treturn answer.answer || NO_INPUT;\n}\n\nexport function buildAskUserQuestionResponse(details: AskUserQuestionToolDetails) {\n\tif (details.cancelled || details.answers.length === 0) return toolResult(DECLINE_MESSAGE, details);\n\tconst segments = details.answers.map((answer) => {\n\t\tconst suffixes = [\n\t\t\tanswer.preview ? `selected preview: ${answer.preview}` : undefined,\n\t\t\tanswer.notes ? `user notes: ${answer.notes}` : undefined,\n\t\t].filter((entry): entry is string => entry !== undefined);\n\t\treturn `\"${answer.question}\"=\"${answerScalar(answer)}\".${suffixes.length ? ` ${suffixes.join(\". \")}.` : \"\"}`;\n\t});\n\treturn toolResult(`${ENVELOPE_PREFIX} ${segments.join(\" \")} ${ENVELOPE_SUFFIX}`, details);\n}\n\nexport function createAskUserQuestionToolDefinition(\n\tinteraction = new QuestionInteraction(),\n): ToolDefinition<typeof AskUserSchema, AskUserQuestionToolDetails> {\n\treturn {\n\t\tname: \"ask_user_question\",\n\t\tlabel: \"Ask User Question\",\n\t\tdescription:\n\t\t\t\"Ask the user up to four structured questions with single-select, multi-select, custom answers, and optional markdown previews.\",\n\t\tpromptSnippet: `Ask up to ${MAX_QUESTIONS} structured questions when requirements are ambiguous`,\n\t\tpromptGuidelines: [\n\t\t\t\"Use ask_user_question when concrete user decisions are required before implementation.\",\n\t\t\t`Group related questions into one ask_user_question call and provide ${MIN_OPTIONS}-${MAX_OPTIONS} concise options for each.`,\n\t\t\t\"Use multiSelect when choices are not mutually exclusive, and use option previews for code, configuration, or layout comparisons.\",\n\t\t],\n\t\tparameters: AskUserSchema,\n\t\texecutionMode: \"sequential\",\n\t\tasync execute(toolCallId, params, signal, _onUpdate, ctx) {\n\t\t\tif (!ctx.hasUI) {\n\t\t\t\treturn toolResult(\"UI is unavailable; ask the questions in plain chat text.\", {\n\t\t\t\t\tanswers: [],\n\t\t\t\t\tcancelled: true,\n\t\t\t\t\terror: \"no_ui\",\n\t\t\t\t});\n\t\t\t}\n\t\t\tconst validation = validateAskUserQuestionEnvelope(params);\n\t\t\tif (!validation.ok) {\n\t\t\t\treturn toolResult(validation.message, {\n\t\t\t\t\tanswers: [],\n\t\t\t\t\tcancelled: true,\n\t\t\t\t\terror: validation.error,\n\t\t\t\t});\n\t\t\t}\n\t\t\tconst answers: AskUserQuestionAnswer[] = [];\n\t\t\tconst controller = interaction.begin();\n\t\t\tconst combinedSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;\n\t\t\ttry {\n\t\t\t\tfor (const [questionIndex, question] of validation.value.questions.entries()) {\n\t\t\t\t\tif (combinedSignal.aborted) {\n\t\t\t\t\t\treturn toolResult(\"The questionnaire was aborted.\", {\n\t\t\t\t\t\t\tanswers,\n\t\t\t\t\t\t\tcancelled: true,\n\t\t\t\t\t\t\terror: \"aborted\",\n\t\t\t\t\t\t\tcancelledAt: { questionIndex, question: question.question },\n\t\t\t\t\t\t});\n\t\t\t\t\t}\n\t\t\t\t\tconst outcome = await interaction.ask(\n\t\t\t\t\t\t{ toolCallId, questionIndex, questionCount: validation.value.questions.length, question },\n\t\t\t\t\t\tctx,\n\t\t\t\t\t\tcombinedSignal,\n\t\t\t\t\t\t(dialogSignal) => askQuestion(ctx, question, questionIndex, dialogSignal),\n\t\t\t\t\t);\n\t\t\t\t\tconst answer = outcome.answer;\n\t\t\t\t\tif (!answer) {\n\t\t\t\t\t\treturn buildAskUserQuestionResponse({\n\t\t\t\t\t\t\tanswers,\n\t\t\t\t\t\t\tcancelled: true,\n\t\t\t\t\t\t\t...(outcome.aborted ? { error: \"aborted\" as const } : {}),\n\t\t\t\t\t\t\tcancelledAt: { questionIndex, question: question.question },\n\t\t\t\t\t\t});\n\t\t\t\t\t}\n\t\t\t\t\tanswers.push(answer);\n\t\t\t\t}\n\t\t\t\treturn buildAskUserQuestionResponse({ answers, cancelled: false });\n\t\t\t} finally {\n\t\t\t\tinteraction.end(controller);\n\t\t\t}\n\t\t},\n\t\trenderCall(args, theme) {\n\t\t\tconst count = Array.isArray(args.questions) ? args.questions.length : 0;\n\t\t\treturn new Text(\n\t\t\t\t`${theme.fg(\"toolTitle\", theme.bold(\"ask_user_question \"))}${theme.fg(\"muted\", `${count} question${count === 1 ? \"\" : \"s\"}`)}`,\n\t\t\t\t0,\n\t\t\t\t0,\n\t\t\t);\n\t\t},\n\t\trenderResult(result, _options, theme) {\n\t\t\tif (result.details.cancelled) {\n\t\t\t\tconst at = result.details.cancelledAt ? ` at question ${result.details.cancelledAt.questionIndex + 1}` : \"\";\n\t\t\t\treturn new Text(theme.fg(\"warning\", `Questionnaire cancelled${at}`), 0, 0);\n\t\t\t}\n\t\t\treturn new Text(\n\t\t\t\tresult.details.answers\n\t\t\t\t\t.map((answer) => `${theme.fg(\"success\", \"✓\")} ${answer.question}: ${answerScalar(answer)}`)\n\t\t\t\t\t.join(\"\\n\"),\n\t\t\t\t0,\n\t\t\t\t0,\n\t\t\t);\n\t\t},\n\t};\n}\n\nexport function registerAskUserQuestion(pi: ExtensionAPI) {\n\tconst interaction = getQuestionInteraction(pi);\n\tpi.registerTool(createAskUserQuestionToolDefinition(interaction));\n\tpi.on(\"session_shutdown\", () => interaction.cancel());\n\tpi.on(\"session_start\", () => interaction.cancel());\n}\n"]}

package/node_modules/@senpiper/sp-agent-extensions/dist/ask-user.js

@@ -1,5 +1,6 @@
 import { Text } from "@senpiper/pi-coding-agent/runtime-deps";
 import { Type } from "typebox";
+import { getQuestionInteraction, QuestionInteraction } from "./question-interaction.js";
 export const MAX_QUESTIONS = 4;
 export const MIN_OPTIONS = 2;
 export const MAX_OPTIONS = 4;
@@ -121,15 +122,17 @@ function questionTitle(question) {
 function displayOptions(question) {
     return new Map(question.options.map((option, index) => [`${index + 1}. ${option.label} — ${option.description}`, option]));
 }
-async function askQuestion(ctx, question, questionIndex) {
+async function askQuestion(ctx, question, questionIndex, signal) {
+    if (signal.aborted)
+        return undefined;
     const byDisplay = displayOptions(question);
     if (!question.multiSelect) {
-        const choice = await ctx.ui.select(questionTitle(question), [...byDisplay.keys(), CUSTOM_ANSWER]);
-        if (choice === undefined)
+        const choice = await ctx.ui.select(questionTitle(question), [...byDisplay.keys(), CUSTOM_ANSWER], { signal });
+        if (signal.aborted || choice === undefined)
             return undefined;
         if (choice === CUSTOM_ANSWER) {
-            const answer = await ctx.ui.input(question.question, "Type your answer");
-            if (answer === undefined)
+            const answer = await ctx.ui.input(question.question, "Type your answer", { signal });
+            if (signal.aborted || answer === undefined)
                 return undefined;
             return { questionIndex, question: question.question, kind: "custom", answer: answer.trim() || null };
         }
@@ -144,8 +147,8 @@ async function askQuestion(ctx, question, questionIndex) {
             preview: option.preview?.trim() || undefined,
         };
     }
-    const choices = await ctx.ui.multiSelect(questionTitle(question), [...byDisplay.keys(), CUSTOM_ANSWER]);
-    if (choices === undefined)
+    const choices = await ctx.ui.multiSelect(questionTitle(question), [...byDisplay.keys(), CUSTOM_ANSWER], { signal });
+    if (signal.aborted || choices === undefined)
         return undefined;
     const customSelected = choices.includes(CUSTOM_ANSWER);
     const selected = [];
@@ -160,8 +163,8 @@ async function askQuestion(ctx, question, questionIndex) {
     }
     let notes;
     if (customSelected) {
-        const custom = await ctx.ui.input(question.question, "Type another answer or note");
-        if (custom === undefined)
+        const custom = await ctx.ui.input(question.question, "Type another answer or note", { signal });
+        if (signal.aborted || custom === undefined)
             return undefined;
         notes = custom.trim() || undefined;
     }
@@ -187,7 +190,7 @@ export function buildAskUserQuestionResponse(details) {
     });
     return toolResult(`${ENVELOPE_PREFIX} ${segments.join(" ")} ${ENVELOPE_SUFFIX}`, details);
 }
-export function createAskUserQuestionToolDefinition() {
+export function createAskUserQuestionToolDefinition(interaction = new QuestionInteraction()) {
     return {
         name: "ask_user_question",
         label: "Ask User Question",
@@ -200,7 +203,7 @@ export function createAskUserQuestionToolDefinition() {
         ],
         parameters: AskUserSchema,
         executionMode: "sequential",
-        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+        async execute(toolCallId, params, signal, _onUpdate, ctx) {
             if (!ctx.hasUI) {
                 return toolResult("UI is unavailable; ask the questions in plain chat text.", {
                     answers: [],
@@ -217,26 +220,35 @@ export function createAskUserQuestionToolDefinition() {
                 });
             }
             const answers = [];
-            for (const [questionIndex, question] of validation.value.questions.entries()) {
-                if (signal?.aborted) {
-                    return toolResult("The questionnaire was aborted.", {
-                        answers,
-                        cancelled: true,
-                        error: "aborted",
-                        cancelledAt: { questionIndex, question: question.question },
-                    });
-                }
-                const answer = await askQuestion(ctx, question, questionIndex);
-                if (!answer) {
-                    return buildAskUserQuestionResponse({
-                        answers,
-                        cancelled: true,
-                        cancelledAt: { questionIndex, question: question.question },
-                    });
+            const controller = interaction.begin();
+            const combinedSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+            try {
+                for (const [questionIndex, question] of validation.value.questions.entries()) {
+                    if (combinedSignal.aborted) {
+                        return toolResult("The questionnaire was aborted.", {
+                            answers,
+                            cancelled: true,
+                            error: "aborted",
+                            cancelledAt: { questionIndex, question: question.question },
+                        });
+                    }
+                    const outcome = await interaction.ask({ toolCallId, questionIndex, questionCount: validation.value.questions.length, question }, ctx, combinedSignal, (dialogSignal) => askQuestion(ctx, question, questionIndex, dialogSignal));
+                    const answer = outcome.answer;
+                    if (!answer) {
+                        return buildAskUserQuestionResponse({
+                            answers,
+                            cancelled: true,
+                            ...(outcome.aborted ? { error: "aborted" } : {}),
+                            cancelledAt: { questionIndex, question: question.question },
+                        });
+                    }
+                    answers.push(answer);
                 }
-                answers.push(answer);
+                return buildAskUserQuestionResponse({ answers, cancelled: false });
+            }
+            finally {
+                interaction.end(controller);
             }
-            return buildAskUserQuestionResponse({ answers, cancelled: false });
         },
         renderCall(args, theme) {
             const count = Array.isArray(args.questions) ? args.questions.length : 0;
@@ -254,6 +266,9 @@ export function createAskUserQuestionToolDefinition() {
     };
 }
 export function registerAskUserQuestion(pi) {
-    pi.registerTool(createAskUserQuestionToolDefinition());
+    const interaction = getQuestionInteraction(pi);
+    pi.registerTool(createAskUserQuestionToolDefinition(interaction));
+    pi.on("session_shutdown", () => interaction.cancel());
+    pi.on("session_start", () => interaction.cancel());
 }
 //# sourceMappingURL=ask-user.js.map