@zetaloop/chappie 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zetaloop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# Chappie
+
+Use ChatGPT to edit files, run commands, and work with [Pi](https://github.com/earendil-works/pi) extensions. Supports multiple Pi sessions, images, and two-way file transfers.
+
+## Setup
+
+Install through Pi:
+
+```sh
+pi install npm:@zetaloop/chappie
+```
+
+Add Chappie to your [otunnel](https://github.com/zetaloop/otunnel) configuration:
+
+```yaml
+mcp:
+  commands:
+    - channel: main
+      command: pi --chappie
+```
+
+Start otunnel with this configuration and add its tunnel as a developer-mode app in ChatGPT. Run Pi in your project:
+
+```sh
+pi --provider chappie --model chatgpt
+```
+
+Send a task in Pi, then ask ChatGPT to call `init`. Chappie pairs the chat with a ready Pi session.
+
+## Usage
+
+Ask ChatGPT to work on the task using Chappie's tools. `chat` sends replies to Pi, and new Pi messages accompany subsequent tool results. Interactive tools display their prompts in Pi.
+
+See the [tool guide](docs/tools.md) for session selection, batch calls, messages, and file and image transfers.

package/docs/tools.md

@@ -0,0 +1,133 @@
+# Tools
+
+| Tool | Purpose |
+|---|---|
+| `init` | Connect to a Pi session and read its environment, tools, skills, global `AGENTS.md`, and pending input. |
+| `sessions` | List connected Pi sessions and the chat's default session. |
+| `tools` | Read the selected session's active tool definitions. |
+| `chat` | Send an assistant message to Pi. |
+| `call` | Run one or more tools as a Pi batch. |
+| `read` | Read local text or images. |
+| `bash` | Execute a shell command. |
+| `edit` | Apply text replacements. |
+| `write` | Write text to a file. |
+| `transfer` | Copy files between ChatGPT and Pi, or export a Pi image as a file. |
+
+## Sessions
+
+Call `init` with `{}` to reuse the chat's session or pair with the next ready, unbound Pi session. Either side can arrive first. Sending a task in Pi starts its Chappie provider request.
+
+`sessions` lists session IDs, working directories, names, and status. `ready` means the provider is accepting output, `executing` means Pi is handling an operation, and `idle` means the next operation will start a turn.
+
+Use an ID from that list to select a default with `init`:
+
+```json
+{ "sessionId": "<session-id>" }
+```
+
+The optional `sessionId` on other tools selects a session for that operation. For example, `read` can inspect another project:
+
+```json
+{ "path": "package.json", "sessionId": "<session-id>" }
+```
+
+`sessions({ sessionId })` shows the selected session and retrieves available input and deferred results. It can be called while Pi is executing a tool batch.
+
+Several chats can select the same Pi session, and one chat can address several sessions. Defaults are saved in `chappie.state.json` under Pi's agent directory. An existing binding waits for its Pi session to reconnect; `init` with another ID selects a different target.
+
+## Tool calls
+
+`read`, `bash`, `edit`, and `write` accept Pi's tool parameters plus `sessionId`. Their descriptions provide the current schemas. For installed extension tools, call `tools` and use the returned name and parameters in `call`.
+
+A single tool uses a one-item `calls` array. To request a batch:
+
+```json
+{
+  "calls": [
+    { "name": "read", "arguments": { "path": "package.json" } },
+    { "name": "read", "arguments": { "path": "src/index.ts" } }
+  ]
+}
+```
+
+Each batch returns its results together. Pi determines how its tools run within the batch. Separate calls run in order within one Pi session; different sessions can work independently.
+
+Extension tools execute through Pi, including their interactive prompts. Results include each tool's name, call ID, error status, and original text or image content.
+
+ChatGPT file inputs use the direct `transfer` tool. Its top-level `files` parameter lets the host prepare the files before sending them to Pi.
+
+## Messages and interrupted calls
+
+Call `chat` to display a reply in Pi:
+
+```json
+{ "text": "Updated the parser and its callers." }
+```
+
+Each call completes one assistant message. Later operations start another turn when Pi is idle. Use `chat` for text that should appear in Pi.
+
+User messages consumed by Pi accompany later Chappie replies, including images. Steering is delivered when Pi consumes it; follow-up uses Pi's normal follow-up timing.
+
+Explicit cancellation removes a queued request or asks Pi to stop its active batch. Available results from that batch accompany a later reply to the originating chat. `sessions` can retrieve them before another tool call. When ChatGPT stops without sending cancellation, local execution continues.
+
+Host request deadlines include time spent in the queue. Use local facilities such as tmux for work intended to outlive one call.
+
+## Files
+
+`transfer.paths` names files on the Pi machine. Relative paths resolve from the selected session's working directory. Absolute paths and `~/` work too, including Windows paths such as `C:/Tmp/report.zip`.
+
+### ChatGPT to Pi
+
+Supply matching `paths` and `files` arrays:
+
+```json
+{
+  "paths": ["assets/reference.png"],
+  "files": ["/mnt/data/reference.png"]
+}
+```
+
+`files` contains actual cloud paths or attachment references available to ChatGPT. The host converts them into file objects with download URLs before Chappie receives the call.
+
+Multiple files are matched by array position:
+
+```json
+{
+  "paths": ["assets/reference.png", "data/input.csv"],
+  "files": ["/mnt/data/reference.png", "/mnt/data/input.csv"]
+}
+```
+
+Chappie creates parent directories and streams each file into its destination. Existing targets produce an error. To replace a file:
+
+```json
+{
+  "paths": ["assets/reference.png"],
+  "files": ["/mnt/data/reference.png"],
+  "overwrite": true
+}
+```
+
+Overwriting truncates the existing file. A failed or canceled download removes the incomplete target opened by that operation, including an overwritten target. Successful files in a batch remain in place; the result reports each file's byte count or error.
+
+### Pi to ChatGPT
+
+Omit `files` to export existing files:
+
+```json
+{ "paths": ["build/output.zip", "renders/preview.png"] }
+```
+
+The result contains resource links with file names, types, and sizes. ChatGPT retrieves the bytes and handles attachment creation and cloud-container access. This may prompt for confirmation.
+
+Each resource refers to its original Pi session, even after the chat selects another default. Keep that Pi process and the source files available while ChatGPT reads them. Files are read when requested. After starting a new Pi process, export again to obtain a fresh reference.
+
+For a directory, create an archive using a Pi tool and export that file.
+
+### Images
+
+`read` sends images directly to ChatGPT for viewing. Images from Pi tools and user messages also include a `piImage` field containing a `chappie://` reference.
+
+To analyze one in ChatGPT's cloud container, pass the returned reference in `transfer.paths`. This exports the image bytes held by Pi as a file. Include the image's owning `sessionId` when another session is selected.
+
+To transfer the original image file, use its local path. Pi may resize or convert images for viewing.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@zetaloop/chappie",
+  "version": "0.1.0",
+  "description": "Connect ChatGPT to Pi",
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@types/node": "^26.5.1",
+    "typebox": "^1.3.30",
+    "typescript": "^7.0.2"
+  },
+  "keywords": [
+    "pi-package",
+    "chatgpt",
+    "mcp"
+  ],
+  "author": "zetaloop",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=26",
+    "pnpm": ">=12"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "mime": "^4.1.0",
+    "zod": "^4.6.4"
+  },
+  "files": [
+    "src",
+    "docs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zetaloop/chappie.git"
+  },
+  "scripts": {
+    "format": "biome check --write .",
+    "check": "biome check . && tsc"
+  }
+}

package/src/broker.ts

@@ -0,0 +1,448 @@
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type {
+	AssistantMessage,
+	ToolCall,
+	ToolResultMessage,
+} from "@earendil-works/pi-ai";
+import {
+	type DeliveryRecord,
+	type ResolvedDelivery,
+	resolveDelivery,
+} from "./delivery.ts";
+import {
+	type BrokerMessage,
+	IpcServer,
+	type JsonLinePeer,
+	type SessionDescription,
+	type SessionInput,
+	type SessionInspection,
+	type SessionMessage,
+	type SessionResult,
+} from "./ipc.ts";
+import { type ResourceData, resourceSessionId } from "./resources.ts";
+import { State } from "./state.ts";
+import type { ToolInput } from "./tools.ts";
+
+interface RegisteredSession {
+	description: SessionDescription;
+	peer: JsonLinePeer<SessionMessage, BrokerMessage>;
+}
+
+interface PendingRequest {
+	peer: JsonLinePeer<SessionMessage, BrokerMessage>;
+	resolve(result: SessionResult): void;
+	reject(error: Error): void;
+	signal: AbortSignal;
+	onAbort(): void;
+}
+
+interface ChangeWaiter {
+	resolve(): void;
+	reject(error: Error): void;
+	signal: AbortSignal;
+	onAbort(): void;
+}
+
+export interface InitializedSession extends SessionInspection {
+	globalAgents?: string;
+	inputs: SessionInput[];
+}
+
+export interface InspectedSession extends SessionInspection {
+	inputs: SessionInput[];
+}
+
+export interface ChatResult {
+	message: AssistantMessage;
+	inputs: SessionInput[];
+}
+
+export interface CallResult {
+	sessionId: string;
+	toolResults: ToolResultMessage[];
+	inputs: SessionInput[];
+}
+
+export class Broker {
+	readonly #agentDir: string;
+	readonly #ipc: IpcServer;
+	readonly #state: State;
+	readonly #sessions = new Map<string, RegisteredSession>();
+	readonly #ready = new Set<string>();
+	readonly #pending = new Map<number, PendingRequest>();
+	readonly #waiters = new Set<ChangeWaiter>();
+	#nextRequestId = 1;
+
+	constructor(agentDir: string) {
+		this.#agentDir = agentDir;
+		this.#state = new State(agentDir);
+		this.#ipc = new IpcServer(
+			agentDir,
+			(peer, message) => this.#receive(peer, message),
+			(peer) => this.#removePeer(peer),
+		);
+	}
+
+	async start(): Promise<void> {
+		await this.#state.load();
+		await this.#ipc.start();
+	}
+
+	async close(): Promise<void> {
+		const error = new Error("Chappie broker ended");
+		for (const [id, pending] of this.#pending) {
+			this.#finishRequest(id, pending);
+			pending.reject(error);
+		}
+		for (const waiter of this.#waiters) {
+			waiter.signal.removeEventListener("abort", waiter.onAbort);
+			waiter.reject(error);
+		}
+		this.#waiters.clear();
+		this.#sessions.clear();
+		this.#ready.clear();
+		await this.#ipc.close();
+	}
+
+	listSessions(sessionId?: string): SessionDescription[] {
+		if (sessionId) {
+			const session = this.#sessions.get(sessionId);
+			return session ? [session.description] : [];
+		}
+		return [...this.#sessions.values()].map(({ description }) => description);
+	}
+
+	binding(chatId: string): string | undefined {
+		return this.#state.binding(chatId);
+	}
+
+	async initialize(
+		chatId: string,
+		sessionId: string | undefined,
+		signal: AbortSignal,
+	): Promise<InitializedSession> {
+		const target = await this.#selectSession(chatId, sessionId, signal, true);
+		const { inspection, inputs } = await this.#inspect(target, signal);
+		const globalAgents = await this.#readGlobalAgents();
+		await this.#ackInputs(target, inputs);
+		return { ...inspection, inputs, ...(globalAgents ? { globalAgents } : {}) };
+	}
+
+	async chat(
+		chatId: string,
+		sessionId: string | undefined,
+		text: string,
+		signal: AbortSignal,
+	): Promise<ChatResult> {
+		const target = await this.#selectSession(chatId, sessionId, signal, false);
+		const result = await this.#request(
+			target,
+			(id) => ({ type: "chat", id, chatId, sessionId: target, text }),
+			signal,
+		);
+		if ("message" in result) {
+			await this.#ackInputs(target, result.inputs);
+			return { message: result.message, inputs: result.inputs };
+		}
+		throw new Error("Pi session returned no assistant message");
+	}
+
+	async tools(
+		chatId: string,
+		sessionId: string | undefined,
+		signal: AbortSignal,
+	): Promise<InspectedSession> {
+		const target = await this.#selectSession(chatId, sessionId, signal, false);
+		const { inspection, inputs } = await this.#inspect(target, signal);
+		await this.#ackInputs(target, inputs);
+		return { ...inspection, inputs };
+	}
+
+	async call(
+		chatId: string,
+		sessionId: string | undefined,
+		calls: ToolInput[],
+		signal: AbortSignal,
+	): Promise<CallResult> {
+		const target = await this.#selectSession(chatId, sessionId, signal, false);
+		const toolCalls: ToolCall[] = calls.map((call) => ({
+			type: "toolCall",
+			id: `chappie-${randomUUID()}`,
+			name: call.name,
+			arguments: call.arguments,
+		}));
+		const result = await this.#request(
+			target,
+			(id) => ({
+				type: "call",
+				id,
+				chatId,
+				sessionId: target,
+				calls: toolCalls,
+			}),
+			signal,
+		);
+		if ("toolResults" in result) {
+			await this.#ackInputs(target, result.inputs);
+			return {
+				sessionId: target,
+				toolResults: result.toolResults,
+				inputs: result.inputs,
+			};
+		}
+		throw new Error("Pi session returned no tool results");
+	}
+
+	async inputs(
+		chatId: string,
+		sessionId: string | undefined,
+		signal: AbortSignal,
+	): Promise<SessionInput[]> {
+		const target = sessionId ?? this.#state.binding(chatId);
+		if (!target) return [];
+		await this.#waitForSession(target, signal);
+		const { inputs } = await this.#inspect(target, signal);
+		await this.#ackInputs(target, inputs);
+		return inputs;
+	}
+
+	async readResource(uri: string, signal: AbortSignal): Promise<ResourceData> {
+		const sessionId = resourceSessionId(uri);
+		await this.#waitForSession(sessionId, signal);
+		const result = await this.#request(
+			sessionId,
+			(id) => ({ type: "readResource", id, sessionId, uri }),
+			signal,
+		);
+		if ("resource" in result) return result.resource;
+		throw new Error("Pi session returned no resource");
+	}
+
+	async deliveries(chatId: string): Promise<ResolvedDelivery[]> {
+		return Promise.all(this.#state.deliveries(chatId).map(resolveDelivery));
+	}
+
+	async acknowledgeDeliveries(
+		deliveries: DeliveryRecord[],
+		signal: AbortSignal,
+	): Promise<void> {
+		if (deliveries.length === 0) return;
+		if (signal.aborted) throw abortError(signal);
+		await this.#state.removeDeliveries(deliveries.map(({ id }) => id));
+		if (!signal.aborted) return;
+		await this.#state.restoreDeliveries(deliveries);
+		throw abortError(signal);
+	}
+
+	async #receive(
+		peer: JsonLinePeer<SessionMessage, BrokerMessage>,
+		message: SessionMessage,
+	): Promise<void> {
+		switch (message.type) {
+			case "sync": {
+				const previous = this.#sessions.get(message.session.id);
+				this.#sessions.set(message.session.id, {
+					description: message.session,
+					peer,
+				});
+				if (message.session.status === "ready") {
+					if (previous?.description.status !== "ready")
+						this.#ready.add(message.session.id);
+				} else {
+					this.#ready.delete(message.session.id);
+				}
+				this.#notifyChange();
+				await peer.send({
+					type: "synced",
+					id: message.id,
+					sessionId: message.session.id,
+				});
+				break;
+			}
+			case "unregister": {
+				const session = this.#sessions.get(message.sessionId);
+				if (session?.peer === peer) this.#removeSession(message.sessionId);
+				break;
+			}
+			case "delivery":
+				await this.#state.addDelivery(message.delivery);
+				await peer.send({ type: "stored", id: message.delivery.id });
+				break;
+			case "result": {
+				const pending = this.#pending.get(message.id);
+				if (!pending || pending.peer !== peer) break;
+				this.#finishRequest(message.id, pending);
+				if ("error" in message) pending.reject(new Error(message.error));
+				else {
+					const { type: _type, id: _id, ...result } = message;
+					pending.resolve(result);
+				}
+				break;
+			}
+		}
+	}
+
+	async #selectSession(
+		chatId: string,
+		requestedId: string | undefined,
+		signal: AbortSignal,
+		bindRequested: boolean,
+	): Promise<string> {
+		if (requestedId) {
+			await this.#waitForSession(requestedId, signal);
+			if (bindRequested && this.#state.binding(chatId) !== requestedId) {
+				await this.#state.setBinding(chatId, requestedId);
+				this.#notifyChange();
+			}
+			return requestedId;
+		}
+
+		const boundId = this.#state.binding(chatId);
+		if (boundId) {
+			await this.#waitForSession(boundId, signal);
+			return boundId;
+		}
+
+		for (;;) {
+			const occupied = this.#state.boundSessions();
+			const candidate = [...this.#ready].find(
+				(sessionId) =>
+					this.#sessions.has(sessionId) && !occupied.has(sessionId),
+			);
+			if (candidate) {
+				await this.#state.setBinding(chatId, candidate);
+				this.#notifyChange();
+				return candidate;
+			}
+			await this.#waitForChange(signal);
+		}
+	}
+
+	async #waitForSession(sessionId: string, signal: AbortSignal): Promise<void> {
+		while (!this.#sessions.has(sessionId)) await this.#waitForChange(signal);
+	}
+
+	async #inspect(
+		sessionId: string,
+		signal: AbortSignal,
+	): Promise<Extract<SessionResult, { inspection: SessionInspection }>> {
+		const result = await this.#request(
+			sessionId,
+			(id) => ({ type: "inspect", id, sessionId }),
+			signal,
+		);
+		if ("inspection" in result) return result;
+		throw new Error("Pi session returned no inspection");
+	}
+
+	async #ackInputs(sessionId: string, inputs: SessionInput[]): Promise<void> {
+		if (inputs.length === 0) return;
+		const session = this.#sessions.get(sessionId);
+		if (!session) throw new Error(`Pi session ${sessionId} is offline`);
+		await session.peer.send({
+			type: "ackInputs",
+			sessionId,
+			ids: inputs.map(({ id }) => id),
+		});
+	}
+
+	async #request(
+		sessionId: string,
+		message: (id: number) => BrokerMessage,
+		signal: AbortSignal,
+	): Promise<SessionResult> {
+		const session = this.#sessions.get(sessionId);
+		if (!session) throw new Error(`Pi session ${sessionId} is offline`);
+		if (signal.aborted) throw abortError(signal);
+		const id = this.#nextRequestId++;
+		const completion = Promise.withResolvers<SessionResult>();
+		const onAbort = (): void => {
+			const pending = this.#pending.get(id);
+			if (!pending) return;
+			void pending.peer.send({ type: "cancel", id, sessionId }).catch(() => {});
+			this.#finishRequest(id, pending);
+			pending.reject(abortError(signal));
+		};
+		const pending: PendingRequest = {
+			peer: session.peer,
+			resolve: completion.resolve,
+			reject: completion.reject,
+			signal,
+			onAbort,
+		};
+		this.#pending.set(id, pending);
+		signal.addEventListener("abort", onAbort, { once: true });
+		try {
+			await session.peer.send(message(id));
+		} catch (error) {
+			this.#finishRequest(id, pending);
+			throw error;
+		}
+		return completion.promise;
+	}
+
+	#waitForChange(signal: AbortSignal): Promise<void> {
+		if (signal.aborted) return Promise.reject(abortError(signal));
+		const completion = Promise.withResolvers<void>();
+		const onAbort = (): void => {
+			this.#waiters.delete(waiter);
+			waiter.reject(abortError(signal));
+		};
+		const waiter: ChangeWaiter = {
+			resolve: completion.resolve,
+			reject: completion.reject,
+			signal,
+			onAbort,
+		};
+		this.#waiters.add(waiter);
+		signal.addEventListener("abort", onAbort, { once: true });
+		return completion.promise;
+	}
+
+	#notifyChange(): void {
+		for (const waiter of this.#waiters) {
+			this.#waiters.delete(waiter);
+			waiter.signal.removeEventListener("abort", waiter.onAbort);
+			waiter.resolve();
+		}
+	}
+
+	#finishRequest(id: number, pending: PendingRequest): void {
+		this.#pending.delete(id);
+		pending.signal.removeEventListener("abort", pending.onAbort);
+	}
+
+	#removePeer(peer: JsonLinePeer<SessionMessage, BrokerMessage>): void {
+		for (const [sessionId, session] of this.#sessions) {
+			if (session.peer === peer) this.#removeSession(sessionId);
+		}
+		for (const [id, pending] of this.#pending) {
+			if (pending.peer !== peer) continue;
+			this.#finishRequest(id, pending);
+			pending.reject(new Error("Pi session disconnected"));
+		}
+	}
+
+	#removeSession(sessionId: string): void {
+		this.#sessions.delete(sessionId);
+		this.#ready.delete(sessionId);
+		this.#notifyChange();
+	}
+
+	async #readGlobalAgents(): Promise<string | undefined> {
+		try {
+			return await readFile(join(this.#agentDir, "AGENTS.md"), "utf8");
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+			throw error;
+		}
+	}
+}
+
+function abortError(signal: AbortSignal): Error {
+	return signal.reason instanceof Error
+		? signal.reason
+		: new Error("Request cancelled");
+}