@zetaloop/chappie 0.2.1 → 0.3.1

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,
@@ -20,10 +27,19 @@ const outputSchema = z.object({
 	text: z
 		.string()
 		.describe(
-			"Complete text output, including Pi user input and deferred results. Images and file resources accompany it as native content blocks.",
+			"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>;
@@ -37,31 +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:
-				"Bind this chat to a Pi session. To resume work or a ChatGPT branch, pass that task's Pi sessionId from context; use sessions to locate a requested target when its ID is unknown. Omit sessionId to reuse this chat's default or allocate the first online, unbound session. Returns the selection source.",
+				"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 ID to set as this chat's default, including an already-bound session when resuming work",
-					),
+					.describe("Default Pi session ID; may be shared with other chats"),
 			}),
-			annotations: {
-				readOnlyHint: false,
-				destructiveHint: false,
-				openWorldHint: false,
-			},
+			annotations: toolAnnotations,
 		},
-		async (args, context) => {
+		handle(async (args, context) => {
 			const chatId = requireChatId(context);
 			const { inputs, ...initialized } = await broker.initialize(
 				chatId,
@@ -69,7 +99,7 @@ export function createServer(broker: Broker): McpServer {
 				context.mcpReq.signal,
 			);
 			return finishResult(broker, context, textResult(initialized, inputs));
-		},
+		}),
 	);
 
 	server.registerTool(
@@ -77,25 +107,18 @@ export function createServer(broker: Broker): McpServer {
 		{
 			title: "Reply in Pi",
 			description:
-				"Display the supplied Markdown in Pi and append it to the session transcript. Code blocks are displayed as text.",
+				"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("Markdown message, including prose and code examples"),
+				text: z.string().min(1).describe("Assistant message in Markdown"),
 				sessionId: z
 					.string()
 					.optional()
 					.describe("Pi session for this operation only"),
 			}),
-			annotations: {
-				readOnlyHint: false,
-				destructiveHint: false,
-				openWorldHint: false,
-			},
+			annotations: toolAnnotations,
 		},
-		async (args, context) => {
+		handle(async (args, context) => {
 			const chatId = requireChatId(context);
 			const { sessionId, cwd, inputs } = await broker.chat(
 				chatId,
@@ -108,15 +131,150 @@ export function createServer(broker: Broker): McpServer {
 				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 invoked through call. Provide names to inspect selected tools. Chappie's own MCP controls, including init, sessions, and chat, are exposed separately.",
+				"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
@@ -129,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,
@@ -151,7 +304,7 @@ export function createServer(broker: Broker): McpServer {
 					inputs,
 				),
 			);
-		},
+		}),
 	);
 
 	server.registerTool(
@@ -159,7 +312,7 @@ 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
@@ -175,13 +328,9 @@ export function createServer(broker: Broker): McpServer {
 					.optional()
 					.describe("Pi session for this operation only"),
 			}),
-			annotations: {
-				readOnlyHint: false,
-				destructiveHint: true,
-				openWorldHint: true,
-			},
+			annotations: toolAnnotations,
 		},
-		async (args, context) => {
+		handle(async (args, context) => {
 			const result = await broker.call(
 				requireChatId(context),
 				args.sessionId,
@@ -198,7 +347,7 @@ export function createServer(broker: Broker): McpServer {
 					result.inputs,
 				),
 			);
-		},
+		}),
 	);
 
 	for (const tool of directTools) {
@@ -209,17 +358,12 @@ export function createServer(broker: Broker): McpServer {
 				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;
 				};
@@ -242,7 +386,7 @@ export function createServer(broker: Broker): McpServer {
 						result.inputs,
 					),
 				);
-			},
+			}),
 		);
 	}
 
@@ -251,22 +395,17 @@ export function createServer(broker: Broker): McpServer {
 		{
 			title: "Local sessions",
 			description:
-				"List online Pi sessions, their saved binding counts, and this conversation's default. A zero bindingCount permits automatic pairing; status describes execution. Offline sessions do not delay the listing.",
+				"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)
@@ -279,7 +418,7 @@ export function createServer(broker: Broker): McpServer {
 				inputs,
 			);
 			return finishResult(broker, context, result);
-		},
+		}),
 	);
 
 	server.registerResource(
@@ -325,13 +464,18 @@ async function finishResult<
 >(broker: Broker, context: RequestContext, result: T) {
 	const chatId = requestChatId(context);
 	const deliveries = chatId ? await broker.deliveries(chatId) : [];
-	const content = [...result.content, ...deliveryContent(deliveries)];
+	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.acknowledgeDeliveries(deliveries, context.mcpReq.signal);
+	await broker.acknowledge(deliveries, answers, context.mcpReq.signal);
 	return { ...result, content, structuredContent };
 }