@miosa/sdk 3.4.1 → 3.6.0

package/dist/computer-use/index.d.ts

@@ -0,0 +1,154 @@
+import { BetaAbstractComputerToolset20260801, BetaComputerConfirmCallable, BetaToolsetCallContext } from '@anthropic-ai/sdk/helpers/beta/toolsets';
+export { BetaComputerMemberResult, ToolError } from '@anthropic-ai/sdk/helpers/beta/toolsets';
+import { BetaComputerToolsetConfigs, BetaComputerZoomInput, BetaComputerMouseMoveInput, BetaComputerLeftClickInput, BetaComputerRightClickInput, BetaComputerMiddleClickInput, BetaComputerDoubleClickInput, BetaComputerTripleClickInput, BetaComputerLeftClickDragInput, BetaComputerScrollInput, BetaComputerTypeInput, BetaComputerKeyInput, BetaComputerHoldKeyInput, BetaComputerWaitInput } from '@anthropic-ai/sdk/resources/beta';
+import { e as ActionName, D as Computer } from '../computer-CKDK0Ahy.js';
+import 'ws';
+import 'node:events';
+
+/**
+ * The older, named `computer` tool (`computer_20241022`, `computer_20250124`,
+ * `computer_20251124`) for models and platforms that do not take the toolset.
+ * These carry an `action` field in the input, which maps one to one onto
+ * `computer.act()`.
+ */
+
+type LegacyComputerToolVersion = "computer_20241022" | "computer_20250124" | "computer_20251124";
+/** Actions each version accepts. */
+declare const LEGACY_ACTIONS: Readonly<Record<LegacyComputerToolVersion, readonly ActionName[]>>;
+/** The beta header each version needs. */
+declare const LEGACY_BETA_HEADERS: Readonly<Record<LegacyComputerToolVersion, string>>;
+interface LegacyComputerToolOptions {
+    version: LegacyComputerToolVersion;
+    displayWidthPx: number;
+    displayHeightPx: number;
+    /** Asked before every `type`, `key` and `hold_key`. Return false to refuse. */
+    confirm: (call: {
+        action: string;
+        input: Record<string, unknown>;
+    }) => boolean | Promise<boolean>;
+}
+type LegacyToolResultContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: "image/png";
+        data: string;
+    };
+};
+interface LegacyComputerTool {
+    /** The entry for `tools[]`. */
+    definition: {
+        type: LegacyComputerToolVersion;
+        name: "computer";
+        display_width_px: number;
+        display_height_px: number;
+    };
+    /** The `anthropic-beta` header value this version needs. */
+    betaHeader: string;
+    /** Run one `tool_use` input and get the `tool_result` content. A failure is returned as text with `isError`. */
+    execute(input: Record<string, unknown>): Promise<{
+        content: LegacyToolResultContent[];
+        isError: boolean;
+    }>;
+}
+declare function miosaComputerToolLegacy(computer: Computer, options: LegacyComputerToolOptions): LegacyComputerTool;
+
+/**
+ * Claude computer-use over a MIOSA computer.
+ *
+ * `miosaComputerToolset(computer, { confirm })` is a `computer_toolset_20260801`
+ * toolset: it subclasses Anthropic's `BetaAbstractComputerToolset20260801`, so
+ * the SDK owns the model loop contract (one `tool_use` per member, the
+ * `toolset_name` echo, stop at the first failure in a batch, the skipped-action
+ * text and the approval gate). This file only drives the desktop.
+ *
+ * Needs the optional peer `@anthropic-ai/sdk` (0.133 or newer). Import it from
+ * `@miosa/sdk/computer-use`.
+ *
+ * ```ts
+ * import Anthropic from "@anthropic-ai/sdk";
+ * import { miosaComputerToolset } from "@miosa/sdk/computer-use";
+ *
+ * const toolset = miosaComputerToolset(computer, {
+ *   confirm: async ({ member, input }) => member !== "type" || askHuman(input),
+ * });
+ * const runner = client.beta.messages.toolRunner({
+ *   model: "claude-sonnet-5",
+ *   max_tokens: 8192,
+ *   messages: [{ role: "user", content: "Open the browser" }],
+ *   tools: [toolset],
+ * });
+ * ```
+ */
+
+type Disabled = {
+    enabled: false;
+};
+interface CommonOptions {
+    /** Set `triple_click` on. It is two requests (click, then double-click) and needs a low-latency link. Default: off. */
+    emulateTripleClick?: boolean;
+    /** Entry-level fields such as `{ cache_control: { type: "ephemeral" } }`. */
+    toolConfigs?: {
+        cache_control?: {
+            type: "ephemeral";
+        } | null;
+    };
+}
+/**
+ * Either pass `confirm`, or switch off `type`, `key` and `hold_key` in
+ * `configs`. A toolset that can type with neither is refused, as in
+ * Anthropic's own constructor.
+ */
+type MiosaComputerToolsetOptions = (CommonOptions & {
+    confirm: BetaComputerConfirmCallable;
+    configs?: BetaComputerToolsetConfigs;
+}) | (CommonOptions & {
+    confirm?: undefined;
+    configs: BetaComputerToolsetConfigs & {
+        type: Disabled;
+        key: Disabled;
+        hold_key: Disabled;
+    };
+});
+/** The desktop driver behind the toolset. */
+declare class MiosaComputerToolset extends BetaAbstractComputerToolset20260801 {
+    private readonly computer;
+    constructor(computer: Computer, options: MiosaComputerToolsetOptions);
+    private act;
+    protected screenshot(): Promise<{
+        data: string;
+        mediaType: "image/png";
+    }>;
+    protected zoom(_ctx: BetaToolsetCallContext, input: BetaComputerZoomInput): Promise<{
+        data: string;
+        mediaType: "image/png";
+    }>;
+    protected cursor_position(): Promise<{
+        x: number;
+        y: number;
+    }>;
+    protected mouse_move(_ctx: BetaToolsetCallContext, input: BetaComputerMouseMoveInput): Promise<void>;
+    protected left_mouse_down(): Promise<void>;
+    protected left_mouse_up(): Promise<void>;
+    protected left_click(_ctx: BetaToolsetCallContext, input: BetaComputerLeftClickInput): Promise<void>;
+    protected right_click(_ctx: BetaToolsetCallContext, input: BetaComputerRightClickInput): Promise<void>;
+    protected middle_click(_ctx: BetaToolsetCallContext, input: BetaComputerMiddleClickInput): Promise<void>;
+    protected double_click(_ctx: BetaToolsetCallContext, input: BetaComputerDoubleClickInput): Promise<void>;
+    protected triple_click(_ctx: BetaToolsetCallContext, input: BetaComputerTripleClickInput): Promise<void>;
+    protected left_click_drag(_ctx: BetaToolsetCallContext, input: BetaComputerLeftClickDragInput): Promise<void>;
+    protected scroll(_ctx: BetaToolsetCallContext, input: BetaComputerScrollInput): Promise<void>;
+    protected type_(_ctx: BetaToolsetCallContext, input: BetaComputerTypeInput): Promise<void>;
+    protected key(_ctx: BetaToolsetCallContext, input: BetaComputerKeyInput): Promise<void>;
+    protected hold_key(_ctx: BetaToolsetCallContext, input: BetaComputerHoldKeyInput): Promise<void>;
+    protected wait(_ctx: BetaToolsetCallContext, input: BetaComputerWaitInput): Promise<void>;
+}
+/**
+ * Build the toolset for one computer. `confirm` is required unless `type`,
+ * `key` and `hold_key` are switched off in `configs`.
+ */
+declare function miosaComputerToolset(computer: Computer, options: MiosaComputerToolsetOptions): MiosaComputerToolset;
+
+export { LEGACY_ACTIONS, LEGACY_BETA_HEADERS, type LegacyComputerTool, type LegacyComputerToolOptions, type LegacyComputerToolVersion, type LegacyToolResultContent, MiosaComputerToolset, type MiosaComputerToolsetOptions, miosaComputerToolLegacy, miosaComputerToolset };

package/dist/computer-use/index.js

@@ -0,0 +1,185 @@
+import { performActionDynamic, InvalidActionInputError } from '../chunk-H245ZDMW.js';
+import { MiosaError } from '../chunk-BMWUKYWU.js';
+import { BetaAbstractComputerToolset20260801, ToolError } from '@anthropic-ai/sdk/helpers/beta/toolsets';
+export { ToolError } from '@anthropic-ai/sdk/helpers/beta/toolsets';
+
+// src/computer-use/legacy.ts
+var BASE_ACTIONS = [
+  "key",
+  "type",
+  "mouse_move",
+  "left_click",
+  "left_click_drag",
+  "right_click",
+  "middle_click",
+  "double_click",
+  "screenshot",
+  "cursor_position"
+];
+var V20250124_ACTIONS = [...BASE_ACTIONS, "left_mouse_down", "left_mouse_up", "scroll", "hold_key", "wait", "triple_click"];
+var V20251124_ACTIONS = [...V20250124_ACTIONS, "zoom"];
+var LEGACY_ACTIONS = {
+  computer_20241022: BASE_ACTIONS,
+  computer_20250124: V20250124_ACTIONS,
+  computer_20251124: V20251124_ACTIONS
+};
+var LEGACY_BETA_HEADERS = {
+  computer_20241022: "computer-use-2024-10-22",
+  computer_20250124: "computer-use-2025-01-24",
+  computer_20251124: "computer-use-2025-11-24"
+};
+var NEEDS_CONFIRM = /* @__PURE__ */ new Set(["type", "key", "hold_key"]);
+function miosaComputerToolLegacy(computer, options) {
+  if (typeof options.confirm !== "function") {
+    throw new MiosaError("a confirm callable is required", 0, "CONFIRM_REQUIRED", {}, void 0, false);
+  }
+  const allowed = new Set(LEGACY_ACTIONS[options.version]);
+  return {
+    definition: {
+      type: options.version,
+      name: "computer",
+      display_width_px: options.displayWidthPx,
+      display_height_px: options.displayHeightPx
+    },
+    betaHeader: LEGACY_BETA_HEADERS[options.version],
+    async execute(input) {
+      const { action, ...params } = input;
+      const fail = (text) => ({ content: [{ type: "text", text }], isError: true });
+      if (typeof action !== "string" || !allowed.has(action)) {
+        return fail(`${options.version} does not support the action ${JSON.stringify(action)}`);
+      }
+      if (NEEDS_CONFIRM.has(action) && !await options.confirm({ action, input: params })) {
+        return fail(`The ${action} action was declined.`);
+      }
+      try {
+        const result = await performActionDynamic(computer.desktop, action, params);
+        if (result.action === "screenshot" || result.action === "zoom") {
+          return {
+            content: [{ type: "image", source: { type: "base64", media_type: "image/png", data: result.imageBase64 } }],
+            isError: false
+          };
+        }
+        if (result.action === "cursor_position") {
+          return { content: [{ type: "text", text: `X=${result.x}, Y=${result.y}` }], isError: false };
+        }
+        return { content: [{ type: "text", text: "Done." }], isError: false };
+      } catch (error) {
+        return fail(error instanceof Error ? error.message : String(error));
+      }
+    }
+  };
+}
+
+// src/computer-use/index.ts
+var NEEDS_CONFIRM2 = ["type", "key", "hold_key"];
+function toToolError(error) {
+  if (error instanceof ToolError) return error;
+  if (error instanceof InvalidActionInputError) return new ToolError(error.message);
+  if (error instanceof MiosaError) return new ToolError(`${error.code ?? "ERROR"}: ${error.message}`);
+  return new ToolError(error instanceof Error ? error.message : String(error));
+}
+var MiosaComputerToolset = class extends BetaAbstractComputerToolset20260801 {
+  constructor(computer, options) {
+    const configs = { ...options.configs ?? {} };
+    if (!options.emulateTripleClick && configs.triple_click === void 0) {
+      configs.triple_click = { enabled: false };
+    }
+    super({
+      configs,
+      ...options.confirm ? { confirm: options.confirm } : {},
+      ...options.toolConfigs ? { toolConfigs: options.toolConfigs } : {}
+    });
+    this.computer = computer;
+  }
+  computer;
+  async act(action, params) {
+    try {
+      return await performActionDynamic(this.computer.desktop, action, params);
+    } catch (error) {
+      throw toToolError(error);
+    }
+  }
+  async screenshot() {
+    const shot = await this.act("screenshot", {});
+    if (shot.action !== "screenshot") throw new ToolError("unexpected screenshot result");
+    return { data: shot.imageBase64, mediaType: "image/png" };
+  }
+  async zoom(_ctx, input) {
+    const shot = await this.act("zoom", { region: input.region });
+    if (shot.action !== "zoom") throw new ToolError("unexpected zoom result");
+    return { data: shot.imageBase64, mediaType: "image/png" };
+  }
+  async cursor_position() {
+    const at = await this.act("cursor_position", {});
+    if (at.action !== "cursor_position") throw new ToolError("unexpected cursor result");
+    return { x: at.x, y: at.y };
+  }
+  async mouse_move(_ctx, input) {
+    await this.act("mouse_move", { coordinate: input.coordinate });
+  }
+  async left_mouse_down() {
+    await this.act("left_mouse_down", {});
+  }
+  async left_mouse_up() {
+    await this.act("left_mouse_up", {});
+  }
+  async left_click(_ctx, input) {
+    await this.act("left_click", clean(input));
+  }
+  async right_click(_ctx, input) {
+    await this.act("right_click", clean(input));
+  }
+  async middle_click(_ctx, input) {
+    await this.act("middle_click", clean(input));
+  }
+  async double_click(_ctx, input) {
+    await this.act("double_click", clean(input));
+  }
+  async triple_click(_ctx, input) {
+    await this.act("triple_click", clean(input));
+  }
+  async left_click_drag(_ctx, input) {
+    await this.act("left_click_drag", clean(input));
+  }
+  async scroll(_ctx, input) {
+    await this.act("scroll", clean(input));
+  }
+  async type_(_ctx, input) {
+    await this.act("type", clean(input));
+  }
+  async key(_ctx, input) {
+    await this.act("key", clean(input));
+  }
+  async hold_key(_ctx, input) {
+    await this.act("hold_key", clean(input));
+  }
+  async wait(_ctx, input) {
+    await this.act("wait", clean(input));
+  }
+};
+function clean(input) {
+  return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== null && value !== void 0));
+}
+function miosaComputerToolset(computer, options) {
+  const confirmMissing = options.confirm === void 0;
+  if (confirmMissing) {
+    for (const member of NEEDS_CONFIRM2) {
+      const config = (options.configs ?? {})[member];
+      if (config?.enabled !== false) {
+        throw new MiosaError(
+          `${member} needs a confirm callable: pass confirm, or disable ${NEEDS_CONFIRM2.join(", ")} in configs`,
+          0,
+          "CONFIRM_REQUIRED",
+          { member },
+          void 0,
+          false
+        );
+      }
+    }
+  }
+  return new MiosaComputerToolset(computer, options);
+}
+
+export { LEGACY_ACTIONS, LEGACY_BETA_HEADERS, MiosaComputerToolset, miosaComputerToolLegacy, miosaComputerToolset };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/computer-use/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/computer-use/legacy.ts","../../src/computer-use/index.ts"],"names":["NEEDS_CONFIRM"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * The older, named `computer` tool (`computer_20241022`, `computer_20250124`,\n * `computer_20251124`) for models and platforms that do not take the toolset.\n * These carry an `action` field in the input, which maps one to one onto\n * `computer.act()`.\n */\n\nimport { MiosaError } from \"../errors.js\";\nimport type { Computer } from \"../resources/computer.js\";\nimport { performActionDynamic, type ActionName } from \"../resources/desktop-act.js\";\n\nexport type LegacyComputerToolVersion = \"computer_20241022\" | \"computer_20250124\" | \"computer_20251124\";\n\nconst BASE_ACTIONS = [\n  \"key\",\n  \"type\",\n  \"mouse_move\",\n  \"left_click\",\n  \"left_click_drag\",\n  \"right_click\",\n  \"middle_click\",\n  \"double_click\",\n  \"screenshot\",\n  \"cursor_position\",\n] as const satisfies readonly ActionName[];\n\nconst V20250124_ACTIONS = [...BASE_ACTIONS, \"left_mouse_down\", \"left_mouse_up\", \"scroll\", \"hold_key\", \"wait\", \"triple_click\"] as const;\nconst V20251124_ACTIONS = [...V20250124_ACTIONS, \"zoom\"] as const;\n\n/** Actions each version accepts. */\nexport const LEGACY_ACTIONS: Readonly<Record<LegacyComputerToolVersion, readonly ActionName[]>> = {\n  computer_20241022: BASE_ACTIONS,\n  computer_20250124: V20250124_ACTIONS,\n  computer_20251124: V20251124_ACTIONS,\n};\n\n/** The beta header each version needs. */\nexport const LEGACY_BETA_HEADERS: Readonly<Record<LegacyComputerToolVersion, string>> = {\n  computer_20241022: \"computer-use-2024-10-22\",\n  computer_20250124: \"computer-use-2025-01-24\",\n  computer_20251124: \"computer-use-2025-11-24\",\n};\n\nconst NEEDS_CONFIRM: ReadonlySet<string> = new Set([\"type\", \"key\", \"hold_key\"]);\n\nexport interface LegacyComputerToolOptions {\n  version: LegacyComputerToolVersion;\n  displayWidthPx: number;\n  displayHeightPx: number;\n  /** Asked before every `type`, `key` and `hold_key`. Return false to refuse. */\n  confirm: (call: { action: string; input: Record<string, unknown> }) => boolean | Promise<boolean>;\n}\n\nexport type LegacyToolResultContent =\n  | { type: \"text\"; text: string }\n  | { type: \"image\"; source: { type: \"base64\"; media_type: \"image/png\"; data: string } };\n\nexport interface LegacyComputerTool {\n  /** The entry for `tools[]`. */\n  definition: {\n    type: LegacyComputerToolVersion;\n    name: \"computer\";\n    display_width_px: number;\n    display_height_px: number;\n  };\n  /** The `anthropic-beta` header value this version needs. */\n  betaHeader: string;\n  /** Run one `tool_use` input and get the `tool_result` content. A failure is returned as text with `isError`. */\n  execute(input: Record<string, unknown>): Promise<{ content: LegacyToolResultContent[]; isError: boolean }>;\n}\n\nexport function miosaComputerToolLegacy(computer: Computer, options: LegacyComputerToolOptions): LegacyComputerTool {\n  if (typeof options.confirm !== \"function\") {\n    throw new MiosaError(\"a confirm callable is required\", 0, \"CONFIRM_REQUIRED\", {}, undefined, false);\n  }\n  const allowed = new Set<string>(LEGACY_ACTIONS[options.version]);\n  return {\n    definition: {\n      type: options.version,\n      name: \"computer\",\n      display_width_px: options.displayWidthPx,\n      display_height_px: options.displayHeightPx,\n    },\n    betaHeader: LEGACY_BETA_HEADERS[options.version],\n    async execute(input) {\n      const { action, ...params } = input;\n      const fail = (text: string) => ({ content: [{ type: \"text\" as const, text }], isError: true });\n      if (typeof action !== \"string\" || !allowed.has(action)) {\n        return fail(`${options.version} does not support the action ${JSON.stringify(action)}`);\n      }\n      if (NEEDS_CONFIRM.has(action) && !(await options.confirm({ action, input: params }))) {\n        return fail(`The ${action} action was declined.`);\n      }\n      try {\n        const result = await performActionDynamic(computer.desktop, action as ActionName, params);\n        if (result.action === \"screenshot\" || result.action === \"zoom\") {\n          return {\n            content: [{ type: \"image\" as const, source: { type: \"base64\" as const, media_type: \"image/png\" as const, data: result.imageBase64 } }],\n            isError: false,\n          };\n        }\n        if (result.action === \"cursor_position\") {\n          return { content: [{ type: \"text\" as const, text: `X=${result.x}, Y=${result.y}` }], isError: false };\n        }\n        return { content: [{ type: \"text\" as const, text: \"Done.\" }], isError: false };\n      } catch (error) {\n        return fail(error instanceof Error ? error.message : String(error));\n      }\n    },\n  };\n}\n","/**\n * Claude computer-use over a MIOSA computer.\n *\n * `miosaComputerToolset(computer, { confirm })` is a `computer_toolset_20260801`\n * toolset: it subclasses Anthropic's `BetaAbstractComputerToolset20260801`, so\n * the SDK owns the model loop contract (one `tool_use` per member, the\n * `toolset_name` echo, stop at the first failure in a batch, the skipped-action\n * text and the approval gate). This file only drives the desktop.\n *\n * Needs the optional peer `@anthropic-ai/sdk` (0.133 or newer). Import it from\n * `@miosa/sdk/computer-use`.\n *\n * ```ts\n * import Anthropic from \"@anthropic-ai/sdk\";\n * import { miosaComputerToolset } from \"@miosa/sdk/computer-use\";\n *\n * const toolset = miosaComputerToolset(computer, {\n *   confirm: async ({ member, input }) => member !== \"type\" || askHuman(input),\n * });\n * const runner = client.beta.messages.toolRunner({\n *   model: \"claude-sonnet-5\",\n *   max_tokens: 8192,\n *   messages: [{ role: \"user\", content: \"Open the browser\" }],\n *   tools: [toolset],\n * });\n * ```\n */\n\nimport {\n  BetaAbstractComputerToolset20260801,\n  ToolError,\n  type BetaComputerConfirmCallable,\n  type BetaComputerMemberResult,\n  type BetaToolsetCallContext,\n} from \"@anthropic-ai/sdk/helpers/beta/toolsets\";\nimport type {\n  BetaComputerDoubleClickInput,\n  BetaComputerHoldKeyInput,\n  BetaComputerKeyInput,\n  BetaComputerLeftClickDragInput,\n  BetaComputerLeftClickInput,\n  BetaComputerMiddleClickInput,\n  BetaComputerMouseMoveInput,\n  BetaComputerRightClickInput,\n  BetaComputerScrollInput,\n  BetaComputerToolsetConfigs,\n  BetaComputerTripleClickInput,\n  BetaComputerTypeInput,\n  BetaComputerWaitInput,\n  BetaComputerZoomInput,\n} from \"@anthropic-ai/sdk/resources/beta\";\n\nimport type { Computer } from \"../resources/computer.js\";\nimport {\n  InvalidActionInputError,\n  performActionDynamic,\n  type ActionName,\n  type ActionResult,\n} from \"../resources/desktop-act.js\";\nimport { MiosaError } from \"../errors.js\";\n\n/** Members that type or press keys. Anthropic requires an approval callable for them. */\nconst NEEDS_CONFIRM = [\"type\", \"key\", \"hold_key\"] as const;\n\ntype Disabled = { enabled: false };\n\ninterface CommonOptions {\n  /** Set `triple_click` on. It is two requests (click, then double-click) and needs a low-latency link. Default: off. */\n  emulateTripleClick?: boolean;\n  /** Entry-level fields such as `{ cache_control: { type: \"ephemeral\" } }`. */\n  toolConfigs?: { cache_control?: { type: \"ephemeral\" } | null };\n}\n\n/**\n * Either pass `confirm`, or switch off `type`, `key` and `hold_key` in\n * `configs`. A toolset that can type with neither is refused, as in\n * Anthropic's own constructor.\n */\nexport type MiosaComputerToolsetOptions =\n  | (CommonOptions & { confirm: BetaComputerConfirmCallable; configs?: BetaComputerToolsetConfigs })\n  | (CommonOptions & {\n      confirm?: undefined;\n      configs: BetaComputerToolsetConfigs & { type: Disabled; key: Disabled; hold_key: Disabled };\n    });\n\nfunction toToolError(error: unknown): ToolError {\n  if (error instanceof ToolError) return error;\n  if (error instanceof InvalidActionInputError) return new ToolError(error.message);\n  if (error instanceof MiosaError) return new ToolError(`${error.code ?? \"ERROR\"}: ${error.message}`);\n  return new ToolError(error instanceof Error ? error.message : String(error));\n}\n\n/** The desktop driver behind the toolset. */\nexport class MiosaComputerToolset extends BetaAbstractComputerToolset20260801 {\n  constructor(\n    private readonly computer: Computer,\n    options: MiosaComputerToolsetOptions,\n  ) {\n    const configs: BetaComputerToolsetConfigs = { ...(options.configs ?? {}) };\n    if (!options.emulateTripleClick && configs.triple_click === undefined) {\n      configs.triple_click = { enabled: false };\n    }\n    super({\n      configs,\n      ...(options.confirm ? { confirm: options.confirm } : {}),\n      ...(options.toolConfigs ? { toolConfigs: options.toolConfigs } : {}),\n    });\n  }\n\n  private async act(action: ActionName, params: Record<string, unknown>): Promise<ActionResult> {\n    try {\n      return await performActionDynamic(this.computer.desktop, action, params);\n    } catch (error) {\n      throw toToolError(error);\n    }\n  }\n\n  protected override async screenshot(): Promise<{ data: string; mediaType: \"image/png\" }> {\n    const shot = await this.act(\"screenshot\", {});\n    if (shot.action !== \"screenshot\") throw new ToolError(\"unexpected screenshot result\");\n    return { data: shot.imageBase64, mediaType: \"image/png\" };\n  }\n\n  protected override async zoom(_ctx: BetaToolsetCallContext, input: BetaComputerZoomInput) {\n    const shot = await this.act(\"zoom\", { region: input.region });\n    if (shot.action !== \"zoom\") throw new ToolError(\"unexpected zoom result\");\n    return { data: shot.imageBase64, mediaType: \"image/png\" as const };\n  }\n\n  protected override async cursor_position(): Promise<{ x: number; y: number }> {\n    const at = await this.act(\"cursor_position\", {});\n    if (at.action !== \"cursor_position\") throw new ToolError(\"unexpected cursor result\");\n    return { x: at.x, y: at.y };\n  }\n\n  protected override async mouse_move(_ctx: BetaToolsetCallContext, input: BetaComputerMouseMoveInput): Promise<void> {\n    await this.act(\"mouse_move\", { coordinate: input.coordinate });\n  }\n\n  protected override async left_mouse_down(): Promise<void> {\n    await this.act(\"left_mouse_down\", {});\n  }\n\n  protected override async left_mouse_up(): Promise<void> {\n    await this.act(\"left_mouse_up\", {});\n  }\n\n  protected override async left_click(_ctx: BetaToolsetCallContext, input: BetaComputerLeftClickInput): Promise<void> {\n    await this.act(\"left_click\", clean(input));\n  }\n\n  protected override async right_click(_ctx: BetaToolsetCallContext, input: BetaComputerRightClickInput): Promise<void> {\n    await this.act(\"right_click\", clean(input));\n  }\n\n  protected override async middle_click(_ctx: BetaToolsetCallContext, input: BetaComputerMiddleClickInput): Promise<void> {\n    await this.act(\"middle_click\", clean(input));\n  }\n\n  protected override async double_click(_ctx: BetaToolsetCallContext, input: BetaComputerDoubleClickInput): Promise<void> {\n    await this.act(\"double_click\", clean(input));\n  }\n\n  protected override async triple_click(_ctx: BetaToolsetCallContext, input: BetaComputerTripleClickInput): Promise<void> {\n    await this.act(\"triple_click\", clean(input));\n  }\n\n  protected override async left_click_drag(_ctx: BetaToolsetCallContext, input: BetaComputerLeftClickDragInput): Promise<void> {\n    await this.act(\"left_click_drag\", clean(input));\n  }\n\n  protected override async scroll(_ctx: BetaToolsetCallContext, input: BetaComputerScrollInput): Promise<void> {\n    await this.act(\"scroll\", clean(input));\n  }\n\n  protected override async type_(_ctx: BetaToolsetCallContext, input: BetaComputerTypeInput): Promise<void> {\n    await this.act(\"type\", clean(input));\n  }\n\n  protected override async key(_ctx: BetaToolsetCallContext, input: BetaComputerKeyInput): Promise<void> {\n    await this.act(\"key\", clean(input));\n  }\n\n  protected override async hold_key(_ctx: BetaToolsetCallContext, input: BetaComputerHoldKeyInput): Promise<void> {\n    await this.act(\"hold_key\", clean(input));\n  }\n\n  protected override async wait(_ctx: BetaToolsetCallContext, input: BetaComputerWaitInput): Promise<void> {\n    await this.act(\"wait\", clean(input));\n  }\n}\n\n/** Drop `null` fields: the API sends `null` for an omitted optional input. */\nfunction clean(input: object): Record<string, unknown> {\n  return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== null && value !== undefined));\n}\n\n/**\n * Build the toolset for one computer. `confirm` is required unless `type`,\n * `key` and `hold_key` are switched off in `configs`.\n */\nexport function miosaComputerToolset(computer: Computer, options: MiosaComputerToolsetOptions): MiosaComputerToolset {\n  const confirmMissing = options.confirm === undefined;\n  if (confirmMissing) {\n    for (const member of NEEDS_CONFIRM) {\n      const config = (options.configs ?? {})[member];\n      if (config?.enabled !== false) {\n        throw new MiosaError(\n          `${member} needs a confirm callable: pass confirm, or disable ${NEEDS_CONFIRM.join(\", \")} in configs`,\n          0,\n          \"CONFIRM_REQUIRED\",\n          { member },\n          undefined,\n          false,\n        );\n      }\n    }\n  }\n  return new MiosaComputerToolset(computer, options);\n}\n\nexport type { BetaComputerMemberResult };\nexport { ToolError };\n\nexport {\n  LEGACY_ACTIONS,\n  LEGACY_BETA_HEADERS,\n  miosaComputerToolLegacy,\n  type LegacyComputerTool,\n  type LegacyComputerToolOptions,\n  type LegacyComputerToolVersion,\n  type LegacyToolResultContent,\n} from \"./legacy.js\";\n"]}

package/dist/helpers/index.d.ts

@@ -0,0 +1,77 @@
+import { eH as Miosa } from '../client-C_uXhex9.js';
+import { c$ as ComputerEvent, be as MachineCommandOptions, bf as MachineCommandResult, bR as RunActivity, cT as WaitOptions, D as Computer, c8 as RunWaitOptions, bQ as Run, cS as WaitIdleOptions } from '../computer-CKDK0Ahy.js';
+import 'ws';
+import 'node:events';
+
+/**
+ * One import for the things every agent loop reaches for, keyed by computer id:
+ *
+ * ```ts
+ * import { waitUntilReady, execCommand, stopAndRemove } from "@miosa/sdk/helpers";
+ * ```
+ *
+ * | Helper | Does |
+ * |---|---|
+ * | `waitUntilReady` | poll until the computer is `active` or `running` |
+ * | `waitForDesktop` | ready, and the desktop answers |
+ * | `waitUntilIdle` | the screen stopped changing |
+ * | `waitForPrompt` | wait for an agent run to finish |
+ * | `streamPrompt` | follow an agent run's activity |
+ * | `streamEvents` | follow in-VM events (window, file, process, clipboard, idle) |
+ * | `streamCommand` | run a command and follow its output |
+ * | `execCommand` | run a command and get the result |
+ * | `readText` / `writeText` | UTF-8 files |
+ * | `stopAndRemove` | stop, then destroy; safe to call twice |
+ */
+
+/** Poll until the computer is ready. Throws `COMPUTER_NOT_READY` if it errors, `COMPUTER_READY_TIMEOUT` (retryable) if it is slow. */
+declare function waitUntilReady(miosa: Miosa, computerId: string, options?: WaitOptions): Promise<Computer>;
+/** Wait until the computer is ready and `GET /desktop/screen-size` answers. */
+declare function waitForDesktop(miosa: Miosa, computerId: string, options?: WaitOptions): Promise<Computer>;
+/** Wait until two screenshots `quietMs` apart match (default 1000 ms). Throws `DESKTOP_IDLE_TIMEOUT` (retryable). */
+declare function waitUntilIdle(miosa: Miosa, computerId: string, options?: WaitIdleOptions): Promise<void>;
+/** Wait for an agent run to reach a terminal status. */
+declare function waitForPrompt(miosa: Miosa, runId: string, options?: RunWaitOptions): Promise<Run>;
+/** Follow an agent run's activity (`GET /runs/:id/activity`). */
+declare function streamPrompt(miosa: Miosa, runId: string): AsyncIterableIterator<RunActivity>;
+type StreamedEvent = {
+    type: ComputerEvent["type"];
+    payload: ComputerEvent["payload"];
+};
+/**
+ * Follow in-VM events as an async iterator. Breaking out of the loop (or an
+ * abort) closes the WebSocket. Needs the optional `ws` package on Node.
+ */
+declare function streamEvents(miosa: Miosa, computerId: string, options: {
+    subscribe: Array<"window" | "clipboard" | "file" | "process" | "idle">;
+    paths?: string[];
+    idleThresholdSec?: number;
+    signal?: AbortSignal;
+}): AsyncGenerator<StreamedEvent>;
+type CommandChunk = {
+    stream: "stdout" | "stderr";
+    data: Uint8Array;
+} | {
+    stream: "exit";
+    code: number;
+};
+/** Run a command and follow its output; the last item is `{ stream: "exit", code }`. */
+declare function streamCommand(miosa: Miosa, computerId: string, command: string, options?: {
+    args?: string[];
+    cwd?: string;
+    env?: string[];
+    signal?: AbortSignal;
+}): AsyncGenerator<CommandChunk>;
+/** Run a command and wait for it (`POST /computers/:id/commands`, up to 600 seconds). */
+declare function execCommand(miosa: Miosa, computerId: string, command: string, options?: MachineCommandOptions): Promise<MachineCommandResult>;
+/** Read a UTF-8 file from the computer. */
+declare function readText(miosa: Miosa, computerId: string, path: string): Promise<string>;
+/** Write a UTF-8 file to the computer. */
+declare function writeText(miosa: Miosa, computerId: string, path: string, content: string): Promise<void>;
+/**
+ * Stop the computer and destroy it. A computer that is already stopped, or
+ * already gone, is not an error, so calling this twice is safe.
+ */
+declare function stopAndRemove(miosa: Miosa, computerId: string): Promise<void>;
+
+export { type CommandChunk, type StreamedEvent, WaitIdleOptions, WaitOptions, execCommand, readText, stopAndRemove, streamCommand, streamEvents, streamPrompt, waitForDesktop, waitForPrompt, waitUntilIdle, waitUntilReady, writeText };

package/dist/helpers/index.js

@@ -0,0 +1,151 @@
+import { NotFoundError } from '../chunk-BMWUKYWU.js';
+
+// src/helpers/index.ts
+async function waitUntilReady(miosa, computerId, options = {}) {
+  return (await miosa.computers.get(computerId)).waitUntilReady(options);
+}
+async function waitForDesktop(miosa, computerId, options = {}) {
+  return (await miosa.computers.get(computerId)).waitForDesktop(options);
+}
+async function waitUntilIdle(miosa, computerId, options = {}) {
+  return (await miosa.computers.get(computerId)).waitUntilIdle(options);
+}
+function waitForPrompt(miosa, runId, options = {}) {
+  return miosa.runs.waitForCompletion(runId, options);
+}
+function streamPrompt(miosa, runId) {
+  return miosa.runs.streamActivity(runId);
+}
+async function* streamEvents(miosa, computerId, options) {
+  const computer = await miosa.computers.get(computerId);
+  const { signal, ...subscription } = options;
+  const stream = computer.events.subscribe(subscription);
+  const queue = [];
+  let failure;
+  let done = false;
+  let wake;
+  const notify = () => {
+    wake?.();
+    wake = void 0;
+  };
+  const emit = stream.emit.bind(stream);
+  stream.emit = (type, ...args) => {
+    if (type === "error") failure = args[0] instanceof Error ? args[0] : new Error(String(args[0]));
+    else if (type === "close") done = true;
+    else queue.push({ type, payload: args[0] });
+    notify();
+    return emit(type, ...args);
+  };
+  signal?.addEventListener("abort", () => {
+    done = true;
+    notify();
+  });
+  try {
+    for (; ; ) {
+      const next = queue.shift();
+      if (next) {
+        yield next;
+        continue;
+      }
+      if (failure) throw failure;
+      if (done) return;
+      await new Promise((resolve) => {
+        wake = resolve;
+      });
+    }
+  } finally {
+    await stream.close();
+  }
+}
+async function* streamCommand(miosa, computerId, command, options = {}) {
+  const computer = await miosa.computers.get(computerId);
+  const { signal, ...rest } = options;
+  const handle = computer.exec.stream({ command, ...rest });
+  const queue = [];
+  let failure;
+  let done = false;
+  let wake;
+  const notify = () => {
+    wake?.();
+    wake = void 0;
+  };
+  handle.on("stdout", (data) => {
+    queue.push({ stream: "stdout", data });
+    notify();
+  });
+  handle.on("stderr", (data) => {
+    queue.push({ stream: "stderr", data });
+    notify();
+  });
+  handle.on("exit", (code) => {
+    queue.push({ stream: "exit", code });
+    done = true;
+    notify();
+  });
+  handle.on("error", (error) => {
+    failure = error;
+    notify();
+  });
+  handle.on("close", () => {
+    done = true;
+    notify();
+  });
+  signal?.addEventListener("abort", () => {
+    done = true;
+    notify();
+  });
+  try {
+    for (; ; ) {
+      const next = queue.shift();
+      if (next) {
+        yield next;
+        if (next.stream === "exit") return;
+        continue;
+      }
+      if (failure) throw failure;
+      if (done) return;
+      await new Promise((resolve) => {
+        wake = resolve;
+      });
+    }
+  } finally {
+    await handle.close();
+  }
+}
+async function execCommand(miosa, computerId, command, options = {}) {
+  const computer = await miosa.computers.get(computerId);
+  return computer.runCommand(command, options);
+}
+async function readText(miosa, computerId, path) {
+  const computer = await miosa.computers.get(computerId);
+  return computer.files.readFile(path);
+}
+async function writeText(miosa, computerId, path, content) {
+  const computer = await miosa.computers.get(computerId);
+  await computer.files.writeFile(path, content);
+}
+async function stopAndRemove(miosa, computerId) {
+  let computer;
+  try {
+    computer = await miosa.computers.get(computerId);
+  } catch (error) {
+    if (error instanceof NotFoundError) return;
+    throw error;
+  }
+  if (computer.status !== "stopped" && computer.status !== "destroyed") {
+    try {
+      await computer.stop();
+    } catch (error) {
+      if (error instanceof NotFoundError) return;
+    }
+  }
+  try {
+    await computer.destroy();
+  } catch (error) {
+    if (!(error instanceof NotFoundError)) throw error;
+  }
+}
+
+export { execCommand, readText, stopAndRemove, streamCommand, streamEvents, streamPrompt, waitForDesktop, waitForPrompt, waitUntilIdle, waitUntilReady, writeText };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/helpers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/helpers/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * One import for the things every agent loop reaches for, keyed by computer id:\n *\n * ```ts\n * import { waitUntilReady, execCommand, stopAndRemove } from \"@miosa/sdk/helpers\";\n * ```\n *\n * | Helper | Does |\n * |---|---|\n * | `waitUntilReady` | poll until the computer is `active` or `running` |\n * | `waitForDesktop` | ready, and the desktop answers |\n * | `waitUntilIdle` | the screen stopped changing |\n * | `waitForPrompt` | wait for an agent run to finish |\n * | `streamPrompt` | follow an agent run's activity |\n * | `streamEvents` | follow in-VM events (window, file, process, clipboard, idle) |\n * | `streamCommand` | run a command and follow its output |\n * | `execCommand` | run a command and get the result |\n * | `readText` / `writeText` | UTF-8 files |\n * | `stopAndRemove` | stop, then destroy; safe to call twice |\n */\n\nimport { NotFoundError } from \"../errors.js\";\nimport type { Miosa } from \"../client.js\";\nimport type { Computer } from \"../resources/computer.js\";\nimport type { WaitIdleOptions, WaitOptions } from \"../resources/computer-agent.js\";\nimport type { ComputerEvent } from \"../resources/events.js\";\nimport type { MachineCommandOptions, MachineCommandResult } from \"../resources/machine-common.js\";\nimport type { Run, RunActivity, RunWaitOptions } from \"../resources/runs.js\";\n\nexport type { WaitIdleOptions, WaitOptions };\n\n// The polling lives on the Computer (src/resources/computer-agent.ts). These\n// look the computer up by id and delegate, so there is one implementation.\n\n/** Poll until the computer is ready. Throws `COMPUTER_NOT_READY` if it errors, `COMPUTER_READY_TIMEOUT` (retryable) if it is slow. */\nexport async function waitUntilReady(miosa: Miosa, computerId: string, options: WaitOptions = {}): Promise<Computer> {\n  return (await miosa.computers.get(computerId)).waitUntilReady(options);\n}\n\n/** Wait until the computer is ready and `GET /desktop/screen-size` answers. */\nexport async function waitForDesktop(miosa: Miosa, computerId: string, options: WaitOptions = {}): Promise<Computer> {\n  return (await miosa.computers.get(computerId)).waitForDesktop(options);\n}\n\n/** Wait until two screenshots `quietMs` apart match (default 1000 ms). Throws `DESKTOP_IDLE_TIMEOUT` (retryable). */\nexport async function waitUntilIdle(miosa: Miosa, computerId: string, options: WaitIdleOptions = {}): Promise<void> {\n  return (await miosa.computers.get(computerId)).waitUntilIdle(options);\n}\n\n/** Wait for an agent run to reach a terminal status. */\nexport function waitForPrompt(miosa: Miosa, runId: string, options: RunWaitOptions = {}): Promise<Run> {\n  return miosa.runs.waitForCompletion(runId, options);\n}\n\n/** Follow an agent run's activity (`GET /runs/:id/activity`). */\nexport function streamPrompt(miosa: Miosa, runId: string): AsyncIterableIterator<RunActivity> {\n  return miosa.runs.streamActivity(runId);\n}\n\nexport type StreamedEvent = { type: ComputerEvent[\"type\"]; payload: ComputerEvent[\"payload\"] };\n\n/**\n * Follow in-VM events as an async iterator. Breaking out of the loop (or an\n * abort) closes the WebSocket. Needs the optional `ws` package on Node.\n */\nexport async function* streamEvents(\n  miosa: Miosa,\n  computerId: string,\n  options: { subscribe: Array<\"window\" | \"clipboard\" | \"file\" | \"process\" | \"idle\">; paths?: string[]; idleThresholdSec?: number; signal?: AbortSignal },\n): AsyncGenerator<StreamedEvent> {\n  const computer = await miosa.computers.get(computerId);\n  const { signal, ...subscription } = options;\n  const stream = computer.events.subscribe(subscription);\n  const queue: StreamedEvent[] = [];\n  let failure: Error | undefined;\n  let done = false;\n  let wake: (() => void) | undefined;\n  const notify = (): void => {\n    wake?.();\n    wake = undefined;\n  };\n\n  // The stream emits one event name per type; tap `emit` to see them all.\n  const emit = stream.emit.bind(stream) as (type: string, ...args: unknown[]) => boolean;\n  (stream as unknown as { emit: typeof emit }).emit = (type: string, ...args: unknown[]): boolean => {\n    if (type === \"error\") failure = args[0] instanceof Error ? args[0] : new Error(String(args[0]));\n    else if (type === \"close\") done = true;\n    else queue.push({ type: type as StreamedEvent[\"type\"], payload: args[0] as StreamedEvent[\"payload\"] });\n    notify();\n    return emit(type, ...args);\n  };\n  signal?.addEventListener(\"abort\", () => {\n    done = true;\n    notify();\n  });\n\n  try {\n    for (;;) {\n      const next = queue.shift();\n      if (next) {\n        yield next;\n        continue;\n      }\n      if (failure) throw failure;\n      if (done) return;\n      await new Promise<void>((resolve) => {\n        wake = resolve;\n      });\n    }\n  } finally {\n    await stream.close();\n  }\n}\n\nexport type CommandChunk =\n  | { stream: \"stdout\" | \"stderr\"; data: Uint8Array }\n  | { stream: \"exit\"; code: number };\n\n/** Run a command and follow its output; the last item is `{ stream: \"exit\", code }`. */\nexport async function* streamCommand(\n  miosa: Miosa,\n  computerId: string,\n  command: string,\n  options: { args?: string[]; cwd?: string; env?: string[]; signal?: AbortSignal } = {},\n): AsyncGenerator<CommandChunk> {\n  const computer = await miosa.computers.get(computerId);\n  const { signal, ...rest } = options;\n  const handle = computer.exec.stream({ command, ...rest });\n  const queue: CommandChunk[] = [];\n  let failure: Error | undefined;\n  let done = false;\n  let wake: (() => void) | undefined;\n  const notify = (): void => {\n    wake?.();\n    wake = undefined;\n  };\n  handle.on(\"stdout\", (data) => {\n    queue.push({ stream: \"stdout\", data });\n    notify();\n  });\n  handle.on(\"stderr\", (data) => {\n    queue.push({ stream: \"stderr\", data });\n    notify();\n  });\n  handle.on(\"exit\", (code) => {\n    queue.push({ stream: \"exit\", code });\n    done = true;\n    notify();\n  });\n  handle.on(\"error\", (error) => {\n    failure = error;\n    notify();\n  });\n  handle.on(\"close\", () => {\n    done = true;\n    notify();\n  });\n  signal?.addEventListener(\"abort\", () => {\n    done = true;\n    notify();\n  });\n  try {\n    for (;;) {\n      const next = queue.shift();\n      if (next) {\n        yield next;\n        if (next.stream === \"exit\") return;\n        continue;\n      }\n      if (failure) throw failure;\n      if (done) return;\n      await new Promise<void>((resolve) => {\n        wake = resolve;\n      });\n    }\n  } finally {\n    await handle.close();\n  }\n}\n\n/** Run a command and wait for it (`POST /computers/:id/commands`, up to 600 seconds). */\nexport async function execCommand(\n  miosa: Miosa,\n  computerId: string,\n  command: string,\n  options: MachineCommandOptions = {},\n): Promise<MachineCommandResult> {\n  const computer = await miosa.computers.get(computerId);\n  return computer.runCommand(command, options);\n}\n\n/** Read a UTF-8 file from the computer. */\nexport async function readText(miosa: Miosa, computerId: string, path: string): Promise<string> {\n  const computer = await miosa.computers.get(computerId);\n  return computer.files.readFile(path);\n}\n\n/** Write a UTF-8 file to the computer. */\nexport async function writeText(miosa: Miosa, computerId: string, path: string, content: string): Promise<void> {\n  const computer = await miosa.computers.get(computerId);\n  await computer.files.writeFile(path, content);\n}\n\n/**\n * Stop the computer and destroy it. A computer that is already stopped, or\n * already gone, is not an error, so calling this twice is safe.\n */\nexport async function stopAndRemove(miosa: Miosa, computerId: string): Promise<void> {\n  let computer: Computer;\n  try {\n    computer = await miosa.computers.get(computerId);\n  } catch (error) {\n    if (error instanceof NotFoundError) return;\n    throw error;\n  }\n  if (computer.status !== \"stopped\" && computer.status !== \"destroyed\") {\n    try {\n      await computer.stop();\n    } catch (error) {\n      if (error instanceof NotFoundError) return;\n      // A computer that cannot stop (already stopping) is still destroyed below.\n    }\n  }\n  try {\n    await computer.destroy();\n  } catch (error) {\n    if (!(error instanceof NotFoundError)) throw error;\n  }\n}\n"]}