@zetaloop/chappie 0.4.0 → 0.4.1

package/README.md

@@ -53,10 +53,10 @@ 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:
+Enable synchronization to resolve conflicting activity:
 
 ```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.
+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

@@ -4,7 +4,7 @@
 |---|---|
 | `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. |
+| `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. |
@@ -21,6 +21,8 @@
 
 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`.
+
 `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.
@@ -37,23 +39,21 @@ 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.
+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
 
-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.
+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 for the session:
+When activity conflicts, start synchronization:
 
 ```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.
+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:
 
@@ -61,15 +61,17 @@ Verify using the code from the most recent initialization:
 { "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 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.
 
-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:
+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>" }
 ```
 
-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.
+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
 

package/package.json

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

package/src/broker.ts

@@ -25,8 +25,8 @@ import { type ResourceData, resourceSessionId } from "./resources.ts";
 import { State } from "./state.ts";
 import type { ToolInput } from "./tools.ts";
 
-const exitInstructions =
-	"Send one final chat message stating your task, entry time, and that this execution is ending; keep all codes private. Then end this ChatGPT response immediately with no further tool calls. Do not wait for unlock, poll history, reinitialize, or resume this task after release.";
+const coordinationInstructions =
+	"Report your goal and progress through chat using your initialization name. The coordinator decides who continues, their tasks, and who exits. Follow the decision through chat and history; if asked to exit, leave a handoff and end this response.";
 
 interface RegisteredSession {
 	description: SessionDescription;
@@ -66,6 +66,7 @@ interface ChangeWaiter {
 }
 
 export interface Initialization {
+	name?: string;
 	code?: string;
 	sessionId: string;
 	instructions: string;
@@ -304,7 +305,7 @@ export class Broker {
 				{ ...activity, event: "sync_rejected" },
 			);
 			throw new Error(
-				`The sync code is missing or outdated. This execution is a stale, accidental duplicate. ${exitInstructions}`,
+				`Invalid sync code. Ordinary tools remain locked. ${coordinationInstructions}`,
 			);
 		}
 		if (action === "verify") {
@@ -324,7 +325,7 @@ export class Broker {
 				...this.syncState(target),
 				...(renewed ? { code: renewed } : {}),
 				instructions:
-					"This is the surviving execution. Keep the verified code private in this ChatGPT context. Use chat and history to identify every observed conflicting execution and require its final exit. Confirm they have ended their responses, rather than only paused ordinary tools. Verification, idle Pi status, or a quiet history page alone does not establish their exit. Release with this code only after explicit final exit statements and resolution of conflicting activity; ordinary tools remain locked until then.",
+					"You are the coordinator. Decide who continues, their tasks, and who exits; you may retain only one execution. Keep this code private. Release after your decisions are acknowledged and requested exits are complete.",
 			};
 		}
 		if (!this.#locks.get(target))
@@ -342,7 +343,7 @@ export class Broker {
 			...result,
 			...this.syncState(target),
 			instructions:
-				"Synchronization released. The surviving execution may continue the current task. Executions with rejected or unavailable codes remain finished.",
+				"Synchronization released. Continue as directed by the coordinator.",
 		};
 	}
 
@@ -809,12 +810,17 @@ export class Broker {
 			event: "joined",
 			initialization: explicit ? "explicit" : "implicit",
 		});
+		const name = activity.requestId?.match(/\/([^/]+)$/)?.[1];
+		const instructions = name
+			? `${historyInstructions} Use this name when coordinating through chat.`
+			: historyInstructions;
 		return {
 			sessionId,
+			...(name ? { name } : {}),
 			...(code ? { code } : {}),
 			instructions: code
-				? `${historyInstructions} Retain this initialization code in this ChatGPT context for sync verification; Pi history and chat messages contain only coordination details.`
-				: historyInstructions,
+				? `${instructions} Keep this code private for sync verification.`
+				: instructions,
 		};
 	}
 
@@ -990,7 +996,7 @@ export class Broker {
 }
 
 function syncMessage(sessionId: string): string {
-	return `Pi session ${sessionId} is synchronizing to end duplicate executions. Ordinary tools and initialization are locked for this session and its bound ChatGPT conversations. Verify with the code returned by your own most recent initialization. With a missing or rejected code, this execution is an accidental duplicate: ${exitInstructions} The verified execution must confirm the conflicting executions' final exits before releasing the lock.`;
+	return `Pi session ${sessionId} is synchronizing. Ordinary tools and initialization are locked. Verify with your own initialization code; keep it private. ${coordinationInstructions} Only the verified coordinator can release.`;
 }
 
 function abortError(signal: AbortSignal): Error {

package/src/instructions.md

@@ -2,6 +2,8 @@ Chappie connects this ChatGPT conversation to Pi sessions on one or more devices
 
 init sets this chat's default Pi session. An execution tool also establishes a default on first use: sessionId selects its target, or omitting it selects the first online session with no saved bindings. These sessions may already contain work. Once a default exists, another tool's sessionId selects only that call's target. Defaults survive broker restarts, and several chats can share one Pi session. When resuming work after explicit or implicit initialization, read recent history to recover progress, then continue from the current request.
 
+Use initialization.name, derived from the initialization request suffix, to identify yourself during coordination.
+
 The active model is this existing ChatGPT conversation. A Pi tool that starts another chappie/chatgpt agent has no ChatGPT conversation to attach to and will wait indefinitely. Subagents targeting another configured model keep that provider's normal behavior.
 
 Prefer ChatGPT's web search, connectors, and cloud tools for remote research and cloud-side work. Use Chappie for local files, processes, Pi extensions, and Pi user interfaces. Pi project-memory tools operate on their local stores; Pi context-reduction tools do not change this ChatGPT conversation.
@@ -14,4 +16,4 @@ transfer pairs files from ChatGPT with Pi destination paths in order. Omit files
 
 Tool results identify the executing Pi sessionId and cwd. A shell command can access another directory without changing its Pi session. structuredContent.text includes the complete text, new Pi input, webAnswer, and deferred results; images and resources are native content blocks. Continue from received results rather than repeating work. Host deadlines include queueing and execution; use local persistent processes for longer work.
 
-Use history to read the current Pi branch with original entry IDs and timestamps, including chat activity records. Assistant messages and tool results expose their originating chatId and requestId in message.chappie; activity records include the same fields. Request IDs and the workflow suffix in notices describe recorded requests, and duplicate executions can share a workflow ID. It defaults to the last 20 entries; before pages backward and after pages forward. History is a record of past work, separate from new Pi input. It leaves a reading notice and returns its content only to the caller.
+Use history to read the current Pi branch with original entry IDs and timestamps, including chat activity records. Assistant messages and tool results expose their originating chatId and requestId in message.chappie; activity records include the same fields. Parallel executions can share a chatId and workflow ID. Workflow timing helps explain differences in their task goals. History defaults to the last 20 entries; before pages backward and after pages forward. History is a record of past work, separate from new Pi input. It leaves a reading notice and returns its content only to the caller.

package/src/server.ts

@@ -33,7 +33,7 @@ const outputSchema = z.object({
 });
 
 const syncInstructions =
-	"Synchronization ends accidental duplicate executions so one execution continues. Retain each initialization code privately in this ChatGPT context for its Pi session. On conflicting activity, call sync with action start, then verify with the code returned by your own most recent initialization. A rejected or unavailable code means this execution must send one final chat message with its task, entry time, and explicit exit statement, then end this ChatGPT response immediately. It must not wait for unlock, poll, reinitialize, or resume after release. Verification returns a new code and leaves ordinary tools and initialization locked. The verified execution uses chat and history to identify conflicting executions, require their final exit messages, and confirm their responses have ended before releasing with that code. Idle Pi status or a quiet history page is not proof of exit. Codes belong only in initialization and sync exchanges, never in chat, history, or notes.";
+	"On conflicting activity, start sync and verify with your own initialization code. Keep codes private. Verification returns a new code to the coordinator; ordinary tools and initialization stay locked. Discuss through chat and history, including after failed verification. The coordinator decides who continues, their tasks, and who exits, including retaining only one execution. Acknowledge the decision; if asked to exit, leave a chat handoff and end your response. Only the coordinator releases after decisions and exits are confirmed.";
 
 const questionTemplate = "ui://chappie/question.html";
 const questionSchema = outputSchema.extend({ question: questionOutput });
@@ -89,7 +89,7 @@ export function createServer(broker: Broker): McpServer {
 		{
 			title: "Connect to Pi",
 			description:
-				"Select this chat's default Pi session and return its environment and tool catalog. Use the task's sessionId to resume, or find it by cwd/name with sessions. For a task without a specified target, omit sessionId to reuse the default or select the first online, unbound session. Read recent history when resuming work.",
+				"Select this chat's default Pi session and return its environment, tool catalog, and initialization name for coordination. Use the task's sessionId to resume, or find it by cwd/name with sessions. For a task without a specified target, omit sessionId to reuse the default or select the first online, unbound session. Read recent history when resuming work.",
 			outputSchema,
 			inputSchema: z.object({
 				sessionId: z
@@ -467,7 +467,7 @@ export function createServer(broker: Broker): McpServer {
 			{
 				title: "Synchronize Pi activity",
 				description:
-					"End duplicate executions: start synchronization, verify your own latest initialization code, and release after conflicting executions exit. Failed verification requires a final chat exit message followed by ending this response. Verification leaves the session locked; chat and history support exit coordination.",
+					"Pause conflicting activity. Verify your initialization code to coordinate; failed verification still permits discussion. The coordinator decides who continues, their tasks, who exits, and when to release.",
 				inputSchema: z.object({
 					action: z.enum(["start", "verify", "release"]),
 					code: z