@zetaloop/chappie 0.4.0 → 0.5.0

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. 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.
+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 globalAgents is present, read and follow the instructions at globalAgents.path. Follow initialization.instructions for your participation in the current task. When executing work, 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.
 
@@ -8,10 +8,10 @@ Prefer ChatGPT's web search, connectors, and cloud tools for remote research and
 
 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.
+When executing work, use chat for assistant messages in Pi, including progress, explanations, and completion 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.
 
-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.
+transfer pairs files from ChatGPT with Pi destination paths in order. To copy between Pi sessions, use paths on the selected source session and to: { sessionId, paths } for the destination. Each side resolves paths in its own working directory. Omit files and to 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.
+Tool results identify the executing Pi sessionId and cwd. A shell command can access another directory without changing its Pi session. structuredContent.text includes tool output, new Pi input, webAnswer, and deferred results; images and resources are native content blocks. ChatGPT truncates tool responses exceeding 10,000 tokens. 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.
+Use history to read the current Pi branch with entry IDs and timestamps. History defaults to the last 20 entries; before pages backward and after pages forward. Use after with wait: true to follow progress: available entries return immediately, otherwise the call waits up to 30 seconds. An empty result means no new entries. Set observer: true when reading as an observer. Read the work's completion message to form the final reply. History returns saved contents separately from new Pi input.

package/src/ipc.ts

@@ -20,7 +20,8 @@ import type {
 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";
+import type { ResourceData, ResourceDescriptor } from "./resources.ts";
+import type { TransferDetails } from "./transfer.ts";
 
 const defaultPort = 24274;
 
@@ -50,7 +51,7 @@ export type SessionResult =
 	| {
 			inspection: SessionInspection;
 			inputs: SessionInput[];
-			globalAgents?: string;
+			globalAgents?: { path: string };
 	  }
 	| { message: AssistantMessage; cwd: string; inputs: SessionInput[] }
 	| {
@@ -61,19 +62,32 @@ export type SessionResult =
 	  }
 	| { history: HistoryResult; cwd: string }
 	| { resource: ResourceData }
+	| { transfer: TransferDetails }
 	| { error: string };
 
+export type SessionRequest =
+	| { type: "inspect"; sessionId: string }
+	| { type: "readResource"; sessionId: string; uri: string; offset?: number }
+	| {
+			type: "copy";
+			sessionId: string;
+			resources: ResourceDescriptor[];
+			paths: string[];
+			overwrite?: boolean;
+	  };
+
 export type SessionMessage =
 	| { type: "sync"; id: number; session: SessionDescription }
 	| { type: "unregister"; sessionId: string }
 	| { type: "delivery"; delivery: DeliveryRecord }
+	| { type: "request"; id: number; request: SessionRequest }
+	| { type: "cancelRequest"; id: number }
 	| ({ type: "result"; id: number } & SessionResult);
 
 export type BrokerMessage =
 	| { type: "synced"; id: number; sessionId: string }
 	| { type: "stored"; id: string }
 	| { type: "notice"; sessionId: string; message: string; activity?: Activity }
-	| { type: "inspect"; id: number; sessionId: string }
 	| {
 			type: "history";
 			id: number;
@@ -99,7 +113,8 @@ export type BrokerMessage =
 			calls: ToolCall[];
 	  }
 	| { type: "cancel"; id: number; sessionId: string; reason: string }
-	| { type: "readResource"; id: number; sessionId: string; uri: string }
+	| (SessionRequest & { id: number })
+	| ({ type: "response"; id: number } & SessionResult)
 	| { type: "ackInputs"; sessionId: string; ids: string[] };
 
 export function ipcEndpoint(agentDir: string): string {

package/src/questions.ts

@@ -1,15 +1,10 @@
 import * as z from "zod";
 
 export const questionInstructions =
-	"Use ask for a question in ChatGPT, then immediately call ask_assert with question.id from its result. The assertion returns when the widget reports loaded and times out if loading fails. User answers arrive separately as webAnswer in normal tool results. Apply answers and revisions promptly; a skip means proceed with available information. Supply header when useful and mark the preferred first option recommended: true. The widget provides custom input and skipping. If loading fails and input is needed, use an installed Pi interactive tool through call.";
+	"ask requests a question widget in ChatGPT; its result confirms creation of the request. Immediately call ask_assert with question.id to confirm loading. If the widget fails to load within 10 seconds, the assertion fails and records the question as skipped. Use an installed Pi interactive tool through call when an answer is needed. User answers arrive separately as webAnswer in normal tool results. Apply answers and revisions promptly; a user skip means proceed with available information.";
 
 export const questionInput = z.object({
-	header: z
-		.string()
-		.trim()
-		.min(1)
-		.optional()
-		.describe("Short topic label above the question, when useful"),
+	header: z.string().trim().min(1).optional().describe("Short topic label"),
 	question: z
 		.string()
 		.trim()
@@ -18,7 +13,7 @@ export const questionInput = z.object({
 	context: z
 		.string()
 		.optional()
-		.describe("Context to display above the choices"),
+		.describe("Background needed to answer the question"),
 	options: z
 		.array(
 			z.object({
@@ -30,12 +25,12 @@ export const questionInput = z.object({
 				recommended: z
 					.boolean()
 					.optional()
-					.describe("Show a Recommended badge; put this choice first"),
+					.describe("Preferred choice; place it first"),
 			}),
 		)
 		.default([])
 		.describe(
-			"Distinct choices, usually two or three. The widget provides custom input and skipping separately.",
+			"Distinct choices, usually two or three. Freeform answers and skipping are available separately.",
 		),
 	allowMultiple: z
 		.boolean()
@@ -46,10 +41,7 @@ export const questionInput = z.object({
 export const answerInput = z.object({
 	selections: z.array(z.number().int().nonnegative()).default([]),
 	text: z.string().trim().default(""),
-	skipped: z
-		.literal(true)
-		.optional()
-		.describe("The user skipped this question"),
+	skipped: z.literal(true).optional().describe("The question was skipped"),
 });
 
 export const questionOutput = questionInput.extend({

package/src/resources.ts

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { readFile, stat } from "node:fs/promises";
+import { open, readFile, stat } from "node:fs/promises";
 import { basename } from "node:path";
 import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
 import mime from "mime";
@@ -124,15 +124,35 @@ export function describeResource(
 export async function readSessionResource(
 	sessionId: string,
 	uri: string,
+	offset?: number,
 ): Promise<ResourceData> {
 	const descriptor = describeResource(sessionId, uri);
 	const entry = store(sessionId).get(uri);
 	if (!entry) throw new Error(`Unknown Chappie resource: ${uri}`);
-	const blob =
-		entry.type === "file"
-			? (await readFile(entry.path)).toString("base64")
-			: entry.data;
-	return { ...descriptor, blob };
+	if (offset === undefined) {
+		const blob =
+			entry.type === "file"
+				? (await readFile(entry.path)).toString("base64")
+				: entry.data;
+		return { ...descriptor, blob };
+	}
+	if (!Number.isSafeInteger(offset) || offset < 0)
+		throw new Error("Resource offset must be a nonnegative integer");
+	const length = Math.min(1024 * 1024, Math.max(0, descriptor.size - offset));
+	let data: Buffer;
+	if (entry.type === "file") {
+		await using file = await open(entry.path, "r");
+		const { buffer, bytesRead } = await file.read(
+			Buffer.alloc(length),
+			0,
+			length,
+			offset,
+		);
+		data = buffer.subarray(0, bytesRead);
+	} else {
+		data = Buffer.from(entry.data, "base64").subarray(offset, offset + length);
+	}
+	return { ...descriptor, blob: data.toString("base64") };
 }
 
 export function resourceSessionId(uri: string): string {

package/src/server.ts

@@ -32,9 +32,6 @@ 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 = {
@@ -61,27 +58,18 @@ export function createServer(broker: Broker): McpServer {
 			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 (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 (args: Args, context: RequestContext): Promise<Result> => {
+			requireChatId(context);
+			context.mcpReq.signal.throwIfAborted();
+			return callback(args, context);
+		};
 	}
 
 	server.registerTool(
@@ -89,7 +77,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. Read recent history when resuming work.",
+				"Select this chat's default Pi session and return its environment, tool catalog, and participation instructions. 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
@@ -115,8 +103,7 @@ export function createServer(broker: Broker): McpServer {
 		"chat",
 		{
 			title: "Reply in Pi",
-			description:
-				"Send an assistant message to Pi. Renders Markdown and saves the message in the session transcript.",
+			description: "Send a Markdown assistant message to Pi.",
 			outputSchema,
 			inputSchema: z.object({
 				text: z.string().min(1).describe("Assistant message in Markdown"),
@@ -146,7 +133,7 @@ export function createServer(broker: Broker): McpServer {
 					inputs,
 				),
 			);
-		}, true),
+		}),
 	);
 
 	if (broker.askEnabled) {
@@ -155,7 +142,7 @@ export function createServer(broker: Broker): McpServer {
 			{
 				title: "Ask in ChatGPT",
 				description:
-					"Create a question in ChatGPT and return its ID immediately. Call ask_assert next with question.id. Answers, revisions, and skips arrive as webAnswer in later tool results.",
+					"Request a question widget in ChatGPT and return its ID immediately. Display depends on the host; call ask_assert next with question.id to confirm loading. Answers, revisions, and skips arrive as webAnswer in later tool results.",
 				inputSchema: questionInput.extend({
 					sessionId: z
 						.string()
@@ -181,7 +168,7 @@ export function createServer(broker: Broker): McpServer {
 						...(initialization ? textResult({ initialization }).content : []),
 						{
 							type: "text",
-							text: `Question created. Call ask_assert({"questionId":"${question.id}"}) next.`,
+							text: `Question widget requested. Call ask_assert({"questionId":"${question.id}"}) next.`,
 						},
 					],
 				});
@@ -197,7 +184,7 @@ export function createServer(broker: Broker): McpServer {
 			{
 				title: "Assert question display",
 				description:
-					"Assert that an ask widget loaded in ChatGPT. Call immediately after ask with question.id. Returns when the widget reports loaded; times out if it fails to load. User answers arrive separately as webAnswer.",
+					"Confirm that an ask widget loaded in ChatGPT. Call immediately after ask with question.id. Fails after 10 seconds without loading and records the question as skipped. Use a Pi interactive tool if an answer is needed. User answers arrive separately as webAnswer.",
 				inputSchema: z.object({
 					questionId: z.string().describe("question.id returned by ask"),
 				}),
@@ -278,7 +265,7 @@ export function createServer(broker: Broker): McpServer {
 								csp: { connectDomains: [], resourceDomains: [] },
 							},
 							"openai/widgetDescription":
-								"A persistent question the user can answer while the assistant continues working.",
+								"A question the user can answer or revise.",
 						},
 					},
 				],
@@ -427,7 +414,7 @@ export function createServer(broker: Broker): McpServer {
 		{
 			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.",
+				"Read Pi history with entry IDs and timestamps. Use before/after to page the current branch, and wait to follow new progress when caught up. Set observer when reading as an observer. An explicit sessionId applies only to this read.",
 			inputSchema: historyInput.extend({
 				sessionId: z
 					.string()
@@ -446,62 +433,18 @@ export function createServer(broker: Broker): McpServer {
 				context.mcpReq.signal,
 			);
 			const { content, ...page } = history;
-			return formatResult({
-				content: [
-					...textResult({
-						...session,
-						history: page,
-						...(broker.syncEnabled
-							? { sync: broker.syncState(session.sessionId) }
-							: {}),
-					}).content,
-					...content,
-				],
-			});
-		}, true),
+			return formatResult(
+				{
+					content: [
+						...textResult({ ...session, history: page }).content,
+						...content,
+					],
+				},
+				requireChatId(context),
+			);
+		}),
 	);
 
-	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",
 		{
@@ -530,14 +473,17 @@ export function createServer(broker: Broker): McpServer {
 				inputs,
 			);
 			return finishResult(broker, context, result);
-		}, true),
+		}),
 	);
 
 	server.registerResource(
 		"Pi resource",
-		new ResourceTemplate("chappie://session/{sessionId}/{kind}/{id}/{name}", {
-			list: undefined,
-		}),
+		new ResourceTemplate(
+			"chappie://session/{sessionId}/{kind}/{id}/{name}{?chatId}",
+			{
+				list: undefined,
+			},
+		),
 		{ title: "Pi resource" },
 		async (uri, _variables, context) => {
 			const resource = await broker.readResource(
@@ -576,8 +522,6 @@ async function finishResult<
 >(broker: Broker, context: RequestContext, result: T) {
 	context.mcpReq.signal.throwIfAborted();
 	const chatId = requestChatId(context);
-	if (!broker.deliveryAllowed(context.mcpReq.signal))
-		return formatResult(result);
 	const deliveries = chatId ? broker.deliveries(chatId) : [];
 	const answers = chatId ? broker.answers(chatId) : [];
 	const content = [
@@ -586,16 +530,23 @@ async function finishResult<
 		...answerContent(answers),
 	];
 	await broker.acknowledge(deliveries, answers, context.mcpReq.signal);
-	return formatResult({ ...result, content });
+	return formatResult({ ...result, content }, chatId);
 }
 
 function formatResult<
 	T extends { content: ReturnType<typeof toolResult>["content"] },
->(result: T) {
+>(result: T, chatId?: string) {
+	const content = result.content.map((block) => {
+		if (block.type !== "resource_link" || !chatId) return block;
+		const uri = new URL(block.uri);
+		uri.searchParams.set("chatId", chatId);
+		return { ...block, uri: uri.href };
+	});
 	return {
 		...result,
+		content,
 		structuredContent: {
-			text: result.content
+			text: content
 				.flatMap((block) => (block.type === "text" ? [block.text] : []))
 				.join("\n"),
 		},