@zetaloop/chappie 0.1.0

package/src/delivery.ts

@@ -0,0 +1,82 @@
+import { readFile } from "node:fs/promises";
+import type { ToolResultMessage } from "@earendil-works/pi-ai";
+import {
+	contentWithImageReferences,
+	resourceDescriptors,
+} from "./resources.ts";
+
+export interface DeliveryRecord {
+	id: string;
+	chatId: string;
+	sessionId: string;
+	sessionFile?: string;
+	toolCallIds: string[];
+	inlineResults?: ToolResultMessage[];
+	error?: string;
+}
+
+export interface ResolvedDelivery extends DeliveryRecord {
+	toolResults: ToolResultMessage[];
+}
+
+export async function resolveDelivery(
+	delivery: DeliveryRecord,
+): Promise<ResolvedDelivery> {
+	let toolResults = delivery.inlineResults ?? [];
+	if (delivery.sessionFile && delivery.toolCallIds.length > 0) {
+		const expected = new Set(delivery.toolCallIds);
+		const found = new Map<string, ToolResultMessage>();
+		for (const line of (await readFile(delivery.sessionFile, "utf8")).split(
+			"\n",
+		)) {
+			if (!line) continue;
+			const entry = JSON.parse(line) as {
+				type?: string;
+				message?: ToolResultMessage;
+			};
+			if (
+				entry.type === "message" &&
+				entry.message?.role === "toolResult" &&
+				expected.has(entry.message.toolCallId)
+			) {
+				found.set(entry.message.toolCallId, entry.message);
+			}
+		}
+		toolResults = delivery.toolCallIds.flatMap((id) => {
+			const result = found.get(id);
+			return result ? [result] : [];
+		});
+	}
+	return { ...delivery, toolResults };
+}
+
+export function deliveryContent(deliveries: ResolvedDelivery[]) {
+	return deliveries.flatMap((delivery) => [
+		{
+			type: "text" as const,
+			text: JSON.stringify({
+				deferredResult: delivery.id,
+				sessionId: delivery.sessionId,
+				error: delivery.error,
+			}),
+		},
+		...delivery.toolResults.flatMap((result) => [
+			{
+				type: "text" as const,
+				text: JSON.stringify({
+					toolCallId: result.toolCallId,
+					toolName: result.toolName,
+					isError: result.isError,
+				}),
+			},
+			...contentWithImageReferences(delivery.sessionId, result.content),
+			...resourceDescriptors(result.details).map((resource) => ({
+				type: "resource_link" as const,
+				uri: resource.uri,
+				name: resource.name,
+				mimeType: resource.mimeType,
+				size: resource.size,
+			})),
+		]),
+	]);
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+import {
+	type ExtensionAPI,
+	getAgentDir,
+} from "@earendil-works/pi-coding-agent";
+
+export default async function chappie(pi: ExtensionAPI): Promise<void> {
+	pi.registerFlag("chappie", {
+		description: "Serve Chappie over MCP",
+		type: "boolean",
+	});
+
+	if (process.argv.includes("--chappie")) {
+		try {
+			const { serveChappie } = await import("./stdio.ts");
+			await serveChappie();
+		} catch (error) {
+			console.error(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	}
+
+	const [{ createChappieProvider }, { LocalSession }, { transfer }] =
+		await Promise.all([
+			import("./provider.ts"),
+			import("./session.ts"),
+			import("./transfer.ts"),
+		]);
+	const session = new LocalSession(pi, getAgentDir());
+	session.install();
+	pi.registerTool(transfer);
+	pi.registerProvider(
+		createChappieProvider((output, context) => session.start(output, context)),
+	);
+}

package/src/instructions.md

@@ -0,0 +1,7 @@
+Chappie connects this ChatGPT conversation to local Pi sessions. Call init before starting work. Omitting sessionId reuses the current binding or pairs with the next Pi session waiting for ChatGPT; specifying sessionId on init selects that Pi session as the new default. A sessionId on any other tool affects only that operation. Use sessions to inspect connected sessions without changing the binding.
+
+Use chat to send one complete assistant message to Pi. Use read, bash, edit, and write directly. Use tools to inspect other active Pi tools and call to execute one or more of them as one native Pi batch. Separate calls remain separate Pi turns; use a call array when tools should share a batch.
+
+Use transfer with paths and files to copy ChatGPT files into Pi. Omit files to expose existing Pi paths or chappie:// image references as MCP resources. Relative paths use the Pi working directory, existing targets require overwrite: true, and resource materialization may require host confirmation.
+
+Tool replies may contain user input consumed by Pi or results from an earlier explicitly cancelled request. Continue from those results instead of repeating completed work. Use the local persistent-process facilities for operations that need to outlive one tool request.

package/src/ipc.ts

@@ -0,0 +1,361 @@
+import { createHash } from "node:crypto";
+import { lstat, unlink } from "node:fs/promises";
+import {
+	createConnection,
+	createServer,
+	type Server,
+	type Socket,
+} from "node:net";
+import { join, resolve } from "node:path";
+import type {
+	AssistantMessage,
+	ToolCall,
+	ToolResultMessage,
+	UserMessage,
+} from "@earendil-works/pi-ai";
+import type {
+	SlashCommandInfo,
+	ToolInfo,
+} from "@earendil-works/pi-coding-agent";
+import type { DeliveryRecord } from "./delivery.ts";
+import type { ResourceData } from "./resources.ts";
+
+export type SessionStatus = "idle" | "ready" | "executing";
+
+export interface SessionDescription {
+	id: string;
+	cwd: string;
+	name?: string;
+	sessionFile?: string;
+	status: SessionStatus;
+}
+
+export interface SessionInspection {
+	session: SessionDescription;
+	tools: ToolInfo[];
+	skills: SlashCommandInfo[];
+}
+
+export interface SessionInput {
+	id: string;
+	sessionId: string;
+	message: UserMessage;
+}
+
+export type SessionResult =
+	| { inspection: SessionInspection; inputs: SessionInput[] }
+	| { message: AssistantMessage; inputs: SessionInput[] }
+	| {
+			message: AssistantMessage;
+			toolResults: ToolResultMessage[];
+			inputs: SessionInput[];
+	  }
+	| { resource: ResourceData }
+	| { error: string };
+
+export type SessionMessage =
+	| { type: "sync"; id: number; session: SessionDescription }
+	| { type: "unregister"; sessionId: string }
+	| { type: "delivery"; delivery: DeliveryRecord }
+	| ({ type: "result"; id: number } & SessionResult);
+
+export type BrokerMessage =
+	| { type: "synced"; id: number; sessionId: string }
+	| { type: "stored"; id: string }
+	| { type: "inspect"; id: number; sessionId: string }
+	| {
+			type: "chat";
+			id: number;
+			chatId: string;
+			sessionId: string;
+			text: string;
+	  }
+	| {
+			type: "call";
+			id: number;
+			chatId: string;
+			sessionId: string;
+			calls: ToolCall[];
+	  }
+	| { type: "cancel"; id: number; sessionId: string }
+	| { type: "readResource"; id: number; sessionId: string; uri: string }
+	| { type: "ackInputs"; sessionId: string; ids: string[] };
+
+export function ipcEndpoint(agentDir: string): string {
+	const directory = resolve(agentDir);
+	if (process.platform !== "win32") return join(directory, "chappie.sock");
+	const identity = directory.replaceAll("\\", "/").toLowerCase();
+	return String.raw`\\.\pipe\chappie-${createHash("sha256").update(identity).digest("hex").slice(0, 16)}`;
+}
+
+export class JsonLinePeer<Incoming, Outgoing> {
+	readonly #socket: Socket;
+	readonly #onMessage: (message: Incoming) => Promise<void> | void;
+	readonly #onClose: () => void;
+	#buffer = "";
+	#messages = Promise.resolve();
+	#writes = Promise.resolve();
+	#closed = false;
+
+	constructor(
+		socket: Socket,
+		onMessage: (message: Incoming) => Promise<void> | void,
+		onClose: () => void,
+	) {
+		this.#socket = socket;
+		this.#onMessage = onMessage;
+		this.#onClose = onClose;
+		socket.setEncoding("utf8");
+		socket.on("data", (chunk: string) => this.#receive(chunk));
+		socket.once("close", () => {
+			this.#closed = true;
+			this.#onClose();
+		});
+		socket.on("error", () => {});
+	}
+
+	get closed(): boolean {
+		return this.#closed;
+	}
+
+	send(message: Outgoing): Promise<void> {
+		const line = `${JSON.stringify(message)}\n`;
+		const sent = this.#writes.then(
+			() =>
+				new Promise<void>((resolveWrite, rejectWrite) => {
+					if (this.#closed) {
+						rejectWrite(new Error("Chappie IPC connection is closed"));
+						return;
+					}
+					this.#socket.write(line, (error) => {
+						if (error) rejectWrite(error);
+						else resolveWrite();
+					});
+				}),
+		);
+		this.#writes = sent.catch(() => {});
+		return sent;
+	}
+
+	close(): void {
+		if (!this.#closed) this.#socket.end();
+	}
+
+	#receive(chunk: string): void {
+		this.#buffer += chunk;
+		let end = this.#buffer.indexOf("\n");
+		while (end !== -1) {
+			const line = this.#buffer.slice(0, end);
+			this.#buffer = this.#buffer.slice(end + 1);
+			if (line.length > 0) {
+				this.#messages = this.#messages
+					.then(() => this.#onMessage(JSON.parse(line) as Incoming))
+					.catch((error: unknown) => {
+						this.#socket.destroy(
+							error instanceof Error ? error : new Error(String(error)),
+						);
+					});
+			}
+			end = this.#buffer.indexOf("\n");
+		}
+	}
+}
+
+export class IpcServer {
+	readonly #endpoint: string;
+	readonly #onMessage: (
+		peer: JsonLinePeer<SessionMessage, BrokerMessage>,
+		message: SessionMessage,
+	) => Promise<void> | void;
+	readonly #onClose: (
+		peer: JsonLinePeer<SessionMessage, BrokerMessage>,
+	) => void;
+	readonly #peers = new Set<JsonLinePeer<SessionMessage, BrokerMessage>>();
+	#server: Server | undefined;
+
+	constructor(
+		agentDir: string,
+		onMessage: (
+			peer: JsonLinePeer<SessionMessage, BrokerMessage>,
+			message: SessionMessage,
+		) => Promise<void> | void,
+		onClose: (peer: JsonLinePeer<SessionMessage, BrokerMessage>) => void,
+	) {
+		this.#endpoint = ipcEndpoint(agentDir);
+		this.#onMessage = onMessage;
+		this.#onClose = onClose;
+	}
+
+	async start(): Promise<void> {
+		if (this.#server) return;
+		if (process.platform !== "win32") await prepareUnixSocket(this.#endpoint);
+		const server = createServer((socket) => {
+			let peer: JsonLinePeer<SessionMessage, BrokerMessage>;
+			peer = new JsonLinePeer(
+				socket,
+				(message) => this.#onMessage(peer, message),
+				() => {
+					this.#peers.delete(peer);
+					this.#onClose(peer);
+				},
+			);
+			this.#peers.add(peer);
+		});
+		await new Promise<void>((resolveListen, rejectListen) => {
+			server.once("error", rejectListen);
+			server.listen(this.#endpoint, () => {
+				server.off("error", rejectListen);
+				resolveListen();
+			});
+		});
+		this.#server = server;
+	}
+
+	async close(): Promise<void> {
+		for (const peer of this.#peers) peer.close();
+		this.#peers.clear();
+		const server = this.#server;
+		this.#server = undefined;
+		if (!server) return;
+		await new Promise<void>((resolveClose, rejectClose) =>
+			server.close((error) => (error ? rejectClose(error) : resolveClose())),
+		);
+	}
+}
+
+interface ConnectionCallbacks {
+	onOpen(): Promise<void> | void;
+	onMessage(message: BrokerMessage): Promise<void> | void;
+	onClose(error: Error): void;
+}
+
+export class IpcClient {
+	readonly #endpoint: string;
+	readonly #callbacks: ConnectionCallbacks;
+	#peer: JsonLinePeer<BrokerMessage, SessionMessage> | undefined;
+	#opening: Promise<void> | undefined;
+	#retry: NodeJS.Timeout | undefined;
+	#closed = false;
+
+	constructor(agentDir: string, callbacks: ConnectionCallbacks) {
+		this.#endpoint = ipcEndpoint(agentDir);
+		this.#callbacks = callbacks;
+	}
+
+	get connected(): boolean {
+		return this.#peer !== undefined && !this.#peer.closed;
+	}
+
+	start(): void {
+		void this.connect().catch(() => {});
+	}
+
+	connect(): Promise<void> {
+		if (this.#closed)
+			return Promise.reject(new Error("Chappie IPC client is closed"));
+		if (this.connected) return Promise.resolve();
+		if (this.#opening) return this.#opening;
+		clearTimeout(this.#retry);
+		this.#retry = undefined;
+		this.#opening = this.#open().finally(() => {
+			this.#opening = undefined;
+		});
+		return this.#opening;
+	}
+
+	send(message: SessionMessage): Promise<void> {
+		const peer = this.#peer;
+		if (!peer || peer.closed)
+			return Promise.reject(new Error("Chappie broker is not running"));
+		return peer.send(message);
+	}
+
+	close(): void {
+		this.#closed = true;
+		clearTimeout(this.#retry);
+		this.#retry = undefined;
+		this.#peer?.close();
+		this.#peer = undefined;
+	}
+
+	async #open(): Promise<void> {
+		const socket = createConnection(this.#endpoint);
+		let failure = new Error("Chappie broker connection ended");
+		await new Promise<void>((resolveOpen, rejectOpen) => {
+			socket.once("connect", resolveOpen);
+			socket.once("error", (error) => {
+				failure = error;
+				rejectOpen(error);
+			});
+		}).catch((error: unknown) => {
+			socket.destroy();
+			this.#scheduleReconnect();
+			throw error;
+		});
+
+		let peer: JsonLinePeer<BrokerMessage, SessionMessage>;
+		peer = new JsonLinePeer(
+			socket,
+			(message) => this.#callbacks.onMessage(message),
+			() => {
+				if (this.#peer !== peer) return;
+				this.#peer = undefined;
+				if (!this.#closed) {
+					this.#callbacks.onClose(failure);
+					this.#scheduleReconnect();
+				}
+			},
+		);
+		this.#peer = peer;
+		try {
+			await this.#callbacks.onOpen();
+		} catch (error) {
+			failure = error instanceof Error ? error : new Error(String(error));
+			peer.close();
+			throw failure;
+		}
+	}
+
+	#scheduleReconnect(): void {
+		if (this.#closed || this.#retry) return;
+		this.#retry = setTimeout(() => {
+			this.#retry = undefined;
+			void this.connect().catch(() => {});
+		}, 500);
+		this.#retry.unref();
+	}
+}
+
+async function prepareUnixSocket(endpoint: string): Promise<void> {
+	try {
+		await lstat(endpoint);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+		throw error;
+	}
+
+	if (await endpointAcceptsConnections(endpoint)) {
+		const error = new Error(
+			`Chappie broker is already listening at ${endpoint}`,
+		) as NodeJS.ErrnoException;
+		error.code = "EADDRINUSE";
+		throw error;
+	}
+	await unlink(endpoint);
+}
+
+function endpointAcceptsConnections(endpoint: string): Promise<boolean> {
+	return new Promise<boolean>((resolveProbe, rejectProbe) => {
+		const socket = createConnection(endpoint);
+		socket.once("connect", () => {
+			socket.end();
+			resolveProbe(true);
+		});
+		socket.once("error", (error: NodeJS.ErrnoException) => {
+			socket.destroy();
+			if (error.code === "ECONNREFUSED" || error.code === "ENOENT")
+				resolveProbe(false);
+			else rejectProbe(error);
+		});
+	});
+}

package/src/provider.ts

@@ -0,0 +1,195 @@
+import {
+	type Api,
+	type AssistantMessage,
+	type AssistantMessageEventStream,
+	type Context,
+	createAssistantMessageEventStream,
+	createProvider,
+	type Model,
+	type StreamOptions,
+	type ToolCall,
+} from "@earendil-works/pi-ai";
+
+export class ProviderOutput {
+	readonly stream: AssistantMessageEventStream;
+	readonly message: AssistantMessage;
+	readonly finished: Promise<void>;
+	#resolveFinished: () => void;
+	#removeAbort?: () => void;
+	#started = false;
+	#closed = false;
+
+	constructor(model: Model<Api>, signal?: AbortSignal) {
+		this.stream = createAssistantMessageEventStream();
+		this.message = {
+			role: "assistant",
+			content: [],
+			api: model.api,
+			provider: model.provider,
+			model: model.id,
+			usage: {
+				input: 0,
+				output: 0,
+				cacheRead: 0,
+				cacheWrite: 0,
+				totalTokens: 0,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+			},
+			stopReason: "pending",
+			timestamp: Date.now(),
+		};
+		const completion = Promise.withResolvers<void>();
+		this.finished = completion.promise;
+		this.#resolveFinished = completion.resolve;
+		if (signal) {
+			const abort = (): void =>
+				this.fail(new Error("Chappie provider request was cancelled"), true);
+			signal.addEventListener("abort", abort, { once: true });
+			this.#removeAbort = () => signal.removeEventListener("abort", abort);
+			if (signal.aborted) abort();
+		}
+	}
+
+	get closed(): boolean {
+		return this.#closed;
+	}
+
+	begin(): void {
+		if (this.#started || this.#closed) return;
+		this.#started = true;
+		this.stream.push({ type: "start", partial: this.message });
+	}
+
+	text(text: string): void {
+		if (this.#closed)
+			throw new Error("Chappie provider response is already complete");
+		this.begin();
+		const contentIndex = this.message.content.length;
+		const block = { type: "text" as const, text: "" };
+		this.message.content.push(block);
+		this.stream.push({
+			type: "text_start",
+			contentIndex,
+			partial: this.message,
+		});
+		block.text = text;
+		this.stream.push({
+			type: "text_delta",
+			contentIndex,
+			delta: text,
+			partial: this.message,
+		});
+		this.stream.push({
+			type: "text_end",
+			contentIndex,
+			content: text,
+			partial: this.message,
+		});
+	}
+
+	toolCalls(calls: ToolCall[]): void {
+		if (this.#closed)
+			throw new Error("Chappie provider response is already complete");
+		this.begin();
+		for (const call of calls) {
+			const contentIndex = this.message.content.length;
+			const block: ToolCall = { ...call, arguments: {} };
+			this.message.content.push(block);
+			this.stream.push({
+				type: "toolcall_start",
+				contentIndex,
+				partial: this.message,
+			});
+			block.arguments = call.arguments;
+			this.stream.push({
+				type: "toolcall_delta",
+				contentIndex,
+				delta: JSON.stringify(call.arguments),
+				partial: this.message,
+			});
+			this.stream.push({
+				type: "toolcall_end",
+				contentIndex,
+				toolCall: block,
+				partial: this.message,
+			});
+		}
+	}
+
+	done(reason: "stop" | "toolUse" = "stop"): void {
+		if (this.#closed) return;
+		this.begin();
+		this.message.stopReason = reason;
+		this.stream.push({ type: "done", reason, message: this.message });
+		this.#finish();
+	}
+
+	fail(error: unknown, aborted = false): void {
+		if (this.#closed) return;
+		this.begin();
+		this.message.stopReason = aborted ? "aborted" : "error";
+		this.message.errorMessage =
+			error instanceof Error ? error.message : String(error);
+		this.stream.push({
+			type: "error",
+			reason: this.message.stopReason,
+			error: this.message,
+		});
+		this.#finish();
+	}
+
+	#finish(): void {
+		this.#closed = true;
+		this.#removeAbort?.();
+		this.stream.end();
+		this.#resolveFinished();
+	}
+}
+
+export function createChappieProvider(
+	start: (output: ProviderOutput, context: Context) => Promise<void>,
+) {
+	const stream = (
+		model: Model<Api>,
+		context: Context,
+		options?: StreamOptions,
+	) => {
+		const output = new ProviderOutput(model, options?.signal);
+		if (!output.closed) {
+			queueMicrotask(() => {
+				void start(output, context).catch((error: unknown) =>
+					output.fail(error),
+				);
+			});
+		}
+		return output.stream;
+	};
+
+	return createProvider({
+		id: "chappie",
+		name: "Chappie",
+		auth: {
+			apiKey: {
+				name: "Local Chappie",
+				async resolve() {
+					return { auth: { headers: {} }, source: "local" };
+				},
+			},
+		},
+		models: [
+			{
+				id: "chatgpt",
+				name: "ChatGPT",
+				api: "chappie",
+				provider: "chappie",
+				baseUrl: "",
+				reasoning: false,
+				input: ["text", "image"],
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+				contextWindow: 1_000_000_000,
+				maxTokens: 1_000_000_000,
+			},
+		],
+		api: { stream, streamSimple: stream },
+	});
+}