pi-ahp 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bang Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,11 @@
 # pi-ahp
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+`pi-ahp` is an [Agent Host Protocol](https://github.com/microsoft/agent-host-protocol) host for the [pi coding agent](https://github.com/earendil-works/pi).
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+It embeds pi and makes its sessions available to AHP clients over WebSocket. Interoperability testing currently focuses on [Agent Host support in Visual Studio Code](https://code.visualstudio.com/docs/agents/concepts/agent-host), with [Agent Console](https://qusic.github.io/agent-console/) providing additional AHP client coverage. The host is not limited to either client.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+The project is currently under development and has not been released or distributed yet.
 
-## Purpose
+## License
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `pi-ahp`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+[MIT](LICENSE)

package/dist/bin/cli.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * `pi-ahp` — starts the host and prints the endpoint clients connect to.
+ */
+import { loadDirectListenerSettings, SettingsError } from "../host/direct-settings.js";
+import { closeOnSignal, startHost, VERSION } from "../host/serve.js";
+function log(message) {
+    process.stderr.write(`${message}\n`);
+}
+function flagValue(args, flag) {
+    const index = args.indexOf(flag);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+async function main() {
+    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/dist/bin/tunnel.js

@@ -0,0 +1,115 @@
+#!/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.js";
+import { createTunnel, ensurePort, findTunnel, rename, requireLogin, TunnelError } from "../tunnel/devtunnel.js";
+import { displayLabel, nameLabel, TUNNEL_PORT } from "../tunnel/vscode.js";
+function log(message) {
+    process.stderr.write(`${message}\n`);
+}
+async function main() {
+    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 what VS Code shows in its list; without it, a name given here",
+            "or in VS Code earlier is left alone.",
+            "",
+            "Serves the host over a dev tunnel that VS Code discovers. Needs a",
+            "`devtunnel` on PATH, already logged in:",
+            "",
+            "    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",
+            `port is fixed by VS Code (${TUNNEL_PORT}); remote access is controlled`,
+            "by Microsoft Dev Tunnels rather than an additional URL token.",
+        ].join("\n"));
+        return;
+    }
+    const flag = (name) => {
+        const index = args.indexOf(name);
+        return index >= 0 ? args[index + 1] : undefined;
+    };
+    const verbose = args.includes("--verbose");
+    const workingDirectory = flag("--cwd") ?? process.cwd();
+    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 = findTunnel();
+    let qualifiedId;
+    if (existing) {
+        qualifiedId = existing.tunnelId;
+        const current = displayLabel(existing.labels);
+        if (name && name !== current) {
+            rename(qualifiedId, current, name);
+        }
+        log(`tunnel: ${qualifiedId} (reused${name && name !== current ? `, renamed to ${name}` : ""})`);
+    }
+    else {
+        qualifiedId = createTunnel(name);
+        log(`tunnel: ${qualifiedId} (new${name ? `, named ${name}` : ""})`);
+    }
+    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;
+    // Shutting down goes through the child's `exit`, 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.
+    host.on("exit", (code) => {
+        if (!stopping) {
+            log(`devtunnel host exited (${code}); shutting down`);
+        }
+        void server.close().then(() => process.exit(stopping ? 0 : (code ?? 1)));
+    });
+    const stop = () => {
+        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("In VS Code, enable `chat.remoteAgentHostsEnabled` and sign in to the");
+    log("same account; the tunnel appears in the agent host list.");
+}
+try {
+    await main();
+}
+catch (error) {
+    if (error instanceof TunnelError) {
+        process.stderr.write(`pi-ahp-tunnel: ${error.message}\n`);
+        process.exit(1);
+    }
+    throw error;
+}

package/dist/channels/chat.js

@@ -0,0 +1,105 @@
+/**
+ * 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, MessageKind, SessionStatus, } from "@microsoft/agent-host-protocol";
+import { chatUri } from "../core/channels.js";
+export function initialChatState(uri, title, selection) {
+    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) {
+    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, sessionChannel, sessionId, title, selection) {
+    const uri = chatUri(sessionId);
+    host.store.create(uri, initialChatState(uri, title, selection));
+    const summary = chatSummaryOf(host.store.get(uri));
+    host.dispatchServerAction(sessionChannel, { type: ActionType.SessionChatAdded, summary });
+    host.dispatchServerAction(sessionChannel, { type: ActionType.SessionDefaultChatChanged, defaultChat: uri });
+    return uri;
+}
+function equalUris(left, right) {
+    if (!left || !right) {
+        return left === right;
+    }
+    return left.length === right.length && left.every((uri, index) => uri === right[index]);
+}
+function equalSummary(left, right) {
+    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, sessionChannel, chatChannel) {
+    const chat = host.store.get(chatChannel);
+    const session = host.store.get(sessionChannel);
+    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/dist/channels/root.js

@@ -0,0 +1,30 @@
+/**
+ * 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 { ROOT_CHANNEL } from "../core/channels.js";
+function initialRootState(agents = []) {
+    return { agents, activeSessions: 0 };
+}
+/** Registers `ahp-root://` on the host. Must run before any client connects. */
+export function installRootChannel(host, agents = []) {
+    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, summary) {
+    host.notify(ROOT_CHANNEL, "root/sessionAdded", { summary });
+}
+export function notifySessionRemoved(host, session) {
+    host.notify(ROOT_CHANNEL, "root/sessionRemoved", { session });
+}
+export function notifySessionSummaryChanged(host, session, changes) {
+    host.notify(ROOT_CHANNEL, "root/sessionSummaryChanged", { session, changes });
+}

package/dist/channels/session.js

@@ -0,0 +1,90 @@
+/**
+ * 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 the backend is up, so a slow agent start never
+ * blocks the client's round-trip.
+ *
+ *
+ * @see https://microsoft.github.io/agent-host-protocol/specification/session-channel
+ */
+import { SessionLifecycle, SessionStatus, } from "@microsoft/agent-host-protocol";
+import { pathToFileUri } from "../core/uri.js";
+export function initialSessionState(provider, title, workingDirectory) {
+    return {
+        provider,
+        title,
+        status: SessionStatus.Idle,
+        lifecycle: SessionLifecycle.Creating,
+        workingDirectories: [pathToFileUri(workingDirectory)],
+        activeClients: [],
+        chats: [],
+    };
+}
+/** Bits 0–4 are mutually exclusive activity; later bits are session metadata. */
+const STATUS_ACTIVITY_MASK = (1 << 5) - 1;
+function timestamp(summary) {
+    const value = Date.parse(summary.modifiedAt);
+    return Number.isFinite(value) ? value : Number.NEGATIVE_INFINITY;
+}
+function mostRecent(chats, matches) {
+    let latest;
+    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) {
+    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),
+        ...(driver.activity !== undefined ? { activity: driver.activity } : {}),
+        modifiedAt: latest.modifiedAt,
+    };
+}
+export function sessionSummaryOf(resource, createdAt, state, meta) {
+    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/dist/channels/terminal.js

@@ -0,0 +1,9 @@
+/** Root catalogue projection; terminal process handles never enter protocol state. */
+export function terminalInfo(resource, state) {
+    return {
+        resource,
+        title: state.title,
+        claim: state.claim,
+        lifecycle: state.lifecycle,
+    };
+}

package/dist/core/channels.js

@@ -0,0 +1,87 @@
+/**
+ * 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
+ */
+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:";
+/** Whether an action namespace belongs to the reducer behind a channel. */
+export function actionBelongsToChannel(type, kind) {
+    return typeof type === "string" && type.startsWith(`${kind}/`);
+}
+function isRootChannel(uri) {
+    return uri === ROOT_CHANNEL;
+}
+function isSessionChannel(uri) {
+    return uri.startsWith(`${SESSION_SCHEME}/`);
+}
+export function isChatChannel(uri) {
+    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) {
+    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;
+}
+function parseSingleSegmentChannel(uri) {
+    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, providerAliases = []) {
+    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) {
+    return `${SESSION_SCHEME}/${sessionId}`;
+}
+/** `ahp-chat:/<id>` → `<id>`. Returns `undefined` when the URI is not a chat. */
+export function chatIdFromUri(uri) {
+    return isChatChannel(uri) ? uri.slice(`${CHAT_SCHEME}/`.length) || undefined : undefined;
+}
+export function chatUri(chatId) {
+    return `${CHAT_SCHEME}/${chatId}`;
+}