@zetaloop/chappie 0.3.2 → 0.4.1

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.
+
+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).

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` | 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. |
@@ -17,14 +19,60 @@
 
 ## 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.
+Initialization returns the request suffix as `initialization.name` when available. Each execution retains its own name for coordination through `chat`.
 
-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` 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. 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 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.
+
+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
+
+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.
+
+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.
+
 ## 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.1",
 	"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)})` : ""}`;
+}