@byokit/herdr 0.1.0-next.dbe7142

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

@@ -0,0 +1,85 @@
+// The deterministic herd the fake serves (docs/runtime-kits.md 6.8): 1 workspace, 1 tab, 2 panes —
+// `w1:p1` a plain shell, `w1:p2` an agent of the first kind. Ids follow the live Herdr
+// `workspace:pane` shape so close guards and filtered subscriptions bind. Ported from muxr
+// `perf/fake-herdr/world.mjs` with the multi-tab herd and perf fixtures removed.
+export const COLS = 80;
+export const ROWS = 24;
+export function paneRect(indexInTab, panesInTab) {
+    const height = Math.max(1, Math.floor(ROWS / panesInTab));
+    const y = indexInTab * height;
+    return {
+        x: 0,
+        y,
+        width: COLS,
+        height: indexInTab === panesInTab - 1 ? ROWS - y : height,
+    };
+}
+export function agentRecord(o) {
+    return {
+        pane_id: o.paneId,
+        tab_id: o.tabId,
+        workspace_id: o.workspaceId,
+        cwd: o.cwd,
+        foreground_cwd: o.cwd,
+        name: o.name,
+        agent: o.kind,
+        display_agent: o.name,
+        agent_status: 'idle',
+        interactive_ready: true,
+        launch_pending: false,
+        revision: o.revision,
+        agent_session: { source: `herdr:${o.kind}`, agent: o.kind, kind: 'id', value: `gen-${o.paneId}` },
+    };
+}
+export function createWorld(o) {
+    const workspace = {
+        workspace_id: 'w1',
+        label: o.cwd,
+        focused: true,
+        worktree: {
+            repo_key: 'fake-herdr',
+            repo_name: 'fake-herdr',
+            repo_root: o.cwd,
+            checkout_path: o.cwd,
+            is_linked_worktree: false,
+        },
+    };
+    const tab = { tab_id: 'w1:t1', workspace_id: 'w1', label: 'main' };
+    const shell = {
+        pane_id: 'w1:p1',
+        tab_id: tab.tab_id,
+        workspace_id: 'w1',
+        cwd: o.cwd,
+        foreground_cwd: o.cwd,
+        label: 'zsh',
+        terminal_title: `zsh · ${o.cwd}`,
+        terminal_title_stripped: `zsh · ${o.cwd}`,
+        focused: true,
+        tokens: {},
+        rect: paneRect(0, 2),
+        text: ['ready.'],
+    };
+    const kind = o.kinds[0] ?? 'pi';
+    const agentPane = {
+        ...shell,
+        pane_id: 'w1:p2',
+        focused: false,
+        rect: paneRect(1, 2),
+        agent_status: 'idle',
+        label: kind,
+        terminal_title: `${kind} · ${kind}`,
+        terminal_title_stripped: `${kind} · ${kind}`,
+    };
+    const agent = agentRecord({
+        paneId: agentPane.pane_id, tabId: tab.tab_id, workspaceId: 'w1', cwd: o.cwd,
+        name: kind, kind, revision: 0,
+    });
+    return { cwd: o.cwd, workspaces: [workspace], tabs: [tab], panes: [shell, agentPane], agents: [agent] };
+}
+export function relayoutTab(world, tabId) {
+    const panes = world.panes.filter((pane) => pane.tab_id === tabId);
+    panes.forEach((pane, index) => { pane.rect = paneRect(index, panes.length); });
+}
+export function freezeWorld(world) {
+    return JSON.parse(JSON.stringify(world));
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,4 @@
+export { startFakeHerdr, type FakeHerdr, type FakeHerdrOptions } from './fake-herdr/server.ts';
+export { writeBinShim, main as fakeHerdrBinMain } from './fake-herdr/bin.ts';
+export { createWorld, type FakeWorld } from './fake-herdr/world.ts';
+export { herdrContract, type HerdrContractBench } from './contract.ts';

package/dist/testing/index.js

@@ -0,0 +1,7 @@
+// The kit's fake Herdr and contract suite (docs/runtime-kits.md 6.8). Built in H6; H3/H5 run the
+// contract against the fake, H9 against the real pinned Herdr. Tests import this by relative path —
+// the package's public exports stay the kit surface.
+export { startFakeHerdr } from "./fake-herdr/server.js";
+export { writeBinShim, main as fakeHerdrBinMain } from "./fake-herdr/bin.js";
+export { createWorld } from "./fake-herdr/world.js";
+export { herdrContract } from "./contract.js";

package/dist/types.d.ts

@@ -0,0 +1,115 @@
+export type HerdrState = {
+    phase: 'stopped' | 'connecting' | 'ready' | 'reconnecting' | 'needs-update' | 'missing' | 'failed';
+    why?: 'binary' | 'socket' | 'version' | 'server-exited';
+};
+export type HerdrKitOptions = {
+    mode: 'adopt';
+    bin: string;
+    socketPath: string;
+    env?: Record<string, string>;
+    path?: string[];
+    transport?: HerdrTransport;
+    onState?: (s: HerdrState) => void;
+} | {
+    mode: 'own';
+    bin: string;
+    stateDir: string;
+    env?: Record<string, string>;
+    path?: string[];
+    transport?: HerdrTransport;
+    onState?: (s: HerdrState) => void;
+};
+export interface HerdrTransport {
+    call(method: string, params: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+    subscribe(subs: {
+        type: string;
+        [k: string]: unknown;
+    }[], on: (e: HerdrEvent) => void, onError: (code: string, message: string) => void): () => void;
+    close(): void;
+}
+export type HerdrEvent = {
+    type: string;
+    [k: string]: unknown;
+};
+export type { HerdrMethods, HerdrMethod, HerdrParams, HerdrResult } from './generated/methods.ts';
+export type { HerdrEvents, HerdrEventName, HerdrEventOf, HerdrSubscription } from './generated/events.ts';
+export type AgentStatus = 'idle' | 'working' | 'blocked' | 'done' | 'unknown';
+export type AgentRef = {
+    paneId: string;
+    name?: string;
+};
+export type StartAgent = {
+    kind: string;
+    cwd: string;
+    name?: string;
+    place: {
+        workspace: 'new';
+        label?: string;
+    } | {
+        tab: 'new';
+        workspaceId: string;
+        label?: string;
+    } | {
+        split: string;
+        direction: 'right' | 'down';
+    } | {
+        pane: string;
+    };
+    worktree?: {
+        branch: string;
+        base?: string;
+    };
+    args?: string[];
+    env?: Record<string, string>;
+    timeoutMs?: number;
+};
+export type PromptReceipt = {
+    paneId: string;
+    terminalId: string;
+    revision: number;
+    status: AgentStatus;
+};
+export type BlockedAgent = {
+    paneId: string;
+    workspaceId: string;
+    tabId: string;
+    kind?: string;
+    revision: number;
+    prompt: string;
+    since: number;
+};
+export type HerdrSnapshot = {
+    connected: boolean;
+    workspaces: {
+        id: string;
+        label: string;
+        tabs: {
+            id: string;
+            label: string;
+            panes: {
+                id: string;
+                cwd?: string;
+                agent?: {
+                    kind?: string;
+                    name?: string;
+                    status: AgentStatus;
+                    revision: number;
+                    launchPending?: boolean;
+                    interactiveReady?: boolean;
+                };
+            }[];
+        }[];
+    }[];
+};
+export type TerminalSession = {
+    ready: Promise<void>;
+    onFrame(fn: (line: string) => void): () => void;
+    send(line: string): void;
+    close(): void;
+    pause(): void;
+    resume(): void;
+    exited: Promise<{
+        code: number | null;
+        stderrTail: string;
+    }>;
+};

package/dist/types.js

@@ -0,0 +1,3 @@
+// The kit's public types (docs/runtime-kits.md 6.2). H1 freezes these signatures; the generated method table (H2)
+// replaces the placeholder pass-through types below without changing any signature.
+export {};

package/dist/words.d.ts

@@ -0,0 +1,10 @@
+import WORDS from './words.json' with { type: 'json' };
+import type { AgentStatus, HerdrState } from './types.ts';
+export type WordKey = keyof typeof WORDS;
+export { WORDS };
+/** A sentence with its `{slots}` filled. */
+export declare const words: (key: WordKey, vars?: Record<string, string>) => string;
+/** The sentence for a kit state; a stopped kit has nothing to say yet. */
+export declare const stateWords: (s: HerdrState) => string;
+/** The sentence for an agent's status. */
+export declare const agentWords: (s: AgentStatus | "starting") => string;

package/dist/words.js

@@ -0,0 +1,18 @@
+// Every sentence a person can see, in one file other languages can read too (words.json, table 6.9). Plain words
+// only: no commands, paths, model ids or error codes (docs/runtime-kits.md 4.3); H8's words test holds the line.
+import WORDS from './words.json' with { type: 'json' };
+export { WORDS };
+/** A sentence with its `{slots}` filled. */
+export const words = (key, vars = {}) => WORDS[key].replace(/\{(\w+)\}/g, (_, k) => vars[k] ?? `{${k}}`);
+const PHASE_KEY = {
+    connecting: 'herdr.connecting', ready: 'herdr.ready', reconnecting: 'herdr.reconnecting',
+    'needs-update': 'herdr.needsUpdate', missing: 'herdr.missing', failed: 'herdr.failed',
+};
+/** The sentence for a kit state; a stopped kit has nothing to say yet. */
+export const stateWords = (s) => (s.phase === 'stopped' ? '' : words(PHASE_KEY[s.phase]));
+const STATUS_KEY = {
+    starting: 'agent.starting', idle: 'agent.idle', working: 'agent.working',
+    blocked: 'agent.blocked', done: 'agent.done', unknown: 'agent.unknown',
+};
+/** The sentence for an agent's status. */
+export const agentWords = (s) => words(STATUS_KEY[s]);

package/dist/words.json

@@ -0,0 +1,19 @@
+{
+    "herdr.missing": "This computer needs Herdr installed first.",
+    "herdr.connecting": "Connecting to Herdr…",
+    "herdr.ready": "Connected to Herdr.",
+    "herdr.reconnecting": "Herdr isn't answering. Trying again by itself.",
+    "herdr.needsUpdate": "Herdr on this computer needs an update to work with this app.",
+    "herdr.failed": "Herdr couldn't start on this computer. Restart the app to try again.",
+    "agent.starting": "Starting…",
+    "agent.idle": "Ready for you.",
+    "agent.working": "Working.",
+    "agent.blocked": "Waiting for your answer.",
+    "agent.done": "Finished.",
+    "agent.unknown": "Running.",
+    "agent.signIn": "Sign in inside {agent}: follow its own steps on the screen.",
+    "agent.notReady": "This helper isn't ready yet. Try again in a moment.",
+    "approval.stale": "That question already changed. Look again before answering.",
+    "close.wouldWiden": "Closing this would close more than you picked. Close the bigger one instead.",
+    "link.notAllowed": "This device can't do that. Ask the person at the computer."
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@byokit/herdr",
+  "version": "0.1.0-next.dbe7142",
+  "description": "Drive the Herdr on this computer — workspaces, tabs, panes, agents and blocked-approval answers — from an app, or hand it to a phone over @byokit/link.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/umeranjum17/byokit.git",
+    "directory": "packages/herdr"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./device": {
+      "react-native": {
+        "types": "./dist/device.d.ts",
+        "default": "./dist/device.js"
+      },
+      "browser": {
+        "types": "./dist/device.d.ts",
+        "default": "./dist/device.js"
+      },
+      "types": "./dist/device.d.ts",
+      "default": "./dist/device.js"
+    },
+    "./link": {
+      "types": "./dist/link.d.ts",
+      "default": "./dist/link.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
+  },
+  "dependencies": {
+    "@byokit/link": "0.3.1",
+    "@byokit/relay": "0.1.3",
+    "@byokit/reach": "0.2.0",
+    "@byokit/seal": "0.1.0",
+    "ws": "8.21.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}