@zetaloop/chappie 0.2.0 → 0.3.0

package/README.md

@@ -1,16 +1,16 @@
 # Chappie
 
-Use ChatGPT to edit files, run commands, and work with [Pi](https://github.com/earendil-works/pi) extensions. Supports multiple Pi sessions, images, and two-way file transfers.
+Use ChatGPT to work through [Pi](https://github.com/earendil-works/pi): edit local files, run commands, call Pi extensions, exchange files and images, and move between sessions on one or more devices.
 
 ## Setup
 
-Install through Pi:
+Install the Pi package:
 
 ```sh
 pi install npm:@zetaloop/chappie
 ```
 
-Add Chappie to your [otunnel](https://github.com/zetaloop/otunnel) configuration:
+Run Chappie as the MCP server managed by [otunnel](https://github.com/zetaloop/otunnel):
 
 ```yaml
 mcp:
@@ -19,16 +19,36 @@ mcp:
       command: pi --chappie
 ```
 
-Start otunnel with this configuration and add its tunnel as a developer-mode app in ChatGPT. Run Pi in your project:
+Add the tunnel as a developer-mode app in ChatGPT, then start Pi in a project:
 
 ```sh
 pi --provider chappie --model chatgpt
 ```
 
-Open Pi with the Chappie provider, then ask ChatGPT to call `init`. Chappie pairs the chat with an online Pi session; the first remote operation starts its turn.
+Call `init` from ChatGPT to connect the conversation to Pi. A conversation can resume an existing task with its Pi session ID, while `sessions` can find connected sessions by device, directory, or name.
 
 ## Usage
 
-Ask ChatGPT to work on the task using Chappie's tools. `chat` sends replies to Pi, and new Pi messages accompany subsequent tool results. Interactive tools display their prompts in Pi.
+Chappie exposes common coding tools directly and every active Pi tool through `tools` and `call`. `chat` sends an assistant message to Pi, Pi input accompanies later tool results, and `transfer` moves files in either direction. `ask` can present a persistent question in ChatGPT when webpage questions are enabled.
 
-See the [tool guide](docs/tools.md) for session selection, batch calls, messages, and file and image transfers.
+See the [tool guide](docs/tools.md) for session selection, Pi tools, webpage questions, and file transfer.
+
+## Configuration
+
+`chappie.json` in Pi's agent directory configures Chappie.
+
+A broker can accept Pi sessions from other devices on the local network:
+
+```json
+{ "listen": true }
+```
+
+Remote Pi sessions connect through the broker device's mDNS name:
+
+```json
+{ "connect": "<broker>.local" }
+```
+
+The default port is `24274`. Set `listen` to a port number or append `:port` to `connect` to use another one. Only the broker device runs otunnel; local and remote sessions appear in the same session list.
+
+Set `ask` to `false` to disable webpage questions. Set `latestWorkflow` to `true` to let a newer otunnel workflow supersede older requests from the same ChatGPT conversation.

package/docs/tools.md

@@ -2,58 +2,40 @@
 
 | Tool | Purpose |
 |---|---|
-| `init` | Connect to a Pi session and read its environment, tool catalog, skills, global `AGENTS.md`, and pending input. |
-| `sessions` | List connected Pi sessions and the chat's default session. |
-| `tools` | Read complete definitions for selected active tools. |
+| `init` | Select this ChatGPT conversation's default Pi session and read its environment. |
+| `sessions` | List connected Pi sessions and the current default. |
+| `tools` | Read full definitions of active Pi tools for `call`. |
 | `chat` | Send an assistant message to Pi. |
-| `call` | Run one or more tools as a Pi batch. |
+| `ask` | Create a persistent question in ChatGPT. |
+| `ask_assert` | Confirm that an `ask` widget loaded. |
+| `call` | Run one or more Pi tools as one native batch. |
 | `read` | Read local text or images. |
-| `bash` | Execute a shell command. |
+| `bash` | Run a shell command. |
 | `edit` | Apply text replacements. |
 | `write` | Write text to a file. |
-| `transfer` | Copy files between ChatGPT and Pi, or export a Pi image as a file. |
-
-## Model environment
-
-The active model is the current ChatGPT conversation. A Pi tool that starts another `chappie/chatgpt` agent cannot create a new browser conversation, so that child waits without a model response. Subagents configured with another provider use that provider normally.
-
-Use ChatGPT's web search, connectors, and cloud tools for remote research and cloud-side work. Chappie tools operate on local files, processes, Pi extensions, and Pi user interfaces. Pi project-memory tools access their local stores; Pi context-reduction tools do not alter the current ChatGPT conversation.
-
-Use `chat` for progress or results that should appear in Pi. When a Pi user decision is needed, load the installed interactive tool definition with `tools` and invoke it through `call`.
+| `transfer` | Move files between ChatGPT and Pi or export a Pi image. |
 
 ## Sessions
 
-Call `init` with `{}` to reuse the chat's session or pair with the first online, unbound Pi session. A newly opened Pi session can be selected before its first user message; the first remote operation starts its Chappie provider turn.
-
-`sessions` lists session IDs, working directories, names, and status. `ready` means the provider is accepting output, `executing` means Pi is handling an operation, and `idle` means the next operation will start a turn.
-
-Use an ID from that list to select a default with `init`:
-
-```json
-{ "sessionId": "<session-id>" }
-```
+Call `init` at the start of local work. Without `sessionId`, it reuses the conversation's saved default or selects an online Pi session with no saved ChatGPT binding. Pass a Pi session ID to resume a specific task, including from another ChatGPT conversation or branch.
 
-The optional `sessionId` on other tools selects a session for that operation. For example, `read` can inspect another project:
+`sessions` lists connected sessions with their ID, device, working directory, name, execution status, and binding count. A conversation can address another session for one operation by supplying that tool's optional `sessionId`; only `init({ sessionId })` changes the saved default.
 
-```json
-{ "path": "package.json", "sessionId": "<session-id>" }
-```
+Several ChatGPT conversations can use the same Pi session. One conversation can also operate on several Pi sessions explicitly. Requests already assigned to a session continue there even if the conversation later changes its default.
 
-`sessions({ sessionId })` filters the online list and retrieves available input when that session is connected. The call returns immediately when the selected or bound session is offline; the saved binding is still shown, and deferred results remain available.
+Remote Pi sessions appear in the same list when they connect to a broker exposed through `listen` and `connect`. Their tools, global `AGENTS.md`, files, images, and Pi interfaces come from the remote device.
 
-Several chats can select the same Pi session, and one chat can address several sessions. Defaults are saved in `chappie.state.json` under Pi's agent directory. An existing binding waits for its Pi session to reconnect; `init` with another ID selects a different target.
+## Pi tools
 
-## Tool calls
+`read`, `bash`, `edit`, `write`, and `transfer` are available directly. `init` includes a short catalog of the active Pi tools; use `tools` for their complete definitions and `call` to invoke extension tools.
 
-`read`, `bash`, `edit`, and `write` accept Pi's tool parameters plus `sessionId`. Their descriptions provide the current schemas. `init` lists every active tool by name with a short description. Load complete definitions for installed extension tools before calling them:
+For example:
 
 ```json
 { "names": ["ask_user", "ctx_search"] }
 ```
 
-Omit `names` to return every active definition. Definitions already present in the current ChatGPT context can be reused without another query.
-
-A single extension tool uses a one-item `calls` array. To request a batch:
+A `call` array is one Pi tool batch:
 
 ```json
 {
@@ -64,46 +46,53 @@ A single extension tool uses a one-item `calls` array. To request a batch:
 }
 ```
 
-Each batch returns its results together. Pi determines how its tools run within the batch. Separate calls run in order within one Pi session; different sessions can work independently.
-
-Extension tools execute through Pi, including their interactive prompts. Results include each tool's name, call ID, error status, and original text or image content.
-
-ChatGPT file inputs use the direct `transfer` tool. Its top-level `files` parameter lets the host prepare the files before sending them to Pi.
+Pi controls execution inside that batch. Separate requests run in order within one Pi session, while different Pi sessions can work independently. Extension tools retain their native Pi behavior, including interactive interfaces.
 
-## Messages and interrupted calls
-
-Call `chat` to display a reply in Pi:
+`chat` creates a normal assistant message in Pi:
 
 ```json
 { "text": "Updated the parser and its callers." }
 ```
 
-Each call completes one assistant message. Later operations start another turn when Pi is idle. The result returns the target session and any new Pi input without repeating the message text.
-
-User messages consumed by Pi accompany later Chappie replies, including images. Steering is delivered when Pi consumes it; follow-up uses Pi's normal follow-up timing.
+Pi user input consumed during the work accompanies later Chappie results, including images. Steering and follow-up follow Pi's own delivery timing.
 
-Explicit cancellation removes a queued request or asks Pi to stop its active batch. Available results from that batch accompany a later reply to the originating chat. `sessions` can retrieve them before another tool call. When ChatGPT stops without sending cancellation, local execution continues.
+If a request is explicitly cancelled after local work has produced results, those results can accompany a later response to the originating ChatGPT conversation. Long-running local work is better run through the environment's persistent process facilities instead of occupying one tool request.
 
-Host request deadlines include time spent in the queue. Use local facilities such as tmux for work intended to outlive one call.
+The active model remains the current ChatGPT conversation. Starting another `chappie/chatgpt` agent inside Pi does not create another browser conversation; tools that need another model should use a separately configured provider.
 
-## Files
+## Webpage questions
 
-`transfer.paths` names files on the Pi machine. Relative paths resolve from the selected session's working directory. Absolute paths and `~/` work too, including Windows paths such as `C:/Tmp/report.zip`.
-
-### ChatGPT to Pi
-
-Supply matching `paths` and `files` arrays:
+When enabled, `ask` creates a question in ChatGPT and returns its ID immediately:
 
 ```json
 {
-  "paths": ["assets/reference.png"],
-  "files": ["/mnt/data/reference.png"]
+  "header": "Export format",
+  "question": "Which export format should the command use?",
+  "context": "Both preserve the required data.",
+  "options": [
+    { "title": "JSON", "description": "Convenient for programs.", "recommended": true },
+    { "title": "CSV", "description": "Convenient for spreadsheets." }
+  ]
 }
 ```
 
-`files` contains actual cloud paths or attachment references available to ChatGPT. The host converts them into file objects with download URLs before Chappie receives the call.
+Call `ask_assert` with the returned ID to confirm that the widget loaded:
 
-Multiple files are matched by array position:
+```json
+{ "questionId": "<question-id>" }
+```
+
+Answers, revisions, and skips arrive later as `webAnswer` in normal Chappie results. `options` can be omitted for a text answer, and `allowMultiple: true` allows several choices. `sessionId` associates the question with a Pi session without changing the conversation's default.
+
+Questions remain available after the assistant response and across broker restarts. Pi's own interactive tools remain ordinary Pi tools and can be invoked through `call`.
+
+## Files
+
+`transfer.paths` always names paths or image references on the Pi side. Relative paths resolve from the selected Pi session's working directory; absolute paths and `~/` are accepted.
+
+### ChatGPT to Pi
+
+Pair Pi destinations with ChatGPT files:
 
 ```json
 {
@@ -112,7 +101,9 @@ Multiple files are matched by array position:
 }
 ```
 
-Chappie creates parent directories and streams each file into its destination. Existing targets produce an error. To replace a file:
+The ChatGPT host turns the cloud paths or attachment references into downloadable file objects before the call reaches Chappie. Chappie creates parent directories and writes each file directly to its destination.
+
+Existing targets produce an error by default. Use `overwrite: true` when replacement is intended:
 
 ```json
 {
@@ -122,26 +113,22 @@ Chappie creates parent directories and streams each file into its destination. E
 }
 ```
 
-Overwriting truncates the existing file. A failed or canceled download removes the incomplete target opened by that operation, including an overwritten target. Successful files in a batch remain in place; the result reports each file's byte count or error.
+A failed or cancelled transfer removes the incomplete destination opened by that operation. Successful members of a multi-file transfer remain in place.
 
 ### Pi to ChatGPT
 
-Omit `files` to export existing files:
+Omit `files` to export existing Pi files:
 
 ```json
 { "paths": ["build/output.zip", "renders/preview.png"] }
 ```
 
-The result contains resource links with file names, types, and sizes. ChatGPT retrieves the bytes and handles attachment creation and cloud-container access. This may prompt for confirmation.
+Chappie returns MCP resource links. ChatGPT retrieves the bytes when it materializes those resources, which can require user confirmation. A resource remains associated with the Pi session that exported it, so that Pi process and source file need to remain available until the bytes are read.
 
-Each resource refers to its original Pi session, even after the chat selects another default. Keep that Pi process and the source files available while ChatGPT reads them. Files are read when requested. After starting a new Pi process, export again to obtain a fresh reference.
-
-For a directory, create an archive using a Pi tool and export that file.
+For a directory, create an archive with a Pi tool and export the resulting file.
 
 ### Images
 
-`read` sends images directly to ChatGPT for viewing. Images from Pi tools and user messages also include a `piImage` field containing a `chappie://` reference.
-
-To analyze one in ChatGPT's cloud container, pass the returned reference in `transfer.paths`. This exports the image bytes held by Pi as a file. Include the image's owning `sessionId` when another session is selected.
+`read` and Pi tool results send images directly to ChatGPT for visual inspection. Chappie also returns a `chappie://` image reference with Pi images. Pass that reference to `transfer.paths` when the same bytes are needed as a file in ChatGPT's cloud environment.
 
-To transfer the original image file, use its local path. Pi may resize or convert images for viewing.
+Use the original local path with `transfer` when the original image file is required; Pi can resize or convert images used only for display.

package/package.json

@@ -1,10 +1,11 @@
 {
 	"name": "@zetaloop/chappie",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Connect ChatGPT to Pi",
 	"devDependencies": {
 		"@earendil-works/pi-ai": "^0.85.1",
 		"@earendil-works/pi-coding-agent": "^0.85.1",
+		"@earendil-works/pi-tui": "^0.85.1",
 		"@types/node": "^26.5.1",
 		"typebox": "^1.3.30",
 		"typescript": "^7.0.2"
@@ -34,6 +35,7 @@
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",
 		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
 		"typebox": "*"
 	},
 	"dependencies": {