@zetaloop/chappie 0.1.0 → 0.2.1

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`. A chat without a default is paired with the first online, unbound Pi session. To resume work in a new chat or branch, use `init` with the original Pi session ID; `sessions` lists projects when the target ID is unknown.
 
 ## Usage
 

package/docs/tools.md

@@ -2,10 +2,10 @@
 
 | 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. |
-| `chat` | Send an assistant message to Pi. |
+| `tools` | Read complete definitions for selected active tools. |
+| `chat` | Display Markdown as an assistant message in Pi. |
 | `call` | Run one or more tools as a Pi batch. |
 | `read` | Read local text or images. |
 | `bash` | Execute a shell command. |
@@ -13,33 +13,51 @@
 | `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.
+For a new task without a specific target, call `init` with `{}` to reuse this chat's default or allocate the first online, unbound Pi session. Sessions register while `chappie/chatgpt` is selected. They can be blank or already contain a task; a remote operation starts a turn when Pi is idle.
+
+`sessions` lists session IDs, working directories, names, status, and `bindingCount`, the number of saved chat defaults pointing to each session. Zero means the session can be allocated automatically. The count includes closed chats; execution status describes Pi activity: `ready` accepts provider output, `executing` handles an operation, and `idle` starts a turn on the next operation.
 
-`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.
+`init.selection` reports how the target was chosen: `existing` reuses this chat's default, `explicit` uses the supplied session ID, and `automatic` allocates the first online session with no saved bindings. Explicit selection also accepts sessions already used by other chats.
 
-Use an ID from that list to select a default with `init`:
+To continue existing work in a new chat or branch, pass the Pi session ID associated with that task in the inherited context:
 
 ```json
 { "sessionId": "<session-id>" }
 ```
 
+This establishes the new chat's default, even when another chat already uses the same Pi session. For a requested project or session without a known ID, select it from `sessions` by working directory or name. When the target is absent or ambiguous, clarify the intended session before running tools. A session being the only one online does not establish that it is the requested target.
+
 The optional `sessionId` on other tools selects a session for that operation. For example, `read` can inspect another project:
 
 ```json
 { "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. The catalog in `init.tools` lists Pi's native and extension tools available through `call`. Chappie's `init`, `sessions`, `tools`, and `chat` are separate top-level MCP tools. Load complete definitions for installed extension tools before calling them:
 
-A single tool uses a one-item `calls` array. To request a batch:
+```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 extension tool uses a one-item `calls` array. To request a batch:
 
 ```json
 {
@@ -52,7 +70,9 @@ A single tool uses a one-item `calls` array. To request a batch:
 
 Each batch returns its results together. Pi determines how its tools run within the batch. Separate calls run in order within one Pi session; different sessions can work independently.
 
-Extension tools execute through Pi, including their interactive prompts. Results include each tool's name, call ID, error status, and original text or image content.
+Extension tools execute through Pi, including their interactive prompts. Each batch starts with its executing `sessionId` and Pi `cwd`, followed by each tool's name, call ID, error status, and original text or image content. The directory is captured when the batch starts; a shell `cd` changes that command's working directory, while the operation stays in the same Pi session.
+
+Every tool declares a `{ text: string }` output. `structuredContent.text` contains the complete text in result order, including Pi input, deferred results, and image references. The same text remains in `content` alongside native images and resource links.
 
 ChatGPT file inputs use the direct `transfer` tool. Its top-level `files` parameter lets the host prepare the files before sending them to Pi.
 
@@ -64,11 +84,11 @@ 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.
+Pi renders the supplied Markdown, including fenced code blocks, and appends the message to the session transcript. Each call completes one assistant message. Later operations start another turn when Pi is idle. The result returns the target `sessionId`, Pi `cwd`, 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.
 
-Explicit cancellation removes a queued request or asks Pi to stop its active batch. Available results from that batch accompany a later reply to the originating chat. `sessions` can retrieve them before another tool call. When ChatGPT stops without sending cancellation, local execution continues.
+Explicit cancellation removes a queued request or asks Pi to stop its active batch. Available results from that batch accompany a later reply to the originating chat, with the original session ID and working directory. `sessions` can retrieve them before another tool call. When ChatGPT stops without sending cancellation, local execution continues.
 
 Host request deadlines include time spent in the queue. Use local facilities such as tmux for work intended to outlive one call.
 

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.1",
+	"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,11 @@ interface ChangeWaiter {
 	onAbort(): void;
 }
 
-export interface InitializedSession extends SessionInspection {
+export interface InitializedSession extends Omit<SessionInspection, "tools"> {
+	selection: "existing" | "explicit" | "automatic";
 	globalAgents?: string;
 	inputs: SessionInput[];
+	tools: { name: string; description: string }[];
 }
 
 export interface InspectedSession extends SessionInspection {
@@ -55,12 +53,14 @@ export interface InspectedSession extends SessionInspection {
 }
 
 export interface ChatResult {
-	message: AssistantMessage;
+	sessionId: string;
+	cwd: string;
 	inputs: SessionInput[];
 }
 
 export interface CallResult {
 	sessionId: string;
+	cwd: string;
 	toolResults: ToolResultMessage[];
 	inputs: SessionInput[];
 }
@@ -70,7 +70,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,16 +101,19 @@ export class Broker {
 		}
 		this.#waiters.clear();
 		this.#sessions.clear();
-		this.#ready.clear();
 		await this.#ipc.close();
 	}
 
-	listSessions(sessionId?: string): SessionDescription[] {
-		if (sessionId) {
-			const session = this.#sessions.get(sessionId);
-			return session ? [session.description] : [];
-		}
-		return [...this.#sessions.values()].map(({ description }) => description);
+	listSessions(
+		sessionId?: string,
+	): (SessionDescription & { bindingCount: number })[] {
+		const counts = this.#state.bindingCounts();
+		return [...this.#sessions.values()]
+			.filter(({ description }) => !sessionId || description.id === sessionId)
+			.map(({ description }) => ({
+				...description,
+				bindingCount: counts.get(description.id) ?? 0,
+			}));
 	}
 
 	binding(chatId: string): string | undefined {
@@ -123,11 +125,25 @@ export class Broker {
 		sessionId: string | undefined,
 		signal: AbortSignal,
 	): Promise<InitializedSession> {
-		const target = await this.#selectSession(chatId, sessionId, signal, true);
+		const { sessionId: target, selection } = await this.#selectSession(
+			chatId,
+			sessionId,
+			signal,
+			true,
+		);
 		const { inspection, inputs } = await this.#inspect(target, signal);
 		const globalAgents = await this.#readGlobalAgents();
 		await this.#ackInputs(target, inputs);
-		return { ...inspection, inputs, ...(globalAgents ? { globalAgents } : {}) };
+		return {
+			selection,
+			...inspection,
+			tools: inspection.tools.map(({ name, description }) => ({
+				name,
+				description: description.split("\n", 1)[0] ?? description,
+			})),
+			inputs,
+			...(globalAgents ? { globalAgents } : {}),
+		};
 	}
 
 	async chat(
@@ -136,7 +152,12 @@ export class Broker {
 		text: string,
 		signal: AbortSignal,
 	): Promise<ChatResult> {
-		const target = await this.#selectSession(chatId, sessionId, signal, false);
+		const { sessionId: target } = await this.#selectSession(
+			chatId,
+			sessionId,
+			signal,
+			false,
+		);
 		const result = await this.#request(
 			target,
 			(id) => ({ type: "chat", id, chatId, sessionId: target, text }),
@@ -144,7 +165,7 @@ export class Broker {
 		);
 		if ("message" in result) {
 			await this.#ackInputs(target, result.inputs);
-			return { message: result.message, inputs: result.inputs };
+			return { sessionId: target, cwd: result.cwd, inputs: result.inputs };
 		}
 		throw new Error("Pi session returned no assistant message");
 	}
@@ -152,12 +173,25 @@ 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 { sessionId: 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(
@@ -166,7 +200,12 @@ export class Broker {
 		calls: ToolInput[],
 		signal: AbortSignal,
 	): Promise<CallResult> {
-		const target = await this.#selectSession(chatId, sessionId, signal, false);
+		const { sessionId: target } = await this.#selectSession(
+			chatId,
+			sessionId,
+			signal,
+			false,
+		);
 		const toolCalls: ToolCall[] = calls.map((call) => ({
 			type: "toolCall",
 			id: `chappie-${randomUUID()}`,
@@ -188,6 +227,7 @@ export class Broker {
 			await this.#ackInputs(target, result.inputs);
 			return {
 				sessionId: target,
+				cwd: result.cwd,
 				toolResults: result.toolResults,
 				inputs: result.inputs,
 			};
@@ -201,8 +241,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 +281,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",
@@ -289,32 +321,34 @@ export class Broker {
 		requestedId: string | undefined,
 		signal: AbortSignal,
 		bindRequested: boolean,
-	): Promise<string> {
+	): Promise<{
+		sessionId: string;
+		selection: InitializedSession["selection"];
+	}> {
 		if (requestedId) {
 			await this.#waitForSession(requestedId, signal);
 			if (bindRequested && this.#state.binding(chatId) !== requestedId) {
 				await this.#state.setBinding(chatId, requestedId);
 				this.#notifyChange();
 			}
-			return requestedId;
+			return { sessionId: requestedId, selection: "explicit" };
 		}
 
 		const boundId = this.#state.binding(chatId);
 		if (boundId) {
 			await this.#waitForSession(boundId, signal);
-			return boundId;
+			return { sessionId: boundId, selection: "existing" };
 		}
 
 		for (;;) {
-			const occupied = this.#state.boundSessions();
-			const candidate = [...this.#ready].find(
-				(sessionId) =>
-					this.#sessions.has(sessionId) && !occupied.has(sessionId),
+			const occupied = this.#state.bindingCounts();
+			const candidate = [...this.#sessions.keys()].find(
+				(sessionId) => !occupied.has(sessionId),
 			);
 			if (candidate) {
 				await this.#state.setBinding(chatId, candidate);
 				this.#notifyChange();
-				return candidate;
+				return { sessionId: candidate, selection: "automatic" };
 			}
 			await this.#waitForChange(signal);
 		}
@@ -427,7 +461,6 @@ export class Broker {
 
 	#removeSession(sessionId: string): void {
 		this.#sessions.delete(sessionId);
-		this.#ready.delete(sessionId);
 		this.#notifyChange();
 	}
 

package/src/delivery.ts

@@ -9,6 +9,7 @@ export interface DeliveryRecord {
 	id: string;
 	chatId: string;
 	sessionId: string;
+	cwd: string;
 	sessionFile?: string;
 	toolCallIds: string[];
 	inlineResults?: ToolResultMessage[];
@@ -57,6 +58,7 @@ export function deliveryContent(deliveries: ResolvedDelivery[]) {
 			text: JSON.stringify({
 				deferredResult: delivery.id,
 				sessionId: delivery.sessionId,
+				cwd: delivery.cwd,
 				error: delivery.error,
 			}),
 		},

package/src/instructions.md

@@ -1,7 +1,13 @@
-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. To continue existing work, call init with the Pi sessionId associated with that task in the context. A new chat or branch establishes its own binding to that ID. For a requested project or session without a known ID, use sessions to match its cwd or name, then init with the chosen ID. If the intended target is absent or ambiguous, resolve the selection with the user before starting work. Pi sessions register while the chappie/chatgpt provider is selected.
 
-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.
+For work without a specific target, init without sessionId reuses the current binding or allocates the first online session with bindingCount zero. These sessions may be blank or already contain a task. Saved bindings persist across broker restarts; explicit init(sessionId) can share a session already used by another chat. init reports its selection as existing, explicit, or automatic. A sessionId on any other tool affects only that operation.
+
+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 display Markdown progress and final messages in Pi, including code examples. Use read, bash, edit, and write directly. init.tools lists Pi's native and extension tools for call; Chappie's init, sessions, tools, and chat are separate top-level MCP tools. Use tools with names to load complete definitions before calling other Pi tools. 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 identify the executing sessionId and Pi cwd. A shell command can access another directory while its session and transcript remain the same. Replies provide their complete text in structuredContent.text, including user input consumed by Pi and results from an earlier explicitly cancelled request. Images and file resources accompany the text as native content blocks. 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/ipc.ts

@@ -44,9 +44,10 @@ export interface SessionInput {
 
 export type SessionResult =
 	| { inspection: SessionInspection; inputs: SessionInput[] }
-	| { message: AssistantMessage; inputs: SessionInput[] }
+	| { message: AssistantMessage; cwd: string; inputs: SessionInput[] }
 	| {
 			message: AssistantMessage;
+			cwd: string;
 			toolResults: ToolResultMessage[];
 			inputs: SessionInput[];
 	  }

package/src/server.ts

@@ -16,6 +16,14 @@ const instructions = readFileSync(
 	"utf8",
 ).trim();
 
+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.",
+		),
+});
+
 interface RequestContext {
 	mcpReq: {
 		_meta?: Record<string, unknown>;
@@ -36,14 +44,20 @@ export function createServer(broker: Broker): McpServer {
 		"init",
 		{
 			title: "Connect to Pi",
-			description: "Connect this ChatGPT conversation to a Pi session.",
+			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.",
+			outputSchema,
 			inputSchema: z.object({
 				sessionId: z
 					.string()
 					.optional()
-					.describe("Pi session to select explicitly"),
+					.describe(
+						"Pi session ID to set as this chat's default, including an already-bound session when resuming work",
+					),
 			}),
 			annotations: {
+				readOnlyHint: false,
+				destructiveHint: false,
 				openWorldHint: false,
 			},
 		},
@@ -62,27 +76,38 @@ export function createServer(broker: Broker): McpServer {
 		"chat",
 		{
 			title: "Reply in Pi",
-			description: "Send one complete assistant message to a Pi session.",
+			description:
+				"Display the supplied Markdown in Pi and append it to the session transcript. Code blocks are displayed as text.",
+			outputSchema,
 			inputSchema: z.object({
-				text: z.string().min(1).describe("Assistant message to display in Pi"),
+				text: z
+					.string()
+					.min(1)
+					.describe("Markdown message, including prose and code examples"),
 				sessionId: z
 					.string()
 					.optional()
 					.describe("Pi session for this operation only"),
 			}),
 			annotations: {
+				readOnlyHint: false,
+				destructiveHint: false,
 				openWorldHint: false,
 			},
 		},
 		async (args, context) => {
 			const chatId = requireChatId(context);
-			const { message, inputs } = await broker.chat(
+			const { sessionId, cwd, 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, cwd }, inputs),
+			);
 		},
 	);
 
@@ -90,8 +115,15 @@ 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 invoked through call. Provide names to inspect selected tools. Chappie's own MCP controls, including init, sessions, and chat, are exposed separately.",
+			outputSchema,
 			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 +131,7 @@ export function createServer(broker: Broker): McpServer {
 			}),
 			annotations: {
 				readOnlyHint: true,
+				destructiveHint: false,
 				idempotentHint: true,
 				openWorldHint: false,
 			},
@@ -107,6 +140,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 +158,9 @@ 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.",
+			outputSchema,
 			inputSchema: z.object({
 				calls: z
 					.array(
@@ -140,6 +176,8 @@ export function createServer(broker: Broker): McpServer {
 					.describe("Pi session for this operation only"),
 			}),
 			annotations: {
+				readOnlyHint: false,
+				destructiveHint: true,
 				openWorldHint: true,
 			},
 		},
@@ -153,7 +191,12 @@ 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,
+				),
 			);
 		},
 	);
@@ -164,11 +207,13 @@ 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",
+					openWorldHint: tool.name === "bash" || tool.name === "transfer",
 				},
 				...(tool.fileParams
 					? { _meta: { "openai/fileParams": tool.fileParams } }
@@ -190,7 +235,12 @@ 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,
+					),
 				);
 			},
 		);
@@ -201,15 +251,17 @@ export function createServer(broker: Broker): McpServer {
 		{
 			title: "Local sessions",
 			description:
-				"List connected Pi sessions and the current conversation binding.",
+				"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.",
+			outputSchema,
 			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,
 			},
@@ -226,7 +278,7 @@ export function createServer(broker: Broker): McpServer {
 				},
 				inputs,
 			);
-			return chatId ? finishResult(broker, context, result) : result;
+			return finishResult(broker, context, result);
 		},
 	);
 
@@ -268,19 +320,19 @@ 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;
+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 content = [...result.content, ...deliveryContent(deliveries)];
+	const structuredContent = {
+		text: content
+			.flatMap((block) => (block.type === "text" ? [block.text] : []))
+			.join("\n"),
+	};
 	await broker.acknowledgeDeliveries(deliveries, context.mcpReq.signal);
-	return completed;
+	return { ...result, content, structuredContent };
 }
 
 function requestChatId(context: RequestContext): string | undefined {

package/src/session.ts

@@ -35,6 +35,7 @@ interface StoreRequest {
 
 interface ActiveRequest {
 	request: RemoteRequest;
+	session: SessionDescription;
 	message: AssistantMessage;
 	completed: boolean;
 	cancelled: boolean;
@@ -298,6 +299,7 @@ export class LocalSession {
 		this.#queue.shift();
 		this.#active = {
 			request,
+			session: this.#description(),
 			message: output.message,
 			completed: false,
 			cancelled: false,
@@ -342,7 +344,7 @@ export class LocalSession {
 		this.#context = context;
 		const active = this.#active;
 		if (!active || message !== active.message) return;
-		const sessionId = context.sessionManager.getSessionId();
+		const sessionId = active.session.id;
 		for (const result of toolResults) rememberImages(sessionId, result.content);
 		active.completed = true;
 		active.toolResults = toolResults;
@@ -354,44 +356,36 @@ export class LocalSession {
 		this.#collectInputs();
 		const inputs = this.#inputs();
 		if (active.cancelled) {
-			const context = this.#context;
-			if (context) {
-				const sessionFile = context.sessionManager.getSessionFile();
-				const delivery: DeliveryRecord = {
-					id: randomUUID(),
-					chatId: active.request.chatId,
-					sessionId: context.sessionManager.getSessionId(),
-					toolCallIds:
-						active.request.type === "call"
-							? active.request.calls.map(({ id }) => id)
-							: [],
-					...(sessionFile
-						? { sessionFile }
-						: { inlineResults: active.toolResults }),
-					...(active.message.errorMessage
-						? { error: active.message.errorMessage }
-						: { error: "Request cancelled" }),
-				};
-				this.#deliveries.set(delivery.id, delivery);
-				await this.#flushDeliveries().catch(() => {});
-			}
+			const sessionFile = active.session.sessionFile;
+			const delivery: DeliveryRecord = {
+				id: randomUUID(),
+				chatId: active.request.chatId,
+				sessionId: active.session.id,
+				cwd: active.session.cwd,
+				toolCallIds:
+					active.request.type === "call"
+						? active.request.calls.map(({ id }) => id)
+						: [],
+				...(sessionFile
+					? { sessionFile }
+					: { inlineResults: active.toolResults }),
+				...(active.message.errorMessage
+					? { error: active.message.errorMessage }
+					: { error: "Request cancelled" }),
+			};
+			this.#deliveries.set(delivery.id, delivery);
+			await this.#flushDeliveries().catch(() => {});
 		} else {
-			await this.#connection?.send(
-				active.request.type === "call"
-					? {
-							type: "result",
-							id: active.request.id,
-							message: active.message,
-							toolResults: active.toolResults,
-							inputs,
-						}
-					: {
-							type: "result",
-							id: active.request.id,
-							message: active.message,
-							inputs,
-						},
-			);
+			await this.#connection?.send({
+				type: "result",
+				id: active.request.id,
+				cwd: active.session.cwd,
+				message: active.message,
+				inputs,
+				...(active.request.type === "call"
+					? { toolResults: active.toolResults }
+					: {}),
+			});
 		}
 		this.#active = undefined;
 		this.#status = "idle";

package/src/state.ts

@@ -40,8 +40,12 @@ export class State {
 		return this.#bindings.get(chatId);
 	}
 
-	boundSessions(): Set<string> {
-		return new Set(this.#bindings.values());
+	bindingCounts(): Map<string, number> {
+		const counts = new Map<string, number>();
+		for (const sessionId of this.#bindings.values()) {
+			counts.set(sessionId, (counts.get(sessionId) ?? 0) + 1);
+		}
+		return counts;
 	}
 
 	setBinding(chatId: string, sessionId: string): Promise<void> {

package/src/tools.ts

@@ -38,10 +38,12 @@ export const directTools = definitions.map((definition) => ({
 export function toolResult(
 	toolResults: ToolResultMessage[],
 	sessionId: string,
+	cwd: string,
 	inputs: SessionInput[] = [],
 ) {
 	return {
 		content: [
+			{ type: "text" as const, text: JSON.stringify({ sessionId, cwd }) },
 			...toolResults.flatMap((result) => [
 				{
 					type: "text" as const,
@@ -70,7 +72,7 @@ export function inputContent(inputs: SessionInput[]) {
 	return inputs.flatMap(({ id, sessionId, message }) => [
 		{
 			type: "text" as const,
-			text: JSON.stringify({ piInput: id }),
+			text: JSON.stringify({ piInput: id, sessionId }),
 		},
 		...(typeof message.content === "string"
 			? [{ type: "text" as const, text: message.content }]

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" }),
 		),