pi-squire 0.15.0 → 0.16.0

package/src/task-replies.ts

@@ -0,0 +1,247 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { settleTask, type TaskEnd, type TaskReply, type TaskState, taskEnd } from "./task-settlement.ts";
+import { readTaskState, taskStatePath, writeTaskState } from "./task-store.ts";
+
+type Inbound = {
+	envelope?: { id?: unknown; from?: unknown; kind?: unknown; body?: unknown };
+	handled?: boolean;
+};
+type ReplyPayload = {
+	to: string;
+	inReplyTo: string[];
+	body: string;
+	status: TaskReply["status"];
+	envelope?: unknown;
+	error?: string;
+};
+export type TaskReplies = { handled(): boolean };
+
+const STARTUP_RETRIES = 2;
+const STARTUP_RETRY_MS = 100;
+
+class Answers {
+	readonly pi: ExtensionAPI;
+	readonly parent: () => string | undefined;
+	readonly canComplete: () => boolean;
+	readonly coordinates: (ctx: ExtensionContext) => boolean;
+	readonly terminal: (ctx: ExtensionContext, ids: readonly string[]) => void;
+	state: TaskState | undefined;
+	path: string | undefined;
+	current: ExtensionContext | undefined;
+	end: TaskEnd | undefined;
+	failed = false;
+	unreadable = false;
+	retry: ReturnType<typeof setImmediate> | undefined;
+	startupRetry: ReturnType<typeof setTimeout> | undefined;
+
+	constructor(
+		pi: ExtensionAPI,
+		parent: () => string | undefined,
+		canComplete: () => boolean,
+		coordinates: (ctx: ExtensionContext) => boolean,
+		terminal: (ctx: ExtensionContext, ids: readonly string[]) => void,
+	) {
+		this.pi = pi;
+		this.parent = parent;
+		this.canComplete = canComplete;
+		this.coordinates = coordinates;
+		this.terminal = terminal;
+	}
+
+	warn(error: unknown, advice?: string): void {
+		this.failed = true;
+		const retained: string = this.state?.outbox.length
+			? "The answer is retained"
+			: "Task reply handling did not complete";
+		const recovery: string = advice ?? `${retained}; retry on reload/reopen or the next settled run.`;
+		this.current?.ui.notify(
+			`delegate: could not handle the task reply: ${String(error)}. ${recovery} Auto-exit is blocked.`,
+			"error",
+		);
+	}
+
+	save(next: TaskState): void {
+		if (this.path === undefined) throw new Error("no task reply state path");
+		writeTaskState(this.path, next);
+		this.state = next;
+	}
+
+	flush(startupRetries = 0): void {
+		if (this.startupRetry !== undefined) clearTimeout(this.startupRetry);
+		this.startupRetry = undefined;
+		if (this.state === undefined) return;
+		try {
+			while (this.state.outbox.length > 0) {
+				const reply: TaskReply = this.state.outbox[0] as TaskReply;
+				const payload: ReplyPayload = {
+					to: this.state.parent,
+					inReplyTo: reply.ids,
+					body: reply.body,
+					status: reply.status,
+				};
+				if (!this.current)
+					throw new Error("task reply context is unavailable; reopen the session to publish the retained answer");
+				this.terminal(this.current, reply.ids);
+				this.pi.events.emit("message:reply", payload);
+				if (payload.error !== undefined || payload.envelope === undefined)
+					throw new Error(payload.error ?? "no message:reply provider installed");
+				// A crash here may resend. Parent correlation suppresses repeated finals.
+				const sent: Set<string> = new Set(reply.ids);
+				this.save({
+					...this.state,
+					requests: this.state.requests.filter((request) => !sent.has(request.id)),
+					outbox: this.state.outbox.slice(1),
+				});
+			}
+			this.failed = false;
+		} catch (error) {
+			this.failed = true;
+			if (startupRetries === 0) this.warn(error);
+			else this.startupRetry = setTimeout(() => this.flush(startupRetries - 1), STARTUP_RETRY_MS).unref();
+		}
+	}
+
+	start(ctx: ExtensionContext): void {
+		this.current = ctx;
+		this.path = taskStatePath(ctx.sessionManager.getSessionId());
+		this.end = undefined;
+		this.failed = false;
+		this.unreadable = false;
+		try {
+			this.state = readTaskState(this.path);
+		} catch (error) {
+			this.state = undefined;
+			this.unreadable = true;
+			this.warn(error);
+		}
+		if (!this.state?.outbox.length) return;
+		// Async session_start handlers between squire and mail can delay provider
+		// initialization past this turn. Retry actual replies briefly, not probes.
+		this.retry = setImmediate(() => {
+			this.retry = undefined;
+			this.flush(STARTUP_RETRIES);
+		});
+	}
+
+	stop(): void {
+		if (this.retry !== undefined) clearImmediate(this.retry);
+		this.retry = undefined;
+		if (this.startupRetry !== undefined) clearTimeout(this.startupRetry);
+		this.startupRetry = undefined;
+		this.current = undefined;
+	}
+
+	takeover(payload: Inbound): void {
+		const envelope: Inbound["envelope"] = payload?.envelope;
+		const owner: string | undefined = this.state?.parent ?? this.parent();
+		if (
+			this.unreadable ||
+			this.current === undefined ||
+			payload.handled ||
+			envelope?.kind !== "request" ||
+			!owner ||
+			envelope.from !== owner ||
+			typeof envelope.id !== "string" ||
+			envelope.id === ""
+		)
+			return;
+		try {
+			// Role lookup can fail on invalid configuration. Wording must not
+			// claim a request without prompting it; launch admission stays strict.
+			let coordinates = false;
+			try {
+				coordinates = this.coordinates(this.current);
+			} catch {
+				/* Keep the original leaf wording. */
+			}
+			const ending: string = coordinates
+				? "Your final task report goes back to it automatically after your child tasks finish and you process their outcomes."
+				: "Your final message this turn goes back to it automatically.";
+			const text: string = `[delegate] Your task, from the session that started you (${owner}). ${ending}\n\n${String(envelope.body ?? "")}`;
+			const base: TaskState = this.state ?? { parent: owner, requests: [], outbox: [] };
+			if (base.requests.some((request) => request.id === envelope.id)) {
+				payload.handled = true;
+				return;
+			}
+			this.save({ ...base, requests: [...base.requests, { id: envelope.id, held: false, seen: true }] });
+			payload.handled = true;
+			this.prompt(text, envelope.id);
+		} catch (error) {
+			this.warn(
+				error,
+				"Task ownership was not recorded and squire did not start the task; fix the storage error and send it again.",
+			);
+		}
+	}
+
+	prompt(text: string, id: string): void {
+		const rejected = (error: unknown): void => {
+			this.unseen(id);
+			this.current?.ui.notify(`delegate: could not start the task: ${String(error)}`, "error");
+		};
+		try {
+			Promise.resolve(this.pi.sendUserMessage(text, { deliverAs: "steer" })).catch(rejected);
+		} catch (error) {
+			rejected(error);
+		}
+	}
+
+	unseen(id: unknown): void {
+		if (this.state === undefined) return;
+		try {
+			this.save({
+				...this.state,
+				requests: this.state.requests.map((request) => (request.id === id ? { ...request, seen: false } : request)),
+			});
+		} catch (error) {
+			this.warn(error);
+		}
+	}
+
+	settle(): void {
+		if (this.state === undefined || this.end === undefined) return;
+		// A stop must still mark held requests at intermediate settles. A
+		// failed intermediate run is otherwise discarded, so recovery's final
+		// run (not an earlier failure) determines the answer.
+		if (!this.end.stopped && !this.canComplete()) {
+			this.end = undefined;
+			return;
+		}
+		try {
+			this.save(settleTask(this.state, this.end));
+			this.end = undefined;
+			this.flush();
+		} catch (error) {
+			this.warn(error);
+		}
+	}
+
+	handled(): boolean {
+		return !this.failed && this.canComplete() && (this.state === undefined || this.state.requests.length === 0);
+	}
+}
+
+/** Restore owed answers even when a session is reopened without launch env. */
+export function registerTaskReplies(
+	pi: ExtensionAPI,
+	parent: string | (() => string | undefined) | undefined = undefined,
+	canComplete: () => boolean = () => true,
+	coordinates: (ctx: ExtensionContext) => boolean = () => false,
+	terminal: (ctx: ExtensionContext, ids: readonly string[]) => void = () => {},
+): TaskReplies {
+	const answers: Answers = new Answers(
+		pi,
+		typeof parent === "function" ? parent : (): string | undefined => parent,
+		canComplete,
+		coordinates,
+		terminal,
+	);
+	pi.on("session_start", (_event, ctx) => answers.start(ctx));
+	pi.on("session_shutdown", () => answers.stop());
+	pi.events.on("message:inbound", (data) => answers.takeover(data as Inbound));
+	pi.on("agent_end", (event, ctx) => {
+		answers.end = taskEnd(event.messages, ctx.signal?.aborted === true);
+	});
+	pi.on("agent_settled", () => answers.settle());
+	return answers;
+}

package/src/task-settlement.ts

@@ -0,0 +1,81 @@
+// Request settlement belongs to squire; asks remain the mail provider's work.
+// Wording and held-through-failure semantics follow pi-session-mail v0.5.0.
+export const NO_ANSWER = "(The session settled with no answer text.)";
+export const TOOK_OVER =
+	"(The user stopped an earlier run partway and took over; the answer that follows is from the run that completed after that.)";
+export const UNSEEN =
+	"(The session was stopped before it read the message. Nothing was done; send it again if it is still needed.)";
+
+export type TaskRequest = { id: string; held: boolean; seen: boolean };
+export type TaskReply = { ids: string[]; body: string; status: "done" | "failed" | "stopped" };
+export type TaskState = { parent: string; requests: TaskRequest[]; outbox: TaskReply[] };
+type Message = { role?: string; content?: unknown; stopReason?: unknown; errorMessage?: unknown };
+export type TaskEnd = { stopped: boolean; error?: string; answer?: string };
+
+function textOf(message: Message): string | undefined {
+	const content = message.content;
+	let text = "";
+	if (typeof content === "string") text = content;
+	else if (Array.isArray(content))
+		text = content
+			.filter((part): part is { type: "text"; text: string } => part?.type === "text" && typeof part.text === "string")
+			.map((part) => part.text)
+			.join("\n");
+	return text.trim() === "" ? undefined : text;
+}
+
+export function taskEnd(messages: readonly unknown[], aborted: boolean): TaskEnd {
+	const assistants: Message[] = (messages as Message[]).filter((message) => message?.role === "assistant");
+	const last: Message | undefined = assistants.at(-1);
+	const stopped: boolean = aborted || last?.stopReason === "aborted";
+	let error: string | undefined;
+	if (!stopped && last?.stopReason === "error")
+		error =
+			typeof last.errorMessage === "string" && last.errorMessage.trim() !== ""
+				? last.errorMessage.trim().replace(/\.+$/, "")
+				: "unknown error";
+	const answer: string | undefined =
+		stopped || error !== undefined
+			? assistants.map(textOf).findLast((text) => text !== undefined)
+			: last && textOf(last);
+	return { stopped, error, answer };
+}
+
+/** Freeze the final body before transport, batching at the provider's 50-id limit. */
+export function settleTask(state: TaskState, end: TaskEnd): TaskState {
+	const requests: TaskRequest[] = [];
+	const groups: Map<string, TaskReply> = new Map();
+	const queued: Set<string> = new Set(state.outbox.flatMap((reply) => reply.ids));
+	for (const request of state.requests) {
+		if (queued.has(request.id)) {
+			requests.push(request);
+			continue;
+		}
+		if (request.seen && (end.stopped || (request.held && end.error !== undefined))) {
+			requests.push({ ...request, held: true });
+			continue;
+		}
+		const reply: TaskReply = describe(request, end);
+		const key: string = JSON.stringify([reply.status, reply.body]);
+		const group: TaskReply = groups.get(key) ?? { ...reply, ids: [] };
+		group.ids.push(request.id);
+		groups.set(key, group);
+		requests.push(request);
+	}
+	const outbox: TaskReply[] = [...state.outbox];
+	for (const group of groups.values())
+		for (let start = 0; start < group.ids.length; start += 50)
+			outbox.push({ ...group, ids: group.ids.slice(start, start + 50) });
+	return { ...state, requests, outbox };
+}
+
+function describe(request: TaskRequest, end: TaskEnd): TaskReply {
+	const ids: string[] = [request.id];
+	if (!request.seen) return { ids, body: UNSEEN, status: "failed" };
+	if (request.held) return { ids, body: `${TOOK_OVER}\n\n${end.answer ?? NO_ANSWER}`, status: "done" };
+	if (end.error !== undefined) {
+		const opening: string = `(The run ended on an error before it finished: ${end.error}. The text that follows, if any, is partial.)`;
+		return { ids, body: opening + (end.answer === undefined ? "" : `\n\n${end.answer}`), status: "failed" };
+	}
+	return { ids, body: end.answer ?? NO_ANSWER, status: "done" };
+}

package/src/task-store.ts

@@ -0,0 +1,26 @@
+// Independent of Pi's transcript buffering: a task can arrive before its first
+// assistant message. Atomic replacement preserves either the old or new outbox.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { TaskState } from "./task-settlement.ts";
+
+export function taskStatePath(session: string): string {
+	return join(getAgentDir(), "squire", "task-replies", `${encodeURIComponent(session)}.json`);
+}
+
+export function readTaskState(path: string): TaskState | undefined {
+	try {
+		return JSON.parse(readFileSync(path, "utf8")) as TaskState;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+export function writeTaskState(path: string, state: TaskState): void {
+	mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+	const temporary: string = `${path}.${process.pid}.tmp`;
+	writeFileSync(temporary, JSON.stringify(state), { mode: 0o600 });
+	renameSync(temporary, path);
+}

package/src/tmux.ts

@@ -39,13 +39,23 @@ export async function requireTmuxVersion(tmux: { version(): Promise<TmuxVersion>
 	}
 }
 
-/**
- * The companion session for a parent in `parentSession`: its own when that is
- * a companion session (marked by pi-squire when it made it), else the name
- * plus `-squire`. The name alone says nothing: a user's session may end in it.
- */
-export function companionName(parentSession: string, isCompanion: boolean): string {
-	return isCompanion ? parentSession : `${parentSession}-squire`;
+/** Pick a managed candidate before any free name, in numeric candidate order. */
+export function companionCandidate(base: string, sessions: ReadonlyMap<string, boolean>): string {
+	const candidates = [...sessions.keys()]
+		.filter(
+			(name) =>
+				name === base || (name.startsWith(`${base}-`) && /^[2-9]$|^[1-9][0-9]+$/.test(name.slice(base.length + 1))),
+		)
+		.sort((a, b) => candidateNumber(base, a) - candidateNumber(base, b));
+	const managed = candidates.find((name) => sessions.get(name) === true);
+	if (managed !== undefined) return managed;
+	let number = 1;
+	while (sessions.has(number === 1 ? base : `${base}-${number}`)) number++;
+	return number === 1 ? base : `${base}-${number}`;
+}
+
+function candidateNumber(base: string, name: string): number {
+	return name === base ? 1 : Number(name.slice(base.length + 1));
 }
 
 /**
@@ -65,6 +75,17 @@ export class WindowOpenError extends Error {
 /** The session the parent's pane is in: its id (`$N`) and name. */
 export type OwnSession = { id: string; name: string };
 
+/** A positively inspected pane on one server incarnation; names are not routing identity. */
+export type PaneLocator = {
+	socket: string;
+	serverPid: number;
+	serverStarted: string;
+	paneId: string;
+	windowId: string;
+	windowName: string;
+	exited: boolean;
+};
+
 export interface TmuxClient {
 	/** Whether this process runs in a tmux pane. */
 	insideTmux(): boolean;
@@ -73,9 +94,13 @@ export interface TmuxClient {
 	/**
 	 * Open a detached window and return its id (for example `@3`) and session.
 	 * `current` opens it in the parent's session; `companion` in
-	 * `<parent's session>-squire`, created when it does not exist.
+	 * the root project's managed companion, created when it does not exist.
 	 */
-	openWindow(spec: WindowSpec, placement: WindowPlacement): Promise<OpenedWindow>;
+	openWindow(spec: WindowSpec, placement: WindowPlacement, companion: string): Promise<OpenedWindow>;
+	/** This process's pane window, for recovering an ambiguous launch at child startup. */
+	currentWindow?(): Promise<{ id: string; name: string } | undefined>;
+	/** Inspect exactly a pane on this client's server; omitted pane means this process's TMUX_PANE. */
+	inspectPane?(paneId?: string): Promise<PaneLocator | undefined>;
 	/** Every window on the server, in one tmux call. */
 	listWindows(): Promise<TmuxWindow[]>;
 	/** Kill a window. */
@@ -109,21 +134,21 @@ function runTmux(args: string[], timeout: number): Promise<string> {
 }
 
 type Run = (args: string[]) => Promise<string>;
-type Parent = { id: string; name: string; companion: boolean };
+type Parent = OwnSession;
 
 /** The user option that marks a session pi-squire made for delegate windows. */
 const COMPANION_OPTION = "@squire-companion";
 
-/** The id, name and companion mark of the session the pane in `TMUX_PANE` belongs to, when known. */
+/** The id and name of the session the pane in `TMUX_PANE` belongs to, when known. */
 async function parentSession(run: Run): Promise<Parent | undefined> {
 	const pane = process.env.TMUX_PANE;
 	if (pane === undefined || pane === "") return undefined;
 	// Only the line's terminator goes: trailing spaces are legal in a session name.
-	const format = `#{session_id}\t#{${COMPANION_OPTION}}\t#{session_name}`;
+	const format = "#{session_id}\t#{session_name}";
 	const out = (await run(["display-message", "-p", "-t", pane, "-F", format])).replace(/\r?\n$/, "");
-	// The name comes last, so it is whatever follows the second tab.
-	const [id, marker, ...name] = out.split("\t");
-	return id.trim() === "" ? undefined : { id: id.trim(), name: name.join("\t"), companion: marker === "1" };
+	// The name comes last, so any tabs within it stay in the name.
+	const [id, ...name] = out.split("\t");
+	return id.trim() === "" ? undefined : { id: id.trim(), name: name.join("\t") };
 }
 
 const envArgs = (spec: WindowSpec): string[] =>
@@ -145,46 +170,62 @@ async function create(run: Run, args: string[]): Promise<string> {
 const failedWith = (err: unknown, text: string): boolean =>
 	err instanceof WindowOpenError && err.message.includes(text);
 
-/**
- * Open a window in the companion session: `new-window`, then on a missing
- * session one `new-session` that makes the delegate its first window and sets
- * `detach-on-destroy off` and the companion mark on that session only, then `new-window` again when
- * another launch created the session first.
- */
-async function openCompanion(run: Run, spec: WindowSpec, session: string): Promise<string> {
-	const newWindow = [
-		"new-window",
-		"-d",
-		"-P",
-		"-F",
-		"#{window_id}",
-		"-n",
-		spec.name,
-		"-c",
-		spec.cwd,
-		...envArgs(spec),
-		"-t",
-		`=${session}:`,
-		"--",
-		...spec.argv,
-	];
+/** Read ownership before choosing a name; exact names are compared in JavaScript. */
+async function companionSessions(
+	run: Run,
+	certainty: "not-opened" | "unknown",
+): Promise<Map<string, { id: string; managed: boolean }>> {
+	let out: string;
 	try {
-		return await create(run, newWindow);
+		out = await run(["list-sessions", "-F", `#{session_id}\t#{${COMPANION_OPTION}}\t#{session_name}`]);
 	} catch (err) {
-		// tmux resolves the target before it creates anything, so nothing was dispatched that could create a window.
-		if (!failedWith(err, "can't find session")) throw err;
-		(err as WindowOpenError).certainty = "not-opened";
+		throw new WindowOpenError((err as Error).message, certainty);
 	}
-	const newSession = ["new-session", "-d", "-s", session, "-n", spec.name, "-c", spec.cwd, ...envArgs(spec)];
-	newSession.push("-P", "-F", "#{window_id}", "--", ...spec.argv);
-	newSession.push(";", "set-option", "-t", `=${session}:`, "detach-on-destroy", "off");
-	newSession.push(";", "set-option", "-t", `=${session}:`, COMPANION_OPTION, "1");
-	try {
-		return await create(run, newSession);
-	} catch (err) {
-		if (!failedWith(err, "duplicate session")) throw err;
+	const sessions = new Map<string, { id: string; managed: boolean }>();
+	for (const line of out.replace(/\r?\n$/, "").split("\n")) {
+		const [id, marker, ...name] = line.split("\t");
+		if (id !== "") sessions.set(name.join("\t"), { id, managed: marker === "1" });
+	}
+	return sessions;
+}
+
+/**
+ * A new-session and its options run in one synchronous tmux command queue.
+ * A duplicate aborts that queue before options run. Re-read ownership after
+ * that race, never treating a duplicate as permission to adopt the winner.
+ * Retry only proven duplicate-name or missing-target failures, not ambiguous task launches.
+ */
+async function openCompanion(run: Run, spec: WindowSpec, base: string): Promise<OpenedWindow> {
+	let certainty: "not-opened" | "unknown" = "not-opened";
+	while (true) {
+		const sessions = await companionSessions(run, certainty);
+		const session = companionCandidate(base, new Map([...sessions].map(([name, value]) => [name, value.managed])));
+		const owned = sessions.get(session);
+		if (owned !== undefined) {
+			const args = ["new-window", "-d", "-P", "-F", "#{window_id}", "-n", spec.name, "-c", spec.cwd, ...envArgs(spec)];
+			// Target the verified session's id, so a replacement with the same name cannot be adopted.
+			args.push("-t", owned.id, "--", ...spec.argv);
+			try {
+				return { id: await create(run, args), session };
+			} catch (err) {
+				if (!failedWith(err, "can't find session")) throw err;
+				// Its last window may have exited since the lookup. Target resolution
+				// failed before tmux could open anything, so select placement again.
+				certainty = "not-opened";
+				continue;
+			}
+		}
+		const args = ["new-session", "-d", "-s", session, "-n", spec.name, "-c", spec.cwd, ...envArgs(spec)];
+		args.push("-P", "-F", "#{window_id}", "--", ...spec.argv);
+		args.push(";", "set-option", "-t", `=${session}:`, COMPANION_OPTION, "1");
+		args.push(";", "set-option", "-t", `=${session}:`, "detach-on-destroy", "off");
+		certainty = "unknown";
+		try {
+			return { id: await create(run, args), session };
+		} catch (err) {
+			if (!failedWith(err, "duplicate session")) throw err;
+		}
 	}
-	return create(run, newWindow);
 }
 
 /** Open a window in the parent's own session, as delegates always did. */
@@ -225,6 +266,32 @@ function navigation(run: Run): Pick<TmuxClient, "ownSession" | "clientFor" | "sw
 	};
 }
 
+async function inspectPane(run: Run, paneId = process.env.TMUX_PANE): Promise<PaneLocator | undefined> {
+	if (!paneId || !/^%[0-9]+$/.test(paneId)) return undefined;
+	const format = "#{socket_path}\t#{pid}\t#{start_time}\t#{pane_id}\t#{window_id}\t#{pane_dead}\t#{window_name}";
+	const out = (await run(["display-message", "-p", "-t", paneId, "-F", format])).replace(/\r?\n$/, "");
+	const [socket, pid, started, pane, window, dead, ...name] = out.split("\t");
+	if (
+		!socket ||
+		!/^\d+$/.test(pid) ||
+		!/^\d+$/.test(started) ||
+		pane !== paneId ||
+		!/^@[0-9]+$/.test(window) ||
+		!["0", "1"].includes(dead) ||
+		!name.length
+	)
+		return undefined;
+	return {
+		socket,
+		serverPid: Number(pid),
+		serverStarted: started,
+		paneId: pane,
+		windowId: window,
+		windowName: name.join("\t"),
+		exited: dead === "1",
+	};
+}
+
 /**
  * The real client. A window is opened relative to the session of the pane in
  * `TMUX_PANE`, not whatever session a client happens to have attached, so it
@@ -247,7 +314,7 @@ export function createTmuxClient(options: { timeoutMs?: number } = {}): TmuxClie
 			return cachedVersion;
 		},
 
-		async openWindow(spec, placement) {
+		async openWindow(spec, placement, companion) {
 			let parent: Parent | undefined;
 			try {
 				parent = await parentSession(run);
@@ -260,8 +327,21 @@ export function createTmuxClient(options: { timeoutMs?: number } = {}): TmuxClie
 			if (known === undefined) {
 				throw new WindowOpenError("could not tell which tmux session this pane is in (TMUX_PANE)", "not-opened");
 			}
-			const session = companionName(known, parent?.companion === true);
-			return { id: await openCompanion(run, spec, session), session };
+			return openCompanion(run, spec, companion);
+		},
+
+		inspectPane: (paneId) => inspectPane(run, paneId),
+
+		async currentWindow() {
+			const pane = process.env.TMUX_PANE;
+			if (!pane) return undefined;
+			const out = (await run(["display-message", "-p", "-t", pane, "-F", "#{window_id}\t#{window_name}"])).replace(
+				/\r?\n$/,
+				"",
+			);
+			const [id, ...name] = out.split("\t");
+			if (!/^@[0-9]+$/.test(id) || !name.length) return undefined;
+			return { id, name: name.join("\t") };
 		},
 
 		async listWindows() {