@zetaloop/chappie 0.3.1 → 0.4.0

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,6 @@
 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.
+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.
 
 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 +13,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. Request IDs and the workflow suffix in notices describe recorded requests, and duplicate executions can share a workflow ID. It 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 =
+	"Synchronization ends accidental duplicate executions so one execution continues. Retain each initialization code privately in this ChatGPT context for its Pi session. On conflicting activity, call sync with action start, then verify with the code returned by your own most recent initialization. A rejected or unavailable code means this execution must send one final chat message with its task, entry time, and explicit exit statement, then end this ChatGPT response immediately. It must not wait for unlock, poll, reinitialize, or resume after release. Verification returns a new code and leaves ordinary tools and initialization locked. The verified execution uses chat and history to identify conflicting executions, require their final exit messages, and confirm their responses have ended before releasing with that code. Idle Pi status or a quiet history page is not proof of exit. Codes belong only in initialization and sync exchanges, never in chat, history, or notes.";
+
 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 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. Read recent history when resuming work.",
 			outputSchema,
 			inputSchema: z.object({
 				sessionId: z
@@ -96,6 +104,7 @@ export function createServer(broker: Broker): McpServer {
 			const { inputs, ...initialized } = await broker.initialize(
 				chatId,
 				args.sessionId,
+				context.mcpReq._meta?.["otunnel/requestId"],
 				context.mcpReq.signal,
 			);
 			return finishResult(broker, context, textResult(initialized, inputs));
@@ -114,24 +123,30 @@ export function createServer(broker: Broker): McpServer {
 				sessionId: z
 					.string()
 					.optional()
-					.describe("Pi session for this operation only"),
+					.describe(
+						"Pi session for this operation; becomes the default if none is set",
+					),
 			}),
 			annotations: toolAnnotations,
 		},
 		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,
+				context.mcpReq._meta?.["otunnel/requestId"],
 				context.mcpReq.signal,
 			);
 			return finishResult(
 				broker,
 				context,
-				textResult({ sessionId, cwd }, inputs),
+				textResult(
+					{ sessionId, cwd, ...(initialization ? { initialization } : {}) },
+					inputs,
+				),
 			);
-		}),
+		}, true),
 	);
 
 	if (broker.askEnabled) {
@@ -154,14 +169,16 @@ 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,
+					context.mcpReq._meta?.["otunnel/requestId"],
 					context.mcpReq.signal,
 				);
 				const result = await finishResult(broker, context, {
 					content: [
+						...(initialization ? textResult({ initialization }).content : []),
 						{
 							type: "text",
 							text: `Question created. Call ask_assert({"questionId":"${question.id}"}) next.`,
@@ -221,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,
@@ -239,7 +256,7 @@ export function createServer(broker: Broker): McpServer {
 					content: [{ type: "text", text }],
 					structuredContent: { text, question },
 				};
-			}),
+			},
 		);
 
 		server.registerResource(
@@ -285,7 +302,9 @@ export function createServer(broker: Broker): McpServer {
 				sessionId: z
 					.string()
 					.optional()
-					.describe("Pi session for this operation only"),
+					.describe(
+						"Pi session for this operation; becomes the default if none is set",
+					),
 			}),
 			annotations: toolAnnotations,
 		},
@@ -294,13 +313,20 @@ export function createServer(broker: Broker): McpServer {
 				requireChatId(context),
 				args.sessionId,
 				args.names,
+				context.mcpReq._meta?.["otunnel/requestId"],
 				context.mcpReq.signal,
 			);
 			return finishResult(
 				broker,
 				context,
 				textResult(
-					{ session: inspected.session, tools: inspected.tools },
+					{
+						session: inspected.session,
+						tools: inspected.tools,
+						...(inspected.initialization
+							? { initialization: inspected.initialization }
+							: {}),
+					},
 					inputs,
 				),
 			);
@@ -326,7 +352,9 @@ export function createServer(broker: Broker): McpServer {
 				sessionId: z
 					.string()
 					.optional()
-					.describe("Pi session for this operation only"),
+					.describe(
+						"Pi session for this operation; becomes the default if none is set",
+					),
 			}),
 			annotations: toolAnnotations,
 		},
@@ -335,6 +363,7 @@ export function createServer(broker: Broker): McpServer {
 				requireChatId(context),
 				args.sessionId,
 				args.calls,
+				context.mcpReq._meta?.["otunnel/requestId"],
 				context.mcpReq.signal,
 			);
 			return finishResult(
@@ -345,6 +374,7 @@ export function createServer(broker: Broker): McpServer {
 					result.sessionId,
 					result.cwd,
 					result.inputs,
+					result.initialization,
 				),
 			);
 		}),
@@ -374,6 +404,7 @@ export function createServer(broker: Broker): McpServer {
 					requireChatId(context),
 					sessionId,
 					calls,
+					context.mcpReq._meta?.["otunnel/requestId"],
 					context.mcpReq.signal,
 				);
 				return finishResult(
@@ -384,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:
+					"End duplicate executions: start synchronization, verify your own latest initialization code, and release after conflicting executions exit. Failed verification requires a final chat exit message followed by ending this response. Verification leaves the session locked; chat and history support exit coordination.",
+				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",
 		{
@@ -418,7 +530,7 @@ export function createServer(broker: Broker): McpServer {
 				inputs,
 			);
 			return finishResult(broker, context, result);
-		}),
+		}, true),
 	);
 
 	server.registerResource(
@@ -462,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 {