@softov/ahpc 0.1.0 → 0.2.0

package/dist/src/wait.js

@@ -0,0 +1,147 @@
+/*
+ * 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;
+    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' && event.call.status === 'pending-confirmation') {
+            if (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;
+            }
+            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.2.0",
   "type": "module",
   "description": "A terminal client for the Agent Host Protocol: sessions, a streaming transcript, and interactive prompts",
   "keywords": [