@byokit/herdr 0.1.0-next.dbe7142

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## Unreleased
+
+- FIX docs drift (K10): README pins the v0.9.1 snapshot (protocol 22) instead of the H1
+  protocol placeholder; `agents.ts` agrees muxr sends `target_pane_id` to `pane.split`; the
+  fake bin's `api schema` reports the pinned identity with no placeholder text.
+
+- `adopt` mode takes `env` and `path` like `own`, merged into the `cli()`/`terminal()` env (so `HOME`,
+  `HERDR_CLIENT_SOCKET_PATH`, `HERDR_SESSION` and a `#!/usr/bin/env node` bin work); `TerminalSession.pause()`/`resume()`
+  apply backpressure to the Herdr child instead of buffering frames in the host.
+- FIX: the packed `dist/words.d.ts` keeps `with { type: 'json' }` on its `./words.json` import, so a strict NodeNext consumer with `skipLibCheck: false` no longer fails with TS1543.
+
+- Scaffold (docs/runtime-kits.md §11.3 H1): frozen public types, kit facade, internal seams and words. Behavior
+  lands in H2–H8; `HERDR_PROTOCOL` is a placeholder until the schema snapshot (H2).
+- Wire `HerdrKit.cli`/`terminal` to `runCli`/`openTerminal` with the supervisor env (6.5), export
+  `./testing`, and run `herdrContract` against `startFakeHerdr` in `test/contract.test.ts`.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,18 @@
+# @byokit/herdr
+
+Drive the Herdr already on this computer — workspaces, tabs, panes, coding agents and blocked-approval answers —
+from an app, or hand it to a phone over [`@byokit/link`](../link). Each agent inside Herdr keeps its own
+subscription login; the kit never sees a credential.
+
+Two ways in: `adopt` talks to the socket path the app passes (the person's own Herdr, nothing spawned, nothing
+written), `own` runs the Herdr binary the app names in an app-owned state directory. Helpers cover the common
+paths (start an agent, deliver a prompt with a receipt, watch blocked agents, exact closes); `call` and
+`subscribe` are typed pass-throughs to the complete socket API, and `cli()` reaches the full CLI.
+
+**Status:** pinned to Herdr v0.9.1 — the schema snapshot (`schema/herdr-api-0.9.1.json`,
+protocol 22) generates the typed surface (`src/generated/`, `HERDR_PROTOCOL` in `src/constants.ts`).
+See [docs/runtime-kits.md](../../docs/runtime-kits.md) §11.3 for the work packages.
+
+Herdr itself is not an npm dependency; the app installs it (see herdr.dev) and passes `bin`. The kit reads no
+environment variables, spawns processes with an explicit env only, and — like every byokit package — never
+touches a person's other AI tools; its tests run against a fake Herdr.

package/dist/agents.d.ts

@@ -0,0 +1,7 @@
+import type { HerdrKit } from './kit.ts';
+import type { HerdrSnapshot } from './types.ts';
+export type Call = (method: string, params: Record<string, unknown>, timeoutMs?: number) => Promise<unknown>;
+export declare function createAgents(ctx: {
+    call: Call;
+    snapshot(): HerdrSnapshot;
+}): Pick<HerdrKit, 'startAgent' | 'prompt' | 'sendKeys' | 'wait' | 'read' | 'agentKinds' | 'installedAgentKinds'>;

package/dist/agents.js

@@ -0,0 +1,141 @@
+// Agent helpers: placements, prompt receipts, waits and reads (docs/runtime-kits.md 6.4).
+// Exact param spellings come from the generated v0.9.1 table (6.7); where muxr and the schema
+// disagree the schema wins. `pane.split` takes `target_pane_id` (muxr agrees), and `agent.start`
+// has no `env` param — a start's env belongs to the placement create/split call (src/generated/methods.ts).
+import { accessSync, constants as fsConstants } from 'node:fs';
+import { join } from 'node:path';
+const PROMPTABLE = ['idle', 'working', 'blocked', 'done'];
+const DEFAULT_TIMEOUT_MS = 60_000;
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const fail = (code, message) => Object.assign(new Error(message), { code });
+function agentOf(snapshot, paneId) {
+    for (const w of snapshot.workspaces)
+        for (const t of w.tabs)
+            for (const p of t.panes) {
+                if (p.id === paneId)
+                    return p.agent;
+            }
+    return undefined;
+}
+// `agent.start` requires a name matching /^[a-z][a-z0-9_-]{0,31}$/; derive one from the kind when absent.
+function agentName(o) {
+    const slug = (o.name ?? o.kind).toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^[-_0-9]+/, '').slice(0, 32);
+    return /^[a-z]/.test(slug) ? slug : `a-${slug}`.slice(0, 32);
+}
+function rootPaneOf(result) {
+    const pane = isObj(result) ? result.root_pane : undefined;
+    return isObj(pane) && typeof pane.pane_id === 'string' ? pane.pane_id : undefined;
+}
+export function createAgents(ctx) {
+    const call = ctx.call;
+    // Every placement takes its pane id from the server's answer, never a prediction (6.4).
+    async function startAgent(o) {
+        const timeout = o.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const env = o.env === undefined ? {} : { env: o.env };
+        let paneId;
+        if (o.worktree !== undefined) {
+            const made = await call('worktree.create', { cwd: o.cwd, branch: o.worktree.branch,
+                ...(o.worktree.base === undefined ? {} : { base: o.worktree.base }) });
+            const worktree = isObj(made?.worktree) ? made.worktree : undefined;
+            const checkout = typeof worktree?.checkout_path === 'string' ? worktree.checkout_path
+                : typeof worktree?.path === 'string' ? worktree.path : o.cwd;
+            // The pinned schema's worktree.create carries the fresh root pane; a server that leaves the
+            // new workspace empty gets its first tab opened in the checkout instead.
+            paneId = rootPaneOf(made) ?? rootPaneOf(await call('tab.create', {
+                workspace_id: made?.workspace?.workspace_id, cwd: checkout, focus: false, ...env,
+            }));
+        }
+        else if ('workspace' in o.place) {
+            paneId = rootPaneOf(await call('workspace.create', { cwd: o.cwd,
+                ...(o.place.label === undefined ? {} : { label: o.place.label }), focus: false, ...env }));
+        }
+        else if ('tab' in o.place) {
+            paneId = rootPaneOf(await call('tab.create', { workspace_id: o.place.workspaceId, cwd: o.cwd,
+                ...(o.place.label === undefined ? {} : { label: o.place.label }), focus: false, ...env }));
+        }
+        else if ('split' in o.place) {
+            const made = await call('pane.split', { target_pane_id: o.place.split,
+                direction: o.place.direction, focus: false, ...env });
+            paneId = typeof made?.pane?.pane_id === 'string' ? made.pane.pane_id : undefined;
+        }
+        else {
+            paneId = o.place.pane;
+        }
+        if (paneId === undefined)
+            throw new Error('herdr: the placement answered no pane id');
+        const name = agentName(o);
+        await call('agent.start', { pane_id: paneId, kind: o.kind, name,
+            ...(o.args === undefined ? {} : { args: o.args }), timeout_ms: timeout }, timeout + 5000);
+        return { paneId, name };
+    }
+    async function prompt(target, text, o) {
+        // The readiness gate reads the kit's own tree: a not-promptable agent is refused with no socket call.
+        const agent = agentOf(ctx.snapshot(), target.paneId);
+        if (agent === undefined || agent.launchPending === true || agent.interactiveReady === false
+            || !PROMPTABLE.includes(agent.status)) {
+            throw fail('agent-not-ready', 'That agent is not ready for a prompt yet.');
+        }
+        const wait = o?.wait === undefined ? undefined
+            : { timeout_ms: o.wait.timeoutMs, ...(o.wait.until === undefined ? {} : { until: o.wait.until }) };
+        let receipt;
+        try {
+            receipt = await call('agent.prompt', { target: target.paneId, text,
+                ...(wait === undefined ? {} : { wait }) });
+        }
+        catch (error) {
+            if (error?.code === 'agent_blocked') {
+                throw fail('agent-blocked', 'That agent is blocked and needs an answer before a new prompt.');
+            }
+            throw error;
+        }
+        const body = isObj(receipt) ? receipt : undefined;
+        const a = isObj(body?.agent) ? body.agent : undefined;
+        if (body?.type !== 'agent_prompted' || a === undefined
+            || typeof a.terminal_id !== 'string' || typeof a.agent_status !== 'string'
+            || typeof a.workspace_id !== 'string' || typeof a.tab_id !== 'string'
+            || typeof a.pane_id !== 'string' || typeof a.focused !== 'boolean'
+            || typeof a.revision !== 'number' || !Number.isSafeInteger(a.revision) || a.revision < 0
+            || a.pane_id !== target.paneId) {
+            throw new Error('Herdr did not queue the prompt.');
+        }
+        return { paneId: a.pane_id, terminalId: a.terminal_id, revision: a.revision, status: a.agent_status };
+    }
+    async function wait(target, o) {
+        const made = await call('agent.wait', { target: target.paneId,
+            ...(o.until === undefined ? {} : { until: o.until }), timeout_ms: o.timeoutMs });
+        // The fake answers `{ agent }`; the pinned schema wraps the status event in `event.data` — both unwrap.
+        return (made?.agent?.agent_status ?? made?.event?.data?.agent_status ?? 'unknown');
+    }
+    async function read(paneId, o) {
+        const made = await call('pane.read', { pane_id: paneId, source: o?.source ?? 'recent',
+            ...(o?.lines === undefined ? {} : { lines: o.lines }),
+            ...(o?.ansi === true ? { format: 'ansi' } : {}) });
+        const body = isObj(made?.read) ? made.read : undefined;
+        return { text: typeof body?.text === 'string' ? body.text : '', truncated: body?.truncated === true };
+    }
+    async function sendKeys(target, keys) {
+        await call('agent.send_keys', { target: target.paneId, keys });
+    }
+    async function agentKinds() {
+        const made = await call('server.agent_manifests', {});
+        const manifests = Array.isArray(made?.manifests) ? made.manifests : [];
+        return manifests.map((m) => (typeof m?.agent === 'string' ? m.agent : '')).filter((kind) => kind !== '');
+    }
+    function installedAgentKinds(kinds, o) {
+        const installed = [];
+        for (const kind of kinds) {
+            if (o.path.some((dir) => {
+                try {
+                    accessSync(join(dir, kind), fsConstants.X_OK);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }))
+                installed.push(kind);
+        }
+        return installed;
+    }
+    return { startAgent, prompt, sendKeys, wait, read, agentKinds, installedAgentKinds };
+}

package/dist/approvals.d.ts

@@ -0,0 +1,24 @@
+import type { Call } from './agents.ts';
+import type { BlockedAgent, HerdrSnapshot } from './types.ts';
+type AgentRecord = NonNullable<HerdrSnapshot['workspaces'][number]['tabs'][number]['panes'][number]['agent']>;
+export declare class Blocked {
+    private readonly call;
+    private readonly entries;
+    private readonly listeners;
+    private readonly reading;
+    private readonly wanted;
+    constructor(ctx: {
+        call: Call;
+    });
+    update(paneId: string, agent: AgentRecord | undefined, where: {
+        workspaceId: string;
+        tabId: string;
+    }): void;
+    private readPrompt;
+    list(): BlockedAgent[];
+    on(fn: (b: BlockedAgent, change: 'added' | 'resolved') => void): () => void;
+    answer(paneId: string, keys: string[], o: {
+        revision: number;
+    }): Promise<void>;
+}
+export {};

package/dist/approvals.js

@@ -0,0 +1,81 @@
+const fail = (code, message) => Object.assign(new Error(message), { code });
+export class Blocked {
+    call;
+    entries = new Map();
+    listeners = new Set();
+    reading = new Set(); // detection reads in flight, one per pane
+    wanted = new Set(); // panes still blocked while their read is in flight
+    constructor(ctx) { this.call = ctx.call; }
+    update(paneId, agent, where) {
+        if (agent?.status !== 'blocked') {
+            this.wanted.delete(paneId);
+            const entry = this.entries.get(paneId);
+            if (entry !== undefined) {
+                this.entries.delete(paneId);
+                for (const fn of this.listeners)
+                    fn(entry, 'resolved');
+            }
+            return;
+        }
+        const current = this.entries.get(paneId);
+        if (current !== undefined) {
+            // Still blocked: keep the question, follow the pane's revision.
+            if (agent.revision !== current.revision)
+                this.entries.set(paneId, { ...current, revision: agent.revision });
+            return;
+        }
+        if (this.reading.has(paneId)) {
+            this.wanted.add(paneId);
+            return;
+        }
+        this.wanted.add(paneId);
+        this.reading.add(paneId);
+        const pending = {
+            paneId, workspaceId: where.workspaceId, tabId: where.tabId,
+            ...(agent.kind === undefined ? {} : { kind: agent.kind }),
+            revision: agent.revision, prompt: '', since: Date.now(),
+        };
+        void this.readPrompt(pending);
+    }
+    // The entry only appears once its prompt text is known, so `list()` never shows a half-read question.
+    async readPrompt(pending) {
+        let prompt = '';
+        try {
+            const made = (await this.call('pane.read', { pane_id: pending.paneId, source: 'detection', lines: 40 }));
+            if (typeof made?.read?.text === 'string')
+                prompt = made.read.text;
+        }
+        catch { /* a failed read still lists the blocked agent, with the text it could get */ }
+        this.reading.delete(pending.paneId);
+        if (!this.wanted.delete(pending.paneId))
+            return; // the pane left `blocked` while the read ran
+        const entry = { ...pending, prompt };
+        this.entries.set(pending.paneId, entry);
+        for (const fn of this.listeners)
+            fn(entry, 'added');
+    }
+    list() { return [...this.entries.values()]; }
+    on(fn) {
+        this.listeners.add(fn);
+        return () => { this.listeners.delete(fn); };
+    }
+    async answer(paneId, keys, o) {
+        let status;
+        let current;
+        try {
+            const made = (await this.call('pane.get', { pane_id: paneId }));
+            status = made?.pane?.agent_status;
+            // The pinned schema carries the pane's revision on pane.get; a server without it falls back
+            // to the revision recorded when the question appeared.
+            if (typeof made?.pane?.revision === 'number')
+                current = made.pane.revision;
+        }
+        catch { /* gone or unreachable: the recorded revision decides below */ }
+        if (current === undefined)
+            current = this.entries.get(paneId)?.revision;
+        if (status !== 'blocked' || current === undefined || o.revision !== current) {
+            throw fail('approval-stale', 'That answer is out of date; the question has changed.');
+        }
+        await this.call('agent.send_keys', { target: paneId, keys });
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+export type CliResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    timedOut: boolean;
+};
+export declare const DEFAULT_CLI_TIMEOUT = 15000;
+/** ENOENT and friends carry the kit's `missing/binary` code (6.3/6.5), message per the 6.3 error shape. */
+export declare function missingBinary(bin: string, cause?: string): Error;
+export declare function runCli(bin: string, env: Record<string, string>, args: string[], timeoutMs?: number): Promise<CliResult>;

package/dist/cli.js

@@ -0,0 +1,89 @@
+// `herdr <args>` with the kit's own env, one argv entry per argument, no environment read
+// (docs/runtime-kits.md 6.5, D13). The env comes from the supervisor (6.3) in `own` mode or is the
+// fixed adopt env in 6.5; this module passes it through verbatim and never touches `process.env`.
+import { spawn } from 'node:child_process';
+// The doc's ceiling: an 8 MB cap per stream, timeouts clamped to 1 s–5 min (docs/runtime-kits.md §11.3 H4).
+const MAX_BUFFER = 8 * 1024 * 1024;
+const MIN_TIMEOUT = 1_000;
+const MAX_TIMEOUT = 5 * 60_000;
+export const DEFAULT_CLI_TIMEOUT = 15_000; // same default as a socket call (6.3)
+/** ENOENT and friends carry the kit's `missing/binary` code (6.3/6.5), message per the 6.3 error shape. */
+export function missingBinary(bin, cause = 'spawn failed') {
+    const e = new Error(`herdr: missing/binary: ${cause}: ${bin}`);
+    e.code = 'missing/binary';
+    return e;
+}
+/** argv goes one entry per execve argument (spaces and quotes survive); reject anything execve would mangle. */
+function checkArgs(args) {
+    if (!Array.isArray(args) || args.length === 0)
+        throw new Error('herdr: args must be a non-empty array of strings');
+    for (const a of args) {
+        if (typeof a !== 'string')
+            throw new Error('herdr: every arg must be a string');
+        if (a.includes('\0'))
+            throw new Error('herdr: args must not contain NUL');
+    }
+}
+function clampTimeout(timeoutMs) {
+    return Math.min(Math.max(timeoutMs ?? DEFAULT_CLI_TIMEOUT, MIN_TIMEOUT), MAX_TIMEOUT);
+}
+export function runCli(bin, env, args, timeoutMs) {
+    if (typeof bin !== 'string' || bin.length === 0)
+        throw new Error('herdr: bin must be a non-empty string');
+    checkArgs(args);
+    const timeout = clampTimeout(timeoutMs);
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, args, { env, stdio: ['ignore', 'pipe', 'pipe'] });
+        const out = [];
+        const err = [];
+        let outLen = 0;
+        let errLen = 0;
+        let timedOut = false;
+        let settled = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+            settle({ stdout: Buffer.concat(out).toString('utf8'), stderr: Buffer.concat(err).toString('utf8'),
+                exitCode: null, timedOut: true });
+        }, timeout);
+        const settle = (r, e) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (e !== undefined)
+                reject(e);
+            else
+                resolve(r);
+        };
+        child.on('error', (e) => {
+            settle(undefined, e.code === 'ENOENT' ? missingBinary(bin, 'no executable') : e);
+        });
+        child.stdout.on('data', (chunk) => {
+            if (settled)
+                return;
+            outLen += chunk.length;
+            if (outLen > MAX_BUFFER) {
+                child.kill();
+                settle(undefined, new Error('herdr: stdout exceeded the 8 MB buffer'));
+                return;
+            }
+            out.push(chunk);
+        });
+        child.stderr.on('data', (chunk) => {
+            if (settled)
+                return;
+            errLen += chunk.length;
+            if (errLen > MAX_BUFFER) {
+                child.kill();
+                settle(undefined, new Error('herdr: stderr exceeded the 8 MB buffer'));
+                return;
+            }
+            err.push(chunk);
+        });
+        child.on('close', (code) => {
+            settle({ stdout: Buffer.concat(out).toString('utf8'), stderr: Buffer.concat(err).toString('utf8'),
+                exitCode: code, timedOut });
+        });
+    });
+}

package/dist/close.d.ts

@@ -0,0 +1,4 @@
+import type { Call } from './agents.ts';
+export declare function closePane(call: Call, paneId: string): Promise<void>;
+export declare function closeTab(call: Call, tabId: string): Promise<void>;
+export declare function closeWorkspace(call: Call, workspaceId: string): Promise<void>;