@zetaloop/chappie 0.4.0 → 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.
 
-Optional session synchronization ends duplicate executions so one execution continues:
-
-```json
-{ "sync": true }
-```
-
-With synchronization enabled, initialization returns a fresh code. `sync` locks a Pi session and its bound conversations while executions verify their codes. Rejected executions announce their exit and end their responses; the verified execution confirms those exits through `chat` and `history`, then releases the lock. Codes persist in broker state; locks last for the broker process. See [synchronization](docs/tools.md#synchronization) for the tool sequence.
+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` | End duplicate executions so one execution continues. |
 | `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,15 +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.
 
-`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.
+When `globalAgents` is present, read and follow the instructions at `globalAgents.path` on the selected Pi session. Follow the participation guidance in `initialization.instructions`.
 
-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.
+`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.
 
 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.
 
@@ -37,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 duplicate executions. Reading leaves a short notice in Pi; the returned history remains separate from new input and pending result delivery.
-
-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.
-
-## Synchronization
-
-Set `sync` to `true` in the broker's `chappie.json` to enable the `sync` tool. Each explicit initialization and first execution that establishes a default returns `initialization.code`. Retain the code in the ChatGPT context alongside its Pi session ID. Ordinary calls use the existing binding; a saved binding without a code receives one on its next execution.
-
-When activity conflicts, start synchronization for the session:
-
-```json
-{ "action": "start", "sessionId": "<session-id>" }
-```
-
-This locks ordinary tools and initialization for that Pi session and every conversation currently bound to it. Existing ordinary requests in that scope are cancelled through Pi's cancellation path. Bound conversations also pause their operations on other sessions. Other conversations continue using unrelated sessions. Automatic session selection considers unlocked sessions.
+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.
 
-`chat`, `history`, and `sessions` remain available to establish which executions must exit. A rejected execution uses `chat` for one final message with its task, entry time, and explicit exit statement, then immediately ends its ChatGPT response and all tool use. Unlocking leaves that execution finished; it must not wait, poll, reinitialize, or resume the task. The verified execution remains responsible for completing the current task. Communication tools keep existing bindings during synchronization. Pending input, webpage answers, and deferred results for the affected work remain available for normal delivery after release. Webpage components can still submit answers and the host can read exported resources.
+Set `observer: true` to read as an observer. New messages and work activity wake waiting readers; idle status alone does not indicate task completion.
 
-Verify using the code from the most recent initialization:
+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.
 
-```json
-{ "action": "verify", "code": "<initialization-code>" }
-```
+## Participation
 
-The first successful verification replaces the code and returns it to that call. Verification leaves the session locked. A missing, incorrect, or older code identifies an accidental duplicate that must exit as described above. This applies to the execution, even when other executions share its conversation ID. Repeating `start` preserves the current synchronization; repeating `verify` with the verified code reads its status.
-
-The holder of the verified code uses `chat` and `history` to identify every observed conflicting execution, require an explicit final exit message, and confirm it has ended its response. A promise to pause ordinary tools, idle Pi status, or a quiet history page alone is insufficient. After those final exits and resolution of conflicting activity, the surviving execution explicitly releases the session:
-
-```json
-{ "action": "release", "code": "<verified-code>" }
-```
-
-Current codes are saved per Pi session in `chappie.state.json`. Activity records contain coordination details; codes stay in initialization and synchronization exchanges. Lock and verification state live in the broker process, so restarting the broker restores ordinary operation. Pi-client and tunnel reconnections retain the running broker's locks. `sessions` and `history` report the current synchronization state.
+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:
@@ -100,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.
 
@@ -108,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
 {
@@ -128,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`.
@@ -147,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:
 
@@ -173,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.0",
+	"version": "0.5.0",
 	"description": "Connect ChatGPT to Pi",
 	"devDependencies": {
 		"@earendil-works/pi-ai": "^0.85.1",