@zetaloop/chappie 0.1.0 → 0.2.0

package/README.md

@@ -25,7 +25,7 @@ Start otunnel with this configuration and add its tunnel as a developer-mode app
 pi --provider chappie --model chatgpt
 ```
 
-Send a task in Pi, then ask ChatGPT to call `init`. Chappie pairs the chat with a ready Pi session.
+Open Pi with the Chappie provider, then ask ChatGPT to call `init`. Chappie pairs the chat with an online Pi session; the first remote operation starts its turn.
 
 ## Usage
 

package/docs/tools.md

@@ -2,9 +2,9 @@
 
 | Tool | Purpose |
 |---|---|
-| `init` | Connect to a Pi session and read its environment, tools, skills, global `AGENTS.md`, and pending input. |
+| `init` | Connect to a Pi session and read its environment, tool catalog, skills, global `AGENTS.md`, and pending input. |
 | `sessions` | List connected Pi sessions and the chat's default session. |
-| `tools` | Read the selected session's active tool definitions. |
+| `tools` | Read complete definitions for selected active tools. |
 | `chat` | Send an assistant message to Pi. |
 | `call` | Run one or more tools as a Pi batch. |
 | `read` | Read local text or images. |
@@ -13,9 +13,17 @@
 | `write` | Write text to a file. |
 | `transfer` | Copy files between ChatGPT and Pi, or export a Pi image as a file. |
 
+## Model environment
+
+The active model is the current ChatGPT conversation. A Pi tool that starts another `chappie/chatgpt` agent cannot create a new browser conversation, so that child waits without a model response. Subagents configured with another provider use that provider normally.
+
+Use ChatGPT's web search, connectors, and cloud tools for remote research and cloud-side work. Chappie tools operate on local files, processes, Pi extensions, and Pi user interfaces. Pi project-memory tools access their local stores; Pi context-reduction tools do not alter the current ChatGPT conversation.
+
+Use `chat` for progress or results that should appear in Pi. When a Pi user decision is needed, load the installed interactive tool definition with `tools` and invoke it through `call`.
+
 ## Sessions
 
-Call `init` with `{}` to reuse the chat's session or pair with the next ready, unbound Pi session. Either side can arrive first. Sending a task in Pi starts its Chappie provider request.
+Call `init` with `{}` to reuse the chat's session or pair with the first online, unbound Pi session. A newly opened Pi session can be selected before its first user message; the first remote operation starts its Chappie provider turn.
 
 `sessions` lists session IDs, working directories, names, and status. `ready` means the provider is accepting output, `executing` means Pi is handling an operation, and `idle` means the next operation will start a turn.
 
@@ -31,15 +39,21 @@ The optional `sessionId` on other tools selects a session for that operation. Fo
 { "path": "package.json", "sessionId": "<session-id>" }
 ```
 
-`sessions({ sessionId })` shows the selected session and retrieves available input and deferred results. It can be called while Pi is executing a tool batch.
+`sessions({ sessionId })` filters the online list and retrieves available input when that session is connected. The call returns immediately when the selected or bound session is offline; the saved binding is still shown, and deferred results remain available.
 
 Several chats can select the same Pi session, and one chat can address several sessions. Defaults are saved in `chappie.state.json` under Pi's agent directory. An existing binding waits for its Pi session to reconnect; `init` with another ID selects a different target.
 
 ## Tool calls
 
-`read`, `bash`, `edit`, and `write` accept Pi's tool parameters plus `sessionId`. Their descriptions provide the current schemas. For installed extension tools, call `tools` and use the returned name and parameters in `call`.
+`read`, `bash`, `edit`, and `write` accept Pi's tool parameters plus `sessionId`. Their descriptions provide the current schemas. `init` lists every active tool by name with a short description. Load complete definitions for installed extension tools before calling them:
+
+```json
+{ "names": ["ask_user", "ctx_search"] }
+```
+
+Omit `names` to return every active definition. Definitions already present in the current ChatGPT context can be reused without another query.
 
-A single tool uses a one-item `calls` array. To request a batch:
+A single extension tool uses a one-item `calls` array. To request a batch:
 
 ```json
 {
@@ -64,7 +78,7 @@ Call `chat` to display a reply in Pi:
 { "text": "Updated the parser and its callers." }
 ```
 
-Each call completes one assistant message. Later operations start another turn when Pi is idle. Use `chat` for text that should appear in Pi.
+Each call completes one assistant message. Later operations start another turn when Pi is idle. The result returns the target session and any new Pi input without repeating the message text.
 
 User messages consumed by Pi accompany later Chappie replies, including images. Steering is delivered when Pi consumes it; follow-up uses Pi's normal follow-up timing.
 

package/package.json

@@ -1,54 +1,55 @@
 {
-  "name": "@zetaloop/chappie",
-  "version": "0.1.0",
-  "description": "Connect ChatGPT to Pi",
-  "devDependencies": {
-    "@earendil-works/pi-ai": "^0.85.1",
-    "@earendil-works/pi-coding-agent": "^0.85.1",
-    "@types/node": "^26.5.1",
-    "typebox": "^1.3.30",
-    "typescript": "^7.0.2"
-  },
-  "keywords": [
-    "pi-package",
-    "chatgpt",
-    "mcp"
-  ],
-  "author": "zetaloop",
-  "license": "MIT",
-  "type": "module",
-  "engines": {
-    "node": ">=26",
-    "pnpm": ">=12"
-  },
-  "pi": {
-    "extensions": [
-      "./src/index.ts"
-    ]
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "typebox": "*"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/server": "^2.0.0",
-    "mime": "^4.1.0",
-    "zod": "^4.6.4"
-  },
-  "files": [
-    "src",
-    "docs"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/zetaloop/chappie.git"
-  },
-  "scripts": {
-    "format": "biome check --write .",
-    "check": "biome check . && tsc"
-  }
-}
+	"name": "@zetaloop/chappie",
+	"version": "0.2.0",
+	"description": "Connect ChatGPT to Pi",
+	"devDependencies": {
+		"@earendil-works/pi-ai": "^0.85.1",
+		"@earendil-works/pi-coding-agent": "^0.85.1",
+		"@types/node": "^26.5.1",
+		"typebox": "^1.3.30",
+		"typescript": "^7.0.2"
+	},
+	"scripts": {
+		"format": "biome check --write .",
+		"check": "biome check . && tsc"
+	},
+	"keywords": [
+		"pi-package",
+		"chatgpt",
+		"mcp"
+	],
+	"author": "zetaloop",
+	"license": "MIT",
+	"packageManager": "pnpm@12.4.1",
+	"type": "module",
+	"engines": {
+		"node": ">=26",
+		"pnpm": ">=12"
+	},
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"typebox": "*"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/server": "^2.0.0",
+		"mime": "^4.1.0",
+		"zod": "^4.6.4"
+	},
+	"files": [
+		"src",
+		"docs"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/zetaloop/chappie.git"
+	}
+}

package/src/broker.ts

@@ -1,11 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import type {
-	AssistantMessage,
-	ToolCall,
-	ToolResultMessage,
-} from "@earendil-works/pi-ai";
+import type { ToolCall, ToolResultMessage } from "@earendil-works/pi-ai";
 import {
 	type DeliveryRecord,
 	type ResolvedDelivery,
@@ -45,9 +41,10 @@ interface ChangeWaiter {
 	onAbort(): void;
 }
 
-export interface InitializedSession extends SessionInspection {
+export interface InitializedSession extends Omit<SessionInspection, "tools"> {
 	globalAgents?: string;
 	inputs: SessionInput[];
+	tools: { name: string; description: string }[];
 }
 
 export interface InspectedSession extends SessionInspection {
@@ -55,7 +52,7 @@ export interface InspectedSession extends SessionInspection {
 }
 
 export interface ChatResult {
-	message: AssistantMessage;
+	sessionId: string;
 	inputs: SessionInput[];
 }
 
@@ -70,7 +67,6 @@ export class Broker {
 	readonly #ipc: IpcServer;
 	readonly #state: State;
 	readonly #sessions = new Map<string, RegisteredSession>();
-	readonly #ready = new Set<string>();
 	readonly #pending = new Map<number, PendingRequest>();
 	readonly #waiters = new Set<ChangeWaiter>();
 	#nextRequestId = 1;
@@ -102,7 +98,6 @@ export class Broker {
 		}
 		this.#waiters.clear();
 		this.#sessions.clear();
-		this.#ready.clear();
 		await this.#ipc.close();
 	}
 
@@ -127,7 +122,15 @@ export class Broker {
 		const { inspection, inputs } = await this.#inspect(target, signal);
 		const globalAgents = await this.#readGlobalAgents();
 		await this.#ackInputs(target, inputs);
-		return { ...inspection, inputs, ...(globalAgents ? { globalAgents } : {}) };
+		return {
+			...inspection,
+			tools: inspection.tools.map(({ name, description }) => ({
+				name,
+				description: description.split("\n", 1)[0] ?? description,
+			})),
+			inputs,
+			...(globalAgents ? { globalAgents } : {}),
+		};
 	}
 
 	async chat(
@@ -144,7 +147,7 @@ export class Broker {
 		);
 		if ("message" in result) {
 			await this.#ackInputs(target, result.inputs);
-			return { message: result.message, inputs: result.inputs };
+			return { sessionId: target, inputs: result.inputs };
 		}
 		throw new Error("Pi session returned no assistant message");
 	}
@@ -152,12 +155,20 @@ export class Broker {
 	async tools(
 		chatId: string,
 		sessionId: string | undefined,
+		names: string[] | undefined,
 		signal: AbortSignal,
 	): Promise<InspectedSession> {
 		const target = await this.#selectSession(chatId, sessionId, signal, false);
 		const { inspection, inputs } = await this.#inspect(target, signal);
 		await this.#ackInputs(target, inputs);
-		return { ...inspection, inputs };
+		const selected = names ? new Set(names) : undefined;
+		return {
+			...inspection,
+			tools: selected
+				? inspection.tools.filter(({ name }) => selected.has(name))
+				: inspection.tools,
+			inputs,
+		};
 	}
 
 	async call(
@@ -201,8 +212,7 @@ export class Broker {
 		signal: AbortSignal,
 	): Promise<SessionInput[]> {
 		const target = sessionId ?? this.#state.binding(chatId);
-		if (!target) return [];
-		await this.#waitForSession(target, signal);
+		if (!target || !this.#sessions.has(target)) return [];
 		const { inputs } = await this.#inspect(target, signal);
 		await this.#ackInputs(target, inputs);
 		return inputs;
@@ -242,17 +252,10 @@ export class Broker {
 	): Promise<void> {
 		switch (message.type) {
 			case "sync": {
-				const previous = this.#sessions.get(message.session.id);
 				this.#sessions.set(message.session.id, {
 					description: message.session,
 					peer,
 				});
-				if (message.session.status === "ready") {
-					if (previous?.description.status !== "ready")
-						this.#ready.add(message.session.id);
-				} else {
-					this.#ready.delete(message.session.id);
-				}
 				this.#notifyChange();
 				await peer.send({
 					type: "synced",
@@ -307,9 +310,8 @@ export class Broker {
 
 		for (;;) {
 			const occupied = this.#state.boundSessions();
-			const candidate = [...this.#ready].find(
-				(sessionId) =>
-					this.#sessions.has(sessionId) && !occupied.has(sessionId),
+			const candidate = [...this.#sessions.keys()].find(
+				(sessionId) => !occupied.has(sessionId),
 			);
 			if (candidate) {
 				await this.#state.setBinding(chatId, candidate);
@@ -427,7 +429,6 @@ export class Broker {
 
 	#removeSession(sessionId: string): void {
 		this.#sessions.delete(sessionId);
-		this.#ready.delete(sessionId);
 		this.#notifyChange();
 	}
 

package/src/instructions.md

@@ -1,7 +1,11 @@
-Chappie connects this ChatGPT conversation to local Pi sessions. Call init before starting work. Omitting sessionId reuses the current binding or pairs with the next Pi session waiting for ChatGPT; specifying sessionId on init selects that Pi session as the new default. A sessionId on any other tool affects only that operation. Use sessions to inspect connected sessions without changing the binding.
+Chappie connects this ChatGPT conversation to local Pi sessions. Call init before starting work. Omitting sessionId reuses the current binding or pairs with the first online, unbound Pi session; specifying sessionId on init selects that Pi session as the new default. A sessionId on any other tool affects only that operation. Use sessions to inspect connected sessions without changing the binding.
 
-Use chat to send one complete assistant message to Pi. Use read, bash, edit, and write directly. Use tools to inspect other active Pi tools and call to execute one or more of them as one native Pi batch. Separate calls remain separate Pi turns; use a call array when tools should share a batch.
+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.
+
+Prefer ChatGPT's web search, connectors, and cloud tools for remote research and cloud-side work. Use Chappie for local files, processes, Pi extensions, and Pi user interfaces. Pi project-memory tools operate on their local stores; Pi context-reduction tools do not change this ChatGPT conversation.
+
+Use chat to send progress and final messages that should appear in Pi. Use read, bash, edit, and write directly. init lists active tools with short descriptions; call tools with their names to load complete definitions before using other Pi tools through call. Use an installed interactive tool through call when input is needed in Pi. Separate calls remain separate Pi turns; use a call array when tools should share a batch.
 
 Use transfer with paths and files to copy ChatGPT files into Pi. Omit files to expose existing Pi paths or chappie:// image references as MCP resources. Relative paths use the Pi working directory, existing targets require overwrite: true, and resource materialization may require host confirmation.
 
-Tool replies may contain user input consumed by Pi or results from an earlier explicitly cancelled request. Continue from those results instead of repeating completed work. Use the local persistent-process facilities for operations that need to outlive one tool request.
+Tool replies may contain user input consumed by Pi or results from an earlier explicitly cancelled request. Continue from those results instead of repeating completed work. Host request deadlines include queueing and execution; use local persistent-process facilities for work intended to outlive one request.

package/src/server.ts

@@ -36,7 +36,8 @@ export function createServer(broker: Broker): McpServer {
 		"init",
 		{
 			title: "Connect to Pi",
-			description: "Connect this ChatGPT conversation to a Pi session.",
+			description:
+				"Connect this ChatGPT conversation to an online Pi session. A sessionId on init becomes the new default.",
 			inputSchema: z.object({
 				sessionId: z
 					.string()
@@ -44,6 +45,7 @@ export function createServer(broker: Broker): McpServer {
 					.describe("Pi session to select explicitly"),
 			}),
 			annotations: {
+				destructiveHint: false,
 				openWorldHint: false,
 			},
 		},
@@ -62,7 +64,7 @@ export function createServer(broker: Broker): McpServer {
 		"chat",
 		{
 			title: "Reply in Pi",
-			description: "Send one complete assistant message to a Pi session.",
+			description: "Display one complete assistant message in Pi.",
 			inputSchema: z.object({
 				text: z.string().min(1).describe("Assistant message to display in Pi"),
 				sessionId: z
@@ -71,18 +73,19 @@ export function createServer(broker: Broker): McpServer {
 					.describe("Pi session for this operation only"),
 			}),
 			annotations: {
+				destructiveHint: false,
 				openWorldHint: false,
 			},
 		},
 		async (args, context) => {
 			const chatId = requireChatId(context);
-			const { message, inputs } = await broker.chat(
+			const { sessionId, inputs } = await broker.chat(
 				chatId,
 				args.sessionId,
 				args.text,
 				context.mcpReq.signal,
 			);
-			return finishResult(broker, context, textResult({ message }, inputs));
+			return finishResult(broker, context, textResult({ sessionId }, inputs));
 		},
 	);
 
@@ -90,8 +93,14 @@ export function createServer(broker: Broker): McpServer {
 		"tools",
 		{
 			title: "Pi tools",
-			description: "List the tools currently active in a Pi session.",
+			description:
+				"Return complete definitions for active Pi tools. Provide names to inspect only those tools.",
 			inputSchema: z.object({
+				names: z
+					.array(z.string())
+					.min(1)
+					.optional()
+					.describe("Tool names to describe; omit to return every active tool"),
 				sessionId: z
 					.string()
 					.optional()
@@ -99,6 +108,7 @@ export function createServer(broker: Broker): McpServer {
 			}),
 			annotations: {
 				readOnlyHint: true,
+				destructiveHint: false,
 				idempotentHint: true,
 				openWorldHint: false,
 			},
@@ -107,6 +117,7 @@ export function createServer(broker: Broker): McpServer {
 			const { inputs, ...inspected } = await broker.tools(
 				requireChatId(context),
 				args.sessionId,
+				args.names,
 				context.mcpReq.signal,
 			);
 			return finishResult(
@@ -124,7 +135,8 @@ export function createServer(broker: Broker): McpServer {
 		"call",
 		{
 			title: "Call Pi tools",
-			description: "Execute one or more tools as a native Pi tool batch.",
+			description:
+				"Execute one or more active Pi tools as one native batch. Arguments must match definitions returned by tools.",
 			inputSchema: z.object({
 				calls: z
 					.array(
@@ -140,6 +152,7 @@ export function createServer(broker: Broker): McpServer {
 					.describe("Pi session for this operation only"),
 			}),
 			annotations: {
+				destructiveHint: true,
 				openWorldHint: true,
 			},
 		},
@@ -167,8 +180,9 @@ export function createServer(broker: Broker): McpServer {
 				inputSchema: tool.inputSchema,
 				annotations: {
 					readOnlyHint: tool.name === "read",
+					destructiveHint: tool.name !== "read",
 					idempotentHint: tool.name === "read",
-					openWorldHint: tool.name === "bash",
+					openWorldHint: tool.name === "bash" || tool.name === "transfer",
 				},
 				...(tool.fileParams
 					? { _meta: { "openai/fileParams": tool.fileParams } }
@@ -201,15 +215,16 @@ export function createServer(broker: Broker): McpServer {
 		{
 			title: "Local sessions",
 			description:
-				"List connected Pi sessions and the current conversation binding.",
+				"List online Pi sessions and the current conversation binding without waiting for offline sessions.",
 			inputSchema: z.object({
 				sessionId: z
 					.string()
 					.optional()
-					.describe("Return only this Pi session when it is online"),
+					.describe("Return this Pi session when it is online"),
 			}),
 			annotations: {
 				readOnlyHint: true,
+				destructiveHint: false,
 				idempotentHint: true,
 				openWorldHint: false,
 			},

package/src/transfer.ts

@@ -18,8 +18,8 @@ interface TransferDetails {
 }
 
 export const transferFile = Type.Object({
-	file_id: Type.String(),
-	download_url: Type.String(),
+	file_id: Type.String({ description: "Host file identifier" }),
+	download_url: Type.String({ description: "Host-provided download URL" }),
 	file_name: Type.Optional(Type.String()),
 	mime_type: Type.Optional(Type.String()),
 });
@@ -28,10 +28,20 @@ export const transfer = {
 	name: "transfer",
 	label: "transfer",
 	description:
-		"Transfer files between ChatGPT and the current Pi session. Provide files to write them to paths; omit files to export existing paths or Chappie image references.",
+		"Copy ChatGPT files into Pi paths, or export Pi paths and Chappie image references as MCP resources. The paths field always names Pi-side sources or destinations.",
 	parameters: Type.Object({
-		paths: Type.Array(Type.String(), { minItems: 1 }),
-		files: Type.Optional(Type.Array(transferFile, { minItems: 1 })),
+		paths: Type.Array(Type.String(), {
+			minItems: 1,
+			description:
+				"Pi paths to import into or export from; chappie:// image references can be exported",
+		}),
+		files: Type.Optional(
+			Type.Array(transferFile, {
+				minItems: 1,
+				description:
+					"ChatGPT files matched to paths by index; omit to export Pi paths",
+			}),
+		),
 		overwrite: Type.Optional(
 			Type.Boolean({ description: "Overwrite existing target files" }),
 		),