@theaileverage/marionette 0.2.1 → 0.2.2

package/dist/herdr-protocol.js

@@ -0,0 +1,108 @@
+// Generated from Herdr 0.9.0 (Apache-2.0); see vendor/herdr-0.9.0/LICENSE.
+// Do not edit. Run npm run sdk:generate.
+export const HERDR_PROTOCOL = 22;
+export const HERDR_SCHEMA_SHA256 = '5fb46b13fdaf39c88cf699b9806685868c7ee6b0142523d84391b1606416dc0a';
+export const HERDR_METHODS = [
+    'ping',
+    'server.stop',
+    'server.live_handoff',
+    'server.reload_config',
+    'server.agent_manifests',
+    'server.reload_agent_manifests',
+    'notification.show',
+    'product_announcement.dismiss',
+    'release_notes.dismiss',
+    'command.invoke',
+    'client.window_title.set',
+    'client.window_title.clear',
+    'client_shell.surface.set',
+    'session.snapshot',
+    'workspace.create',
+    'workspace.list',
+    'workspace.get',
+    'workspace.focus',
+    'workspace.rename',
+    'workspace.move',
+    'workspace.move_block',
+    'workspace.report_metadata',
+    'workspace.close',
+    'worktree.list',
+    'worktree.create',
+    'worktree.open',
+    'worktree.remove',
+    'tab.create',
+    'tab.list',
+    'tab.get',
+    'tab.focus',
+    'tab.rename',
+    'tab.move',
+    'tab.close',
+    'agent.list',
+    'agent.get',
+    'agent.read',
+    'agent.explain',
+    'agent.send_keys',
+    'agent.rename',
+    'agent.view.set',
+    'agent.view.clear',
+    'agent.focus',
+    'agent.start',
+    'agent.prompt',
+    'agent.wait',
+    'pane.split',
+    'pane.swap',
+    'pane.move',
+    'pane.zoom',
+    'pane.layout',
+    'pane.process_info',
+    'layout.export',
+    'layout.apply',
+    'layout.set_split_ratio',
+    'pane.neighbor',
+    'pane.edges',
+    'pane.focus_direction',
+    'pane.resize',
+    'pane.scroll',
+    'pane.edit_scrollback',
+    'pane.selection.read',
+    'pane.copy_motion',
+    'pane.copy_search',
+    'pane.list',
+    'pane.current',
+    'pane.get',
+    'pane.focus',
+    'pane.input.set',
+    'pane.link.activate',
+    'pane.rename',
+    'pane.send_text',
+    'pane.send_keys',
+    'pane.send_input',
+    'pane.read',
+    'pane.graphics.set',
+    'pane.graphics.clear',
+    'pane.graphics.info',
+    'pane.report_agent',
+    'pane.report_agent_session',
+    'pane.report_metadata',
+    'pane.clear_agent_authority',
+    'pane.release_agent',
+    'pane.close',
+    'popup.close',
+    'events.subscribe',
+    'events.wait',
+    'pane.wait_for_output',
+    'integration.list',
+    'integration.install',
+    'integration.uninstall',
+    'plugin.link',
+    'plugin.list',
+    'plugin.unlink',
+    'plugin.enable',
+    'plugin.disable',
+    'plugin.action.list',
+    'plugin.action.invoke',
+    'plugin.log.list',
+    'plugin.pane.open',
+    'plugin.pane.focus',
+    'plugin.pane.close',
+];

package/dist/herdr-sdk.d.ts

@@ -0,0 +1,105 @@
+import { type HerdrMethod, type HerdrParams, type HerdrResult, type ResponseTypes, type RequestTypes } from './herdr-protocol.js';
+import { HerdrEventStream, HerdrGraphicsStream, type GraphicsStreamParams } from './herdr-streams.js';
+import { type RequestOptions, type StreamOptions } from './herdr-transport.js';
+export * from './herdr-protocol.js';
+export { HerdrError } from './herdr-transport.js';
+export type { RequestOptions, StreamOptions } from './herdr-transport.js';
+export { HerdrEventStream, HerdrGraphicsStream } from './herdr-streams.js';
+export type { GraphicsStreamParams, GraphicsFrame, GraphicsFileFrame, GraphicsFrameAck, } from './herdr-streams.js';
+export type Pane = ResponseTypes.PaneInfo;
+export type Agent = ResponseTypes.AgentInfo;
+export type PaneLayout = ResponseTypes.PaneLayoutSnapshot;
+export type RequestMethod = Exclude<HerdrMethod, 'events.subscribe'>;
+export type RequestArgs<M extends RequestMethod> = {} extends HerdrParams[M] ? [params?: HerdrParams[M], options?: RequestOptions] : [params: HerdrParams[M], options?: RequestOptions];
+export type HerdrApi = {
+    readonly [M in RequestMethod]: (...args: RequestArgs<M>) => Promise<HerdrResult>;
+} & {
+    readonly 'events.subscribe': (params: HerdrParams['events.subscribe'], options?: StreamOptions) => Promise<HerdrEventStream>;
+    readonly 'pane.graphics.stream': (params: GraphicsStreamParams, options?: StreamOptions) => Promise<HerdrGraphicsStream>;
+};
+export interface LaunchOptions {
+    cwd: string;
+    env?: Record<string, string>;
+    focus?: boolean;
+}
+export interface WaitOptions {
+    timeout_ms: number;
+    until?: ('idle' | 'working' | 'blocked' | 'done' | 'unknown')[];
+}
+/** Explicit connection selection, typed wire APIs, and small convenience helpers. */
+export declare class HerdrClient {
+    readonly socketPath: string;
+    constructor(socketPath: string);
+    static fromEnv(env?: NodeJS.ProcessEnv): HerdrClient;
+    /** Escape hatch for future one-shot methods. Streams require their dedicated transports. */
+    call<T = unknown>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+    /** All schema-defined one-shot methods with exact typed parameter objects. */
+    request<M extends RequestMethod>(method: M, ...args: RequestArgs<M>): Promise<HerdrResult>;
+    subscribe(subscriptions: RequestTypes.Subscription[], options?: StreamOptions): Promise<HerdrEventStream>;
+    graphicsStream(params: GraphicsStreamParams, options?: StreamOptions): Promise<HerdrGraphicsStream>;
+    /** One-to-one method names, including streams, for discovery and generated agent code. */
+    readonly api: HerdrApi;
+    readonly workspace: {
+        list: () => Promise<{
+            workspaces: {
+                workspace_id: string;
+                label?: string;
+            }[];
+        }>;
+        create: (options: LaunchOptions & {
+            label: string;
+        }) => Promise<{
+            root_pane: Pane;
+            workspace: {
+                workspace_id: string;
+            };
+        }>;
+    };
+    readonly tab: {
+        create: (workspaceId: string, options: LaunchOptions & {
+            label?: string;
+        }) => Promise<{
+            root_pane: Pane;
+        }>;
+        list: (workspaceId: string) => Promise<{
+            tabs: {
+                tab_id: string;
+                workspace_id: string;
+                label?: string;
+                pane_count: number;
+            }[];
+        }>;
+        close: (tabId: string) => Promise<unknown>;
+    };
+    readonly pane: {
+        list: (workspaceId: string) => Promise<{
+            panes: Pane[];
+        }>;
+        layout: (paneId: string) => Promise<{
+            layout: PaneLayout;
+        }>;
+        split: (paneId: string, options: LaunchOptions & {
+            direction: "right" | "down";
+            ratio?: number;
+        }) => Promise<{
+            pane: Pane;
+        }>;
+        read: (paneId: string, lines?: number) => Promise<{
+            read: {
+                text: string;
+            };
+        }>;
+        sendText: (paneId: string, text: string) => Promise<unknown>;
+        sendKeys: (paneId: string, keys: string[]) => Promise<unknown>;
+        close: (paneId: string) => Promise<unknown>;
+    };
+    readonly agent: {
+        start: (paneId: string, name: string, kind: string, args?: string[], timeoutMs?: number) => Promise<unknown>;
+        get: (target: string) => Promise<{
+            agent: Agent;
+        }>;
+        prompt: (target: string, text: string, wait?: WaitOptions) => Promise<unknown>;
+        wait: (target: string, options: WaitOptions) => Promise<unknown>;
+        sendKeys: (target: string, keys: string[]) => Promise<unknown>;
+    };
+}

package/dist/herdr-sdk.js

@@ -0,0 +1,105 @@
+import { HERDR_METHODS, } from './herdr-protocol.js';
+import { HerdrEventStream, HerdrGraphicsStream, } from './herdr-streams.js';
+import { socketRequest, validateSocketPath, } from './herdr-transport.js';
+export * from './herdr-protocol.js';
+export { HerdrError } from './herdr-transport.js';
+export { HerdrEventStream, HerdrGraphicsStream } from './herdr-streams.js';
+/** Respect server waits; the transport must not time out an otherwise valid long wait. */
+function deadline(method, params) {
+    if (method === 'agent.start')
+        return (params.timeout_ms ?? 30000) + 5000;
+    const wait = method === 'agent.prompt'
+        ? params.wait
+        : ['agent.wait', 'events.wait', 'pane.wait_for_output'].includes(method)
+            ? params
+            : undefined;
+    if (wait)
+        return wait.timeout_ms == null ? null : wait.timeout_ms + 5000;
+    return 10000;
+}
+/** Explicit connection selection, typed wire APIs, and small convenience helpers. */
+export class HerdrClient {
+    socketPath;
+    constructor(socketPath) {
+        this.socketPath = socketPath;
+        validateSocketPath(socketPath);
+    }
+    static fromEnv(env = process.env) {
+        if (env.HERDR_ENV !== '1' || !env.HERDR_SOCKET_PATH)
+            throw new Error('Run inside Herdr or supply an explicitly selected socket path');
+        return new HerdrClient(env.HERDR_SOCKET_PATH);
+    }
+    /** Escape hatch for future one-shot methods. Streams require their dedicated transports. */
+    call(method, params = {}, timeoutMs = 10000) {
+        if (method === 'events.subscribe' || method === 'pane.graphics.stream')
+            return Promise.reject(new TypeError('Use subscribe(), graphicsStream(), or api for a streaming method'));
+        return socketRequest(this.socketPath, method, params, { timeoutMs });
+    }
+    /** All schema-defined one-shot methods with exact typed parameter objects. */
+    request(method, ...args) {
+        const [params = {}, options = {}] = args;
+        if (!HERDR_METHODS.includes(method) ||
+            method === 'events.subscribe')
+            return Promise.reject(new TypeError('Unknown one-shot method; use call() for extensions or subscribe() for events'));
+        return socketRequest(this.socketPath, method, params, {
+            ...options,
+            timeoutMs: options.timeoutMs === undefined ? deadline(method, params) : options.timeoutMs,
+        });
+    }
+    subscribe(subscriptions, options) {
+        return HerdrEventStream.open(this.socketPath, subscriptions, options);
+    }
+    graphicsStream(params, options) {
+        return HerdrGraphicsStream.open(this.socketPath, params, options);
+    }
+    /** One-to-one method names, including streams, for discovery and generated agent code. */
+    api = Object.freeze(Object.fromEntries([
+        ...HERDR_METHODS.map((method) => [
+            method,
+            method === 'events.subscribe'
+                ? (params, options) => this.subscribe(params.subscriptions, options)
+                : (params = {}, options) => this.request(method, params, options),
+        ]),
+        [
+            'pane.graphics.stream',
+            (params, options) => this.graphicsStream(params, options),
+        ],
+    ]));
+    workspace = {
+        list: () => this.call('workspace.list'),
+        create: (options) => this.call('workspace.create', {
+            focus: false,
+            ...options,
+        }),
+    };
+    tab = {
+        create: (workspaceId, options) => this.call('tab.create', {
+            focus: false,
+            ...options,
+            workspace_id: workspaceId,
+        }),
+        list: (workspaceId) => this.call('tab.list', { workspace_id: workspaceId }),
+        close: (tabId) => this.call('tab.close', { tab_id: tabId }),
+    };
+    pane = {
+        list: (workspaceId) => this.call('pane.list', { workspace_id: workspaceId }),
+        layout: (paneId) => this.call('pane.layout', { pane_id: paneId }),
+        split: (paneId, options) => this.call('pane.split', { focus: false, ...options, target_pane_id: paneId }),
+        read: (paneId, lines = 120) => this.call('pane.read', {
+            pane_id: paneId,
+            source: 'recent_unwrapped',
+            format: 'text',
+            lines,
+        }),
+        sendText: (paneId, text) => this.call('pane.send_text', { pane_id: paneId, text }),
+        sendKeys: (paneId, keys) => this.call('pane.send_keys', { pane_id: paneId, keys }),
+        close: (paneId) => this.call('pane.close', { pane_id: paneId }),
+    };
+    agent = {
+        start: (paneId, name, kind, args = [], timeoutMs = 30000) => this.call('agent.start', { pane_id: paneId, name, kind, args, timeout_ms: timeoutMs }, timeoutMs + 5000),
+        get: (target) => this.call('agent.get', { target }),
+        prompt: (target, text, wait) => this.call('agent.prompt', { target, text, ...(wait ? { wait } : {}) }, wait ? wait.timeout_ms + 5000 : 10000),
+        wait: (target, options) => this.call('agent.wait', { target, ...options }, options.timeout_ms + 5000),
+        sendKeys: (target, keys) => this.call('agent.send_keys', { target, keys }),
+    };
+}

package/dist/herdr-streams.d.ts

@@ -0,0 +1,49 @@
+import { type StreamOptions } from './herdr-transport.js';
+import type { HerdrEvent, HerdrResult, RequestTypes } from './herdr-protocol.js';
+export declare class HerdrEventStream implements AsyncIterableIterator<HerdrEvent> {
+    private connection;
+    private constructor();
+    static open(socketPath: string, subscriptions: RequestTypes.Subscription[], options?: StreamOptions): Promise<HerdrEventStream>;
+    get closed(): Promise<void>;
+    [Symbol.asyncIterator](): this;
+    next(): Promise<IteratorResult<HerdrEvent>>;
+    close(): void;
+    return(): Promise<IteratorResult<HerdrEvent>>;
+}
+/** This wire method is documented but omitted from Herdr 0.9.0's exported JSON schema. */
+export interface GraphicsStreamParams {
+    pane_id: string;
+    layer_id?: string | null;
+    z_index?: number;
+}
+export interface GraphicsFrame {
+    format: RequestTypes.PaneGraphicsFormat;
+    image_width: number;
+    image_height: number;
+    placement?: RequestTypes.PaneGraphicsPlacementParams;
+}
+export interface GraphicsFileFrame extends Omit<GraphicsFrame, 'format'> {
+    format: 'rgba' | 'bgra';
+    file: {
+        path: string;
+    };
+    sequence: number;
+    revision: number;
+}
+export type GraphicsFrameAck = Extract<HerdrResult, {
+    type: 'pane_graphics_frame_ack';
+}>;
+export declare class HerdrGraphicsStream {
+    private connection;
+    private busy;
+    private constructor();
+    static open(socketPath: string, params: GraphicsStreamParams, options?: StreamOptions): Promise<HerdrGraphicsStream>;
+    /** Resolves after local close; rejects on remote failure, cancellation, or disconnect. */
+    get closed(): Promise<void>;
+    private exclusive;
+    /** Resolves after local socket write, not a render ACK: inline success has no wire reply. */
+    frame(frame: GraphicsFrame, data: Uint8Array, timeoutMs?: number): Promise<void>;
+    /** Keep the immutable source file until this method acknowledges its sequence and revision. */
+    fileFrame(frame: GraphicsFileFrame, timeoutMs?: number): Promise<GraphicsFrameAck>;
+    close(): void;
+}

package/dist/herdr-streams.js

@@ -0,0 +1,156 @@
+import { isAbsolute } from 'node:path';
+import { HerdrError, JsonConnection, validateTimeout, } from './herdr-transport.js';
+export class HerdrEventStream {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    static async open(socketPath, subscriptions, options = {}) {
+        const timeout = options.timeoutMs === undefined ? 10000 : options.timeoutMs;
+        validateTimeout(timeout);
+        JSON.stringify(subscriptions);
+        const connection = new JsonConnection(socketPath, options);
+        try {
+            const result = await connection.start('events.subscribe', { subscriptions }, timeout);
+            if (result?.type !== 'subscription_started')
+                throw new HerdrError('herdr_invalid_response', 'Missing subscription acknowledgement');
+            return new HerdrEventStream(connection);
+        }
+        catch (error) {
+            connection.close();
+            throw error;
+        }
+    }
+    get closed() {
+        return this.connection.closed;
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    async next() {
+        const value = await this.connection.read();
+        if (value === undefined)
+            return { done: true, value: undefined };
+        if (!value || typeof value.event !== 'string' || !Object.hasOwn(value, 'data')) {
+            const error = new HerdrError('herdr_invalid_response', 'Expected a Herdr event envelope');
+            this.connection.fail(error, true);
+            throw error;
+        }
+        return { done: false, value: value };
+    }
+    close() {
+        this.connection.close();
+    }
+    async return() {
+        this.close();
+        return { done: true, value: undefined };
+    }
+}
+const maxInlineBytes = 16 * 1024 * 1024;
+function integer(value, name, min = 0, max = Number.MAX_SAFE_INTEGER) {
+    if (!Number.isSafeInteger(value) || value < min || value > max)
+        throw new TypeError(`Invalid ${name}`);
+}
+function frameHeader(frame) {
+    integer(frame.image_width, 'image_width', 1, 0xffffffff);
+    integer(frame.image_height, 'image_height', 1, 0xffffffff);
+    if (!['png', 'rgb', 'rgba', 'bgra'].includes(frame.format))
+        throw new TypeError('Invalid frame format');
+    return {
+        format: frame.format,
+        image_width: frame.image_width,
+        image_height: frame.image_height,
+        ...(frame.placement ? { placement: frame.placement } : {}),
+    };
+}
+function encodeHeader(header) {
+    const line = JSON.stringify(header) + '\n';
+    if (Buffer.byteLength(line) > 64 * 1024)
+        throw new TypeError('Graphics header exceeds 64 KiB');
+    return line;
+}
+export class HerdrGraphicsStream {
+    connection;
+    busy = false;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    static async open(socketPath, params, options = {}) {
+        const timeout = options.timeoutMs === undefined ? 10000 : options.timeoutMs;
+        validateTimeout(timeout);
+        JSON.stringify(params);
+        const connection = new JsonConnection(socketPath, options);
+        try {
+            const result = await connection.start('pane.graphics.stream', params, timeout);
+            if (result?.type !== 'ok')
+                throw new HerdrError('herdr_invalid_response', 'Missing graphics stream acknowledgement');
+            return new HerdrGraphicsStream(connection);
+        }
+        catch (error) {
+            connection.close();
+            throw error;
+        }
+    }
+    /** Resolves after local close; rejects on remote failure, cancellation, or disconnect. */
+    get closed() {
+        return this.connection.closed;
+    }
+    async exclusive(action) {
+        if (this.busy)
+            throw new HerdrError('herdr_stream_busy', 'Await the previous frame before sending another');
+        this.busy = true;
+        try {
+            return await action();
+        }
+        finally {
+            this.busy = false;
+        }
+    }
+    /** Resolves after local socket write, not a render ACK: inline success has no wire reply. */
+    async frame(frame, data, timeoutMs = 30000) {
+        validateTimeout(timeoutMs);
+        if (!data.byteLength || data.byteLength > maxInlineBytes)
+            throw new TypeError('Inline graphics data must be 1 byte to 16 MiB');
+        const header = encodeHeader({ ...frameHeader(frame), data_length: data.byteLength });
+        return this.exclusive(async () => {
+            // Snapshot bytes before awaiting writes so caller mutation cannot corrupt framing.
+            const bytes = Buffer.from(data);
+            await this.connection.within(timeoutMs, async () => {
+                await this.connection.write(header);
+                await this.connection.write(bytes);
+            });
+        });
+    }
+    /** Keep the immutable source file until this method acknowledges its sequence and revision. */
+    async fileFrame(frame, timeoutMs = 30000) {
+        validateTimeout(timeoutMs);
+        if (!['rgba', 'bgra'].includes(frame.format) || !isAbsolute(frame.file.path))
+            throw new TypeError('File frames require rgba/bgra and an absolute source path');
+        integer(frame.sequence, 'sequence');
+        integer(frame.revision, 'revision');
+        const { sequence, revision } = frame;
+        const header = encodeHeader({
+            ...frameHeader(frame),
+            file: { path: frame.file.path },
+            sequence,
+            revision,
+        });
+        return this.exclusive(() => this.connection.within(timeoutMs, async () => {
+            await this.connection.write(header);
+            const message = await this.connection.read();
+            const result = message?.result;
+            if (message?.id !== `${this.connection.id}:file:${sequence}` ||
+                result?.type !== 'pane_graphics_frame_ack' ||
+                result.sequence !== sequence ||
+                result.revision !== revision) {
+                const error = new HerdrError('herdr_invalid_response', 'Graphics acknowledgement did not match the file frame');
+                this.connection.fail(error, true);
+                throw error;
+            }
+            return result;
+        }));
+    }
+    close() {
+        this.connection.close();
+    }
+}

package/dist/herdr-transport.d.ts

@@ -0,0 +1,50 @@
+export declare class HerdrError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+export interface RequestOptions {
+    /** Transport deadline, including connection time; null disables it. */
+    timeoutMs?: number | null;
+    signal?: AbortSignal;
+    maxResponseBytes?: number;
+}
+export interface StreamOptions extends RequestOptions {
+    maxQueuedEvents?: number;
+    maxQueuedBytes?: number;
+}
+export declare function validateSocketPath(path: string): void;
+export declare function validateTimeout(value: number | null): void;
+/** Internal, single-reader NDJSON connection. JSON reads and binary writes stay separate. */
+export declare class JsonConnection {
+    private options;
+    readonly id: `${string}-${string}-${string}-${string}-${string}`;
+    readonly closed: Promise<void>;
+    private resolveClosed;
+    private rejectClosed;
+    private socket;
+    private buffer;
+    private queue;
+    private queuedBytes;
+    private reader?;
+    private writes;
+    private ended;
+    private failure?;
+    private explicitClose;
+    private readonly maxMessageBytes;
+    private readonly maxQueuedEvents;
+    private readonly maxQueuedBytes;
+    private readonly abort;
+    constructor(socketPath: string, options?: StreamOptions);
+    private error;
+    private detachAbort;
+    private rejectWrites;
+    fail(error: Error, discard?: boolean): void;
+    close(): void;
+    private deliver;
+    private receive;
+    read(): Promise<any>;
+    write(data: string | Uint8Array): Promise<void>;
+    within<T>(timeoutMs: number | null, action: () => Promise<T>): Promise<T>;
+    start(method: string, params: unknown, timeoutMs: number | null): Promise<any>;
+}
+export declare function socketRequest<T>(socketPath: string, method: string, params: unknown, options?: RequestOptions): Promise<T>;