@byokit/herdr 0.1.0-next.dbe7142

package/dist/close.js

@@ -0,0 +1,85 @@
+const codeOf = (error) => {
+    const code = error?.code;
+    if (typeof code === 'string')
+        return code;
+    return /herdr: ([a-z0-9_]+):/i.exec(error instanceof Error ? error.message : String(error))?.[1];
+};
+const fail = (code, message) => Object.assign(new Error(message), { code });
+const unavailable = (kind) => fail(`${kind}-unavailable`, `That ${kind} is no longer available.`);
+const count = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
+export async function closePane(call, paneId) {
+    let tabId;
+    try {
+        const made = (await call('pane.get', { pane_id: paneId }));
+        tabId = made?.pane?.tab_id;
+    }
+    catch (error) {
+        if (codeOf(error) === 'pane_not_found')
+            throw unavailable('pane');
+        throw error;
+    }
+    if (typeof tabId !== 'string')
+        throw unavailable('pane');
+    let paneCount = 0;
+    try {
+        const made = (await call('tab.get', { tab_id: tabId }));
+        paneCount = count(made?.tab?.pane_count);
+    }
+    catch (error) {
+        if (codeOf(error) === 'tab_not_found')
+            throw unavailable('pane');
+        throw error;
+    }
+    if (paneCount <= 1)
+        throw fail('pane-close-would-widen', 'Closing this pane would close its tab; close the tab instead.');
+    await call('pane.close', { pane_id: paneId });
+}
+export async function closeTab(call, tabId) {
+    let workspaceId;
+    try {
+        const made = (await call('tab.get', { tab_id: tabId }));
+        workspaceId = made?.tab?.workspace_id;
+    }
+    catch (error) {
+        if (codeOf(error) === 'tab_not_found')
+            throw unavailable('tab');
+        throw error;
+    }
+    if (typeof workspaceId !== 'string')
+        throw unavailable('tab');
+    let tabCount = 0;
+    try {
+        const made = (await call('workspace.get', { workspace_id: workspaceId }));
+        tabCount = count(made?.workspace?.tab_count);
+    }
+    catch (error) {
+        if (codeOf(error) === 'workspace_not_found')
+            throw unavailable('tab');
+        throw error;
+    }
+    if (tabCount <= 1)
+        throw fail('tab-close-would-widen', 'Closing this tab would close its workspace; close the workspace instead.');
+    await call('tab.close', { tab_id: tabId });
+}
+export async function closeWorkspace(call, workspaceId) {
+    let worktree;
+    try {
+        const made = (await call('workspace.get', { workspace_id: workspaceId }));
+        worktree = made?.workspace?.worktree;
+    }
+    catch (error) {
+        if (codeOf(error) === 'workspace_not_found')
+            throw unavailable('workspace');
+        throw error;
+    }
+    // The root of a worktree group — a non-linked checkout whose repo key a linked one shares — widens.
+    if (worktree?.is_linked_worktree === false && typeof worktree.repo_key === 'string') {
+        const made = (await call('workspace.list', {}));
+        const group = (Array.isArray(made?.workspaces) ? made.workspaces : [])
+            .filter((w) => w?.worktree?.repo_key === worktree.repo_key).length;
+        if (group >= 2) {
+            throw fail('workspace-close-would-widen', 'Closing this workspace would close its worktree group; close the linked checkouts instead.');
+        }
+    }
+    await call('workspace.close', { workspace_id: workspaceId });
+}

package/dist/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const HERDR_VERSION = "0.9.1";
+export declare const HERDR_PROTOCOL: number;

package/dist/constants.js

@@ -0,0 +1,5 @@
+// The pinned Herdr release (docs/runtime-kits.md D5) and the protocol this kit speaks.
+export const HERDR_VERSION = '0.9.1';
+// From the v0.9.1 schema snapshot (schema/herdr-api-0.9.1.json, docs/runtime-kits.md 6.7);
+// regenerated by scripts/gen-types.ts and pinned by test/generated.test.ts.
+export const HERDR_PROTOCOL = 22;

package/dist/device.d.ts

@@ -0,0 +1,40 @@
+import type { DeviceLink } from '@byokit/link';
+import type { AgentRef, BlockedAgent, HerdrSnapshot, HerdrState, PromptReceipt, StartAgent } from './types.ts';
+export { openNotice } from './notices.ts';
+export declare function herdrDevice(link: DeviceLink): {
+    state(): Promise<{
+        state: HerdrState;
+        words: string;
+    }>;
+    tree(): Promise<HerdrSnapshot>;
+    startAgent(o: StartAgent): Promise<AgentRef>;
+    prompt(paneId: string, text: string): Promise<PromptReceipt>;
+    keys(paneId: string, keys: string[]): Promise<void>;
+    read(paneId: string, o?: {
+        source?: 'visible' | 'recent' | 'recent_unwrapped' | 'detection';
+        lines?: number;
+    }): Promise<{
+        text: string;
+        truncated: boolean;
+    }>;
+    blocked(): Promise<BlockedAgent[]>;
+    answer(paneId: string, keys: string[], revision: number): Promise<void>;
+    close(o: {
+        pane?: string;
+        tab?: string;
+        workspace?: string;
+    }): Promise<void>;
+    events(): AsyncIterable<unknown>;
+    registerNotices(seed: Uint8Array): Promise<void>;
+    openNotice(data: Record<string, unknown>, seed: Uint8Array): BlockedAgent | null;
+    call(method: string, params?: unknown): Promise<unknown>;
+    terminal(paneId: string, o: {
+        mode: 'control' | 'observe';
+        cols: number;
+        rows: number;
+    }): {
+        onFrame(fn: (line: string) => void): () => void;
+        send(line: string): void;
+        close(): void;
+    };
+};

package/dist/device.js

@@ -0,0 +1,128 @@
+export { openNotice } from "./notices.js";
+import { boxPublicKeyB64, openNotice } from "./notices.js";
+const decodeLines = () => {
+    const text = new TextDecoder();
+    let pending = '';
+    return {
+        push: (chunk) => {
+            pending += text.decode(chunk, { stream: true });
+            const lines = pending.split('\n');
+            pending = lines.pop() ?? '';
+            return lines.filter((line) => line.length > 0);
+        },
+        flush: () => {
+            pending += text.decode();
+            const rest = pending;
+            pending = '';
+            return rest.length > 0 ? [rest] : [];
+        },
+    };
+};
+/** A link stream as newline-delimited JSON frames; unparsed lines surface as `{ type: 'raw', line }`. */
+async function* streamFrames(link, op, args) {
+    const s = await link.stream(op, args);
+    const ready = [];
+    let wake;
+    let ended = false;
+    const lines = decodeLines();
+    const emit = (frame) => {
+        ready.push(frame);
+        wake?.();
+        wake = undefined;
+    };
+    s.onData = (chunk) => {
+        for (const line of lines.push(chunk)) {
+            try {
+                emit(JSON.parse(line));
+            }
+            catch {
+                emit({ type: 'raw', line });
+            }
+        }
+    };
+    s.onEnd = () => {
+        for (const line of lines.flush())
+            emit({ type: 'raw', line });
+        ended = true;
+        wake?.();
+        wake = undefined;
+    };
+    for (;;) {
+        while (ready.length > 0)
+            yield ready.shift();
+        if (ended)
+            return;
+        await new Promise((resolve) => { wake = resolve; });
+    }
+}
+const terminalHandle = (opening) => {
+    const listeners = new Set();
+    const lines = decodeLines();
+    let s;
+    const queued = [];
+    let dead = false;
+    // The frozen H7 signature returns the handle synchronously; the stream opens underneath and
+    // sends made before it opens queue until then (frames cannot arrive before the open anyway).
+    opening.then((opened) => {
+        if (dead) {
+            opened.end();
+            return;
+        }
+        s = opened;
+        opened.onData = (chunk) => {
+            for (const line of lines.push(chunk)) {
+                for (const fn of listeners)
+                    fn(line);
+            }
+        };
+        opened.onEnd = () => {
+            for (const line of lines.flush()) {
+                for (const fn of listeners)
+                    fn(line);
+            }
+        };
+        for (const line of queued.splice(0))
+            void opened.write(`${line}\n`).catch(() => { });
+    }, () => { dead = true; });
+    return {
+        onFrame: (fn) => {
+            listeners.add(fn);
+            return () => { listeners.delete(fn); };
+        },
+        send: (line) => {
+            if (s !== undefined)
+                void s.write(`${line}\n`).catch(() => { });
+            else if (!dead)
+                queued.push(line);
+        },
+        close: () => { dead = true; s?.end(); },
+    };
+};
+export function herdrDevice(link) {
+    if (!link)
+        throw new Error('herdr: herdrDevice needs a link');
+    return {
+        state: () => link.request('hd.state', {}),
+        tree: () => link.request('hd.tree', {}),
+        startAgent: (o) => link.request('hd.agent.start', o),
+        prompt: (paneId, text) => link.request('hd.prompt', { paneId, text }),
+        keys: async (paneId, keys) => {
+            await link.request('hd.keys', { paneId, keys });
+        },
+        read: (paneId, o) => link.request('hd.read', { paneId, ...o }),
+        blocked: () => link.request('hd.blocked', {}),
+        answer: async (paneId, keys, revision) => {
+            await link.request('hd.answer', { paneId, keys, revision });
+        },
+        close: async (o) => {
+            await link.request('hd.close', o);
+        },
+        events: () => streamFrames(link, 'hd.events', {}),
+        registerNotices: async (seed) => {
+            await link.request('hd.notices.register', { boxPublicKey: boxPublicKeyB64(seed) });
+        },
+        openNotice: (data, seed) => openNotice(data, seed),
+        call: (method, params) => link.request('hd.call', { method, params }),
+        terminal: (paneId, o) => terminalHandle(link.stream('hd.terminal', { paneId, ...o })),
+    };
+}

package/dist/generated/events.d.ts

@@ -0,0 +1,371 @@
+export interface HerdrEvents {
+    'layout.updated': LayoutUpdatedData;
+    'pane.agent_detected': PaneAgentDetectedData;
+    'pane.agent_status_changed': PaneAgentStatusChangedEvent;
+    'pane.closed': PaneClosedData;
+    'pane.created': PaneCreatedData;
+    'pane.exited': PaneExitedData;
+    'pane.focused': PaneFocusedData;
+    'pane.moved': PaneMovedData;
+    'pane.output_matched': PaneOutputMatchedEvent;
+    'pane.scroll_changed': PaneScrollChangedEvent;
+    'pane.updated': PaneUpdatedData;
+    'tab.closed': TabClosedData;
+    'tab.created': TabCreatedData;
+    'tab.focused': TabFocusedData;
+    'tab.moved': TabMovedData;
+    'tab.renamed': TabRenamedData;
+    'workspace.closed': WorkspaceClosedData;
+    'workspace.created': WorkspaceCreatedData;
+    'workspace.focused': WorkspaceFocusedData;
+    'workspace.metadata_updated': WorkspaceMetadataUpdatedData;
+    'workspace.moved': WorkspaceMovedData;
+    'workspace.renamed': WorkspaceRenamedData;
+    'workspace.reordered': WorkspaceReorderedData;
+    'workspace.updated': WorkspaceUpdatedData;
+    'worktree.created': WorktreeCreatedData;
+    'worktree.opened': WorktreeOpenedData;
+    'worktree.removed': WorktreeRemovedData;
+}
+export interface HerdrEventFilters {
+    'pane.agent_status_changed': PaneAgentStatusChangedFilter;
+    'pane.output_matched': PaneOutputMatchedFilter;
+    'pane.scroll_changed': PaneScrollChangedFilter;
+}
+export type HerdrEventName = keyof HerdrEvents;
+export type HerdrEventOf<E extends HerdrEventName> = HerdrEvents[E];
+export type HerdrSubscription<E extends HerdrEventName = HerdrEventName> = {
+    type: E;
+} & (E extends keyof HerdrEventFilters ? HerdrEventFilters[E] : unknown);
+export type SplitDirection = "right" | "down";
+export type AgentStatus = "idle" | "working" | "blocked" | "done" | "unknown";
+export type AgentSessionRefKind = "id" | "path";
+export type ReadFormat = "text" | "ansi";
+export type ReadSource = "visible" | "recent" | "recent_unwrapped" | "detection";
+export type OutputMatch = {
+    type: "substring";
+    value: string;
+    [k: string]: unknown;
+} | {
+    type: "regex";
+    value: string;
+    [k: string]: unknown;
+};
+export interface LayoutUpdatedData {
+    layout: EventPaneLayoutSnapshot;
+    type: "layout_updated";
+    [k: string]: unknown;
+}
+export interface EventPaneLayoutSnapshot {
+    area: PaneLayoutRect;
+    focused_pane_id: string;
+    panes: EventPaneLayoutPane[];
+    splits: EventPaneLayoutSplit[];
+    tab_id: string;
+    workspace_id: string;
+    zoomed: boolean;
+    [k: string]: unknown;
+}
+export interface PaneLayoutRect {
+    height: number;
+    width: number;
+    x: number;
+    y: number;
+    [k: string]: unknown;
+}
+export interface EventPaneLayoutPane {
+    focused: boolean;
+    pane_id: string;
+    rect: PaneLayoutRect;
+    [k: string]: unknown;
+}
+export interface EventPaneLayoutSplit {
+    direction: SplitDirection;
+    id: string;
+    ratio: number;
+    rect: PaneLayoutRect;
+    [k: string]: unknown;
+}
+export interface PaneAgentDetectedData {
+    agent?: string | null;
+    final_status?: AgentStatus | null;
+    pane_id: string;
+    released?: boolean;
+    type: "pane_agent_detected";
+    workspace_id: string;
+    [k: string]: unknown;
+}
+export interface PaneAgentStatusChangedEvent {
+    agent?: string | null;
+    agent_status: AgentStatus;
+    display_agent?: string | null;
+    pane_id: string;
+    state_labels?: {
+        [k: string]: string;
+    };
+    title?: string | null;
+    workspace_id: string;
+    [k: string]: unknown;
+}
+export interface PaneAgentStatusChangedFilter {
+    agent_status?: AgentStatus | null;
+    pane_id: string;
+    [k: string]: unknown;
+}
+export interface PaneClosedData {
+    pane_id: string;
+    type: "pane_closed";
+    workspace_id: string;
+    [k: string]: unknown;
+}
+export interface PaneCreatedData {
+    pane: EventPaneInfo;
+    type: "pane_created";
+    [k: string]: unknown;
+}
+export interface EventPaneInfo {
+    agent?: string | null;
+    agent_session?: EventAgentSessionInfo | null;
+    agent_status: AgentStatus;
+    cwd?: string | null;
+    display_agent?: string | null;
+    focused: boolean;
+    foreground_cwd?: string | null;
+    label?: string | null;
+    pane_id: string;
+    revision: number;
+    scroll?: PaneScrollInfo | null;
+    state_labels?: {
+        [k: string]: string;
+    };
+    tab_id: string;
+    terminal_id: string;
+    terminal_title?: string | null;
+    terminal_title_stripped?: string | null;
+    title?: string | null;
+    tokens?: {
+        [k: string]: string;
+    };
+    workspace_id: string;
+    [k: string]: unknown;
+}
+export interface EventAgentSessionInfo {
+    agent: string;
+    kind: AgentSessionRefKind;
+    source: string;
+    value: string;
+    [k: string]: unknown;
+}
+export interface PaneScrollInfo {
+    max_offset_from_bottom: number;
+    offset_from_bottom: number;
+    viewport_rows: number;
+    [k: string]: unknown;
+}
+export interface PaneExitedData {
+    pane_id: string;
+    type: "pane_exited";
+    workspace_id: string;
+    [k: string]: unknown;
+}
+export interface PaneFocusedData {
+    pane_id: string;
+    type: "pane_focused";
+    workspace_id: string;
+    [k: string]: unknown;
+}
+export interface PaneMovedData {
+    closed_tab_id?: string | null;
+    closed_workspace_id?: string | null;
+    created_tab?: EventTabInfo | null;
+    created_workspace?: EventWorkspaceInfo | null;
+    pane: EventPaneInfo;
+    previous_pane_id: string;
+    previous_tab_id: string;
+    previous_workspace_id: string;
+    type: "pane_moved";
+    [k: string]: unknown;
+}
+export interface EventTabInfo {
+    agent_status: AgentStatus;
+    focused: boolean;
+    label: string;
+    number: number;
+    pane_count: number;
+    tab_id: string;
+    workspace_id: string;
+    [k: string]: unknown;
+}
+export interface EventWorkspaceInfo {
+    active_tab_id: string;
+    agent_status: AgentStatus;
+    focused: boolean;
+    label: string;
+    number: number;
+    pane_count: number;
+    tab_count: number;
+    tokens?: {
+        [k: string]: string;
+    };
+    workspace_id: string;
+    worktree?: WorkspaceWorktreeInfo | null;
+    [k: string]: unknown;
+}
+export interface WorkspaceWorktreeInfo {
+    checkout_path: string;
+    is_linked_worktree: boolean;
+    repo_key: string;
+    repo_name: string;
+    repo_root: string;
+    [k: string]: unknown;
+}
+export interface PaneOutputMatchedEvent {
+    matched_line: string;
+    pane_id: string;
+    read: SubscriptionPaneReadResult;
+    [k: string]: unknown;
+}
+export interface SubscriptionPaneReadResult {
+    format: ReadFormat;
+    pane_id: string;
+    revision: number;
+    source: ReadSource;
+    tab_id: string;
+    text: string;
+    truncated: boolean;
+    workspace_id: string;
+    [k: string]: unknown;
+}
+export interface PaneOutputMatchedFilter {
+    lines?: number | null;
+    match: OutputMatch;
+    pane_id: string;
+    source: ReadSource;
+    strip_ansi?: boolean;
+    [k: string]: unknown;
+}
+export interface PaneScrollChangedEvent {
+    pane_id: string;
+    scroll: PaneScrollInfo;
+    workspace_id: string;
+    [k: string]: unknown;
+}
+export interface PaneScrollChangedFilter {
+    pane_id: string;
+    [k: string]: unknown;
+}
+export interface PaneUpdatedData {
+    pane: EventPaneInfo;
+    type: "pane_updated";
+    [k: string]: unknown;
+}
+export interface TabClosedData {
+    tab_id: string;
+    type: "tab_closed";
+    workspace_id: string;
+    [k: string]: unknown;
+}
+export interface TabCreatedData {
+    tab: EventTabInfo;
+    type: "tab_created";
+    [k: string]: unknown;
+}
+export interface TabFocusedData {
+    tab_id: string;
+    type: "tab_focused";
+    workspace_id: string;
+    [k: string]: unknown;
+}
+export interface TabMovedData {
+    insert_index: number;
+    tab_id: string;
+    tabs: EventTabInfo[];
+    type: "tab_moved";
+    workspace_id: string;
+    [k: string]: unknown;
+}
+export interface TabRenamedData {
+    label: string;
+    tab_id: string;
+    type: "tab_renamed";
+    workspace_id: string;
+    [k: string]: unknown;
+}
+export interface WorkspaceClosedData {
+    type: "workspace_closed";
+    workspace?: EventWorkspaceInfo | null;
+    workspace_id: string;
+    [k: string]: unknown;
+}
+export interface WorkspaceCreatedData {
+    type: "workspace_created";
+    workspace: EventWorkspaceInfo;
+    [k: string]: unknown;
+}
+export interface WorkspaceFocusedData {
+    type: "workspace_focused";
+    workspace_id: string;
+    [k: string]: unknown;
+}
+export interface WorkspaceMetadataUpdatedData {
+    type: "workspace_metadata_updated";
+    workspace: EventWorkspaceInfo;
+    [k: string]: unknown;
+}
+export interface WorkspaceMovedData {
+    insert_index: number;
+    type: "workspace_moved";
+    workspace_id: string;
+    workspaces: EventWorkspaceInfo[];
+    [k: string]: unknown;
+}
+export interface WorkspaceRenamedData {
+    label: string;
+    type: "workspace_renamed";
+    workspace_id: string;
+    [k: string]: unknown;
+}
+export interface WorkspaceReorderedData {
+    before_workspace_id?: string | null;
+    type: "workspace_reordered";
+    workspace_ids: string[];
+    workspaces: EventWorkspaceInfo[];
+    [k: string]: unknown;
+}
+export interface WorkspaceUpdatedData {
+    type: "workspace_updated";
+    workspace: EventWorkspaceInfo;
+    [k: string]: unknown;
+}
+export interface WorktreeCreatedData {
+    type: "worktree_created";
+    workspace: EventWorkspaceInfo;
+    worktree: WorktreeInfo;
+    [k: string]: unknown;
+}
+export interface WorktreeInfo {
+    branch?: string | null;
+    is_bare: boolean;
+    is_detached: boolean;
+    is_linked_worktree: boolean;
+    is_prunable: boolean;
+    label: string;
+    open_workspace_id?: string | null;
+    path: string;
+    [k: string]: unknown;
+}
+export interface WorktreeOpenedData {
+    already_open: boolean;
+    type: "worktree_opened";
+    workspace: EventWorkspaceInfo;
+    worktree: WorktreeInfo;
+    [k: string]: unknown;
+}
+export interface WorktreeRemovedData {
+    forced: boolean;
+    type: "worktree_removed";
+    workspace?: EventWorkspaceInfo | null;
+    workspace_id: string;
+    worktree: WorktreeInfo;
+    [k: string]: unknown;
+}

package/dist/generated/events.js

@@ -0,0 +1,3 @@
+// Generated by scripts/gen-types.ts from schema/herdr-api-0.9.1.json (docs/runtime-kits.md 6.7) — do not edit.
+// Event table: subscription kind to payload; filtered kinds carry their filter fields.
+export {};