@theaileverage/marionette 0.2.2 → 0.3.0

package/dist/herdr-protocol.d.ts

@@ -1,5 +1,5 @@
 export declare const HERDR_PROTOCOL: 22;
-export declare const HERDR_SCHEMA_SHA256: "5fb46b13fdaf39c88cf699b9806685868c7ee6b0142523d84391b1606416dc0a";
+export declare const HERDR_SCHEMA_SHA256: '5fb46b13fdaf39c88cf699b9806685868c7ee6b0142523d84391b1606416dc0a';
 export declare namespace RequestTypes {
     type AgentPromptParams = {
         target: string;
@@ -1904,7 +1904,7 @@ export interface HerdrParams {
     'plugin.pane.focus': RequestTypes.PluginPaneFocusParams;
     'plugin.pane.close': RequestTypes.PluginPaneCloseParams;
 }
-export declare const HERDR_METHODS: readonly ["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"];
+export declare const HERDR_METHODS: readonly ['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'];
 export type HerdrMethod = keyof HerdrParams;
 export type HerdrResult = ResponseTypes.ResponseResult;
 export type HerdrEvent = {

package/dist/herdr-sdk.d.ts

@@ -1,11 +1,12 @@
-import { type HerdrMethod, type HerdrParams, type HerdrResult, type ResponseTypes, type RequestTypes } from './herdr-protocol.js';
+import type { HerdrJson } from './herdr-transport.js';
+import { type HerdrMethod, type HerdrParams, type HerdrResult, type RequestTypes, type ResponseTypes } 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 { HerdrEventStream, HerdrGraphicsStream } from './herdr-streams.js';
+export type { GraphicsFileFrame, GraphicsFrame, GraphicsFrameAck, GraphicsStreamParams, } from './herdr-streams.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;
@@ -22,17 +23,17 @@ export interface LaunchOptions {
     env?: Record<string, string>;
     focus?: boolean;
 }
-export interface WaitOptions {
+export type 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>;
+    call<T = unknown>(method: string, params?: Record<string, HerdrJson | undefined>, timeoutMs?: number, signal?: AbortSignal): 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>;
@@ -79,7 +80,7 @@ export declare class HerdrClient {
             layout: PaneLayout;
         }>;
         split: (paneId: string, options: LaunchOptions & {
-            direction: "right" | "down";
+            direction: 'right' | 'down';
             ratio?: number;
         }) => Promise<{
             pane: Pane;

package/dist/herdr-sdk.js

@@ -2,8 +2,8 @@ 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';
+export { HerdrError } from './herdr-transport.js';
 /** Respect server waits; the transport must not time out an otherwise valid long wait. */
 function deadline(method, params) {
     if (method === 'agent.start')
@@ -30,16 +30,15 @@ export class HerdrClient {
         return new HerdrClient(env.HERDR_SOCKET_PATH);
     }
     /** Escape hatch for future one-shot methods. Streams require their dedicated transports. */
-    call(method, params = {}, timeoutMs = 10000) {
+    call(method, params = {}, timeoutMs = 10000, signal) {
         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 });
+        return socketRequest(this.socketPath, method, params, { timeoutMs, signal });
     }
     /** 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')
+        if (!HERDR_METHODS.some((known) => known === method) || String(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,
@@ -53,6 +52,8 @@ export class HerdrClient {
         return HerdrGraphicsStream.open(this.socketPath, params, options);
     }
     /** One-to-one method names, including streams, for discovery and generated agent code. */
+    // SAFETY: Every generated method is installed below with its matching request transport;
+    // the two streaming methods are explicitly routed to their dedicated transports.
     api = Object.freeze(Object.fromEntries([
         ...HERDR_METHODS.map((method) => [
             method,
@@ -98,7 +99,12 @@ export class HerdrClient {
     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),
+        prompt: (target, text, wait) => {
+            const params = { target, text };
+            if (wait)
+                params.wait = wait;
+            return this.call('agent.prompt', params, 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

@@ -1,5 +1,5 @@
-import { type StreamOptions } from './herdr-transport.js';
 import type { HerdrEvent, HerdrResult, RequestTypes } from './herdr-protocol.js';
+import { type StreamOptions } from './herdr-transport.js';
 export declare class HerdrEventStream implements AsyncIterableIterator<HerdrEvent> {
     private connection;
     private constructor();
@@ -11,11 +11,11 @@ export declare class HerdrEventStream implements AsyncIterableIterator<HerdrEven
     return(): Promise<IteratorResult<HerdrEvent>>;
 }
 /** This wire method is documented but omitted from Herdr 0.9.0's exported JSON schema. */
-export interface GraphicsStreamParams {
+export type GraphicsStreamParams = {
     pane_id: string;
     layer_id?: string | null;
     z_index?: number;
-}
+};
 export interface GraphicsFrame {
     format: RequestTypes.PaneGraphicsFormat;
     image_width: number;

package/dist/herdr-streams.js

@@ -31,12 +31,14 @@ export class HerdrEventStream {
         const value = await this.connection.read();
         if (value === undefined)
             return { done: true, value: undefined };
+        // The published SDK has no runtime dependencies; validate its wire envelope here.
+        // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Dependency-free JSON protocol boundary.
         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 };
+        return { done: false, value };
     }
     close() {
         this.connection.close();
@@ -56,12 +58,14 @@ function frameHeader(frame) {
     integer(frame.image_height, 'image_height', 1, 0xffffffff);
     if (!['png', 'rgb', 'rgba', 'bgra'].includes(frame.format))
         throw new TypeError('Invalid frame format');
-    return {
+    const header = {
         format: frame.format,
         image_width: frame.image_width,
         image_height: frame.image_height,
-        ...(frame.placement ? { placement: frame.placement } : {}),
     };
+    if (frame.placement)
+        header.placement = frame.placement;
+    return header;
 }
 function encodeHeader(header) {
     const line = JSON.stringify(header) + '\n';

package/dist/herdr-transport.d.ts

@@ -1,3 +1,7 @@
+/** JSON payload accepted by the dependency-free wire transport, including omitted object fields. */
+export type HerdrJson = string | number | boolean | null | HerdrJson[] | {
+    [key: string]: HerdrJson | undefined;
+};
 export declare class HerdrError extends Error {
     code: string;
     constructor(code: string, message: string);
@@ -45,6 +49,6 @@ export declare class JsonConnection {
     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>;
+    start(method: string, params: Record<string, HerdrJson | undefined>, timeoutMs: number | null): Promise<any>;
 }
-export declare function socketRequest<T>(socketPath: string, method: string, params: unknown, options?: RequestOptions): Promise<T>;
+export declare function socketRequest<T>(socketPath: string, method: string, params: Record<string, HerdrJson | undefined>, options?: RequestOptions): Promise<T>;

package/dist/herdr-transport.js

@@ -1,5 +1,5 @@
-import net from 'node:net';
 import { randomUUID } from 'node:crypto';
+import net from 'node:net';
 import { isAbsolute } from 'node:path';
 export class HerdrError extends Error {
     code;
@@ -224,7 +224,7 @@ export async function socketRequest(socketPath, method, params, options = {}) {
     JSON.stringify(params);
     const connection = new JsonConnection(socketPath, options);
     try {
-        return (await connection.start(method, params, timeoutMs));
+        return await connection.start(method, params, timeoutMs);
     }
     finally {
         connection.close();