@byokit/herdr 0.1.0-next.dbe7142 → 0.1.1

package/dist/testing/contract.d.ts

@@ -1,9 +1,19 @@
 import type { HerdrKit } from '../kit.ts';
 import type { FakeHerdr } from './fake-herdr/server.ts';
-import type { HerdrTransport } from '../types.ts';
+import type { HerdrProtocolRange, HerdrTransport } from '../types.ts';
 export type HerdrContractBench = {
     kit: HerdrKit;
     fake?: FakeHerdr;
-    withTransport?: (transport: HerdrTransport) => HerdrKit;
+    withTransport?: (transport: HerdrTransport, o?: {
+        protocolRange?: HerdrProtocolRange;
+    }) => HerdrKit;
 };
-export declare function herdrContract(make: () => Promise<HerdrContractBench>): void;
+export type HerdrContractTestContext = {
+    skip: (message?: string) => void;
+};
+export type HerdrContractTestFn = (name: string, fn: (t: HerdrContractTestContext) => void | Promise<void>) => void | Promise<void>;
+export type HerdrContractOptions = {
+    /** The runner's `test` (node:test's by default; pass vitest's `test` under vitest). */
+    test?: HerdrContractTestFn;
+};
+export declare function herdrContract(make: () => Promise<HerdrContractBench>, options?: HerdrContractOptions | HerdrContractTestFn): void;

package/dist/testing/contract.js

@@ -2,10 +2,12 @@
 // in later work packages' tests (H3/H5 wire `make` up) and against the real pinned Herdr in the lab
 // (H9, which passes no `fake`). Cases that need to script the transport's wire answers use
 // `withTransport`; when a `make` omits it, those cases skip.
-import { test } from 'node:test';
+import { test as nodeTest } from 'node:test';
 import assert from 'node:assert/strict';
 import { HERDR_PROTOCOL } from "../constants.js";
-export function herdrContract(make) {
+export function herdrContract(make, options) {
+    const runTest = typeof options === 'function' ? options : (options?.test ?? nodeTest);
+    const test = runTest;
     const settle = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
     async function until(probe, ok, ms = 2000) {
         const deadline = Date.now() + ms;
@@ -29,6 +31,14 @@ export function herdrContract(make) {
             await made.fake?.stop().catch(() => { });
         }
     }
+    // Transport doubles that never exercise the control surface still satisfy its type.
+    function ackedStop() {
+        return Object.assign(() => { }, {
+            ready: Promise.resolve(true),
+            onReconnect() { },
+            onDisconnect() { },
+        });
+    }
     function agentStatusOf(snapshot, paneId) {
         let panes = 0;
         let status;
@@ -52,24 +62,96 @@ export function herdrContract(make) {
             assert.equal(typeof ping.version, 'string');
         });
     });
-    test('contract: a protocol mismatch reports needs-update', async (t) => {
+    test('contract: a newer server is needs-update state, not a throw — the kit stays usable', async (t) => {
         await bench(async ({ withTransport }) => {
             if (!withTransport)
                 return t.skip('make provides no transport double');
+            const snapshot = {
+                protocol: HERDR_PROTOCOL + 999,
+                snapshot: {
+                    protocol: HERDR_PROTOCOL + 999,
+                    workspaces: [{ workspace_id: 'w1', label: 'x' }],
+                    tabs: [{ tab_id: 'w1:t1', workspace_id: 'w1', label: 'main' }],
+                    panes: [{ pane_id: 'w1:p2', tab_id: 'w1:t1', workspace_id: 'w1' }],
+                    agents: [{ pane_id: 'w1:p2', agent_status: 'idle', revision: 1 }],
+                },
+            };
             const kit = withTransport({
-                call: async () => ({ protocol: HERDR_PROTOCOL + 999 }),
-                subscribe: () => () => { },
+                call: async (method) => (method === 'session.snapshot' ? snapshot : { protocol: HERDR_PROTOCOL + 999 }),
+                subscribe: () => ackedStop(),
                 close: () => { },
             });
             try {
-                await kit.start().catch(() => { });
+                await kit.start();
                 assert.equal(kit.state.phase, 'needs-update');
+                assert.equal(kit.state.why, 'version');
+                assert.equal(kit.snapshot().workspaces.length, 1, 'the snapshot still installs');
+                assert.ok(kit.snapshot().connected, 'the kit stays connected');
+                await kit.call('ping', {});
             }
             finally {
                 await kit.stop().catch(() => { });
             }
         });
     });
+    test('contract: an older server fails closed', async (t) => {
+        await bench(async ({ withTransport }) => {
+            if (!withTransport)
+                return t.skip('make provides no transport double');
+            const kit = withTransport({
+                call: async () => ({ protocol: HERDR_PROTOCOL - 1 }),
+                subscribe: () => ackedStop(),
+                close: () => { },
+            });
+            try {
+                await assert.rejects(kit.start(), /protocol mismatch/);
+                assert.equal(kit.state.phase, 'needs-update');
+            }
+            finally {
+                await kit.stop().catch(() => { });
+            }
+        });
+    });
+    test('contract: a declared protocol range accepts a newer server as ready', async (t) => {
+        await bench(async ({ withTransport }) => {
+            if (!withTransport)
+                return t.skip('make provides no transport double');
+            const snapshot = {
+                protocol: HERDR_PROTOCOL + 1,
+                snapshot: {
+                    protocol: HERDR_PROTOCOL + 1,
+                    workspaces: [{ workspace_id: 'w1', label: 'x' }],
+                    tabs: [{ tab_id: 'w1:t1', workspace_id: 'w1', label: 'main' }],
+                    panes: [{ pane_id: 'w1:p2', tab_id: 'w1:t1', workspace_id: 'w1' }],
+                    agents: [{ pane_id: 'w1:p2', agent_status: 'idle', revision: 1 }],
+                },
+            };
+            const transport = {
+                call: async (method) => (method === 'session.snapshot' ? snapshot : { protocol: HERDR_PROTOCOL + 1 }),
+                subscribe: () => ackedStop(),
+                close: () => { },
+            };
+            const inRange = withTransport(transport);
+            try {
+                await inRange.start();
+                assert.equal(inRange.state.phase, 'needs-update', 'without the range a newer server is needs-update');
+            }
+            finally {
+                await inRange.stop().catch(() => { });
+            }
+            const ranged = withTransport(transport, {
+                protocolRange: { min: HERDR_PROTOCOL, max: HERDR_PROTOCOL + 1 },
+            });
+            try {
+                await ranged.start();
+                assert.equal(ranged.state.phase, 'ready', 'the declared range accepts the newer server');
+                assert.equal(ranged.snapshot().workspaces.length, 1);
+            }
+            finally {
+                await ranged.stop().catch(() => { });
+            }
+        });
+    });
     test('contract: an event racing the bootstrap snapshot is applied after it, once', async (t) => {
         await bench(async ({ withTransport }) => {
             if (!withTransport)
@@ -83,12 +165,12 @@ export function herdrContract(make) {
                 },
             };
             const kit = withTransport({
-                // The ack carries the race: `pane.updated` lands after the subscribe but before the kit
+                // The ack carries the race: `pane_updated` lands after the subscribe but before the kit
                 // installs the snapshot, so buffering must order it after — and never duplicate it.
                 call: async (method) => (method === 'session.snapshot' ? snapshot : { protocol: HERDR_PROTOCOL }),
                 subscribe: (_subs, on) => {
-                    queueMicrotask(() => on({ type: 'pane.updated', pane: { pane_id: 'w1:p2', agent_status: 'working' } }));
-                    return () => { };
+                    queueMicrotask(() => on({ type: 'pane_updated', pane: { pane_id: 'w1:p2', agent_status: 'working' } }));
+                    return ackedStop();
                 },
                 close: () => { },
             });
@@ -116,7 +198,7 @@ export function herdrContract(make) {
                     if (subs.some((s) => s.type === 'pane.agent_status_changed')) {
                         onError('invalid_subscription', 'pane.agent_status_changed needs a pane_id');
                     }
-                    return () => { };
+                    return ackedStop();
                 },
                 close: () => { },
             });
@@ -126,9 +208,17 @@ export function herdrContract(make) {
                 // Deliberately schema-invalid: the pinned schema (6.7) requires pane_id for this filtered
                 // kind, so the server rejects the batch — the exact answer the transport double gives here.
                 const rejected = { type: 'pane.agent_status_changed' };
-                kit.subscribe([rejected], () => { });
+                const errors = [];
+                const stop = kit.subscribe([rejected], () => { }, (code, message) => errors.push({ code, message }));
+                assert.equal(typeof stop, 'function');
+                assert.ok(stop.ready instanceof Promise, 'the stop carries the ack promise');
+                assert.equal(typeof stop.onReconnect, 'function');
+                assert.equal(typeof stop.onDisconnect, 'function');
                 await settle(1200); // longer than the 1 s reconnect delay a retry would use
+                assert.deepEqual(errors.map((e) => e.code), ['invalid_subscription'], 'the rejection reaches onError exactly once');
+                assert.match(errors[0].message, /pane_id/);
                 assert.equal(subscribeCalls, bootstrapCalls + 1, 'the rejected subscription is never retried');
+                stop();
             }
             finally {
                 await kit.stop().catch(() => { });
@@ -145,6 +235,8 @@ export function herdrContract(make) {
             await settle(100); // the subscribe registers on its own socket; an emit before that never arrives
             fake.emit({ type: 'pane.created', pane_id: 'w9:p9' });
             await until(() => seen.length, (n) => n >= 1);
+            // The fake emits the live underscore spelling; the kit matches both spellings.
+            assert.equal(seen[0].type, 'pane_created');
             assert.equal(seen[0].pane_id, 'w9:p9');
             stop();
             fake.emit({ type: 'pane.created', pane_id: 'w9:p10' });
@@ -191,6 +283,18 @@ export function herdrContract(make) {
             assert.ok(workspaces.workspaces?.some((workspace) => workspace.worktree?.is_linked_worktree === true), 'the worktree placement registers a linked checkout');
         });
     });
+    test('contract: a started agent joins snapshot() and its status stays current there', async () => {
+        await bench(async ({ kit }) => {
+            await kit.start();
+            const { paneId } = await kit.startAgent({ kind: 'pi', cwd: '/tmp/h6', place: { workspace: 'new' } });
+            await until(() => agentStatusOf(kit.snapshot(), paneId).status, (status) => status === 'idle');
+            await kit.prompt({ paneId }, 'ask permission');
+            await until(() => agentStatusOf(kit.snapshot(), paneId).status, (status) => status === 'blocked');
+            const blocked = await until(() => kit.blocked().find((b) => b.paneId === paneId), () => true);
+            await kit.answer(paneId, ['y'], { revision: blocked.revision });
+            await until(() => agentStatusOf(kit.snapshot(), paneId).status, (status) => status === 'idle');
+        });
+    });
     test('contract: prompt validates the receipt and appends the reply text', async () => {
         await bench(async ({ kit }) => {
             await kit.start();
@@ -223,7 +327,7 @@ export function herdrContract(make) {
                     }
                     return { protocol: HERDR_PROTOCOL };
                 },
-                subscribe: () => () => { },
+                subscribe: () => ackedStop(),
                 close: () => { },
             });
             try {

package/dist/testing/fake-herdr/bin.js

@@ -2,9 +2,9 @@
 // `api schema`, the `server` verb, JSON CLI verbs and `terminal session`. World state lives on the
 // control socket; this process never speaks JSON-RPC except to forward a CLI verb. Ported from muxr
 // `perf/fake-herdr/bin.mjs` with the perf byte rates and graphics probes removed.
-import { chmodSync, mkdirSync, writeFileSync } from 'node:fs';
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { createConnection } from 'node:net';
-import { dirname, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { HERDR_PROTOCOL, HERDR_VERSION } from "../../constants.js";
 const SELF = fileURLToPath(import.meta.url);
@@ -82,13 +82,20 @@ async function runServer() {
     process.on('SIGTERM', stop);
     process.on('SIGINT', stop);
 }
-// `{"type":"fake.stream","count":n,"size":b,"progress":file}` on stdin: n frames with data `<i>:` plus b bytes,
-// written as fast as the pipe takes them. After each write the frames-written count lands in `progress`, so a
-// test can see how far a paused reader let the stream run.
+// Terminal frames carry the real Herdr shape — `{ type: 'terminal.frame', pane_id, full, bytes }`
+// with `bytes` the UTF-8 length of `full` — plus the fake's `data` alias (same string as `full`),
+// so older assertions reading `data` keep passing. A `{"type":"terminal.resize",cols,rows}` line
+// resizes the session and answers one empty frame stamped with the new size; `terminal.release`
+// exits; `{"type":"fake.stream","count":n,"size":b,"progress":file}` streams n frames with full
+// `<i>:` plus b bytes as fast as the pipe takes them, recording the frames-written count in
+// `progress` after each write so a test can see how far a paused reader let the stream run.
+function frame(paneId, full, extra = {}) {
+    return `${JSON.stringify({ type: 'terminal.frame', pane_id: paneId, data: full, full, bytes: Buffer.byteLength(full), ...extra })}\n`;
+}
 async function stream(paneId, o) {
     const pad = 'x'.repeat(o.size ?? 1024);
     for (let i = 0; i < (o.count ?? 0); i += 1) {
-        const ok = process.stdout.write(`${JSON.stringify({ type: 'terminal.frame', pane_id: paneId, data: `${i}:${pad}` })}\n`);
+        const ok = process.stdout.write(frame(paneId, `${i}:${pad}`));
         if (o.progress)
             writeFileSync(o.progress, String(i + 1));
         if (!ok)
@@ -98,12 +105,12 @@ async function stream(paneId, o) {
 function runTerminal(args) {
     // `herdr terminal session <control|observe> <pane> [--takeover] --cols <n> --rows <n>`.
     // The fake needs no server for this: one ready frame, then every send line echoes back as an
-    // output frame (docs/runtime-kits.md 6.8), except `fake.stream` below.
+    // output frame (docs/runtime-kits.md 6.8), except `fake.stream` and `terminal.resize` above.
     const mode = args[0] === 'observe' ? 'observe' : 'control';
     const rest = args[0] === 'control' || args[0] === 'observe' ? args.slice(1) : args;
     const paneId = rest[0] ?? 'w1:p1';
-    const cols = Number(flag(args, '--cols')) || 80;
-    const rows = Number(flag(args, '--rows')) || 24;
+    let cols = Number(flag(args, '--cols')) || 80;
+    let rows = Number(flag(args, '--rows')) || 24;
     const takeover = args.includes('--takeover');
     process.stdout.write(`${JSON.stringify({ type: 'terminal.ready', pane_id: paneId, mode, takeover, cols, rows })}\n`);
     let buffer = '';
@@ -116,6 +123,7 @@ function runTerminal(args) {
             if (line.trim() === '')
                 continue;
             let data = line;
+            let extra = {};
             try {
                 const message = JSON.parse(line);
                 if (message.type === 'terminal.release')
@@ -124,11 +132,20 @@ function runTerminal(args) {
                     void stream(paneId, message);
                     continue;
                 }
+                if (message.type === 'terminal.resize') {
+                    if (typeof message.cols === 'number' && message.cols > 0)
+                        cols = Math.floor(message.cols);
+                    if (typeof message.rows === 'number' && message.rows > 0)
+                        rows = Math.floor(message.rows);
+                    process.stdout.write(frame(paneId, '', { cols, rows }));
+                    continue;
+                }
+                // `terminal.input` carries the keys in `data`; anything else with a string `data` echoes it.
                 if (typeof message.data === 'string')
                     data = message.data;
             }
             catch { /* a raw line echoes as-is */ }
-            process.stdout.write(`${JSON.stringify({ type: 'terminal.frame', pane_id: paneId, data })}\n`);
+            process.stdout.write(frame(paneId, data, { cols, rows }));
         }
     });
     process.stdin.on('end', () => process.exit(0));
@@ -186,8 +203,20 @@ export async function main(argv) {
         return;
     }
     if (cmd === 'api' && sub === 'schema') {
-        // Reports the pinned v0.9.1 snapshot identity (schema/herdr-api-0.9.1.json, docs/runtime-kits.md 6.7).
-        process.stdout.write(`${JSON.stringify({ title: 'herdr api schema', protocol: HERDR_PROTOCOL, version: HERDR_VERSION })}\n`);
+        // Prints the pinned v0.9.1 snapshot itself (schema/herdr-api-0.9.1.json, docs/runtime-kits.md
+        // 6.7) — the same bytes `scripts/gen-types.ts` generates the typed surface from — exactly as
+        // the real `herdr api schema` prints its bundled schema. Only when the snapshot file is
+        // unreachable (a packed install without it) does the shim fall back to the pinned identity.
+        try {
+            const snapshot = readFileSync(join(dirname(SELF), '../../../schema/herdr-api-0.9.1.json'), 'utf8');
+            const parsed = JSON.parse(snapshot);
+            if (parsed.protocol !== HERDR_PROTOCOL)
+                throw new Error('fake-herdr bin: schema snapshot drift');
+            process.stdout.write(snapshot.endsWith('\n') ? snapshot : `${snapshot}\n`);
+        }
+        catch {
+            process.stdout.write(`${JSON.stringify({ protocol: HERDR_PROTOCOL, version: HERDR_VERSION })}\n`);
+        }
         return;
     }
     if (cmd === 'server') {

package/dist/testing/fake-herdr/server.d.ts

@@ -1,21 +1,37 @@
-import { type FakeWorld } from './world.ts';
+import { type FakePluginSeed, type FakeWorld } from './world.ts';
 export type FakeHerdrOptions = {
     dir: string;
     socketPath?: string;
     world?: {
         cwd?: string;
         kinds?: readonly string[];
+        seed?: number;
+        plugins?: readonly FakePluginSeed[];
     };
+    agentStartFaults?: AgentStartFault[];
     onStop?: () => void;
 };
+export type AgentStartFault = {
+    code: string;
+    message?: string;
+};
 export type FakeHerdr = {
     socketPath: string;
     bin: string;
     world: FakeWorld;
+    agentStartFaults: AgentStartFault[];
     emit(event: {
         type: string;
     } & Record<string, unknown>): void;
     setStatus(paneId: string, status: string): void;
+    watching(): string[];
+    watching(paneId: string): boolean;
+    snapshotCount(): number;
+    holdSnapshot(): () => void;
+    failNextSnapshot(code?: string, message?: string): void;
+    holdAck(): () => void;
+    failNextAck(code?: string, message?: string): void;
+    subscriptionCount(): number;
     stop(): Promise<void>;
 };
 export declare function startFakeHerdr(options: FakeHerdrOptions): Promise<FakeHerdr>;