@zetaloop/chappie 0.2.1 → 0.3.0

package/src/config.ts

@@ -0,0 +1,21 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import * as z from "zod";
+
+const configSchema = z.object({
+	ask: z.boolean().optional(),
+	connect: z.string().min(1).optional(),
+	latestWorkflow: z.boolean().optional(),
+	listen: z.union([z.boolean(), z.number().int().min(1).max(65535)]).optional(),
+});
+
+export async function readConfig(agentDir: string) {
+	let contents: string;
+	try {
+		contents = await readFile(join(agentDir, "chappie.json"), "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+		throw error;
+	}
+	return configSchema.parse(JSON.parse(contents));
+}

package/src/delivery.ts

@@ -1,4 +1,3 @@
-import { readFile } from "node:fs/promises";
 import type { ToolResultMessage } from "@earendil-works/pi-ai";
 import {
 	contentWithImageReferences,
@@ -10,48 +9,35 @@ export interface DeliveryRecord {
 	chatId: string;
 	sessionId: string;
 	cwd: string;
-	sessionFile?: string;
-	toolCallIds: string[];
-	inlineResults?: ToolResultMessage[];
-	error?: string;
-}
-
-export interface ResolvedDelivery extends DeliveryRecord {
 	toolResults: ToolResultMessage[];
+	error?: string;
 }
 
-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 toolResultsContent(
+	toolResults: ToolResultMessage[],
+	sessionId: string,
+) {
+	return toolResults.flatMap((result) => [
+		{
+			type: "text" as const,
+			text: JSON.stringify({
+				toolCallId: result.toolCallId,
+				toolName: result.toolName,
+				isError: result.isError,
+			}),
+		},
+		...contentWithImageReferences(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,
+		})),
+	]);
 }
 
-export function deliveryContent(deliveries: ResolvedDelivery[]) {
+export function deliveryContent(deliveries: DeliveryRecord[]) {
 	return deliveries.flatMap((delivery) => [
 		{
 			type: "text" as const,
@@ -62,23 +48,6 @@ export function deliveryContent(deliveries: ResolvedDelivery[]) {
 				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,
-			})),
-		]),
+		...toolResultsContent(delivery.toolResults, delivery.sessionId),
 	]);
 }

package/src/index.ts

@@ -19,16 +19,21 @@ export default async function chappie(pi: ExtensionAPI): Promise<void> {
 		}
 	}
 
-	const [{ createChappieProvider }, { LocalSession }, { transfer }] =
-		await Promise.all([
-			import("./provider.ts"),
-			import("./session.ts"),
-			import("./transfer.ts"),
-		]);
-	const session = new LocalSession(pi, getAgentDir());
+	const agentDir = getAgentDir();
+	const [
+		{ readConfig },
+		{ createChappieProvider },
+		{ LocalSession },
+		{ transfer },
+	] = await Promise.all([
+		import("./config.ts"),
+		import("./provider.ts"),
+		import("./session.ts"),
+		import("./transfer.ts"),
+	]);
+	const config = await readConfig(agentDir);
+	const session = new LocalSession(pi, agentDir, config.connect);
 	session.install();
 	pi.registerTool(transfer);
-	pi.registerProvider(
-		createChappieProvider((output, context) => session.start(output, context)),
-	);
+	pi.registerProvider(createChappieProvider((output) => session.start(output)));
 }

package/src/instructions.md

@@ -1,13 +1,15 @@
-Chappie connects this ChatGPT conversation to local Pi sessions. To continue existing work, call init with the Pi sessionId associated with that task in the context. A new chat or branch establishes its own binding to that ID. For a requested project or session without a known ID, use sessions to match its cwd or name, then init with the chosen ID. If the intended target is absent or ambiguous, resolve the selection with the user before starting work. Pi sessions register while the chappie/chatgpt provider is selected.
+Chappie connects this ChatGPT conversation to Pi sessions on one or more devices. Resume work with init using the task's Pi sessionId, including in a new chat or branch. When only a project or session name is known, find its device/cwd/name in sessions, then call init. If the target is absent or ambiguous, ask the user to resolve it. Pi sessions appear while the chappie/chatgpt provider is selected.
 
-For work without a specific target, init without sessionId reuses the current binding or allocates the first online session with bindingCount zero. These sessions may be blank or already contain a task. Saved bindings persist across broker restarts; explicit init(sessionId) can share a session already used by another chat. init reports its selection as existing, explicit, or automatic. A sessionId on any other tool affects only that operation.
+init sets this chat's default Pi session. For a task without a specified target, omitting sessionId reuses that default or selects the first online session with no saved bindings. These sessions may already contain work. Defaults survive broker restarts, and several chats can share one Pi session. Other tools' sessionId affects only that call.
 
 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.
 
-Use chat to display Markdown progress and final messages in Pi, including code examples. Use read, bash, edit, and write directly. init.tools lists Pi's native and extension tools for call; Chappie's init, sessions, tools, and chat are separate top-level MCP tools. Use tools with names to load complete definitions before calling other Pi tools. Use an installed interactive tool through call when input is needed in Pi. Separate calls remain separate Pi turns; use a call array when tools should share a batch.
+Respond promptly to new Pi user input with a substantive reply, interaction, or immediate action that makes the response apparent in Pi before continuing lengthy work. Address inputs received together in one response; an immediate answer or result serves as its own acknowledgment.
 
-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.
+Use chat for assistant messages in Pi, including progress, explanations, and results. Use read, bash, edit, write, and transfer directly. init.tools is a Pi tool catalog; tools returns full definitions for call. Invoke Chappie's MCP tools directly. Each call array is one native Pi batch; separate calls are separate Pi turns. For Pi interaction, call an installed interactive tool.
 
-Tool replies identify the executing sessionId and Pi cwd. A shell command can access another directory while its session and transcript remain the same. Replies provide their complete text in structuredContent.text, including user input consumed by Pi and results from an earlier explicitly cancelled request. Images and file resources accompany the text as native content blocks. Continue from those results instead of repeating completed work. Host request deadlines include queueing and execution; use local persistent-process facilities for work intended to outlive one request.
+transfer pairs files from ChatGPT with Pi destination paths in order. Omit files to return resource links for Pi paths or chappie:// image references. Relative paths use the Pi working directory; overwrite: true replaces existing targets. The host may request confirmation when retrieving exported bytes.
+
+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.

package/src/ipc.ts

@@ -20,13 +20,15 @@ import type {
 import type { DeliveryRecord } from "./delivery.ts";
 import type { ResourceData } from "./resources.ts";
 
+const defaultPort = 24274;
+
 export type SessionStatus = "idle" | "ready" | "executing";
 
 export interface SessionDescription {
 	id: string;
 	cwd: string;
+	device: string;
 	name?: string;
-	sessionFile?: string;
 	status: SessionStatus;
 }
 
@@ -43,7 +45,11 @@ export interface SessionInput {
 }
 
 export type SessionResult =
-	| { inspection: SessionInspection; inputs: SessionInput[] }
+	| {
+			inspection: SessionInspection;
+			inputs: SessionInput[];
+			globalAgents?: string;
+	  }
 	| { message: AssistantMessage; cwd: string; inputs: SessionInput[] }
 	| {
 			message: AssistantMessage;
@@ -63,6 +69,7 @@ export type SessionMessage =
 export type BrokerMessage =
 	| { type: "synced"; id: number; sessionId: string }
 	| { type: "stored"; id: string }
+	| { type: "notice"; sessionId: string; message: string }
 	| { type: "inspect"; id: number; sessionId: string }
 	| {
 			type: "chat";
@@ -78,7 +85,7 @@ export type BrokerMessage =
 			sessionId: string;
 			calls: ToolCall[];
 	  }
-	| { type: "cancel"; id: number; sessionId: string }
+	| { type: "cancel"; id: number; sessionId: string; reason: string }
 	| { type: "readResource"; id: number; sessionId: string; uri: string }
 	| { type: "ackInputs"; sessionId: string; ids: string[] };
 
@@ -172,7 +179,7 @@ export class IpcServer {
 		peer: JsonLinePeer<SessionMessage, BrokerMessage>,
 	) => void;
 	readonly #peers = new Set<JsonLinePeer<SessionMessage, BrokerMessage>>();
-	#server: Server | undefined;
+	readonly #servers = new Set<Server>();
 
 	constructor(
 		agentDir: string,
@@ -187,10 +194,34 @@ export class IpcServer {
 		this.#onClose = onClose;
 	}
 
-	async start(): Promise<void> {
-		if (this.#server) return;
+	async start(network: boolean | number = false): Promise<void> {
+		if (this.#servers.size > 0) return;
 		if (process.platform !== "win32") await prepareUnixSocket(this.#endpoint);
-		const server = createServer((socket) => {
+		try {
+			const local = this.#createServer();
+			await listenServer(local, this.#endpoint);
+			this.#servers.add(local);
+			if (!network) return;
+
+			const remote = this.#createServer();
+			await listenServer(remote, network === true ? defaultPort : network);
+			this.#servers.add(remote);
+		} catch (error) {
+			await this.close();
+			throw error;
+		}
+	}
+
+	async close(): Promise<void> {
+		for (const peer of this.#peers) peer.close();
+		this.#peers.clear();
+		const servers = [...this.#servers];
+		this.#servers.clear();
+		await Promise.all(servers.map(closeServer));
+	}
+
+	#createServer(): Server {
+		return createServer((socket) => {
 			let peer: JsonLinePeer<SessionMessage, BrokerMessage>;
 			peer = new JsonLinePeer(
 				socket,
@@ -202,25 +233,6 @@ export class IpcServer {
 			);
 			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())),
-		);
 	}
 }
 
@@ -232,14 +244,21 @@ interface ConnectionCallbacks {
 
 export class IpcClient {
 	readonly #endpoint: string;
+	readonly #remote: string | undefined;
 	readonly #callbacks: ConnectionCallbacks;
 	#peer: JsonLinePeer<BrokerMessage, SessionMessage> | undefined;
 	#opening: Promise<void> | undefined;
+	#controller: AbortController | undefined;
 	#retry: NodeJS.Timeout | undefined;
 	#closed = false;
 
-	constructor(agentDir: string, callbacks: ConnectionCallbacks) {
+	constructor(
+		agentDir: string,
+		remote: string | undefined,
+		callbacks: ConnectionCallbacks,
+	) {
 		this.#endpoint = ipcEndpoint(agentDir);
+		this.#remote = remote;
 		this.#callbacks = callbacks;
 	}
 
@@ -258,8 +277,11 @@ export class IpcClient {
 		if (this.#opening) return this.#opening;
 		clearTimeout(this.#retry);
 		this.#retry = undefined;
-		this.#opening = this.#open().finally(() => {
+		const controller = new AbortController();
+		this.#controller = controller;
+		this.#opening = this.#open(controller.signal).finally(() => {
 			this.#opening = undefined;
+			if (this.#controller === controller) this.#controller = undefined;
 		});
 		return this.#opening;
 	}
@@ -275,24 +297,25 @@ export class IpcClient {
 		this.#closed = true;
 		clearTimeout(this.#retry);
 		this.#retry = undefined;
+		this.#controller?.abort(new Error("Chappie IPC client is closed"));
+		this.#controller = 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();
+	async #open(signal: AbortSignal): Promise<void> {
+		let socket: Socket | undefined;
+		let failure = new Error("Chappie disconnected");
+		try {
+			socket = this.#remote
+				? createConnection(networkEndpoint(this.#remote))
+				: createConnection(this.#endpoint);
+			await connectSocket(socket, signal);
+		} catch (error) {
+			socket?.destroy();
 			this.#scheduleReconnect();
 			throw error;
-		});
+		}
 
 		let peer: JsonLinePeer<BrokerMessage, SessionMessage>;
 		peer = new JsonLinePeer(
@@ -327,6 +350,85 @@ export class IpcClient {
 	}
 }
 
+function listenServer(
+	server: Server,
+	endpoint: string | number,
+): Promise<void> {
+	return new Promise<void>((resolveListen, rejectListen) => {
+		const onError = (error: Error): void => {
+			server.off("listening", onListening);
+			rejectListen(error);
+		};
+		const onListening = (): void => {
+			server.off("error", onError);
+			resolveListen();
+		};
+		server.once("error", onError);
+		server.once("listening", onListening);
+		server.listen(endpoint);
+	});
+}
+
+function closeServer(server: Server): Promise<void> {
+	return new Promise<void>((resolveClose, rejectClose) =>
+		server.close((error) => (error ? rejectClose(error) : resolveClose())),
+	);
+}
+
+interface NetworkEndpoint {
+	host: string;
+	port: number;
+}
+
+function networkEndpoint(value: string): NetworkEndpoint {
+	const url = new URL(`tcp://${value}`);
+	if (url.username || url.password || url.pathname || url.search || url.hash)
+		throw new Error(`Invalid Chappie broker address: ${value}`);
+	const host = url.hostname.startsWith("[")
+		? url.hostname.slice(1, -1)
+		: url.hostname;
+	if (!host) throw new Error(`Invalid Chappie broker address: ${value}`);
+	return { host, port: url.port ? Number(url.port) : defaultPort };
+}
+
+function connectSocket(socket: Socket, signal: AbortSignal): Promise<void> {
+	return new Promise<void>((resolveConnect, rejectConnect) => {
+		const cleanup = (): void => {
+			signal.removeEventListener("abort", onAbort);
+			socket.off("connect", onConnect);
+			socket.off("error", onError);
+		};
+		const onConnect = (): void => {
+			cleanup();
+			resolveConnect();
+		};
+		const onError = (error: Error): void => {
+			cleanup();
+			rejectConnect(error);
+		};
+		const onAbort = (): void => {
+			cleanup();
+			socket.destroy();
+			rejectConnect(abortError(signal));
+		};
+		if (signal.aborted) {
+			onAbort();
+			return;
+		}
+		signal.addEventListener("abort", onAbort, { once: true });
+		socket.once("connect", onConnect);
+		socket.once("error", onError);
+	});
+}
+
+function abortError(signal: AbortSignal): Error {
+	return signal.reason instanceof Error
+		? signal.reason
+		: new Error(
+				typeof signal.reason === "string" ? signal.reason : "Request cancelled",
+			);
+}
+
 async function prepareUnixSocket(endpoint: string): Promise<void> {
 	try {
 		await lstat(endpoint);

package/src/provider.ts

@@ -147,19 +147,17 @@ export class ProviderOutput {
 }
 
 export function createChappieProvider(
-	start: (output: ProviderOutput, context: Context) => Promise<void>,
+	start: (output: ProviderOutput) => Promise<void>,
 ) {
 	const stream = (
 		model: Model<Api>,
-		context: Context,
+		_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),
-				);
+				void start(output).catch((error: unknown) => output.fail(error));
 			});
 		}
 		return output.stream;