@softov/ahpc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luiz Fernando Softov <lfs@softov.dev>
+
+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

@@ -0,0 +1,296 @@
+# ahpc
+
+[![npm](https://img.shields.io/npm/v/%40softov%2Fahpc)](https://www.npmjs.com/package/@softov/ahpc)
+![license MIT](https://img.shields.io/badge/license-MIT-blue)
+![node >=22](https://img.shields.io/badge/node-%3E%3D22-5fa04e)
+![Agent Host Protocol 0.9.0](https://img.shields.io/badge/AHP-0.9.0-0b7285)
+![built with TextUI](https://img.shields.io/badge/built%20with-TextUI-7048e8)
+
+A terminal client for the [Agent Host Protocol](https://microsoft.github.io/agent-host-protocol/).
+It can be used as cli (commands) or tui (interactive chat).
+
+Connect to an AHP host, manage sessions, and work with agents directly from your terminal.
+
+> [!NOTE]
+> `ahpc` is a client. It does not run agents or models itself.
+> You need an AHP-compatible host to connect to.
+
+The interface is built with [TextUI](https://github.com/softov/textui), a component toolkit for terminal applications.
+
+## Quick start
+
+```sh
+npm install -g @softov/ahpc
+```
+
+Or run it without installing, with `npx @softov/ahpc`.
+
+The package is scoped; the command it installs is `ahpc`.
+
+A scripted host is built in, so the screen runs with nothing else to set up:
+
+```sh
+ahpc
+```
+
+Point it at a real host:
+
+```sh
+ahpc --host ws://127.0.0.1:9187
+ahpc session list --host ws://127.0.0.1:9187
+```
+
+[`ahpd`](https://github.com/softov/ahpd) and VS Code's agent host are both AHP hosts.
+
+## What it does
+
+| | |
+|---|---|
+| Sessions | List, create, configure, archive and delete sessions on a host. |
+| Turns | Send a prompt, stream the reply, queue follow-ups, cancel. |
+| Answering | Approve or deny tool calls, and answer questions the agent asks mid-turn. |
+| Chats | Multiple conversations in one session. |
+| Changes and files | Files a session changed, their diffs, and the host's filesystem. |
+| Terminals | Shells running on the host, and their output. |
+| Automations | Scheduled and triggered runs, with their history. |
+| Customizations | Skills, prompts, agents and MCP servers, and which are enabled. |
+| Telemetry | Stream the host's log. |
+
+## Interactive
+
+`ahpc` with no command opens the screen.
+
+![The session list, with status and workspace for each](docs/img/sessions.svg)
+
+The list shows every session on the host: its status, the agent, the workspace and branch, and what it is doing right now. Sessions waiting on you are counted at the top. `ctrl+f` filters by title, agent or workspace, and `x` shows the archived ones with a count of how many that is.
+
+![A session, its transcript and the facts about it](docs/img/transcript.svg)
+
+Inside a session, the header shows the model, thinking level, permission mode, workspace and branch. All of it comes from the host, not from local guesses.
+
+`ctrl+f` opens a find box in the top right. Type and the term is coloured wherever it appears; `enter` and `down` go to the next one, `up` to the one before, and both wrap. The box says which match you are on and how many there are.
+
+![Starting a session, and the questions the host asks first](docs/img/compose.svg)
+
+Before the first message, a new session asks the agent, the model and its options, the permission mode and the workspace. The questions come from the host's `configSchema`, so options `ahpc` has never seen still get a row.
+
+### Keys
+
+| Key | |
+|---|---|
+| `enter` | Send |
+| `alt+enter` | Newline |
+| `tab` | Move to the options row |
+| `esc` | Close the menu, then leave the field, then go back |
+| `/` | Slash commands, from the host and from `ahpc` — `/config` opens the settings palette |
+| `@` | Complete a file path on the host |
+| `ctrl+g` | Edit the message in `$VISUAL` or `$EDITOR` |
+| `ctrl+p` | Command palette |
+| `f1` | Every key that works where you are |
+| `ctrl+f` | Filter the session list, or find in the open conversation |
+| `ctrl+n` | New session |
+| `ctrl+r` | Refresh |
+| `alt+t` | Theme |
+| `alt+m` | Markdown on or off |
+| `ctrl+c` | Cancel the running turn, or quit |
+
+Editing in the composer follows readline:
+
+| Key | |
+|---|---|
+| `ctrl+a` / `ctrl+e` | Start or end of the line |
+| `ctrl+k` / `ctrl+u` | Delete to the end, or to the start |
+| `ctrl+w`, `alt+backspace` | Delete the word before the caret |
+| `alt+d` | Delete the word after it |
+| `ctrl+z` / `alt+z` | Undo, redo |
+| `ctrl+←` / `ctrl+→` | Move a word at a time |
+
+Undo groups a run of typing into one step, so it takes back a word rather than a character.
+
+When a tool call is waiting: `a` approves, `d` denies, `1`-`9` pick an offered option. When the agent asks a question: `tab` moves between fields, `space` selects, `enter` sends.
+
+## Commands
+
+`ahpc <command>` runs without the screen. Output is formatted for reading; `--json` gives the same data for scripts.
+
+### Sessions
+
+| Command | | |
+|---|---|---|
+| `session list` | List sessions, newest first | `--archived` `--json` |
+| `session show <uri>` | Session details | `--full` `--json` |
+| `session new` | Create a new session | `--agent` `--cwd` `--set k=v` `--json` |
+| `session rm <uri>` | Delete a session | |
+| `session read <uri>` | Mark as read | `--unread` |
+| `session archive <uri>` | Archive a session | `--undo` |
+| `session history <uri>` | Show turns history | `--all` `--full` `--json` |
+| `session config <uri>` | Show the config schema and current values | `--json` |
+| `session set <uri> <k> <v>` | Change one config property | |
+| `session customizations <uri>` | List skills, prompts, agents and MCP servers | `--json` |
+| `session toggle <uri> <id>` | Toggle customization on/off | `--off` |
+| `session export <uri>` | Export the session as one document | `--json` `--markdown` |
+
+### Turns
+
+| Command | | |
+|---|---|---|
+| `prompt <uri> <text>` | Send a prompt and stream the reply | `--model` `--json` |
+| `exec <text>` | Run one prompt in a throwaway session | `--agent` `--cwd` `--model` `--json` |
+| `cancel <uri>` | Cancel the running turn | |
+| `queue <uri> <text>` | Queue a prompt behind the running turn | `--model` |
+| `unqueue <uri> <id>` | Remove a queued prompt | |
+
+### Answering
+
+| Command | | |
+|---|---|---|
+| `watch <uri>` | Block until the agent needs input, print it, exit | `--until turn\|input\|idle` `--timeout` `--json` |
+| `confirm <uri> <toolCallId>` | Approve a tool call | `--deny` `--option` |
+| `answer <uri> <requestId>` | Answer a question | `--field k=v` `--reject` |
+
+### Chats
+
+| Command | | |
+|---|---|---|
+| `chat list <uri>` | List the chats in a session | `--json` |
+| `chat new <uri> [text]` | Start another chat | |
+| `chat rm <chatUri>` | Close a chat | |
+
+### The host
+
+| Command | | |
+|---|---|---|
+| `agents` | List the agents the host serves, with their models | `--json` |
+| `models` | List every model, grouped by agent | `--json` |
+| `commands` | List the slash commands the host offers | `--json` |
+| `customizations` | List skills, prompts, agents and MCP servers | `--kind` `--json` |
+| `completions <uri> <text>` | Show what the host would complete | `--offset` `--json` |
+| `logs` | Stream the host's log | `--level` `--follow` |
+| `auth` | List the resources this host protects | `--json` |
+| `auth <resource>` | Send a token for one | `--token` `--expires-in` |
+| `status` | Show the current connection | `--json` |
+
+### Changes and files
+
+| Command | | |
+|---|---|---|
+| `changes <uri>` | List the files a session changed | `--list` `--scope` `--reviewed` `--unreviewed` `--operations` `--run` `--json` |
+| `content <uri> <file>` | Print one changed file in full | |
+| `resource list <uri>` | List a directory on the host | `--json` |
+| `resource read <uri>` | Read a file on the host | |
+| `resource stat <uri>` | Show a file's type and size | `--json` |
+| `resource write <uri> [file]` | Write a file, from a path or stdin | `--create-only` `--force` |
+| `resource rm <uri>` | Delete a file or directory | `--recursive` |
+| `resource mkdir <uri>` | Create a directory | |
+| `resource mv <uri> <to>` | Move or rename | `--fail-if-exists` |
+| `resource cp <uri> <to>` | Copy | `--fail-if-exists` |
+
+Writes are guarded by the file's etag unless you pass `--force`, so two clients editing the same file cannot silently overwrite each other.
+
+### Terminals
+
+| Command | | |
+|---|---|---|
+| `terminal list` | List running terminals | `--json` |
+| `terminal new` | Open a shell | `--cwd` `--name` |
+| `terminal rm <uri>` | Close a terminal | |
+| `terminal send <uri> <text>` | Send input to a terminal | |
+| `terminal watch <uri>` | Follow a terminal's output | `--timeout` |
+
+### Automations
+
+| Command | | |
+|---|---|---|
+| `automation list` | List automations | `--json` |
+| `automation show <uri>` | Show one automation | `--json` |
+| `automation triggers` | List the triggers this host supports | `--json` |
+| `automation runs <uri>` | Show an automation's run history | `--json` |
+| `automation run <uri>` | Run it now | |
+| `automation enable <uri>` / `disable <uri>` | Enable or disable it | |
+| `automation rm <uri>` | Delete it | |
+
+### Anything else
+
+| Command | | |
+|---|---|---|
+| `dispatch <uri> <type>` | Send a raw protocol action | `--field k=v` `--chat` |
+| `config` | Show the config file path and current values | `--json` |
+| `help` | Print this command list | |
+
+## AHP support
+
+All 30 client-to-server requests are implemented, and 21 of the 45 client-dispatchable actions are used. `ahpc` subscribes to the root, session, chat, terminal and automation channels, plus the telemetry channel the host advertises for its log.
+
+AHP is symmetrical, so a host can also request things from the client. Nine of the ten server-initiated methods are implemented; `createResourceWatch` is not. Nothing is shared until `--publish <dir>` names a directory, and it stays read-only without `--publish-writable`:
+
+```sh
+ahpc --host ws://127.0.0.1:9187 --publish ~/notes
+```
+
+The host reads those files at `virtual://<clientId>/<path>`. Publishing lasts only while the screen is open.
+
+[docs/CONFORMANCE.md](docs/CONFORMANCE.md) covers the full surface: which actions are dispatched, four divergences and why, undeclared fields hosts send in practice, and three defects that belong to the protocol package rather than any implementation.
+
+## Configuration
+
+`$XDG_CONFIG_HOME/ahpc/config.json`, or `~/.config/ahpc/config.json`:
+
+```json
+{ "host": "ws://127.0.0.1:9187", "theme": "paper-light" }
+```
+
+Precedence: a flag overrides an environment variable, which overrides the file.
+
+| | |
+|---|---|
+| `--host`, `AHPC_HOST` | The host to connect to |
+| `--token`, `AHPC_TOKEN` | A bearer token for it |
+| `AHPC_TOKEN_<RESOURCE>` | A token for one protected resource |
+| `--config-file` | Read this file instead |
+
+`ahpc config` prints the file path and the values in force. It works without a host, which is what you need when the host is the problem.
+
+### Keys
+
+`keys` maps a chord to a command id, or to `null` to unbind it:
+
+```json
+{
+  "keys": {
+    "ctrl+g": "editor.open",
+    "ctrl+t": null,
+    "ctrl+y": "session.new"
+  }
+}
+```
+
+Naming a chord replaces every default on it, so a chord is either yours or the client's and never half of each. A chord bound to a name no command answers to is reported at startup rather than ignored. `ctrl+c`, `ctrl+d`, `ctrl+h`, `ctrl+i`, `ctrl+j`, `ctrl+m` and `ctrl+[` cannot be rebound usefully — a terminal sends them as interrupt, end-of-file, backspace, tab, newline, return and escape.
+
+## Development
+
+```sh
+git clone https://github.com/softov/ahpc
+cd ahpc
+npm install
+
+npm test
+npm run typecheck
+npm run build      # dist/src, which is what the package ships
+```
+
+Two tools check the client against the protocol itself:
+
+```sh
+npm run schema              # a strict JSON Schema from the package's own declarations
+npm run wire -- <capture>   # check a recording against it
+```
+
+`AHPC_RECORD=<file>` appends every frame sent and received. `test/conformance.test.ts` runs the same check against frames produced by the test run itself, so it cannot pass on a stale recording.
+
+The screens, widgets and input handling come from [TextUI](https://github.com/softov/textui) — `@textui/core` for components and state, `@textui/widgets` for the catalog, `@textui/terminal` for rendering and key decoding, and `@textui/testing` for the harness the tests run in. `ahpc` began as an example inside it.
+
+[docs/DESIGN.md](docs/DESIGN.md) covers why the client is built this way: how a terminal handles a transcript differently from a browser, and what the widget catalog was missing.
+
+## License
+
+MIT.

package/dist/src/ahp/channels.d.ts

@@ -0,0 +1,146 @@
+/** Who is holding which channel open, and what the host is saying on it. */
+/** One thing the host said on a channel: an action, or a protocol notification. */
+export interface ChannelEvent {
+    type: string;
+    params?: unknown;
+}
+/** A channel event with the channel it arrived on. */
+export interface AddressedEvent {
+    channel: string;
+    event: ChannelEvent;
+}
+/** State as the host holds it, before this client has read anything out of it. */
+export type ChannelState = Record<string, unknown> | null;
+/**
+ * One reader of one channel.
+ *
+ * `opened` arrives before any `event`, and arrives *again* after a reconnect
+ * that could not be closed by replay: a consumer rebuilds from the state it is
+ * handed rather than assuming the one it had is still the truth.
+ */
+export interface Consumer {
+    /** The channel's state, as of the moment this reader joined it. */
+    opened(state: ChannelState): void;
+    /** Everything the host sends on the channel, in the order it sent it. */
+    event(event: ChannelEvent): void;
+    /** The host would not serve the channel, in the words it used. */
+    refused?(message: string): void;
+}
+/** What this registry needs of a protocol client. */
+export interface ChannelClient {
+    subscribe(uri: string): Promise<{
+        result: {
+            snapshot?: {
+                state?: unknown;
+                fromSeq?: number;
+            } | null;
+        };
+    }>;
+    unsubscribe(uri: string): Promise<void>;
+    events(): AsyncIterableIterator<AddressedEvent>;
+}
+/** A reader's hold on a channel, given up by calling `release`. */
+export interface Hold {
+    release(): void;
+}
+/** A snapshot the host handed back for one channel during a reconnect. */
+export interface ResumedSnapshot {
+    resource: string;
+    state?: unknown;
+}
+export interface Channels {
+    /**
+     * Take a hold on a channel and start reading it.
+     *
+     * Synchronous, because every caller is a screen being drawn: the subscribe
+     * happens behind this and the consumer hears about it through `opened`. A
+     * hold released before the subscribe lands never subscribes at all.
+     */
+    open(uri: string, consumer: Consumer): Hold;
+    /**
+     * The channel's state now, without holding it open afterwards.
+     *
+     * A read rather than a watch: this subscribes, takes the state, and
+     * unsubscribes again unless somebody else is holding the channel. A host
+     * has no other way to answer "what is in there" - there is no `getState` -
+     * so the subscription is the question and letting go is the whole point.
+     */
+    state(uri: string): Promise<ChannelState>;
+    /** Every channel held right now, which is what `reconnect` has to be told. */
+    held(): string[];
+    /** The highest `serverSeq` this client has seen on any channel. */
+    seq(): number;
+    /**
+     * Read one channel's refusal, if it was refused.
+     *
+     * A refusal is an answer about what the host is - `-32001` for a session
+     * whose agent has gone - and asking again on every keystroke turns one
+     * refusal into a stream of them.
+     */
+    refusal(uri: string): string | undefined;
+    /**
+     * Let a refusal be asked again: one channel, or every one of them.
+     *
+     * What a host refuses can stop being refused - a session is created, an
+     * agent comes back - and the answer is only worth keeping until something
+     * happens that could have changed it.
+     */
+    forget(uri?: string): void;
+    /** Start reading a connection's event stream. Ends when the stream does. */
+    drain(client: ChannelClient): void;
+    /**
+     * Take up the same channels again on a new connection.
+     *
+     * `replayed` is the branch where the host could name everything missed:
+     * the envelopes go to their consumers in order and nobody is re-opened.
+     * `resumed` is the branch where it could not, and every consumer is handed
+     * a fresh state. `missing` is refused either way.
+     */
+    resume(client: ChannelClient, result: {
+        replayed?: readonly unknown[];
+        resumed?: readonly ResumedSnapshot[];
+        missing?: readonly string[];
+    }): void;
+    /**
+     * Take a channel the handshake already opened, with the state it answered.
+     *
+     * `initialize` accepts `initialSubscriptions` and answers with a snapshot
+     * for each, which leaves the channel subscribed at the host before anything
+     * here has asked for it. Without this the first reader would subscribe again
+     * - the round trip the handshake exists to save, and a second `subscribe`
+     * for a channel this connection already holds.
+     */
+    adopt(uri: string, state: ChannelState): void;
+    /** Forget every subscription without unsubscribing: the socket is already gone. */
+    detach(): void;
+}
+export interface ChannelsOptions {
+    client: ChannelClient;
+    /** Told when a channel is refused, so the reason reaches a person. */
+    onRefusal?(uri: string, message: string): void;
+    /** Told when the host refuses an action this client dispatched. */
+    onRejection?(uri: string, message: string): void;
+    /**
+     * This client's id, as `initialize` gave it.
+     *
+     * Only so that a refusal can be told from somebody else's: an envelope
+     * naming another client is still not applied, and is not reported here.
+     */
+    clientId?: string;
+    /** The host's own words for a failure, as a client would show them. */
+    reason(error: unknown): string;
+    /**
+     * How long to keep a channel nobody is reading, in milliseconds.
+     *
+     * Not laziness about letting go - a pause before it. Reading a snapshot and
+     * opening a view are two holds on the same channel a moment apart, and
+     * navigating away and back is two more, so releasing on the instant the
+     * count reaches zero puts an `unsubscribe` between every pair of them. A
+     * host is entitled to act on that: the reference one evicts a session from
+     * memory when its last subscriber leaves and restores it from disk on the
+     * next subscribe, and a client that unsubscribes and immediately subscribes
+     * again is racing that restore. `0` releases at once.
+     */
+    lingerMs?: number;
+}
+export declare function openChannels(options: ChannelsOptions): Channels;