pi-ahp 0.1.0 → 0.1.1

package/README.md

@@ -1,10 +1,113 @@
 # pi-ahp
 
+[![CI](https://github.com/Qusic/pi-ahp/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/Qusic/pi-ahp/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/pi-ahp)](https://www.npmjs.com/package/pi-ahp)
+[![pi](https://img.shields.io/npm/dependency-version/pi-ahp/@earendil-works/pi-coding-agent?label=pi)](https://github.com/earendil-works/pi)
+[![AHP](https://img.shields.io/npm/dependency-version/pi-ahp/@microsoft/agent-host-protocol?label=AHP)](https://github.com/microsoft/agent-host-protocol)
+[![License](https://img.shields.io/npm/l/pi-ahp)](LICENSE)
+
 `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).
 
-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.
+It embeds pi and makes its sessions available to AHP clients over WebSocket. Interoperability is primarily tested with [Agent Host support in Visual Studio Code](https://code.visualstudio.com/docs/agents/concepts/agent-host) and [Agent Console for iPhone and iPad](https://qusic.github.io/agent-console/), but the host is not limited to either client.
+
+The project is under active development; expect rough edges and occasional instability. Contributions are welcome.
+
+## Requirements
+
+- Node.js 24 or later
+- At least one model provider configured for pi
+
+## Usage
+
+```sh
+npm install --global pi-ahp
+```
+
+`pi-ahp` starts a direct WebSocket listener and prints its connection URL:
+
+```sh
+pi-ahp
+```
+
+On first run, it creates `~/.pi/ahp/settings.json` with a free port and a random token, for example:
+
+```json
+{
+  "host": "127.0.0.1",
+  "port": 32145,
+  "token": "<generated token>"
+}
+```
+
+The token is optional and may be set to `null`. The host and port can also be overridden for one run:
+
+```sh
+pi-ahp --host 127.0.0.1 --port 31546
+```
+
+Enter the printed URL in any AHP client. The direct listener is bring-your-own-network: reach it through Tailscale, SSH port forwarding, a reverse proxy, or any other network you manage. Keep the connection token enabled whenever the listener is reachable beyond localhost.
+
+`pi-ahp-tunnel` instead creates or reuses a Microsoft Dev Tunnel for clients that support it, including VS Code and Agent Console. It requires the [`devtunnel` CLI](https://aka.ms/devtunnels/download) and does not use the direct-listener settings:
+
+```sh
+devtunnel user login
+pi-ahp-tunnel
+```
+
+Run either command with `--help` for all available options.
+
+### Visual Studio Code
+
+VS Code exposes remote Agent Host setup only in its dedicated Agents window, not in a regular editor window. From a regular window, run **Chat: Open Agents Window**.
+
+If the remote-host commands are unavailable, or if you want to use a direct connection without signing in to GitHub, add these settings to VS Code's user `settings.json` before opening the Agents window:
+
+```json
+{
+  "chat.remoteAgentHostsEnabled": true,
+  "chat.agentHost.allowSignedOutWhenUsable": true
+}
+```
+
+The signed-out option is currently experimental and desktop-only. When prompted, choose **Continue Without Signing In**; you do not need to preconfigure a host manually.
+
+- **Direct WebSocket:** run **Agents: Add Remote Agent Host...** and paste the URL printed by `pi-ahp`.
+- **Dev Tunnel:** sign in to the same account in VS Code, then run **Agents: Connect to Remote Agent Host via Dev Tunnel**. Tunnel discovery requires sign-in.
+
+## AHP support
+
+The following is a high-level mapping to the [official AHP specification](https://microsoft.github.io/agent-host-protocol/specification/overview).
+
+Currently supported protocol versions: **0.9.0**
+
+🟢 Supported · 🟡 Planned · 🔴 Out of scope
 
-The project is currently under development and has not been released or distributed yet.
+| Feature | Status | Notes |
+| --- | :---: | --- |
+| Connection lifecycle and reconnect | 🟢 | Active work survives a temporary connection loss, but not a host restart |
+| Durable sessions and history | 🟢 | Completed history for the active conversation branch recovers after restart |
+| Streaming chat and pi tool calls | 🟢 | One chat per session |
+| Steering, queues, drafts, and truncation | 🟢 | Drafts and unconsumed queues do not survive a host restart |
+| Models, session setup, and completions | 🟢 | Model and thinking-level selection, working directory, and `@` file completions |
+| Text attachments | 🟢 | Client-provided text, local file references, and embedded UTF-8 text |
+| Files and watches | 🟢 | Host-local `file:` resources only |
+| Interactive terminals | 🟢 | Client-owned; terminals and scrollback end when the host stops |
+| Images and vision | 🟡 | Pass AHP image attachments to vision-capable pi models |
+| Tool catalogue and client tools | 🟡 | Show available pi tools and let connected clients contribute tools |
+| pi customizations | 🟡 | Show and configure loaded extensions, skills, and prompt templates |
+| Changeset views | 🟡 | Expose uncommitted workspace changes |
+| Terminal command detection | 🟡 | Group terminal output by command and exit status |
+| Persistent read and archive controls | 🔴 | pi sessions do not store this metadata |
+| Multiple chats or working directories | 🔴 | A pi session has one active branch and cwd; branches are not simultaneous AHP chats |
+| Custom agents | 🔴 | pi sub-agents are extension tools rather than selectable agents |
+| Elicitation | 🔴 | pi extension dialogs are not persisted as turn input |
+| Tool input and result confirmation | 🔴 | pi has no built-in permission policy |
+| Errored-turn resume | 🔴 | pi cannot reopen a finalized turn |
+| MCP lifecycle and Apps | 🔴 | pi has no built-in MCP runtime; extension implementations are opaque |
+| Annotations | 🔴 | There is no corresponding pi session state |
+| Automations and automation runs | 🔴 | pi has no scheduler or automation-run model |
+| AHP protected-resource authentication | 🔴 | pi manages model-provider credentials itself |
+| OTLP telemetry channels | 🔴 | pi does not provide host telemetry as OTLP |
 
 ## License
 

package/dist/channels/session.js

@@ -3,10 +3,9 @@
  *
  * 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.
- *
+ * 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
  */
@@ -23,7 +22,7 @@ export function initialSessionState(provider, title, workingDirectory) {
         chats: [],
     };
 }
-/** Bits 0–4 are mutually exclusive activity; later bits are session metadata. */
+/** The low five bits encode activity; higher bits carry independent metadata flags. */
 const STATUS_ACTIVITY_MASK = (1 << 5) - 1;
 function timestamp(summary) {
     const value = Date.parse(summary.modifiedAt);

package/dist/core/client-workarounds.js

@@ -2,8 +2,9 @@
  * Repairs to the traffic of clients whose reading of the protocol differs from
  * this host's. Each entry says what the client does and what would let it go.
  */
-import { ActionType } from "@microsoft/agent-host-protocol";
-import { chatIdFromUri, chatUri, sessionIdFromUri, sessionUri } from "./channels.js";
+import { ActionType, JsonRpcErrorCodes } from "@microsoft/agent-host-protocol";
+import { ProtocolError } from "../protocol/errors.js";
+import { chatIdFromUri, chatUri, ROOT_CHANNEL, sessionIdFromUri, sessionUri } from "./channels.js";
 /**
  * Field names that carry session or chat URIs in state, actions, and catalogue
  * notifications. The rewrite itself ignores every other URI scheme.
@@ -13,11 +14,16 @@ const REWRITABLE_FIELDS = new Set(["channel", "resource", "defaultChat", "sessio
 const DERIVED_CHAT_URI = /^ahp-chat:\/\/[^/]+\/([^/?#]+)$/;
 /** The client names VS Code identifies itself with at `initialize`. */
 const VSCODE_CLIENT_NAMES = new Set(["vscode-editor-window", "vscode-agents-window"]);
+const VSCODE_MATERIALIZED_SESSION_DISPOSAL_REFUSAL = "Materialized session disposal is temporarily disabled for VS Code because of a VS Code provisional-session lifecycle bug; this session was kept.";
+/** Actions after which a session is no longer an abandoned empty draft. */
+const MATERIALIZING_ACTIONS = new Set([
+    ActionType.ChatTurnStarted,
+    ActionType.ChatPendingMessageSet,
+    ActionType.SessionTitleChanged,
+]);
 /**
- * The scheme VS Code will address sessions under, being this host's agent
- * provider name. Hard-coded rather than threaded down from the pi layer:
- * everything about this file is temporary, and a parameter for it would outlive
- * the reason for it in three signatures.
+ * The provider scheme affected by this compatibility layer. Keep it local so
+ * client-specific routing does not leak into canonical host APIs.
  */
 const PROVIDER_SESSION_SCHEME = "pi";
 /** Methods where a direct `pi:/...` target can only mean a session. */
@@ -35,62 +41,157 @@ function providerSessionId(uri) {
 function isProviderSession(uri) {
     return uri.toLowerCase().startsWith(`${PROVIDER_SESSION_SCHEME}:/`) && providerSessionId(uri) !== undefined;
 }
+function canonicalSessionUri(uri) {
+    const sessionId = providerSessionId(uri);
+    return sessionId ? sessionUri(sessionId) : undefined;
+}
+function owningSessionUri(uri) {
+    const session = canonicalSessionUri(uri);
+    if (session)
+        return session;
+    const chatId = chatIdFromUri(uri);
+    return chatId ? sessionUri(chatId) : undefined;
+}
 function typeOfAction(value) {
     return typeof value === "object" && value !== null && "type" in value && typeof value.type === "string"
         ? value.type
         : undefined;
 }
+function hasVscodeClientMeta(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        ("vscode.telemetryLevel" in value || "vscode.clientConnectionKind" in value));
+}
 /**
- * VS Code addresses sessions and chats at URIs it computes, not the ones it was
- * given.
+ * Allows VS Code to clean up only sessions known to be unused drafts on this
+ * connection. Unknown sessions are protected: reconnect does not carry enough
+ * history to prove that they are empty.
  *
- * Three assumptions drive it, none of them in the protocol:
- *
- *  - A session lives at `<agentProvider>:/<id>`. `agentHostSessionHandler`
- *    rebuilds the URI that way from the provider name rather than using the
- *    `resource` the host published. It has a `sessionSchemeAlias` config for
- *    exactly this mismatch — "sessions are `ahp-session:/<id>` while the agent
- *    is `copilot`" — but only its cloud sandbox provider sets it.
- *  - A session's default chat lives at `ahp-chat://default/<base64url(session)>`,
- *    derived so producer and consumer "can compute it without a lookup table".
- *    `SessionState.defaultChat` and the session's chat list are both ignored.
- *  - `completions` targets the backend session URI even though its `channel`
- *    is specified as a chat URI. VS Code's host accepts either and silently
- *    chooses the default chat; this host keeps that tolerance per connection.
- *
- * So nothing this host sends is addressable by it, and every subscription
- * misses: sessions list, and opening one shows an empty transcript. Publishing
- * its shapes instead would push a base64 blob and a provider-specific scheme
- * onto every other client, so the translation is per connection and only for
- * the clients that need it.
+ * Remove this tracker when VS Code graduates materialized remote sessions
+ * before tearing down its provisional-session service.
+ */
+class VscodeSessionDisposalGuard {
+    #sessions = new Map();
+    #pendingRequests = new Map();
+    applyToIncoming(message, params) {
+        const channel = typeof params.channel === "string" ? params.channel : undefined;
+        const actionType = typeOfAction(params.action);
+        if (channel && actionType && MATERIALIZING_ACTIONS.has(actionType)) {
+            this.#markMaterialized(channel);
+        }
+        if (!("id" in message) || !channel) {
+            return;
+        }
+        const session = canonicalSessionUri(channel);
+        if (!session) {
+            return;
+        }
+        if (message.method === "createSession") {
+            this.#sessions.set(session, params.importConversation === undefined ? "creating" : "materialized");
+            this.#pendingRequests.set(message.id, { kind: "create", session });
+            return;
+        }
+        if (message.method !== "disposeSession") {
+            return;
+        }
+        if (this.#sessions.get(session) !== "empty") {
+            throw new ProtocolError(JsonRpcErrorCodes.InvalidRequest, VSCODE_MATERIALIZED_SESSION_DISPOSAL_REFUSAL);
+        }
+        this.#sessions.set(session, "disposing");
+        this.#pendingRequests.set(message.id, { kind: "dispose", session });
+    }
+    applyToOutgoing(message) {
+        if (!("method" in message)) {
+            this.#applyResponse(message);
+            return;
+        }
+        const params = message.params;
+        if (!params) {
+            return;
+        }
+        const actionType = typeOfAction(params.action);
+        if (message.method === "action" &&
+            params.rejectionReason === undefined &&
+            actionType !== undefined &&
+            MATERIALIZING_ACTIONS.has(actionType) &&
+            typeof params.channel === "string") {
+            this.#markMaterialized(params.channel);
+        }
+        if (message.method === "root/sessionRemoved" && typeof params.session === "string") {
+            const session = canonicalSessionUri(params.session);
+            if (session)
+                this.#sessions.delete(session);
+        }
+    }
+    #applyResponse(message) {
+        const pending = this.#pendingRequests.get(message.id);
+        if (!pending) {
+            return;
+        }
+        this.#pendingRequests.delete(message.id);
+        const state = this.#sessions.get(pending.session);
+        if (pending.kind === "create") {
+            if ("result" in message) {
+                if (state === "creating")
+                    this.#sessions.set(pending.session, "empty");
+            }
+            else {
+                this.#sessions.delete(pending.session);
+            }
+            return;
+        }
+        if ("result" in message) {
+            this.#sessions.delete(pending.session);
+        }
+        else if (state === "disposing") {
+            this.#sessions.set(pending.session, "empty");
+        }
+    }
+    #markMaterialized(channel) {
+        const session = owningSessionUri(channel);
+        if (session && this.#sessions.has(session)) {
+            this.#sessions.set(session, "materialized");
+        }
+    }
+}
+/**
+ * VS Code computes provider-scoped session URIs and derived default-chat URIs
+ * instead of using the canonical resources published by the host. It also
+ * targets `completions` at the session URI rather than the chat URI. Publishing
+ * those shapes globally would impose one client's dialect on every client, so
+ * translation remains per connection and core services see canonical URIs.
  *
- * Normally VS Code is identified at `initialize`, before the session list and
- * snapshots go out. A raw `pi:/...` target separately identifies only the
- * provider-style session scheme, which covers the iOS client without forcing
- * VS Code's derived-chat format on it. Observing a derived chat enables that
- * second translation. After a host restart, reconnect subscriptions provide the
- * same fingerprints. Replies use each connection's dialect while core services
- * see canonical URIs.
+ * `initialize.clientInfo`, VS Code's namespaced request metadata, and derived
+ * chat URIs identify VS Code and gate its workarounds. Independently, a raw
+ * `pi:/...` target selects the provider-session URI dialect used by the iOS
+ * client. Both observations remain per connection; core services stay canonical.
  *
- * Goes when VS Code addresses what it was given.
+ * Remove each compatibility branch when its clients emit canonical AHP traffic.
  */
 export class ClientWorkarounds {
-    #dialect = "canonical";
-    /** Reads implementation identity without erasing a dialect inferred from URIs. */
+    #isVscode = false;
+    #usesProviderSessionUris = false;
+    #vscodeSessionDisposal = new VscodeSessionDisposalGuard();
+    /** Reads implementation identity without erasing observations from wire traffic. */
     identify(clientInfo) {
         if (VSCODE_CLIENT_NAMES.has(clientInfo?.name ?? ""))
-            this.#dialect = "vscode";
+            this.#isVscode = true;
     }
     /** Rewrites this connection's parsed request or notification in place. */
     applyToIncoming(message) {
         const params = message.params;
         if (!params)
             return;
-        this.#observeDialect(message.method, params);
-        const rewrite = (uri) => inbound(uri, this.#dialect);
+        this.#observeTraffic(message.method, params);
+        // Remove when VS Code includes the AHP 0.9 root-channel discriminant in reconnect.
+        if ("id" in message && this.#isVscode && message.method === "reconnect" && params.channel === undefined) {
+            params.channel = ROOT_CHANNEL;
+        }
+        const dialect = this.#uriDialect();
+        const rewrite = (uri) => inbound(uri, dialect);
         if (typeof params.channel === "string") {
             let channel = rewrite(params.channel);
-            if (message.method === "completions" && this.#dialect !== "canonical") {
+            if (message.method === "completions" && dialect !== "canonical") {
                 // Both VS Code and the iOS client currently target completions at the
                 // provider-style session URI.
                 const sessionId = providerSessionId(channel);
@@ -99,7 +200,7 @@ export class ClientWorkarounds {
             // VS Code addresses its session rename to the selected chat. AHP defines
             // `session/titleChanged` only on the owning session.
             if (message.method === "dispatchAction" &&
-                this.#dialect === "vscode" &&
+                this.#isVscode &&
                 typeOfAction(params.action) === ActionType.SessionTitleChanged) {
                 const chatId = chatIdFromUri(channel);
                 channel = chatId ? sessionUri(chatId) : channel;
@@ -114,34 +215,49 @@ export class ClientWorkarounds {
                 params[field] = subscriptions.map((uri) => (typeof uri === "string" ? rewrite(uri) : uri));
             }
         }
+        if (this.#isVscode) {
+            this.#vscodeSessionDisposal.applyToIncoming(message, params);
+        }
     }
-    /** Returns the message to send, rewritten if this client needs it. */
-    applyToMessage(message) {
-        const dialect = this.#dialect;
+    /** Returns the outgoing message, rewritten if this client needs it. */
+    applyToOutgoing(message) {
+        if (this.#isVscode) {
+            this.#vscodeSessionDisposal.applyToOutgoing(message);
+        }
+        const dialect = this.#uriDialect();
         return dialect === "canonical"
             ? message
             : rewriteFields(message, (uri) => outbound(uri, dialect));
     }
-    #observeDialect(method, params) {
+    #observeTraffic(method, params) {
         const direct = typeof params.channel === "string" ? params.channel : undefined;
         const listed = [
             ...(Array.isArray(params.initialSubscriptions) ? params.initialSubscriptions : []),
             ...(Array.isArray(params.subscriptions) ? params.subscriptions : []),
         ];
         const observed = direct ? [direct, ...listed] : listed;
-        if (observed.some((uri) => typeof uri === "string" && sessionFromDerivedChat(uri) !== undefined)) {
-            this.#dialect = "vscode";
-        }
-        else if (this.#dialect === "canonical" &&
+        this.#observeVscode(params, observed);
+        if (!this.#usesProviderSessionUris &&
             (PROVIDER_SESSION_METHODS.has(method) ? observed : listed).some((uri) => typeof uri === "string" && isProviderSession(uri))) {
-            this.#dialect = "provider";
+            this.#usesProviderSessionUris = true;
         }
     }
+    #observeVscode(params, observed) {
+        if (hasVscodeClientMeta(params._meta) ||
+            observed.some((uri) => typeof uri === "string" && sessionFromDerivedChat(uri) !== undefined)) {
+            this.#isVscode = true;
+        }
+    }
+    #uriDialect() {
+        if (this.#isVscode)
+            return "vscode";
+        return this.#usesProviderSessionUris ? "provider" : "canonical";
+    }
 }
 /**
  * Translates a URI this client computed into the one this host minted.
  *
- * A derived chat URI is unwrapped whoever sent it — it names no channel this
+ * A derived chat URI is unwrapped regardless of who sent it — it names no channel this
  * host could otherwise serve. A provider-aliased session URI is only rewritten
  * for a client identified as using that alias; unknown schemes are left alone.
  */

package/dist/core/connection.js

@@ -10,7 +10,7 @@ export class ClientConnection {
         this.transport = transport;
     }
     send(message) {
-        this.transport.send(this.workarounds.applyToMessage(message));
+        this.transport.send(this.workarounds.applyToOutgoing(message));
     }
     subscribe(channel) {
         this.subscriptions.add(channel);

package/dist/core/host.js

@@ -68,7 +68,6 @@ function validateInitialize(params) {
     if (params.capabilities !== undefined && !isRecord(params.capabilities)) {
         throw ProtocolError.invalidParams("capabilities must be an object");
     }
-    return negotiateProtocolVersion(params.protocolVersions);
 }
 function validateReconnect(params) {
     if (typeof params?.clientId !== "string" || params.clientId.length === 0) {
@@ -100,6 +99,21 @@ export class AhpHost {
     get store() {
         return this.#store;
     }
+    /** Removes a channel and releases every connection subscribed to that identity. */
+    deleteChannel(channel) {
+        const deleted = this.#store.delete(channel);
+        let released = false;
+        for (const connection of this.#connections) {
+            if (connection.isSubscribed(channel)) {
+                connection.unsubscribe(channel);
+                released = true;
+            }
+        }
+        if (released) {
+            this.#notifySubscriberCount(channel);
+        }
+        return deleted;
+    }
     get serverSeq() {
         return this.#sequencer.current;
     }
@@ -156,9 +170,6 @@ export class AhpHost {
         }
     }
     async #dispatchRequest(connection, request) {
-        if (ROOT_COMMANDS.has(request.method) && readChannel(request.params) !== ROOT_CHANNEL) {
-            throw ProtocolError.invalidParams(`${request.method} requires channel ${ROOT_CHANNEL}`);
-        }
         const handshake = request.method === "initialize" || request.method === "reconnect";
         if (handshake && connection.clientId) {
             throw new ProtocolError(JsonRpcErrorCodes.InvalidRequest, "Connection is already initialized");
@@ -169,8 +180,9 @@ export class AhpHost {
         let protocolVersion = "";
         if (request.method === "initialize") {
             const params = request.params;
-            protocolVersion = validateInitialize(params);
-            connection.workarounds.identify(params?.clientInfo);
+            validateInitialize(params);
+            protocolVersion = negotiateProtocolVersion(params.protocolVersions);
+            connection.workarounds.identify(params.clientInfo ?? this.#clientInfoById.get(params.clientId));
         }
         else if (request.method === "reconnect") {
             const params = request.params;
@@ -178,6 +190,9 @@ export class AhpHost {
             connection.workarounds.identify(this.#clientInfoById.get(params.clientId));
         }
         connection.workarounds.applyToIncoming(request);
+        if (ROOT_COMMANDS.has(request.method) && readChannel(request.params) !== ROOT_CHANNEL) {
+            throw ProtocolError.invalidParams(`${request.method} requires channel ${ROOT_CHANNEL}`);
+        }
         switch (request.method) {
             // `ping` must be answered whether or not the client has completed
             // `initialize` or holds any subscription.
@@ -346,7 +361,6 @@ export class AhpHost {
         this.#bindClient(connection, params.clientId);
         const identifiedClient = params.clientInfo ?? this.#clientInfoById.get(params.clientId);
         this.#clientInfoById.set(params.clientId, identifiedClient);
-        connection.workarounds.identify(identifiedClient);
         const snapshots = [];
         for (const uri of params.initialSubscriptions ?? []) {
             if (!this.#store.has(uri)) {

package/dist/core/sequencer.js

@@ -9,9 +9,8 @@
  * @see https://microsoft.github.io/agent-host-protocol/specification/lifecycle
  */
 /**
- * How many envelopes to retain for replay. Matches the reference host's
- * `REPLAY_BUFFER_CAPACITY`. A client whose gap predates the buffer gets fresh
- * snapshots instead — correct, just more expensive.
+ * Local memory bound for replay. A client whose gap predates the buffer gets
+ * fresh snapshots instead, preserving correctness at the cost of more data.
  */
 const DEFAULT_REPLAY_BUFFER_CAPACITY = 1000;
 export class Sequencer {

package/dist/core/uri.js

@@ -1,13 +1,7 @@
 /**
- * URI helpers shared across channels and backends.
- *
- * The protocol carries filesystem locations as `file:` URIs. Converting them
- * lives here rather than in whichever module happened to need it first, because
- * having two conversions is how they drift: a hand-rolled
- * `decodeURIComponent(new URL(uri).pathname)` silently turns the UNC URI
- * `file://host/share/x` into the local path `/share/x`, while `node:url`
- * rejects it — so the same input was accepted in one command and refused in
- * another.
+ * URI helpers shared across channels and backends. Filesystem conversion uses
+ * `node:url` consistently so platform and remote-authority semantics cannot
+ * diverge between commands.
  */
 import { fileURLToPath, pathToFileURL } from "node:url";
 /**

package/dist/host/pi-host.js

@@ -9,7 +9,7 @@ import { AhpHost } from "../core/host.js";
 import { CompletionService, MENTION_TRIGGER } from "../pi/completions.js";
 import { deleteSessionFile } from "../pi/delete-session.js";
 import { InProcessPiBackend } from "../pi/in-process-backend.js";
-import { buildAgentInfo, THINKING_CONFIG_KEY } from "../pi/models.js";
+import { buildAgentInfo, modelSelectionId, THINKING_CONFIG_KEY } from "../pi/models.js";
 import { resolveProjectTrust } from "../pi/project-trust.js";
 import { ResourcePathPolicy } from "../pi/resource-paths.js";
 import { ResourceService } from "../pi/resource-service.js";
@@ -20,12 +20,9 @@ import { SessionHydrator } from "../pi/session-hydrator.js";
 import { SessionRegistry } from "../pi/session-registry.js";
 import { TerminalService } from "./terminal-service.js";
 /**
- * Builds the host and registers every channel a client can reach at this
- * milestone.
- *
- * The model list is read once at startup. Refreshing it later means dispatching
- * `root/agentsChanged`, which is what makes the agent list a state channel
- * rather than a one-shot handshake field.
+ * Builds the host and registers every supported channel. The model list is a
+ * startup snapshot; dynamic refresh would require publishing
+ * `root/agentsChanged` and is not implemented.
  */
 export async function createPiHost(options = {}) {
     const workingDirectory = options.workingDirectory ?? process.cwd();
@@ -65,7 +62,9 @@ export async function createPiHost(options = {}) {
     const fallbackThinking = fallback
         ? clampThinkingLevel(fallback, configured ? (settingsManager?.getDefaultThinkingLevel() ?? "medium") : "medium")
         : undefined;
-    const fallbackSelection = () => fallback && fallbackThinking ? { id: fallback.id, config: { [THINKING_CONFIG_KEY]: fallbackThinking } } : undefined;
+    const fallbackSelection = () => fallback && fallbackThinking
+        ? { id: modelSelectionId(fallback), config: { [THINKING_CONFIG_KEY]: fallbackThinking } }
+        : undefined;
     const catalogue = new PiSessionCatalogue();
     const resourcePaths = new ResourcePathPolicy(options.resourceRoots);
     const resources = new ResourceService({ pathPolicy: resourcePaths });
@@ -88,7 +87,7 @@ export async function createPiHost(options = {}) {
         defaultWorkingDirectory: workingDirectory,
         createBackend,
         defaultSelection: fallbackSelection,
-        deleteFile: options.deleteFile ?? ((path) => void deleteSessionFile(path)),
+        deleteFile: options.deleteFile ?? deleteSessionFile,
         findSessionFile: (id) => catalogue.findSessionFile(id),
         ...(options.log ? { log: options.log } : {}),
     });
@@ -116,8 +115,8 @@ export async function createPiHost(options = {}) {
         },
         sessions: {
             create(params) {
-                // The registry's narrower structural type documents the optional fields
-                // this milestone ignores: config, activeClient, and progressToken.
+                // The registry's narrower structural type makes the unsupported optional
+                // fields explicit: config, activeClient, and progressToken are ignored.
                 sessions.create(params);
             },
             dispose(channel) {
@@ -131,6 +130,7 @@ export async function createPiHost(options = {}) {
             host,
             catalogue,
             isLive: (session) => sessions.has(session),
+            isDisposing: (session) => sessions.isDisposing(session),
             // Adopted without a backend; one starts on the first turn.
             adopt: (session) => void sessions.adopt(session),
             fallbackSelection,

package/dist/host/terminal-service.js

@@ -31,7 +31,12 @@ function defaultShell() {
         return process.env.SHELL || "sh";
     }
 }
-/** Bridges terminal channel actions to independent pseudoterminal processes. */
+/**
+ * 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 {
     #host;
     #options;

package/dist/pi/activity.js

@@ -131,7 +131,6 @@ function searchInput(input) {
     }
     return parts.join(" ");
 }
-/** What to show between tool calls, while the model is producing output. */
 /**
  * The same description, phrased for a call that has finished.
  *