@pi-in-go/pigpen-ahp 0.1.0

package/proof/oracle/src/host/terminal-service.ts

@@ -0,0 +1,346 @@
+import { stat } from "node:fs/promises";
+import { userInfo } from "node:os";
+import { basename } from "node:path";
+import {
+	ActionType,
+	AhpErrorCodes,
+	type CreateTerminalParams,
+	type StateAction,
+	TerminalClaimKind,
+	TerminalLifecycleStatus,
+	type TerminalState,
+	type URI,
+} from "@microsoft/agent-host-protocol";
+import { spawn as spawnPty } from "node-pty";
+import { terminalInfo } from "../channels/terminal.ts";
+import { channelKind, ROOT_CHANNEL, sessionIdFromUri } from "../core/channels.ts";
+import type { AhpHost, TerminalHandler } from "../core/host.ts";
+import { fileUriToPath, pathToFileUri } from "../core/uri.ts";
+import { PI_PROVIDER } from "../pi/provider.ts";
+import { ProtocolError } from "../protocol/errors.ts";
+
+interface Disposable {
+	dispose(): void;
+}
+
+interface PtyProcess {
+	onData(listener: (data: string) => void): Disposable;
+	onExit(listener: (event: { exitCode: number }) => void): Disposable;
+	write(data: string): void;
+	resize(cols: number, rows: number): void;
+	kill(): void;
+}
+
+type PtySpawner = (
+	file: string,
+	args: string[],
+	options: { name: string; cols: number; rows: number; cwd: string },
+) => PtyProcess;
+
+export interface TerminalServiceOptions {
+	readonly defaultWorkingDirectory: string;
+	readonly shell?: string;
+	readonly log?: (message: string) => void;
+}
+
+interface TerminalEntry {
+	readonly pty: PtyProcess;
+	dataListener: Disposable | undefined;
+	exitListener: Disposable | undefined;
+	pendingData: string;
+	flushTimer: NodeJS.Timeout | undefined;
+}
+
+const DEFAULT_COLS = 80;
+const DEFAULT_ROWS = 24;
+const MAX_DIMENSION = 65_535;
+const OUTPUT_BATCH_DELAY_MS = 8;
+const OUTPUT_BATCH_THRESHOLD_CHARS = 16 * 1024;
+
+function validDimension(value: number): boolean {
+	return Number.isSafeInteger(value) && value > 0 && value <= MAX_DIMENSION;
+}
+
+function dimension(value: number | undefined, fallback: number, name: string): number {
+	const result = value ?? fallback;
+	if (!validDimension(result)) {
+		throw ProtocolError.invalidParams(`${name} must be an integer between 1 and ${MAX_DIMENSION}`);
+	}
+	return result;
+}
+
+function defaultShell(): string {
+	try {
+		return userInfo().shell || process.env.SHELL || "sh";
+	} catch {
+		return process.env.SHELL || "sh";
+	}
+}
+
+/**
+ * Bridges terminal actions to independent pseudoterminal processes. `StateStore`
+ * owns every protocol-visible `TerminalState`; the runtime map holds only PTY
+ * handles and output awaiting publication. Terminals are currently client-owned,
+ * so claim transfer is rejected rather than represented in a second state store.
+ */
+export class TerminalService implements TerminalHandler {
+	readonly #host: AhpHost;
+	readonly #options: TerminalServiceOptions;
+	readonly #spawn: PtySpawner;
+	readonly #entries = new Map<URI, TerminalEntry>();
+	readonly #unhookAction: () => void;
+	readonly #unhookValidator: () => void;
+	#closed = false;
+
+	constructor(host: AhpHost, options: TerminalServiceOptions, spawn: PtySpawner = spawnPty) {
+		this.#host = host;
+		this.#options = options;
+		this.#spawn = spawn;
+		this.#unhookValidator = host.addClientActionValidator((channel, action, clientId) =>
+			this.#validateClientAction(channel, action, clientId),
+		);
+		this.#unhookAction = host.onClientAction((channel, action) => this.#applyClientAction(channel, action));
+	}
+
+	async create(params: CreateTerminalParams, clientId: string): Promise<void> {
+		if (this.#closed) {
+			throw new Error("Terminal service is closed");
+		}
+		const channel = params?.channel;
+		if (typeof channel !== "string" || !/^[a-zA-Z][a-zA-Z0-9+.-]*:\/[^/?#]+$/.test(channel)) {
+			throw ProtocolError.invalidParams("createTerminal requires a URI channel");
+		}
+		const inferredKind = channelKind(channel);
+		if (inferredKind !== undefined && inferredKind !== "terminal") {
+			throw ProtocolError.invalidParams(`Channel belongs to ${inferredKind}, not terminal: ${channel}`);
+		}
+		if (sessionIdFromUri(channel, [PI_PROVIDER])) {
+			throw ProtocolError.invalidParams(`Channel uses the ${PI_PROVIDER} session scheme: ${channel}`);
+		}
+		this.#assertAvailable(channel);
+		if (params.claim?.kind !== TerminalClaimKind.Client) {
+			throw ProtocolError.invalidParams("Only client-owned terminals are supported");
+		}
+		if (!clientId || params.claim.clientId !== clientId) {
+			throw ProtocolError.invalidParams("Terminal claim must match the initialized client");
+		}
+		if (params.name !== undefined && typeof params.name !== "string") {
+			throw ProtocolError.invalidParams("Terminal name must be a string");
+		}
+
+		const cols = dimension(params.cols, DEFAULT_COLS, "cols");
+		const rows = dimension(params.rows, DEFAULT_ROWS, "rows");
+		const cwdUri = params.cwd ?? pathToFileUri(this.#options.defaultWorkingDirectory);
+		if (typeof cwdUri !== "string" || !cwdUri.startsWith("file://")) {
+			throw ProtocolError.invalidParams("Terminal cwd must be a file: URI");
+		}
+		let cwd: string;
+		try {
+			cwd = fileUriToPath(cwdUri);
+		} catch {
+			throw ProtocolError.invalidParams(`Invalid terminal cwd: ${cwdUri}`);
+		}
+		let cwdStat: Awaited<ReturnType<typeof stat>>;
+		try {
+			cwdStat = await stat(cwd);
+		} catch {
+			throw ProtocolError.notFound(cwdUri);
+		}
+		if (!cwdStat.isDirectory()) {
+			throw ProtocolError.invalidParams(`Terminal cwd is not a directory: ${cwdUri}`);
+		}
+		// `stat` yielded to other requests; close the duplicate-create race before spawning.
+		this.#assertAvailable(channel);
+
+		const shell = this.#options.shell ?? defaultShell();
+		const title = params.name ?? basename(shell);
+		const pty = this.#spawn(shell, [], {
+			name: "xterm-256color",
+			cols,
+			rows,
+			cwd,
+		});
+		const state: TerminalState = {
+			title,
+			cwd: pathToFileUri(cwd),
+			cols,
+			rows,
+			content: [],
+			lifecycle: { status: TerminalLifecycleStatus.Running },
+			claim: { kind: TerminalClaimKind.Client, clientId },
+			isPty: true,
+		};
+		this.#host.store.create(channel, state, "terminal");
+
+		const entry: TerminalEntry = {
+			pty,
+			dataListener: undefined,
+			exitListener: undefined,
+			pendingData: "",
+			flushTimer: undefined,
+		};
+		this.#entries.set(channel, entry);
+		entry.dataListener = pty.onData((data) => this.#onData(channel, entry, data));
+		entry.exitListener = pty.onExit((event) => this.#onExit(channel, entry, event.exitCode));
+		this.#publishCatalogue();
+	}
+
+	dispose(channel: URI): void {
+		const entry = this.#entries.get(channel);
+		if (entry) this.#remove(channel, entry, true);
+	}
+
+	/** Kills every PTY and unregisters side-effect hooks. Safe to call more than once. */
+	shutdown(): void {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#unhookValidator();
+		this.#unhookAction();
+		const hadEntries = this.#entries.size > 0;
+		for (const [channel, entry] of this.#entries) {
+			this.#remove(channel, entry, false);
+		}
+		if (hadEntries) this.#publishCatalogue();
+	}
+
+	#assertAvailable(channel: URI): void {
+		if (this.#entries.has(channel) || this.#host.store.has(channel)) {
+			throw new ProtocolError(AhpErrorCodes.AlreadyExists, `Terminal already exists: ${channel}`);
+		}
+	}
+
+	#state(channel: URI): TerminalState | undefined {
+		return this.#host.store.kindOf(channel) === "terminal"
+			? (this.#host.store.get(channel) as TerminalState)
+			: undefined;
+	}
+
+	#validateClientAction(channel: URI, action: StateAction, clientId: string): string | undefined {
+		if (this.#host.store.kindOf(channel) !== "terminal") return undefined;
+		const state = this.#state(channel);
+		if (!state || !this.#entries.has(channel)) return "Terminal process is unavailable";
+
+		switch (action.type) {
+			case ActionType.TerminalClaimed:
+				return "This host does not support transferring terminal claims";
+			case ActionType.TerminalInput:
+				if (typeof action.data !== "string") return "Terminal input must be a string";
+				break;
+			case ActionType.TerminalResized:
+				if (!validDimension(action.cols) || !validDimension(action.rows)) {
+					return `Terminal dimensions must be integers between 1 and ${MAX_DIMENSION}`;
+				}
+				break;
+			case ActionType.TerminalTitleChanged:
+				if (typeof action.title !== "string") return "Terminal title must be a string";
+				break;
+			case ActionType.TerminalCleared:
+				break;
+			default:
+				return `This host does not accept ${action.type} on terminal channels`;
+		}
+
+		if (state.claim.kind !== TerminalClaimKind.Client || state.claim.clientId !== clientId) {
+			return "This terminal is claimed by another client";
+		}
+		if (
+			(action.type === ActionType.TerminalInput || action.type === ActionType.TerminalResized) &&
+			state.lifecycle.status !== TerminalLifecycleStatus.Running
+		) {
+			return "Terminal process has exited";
+		}
+		return undefined;
+	}
+
+	#applyClientAction(channel: URI, action: StateAction): void {
+		const entry = this.#entries.get(channel);
+		if (!entry) return;
+		switch (action.type) {
+			case ActionType.TerminalInput:
+				entry.pty.write(action.data);
+				break;
+			case ActionType.TerminalResized:
+				entry.pty.resize(action.cols, action.rows);
+				break;
+			case ActionType.TerminalTitleChanged:
+				this.#publishCatalogue();
+				break;
+			case ActionType.TerminalCleared:
+				// The reducer already cleared retained output; discard older data that
+				// arrived before the action but was still waiting in the output batch.
+				this.#discardPendingData(entry);
+				break;
+		}
+	}
+
+	#onData(channel: URI, entry: TerminalEntry, data: string): void {
+		if (this.#entries.get(channel) !== entry || data.length === 0) return;
+		entry.pendingData += data;
+		if (entry.pendingData.length >= OUTPUT_BATCH_THRESHOLD_CHARS) {
+			this.#flushPendingData(channel, entry);
+			return;
+		}
+		if (!entry.flushTimer) {
+			entry.flushTimer = setTimeout(() => this.#flushPendingData(channel, entry), OUTPUT_BATCH_DELAY_MS);
+			entry.flushTimer.unref?.();
+		}
+	}
+
+	#flushPendingData(channel: URI, entry: TerminalEntry): void {
+		if (entry.flushTimer) clearTimeout(entry.flushTimer);
+		entry.flushTimer = undefined;
+		const data = entry.pendingData;
+		entry.pendingData = "";
+		if (this.#entries.get(channel) !== entry || data.length === 0) return;
+		this.#host.dispatchServerAction(channel, { type: ActionType.TerminalData, data });
+	}
+
+	#discardPendingData(entry: TerminalEntry): void {
+		if (entry.flushTimer) clearTimeout(entry.flushTimer);
+		entry.flushTimer = undefined;
+		entry.pendingData = "";
+	}
+
+	#onExit(channel: URI, entry: TerminalEntry, exitCode: number): void {
+		if (this.#entries.get(channel) !== entry) return;
+		const state = this.#state(channel);
+		if (!state || state.lifecycle.status === TerminalLifecycleStatus.Exited) return;
+		this.#flushPendingData(channel, entry);
+		entry.dataListener?.dispose();
+		entry.exitListener?.dispose();
+		entry.dataListener = undefined;
+		entry.exitListener = undefined;
+		this.#host.dispatchServerAction(channel, { type: ActionType.TerminalExited, exitCode });
+		this.#publishCatalogue();
+	}
+
+	#remove(channel: URI, entry: TerminalEntry, notify: boolean): void {
+		if (this.#entries.get(channel) !== entry) return;
+		if (notify) this.#flushPendingData(channel, entry);
+		else this.#discardPendingData(entry);
+		const state = this.#state(channel);
+		this.#entries.delete(channel);
+		entry.dataListener?.dispose();
+		entry.exitListener?.dispose();
+		if (state?.lifecycle.status === TerminalLifecycleStatus.Running) {
+			if (notify) {
+				this.#host.dispatchServerAction(channel, { type: ActionType.TerminalExited });
+			}
+			try {
+				entry.pty.kill();
+			} catch (error) {
+				this.#options.log?.(`cannot kill terminal ${channel}: ${String(error)}`);
+			}
+		}
+		this.#host.store.delete(channel);
+		if (notify) this.#publishCatalogue();
+	}
+
+	#publishCatalogue(): void {
+		const terminals = [...this.#entries.keys()].sort().flatMap((resource) => {
+			const state = this.#state(resource);
+			return state ? [terminalInfo(resource, state)] : [];
+		});
+		this.#host.dispatchServerAction(ROOT_CHANNEL, { type: ActionType.RootTerminalsChanged, terminals });
+	}
+}

package/proof/oracle/src/pi/activity.ts

@@ -0,0 +1,171 @@
+/**
+ * Human-readable descriptions of what the agent is doing right now.
+ *
+ * `SessionState.activity` / `ChatState.activity` are the protocol's slot for
+ * the line a client shows next to its spinner. Without them a long turn is an
+ * opaque wait — pi's event stream knows it is reading `src/main.ts`, but the
+ * client only sees "working".
+ *
+ * These are display strings, not a machine contract: a client renders them
+ * verbatim, so they should read like something a person would say.
+ */
+
+/** Longest a rendered command or path may be before it is shortened. */
+const MAX_LENGTH = 60;
+
+/**
+ * Shortens the middle rather than the end.
+ *
+ * The informative parts of both a path and a shell command sit at the two ends
+ * — the file name, the flags — so trimming the tail loses the most useful half.
+ */
+function shorten(value: string, limit = MAX_LENGTH): string {
+	const collapsed = value.replace(/\s+/gu, " ").trim();
+	if (collapsed.length <= limit) {
+		return collapsed;
+	}
+	const head = Math.ceil((limit - 1) / 2);
+	const tail = Math.floor((limit - 1) / 2);
+	return `${collapsed.slice(0, head)}…${collapsed.slice(collapsed.length - tail)}`;
+}
+
+/** Renders a path relative to the working directory when it sits underneath it. */
+function displayPath(value: unknown, workingDirectory?: string): string | undefined {
+	if (typeof value !== "string" || value.length === 0) {
+		return undefined;
+	}
+	const relative =
+		workingDirectory && value.startsWith(`${workingDirectory}/`) ? value.slice(workingDirectory.length + 1) : value;
+	return shorten(relative);
+}
+
+/**
+ * Describes a tool invocation.
+ *
+ * pi's built-in tools are named individually so the common cases read well;
+ * anything else — an extension tool, a custom tool — falls back to its own
+ * name, which is still better than nothing.
+ */
+export function describeToolCall(toolName: string, args: unknown, workingDirectory?: string): string {
+	const input = (args ?? {}) as Record<string, unknown>;
+	const path = displayPath(input.path, workingDirectory);
+
+	switch (toolName) {
+		case "read":
+			return path ? `Reading ${path}` : "Reading a file";
+		case "write":
+			return path ? `Writing ${path}` : "Writing a file";
+		case "edit":
+			return path ? `Editing ${path}` : "Editing a file";
+		case "bash": {
+			const command = typeof input.command === "string" ? shorten(input.command) : undefined;
+			return command ? `Running ${command}` : "Running a command";
+		}
+		case "ls":
+			return path ? `Listing ${path}` : "Listing files";
+		case "find": {
+			const pattern = typeof input.pattern === "string" ? shorten(input.pattern, 30) : undefined;
+			return pattern ? `Finding ${pattern}` : "Finding files";
+		}
+		case "grep": {
+			const pattern = typeof input.pattern === "string" ? shorten(input.pattern, 30) : undefined;
+			return pattern ? `Searching for ${pattern}` : "Searching";
+		}
+		default:
+			return `Running ${shorten(toolName, 40)}`;
+	}
+}
+
+/**
+ * The one argument that says what a tool call is about.
+ *
+ * `toolInput` is rendered for the call itself, and the protocol carries no
+ * structured parameters next to it, so serialising the whole argument object
+ * spends the field on quoting and braces — a shell command comes out as
+ * `{"command":"ls -la","timeout":5}` rather than something a reader can run.
+ * Anything without an obvious subject keeps the full arguments, which is still
+ * the most informative thing available for it.
+ */
+export function toolInputFor(toolName: string, args: unknown): string | undefined {
+	const input = (args ?? {}) as Record<string, unknown>;
+	switch (toolName) {
+		case "bash":
+			return stringArg(input.command) ?? fullArguments(args);
+		case "grep":
+		case "find":
+			return searchInput(input) ?? fullArguments(args);
+		case "read":
+		case "write":
+		case "edit":
+		case "ls":
+			return stringArg(input.path) ?? fullArguments(args);
+		default:
+			return fullArguments(args);
+	}
+}
+
+function stringArg(value: unknown): string | undefined {
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function fullArguments(args: unknown): string | undefined {
+	return args === undefined ? undefined : JSON.stringify(args, null, 2);
+}
+
+/**
+ * A search rendered as its pattern plus whatever narrows it.
+ *
+ * The pattern alone loses the difference between searching one directory and
+ * searching the tree. Models fill the defaults in explicitly — a capture has
+ * `path: "."`, a glob matching everything, `ignoreCase: false`, `limit: 100`
+ * — so appending everything present would bury the pattern in restated
+ * defaults. Only arguments that actually narrow the search are shown, in the
+ * order `rg` writes them, which is also how they read aloud.
+ */
+function searchInput(input: Record<string, unknown>): string | undefined {
+	const pattern = stringArg(input.pattern);
+	if (!pattern) {
+		return undefined;
+	}
+	const parts = [pattern];
+	const glob = stringArg(input.glob);
+	if (glob && glob !== "**/*") {
+		parts.push(`--glob ${glob}`);
+	}
+	if (input.ignoreCase === true) {
+		parts.push("--ignore-case");
+	}
+	const path = stringArg(input.path);
+	if (path && path !== ".") {
+		parts.push(`in ${path}`);
+	}
+	return parts.join(" ");
+}
+
+/**
+ * The same description, phrased for a call that has finished.
+ *
+ * The two sit next to each other in a transcript — one line for a call in
+ * flight, one for a call that completed — so reusing the present-tense text
+ * leaves a finished call still claiming to be running. Only the leading verb
+ * changes, which keeps the subject identical between them.
+ */
+const PAST_TENSE_VERBS: Record<string, string> = {
+	Reading: "Read",
+	Writing: "Wrote",
+	Editing: "Edited",
+	Running: "Ran",
+	Listing: "Listed",
+	Finding: "Found",
+	Searching: "Searched",
+};
+
+export function describeFinishedToolCall(toolName: string, args: unknown, workingDirectory?: string): string {
+	const description = describeToolCall(toolName, args, workingDirectory);
+	const [verb, ...rest] = description.split(" ");
+	const past = verb ? PAST_TENSE_VERBS[verb] : undefined;
+	return past ? [past, ...rest].join(" ") : description;
+}
+
+export const THINKING_ACTIVITY = "Thinking";
+export const RESPONDING_ACTIVITY = "Responding";