@zetaloop/chappie 0.3.2 → 0.4.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. `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 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.
 
-See the [tool guide](docs/tools.md) for session selection, Pi tools, webpage questions, and file transfer.
+See the [tool guide](docs/tools.md) for session selection, history, synchronization, Pi tools, webpage questions, and file transfer.
 
 ## Configuration
 
@@ -51,4 +51,12 @@ Remote Pi sessions connect through the broker device's mDNS name:
 
 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.
+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.

package/docs/tools.md

@@ -3,6 +3,8 @@
 | Tool | Purpose |
 |---|---|
 | `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. |
@@ -17,14 +19,58 @@
 
 ## 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.
+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 session 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.
+`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.
 
-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.
+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.
 
 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.
 
+## History
+
+`history` reads the current branch of a Pi session. It uses the saved default or an explicit `sessionId`, independently of default-session selection.
+
+```json
+{ "sessionId": "<session-id>", "limit": 20, "before": "<entry-id>" }
+```
+
+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.
+
+`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.
+
+Verify using the code from the most recent initialization:
+
+```json
+{ "action": "verify", "code": "<initialization-code>" }
+```
+
+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.
+
 ## Pi tools
 
 `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.

package/package.json

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

package/src/activity.ts

@@ -0,0 +1,21 @@
+export interface Source {
+	chatId: string;
+	requestId?: string;
+}
+
+export interface Activity extends Partial<Source> {
+	event?: string;
+	initialization?: "explicit" | "implicit";
+}
+
+export function source(chatId: string, requestId: unknown): Source {
+	return {
+		chatId,
+		...(typeof requestId === "string" ? { requestId } : {}),
+	};
+}
+
+export function chatLabel({ chatId, requestId }: Source): string {
+	const workflow = requestId?.match(/^wfr_([^/]+)\//)?.[1];
+	return `ChatGPT ${chatId.slice(-4)}${workflow ? `(${workflow.slice(-4)})` : ""}`;
+}