@pi-in-go/pigpen-ahp 0.1.0

package/proof/oracle/src/bin/cli.ts

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * `pi-ahp` — starts the host and prints the endpoint clients connect to.
+ */
+
+import { loadDirectListenerSettings, SettingsError } from "../host/direct-settings.ts";
+import { closeOnSignal, startHost, VERSION } from "../host/serve.ts";
+
+function log(message: string): void {
+	process.stderr.write(`${message}\n`);
+}
+
+function flagValue(args: string[], flag: string): string | undefined {
+	const index = args.indexOf(flag);
+	return index >= 0 ? args[index + 1] : undefined;
+}
+
+async function main(): Promise<void> {
+	const args = process.argv.slice(2);
+	if (args.includes("--help") || args.includes("-h")) {
+		log(
+			[
+				`pi-ahp v${VERSION}`,
+				"",
+				"Usage: pi-ahp [--port <n>] [--host <addr>] [--cwd <path>] [--verbose]",
+				"",
+				"Direct-listener settings persist at ~/.pi/ahp/settings.json; the",
+				"port and token are generated on first run.",
+			].join("\n"),
+		);
+		return;
+	}
+
+	const verbose = args.includes("--verbose");
+	const settings = await loadDirectListenerSettings();
+	const workingDirectory = flagValue(args, "--cwd") ?? process.cwd();
+
+	const server = await startHost({
+		host: flagValue(args, "--host") ?? settings.host,
+		port: Number(flagValue(args, "--port") ?? settings.port),
+		connectionToken: settings.token ?? undefined,
+		workingDirectory,
+		...(verbose ? { log } : {}),
+	});
+
+	log(
+		settings.token
+			? `pi-ahp listening on ws://${server.host}:${server.port}?token=${settings.token}`
+			: `pi-ahp listening on ws://${server.host}:${server.port} (no token — anyone who can reach ${server.host} can drive the agent)`,
+	);
+	log(`working directory: ${workingDirectory}`);
+
+	closeOnSignal(server);
+}
+
+try {
+	await main();
+} catch (error) {
+	// A settings problem is the user's to fix, not a crash: print what is wrong
+	// and where, without a stack trace pointing into the store.
+	if (error instanceof SettingsError) {
+		process.stderr.write(`pi-ahp: ${error.message}\n`);
+		process.exit(1);
+	}
+	throw error;
+}

package/proof/oracle/src/bin/tunnel.ts

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * Serves pi-ahp in the fixed Dev Tunnel shape VS Code discovers. Dev Tunnels
+ * controls remote access; the forwarded loopback listener has no URL token.
+ */
+
+import { spawn } from "node:child_process";
+import { startHost, VERSION } from "../host/serve.ts";
+import { DevTunnelCli, TunnelError } from "../tunnel/devtunnel.ts";
+import { displayLabel, nameLabel, TUNNEL_PORT } from "../tunnel/discovery.ts";
+
+function log(message: string): void {
+	process.stderr.write(`${message}\n`);
+}
+
+async function main(): Promise<void> {
+	const args = process.argv.slice(2);
+	if (args.includes("--help") || args.includes("-h")) {
+		log(
+			[
+				`pi-ahp-tunnel v${VERSION}`,
+				"",
+				"Usage: pi-ahp-tunnel [--name <label>] [--cwd <path>] [--verbose]",
+				"",
+				"Reuses this host's tunnel, creating one on the first run. `--name`",
+				"sets the display label shown by clients; without it, an existing",
+				"label is left alone.",
+				"",
+				"Serves the host over a dev tunnel that compatible AHP clients can",
+				"discover. It requires `devtunnel` on PATH and an existing login:",
+				"",
+				"    devtunnel user login -g      GitHub account",
+				"    devtunnel user login         Microsoft account (the default)",
+				"",
+				"Add -d for device-code auth when there is no browser. See",
+				"`devtunnel user login --help` for the rest.",
+				"",
+				"Does not read or modify pi-ahp's direct-listener settings. The",
+				`discovery port is fixed at ${TUNNEL_PORT}; remote access is controlled`,
+				"by Microsoft Dev Tunnels rather than an additional URL token.",
+			].join("\n"),
+		);
+		return;
+	}
+
+	const flag = (name: string): string | undefined => {
+		const index = args.indexOf(name);
+		return index >= 0 ? args[index + 1] : undefined;
+	};
+	const verbose = args.includes("--verbose");
+	const workingDirectory = flag("--cwd") ?? process.cwd();
+
+	const devtunnel = new DevTunnelCli();
+	devtunnel.requireLogin();
+	const requested = flag("--name");
+	const name = requested ? nameLabel(requested) : undefined;
+	if (requested && !name) {
+		log(`ignoring --name ${requested}: nothing left after removing characters a label cannot hold`);
+	}
+
+	const existing = devtunnel.findTunnel();
+	let qualifiedId: string;
+	if (existing) {
+		qualifiedId = existing.tunnelId;
+		const current = displayLabel(existing.labels);
+		if (name && name !== current) {
+			devtunnel.rename(qualifiedId, current, name);
+		}
+		log(`tunnel: ${qualifiedId} (reused${name && name !== current ? `, renamed to ${name}` : ""})`);
+	} else {
+		qualifiedId = devtunnel.createTunnel(name);
+		log(`tunnel: ${qualifiedId} (new${name ? `, named ${name}` : ""})`);
+	}
+	devtunnel.ensurePort(qualifiedId);
+
+	// The host must be up before the tunnel forwards to it, or the first client
+	// through the relay hits a closed port.
+	const server = await startHost({
+		host: "127.0.0.1",
+		port: TUNNEL_PORT,
+		workingDirectory,
+		...(verbose ? { log } : {}),
+	});
+	log(`listening on 127.0.0.1:${server.port}, working directory: ${workingDirectory}`);
+	log("remote access control: Microsoft Dev Tunnels; local listener: no URL token");
+
+	const host = spawn("devtunnel", ["host", qualifiedId], { stdio: "inherit" });
+	let stopping = false;
+	let hostFinished = false;
+
+	// Shutting down goes through the child, not alongside it. Killing the child
+	// and exiting in the same tick raced: `devtunnel host` outlives us, keeps the
+	// relay connection, and the tunnel looks hosted by a process that is gone.
+	const finish = (code: number, failure?: string): void => {
+		if (hostFinished) return;
+		hostFinished = true;
+		if (!stopping && failure) log(failure);
+		void server.close().then(() => process.exit(stopping ? 0 : code));
+	};
+	host.on("exit", (code) => finish(code ?? 1, `devtunnel host exited (${code}); shutting down`));
+	host.on("error", (error) => finish(1, `devtunnel host failed: ${error.message}`));
+
+	const stop = (): void => {
+		if (stopping) {
+			// A second Ctrl-C means the wait itself is the problem.
+			process.exit(1);
+		}
+		stopping = true;
+		host.kill();
+		// A child that will not take SIGTERM should not wedge the terminal;
+		// an orphaned relay is the lesser failure.
+		setTimeout(() => host.kill("SIGKILL"), 5000).unref();
+	};
+	process.on("SIGINT", stop);
+	process.on("SIGTERM", stop);
+	log("");
+	log("Connect from a Dev Tunnel-capable AHP client signed in to the same account.");
+}
+
+try {
+	await main();
+} catch (error) {
+	if (error instanceof TunnelError) {
+		process.stderr.write(`pi-ahp-tunnel: ${error.message}\n`);
+		process.exit(1);
+	}
+	throw error;
+}

package/proof/oracle/src/channels/chat.ts

@@ -0,0 +1,134 @@
+/**
+ * The chat channel — `ahp-chat:/<uuid>`.
+ *
+ * Every session this host serves has exactly one chat. That is why the agent
+ * declares no `multipleChats` capability: its absence is the protocol's way of
+ * telling a client not to call `createChat`.
+ *
+ * @see https://microsoft.github.io/agent-host-protocol/specification/chat-channel
+ */
+
+import {
+	ActionType,
+	ChatOriginKind,
+	type ChatState,
+	type ChatSummary,
+	MessageKind,
+	type ModelSelection,
+	type SessionState,
+	SessionStatus,
+	type URI,
+} from "@microsoft/agent-host-protocol";
+import { chatUri } from "../core/channels.ts";
+import type { AhpHost } from "../core/host.ts";
+
+export function initialChatState(uri: URI, title: string, selection?: ModelSelection): ChatState {
+	return {
+		resource: uri,
+		title,
+		status: SessionStatus.Idle,
+		modifiedAt: new Date().toISOString(),
+		// A session's default chat exists because the user made the session.
+		origin: { kind: ChatOriginKind.User },
+		turns: [],
+		// Seeded before the agent exists. Starting one takes seconds, and a
+		// client that subscribes in the meantime would otherwise find an empty
+		// model picker and be unable to send. The backend refines this once it
+		// is up, if it resolves to something different.
+		...(selection ? { draft: { text: "", origin: { kind: MessageKind.User }, model: selection } } : {}),
+	};
+}
+
+export function chatSummaryOf(state: ChatState): ChatSummary {
+	return {
+		resource: state.resource,
+		title: state.title,
+		status: state.status,
+		modifiedAt: state.modifiedAt,
+		...(state.activity !== undefined ? { activity: state.activity } : {}),
+		...(state.origin !== undefined ? { origin: state.origin } : {}),
+		...(state.interactivity !== undefined ? { interactivity: state.interactivity } : {}),
+		...(state.workingDirectories !== undefined ? { workingDirectories: state.workingDirectories } : {}),
+	};
+}
+
+/**
+ * Creates a session's default chat and registers it in the session catalog.
+ *
+ * The chat id is derived from the session id so that the pairing is
+ * reconstructible without a lookup table, matching how the session URI already
+ * carries pi's session id.
+ */
+export function installDefaultChat(
+	host: AhpHost,
+	sessionChannel: URI,
+	sessionId: string,
+	title: string,
+	selection?: ModelSelection,
+): URI {
+	const uri = chatUri(sessionId);
+	host.store.create(uri, initialChatState(uri, title, selection));
+
+	const summary = chatSummaryOf(host.store.get(uri) as ChatState);
+	host.dispatchServerAction(sessionChannel, { type: ActionType.SessionChatAdded, summary });
+	host.dispatchServerAction(sessionChannel, { type: ActionType.SessionDefaultChatChanged, defaultChat: uri });
+	return uri;
+}
+
+function equalUris(left: readonly URI[] | undefined, right: readonly URI[] | undefined): boolean {
+	if (!left || !right) {
+		return left === right;
+	}
+	return left.length === right.length && left.every((uri, index) => uri === right[index]);
+}
+
+function equalSummary(left: ChatSummary, right: ChatSummary): boolean {
+	return (
+		left.resource === right.resource &&
+		left.title === right.title &&
+		left.status === right.status &&
+		left.activity === right.activity &&
+		left.modifiedAt === right.modifiedAt &&
+		(left.origin === right.origin || JSON.stringify(left.origin) === JSON.stringify(right.origin)) &&
+		left.interactivity === right.interactivity &&
+		equalUris(left.workingDirectories, right.workingDirectories)
+	);
+}
+
+/**
+ * Mirrors a chat's denormalized summary fields into its owning session.
+ *
+ * Partial updates cannot express removal of an optional JSON field: an
+ * `undefined` value disappears on the wire and means "unchanged". Use the
+ * action's full-summary upsert form when one of those fields is cleared.
+ */
+export function syncChatSummary(host: AhpHost, sessionChannel: URI, chatChannel: URI): boolean {
+	const chat = host.store.get(chatChannel) as ChatState | undefined;
+	const session = host.store.get(sessionChannel) as SessionState | undefined;
+	const previous = session?.chats.find((summary) => summary.resource === chatChannel);
+	if (!chat || !previous) {
+		return false;
+	}
+
+	const current = chatSummaryOf(chat);
+	if (equalSummary(previous, current)) {
+		return false;
+	}
+
+	const clearsOptional =
+		(previous.activity !== undefined && current.activity === undefined) ||
+		(previous.origin !== undefined && current.origin === undefined) ||
+		(previous.interactivity !== undefined && current.interactivity === undefined) ||
+		(previous.workingDirectories !== undefined && current.workingDirectories === undefined);
+	if (clearsOptional) {
+		host.dispatchServerAction(sessionChannel, { type: ActionType.SessionChatAdded, summary: current });
+	} else {
+		const { resource: _resource, ...changes } = current;
+		host.dispatchServerAction(sessionChannel, {
+			type: ActionType.SessionChatUpdated,
+			chat: chatChannel,
+			changes,
+		});
+	}
+	return true;
+}

package/proof/oracle/src/channels/root.ts

@@ -0,0 +1,39 @@
+/**
+ * The root channel — `ahp-root://`.
+ *
+ * Exactly one root channel exists per host. It carries the agents this host can
+ * speak to plus host-level config. The session catalogue is deliberately *not*
+ * root state: clients fetch it with `listSessions` and patch it from
+ * `root/session*` notifications.
+ *
+ * @see https://microsoft.github.io/agent-host-protocol/specification/root-channel
+ */
+
+import type { AgentInfo, RootState, SessionSummary, URI } from "@microsoft/agent-host-protocol";
+import { ROOT_CHANNEL } from "../core/channels.ts";
+import type { AhpHost } from "../core/host.ts";
+
+function initialRootState(agents: AgentInfo[] = []): RootState {
+	return { agents, activeSessions: 0 };
+}
+
+/** Registers `ahp-root://` on the host. Must run before any client connects. */
+export function installRootChannel(host: AhpHost, agents: AgentInfo[] = []): void {
+	host.store.create(ROOT_CHANNEL, initialRootState(agents));
+}
+
+// ── Catalogue notifications ───────────────────────────────────────────────
+// Ephemeral and never replayed on reconnect; after reconnecting a client
+// re-fetches the catalogue with `listSessions`.
+
+export function notifySessionAdded(host: AhpHost, summary: SessionSummary): void {
+	host.notify(ROOT_CHANNEL, "root/sessionAdded", { summary });
+}
+
+export function notifySessionRemoved(host: AhpHost, session: URI): void {
+	host.notify(ROOT_CHANNEL, "root/sessionRemoved", { session });
+}
+
+export function notifySessionSummaryChanged(host: AhpHost, session: URI, changes: Partial<SessionSummary>): void {
+	host.notify(ROOT_CHANNEL, "root/sessionSummaryChanged", { session, changes });
+}

package/proof/oracle/src/channels/session.ts

@@ -0,0 +1,118 @@
+/**
+ * The session channel — `ahp-session:/<uuid>`.
+ *
+ * A session is the coordination scope; the conversation itself lives on a chat
+ * channel underneath it. Creation is asynchronous by design: the host returns
+ * immediately with `lifecycle: 'creating'` and dispatches `session/ready` or
+ * `session/creationFailed` once backend startup settles, so a slow agent start
+ * never blocks the client's round-trip.
+ *
+ * @see https://microsoft.github.io/agent-host-protocol/specification/session-channel
+ */
+
+import {
+	type ChatSummary,
+	SessionLifecycle,
+	type SessionState,
+	SessionStatus,
+	type SessionSummary,
+	type URI,
+} from "@microsoft/agent-host-protocol";
+import { pathToFileUri } from "../core/uri.ts";
+
+export function initialSessionState(provider: string, title: string, workingDirectory: string): SessionState {
+	return {
+		provider,
+		title,
+		status: SessionStatus.Idle,
+		lifecycle: SessionLifecycle.Creating,
+		workingDirectories: [pathToFileUri(workingDirectory)],
+		activeClients: [],
+		chats: [],
+	};
+}
+
+/** The low five bits encode activity; higher bits carry independent metadata flags. */
+const STATUS_ACTIVITY_MASK = (1 << 5) - 1;
+
+interface SessionChatAggregate {
+	readonly status: SessionStatus;
+	readonly activity?: string;
+	readonly modifiedAt?: string;
+}
+
+function timestamp(summary: ChatSummary): number {
+	const value = Date.parse(summary.modifiedAt);
+	return Number.isFinite(value) ? value : Number.NEGATIVE_INFINITY;
+}
+
+function mostRecent(chats: readonly ChatSummary[], matches: (chat: ChatSummary) => boolean): ChatSummary | undefined {
+	let latest: ChatSummary | undefined;
+	for (const chat of chats) {
+		if (matches(chat) && (!latest || timestamp(chat) > timestamp(latest))) {
+			latest = chat;
+		}
+	}
+	return latest;
+}
+
+/**
+ * Projects the session-level summary fields AHP derives from its chat catalog.
+ *
+ * The current host exposes one chat, so this is a direct pass-through today.
+ * Keeping the complete 0.9 rule here makes the projection deterministic and
+ * avoids teaching the pi adapter about protocol status bits.
+ */
+export function aggregateSessionChats(state: SessionState): SessionChatAggregate {
+	if (state.chats.length === 0) {
+		return {
+			status: state.status,
+			...(state.activity !== undefined ? { activity: state.activity } : {}),
+		};
+	}
+
+	const latest = mostRecent(state.chats, () => true);
+	if (!latest) {
+		return { status: state.status };
+	}
+	let driver = state.chats.find((chat) => chat.resource === state.defaultChat) ?? latest;
+	const inputNeeded = mostRecent(
+		state.chats,
+		(chat) => (chat.status & SessionStatus.InputNeeded) === SessionStatus.InputNeeded,
+	);
+	const error = mostRecent(state.chats, (chat) => (chat.status & SessionStatus.Error) === SessionStatus.Error);
+	if (inputNeeded) {
+		driver = inputNeeded;
+	} else if (error) {
+		driver = error;
+	}
+
+	const metadataBits = state.status & ~STATUS_ACTIVITY_MASK;
+	const activityBits = driver.status & STATUS_ACTIVITY_MASK;
+	return {
+		status: (metadataBits | activityBits) as SessionStatus,
+		...(driver.activity !== undefined ? { activity: driver.activity } : {}),
+		modifiedAt: latest.modifiedAt,
+	};
+}
+
+export function sessionSummaryOf(
+	resource: URI,
+	createdAt: string,
+	state: SessionState,
+	meta?: Record<string, unknown>,
+): SessionSummary {
+	const aggregate = aggregateSessionChats(state);
+	return {
+		resource,
+		provider: state.provider,
+		title: state.title,
+		status: aggregate.status,
+		// Root summary activity is deliberately omitted for AHP 0.9: its partial
+		// update shape cannot distinguish "clear" from "unchanged" on JSON wire.
+		createdAt,
+		modifiedAt: aggregate.modifiedAt ?? createdAt,
+		...(state.workingDirectories ? { workingDirectories: state.workingDirectories } : {}),
+		...(meta ? { _meta: meta } : {}),
+	};
+}

package/proof/oracle/src/channels/terminal.ts

@@ -0,0 +1,11 @@
+import type { TerminalInfo, TerminalState, URI } from "@microsoft/agent-host-protocol";
+
+/** Root catalogue projection; terminal process handles never enter protocol state. */
+export function terminalInfo(resource: URI, state: TerminalState): TerminalInfo {
+	return {
+		resource,
+		title: state.title,
+		claim: state.claim,
+		lifecycle: state.lifecycle,
+	};
+}

package/proof/oracle/src/core/channels.ts

@@ -0,0 +1,108 @@
+/**
+ * Channel URI scheme helpers.
+ *
+ * Channels are the routing key for the whole protocol: every command and every
+ * notification carries `params.channel`, so `(method, channel)` is enough to
+ * dispatch a message.
+ *
+ * @see https://microsoft.github.io/agent-host-protocol/specification/subscriptions
+ */
+
+import type { URI } from "@microsoft/agent-host-protocol";
+
+export const ROOT_CHANNEL = "ahp-root://";
+
+const SESSION_SCHEME = "ahp-session:";
+const CHAT_SCHEME = "ahp-chat:";
+const TERMINAL_SCHEME = "ahp-terminal:";
+const CHANGESET_SCHEME = "ahp-changeset:";
+export const RESOURCE_WATCH_SCHEME = "ahp-resource-watch:";
+
+export type ChannelKind = "root" | "session" | "chat" | "terminal" | "changeset" | "resourceWatch";
+
+/** Whether an action namespace belongs to the reducer behind a channel. */
+export function actionBelongsToChannel(type: unknown, kind: ChannelKind): boolean {
+	return typeof type === "string" && type.startsWith(`${kind}/`);
+}
+
+function isRootChannel(uri: URI): boolean {
+	return uri === ROOT_CHANNEL;
+}
+
+function isSessionChannel(uri: URI): boolean {
+	return uri.startsWith(`${SESSION_SCHEME}/`);
+}
+
+export function isChatChannel(uri: URI): boolean {
+	return uri.startsWith(`${CHAT_SCHEME}/`);
+}
+
+/**
+ * Classifies a channel URI, or `undefined` for a scheme this host does not
+ * serve.
+ *
+ * Deliberately strict: it drives `subscribe`, where guessing wrong would create
+ * a channel with the wrong reducer. A command that creates a resource can
+ * register its client-chosen URI with an explicit kind instead.
+ */
+export function channelKind(uri: URI): ChannelKind | undefined {
+	if (isRootChannel(uri)) {
+		return "root";
+	}
+	if (isSessionChannel(uri)) {
+		return "session";
+	}
+	if (isChatChannel(uri)) {
+		return "chat";
+	}
+	if (uri.startsWith(`${TERMINAL_SCHEME}/`)) {
+		return "terminal";
+	}
+	if (uri.startsWith(`${CHANGESET_SCHEME}/`)) {
+		return "changeset";
+	}
+	if (uri.startsWith(`${RESOURCE_WATCH_SCHEME}/`)) {
+		return "resourceWatch";
+	}
+	return undefined;
+}
+
+interface SingleSegmentChannel {
+	readonly scheme: string;
+	readonly id: string;
+}
+
+function parseSingleSegmentChannel(uri: URI): SingleSegmentChannel | undefined {
+	const match = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/([^/?#]+)$/.exec(uri);
+	const scheme = match?.[1];
+	const id = match?.[2];
+	return scheme && id ? { scheme: scheme.toLowerCase(), id } : undefined;
+}
+
+/**
+ * Identifies a session from its canonical scheme or explicit provider aliases
+ * given as bare scheme names. Shape alone never makes an unknown URI a session.
+ */
+export function sessionIdFromUri(uri: URI, providerAliases: readonly string[] = []): string | undefined {
+	const parsed = parseSingleSegmentChannel(uri);
+	if (!parsed) {
+		return undefined;
+	}
+	const canonical = SESSION_SCHEME.slice(0, -1);
+	return parsed.scheme === canonical || providerAliases.some((alias) => parsed.scheme === alias.toLowerCase())
+		? parsed.id
+		: undefined;
+}
+
+export function sessionUri(sessionId: string): URI {
+	return `${SESSION_SCHEME}/${sessionId}`;
+}
+
+/** `ahp-chat:/<id>` → `<id>`. Returns `undefined` when the URI is not a chat. */
+export function chatIdFromUri(uri: URI): string | undefined {
+	return isChatChannel(uri) ? uri.slice(`${CHAT_SCHEME}/`.length) || undefined : undefined;
+}
+
+export function chatUri(chatId: string): URI {
+	return `${CHAT_SCHEME}/${chatId}`;
+}