@zetaloop/chappie 0.2.0 → 0.3.0

package/src/broker.ts

@@ -1,12 +1,7 @@
 import { randomUUID } from "node:crypto";
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
 import type { ToolCall, ToolResultMessage } from "@earendil-works/pi-ai";
-import {
-	type DeliveryRecord,
-	type ResolvedDelivery,
-	resolveDelivery,
-} from "./delivery.ts";
+import { readConfig } from "./config.ts";
+import type { DeliveryRecord } from "./delivery.ts";
 import {
 	type BrokerMessage,
 	IpcServer,
@@ -17,6 +12,13 @@ import {
 	type SessionMessage,
 	type SessionResult,
 } from "./ipc.ts";
+import {
+	type Question,
+	type QuestionAnswer,
+	type QuestionInput,
+	type QuestionRecord,
+	questionView,
+} from "./questions.ts";
 import { type ResourceData, resourceSessionId } from "./resources.ts";
 import { State } from "./state.ts";
 import type { ToolInput } from "./tools.ts";
@@ -34,6 +36,11 @@ interface PendingRequest {
 	onAbort(): void;
 }
 
+interface Workflow {
+	id: string;
+	controller: AbortController;
+}
+
 interface ChangeWaiter {
 	resolve(): void;
 	reject(error: Error): void;
@@ -42,6 +49,7 @@ interface ChangeWaiter {
 }
 
 export interface InitializedSession extends Omit<SessionInspection, "tools"> {
+	selection: "existing" | "explicit" | "automatic";
 	globalAgents?: string;
 	inputs: SessionInput[];
 	tools: { name: string; description: string }[];
@@ -53,11 +61,13 @@ export interface InspectedSession extends SessionInspection {
 
 export interface ChatResult {
 	sessionId: string;
+	cwd: string;
 	inputs: SessionInput[];
 }
 
 export interface CallResult {
 	sessionId: string;
+	cwd: string;
 	toolResults: ToolResultMessage[];
 	inputs: SessionInput[];
 }
@@ -69,6 +79,9 @@ export class Broker {
 	readonly #sessions = new Map<string, RegisteredSession>();
 	readonly #pending = new Map<number, PendingRequest>();
 	readonly #waiters = new Set<ChangeWaiter>();
+	readonly #workflows = new Map<string, Workflow>();
+	#ask = true;
+	#latestWorkflow = false;
 	#nextRequestId = 1;
 
 	constructor(agentDir: string) {
@@ -82,12 +95,19 @@ export class Broker {
 	}
 
 	async start(): Promise<void> {
+		const config = await readConfig(this.#agentDir);
+		this.#ask = config.ask ?? true;
+		this.#latestWorkflow = config.latestWorkflow ?? false;
 		await this.#state.load();
-		await this.#ipc.start();
+		await this.#ipc.start(config.listen ?? false);
 	}
 
 	async close(): Promise<void> {
 		const error = new Error("Chappie broker ended");
+		for (const workflow of this.#workflows.values()) {
+			workflow.controller.abort(error);
+		}
+		this.#workflows.clear();
 		for (const [id, pending] of this.#pending) {
 			this.#finishRequest(id, pending);
 			pending.reject(error);
@@ -101,12 +121,53 @@ export class Broker {
 		await this.#ipc.close();
 	}
 
-	listSessions(sessionId?: string): SessionDescription[] {
-		if (sessionId) {
-			const session = this.#sessions.get(sessionId);
-			return session ? [session.description] : [];
+	async workflow(
+		chatId: string | undefined,
+		requestId: unknown,
+		signal: AbortSignal,
+	): Promise<AbortSignal> {
+		if (!this.#latestWorkflow || !chatId) return signal;
+		const id =
+			typeof requestId === "string"
+				? /^wfr_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}(?=\/|$)/i
+						.exec(requestId)?.[0]
+						.toLowerCase()
+				: undefined;
+		if (!id) return signal;
+		signal.throwIfAborted();
+		const latest = this.#state.workflow(chatId);
+		const superseded = new Error(
+			"A newer workflow is handling this chat. Stop this workflow.",
+		);
+		// UUIDv7 puts the creation timestamp first, including across broker restarts.
+		if (latest && id < latest) throw superseded;
+		let workflow = this.#workflows.get(chatId);
+		if (!workflow || workflow.id !== id) {
+			const previous = workflow;
+			workflow = { id, controller: new AbortController() };
+			this.#workflows.set(chatId, workflow);
+			previous?.controller.abort(superseded);
+			if (latest !== id) await this.#state.setWorkflow(chatId, id);
 		}
-		return [...this.#sessions.values()].map(({ description }) => description);
+		const combined = AbortSignal.any([signal, workflow.controller.signal]);
+		combined.throwIfAborted();
+		return combined;
+	}
+
+	listSessions(
+		sessionId?: string,
+	): (SessionDescription & { bindingCount: number })[] {
+		const counts = this.#state.bindingCounts();
+		return [...this.#sessions.values()]
+			.filter(({ description }) => !sessionId || description.id === sessionId)
+			.map(({ description }) => ({
+				...description,
+				bindingCount: counts.get(description.id) ?? 0,
+			}));
+	}
+
+	get askEnabled(): boolean {
+		return this.#ask;
 	}
 
 	binding(chatId: string): string | undefined {
@@ -118,11 +179,22 @@ export class Broker {
 		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();
+		const previous = this.#state.binding(chatId);
+		const { sessionId: target, selection } = await this.#selectSession(
+			chatId,
+			sessionId,
+			signal,
+			true,
+		);
+		if (previous === target)
+			await this.#notify(target, `ChatGPT ${chatId.slice(-4)} joined`);
+		const { inspection, inputs, globalAgents } = await this.#inspect(
+			target,
+			signal,
+		);
 		await this.#ackInputs(target, inputs);
 		return {
+			selection,
 			...inspection,
 			tools: inspection.tools.map(({ name, description }) => ({
 				name,
@@ -139,7 +211,12 @@ export class Broker {
 		text: string,
 		signal: AbortSignal,
 	): Promise<ChatResult> {
-		const target = await this.#selectSession(chatId, sessionId, signal, false);
+		const { sessionId: target } = await this.#selectSession(
+			chatId,
+			sessionId,
+			signal,
+			false,
+		);
 		const result = await this.#request(
 			target,
 			(id) => ({ type: "chat", id, chatId, sessionId: target, text }),
@@ -147,7 +224,7 @@ export class Broker {
 		);
 		if ("message" in result) {
 			await this.#ackInputs(target, result.inputs);
-			return { sessionId: target, inputs: result.inputs };
+			return { sessionId: target, cwd: result.cwd, inputs: result.inputs };
 		}
 		throw new Error("Pi session returned no assistant message");
 	}
@@ -158,7 +235,12 @@ export class Broker {
 		names: string[] | undefined,
 		signal: AbortSignal,
 	): Promise<InspectedSession> {
-		const target = await this.#selectSession(chatId, sessionId, signal, false);
+		const { sessionId: target } = await this.#selectSession(
+			chatId,
+			sessionId,
+			signal,
+			false,
+		);
 		const { inspection, inputs } = await this.#inspect(target, signal);
 		await this.#ackInputs(target, inputs);
 		const selected = names ? new Set(names) : undefined;
@@ -177,7 +259,12 @@ export class Broker {
 		calls: ToolInput[],
 		signal: AbortSignal,
 	): Promise<CallResult> {
-		const target = await this.#selectSession(chatId, sessionId, signal, false);
+		const { sessionId: target } = await this.#selectSession(
+			chatId,
+			sessionId,
+			signal,
+			false,
+		);
 		const toolCalls: ToolCall[] = calls.map((call) => ({
 			type: "toolCall",
 			id: `chappie-${randomUUID()}`,
@@ -199,6 +286,7 @@ export class Broker {
 			await this.#ackInputs(target, result.inputs);
 			return {
 				sessionId: target,
+				cwd: result.cwd,
 				toolResults: result.toolResults,
 				inputs: result.inputs,
 			};
@@ -218,6 +306,88 @@ export class Broker {
 		return inputs;
 	}
 
+	async ask(
+		chatId: string,
+		sessionId: string | undefined,
+		input: QuestionInput,
+		signal: AbortSignal,
+	): Promise<Question> {
+		const { sessionId: target } = await this.#selectSession(
+			chatId,
+			sessionId,
+			signal,
+			false,
+		);
+		const session = this.#sessions.get(target);
+		if (!session) throw new Error(`Pi session ${target} is offline`);
+		const question: QuestionRecord = {
+			...input,
+			id: randomUUID(),
+			chatId,
+			sessionId: target,
+			cwd: session.description.cwd,
+			delivered: false,
+		};
+		await this.#state.addQuestion(question);
+		void this.#notify(
+			target,
+			`ChatGPT ${chatId.slice(-4)} asked: ${question.question}`,
+		).catch(() => {});
+		return questionView(question);
+	}
+
+	async assertQuestion(
+		chatId: string,
+		id: string,
+		signal: AbortSignal,
+	): Promise<Question> {
+		for (;;) {
+			signal.throwIfAborted();
+			const question = this.#state.question(chatId, id);
+			if (question.loaded) return questionView(question);
+			await this.#waitForChange(signal);
+		}
+	}
+
+	async answer(
+		chatId: string,
+		id: string,
+		answer?: QuestionAnswer,
+		loaded = false,
+	): Promise<Question> {
+		let question = this.#state.question(chatId, id);
+		if ((loaded || answer) && !question.loaded) {
+			question = { ...question, loaded: true };
+			await this.#state.addQuestion(question);
+			this.#notifyChange();
+		}
+		if (answer) {
+			const previous = question.answer;
+			question = await this.#state.answer(chatId, id, answer);
+			if (question.answer !== previous) {
+				const response = [
+					...(question.answer?.selections ?? []).map(
+						(index) => question.options[index]?.title,
+					),
+					question.answer?.text,
+				]
+					.filter(Boolean)
+					.join(", ");
+				const message = question.answer?.skipped
+					? `Skipped in ChatGPT ${chatId.slice(-4)}: ${question.question}`
+					: previous
+						? `Answer updated in ChatGPT ${chatId.slice(-4)}: ${question.question} — ${response}`
+						: `Answered in ChatGPT ${chatId.slice(-4)}: ${question.question} — ${response}`;
+				void this.#notify(question.sessionId, message).catch(() => {});
+			}
+		}
+		return questionView(question);
+	}
+
+	answers(chatId: string): QuestionRecord[] {
+		return this.#state.answers(chatId);
+	}
+
 	async readResource(uri: string, signal: AbortSignal): Promise<ResourceData> {
 		const sessionId = resourceSessionId(uri);
 		await this.#waitForSession(sessionId, signal);
@@ -230,20 +400,16 @@ export class Broker {
 		throw new Error("Pi session returned no resource");
 	}
 
-	async deliveries(chatId: string): Promise<ResolvedDelivery[]> {
-		return Promise.all(this.#state.deliveries(chatId).map(resolveDelivery));
+	deliveries(chatId: string): DeliveryRecord[] {
+		return this.#state.deliveries(chatId);
 	}
 
-	async acknowledgeDeliveries(
+	acknowledge(
 		deliveries: DeliveryRecord[],
+		answers: QuestionRecord[],
 		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);
+		return this.#state.acknowledge(deliveries, answers, signal);
 	}
 
 	async #receive(
@@ -252,16 +418,20 @@ export class Broker {
 	): Promise<void> {
 		switch (message.type) {
 			case "sync": {
+				const registered =
+					this.#sessions.get(message.session.id)?.peer === peer;
 				this.#sessions.set(message.session.id, {
 					description: message.session,
 					peer,
 				});
-				this.#notifyChange();
 				await peer.send({
 					type: "synced",
 					id: message.id,
 					sessionId: message.session.id,
 				});
+				if (!registered)
+					await this.#notify(message.session.id, "Chappie connected");
+				this.#notifyChange();
 				break;
 			}
 			case "unregister": {
@@ -292,36 +462,56 @@ export class Broker {
 		requestedId: string | undefined,
 		signal: AbortSignal,
 		bindRequested: boolean,
-	): Promise<string> {
+	): Promise<{
+		sessionId: string;
+		selection: InitializedSession["selection"];
+	}> {
 		if (requestedId) {
 			await this.#waitForSession(requestedId, signal);
 			if (bindRequested && this.#state.binding(chatId) !== requestedId) {
-				await this.#state.setBinding(chatId, requestedId);
-				this.#notifyChange();
+				await this.#bind(chatId, requestedId);
 			}
-			return requestedId;
+			return { sessionId: requestedId, selection: "explicit" };
 		}
 
 		const boundId = this.#state.binding(chatId);
 		if (boundId) {
 			await this.#waitForSession(boundId, signal);
-			return boundId;
+			return { sessionId: boundId, selection: "existing" };
 		}
 
 		for (;;) {
-			const occupied = this.#state.boundSessions();
+			const occupied = this.#state.bindingCounts();
 			const candidate = [...this.#sessions.keys()].find(
 				(sessionId) => !occupied.has(sessionId),
 			);
 			if (candidate) {
-				await this.#state.setBinding(chatId, candidate);
-				this.#notifyChange();
-				return candidate;
+				await this.#bind(chatId, candidate);
+				return { sessionId: candidate, selection: "automatic" };
 			}
 			await this.#waitForChange(signal);
 		}
 	}
 
+	async #bind(chatId: string, sessionId: string): Promise<void> {
+		const previous = this.#state.binding(chatId);
+		await this.#state.setBinding(chatId, sessionId);
+		this.#notifyChange();
+		if (previous) {
+			await this.#notify(previous, `ChatGPT ${chatId.slice(-4)} left`);
+			if (this.#state.chats(previous).length === 0) {
+				await this.#notify(previous, "Ready for ChatGPT");
+			}
+		}
+		await this.#notify(sessionId, `ChatGPT ${chatId.slice(-4)} joined`);
+	}
+
+	async #notify(sessionId: string, message: string): Promise<void> {
+		await this.#sessions
+			.get(sessionId)
+			?.peer.send({ type: "notice", sessionId, message });
+	}
+
 	async #waitForSession(sessionId: string, signal: AbortSignal): Promise<void> {
 		while (!this.#sessions.has(sessionId)) await this.#waitForChange(signal);
 	}
@@ -363,7 +553,14 @@ export class Broker {
 		const onAbort = (): void => {
 			const pending = this.#pending.get(id);
 			if (!pending) return;
-			void pending.peer.send({ type: "cancel", id, sessionId }).catch(() => {});
+			void pending.peer
+				.send({
+					type: "cancel",
+					id,
+					sessionId,
+					reason: abortError(signal).message,
+				})
+				.catch(() => {});
 			this.#finishRequest(id, pending);
 			pending.reject(abortError(signal));
 		};
@@ -431,19 +628,12 @@ export class Broker {
 		this.#sessions.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");
+		: new Error(
+				typeof signal.reason === "string" ? signal.reason : "Request cancelled",
+			);
 }

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,
@@ -9,74 +8,46 @@ export interface DeliveryRecord {
 	id: string;
 	chatId: string;
 	sessionId: string;
-	sessionFile?: string;
-	toolCallIds: string[];
-	inlineResults?: ToolResultMessage[];
-	error?: string;
-}
-
-export interface ResolvedDelivery extends DeliveryRecord {
+	cwd: string;
 	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,
 			text: JSON.stringify({
 				deferredResult: delivery.id,
 				sessionId: delivery.sessionId,
+				cwd: delivery.cwd,
 				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,11 +1,15 @@
-Chappie connects this ChatGPT conversation to local Pi sessions. Call init before starting work. Omitting sessionId reuses the current binding or pairs with the first online, unbound Pi session; 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.
+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.
+
+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 send progress and final messages that should appear in Pi. Use read, bash, edit, and write directly. init lists active tools with short descriptions; call tools with their names to load complete definitions before using other Pi tools through call. 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 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.
 
-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.
+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 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. Host request deadlines include queueing and execution; use local persistent-process facilities for work intended to outlive one request.
+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.