@zetaloop/chappie 0.4.1 → 0.5.0

package/README.md

@@ -29,9 +29,9 @@ Call `init` from ChatGPT to connect the conversation to Pi. A conversation can r
 
 ## Usage
 
-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. `history` reads recent Pi messages and activity with timestamps. `ask` can present a persistent question in ChatGPT when webpage questions are enabled.
+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 between ChatGPT and Pi or between connected devices. `history` reads recent Pi messages and activity with timestamps. `ask` can present a persistent question in ChatGPT when webpage questions are enabled.
 
-See the [tool guide](docs/tools.md) for session selection, history, synchronization, Pi tools, webpage questions, and file transfer.
+See the [tool guide](docs/tools.md) for session selection, history, Pi tools, webpage questions, and file transfer.
 
 ## Configuration
 
@@ -53,10 +53,4 @@ The default port is `24274`. Set `listen` to a port number or append `:port` to
 
 Set `ask` to `false` to disable webpage questions.
 
-Enable synchronization to resolve conflicting activity:
-
-```json
-{ "sync": true }
-```
-
-Initialization returns a short name and a private code. `sync` pauses conflicting work for discussion through `chat` and `history`. The verified coordinator decides who continues, their tasks, and who exits, including retaining only one execution. See [synchronization](docs/tools.md#synchronization).
+Closely spaced initializations from the same ChatGPT conversation receive guidance to observe the ongoing work through `history` and explain its results. See [participation](docs/tools.md#participation).

package/docs/tools.md

@@ -4,7 +4,6 @@
 |---|---|
 | `init` | Select this ChatGPT conversation's default Pi session and read its environment. |
 | `history` | Read the current Pi branch with timestamps and entry IDs. |
-| `sync` | Resolve conflicting activity under one coordinator. |
 | `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. |
@@ -15,17 +14,17 @@
 | `bash` | Run a shell command. |
 | `edit` | Apply text replacements. |
 | `write` | Write text to a file. |
-| `transfer` | Move files between ChatGPT and Pi or export a Pi image. |
+| `transfer` | Move files between ChatGPT and Pi, copy between Pi sessions, or export a Pi image. |
 
 ## Sessions
 
 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. Read recent `history` to recover progress before continuing the current task.
 
-Initialization returns the request suffix as `initialization.name` when available. Each execution retains its own name for coordination through `chat`.
+When `globalAgents` is present, read and follow the instructions at `globalAgents.path` on the selected Pi session. Follow the participation guidance in `initialization.instructions`.
 
-`sessions` lists connected sessions with their ID, device, working directory, name, execution status, and binding count. The first execution tool call establishes the default using its `sessionId` or an online session with no saved bindings. During synchronization, `chat` and `history` use the requested session solely for communication. Once a default exists, another tool's `sessionId` selects only that operation's target; `init({ sessionId })` changes the default.
+`sessions` lists connected sessions with their ID, device, working directory, name, execution status, and binding count. The first execution tool call establishes the default using its `sessionId` or an online session with no saved bindings. Once a default exists, another tool's `sessionId` selects only that operation's target; `init({ sessionId })` changes the default.
 
-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. Synchronization can cancel ordinary requests for the locked session or its bound conversations.
+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.
 
 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.
 
@@ -39,42 +38,20 @@ Remote Pi sessions appear in the same list when they connect to a broker exposed
 
 Omit `before` for the latest entries. Use `after` to read forward from an entry. Both fields can delimit a range, with the named entries outside the returned range. The default limit is 20 readable entries. Results follow branch order and contain each entry's original ID and timestamp. `hasMore` indicates additional entries in the requested direction.
 
-Messages, tool calls and results, summaries, images, file links, and Chappie activity records use their saved contents, including Pi's existing truncation notices and full-output paths. Assistant messages carry their originating `chatId` and optional full `requestId` in `message.chappie`. Tool results inherit the source of their `toolCallId`, including when the call falls outside the requested page. Activity records carry the same source fields. Request-specific notices display a compact label such as `ChatGPT Zxbs(fd44) joined`; the workflow suffix is for log correlation and can be shared by parallel executions. When participants report different goals, workflow timing helps identify possible work resumed from an earlier ChatGPT message. Reading leaves a short notice in Pi; the returned history remains separate from new input and pending result delivery.
+To follow progress, pass `after` with `wait: true`. Available entries return immediately; at the end of the branch, the request waits up to 30 seconds for new readable entries. A timeout returns an empty page. Reads with `before` return immediately. Cancellation, disconnection, or an invalidated branch cursor ends the request. Waiting for history leaves the session available for other requests.
 
-Pi user input, webpage answers, connection status, and deferred delivery target sessions or conversations. A deferred result's `requestId` identifies the original operation; the result can reach another execution in that conversation.
+Set `observer: true` to read as an observer. New messages and work activity wake waiting readers; idle status alone does not indicate task completion.
 
-## Synchronization
+History includes saved messages, tool calls and results, summaries, images, file links, and work activity. Truncation notices and full-output paths are included so complete output can be read when needed. Reading history leaves new input and pending results available for normal delivery.
 
-Enable `sync` in the broker's `chappie.json`. Initialization returns a private `initialization.code` for its Pi session; a saved binding without a code receives one on its next execution.
+## Participation
 
-When activity conflicts, start synchronization:
-
-```json
-{ "action": "start", "sessionId": "<session-id>" }
-```
-
-This locks ordinary tools and initialization for the Pi session and its bound conversations, cancelling their active ordinary requests. Bound conversations also pause work on other sessions; unrelated conversations continue. `chat`, `history`, and `sessions` remain available with existing bindings.
-
-Verify using the code from the most recent initialization:
-
-```json
-{ "action": "verify", "code": "<initialization-code>" }
-```
-
-The first successful verification returns a replacement code to the coordinator. Everyone can discuss goals and progress through `chat` and `history`, including executions with missing or rejected codes. The coordinator decides who continues, their tasks, and who exits, and may retain only one execution.
-
-Participants acknowledge the decision. Those directed to exit leave a chat handoff and end their responses. Only the coordinator can release, after these decisions and exits are confirmed:
-
-```json
-{ "action": "release", "code": "<verified-code>" }
-```
-
-Remaining executions resume their assigned work. Pending input, webpage answers, and deferred results resume normal delivery. Webpage submissions and exported resource reads remain available throughout synchronization.
-
-Codes persist per Pi session in `chappie.state.json`; locks last for the broker process and survive Pi-client or tunnel reconnections. Repeated `start` preserves the lock; `verify` with the current code, `sessions`, and `history` report its status.
+The executing assistant uses `chat` to share progress and completion in Pi. When initialization directs an assistant to observe, it follows that work through `history` with `observer: true` and `wait: true`, thinks independently, and explains the recorded results in ChatGPT when the task is complete.
 
 ## Pi tools
 
+ChatGPT truncates tool responses exceeding 10,000 tokens.
+
 `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.
 
 For example:
@@ -102,7 +79,7 @@ Pi controls execution inside that batch. Separate requests run in order within o
 { "text": "Updated the parser and its callers." }
 ```
 
-Pi user input consumed during the work accompanies later Chappie results, including images. Steering and follow-up follow Pi's own delivery timing.
+Pi user input consumed during the work accompanies later Chappie results, including images.
 
 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.
 
@@ -110,7 +87,7 @@ The active model remains the current ChatGPT conversation. Starting another `cha
 
 ## Webpage questions
 
-When enabled, `ask` creates a question in ChatGPT and returns its ID immediately:
+When enabled, `ask` saves a question and requests a widget in ChatGPT, returning its ID immediately. Display depends on the host:
 
 ```json
 {
@@ -130,6 +107,8 @@ Call `ask_assert` with the returned ID to confirm that the widget loaded:
 { "questionId": "<question-id>" }
 ```
 
+If the widget has not loaded within 10 seconds, `ask_assert` fails and saves the unanswered question as skipped. Use a Pi interactive tool when an answer is needed. The user can still answer or edit the saved question when its widget is available.
+
 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 using the session selection rules above.
 
 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`.
@@ -149,7 +128,7 @@ Pair Pi destinations with ChatGPT files:
 }
 ```
 
-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.
+The ChatGPT host turns the cloud paths or attachment references into downloadable file objects before the call reaches Chappie. Parent directories are created as needed.
 
 Existing targets produce an error by default. Use `overwrite: true` when replacement is intended:
 
@@ -175,6 +154,25 @@ Chappie returns MCP resource links. ChatGPT retrieves the bytes when it material
 
 For a directory, create an archive with a Pi tool and export the resulting file.
 
+### Pi to Pi
+
+Supply `to` to copy files to another connected Pi session:
+
+```json
+{
+  "sessionId": "<source-session>",
+  "paths": ["build/output.zip"],
+  "to": {
+    "sessionId": "<destination-session>",
+    "paths": ["downloads/output.zip"]
+  }
+}
+```
+
+Source and destination paths correspond by position. Each session resolves its own relative paths, absolute paths, and `~/`. Image references can also be copied. `files` and `to` select different sources and are mutually exclusive.
+
+Both Pi sessions need to stay connected during the transfer. `overwrite: true` replaces an existing destination. Cancellation or failure discards the incomplete file; successfully copied files remain available.
+
 ### Images
 
 `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.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zetaloop/chappie",
-	"version": "0.4.1",
+	"version": "0.5.0",
 	"description": "Connect ChatGPT to Pi",
 	"devDependencies": {
 		"@earendil-works/pi-ai": "^0.85.1",