@zetaloop/chappie 0.3.2 → 0.4.1

package/src/config.ts

@@ -5,8 +5,8 @@ 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(),
+	sync: z.boolean().optional(),
 });
 
 export async function readConfig(agentDir: string) {

package/src/delivery.ts

@@ -1,12 +1,12 @@
 import type { ToolResultMessage } from "@earendil-works/pi-ai";
+import type { Source } from "./activity.ts";
 import {
 	contentWithImageReferences,
 	resourceDescriptors,
 } from "./resources.ts";
 
-export interface DeliveryRecord {
+export interface DeliveryRecord extends Source {
 	id: string;
-	chatId: string;
 	sessionId: string;
 	cwd: string;
 	toolResults: ToolResultMessage[];
@@ -43,6 +43,7 @@ export function deliveryContent(deliveries: DeliveryRecord[]) {
 			type: "text" as const,
 			text: JSON.stringify({
 				deferredResult: delivery.id,
+				requestId: delivery.requestId,
 				sessionId: delivery.sessionId,
 				cwd: delivery.cwd,
 				error: delivery.error,

package/src/history.ts

@@ -0,0 +1,123 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import * as z from "zod";
+import type { Source } from "./activity.ts";
+import { toolResultsContent } from "./delivery.ts";
+import type { ProviderOutput } from "./provider.ts";
+import { contentWithImageReferences, rememberImages } from "./resources.ts";
+
+export const historyInput = z.object({
+	limit: z
+		.number()
+		.int()
+		.min(1)
+		.default(20)
+		.describe("Maximum number of history entries"),
+	before: z
+		.string()
+		.min(1)
+		.optional()
+		.describe("Read entries before this entry ID"),
+	after: z
+		.string()
+		.min(1)
+		.optional()
+		.describe("Read entries after this entry ID, starting with the earliest"),
+});
+
+export type HistoryRange = z.infer<typeof historyInput>;
+export type HistoryResult = ReturnType<typeof historyResult>;
+
+export const historyInstructions =
+	"When resuming work, read recent history to recover progress, then continue from the current request.";
+
+export function historyResult(
+	branch: SessionEntry[],
+	sessionId: string,
+	{ limit, before, after }: HistoryRange,
+) {
+	const start = after ? entryIndex(branch, after) + 1 : 0;
+	const end = before ? entryIndex(branch, before) : branch.length;
+	if (start > end) throw new Error("History after must precede before");
+	const entries = branch.slice(start, end).filter((entry) => {
+		switch (entry.type) {
+			case "message":
+				return (
+					entry.message.role !== "custom" ||
+					entry.message.customType !== "chappie.request"
+				);
+			case "custom_message":
+				return entry.customType !== "chappie.request";
+			case "custom":
+				return entry.customType === "chappie.notice";
+			case "compaction":
+			case "branch_summary":
+				return true;
+			default:
+				return false;
+		}
+	});
+	const selected = after ? entries.slice(0, limit) : entries.slice(-limit);
+	const sources = new Map<string, Source>();
+	for (const entry of branch) {
+		if (entry.type !== "message" || entry.message.role !== "assistant")
+			continue;
+		const message = entry.message as ProviderOutput["message"];
+		if (!message.chappie) continue;
+		for (const block of message.content) {
+			if (block.type === "toolCall") sources.set(block.id, message.chappie);
+		}
+	}
+	return {
+		count: selected.length,
+		hasMore: entries.length > selected.length,
+		content: selected.flatMap((entry) =>
+			entryContent(entry, sessionId, sources),
+		),
+	};
+}
+
+function entryIndex(entries: SessionEntry[], id: string): number {
+	const index = entries.findIndex((entry) => entry.id === id);
+	if (index === -1)
+		throw new Error(`History entry ${id} is not on the current branch`);
+	return index;
+}
+
+function entryContent(
+	entry: SessionEntry,
+	sessionId: string,
+	sources: Map<string, Source>,
+): ReturnType<typeof toolResultsContent> {
+	const record: Record<string, unknown> = { ...entry };
+	const message = entry.type === "message" ? entry.message : entry;
+	if (!("content" in message)) {
+		return [{ type: "text", text: JSON.stringify(record) }];
+	}
+	const { content, ...metadata } = message;
+	if (entry.type === "message") {
+		const source =
+			entry.message.role === "toolResult"
+				? sources.get(entry.message.toolCallId)
+				: undefined;
+		record.message = { ...metadata, ...(source ? { chappie: source } : {}) };
+	} else delete record.content;
+	const header = { type: "text" as const, text: JSON.stringify(record) };
+	if (entry.type === "message" && entry.message.role === "toolResult") {
+		rememberImages(sessionId, entry.message.content);
+		return [header, ...toolResultsContent([entry.message], sessionId)];
+	}
+	const blocks =
+		typeof content === "string"
+			? [{ type: "text" as const, text: content }]
+			: content;
+	return [
+		header,
+		...blocks.flatMap((block): ReturnType<typeof toolResultsContent> => {
+			if (block.type === "text" || block.type === "image") {
+				rememberImages(sessionId, [block]);
+				return contentWithImageReferences(sessionId, [block]);
+			}
+			return [{ type: "text", text: JSON.stringify(block) }];
+		}),
+	];
+}

package/src/instructions.md

@@ -1,6 +1,8 @@
 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. A session 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.
+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.
 
@@ -13,3 +15,5 @@ Use chat for assistant messages in Pi, including progress, explanations, and res
 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.
+
+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/ipc.ts

@@ -17,7 +17,9 @@ import type {
 	SlashCommandInfo,
 	ToolInfo,
 } from "@earendil-works/pi-coding-agent";
+import type { Activity } from "./activity.ts";
 import type { DeliveryRecord } from "./delivery.ts";
+import type { HistoryRange, HistoryResult } from "./history.ts";
 import type { ResourceData } from "./resources.ts";
 
 const defaultPort = 24274;
@@ -57,6 +59,7 @@ export type SessionResult =
 			toolResults: ToolResultMessage[];
 			inputs: SessionInput[];
 	  }
+	| { history: HistoryResult; cwd: string }
 	| { resource: ResourceData }
 	| { error: string };
 
@@ -69,12 +72,21 @@ export type SessionMessage =
 export type BrokerMessage =
 	| { type: "synced"; id: number; sessionId: string }
 	| { type: "stored"; id: string }
-	| { type: "notice"; sessionId: string; message: string }
+	| { type: "notice"; sessionId: string; message: string; activity?: Activity }
 	| { type: "inspect"; id: number; sessionId: string }
+	| {
+			type: "history";
+			id: number;
+			sessionId: string;
+			range: HistoryRange;
+			chatId: string;
+			requestId?: string;
+	  }
 	| {
 			type: "chat";
 			id: number;
 			chatId: string;
+			requestId?: string;
 			sessionId: string;
 			text: string;
 	  }
@@ -82,6 +94,7 @@ export type BrokerMessage =
 			type: "call";
 			id: number;
 			chatId: string;
+			requestId?: string;
 			sessionId: string;
 			calls: ToolCall[];
 	  }

package/src/provider.ts

@@ -9,10 +9,11 @@ import {
 	type StreamOptions,
 	type ToolCall,
 } from "@earendil-works/pi-ai";
+import type { Source } from "./activity.ts";
 
 export class ProviderOutput {
 	readonly stream: AssistantMessageEventStream;
-	readonly message: AssistantMessage;
+	readonly message: AssistantMessage & { chappie?: Source };
 	readonly finished: Promise<void>;
 	#resolveFinished: () => void;
 	#removeAbort?: () => void;

package/src/server.ts

@@ -4,6 +4,7 @@ import * as z from "zod";
 import packageJson from "../package.json" with { type: "json" };
 import type { Broker } from "./broker.ts";
 import { deliveryContent } from "./delivery.ts";
+import { historyInput } from "./history.ts";
 import {
 	answerContent,
 	answerInput,
@@ -31,6 +32,9 @@ const outputSchema = z.object({
 		),
 });
 
+const syncInstructions =
+	"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 });
 const toolAnnotations = {
@@ -54,26 +58,30 @@ export function createServer(broker: Broker): McpServer {
 			version: packageJson.version,
 		},
 		{
-			instructions: broker.askEnabled
-				? `${instructions}\n\n${questionInstructions}`
-				: instructions,
+			instructions: [
+				instructions,
+				...(broker.askEnabled ? [questionInstructions] : []),
+				...(broker.syncEnabled ? [syncInstructions] : []),
+			].join("\n\n"),
 		},
 	);
 
 	function handle<Args, Result>(
 		callback: (args: Args, context: RequestContext) => Promise<Result>,
+		communication = false,
 	) {
-		return async (args: Args, context: RequestContext): Promise<Result> => {
-			const signal = await broker.workflow(
-				requestChatId(context),
-				context.mcpReq._meta?.["otunnel/requestId"],
+		return (args: Args, context: RequestContext): Promise<Result> =>
+			broker.run(
+				requireChatId(context),
+				(args as { sessionId?: string }).sessionId,
 				context.mcpReq.signal,
+				(signal) =>
+					callback(args, {
+						...context,
+						mcpReq: { ...context.mcpReq, signal },
+					}),
+				communication,
 			);
-			return callback(args, {
-				...context,
-				mcpReq: { ...context.mcpReq, signal },
-			});
-		};
 	}
 
 	server.registerTool(
@@ -81,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.",
+				"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
@@ -123,7 +131,7 @@ export function createServer(broker: Broker): McpServer {
 		},
 		handle(async (args, context) => {
 			const chatId = requireChatId(context);
-			const { sessionId, cwd, inputs } = await broker.chat(
+			const { sessionId, cwd, inputs, initialization } = await broker.chat(
 				chatId,
 				args.sessionId,
 				args.text,
@@ -133,9 +141,12 @@ export function createServer(broker: Broker): McpServer {
 			return finishResult(
 				broker,
 				context,
-				textResult({ sessionId, cwd }, inputs),
+				textResult(
+					{ sessionId, cwd, ...(initialization ? { initialization } : {}) },
+					inputs,
+				),
 			);
-		}),
+		}, true),
 	);
 
 	if (broker.askEnabled) {
@@ -158,7 +169,7 @@ export function createServer(broker: Broker): McpServer {
 				_meta: { ui: { resourceUri: questionTemplate } },
 			},
 			handle(async ({ sessionId, ...input }, context) => {
-				const question = await broker.ask(
+				const { initialization, ...question } = await broker.ask(
 					requireChatId(context),
 					sessionId,
 					input,
@@ -167,6 +178,7 @@ export function createServer(broker: Broker): McpServer {
 				);
 				const result = await finishResult(broker, context, {
 					content: [
+						...(initialization ? textResult({ initialization }).content : []),
 						{
 							type: "text",
 							text: `Question created. Call ask_assert({"questionId":"${question.id}"}) next.`,
@@ -226,7 +238,7 @@ export function createServer(broker: Broker): McpServer {
 				annotations: toolAnnotations,
 				_meta: { ui: { visibility: ["app"] }, "openai/widgetAccessible": true },
 			},
-			handle(async ({ questionId, answer, loaded = false }, context) => {
+			async ({ questionId, answer, loaded = false }, context) => {
 				const question = await broker.answer(
 					requireChatId(context),
 					questionId,
@@ -244,7 +256,7 @@ export function createServer(broker: Broker): McpServer {
 					content: [{ type: "text", text }],
 					structuredContent: { text, question },
 				};
-			}),
+			},
 		);
 
 		server.registerResource(
@@ -308,7 +320,13 @@ export function createServer(broker: Broker): McpServer {
 				broker,
 				context,
 				textResult(
-					{ session: inspected.session, tools: inspected.tools },
+					{
+						session: inspected.session,
+						tools: inspected.tools,
+						...(inspected.initialization
+							? { initialization: inspected.initialization }
+							: {}),
+					},
 					inputs,
 				),
 			);
@@ -356,6 +374,7 @@ export function createServer(broker: Broker): McpServer {
 					result.sessionId,
 					result.cwd,
 					result.inputs,
+					result.initialization,
 				),
 			);
 		}),
@@ -396,12 +415,93 @@ export function createServer(broker: Broker): McpServer {
 						result.sessionId,
 						result.cwd,
 						result.inputs,
+						result.initialization,
 					),
 				);
 			}),
 		);
 	}
 
+	server.registerTool(
+		"history",
+		{
+			title: "Session history",
+			description:
+				"Read recent Pi history with entry IDs and timestamps. Use before/after to page the current branch. History provides context for the current task. An explicit sessionId applies only to this read.",
+			inputSchema: historyInput.extend({
+				sessionId: z
+					.string()
+					.optional()
+					.describe("Pi session to read; defaults to this chat's session"),
+			}),
+			outputSchema,
+			annotations: toolAnnotations,
+		},
+		handle(async ({ sessionId, ...range }, context) => {
+			const { history, ...session } = await broker.history(
+				requireChatId(context),
+				sessionId,
+				range,
+				context.mcpReq._meta?.["otunnel/requestId"],
+				context.mcpReq.signal,
+			);
+			const { content, ...page } = history;
+			return formatResult({
+				content: [
+					...textResult({
+						...session,
+						history: page,
+						...(broker.syncEnabled
+							? { sync: broker.syncState(session.sessionId) }
+							: {}),
+					}).content,
+					...content,
+				],
+			});
+		}, true),
+	);
+
+	if (broker.syncEnabled) {
+		server.registerTool(
+			"sync",
+			{
+				title: "Synchronize Pi activity",
+				description:
+					"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
+						.string()
+						.optional()
+						.describe(
+							"Initialization code for verification, or the verified code for release; omit when unavailable",
+						),
+					sessionId: z
+						.string()
+						.optional()
+						.describe(
+							"Pi session to synchronize; defaults to this chat's session",
+						),
+				}),
+				outputSchema,
+				annotations: toolAnnotations,
+			},
+			async ({ action, code, sessionId }, context) =>
+				formatResult(
+					textResult(
+						await broker.sync(
+							requireChatId(context),
+							sessionId,
+							action,
+							code,
+							context.mcpReq._meta?.["otunnel/requestId"],
+							context.mcpReq.signal,
+						),
+					),
+				),
+		);
+	}
+
 	server.registerTool(
 		"sessions",
 		{
@@ -420,12 +520,7 @@ export function createServer(broker: Broker): McpServer {
 		handle(async (args, context) => {
 			const chatId = requestChatId(context);
 			const inputs = chatId
-				? await broker.inputs(
-						chatId,
-						args.sessionId,
-						context.mcpReq._meta?.["otunnel/requestId"],
-						context.mcpReq.signal,
-					)
+				? await broker.inputs(chatId, args.sessionId, context.mcpReq.signal)
 				: [];
 			const result = textResult(
 				{
@@ -435,7 +530,7 @@ export function createServer(broker: Broker): McpServer {
 				inputs,
 			);
 			return finishResult(broker, context, result);
-		}),
+		}, true),
 	);
 
 	server.registerResource(
@@ -479,21 +574,32 @@ function textResult(
 async function finishResult<
 	T extends { content: ReturnType<typeof toolResult>["content"] },
 >(broker: Broker, context: RequestContext, result: T) {
+	context.mcpReq.signal.throwIfAborted();
 	const chatId = requestChatId(context);
-	const deliveries = chatId ? await broker.deliveries(chatId) : [];
+	if (!broker.deliveryAllowed(context.mcpReq.signal))
+		return formatResult(result);
+	const deliveries = chatId ? broker.deliveries(chatId) : [];
 	const answers = chatId ? broker.answers(chatId) : [];
 	const content = [
 		...result.content,
 		...deliveryContent(deliveries),
 		...answerContent(answers),
 	];
-	const structuredContent = {
-		text: content
-			.flatMap((block) => (block.type === "text" ? [block.text] : []))
-			.join("\n"),
-	};
 	await broker.acknowledge(deliveries, answers, context.mcpReq.signal);
-	return { ...result, content, structuredContent };
+	return formatResult({ ...result, content });
+}
+
+function formatResult<
+	T extends { content: ReturnType<typeof toolResult>["content"] },
+>(result: T) {
+	return {
+		...result,
+		structuredContent: {
+			text: result.content
+				.flatMap((block) => (block.type === "text" ? [block.text] : []))
+				.join("\n"),
+		},
+	};
 }
 
 function requestChatId(context: RequestContext): string | undefined {

package/src/session.ts

@@ -13,7 +13,9 @@ import type {
 	SessionEntry,
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
+import { type Activity, chatLabel, source } from "./activity.ts";
 import type { DeliveryRecord } from "./delivery.ts";
+import { historyResult } from "./history.ts";
 import {
 	type BrokerMessage,
 	IpcClient,
@@ -27,7 +29,7 @@ import { readSessionResource, rememberImages } from "./resources.ts";
 
 type RemoteRequest = Extract<BrokerMessage, { type: "chat" | "call" }>;
 
-interface Notice {
+interface Notice extends Activity {
 	message: string;
 	type: "info" | "warning" | "error";
 }
@@ -126,9 +128,17 @@ export class LocalSession {
 		this.#pi.on("session_shutdown", () => this.close());
 	}
 
-	#notify(message: string, type: Notice["type"] = "info"): void {
+	#notify(
+		message: string,
+		type: Notice["type"] = "info",
+		activity: Activity = {},
+	): void {
 		if (this.#context)
-			this.#pi.appendEntry<Notice>("chappie.notice", { message, type });
+			this.#pi.appendEntry<Notice>("chappie.notice", {
+				message,
+				type,
+				...activity,
+			});
 	}
 
 	async start(output: ProviderOutput): Promise<void> {
@@ -261,7 +271,7 @@ export class LocalSession {
 				if (
 					message.sessionId === this.#context?.sessionManager.getSessionId()
 				) {
-					this.#notify(message.message);
+					this.#notify(message.message, "info", message.activity);
 				}
 				break;
 			case "inspect":
@@ -276,6 +286,26 @@ export class LocalSession {
 					};
 				});
 				break;
+			case "history":
+				await this.#reply(message.id, message.sessionId, () => {
+					const context = this.#context;
+					if (!context) throw new Error("Chappie session is not available");
+					const history = historyResult(
+						context.sessionManager.getBranch(),
+						message.sessionId,
+						message.range,
+					);
+					this.#notify(
+						`${chatLabel(message)} read history: ${history.count} entries`,
+						"info",
+						{
+							event: "history",
+							...source(message.chatId, message.requestId),
+						},
+					);
+					return { type: "result", id: message.id, cwd: context.cwd, history };
+				});
+				break;
 			case "ackInputs":
 				if (
 					message.sessionId === this.#context?.sessionManager.getSessionId()
@@ -305,8 +335,12 @@ export class LocalSession {
 						? [...new Set(request.calls.map((call) => call.name))].join(", ")
 						: "chat";
 				this.#notify(
-					`${name} cancelled for ChatGPT ${request.chatId.slice(-4)}: ${message.reason}`,
+					`${name} cancelled for ${chatLabel(request)}: ${message.reason}`,
 					"warning",
+					{
+						event: "cancelled",
+						...source(request.chatId, request.requestId),
+					},
 				);
 				if (queued !== -1) {
 					this.#queue.splice(queued, 1);
@@ -370,6 +404,7 @@ export class LocalSession {
 		}
 
 		this.#queue.shift();
+		output.message.chappie = source(request.chatId, request.requestId);
 		this.#active = {
 			request,
 			session: this.#description(),
@@ -431,7 +466,7 @@ export class LocalSession {
 		if (active.cancelled !== undefined) {
 			const delivery: DeliveryRecord = {
 				id: randomUUID(),
-				chatId: active.request.chatId,
+				...source(active.request.chatId, active.request.requestId),
 				sessionId: active.session.id,
 				cwd: active.session.cwd,
 				toolResults: active.toolResults,
@@ -515,7 +550,14 @@ export class LocalSession {
 					await connection.send({ type: "delivery", delivery });
 					await completion.promise;
 					this.#deliveries.delete(delivery.id);
-					this.#notify(`Result saved for ChatGPT ${delivery.chatId.slice(-4)}`);
+					this.#notify(
+						`Result saved for ChatGPT ${delivery.chatId.slice(-4)}`,
+						"info",
+						{
+							event: "result_saved",
+							...source(delivery.chatId, delivery.requestId),
+						},
+					);
 				} finally {
 					this.#stores.delete(delivery.id);
 				}