@softov/ahpc 0.1.0 → 0.3.0

package/dist/src/tui.d.ts

@@ -79,7 +79,7 @@ interface Options {
     publishWritable?: boolean;
     help: boolean;
 }
-export declare const USAGE = "ahpc - a terminal client for the Agent Host Protocol\n\n  ahpc [options]\n\nThe host\n  --host <url>          A live agent host, ws://host:port\n  --token <tkn>         A bearer token for it\n  --config-file <f>     Read this instead of ~/.config/ahpc/config.json\n  (none of these)       The scripted host, which needs nothing installed\n\nWhere the agent works\n  --path <dir>          A path on the host, not on this machine. The host\n                        has to serve it, and says so if it does not.\n                        Left out, the host decides.\n\nWhat this client serves back\n  --publish <dir>       Serve this directory to the host under\n                        virtual://<clientId>/. Nothing is served without\n                        it, and every such request is refused.\n  --publish-writable    Let the host write into it. Read-only otherwise.\n                        Serving lasts as long as the screen does: with no\n                        terminal attached this prints one frame and exits,\n                        so a background shell publishes nothing.\n\nAppearance\n  --theme <name>        workbench, paper-light, ...\n  --shell <name>        The shell layout\n  --screen <name>       Which screen to open on\n  --bood                Let the creature loose on the whole screen. It\n                        keeps off the composer and off anything asking\n                        a question, and alt+g turns it off again.\n  --session <uri>       Open this session\n\nStills, for a README or a test\n  --static, -s          One frame to stdout instead of running\n  --width, -w <n>       Columns\n  --height <n>          Rows\n  --unicode <level>     ascii, bmp, full\n  --colors <n>          0, 4, 8 or 24\n  --svg <file>          Write the still as SVG here\n  --tick <ms>           Milliseconds per scripted word\n  --settled             Run the script out before the frame\n  --pump <n>            Or exactly this many scripted words\n  --say <text>          Say this on the open session first\n  --approve             Answer the confirmation the script stops at\n  --answer              ...and then the question\n\n  --help, -h            This\n\nCommands\n  ahpc <command> ...    Drive a host without the screen. 'ahpc help' lists\n                        them: sessions, prompts, approvals, terminals.\n";
+export declare const USAGE = "ahpc - a terminal client for the Agent Host Protocol\n\n  ahpc [options]\n\nThe host\n  --host <url>          A live agent host, ws://host:port\n  --token <tkn>         A bearer token for it\n  --config-file <f>     Read this instead of ~/.config/ahpc/config.json\n  (none of these)       The scripted host, which needs nothing installed\n\nWhere the agent works\n  --path <dir>          A path on the host, not on this machine. The host\n                        has to serve it, and says so if it does not.\n                        Left out, the host decides.\n\nWhat this client serves back\n  --publish <dir>       Serve this directory to the host under\n                        virtual://<clientId>/. Nothing is served without\n                        it, and every such request is refused.\n  --publish-writable    Let the host write into it. Read-only otherwise.\n                        Serving lasts as long as the screen does: with no\n                        terminal attached this prints one frame and exits,\n                        so a background shell publishes nothing.\n\nAppearance\n  --theme <name>        workbench, paper-light, ...\n  --shell <name>        The shell layout\n  --screen <name>       Which screen to open on\n  --bood                Let the creature loose on the whole screen. It\n                        keeps off the composer and off anything asking\n                        a question, and alt+g turns it off again.\n  --session <uri>       Open this session\n\nStills, for a README or a test\n  --static, -s          One frame to stdout instead of running\n  --width, -w <n>       Columns\n  --height <n>          Rows\n  --unicode <level>     ascii, bmp, full\n  --colors <n>          0, 4, 8 or 24\n  --svg <file>          Write the still as SVG here\n  --tick <ms>           Milliseconds per scripted word\n  --settled             Run the script out before the frame\n  --pump <n>            Or exactly this many scripted words\n  --say <text>          Say this on the open session first\n  --approve             Answer the confirmation the script stops at\n  --answer              ...and then the question\n\n  --version, -v         What version this is\n  --help, -h            This\n\nCommands\n  ahpc <command> ...    Drive a host without the screen. 'ahpc help' lists\n                        them: sessions, prompts, approvals, terminals.\n";
 export declare function parse(argv: string[]): Options;
 /**
  * The screen.

package/dist/src/tui.js

@@ -53,6 +53,7 @@ Stills, for a README or a test
   --approve             Answer the confirmation the script stops at
   --answer              ...and then the question
 
+  --version, -v         What version this is
   --help, -h            This
 
 Commands

package/dist/src/version.d.ts

@@ -0,0 +1,2 @@
+/** The version in the nearest `package.json`, or `unknown` where there is none. */
+export declare const version: () => string;

package/dist/src/version.js

@@ -0,0 +1,38 @@
+/*
+ * What version this is, read from the manifest rather than written twice.
+ *
+ * A literal in the source is a literal that drifts: the one in `mcp/serve.ts`
+ * said 0.1 while the package said 0.2 within a day of being written, and a
+ * `--version` that lies is worse than no `--version` at all.
+ *
+ * Found by walking up from this module rather than by a fixed relative path,
+ * because the depth differs: `src/version.ts` in a checkout and
+ * `dist/src/version.js` in an install, and neither should have to know which
+ * it is. `package.json` is always at the package root and npm always ships
+ * it, so the first one above this file is the right one.
+ *
+ * This file imports nothing but Node, on purpose. The entry point answers
+ * `--version` before it decides which front end to load, and loading one to
+ * answer it would make the fastest question the slowest.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** The version in the nearest `package.json`, or `unknown` where there is none. */
+export const version = () => {
+    let at = dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        try {
+            const found = JSON.parse(readFileSync(join(at, 'package.json'), 'utf8'));
+            if (typeof found.version === 'string')
+                return found.version;
+        }
+        catch { /* not this directory */ }
+        const up = dirname(at);
+        // The root of the filesystem, which means there is no manifest anywhere
+        // above this file - a bundler inlined it, or something unpacked it wrong.
+        if (up === at)
+            return 'unknown';
+        at = up;
+    }
+};

package/dist/src/wait.d.ts

@@ -0,0 +1,56 @@
+import type { HostConnection, HostEvent } from './ahp/connection.js';
+import type { ModelSelection, SessionUri, Turn } from './ahp/types.js';
+/**
+ * Watch one session until it does something, then stop watching.
+ *
+ * Every streaming command is this with a different stopping condition. The
+ * subscription is always closed - a caller that left one open would be a
+ * process that never exits, which is the one thing a shell cannot work around.
+ */
+export declare function until(host: HostConnection, uri: SessionUri, done: (event: HostEvent) => boolean, options?: {
+    onEvent?(event: HostEvent): void;
+    timeoutSeconds?: number;
+}): Promise<HostEvent | undefined>;
+/** A turn, as a line of prose rather than a tree of parts. */
+export declare const spoken: (turn: Turn) => string;
+/** What a caller wants told while a turn is running, and how long to wait. */
+export interface TurnOptions {
+    model?: ModelSelection;
+    timeoutSeconds?: number;
+    /** Text the agent has said that the caller has not been given yet. */
+    onDelta?(text: string): void;
+    /** A tool call the agent is blocked on, said once per call. */
+    onWaiting?(call: {
+        id: string;
+        name: string;
+    }): void;
+    /**
+     * A tool the agent has started using, said once per call.
+     *
+     * Every tool call rather than only the ones that stop for a person, because
+     * this is what a caller watching a long turn has to go on: `onWaiting` fires
+     * on an approval and most turns never ask for one.
+     */
+    onStep?(call: {
+        id: string;
+        name: string;
+    }): void;
+}
+/**
+ * Say something, and block until the turn it starts has finished.
+ *
+ * Subscribed before saying anything: the first snapshot is the baseline that
+ * says which turns were already there, and one taken afterwards would count
+ * the new turn among them.
+ *
+ * "Finished" is a turn of *ours* having ended - one that was not in the
+ * baseline - rather than the last in the list, which is a different session's
+ * answer when two people are talking in the same chat. A turn that stops to
+ * ask a person something is not finished and is not this caller's to answer,
+ * so the wait runs on until whoever is answering has.
+ *
+ * Answers `undefined` where the timeout ran out, which is a caller's to
+ * report rather than to throw: the turn is still going and the session is
+ * still there.
+ */
+export declare function turn(host: HostConnection, uri: SessionUri, text: string, options?: TurnOptions): Promise<Turn | undefined>;

package/dist/src/wait.js

@@ -0,0 +1,160 @@
+/*
+ * Watching one session until it does something, for whoever is asking.
+ *
+ * The CLI and the tool server both say a thing and then block until the turn
+ * it started has finished, and both need the same answer to "finished" - which
+ * is not "the last turn in the list" and not "nothing is running". Written
+ * once here, because the two disagreeing would mean a tool that returned
+ * before the reply was complete while the same command in a shell waited.
+ */
+/**
+ * Watch one session until it does something, then stop watching.
+ *
+ * Every streaming command is this with a different stopping condition. The
+ * subscription is always closed - a caller that left one open would be a
+ * process that never exits, which is the one thing a shell cannot work around.
+ */
+export function until(host, uri, done, options = {}) {
+    return new Promise((answer) => {
+        let closed = false;
+        /*
+         * The handle may not exist yet when this runs.
+         *
+         * A host is entitled to deliver the opening snapshot *synchronously*
+         * inside `subscribe` - the scripted one does, and it is the honest thing
+         * for a host holding the state already - so a condition satisfied by that
+         * first event fires before `subscribe` has returned anything to close.
+         * Reading the handle there threw, which made every waiting command fail
+         * against the scripted host and work against a socket, purely because one
+         * of them answers a tick later.
+         */
+        let handle;
+        const finish = (event) => {
+            if (closed)
+                return;
+            closed = true;
+            clearTimeout(timer);
+            handle?.close();
+            answer(event);
+        };
+        const timer = setTimeout(() => finish(undefined), Math.max(1, (options.timeoutSeconds ?? 900)) * 1000);
+        timer.unref?.();
+        handle = host.subscribe(uri, (event) => {
+            options.onEvent?.(event);
+            if (done(event))
+                finish(event);
+        });
+        // Already over, before there was a handle to close. Closing it now is what
+        // `finish` could not do.
+        if (closed)
+            handle.close();
+    });
+}
+/** A turn, as a line of prose rather than a tree of parts. */
+export const spoken = (turn) => turn.parts
+    .map((part) => (part.kind === 'markdown' ? part.content : ''))
+    .join('')
+    .trim();
+/**
+ * Say something, and block until the turn it starts has finished.
+ *
+ * Subscribed before saying anything: the first snapshot is the baseline that
+ * says which turns were already there, and one taken afterwards would count
+ * the new turn among them.
+ *
+ * "Finished" is a turn of *ours* having ended - one that was not in the
+ * baseline - rather than the last in the list, which is a different session's
+ * answer when two people are talking in the same chat. A turn that stops to
+ * ask a person something is not finished and is not this caller's to answer,
+ * so the wait runs on until whoever is answering has.
+ *
+ * Answers `undefined` where the timeout ran out, which is a caller's to
+ * report rather than to throw: the turn is still going and the session is
+ * still there.
+ */
+export async function turn(host, uri, text, options = {}) {
+    let given = 0;
+    let sawActive = false;
+    let before = new Set();
+    let first = true;
+    let noted;
+    let answer;
+    /** Tool calls already reported, so a snapshot rebuilt per token says each once. */
+    const stepped = new Set();
+    const step = (call) => {
+        if (stepped.has(call.id))
+            return;
+        stepped.add(call.id);
+        options.onStep?.(call);
+    };
+    const finished = until(host, uri, (event) => {
+        /*
+         * Two vocabularies, because a host may speak either.
+         *
+         * `live.ts` rebuilds the whole view and sends a `snapshot` after every
+         * action; `fake.ts` sends what changed - `turnStarted`, `delta`,
+         * `turnComplete`. Both are `HostEvent` and both are legal, and a caller
+         * that read only snapshots waited for ever on the scripted host, which
+         * this client offers as the one that needs nothing installed.
+         */
+        if (event.type === 'turnStarted') {
+            sawActive = true;
+            return false;
+        }
+        if (event.type === 'delta') {
+            if (event.kind === 'markdown')
+                options.onDelta?.(event.text);
+            return false;
+        }
+        if (event.type === 'toolCall') {
+            step({ id: event.call.id, name: event.call.name });
+            if (event.call.status === 'pending-confirmation' && noted !== event.call.id) {
+                noted = event.call.id;
+                options.onWaiting?.({ id: event.call.id, name: event.call.name });
+            }
+            return false;
+        }
+        if (event.type === 'turnComplete') {
+            if (before.has(event.turn.id))
+                return false;
+            answer = event.turn;
+            return true;
+        }
+        if (event.type !== 'snapshot')
+            return false;
+        if (first) {
+            first = false;
+            before = new Set(event.turns.map((one) => one.id));
+        }
+        if (event.active) {
+            sawActive = true;
+            const now = spoken(event.active);
+            if (now.length > given) {
+                options.onDelta?.(now.slice(given));
+                given = now.length;
+            }
+            for (const part of event.active.parts) {
+                if (part.kind === 'toolCall')
+                    step({ id: part.call.id, name: part.call.name });
+            }
+            const call = event.active.parts.find((part) => part.kind === 'toolCall'
+                && part.call.status === 'pending-confirmation');
+            if (call?.kind === 'toolCall' && noted !== call.call.id) {
+                noted = call.call.id;
+                options.onWaiting?.({ id: call.call.id, name: call.call.name });
+            }
+            return false;
+        }
+        // Something wants a person. Not finished, and not this caller's to answer.
+        if (event.input)
+            return false;
+        const fresh = event.turns.filter((one) => one.role === 'agent' && !before.has(one.id));
+        if (!sawActive && fresh.length === 0)
+            return false;
+        answer = fresh[fresh.length - 1];
+        return true;
+    }, { ...(options.timeoutSeconds === undefined ? {} : { timeoutSeconds: options.timeoutSeconds }) });
+    host.say(uri, text, options.model);
+    await finished;
+    return answer;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softov/ahpc",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "A terminal client for the Agent Host Protocol: sessions, a streaming transcript, and interactive prompts",
   "keywords": [