@zetaloop/chappie 0.2.0 → 0.3.0

package/src/server.ts

@@ -4,6 +4,13 @@ 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 {
+	answerContent,
+	answerInput,
+	questionInput,
+	questionInstructions,
+	questionOutput,
+} from "./questions.ts";
 import {
 	directTools,
 	inputContent,
@@ -16,6 +23,23 @@ const instructions = readFileSync(
 	"utf8",
 ).trim();
 
+const outputSchema = z.object({
+	text: z
+		.string()
+		.describe(
+			"Complete text output, including Pi user input, submitted webpage answers, and deferred results. Images and file resources accompany it as native content blocks.",
+		),
+});
+
+const questionTemplate = "ui://chappie/question.html";
+const questionSchema = outputSchema.extend({ question: questionOutput });
+const toolAnnotations = {
+	readOnlyHint: true,
+	destructiveHint: false,
+	idempotentHint: true,
+	openWorldHint: false,
+} as const;
+
 interface RequestContext {
 	mcpReq: {
 		_meta?: Record<string, unknown>;
@@ -29,27 +53,45 @@ export function createServer(broker: Broker): McpServer {
 			name: "chappie",
 			version: packageJson.version,
 		},
-		{ instructions },
+		{
+			instructions: broker.askEnabled
+				? `${instructions}\n\n${questionInstructions}`
+				: instructions,
+		},
 	);
 
+	function handle<Args, Result>(
+		callback: (args: Args, context: RequestContext) => Promise<Result>,
+	) {
+		return async (args: Args, context: RequestContext): Promise<Result> => {
+			const signal = await broker.workflow(
+				requestChatId(context),
+				context.mcpReq._meta?.["otunnel/requestId"],
+				context.mcpReq.signal,
+			);
+			return callback(args, {
+				...context,
+				mcpReq: { ...context.mcpReq, signal },
+			});
+		};
+	}
+
 	server.registerTool(
 		"init",
 		{
 			title: "Connect to Pi",
 			description:
-				"Connect this ChatGPT conversation to an online Pi session. A sessionId on init becomes the new default.",
+				"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.",
+			outputSchema,
 			inputSchema: z.object({
 				sessionId: z
 					.string()
 					.optional()
-					.describe("Pi session to select explicitly"),
+					.describe("Default Pi session ID; may be shared with other chats"),
 			}),
-			annotations: {
-				destructiveHint: false,
-				openWorldHint: false,
-			},
+			annotations: toolAnnotations,
 		},
-		async (args, context) => {
+		handle(async (args, context) => {
 			const chatId = requireChatId(context);
 			const { inputs, ...initialized } = await broker.initialize(
 				chatId,
@@ -57,44 +99,183 @@ export function createServer(broker: Broker): McpServer {
 				context.mcpReq.signal,
 			);
 			return finishResult(broker, context, textResult(initialized, inputs));
-		},
+		}),
 	);
 
 	server.registerTool(
 		"chat",
 		{
 			title: "Reply in Pi",
-			description: "Display one complete assistant message in Pi.",
+			description:
+				"Send an assistant message to Pi. Renders Markdown and saves the message in the session transcript.",
+			outputSchema,
 			inputSchema: z.object({
-				text: z.string().min(1).describe("Assistant message to display in Pi"),
+				text: z.string().min(1).describe("Assistant message in Markdown"),
 				sessionId: z
 					.string()
 					.optional()
 					.describe("Pi session for this operation only"),
 			}),
-			annotations: {
-				destructiveHint: false,
-				openWorldHint: false,
-			},
+			annotations: toolAnnotations,
 		},
-		async (args, context) => {
+		handle(async (args, context) => {
 			const chatId = requireChatId(context);
-			const { sessionId, inputs } = await broker.chat(
+			const { sessionId, cwd, inputs } = await broker.chat(
 				chatId,
 				args.sessionId,
 				args.text,
 				context.mcpReq.signal,
 			);
-			return finishResult(broker, context, textResult({ sessionId }, inputs));
-		},
+			return finishResult(
+				broker,
+				context,
+				textResult({ sessionId, cwd }, inputs),
+			);
+		}),
 	);
 
+	if (broker.askEnabled) {
+		server.registerTool(
+			"ask",
+			{
+				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.",
+				inputSchema: questionInput.extend({
+					sessionId: z
+						.string()
+						.optional()
+						.describe(
+							"Pi session for this question; defaults to this chat's session",
+						),
+				}),
+				outputSchema: questionSchema,
+				annotations: toolAnnotations,
+				_meta: { ui: { resourceUri: questionTemplate } },
+			},
+			handle(async ({ sessionId, ...input }, context) => {
+				const question = await broker.ask(
+					requireChatId(context),
+					sessionId,
+					input,
+					context.mcpReq.signal,
+				);
+				const result = await finishResult(broker, context, {
+					content: [
+						{
+							type: "text",
+							text: `Question created. Call ask_assert({"questionId":"${question.id}"}) next.`,
+						},
+					],
+				});
+				return {
+					...result,
+					structuredContent: { ...result.structuredContent, question },
+				};
+			}),
+		);
+
+		server.registerTool(
+			"ask_assert",
+			{
+				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.",
+				inputSchema: z.object({
+					questionId: z.string().describe("question.id returned by ask"),
+				}),
+				outputSchema: questionSchema,
+				annotations: toolAnnotations,
+			},
+			handle(async ({ questionId }, context) => {
+				const question = await broker.assertQuestion(
+					requireChatId(context),
+					questionId,
+					context.mcpReq.signal,
+				);
+				const result = await finishResult(broker, context, {
+					content: [{ type: "text", text: "Question widget loaded." }],
+				});
+				return {
+					...result,
+					structuredContent: { ...result.structuredContent, question },
+				};
+			}),
+		);
+
+		server.registerTool(
+			"answer",
+			{
+				title: "Question state",
+				description:
+					"Read a saved question, report widget loading, or save an answer, revision, or skip.",
+				inputSchema: z.object({
+					questionId: z.string(),
+					answer: answerInput.optional(),
+					loaded: z
+						.literal(true)
+						.optional()
+						.describe("The question widget has loaded"),
+				}),
+				outputSchema: questionSchema,
+				annotations: toolAnnotations,
+				_meta: { ui: { visibility: ["app"] }, "openai/widgetAccessible": true },
+			},
+			handle(async ({ questionId, answer, loaded = false }, context) => {
+				const question = await broker.answer(
+					requireChatId(context),
+					questionId,
+					answer,
+					loaded,
+				);
+				const text = answer
+					? answer.skipped
+						? "Question skipped."
+						: "Answer saved."
+					: loaded
+						? "Question widget loaded."
+						: "Question state.";
+				return {
+					content: [{ type: "text", text }],
+					structuredContent: { text, question },
+				};
+			}),
+		);
+
+		server.registerResource(
+			"question",
+			questionTemplate,
+			{ title: "Chappie question", mimeType: "text/html;profile=mcp-app" },
+			async () => ({
+				contents: [
+					{
+						uri: questionTemplate,
+						mimeType: "text/html;profile=mcp-app",
+						text: readFileSync(
+							new URL("./question.html", import.meta.url),
+							"utf8",
+						),
+						_meta: {
+							ui: {
+								prefersBorder: true,
+								csp: { connectDomains: [], resourceDomains: [] },
+							},
+							"openai/widgetDescription":
+								"A persistent question the user can answer while the assistant continues working.",
+						},
+					},
+				],
+			}),
+		);
+	}
+
 	server.registerTool(
 		"tools",
 		{
 			title: "Pi tools",
 			description:
-				"Return complete definitions for active Pi tools. Provide names to inspect only those tools.",
+				"Get full definitions of Pi tools for call. Filter by names, or omit names to list all active tools.",
+			outputSchema,
 			inputSchema: z.object({
 				names: z
 					.array(z.string())
@@ -106,14 +287,9 @@ export function createServer(broker: Broker): McpServer {
 					.optional()
 					.describe("Pi session for this operation only"),
 			}),
-			annotations: {
-				readOnlyHint: true,
-				destructiveHint: false,
-				idempotentHint: true,
-				openWorldHint: false,
-			},
+			annotations: toolAnnotations,
 		},
-		async (args, context) => {
+		handle(async (args, context) => {
 			const { inputs, ...inspected } = await broker.tools(
 				requireChatId(context),
 				args.sessionId,
@@ -128,7 +304,7 @@ export function createServer(broker: Broker): McpServer {
 					inputs,
 				),
 			);
-		},
+		}),
 	);
 
 	server.registerTool(
@@ -136,7 +312,8 @@ export function createServer(broker: Broker): McpServer {
 		{
 			title: "Call Pi tools",
 			description:
-				"Execute one or more active Pi tools as one native batch. Arguments must match definitions returned by tools.",
+				"Execute Pi tools using the definitions returned by tools. Each calls array is one native Pi batch.",
+			outputSchema,
 			inputSchema: z.object({
 				calls: z
 					.array(
@@ -151,12 +328,9 @@ export function createServer(broker: Broker): McpServer {
 					.optional()
 					.describe("Pi session for this operation only"),
 			}),
-			annotations: {
-				destructiveHint: true,
-				openWorldHint: true,
-			},
+			annotations: toolAnnotations,
 		},
-		async (args, context) => {
+		handle(async (args, context) => {
 			const result = await broker.call(
 				requireChatId(context),
 				args.sessionId,
@@ -166,9 +340,14 @@ export function createServer(broker: Broker): McpServer {
 			return finishResult(
 				broker,
 				context,
-				toolResult(result.toolResults, result.sessionId, result.inputs),
+				toolResult(
+					result.toolResults,
+					result.sessionId,
+					result.cwd,
+					result.inputs,
+				),
 			);
-		},
+		}),
 	);
 
 	for (const tool of directTools) {
@@ -177,18 +356,14 @@ export function createServer(broker: Broker): McpServer {
 			{
 				title: tool.name,
 				description: tool.description,
+				outputSchema,
 				inputSchema: tool.inputSchema,
-				annotations: {
-					readOnlyHint: tool.name === "read",
-					destructiveHint: tool.name !== "read",
-					idempotentHint: tool.name === "read",
-					openWorldHint: tool.name === "bash" || tool.name === "transfer",
-				},
+				annotations: toolAnnotations,
 				...(tool.fileParams
 					? { _meta: { "openai/fileParams": tool.fileParams } }
 					: {}),
 			},
-			async (args, context) => {
+			handle(async (args, context) => {
 				const input = { ...args } as Record<string, unknown> & {
 					sessionId?: string;
 				};
@@ -204,9 +379,14 @@ export function createServer(broker: Broker): McpServer {
 				return finishResult(
 					broker,
 					context,
-					toolResult(result.toolResults, result.sessionId, result.inputs),
+					toolResult(
+						result.toolResults,
+						result.sessionId,
+						result.cwd,
+						result.inputs,
+					),
 				);
-			},
+			}),
 		);
 	}
 
@@ -215,21 +395,17 @@ export function createServer(broker: Broker): McpServer {
 		{
 			title: "Local sessions",
 			description:
-				"List online Pi sessions and the current conversation binding without waiting for offline sessions.",
+				"List online Pi sessions with their IDs, devices, cwd, names, execution status, and saved binding counts. Also returns this chat's default.",
+			outputSchema,
 			inputSchema: z.object({
 				sessionId: z
 					.string()
 					.optional()
-					.describe("Return this Pi session when it is online"),
+					.describe("Filter the online list to this Pi session"),
 			}),
-			annotations: {
-				readOnlyHint: true,
-				destructiveHint: false,
-				idempotentHint: true,
-				openWorldHint: false,
-			},
+			annotations: toolAnnotations,
 		},
-		async (args, context) => {
+		handle(async (args, context) => {
 			const chatId = requestChatId(context);
 			const inputs = chatId
 				? await broker.inputs(chatId, args.sessionId, context.mcpReq.signal)
@@ -241,8 +417,8 @@ export function createServer(broker: Broker): McpServer {
 				},
 				inputs,
 			);
-			return chatId ? finishResult(broker, context, result) : result;
-		},
+			return finishResult(broker, context, result);
+		}),
 	);
 
 	server.registerResource(
@@ -283,19 +459,24 @@ function textResult(
 	};
 }
 
-async function finishResult<T extends { content: object[] }>(
-	broker: Broker,
-	context: RequestContext,
-	result: T,
-): Promise<T> {
-	const chatId = requireChatId(context);
-	const deliveries = await broker.deliveries(chatId);
-	const completed = {
-		...result,
-		content: [...result.content, ...deliveryContent(deliveries)],
-	} as T;
-	await broker.acknowledgeDeliveries(deliveries, context.mcpReq.signal);
-	return completed;
+async function finishResult<
+	T extends { content: ReturnType<typeof toolResult>["content"] },
+>(broker: Broker, context: RequestContext, result: T) {
+	const chatId = requestChatId(context);
+	const deliveries = chatId ? await 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 };
 }
 
 function requestChatId(context: RequestContext): string | undefined {