@zetaloop/chappie 0.3.1 → 0.3.2

package/docs/tools.md

@@ -19,7 +19,7 @@
 
 Call `init` at the start of local work. Without `sessionId`, it reuses the conversation's saved default or selects an online Pi session with no saved ChatGPT binding. Pass a Pi session ID to resume a specific task, including from another ChatGPT conversation or branch.
 
-`sessions` lists connected sessions with their ID, device, working directory, name, execution status, and binding count. A conversation can address another session for one operation by supplying that tool's optional `sessionId`; only `init({ sessionId })` changes the saved default.
+`sessions` lists connected sessions with their ID, device, working directory, name, execution status, and binding count. The first session tool call establishes the default using its `sessionId` or an online session with no saved bindings. Once a default exists, another tool's `sessionId` selects only that operation's target; `init({ sessionId })` changes the default.
 
 Several ChatGPT conversations can use the same Pi session. One conversation can also operate on several Pi sessions explicitly. Requests already assigned to a session continue there even if the conversation later changes its default.
 
@@ -82,7 +82,7 @@ Call `ask_assert` with the returned ID to confirm that the widget loaded:
 { "questionId": "<question-id>" }
 ```
 
-Answers, revisions, and skips arrive later as `webAnswer` in normal Chappie results. `options` can be omitted for a text answer, and `allowMultiple: true` allows several choices. `sessionId` associates the question with a Pi session without changing the conversation's default.
+Answers, revisions, and skips arrive later as `webAnswer` in normal Chappie results. `options` can be omitted for a text answer, and `allowMultiple: true` allows several choices. `sessionId` associates the question with a Pi session using the session selection rules above.
 
 Questions remain available after the assistant response and across broker restarts. Pi's own interactive tools remain ordinary Pi tools and can be invoked through `call`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zetaloop/chappie",
-	"version": "0.3.1",
+	"version": "0.3.2",
 	"description": "Connect ChatGPT to Pi",
 	"devDependencies": {
 		"@earendil-works/pi-ai": "^0.85.1",

package/src/broker.ts

@@ -127,12 +127,7 @@ export class Broker {
 		signal: AbortSignal,
 	): Promise<AbortSignal> {
 		if (!this.#latestWorkflow || !chatId) return signal;
-		const id =
-			typeof requestId === "string"
-				? /^wfr_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}(?=\/|$)/i
-						.exec(requestId)?.[0]
-						.toLowerCase()
-				: undefined;
+		const id = workflowId(requestId);
 		if (!id) return signal;
 		signal.throwIfAborted();
 		const latest = this.#state.workflow(chatId);
@@ -177,17 +172,16 @@ export class Broker {
 	async initialize(
 		chatId: string,
 		sessionId: string | undefined,
+		requestId: unknown,
 		signal: AbortSignal,
 	): Promise<InitializedSession> {
-		const previous = this.#state.binding(chatId);
 		const { sessionId: target, selection } = await this.#selectSession(
 			chatId,
 			sessionId,
+			requestId,
 			signal,
 			true,
 		);
-		if (previous === target)
-			await this.#notify(target, `ChatGPT ${chatId.slice(-4)} joined`);
 		const { inspection, inputs, globalAgents } = await this.#inspect(
 			target,
 			signal,
@@ -209,13 +203,14 @@ export class Broker {
 		chatId: string,
 		sessionId: string | undefined,
 		text: string,
+		requestId: unknown,
 		signal: AbortSignal,
 	): Promise<ChatResult> {
 		const { sessionId: target } = await this.#selectSession(
 			chatId,
 			sessionId,
+			requestId,
 			signal,
-			false,
 		);
 		const result = await this.#request(
 			target,
@@ -233,13 +228,14 @@ export class Broker {
 		chatId: string,
 		sessionId: string | undefined,
 		names: string[] | undefined,
+		requestId: unknown,
 		signal: AbortSignal,
 	): Promise<InspectedSession> {
 		const { sessionId: target } = await this.#selectSession(
 			chatId,
 			sessionId,
+			requestId,
 			signal,
-			false,
 		);
 		const { inspection, inputs } = await this.#inspect(target, signal);
 		await this.#ackInputs(target, inputs);
@@ -257,13 +253,14 @@ export class Broker {
 		chatId: string,
 		sessionId: string | undefined,
 		calls: ToolInput[],
+		requestId: unknown,
 		signal: AbortSignal,
 	): Promise<CallResult> {
 		const { sessionId: target } = await this.#selectSession(
 			chatId,
 			sessionId,
+			requestId,
 			signal,
-			false,
 		);
 		const toolCalls: ToolCall[] = calls.map((call) => ({
 			type: "toolCall",
@@ -297,10 +294,14 @@ export class Broker {
 	async inputs(
 		chatId: string,
 		sessionId: string | undefined,
+		requestId: unknown,
 		signal: AbortSignal,
 	): Promise<SessionInput[]> {
-		const target = sessionId ?? this.#state.binding(chatId);
+		const boundId = this.#state.binding(chatId);
+		const target = sessionId ?? boundId;
 		if (!target || !this.#sessions.has(target)) return [];
+		signal.throwIfAborted();
+		if (target === boundId) await this.#join(chatId, target, requestId);
 		const { inputs } = await this.#inspect(target, signal);
 		await this.#ackInputs(target, inputs);
 		return inputs;
@@ -310,13 +311,14 @@ export class Broker {
 		chatId: string,
 		sessionId: string | undefined,
 		input: QuestionInput,
+		requestId: unknown,
 		signal: AbortSignal,
 	): Promise<Question> {
 		const { sessionId: target } = await this.#selectSession(
 			chatId,
 			sessionId,
+			requestId,
 			signal,
-			false,
 		);
 		const session = this.#sessions.get(target);
 		if (!session) throw new Error(`Pi session ${target} is offline`);
@@ -460,50 +462,66 @@ export class Broker {
 	async #selectSession(
 		chatId: string,
 		requestedId: string | undefined,
+		requestId: unknown,
 		signal: AbortSignal,
-		bindRequested: boolean,
+		bindRequested = false,
 	): Promise<{
 		sessionId: string;
 		selection: InitializedSession["selection"];
 	}> {
 		if (requestedId) {
 			await this.#waitForSession(requestedId, signal);
-			if (bindRequested && this.#state.binding(chatId) !== requestedId) {
-				await this.#bind(chatId, requestedId);
+			signal.throwIfAborted();
+			const boundId = this.#state.binding(chatId);
+			if (bindRequested || !boundId || boundId === requestedId) {
+				await this.#join(chatId, requestedId, requestId, bindRequested);
 			}
 			return { sessionId: requestedId, selection: "explicit" };
 		}
 
-		const boundId = this.#state.binding(chatId);
-		if (boundId) {
-			await this.#waitForSession(boundId, signal);
-			return { sessionId: boundId, selection: "existing" };
-		}
-
 		for (;;) {
+			signal.throwIfAborted();
+			const boundId = this.#state.binding(chatId);
+			if (boundId) {
+				await this.#waitForSession(boundId, signal);
+				signal.throwIfAborted();
+				if (bindRequested || this.#state.binding(chatId) === boundId) {
+					await this.#join(chatId, boundId, requestId, bindRequested);
+				}
+				return { sessionId: boundId, selection: "existing" };
+			}
 			const occupied = this.#state.bindingCounts();
 			const candidate = [...this.#sessions.keys()].find(
 				(sessionId) => !occupied.has(sessionId),
 			);
 			if (candidate) {
-				await this.#bind(chatId, candidate);
+				await this.#join(chatId, candidate, requestId, bindRequested);
 				return { sessionId: candidate, selection: "automatic" };
 			}
 			await this.#waitForChange(signal);
 		}
 	}
 
-	async #bind(chatId: string, sessionId: string): Promise<void> {
+	async #join(
+		chatId: string,
+		sessionId: string,
+		requestId: unknown,
+		explicit = false,
+	): Promise<void> {
 		const previous = this.#state.binding(chatId);
-		await this.#state.setBinding(chatId, sessionId);
-		this.#notifyChange();
-		if (previous) {
-			await this.#notify(previous, `ChatGPT ${chatId.slice(-4)} left`);
-			if (this.#state.chats(previous).length === 0) {
-				await this.#notify(previous, "Ready for ChatGPT");
-			}
+		const workflow = workflowId(requestId);
+		const joined = await this.#state.join(chatId, sessionId, workflow);
+		if (previous !== sessionId) {
+			this.#notifyChange();
+			if (previous)
+				await this.#notify(previous, `ChatGPT ${chatId.slice(-4)} left`);
+		}
+		if (joined || explicit) {
+			await this.#notify(
+				sessionId,
+				`ChatGPT ${chatId.slice(-4)}${workflow ? ` (${workflow.slice(-4)})` : ""} joined`,
+			);
 		}
-		await this.#notify(sessionId, `ChatGPT ${chatId.slice(-4)} joined`);
 	}
 
 	async #notify(sessionId: string, message: string): Promise<void> {
@@ -630,6 +648,14 @@ export class Broker {
 	}
 }
 
+function workflowId(requestId: unknown): string | undefined {
+	return typeof requestId === "string"
+		? /^wfr_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}(?=\/|$)/i
+				.exec(requestId)?.[0]
+				.toLowerCase()
+		: undefined;
+}
+
 function abortError(signal: AbortSignal): Error {
 	return signal.reason instanceof Error
 		? signal.reason

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. For a task without a specified target, omitting sessionId reuses that default or selects the first online session with no saved bindings. These sessions may already contain work. Defaults survive broker restarts, and several chats can share one Pi session. Other tools' sessionId affects only that call.
+init sets this chat's default Pi session. A session 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.
 
 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.
 

package/src/server.ts

@@ -96,6 +96,7 @@ export function createServer(broker: Broker): McpServer {
 			const { inputs, ...initialized } = await broker.initialize(
 				chatId,
 				args.sessionId,
+				context.mcpReq._meta?.["otunnel/requestId"],
 				context.mcpReq.signal,
 			);
 			return finishResult(broker, context, textResult(initialized, inputs));
@@ -114,7 +115,9 @@ export function createServer(broker: Broker): McpServer {
 				sessionId: z
 					.string()
 					.optional()
-					.describe("Pi session for this operation only"),
+					.describe(
+						"Pi session for this operation; becomes the default if none is set",
+					),
 			}),
 			annotations: toolAnnotations,
 		},
@@ -124,6 +127,7 @@ export function createServer(broker: Broker): McpServer {
 				chatId,
 				args.sessionId,
 				args.text,
+				context.mcpReq._meta?.["otunnel/requestId"],
 				context.mcpReq.signal,
 			);
 			return finishResult(
@@ -158,6 +162,7 @@ export function createServer(broker: Broker): McpServer {
 					requireChatId(context),
 					sessionId,
 					input,
+					context.mcpReq._meta?.["otunnel/requestId"],
 					context.mcpReq.signal,
 				);
 				const result = await finishResult(broker, context, {
@@ -285,7 +290,9 @@ export function createServer(broker: Broker): McpServer {
 				sessionId: z
 					.string()
 					.optional()
-					.describe("Pi session for this operation only"),
+					.describe(
+						"Pi session for this operation; becomes the default if none is set",
+					),
 			}),
 			annotations: toolAnnotations,
 		},
@@ -294,6 +301,7 @@ export function createServer(broker: Broker): McpServer {
 				requireChatId(context),
 				args.sessionId,
 				args.names,
+				context.mcpReq._meta?.["otunnel/requestId"],
 				context.mcpReq.signal,
 			);
 			return finishResult(
@@ -326,7 +334,9 @@ export function createServer(broker: Broker): McpServer {
 				sessionId: z
 					.string()
 					.optional()
-					.describe("Pi session for this operation only"),
+					.describe(
+						"Pi session for this operation; becomes the default if none is set",
+					),
 			}),
 			annotations: toolAnnotations,
 		},
@@ -335,6 +345,7 @@ export function createServer(broker: Broker): McpServer {
 				requireChatId(context),
 				args.sessionId,
 				args.calls,
+				context.mcpReq._meta?.["otunnel/requestId"],
 				context.mcpReq.signal,
 			);
 			return finishResult(
@@ -374,6 +385,7 @@ export function createServer(broker: Broker): McpServer {
 					requireChatId(context),
 					sessionId,
 					calls,
+					context.mcpReq._meta?.["otunnel/requestId"],
 					context.mcpReq.signal,
 				);
 				return finishResult(
@@ -408,7 +420,12 @@ export function createServer(broker: Broker): McpServer {
 		handle(async (args, context) => {
 			const chatId = requestChatId(context);
 			const inputs = chatId
-				? await broker.inputs(chatId, args.sessionId, context.mcpReq.signal)
+				? await broker.inputs(
+						chatId,
+						args.sessionId,
+						context.mcpReq._meta?.["otunnel/requestId"],
+						context.mcpReq.signal,
+					)
 				: [];
 			const result = textResult(
 				{

package/src/session.ts

@@ -194,7 +194,6 @@ export class LocalSession {
 			this.#resetInputs(context);
 		}
 		if (!this.#connection) {
-			this.#notify("Connecting to Chappie…");
 			this.#connection = new IpcClient(this.#agentDir, this.#connect, {
 				onOpen: async () => {
 					await this.#sync();

package/src/state.ts

@@ -5,6 +5,7 @@ import type { QuestionAnswer, QuestionRecord } from "./questions.ts";
 
 interface StateFile {
 	bindings?: Record<string, string>;
+	joins?: Record<string, string[]>;
 	workflows?: Record<string, string>;
 	deliveries?: DeliveryRecord[];
 	questions?: QuestionRecord[];
@@ -14,6 +15,7 @@ export class State {
 	readonly #path: string;
 	readonly #temporaryPath: string;
 	readonly #bindings = new Map<string, string>();
+	readonly #joins = new Map<string, Set<string>>();
 	readonly #workflows = new Map<string, string>();
 	readonly #deliveries = new Map<string, DeliveryRecord>();
 	readonly #questions = new Map<string, QuestionRecord>();
@@ -36,6 +38,9 @@ export class State {
 		for (const [chatId, sessionId] of Object.entries(state.bindings ?? {})) {
 			if (typeof sessionId === "string") this.#bindings.set(chatId, sessionId);
 		}
+		for (const [chatId, ids] of Object.entries(state.joins ?? {})) {
+			this.#joins.set(chatId, new Set(ids));
+		}
 		for (const [chatId, id] of Object.entries(state.workflows ?? {})) {
 			this.#workflows.set(chatId, id);
 		}
@@ -59,12 +64,6 @@ export class State {
 		return this.#bindings.get(chatId);
 	}
 
-	chats(sessionId: string): string[] {
-		return [...this.#bindings]
-			.filter(([, target]) => target === sessionId)
-			.map(([chatId]) => chatId);
-	}
-
 	bindingCounts(): Map<string, number> {
 		const counts = new Map<string, number>();
 		for (const sessionId of this.#bindings.values()) {
@@ -73,9 +72,21 @@ export class State {
 		return counts;
 	}
 
-	setBinding(chatId: string, sessionId: string): Promise<void> {
+	async join(
+		chatId: string,
+		sessionId: string,
+		workflowId: string | undefined,
+	): Promise<boolean> {
+		const changed = this.#bindings.get(chatId) !== sessionId;
+		const workflows = changed
+			? new Set<string>()
+			: (this.#joins.get(chatId) ?? new Set<string>());
+		if (!changed && (!workflowId || workflows.has(workflowId))) return false;
 		this.#bindings.set(chatId, sessionId);
-		return this.#save();
+		if (workflowId) workflows.add(workflowId);
+		this.#joins.set(chatId, workflows);
+		await this.#save();
+		return true;
 	}
 
 	deliveries(chatId: string): DeliveryRecord[] {
@@ -168,10 +179,13 @@ export class State {
 	#save(): Promise<void> {
 		const saved = this.#writes.then(async () => {
 			const bindings = Object.fromEntries(this.#bindings);
+			const joins = Object.fromEntries(
+				[...this.#joins].map(([chatId, ids]) => [chatId, [...ids]]),
+			);
 			const workflows = Object.fromEntries(this.#workflows);
 			await writeFile(
 				this.#temporaryPath,
-				`${JSON.stringify({ bindings, workflows, deliveries: [...this.#deliveries.values()], questions: [...this.#questions.values()] }, null, 2)}\n`,
+				`${JSON.stringify({ bindings, joins, workflows, deliveries: [...this.#deliveries.values()], questions: [...this.#questions.values()] }, null, 2)}\n`,
 				{
 					mode: 0o600,
 				},

package/src/tools.ts

@@ -73,7 +73,8 @@ function withSessionId(
 			...copy.properties,
 			sessionId: {
 				type: "string",
-				description: "Pi session for this operation only",
+				description:
+					"Pi session for this operation; becomes the default if none is set",
 			},
 		},
 		additionalProperties: false,