@cydm/pie 2.6.12 → 2.7.1

package/dist/builtin/skills/computer-use-axi/computer-use-axi-runtime.js

@@ -0,0 +1,728 @@
+#!/usr/bin/env node
+import { createRequire as __createRequire } from "node:module"; const require = __createRequire(import.meta.url);
+
+// vendor/computer-use-axi/src/cli.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { pathToFileURL } from "node:url";
+
+// vendor/computer-use-axi/src/broker-client.ts
+import { spawn } from "node:child_process";
+import { closeSync, existsSync as existsSync2, mkdirSync as mkdirSync2, openSync } from "node:fs";
+import net from "node:net";
+import path3 from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// vendor/computer-use-axi/src/broker-protocol.ts
+import { createHash, randomUUID } from "node:crypto";
+import path2 from "node:path";
+
+// vendor/computer-use-axi/src/persist.ts
+import path from "node:path";
+
+// src/config.ts
+import { existsSync, mkdirSync, readFileSync, renameSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname(__filename);
+var isBunRuntime = !!process.versions.bun;
+function getPackageDir() {
+  const envDir = process.env.PIE_PACKAGE_DIR;
+  if (envDir) {
+    if (envDir === "~") return homedir();
+    if (envDir.startsWith("~/")) return homedir() + envDir.slice(1);
+    return envDir;
+  }
+  let dir = __dirname;
+  while (dir !== dirname(dir)) {
+    if (existsSync(join(dir, "package.json"))) {
+      return dir;
+    }
+    dir = dirname(dir);
+  }
+  return __dirname;
+}
+function getPackageJsonPath() {
+  return join(getPackageDir(), "package.json");
+}
+var pkg = JSON.parse(readFileSync(getPackageJsonPath(), "utf-8"));
+var CONFIG_DIR_NAME = ".pie";
+var VERSION = pkg.version;
+var ENV_AGENT_DIR = "PIE_CODING_AGENT_DIR";
+function getConfigDir() {
+  const envDir = process.env[ENV_AGENT_DIR];
+  if (envDir) {
+    if (envDir === "~") return homedir();
+    if (envDir.startsWith("~/")) return homedir() + envDir.slice(1);
+    return envDir;
+  }
+  return join(homedir(), CONFIG_DIR_NAME);
+}
+
+// vendor/computer-use-axi/src/persist.ts
+function stateRootDir(env = process.env) {
+  const override = env.PIE_COMPUTER_USE_STATE_DIR?.trim();
+  if (override) return override;
+  return path.join(getConfigDir(), "computer-use");
+}
+
+// src/runtime/computer-use-owner.ts
+var COMPUTER_USE_OWNER_ENV = "PIE_COMPUTER_USE_OWNER_ID";
+var COMPUTER_USE_EXECUTION_ENV = "PIE_COMPUTER_USE_EXECUTION_ID";
+var COMPUTER_USE_STANDALONE_OWNER = "standalone";
+var OWNER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,255}$/;
+function normalizeComputerUseOwner(value) {
+  if (typeof value !== "string") return COMPUTER_USE_STANDALONE_OWNER;
+  const trimmed = value.trim();
+  if (!trimmed) return COMPUTER_USE_STANDALONE_OWNER;
+  return OWNER_PATTERN.test(trimmed) ? trimmed : COMPUTER_USE_STANDALONE_OWNER;
+}
+function computerUseOwnerFromEnv(env = process.env) {
+  return normalizeComputerUseOwner(env[COMPUTER_USE_OWNER_ENV]);
+}
+
+// vendor/computer-use-axi/src/broker-protocol.ts
+var BROKER_PROTOCOL_VERSION = 1;
+var BROKER_ENGINE_VERSION = 1;
+var BROKER_PACKAGE_VERSION = "0.5.1-pie.1";
+var BROKER_MAX_FRAME_BYTES = 4 * 1024 * 1024;
+var BROKER_MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+var BROKER_DEFAULT_REQUEST_BUDGET_MS = 12e4;
+var BROKER_MAX_REQUEST_BUDGET_MS = 15 * 6e4;
+var BROKER_IDLE_EXIT_MS = 30 * 6e4;
+var BROKER_HANDSHAKE_TIMEOUT_MS = 3e3;
+function computeBuildIdentity() {
+  const seed = `${BROKER_PROTOCOL_VERSION}:${BROKER_ENGINE_VERSION}:${BROKER_PACKAGE_VERSION}`;
+  return {
+    version: BROKER_PACKAGE_VERSION,
+    identity: createHash("sha256").update(seed).digest("hex").slice(0, 16)
+  };
+}
+var BROKER_BUILD = computeBuildIdentity();
+var BrokerProtocolError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "BrokerProtocolError";
+  }
+  code;
+};
+function encodeFrame(value, maxBytes = BROKER_MAX_FRAME_BYTES) {
+  let json;
+  try {
+    json = JSON.stringify(value);
+  } catch (error) {
+    throw new BrokerProtocolError("encode_failed", error instanceof Error ? error.message : String(error));
+  }
+  const bytes = Buffer.byteLength(json, "utf8");
+  if (bytes > maxBytes) throw new BrokerProtocolError("frame_too_large", `Frame of ${bytes} bytes exceeds the ${maxBytes}-byte limit.`);
+  return Buffer.from(`${json}
+`, "utf8");
+}
+var FrameDecoder = class {
+  constructor(maxBytes = BROKER_MAX_FRAME_BYTES) {
+    this.maxBytes = maxBytes;
+  }
+  maxBytes;
+  buffer = Buffer.alloc(0);
+  push(chunk) {
+    this.buffer = this.buffer.length === 0 ? chunk : Buffer.concat([this.buffer, chunk]);
+    const frames = [];
+    for (; ; ) {
+      const newline = this.buffer.indexOf(10);
+      if (newline < 0) break;
+      const line = this.buffer.subarray(0, newline).toString("utf8").trim();
+      this.buffer = this.buffer.subarray(newline + 1);
+      if (!line) continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        throw new BrokerProtocolError("invalid_json", "Frame is not valid JSON.");
+      }
+      frames.push(parsed);
+    }
+    if (this.buffer.length > this.maxBytes) {
+      throw new BrokerProtocolError("frame_too_large", `Unterminated frame exceeds the ${this.maxBytes}-byte limit.`);
+    }
+    return frames;
+  }
+};
+function resolveBrokerEndpoint(env = process.env) {
+  const socketOverride = env.PIE_COMPUTER_USE_BROKER_SOCKET?.trim();
+  if (process.platform === "win32") {
+    const seed = socketOverride || stateRootDir(env);
+    const key = createHash("sha256").update(seed).digest("hex").slice(0, 16);
+    return { kind: "named-pipe", path: `\\\\.\\pipe\\pie-computer-use-axi-${key}` };
+  }
+  const socketPath = socketOverride || path2.join(stateRootDir(env), "run", "broker.sock");
+  if (Buffer.byteLength(socketPath, "utf8") > 100) {
+    throw new BrokerProtocolError("endpoint_too_long", `Unix socket path is ${Buffer.byteLength(socketPath)} bytes (limit ~104): ${socketPath}. Set PIE_COMPUTER_USE_BROKER_SOCKET to a shorter path.`);
+  }
+  return { kind: "unix-socket", path: socketPath, directory: path2.dirname(socketPath) };
+}
+
+// vendor/computer-use-axi/src/broker-client.ts
+var BrokerCallError = class extends Error {
+  constructor(code, message, options = {}) {
+    super(message);
+    this.code = code;
+    this.options = options;
+    this.name = "BrokerCallError";
+  }
+  code;
+  options;
+};
+var SocketFrames = class {
+  constructor(socket) {
+    this.socket = socket;
+    socket.on("data", (chunk) => {
+      try {
+        for (const frame of this.decoder.push(chunk)) {
+          const waiter = this.waiters.shift();
+          if (waiter) waiter(frame);
+          else this.queue.push(frame);
+        }
+      } catch {
+        this.close();
+      }
+    });
+    socket.on("error", () => this.close());
+    socket.on("close", () => this.close());
+  }
+  socket;
+  decoder = new FrameDecoder();
+  queue = [];
+  waiters = [];
+  closed = false;
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    for (const waiter of this.waiters.splice(0)) waiter(null);
+  }
+  next(timeoutMs) {
+    const queued = this.queue.shift();
+    if (queued !== void 0) return Promise.resolve(queued);
+    if (this.closed) return Promise.resolve(null);
+    return new Promise((resolve2) => {
+      const timer = setTimeout(() => {
+        const index = this.waiters.indexOf(waiter);
+        if (index >= 0) this.waiters.splice(index, 1);
+        resolve2(null);
+      }, timeoutMs);
+      const waiter = (value) => {
+        clearTimeout(timer);
+        resolve2(value);
+      };
+      this.waiters.push(waiter);
+    });
+  }
+};
+function tryConnect(endpoint, timeoutMs = 600) {
+  return new Promise((resolve2) => {
+    const socket = net.createConnection(endpoint.path);
+    const timer = setTimeout(() => {
+      socket.destroy();
+      resolve2(void 0);
+    }, timeoutMs);
+    socket.once("connect", () => {
+      clearTimeout(timer);
+      resolve2(socket);
+    });
+    socket.once("error", () => {
+      clearTimeout(timer);
+      resolve2(void 0);
+    });
+  });
+}
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+function resolveBrokerSpawn() {
+  const here = path3.dirname(fileURLToPath2(import.meta.url));
+  const override = process.env.PIE_COMPUTER_USE_BROKER_ENTRY?.trim();
+  const candidates = [
+    override,
+    path3.join(here, "computer-use-axi-broker.js"),
+    path3.join(here, "broker-main.ts")
+  ].filter((candidate) => Boolean(candidate));
+  for (const candidate of candidates) {
+    if (!existsSync2(candidate)) continue;
+    if (candidate.endsWith(".ts")) return { file: process.execPath, args: ["--import", "tsx", candidate] };
+    return { file: process.execPath, args: [candidate] };
+  }
+  throw new BrokerCallError("broker_entry_missing", "Pie's computer-use broker entry is missing. Rebuild or reinstall Pie.", { exitCode: 1 });
+}
+function spawnBroker() {
+  const command = resolveBrokerSpawn();
+  let stdio = "ignore";
+  let logFd;
+  try {
+    const logDir = path3.join(stateRootDir(), "broker");
+    mkdirSync2(logDir, { recursive: true, mode: 448 });
+    logFd = openSync(path3.join(logDir, "broker.log"), "a", 384);
+    stdio = ["ignore", logFd, logFd];
+  } catch {
+    stdio = "ignore";
+  }
+  const child = spawn(command.file, command.args, {
+    detached: true,
+    stdio,
+    env: process.env,
+    windowsHide: true
+  });
+  if (logFd !== void 0) {
+    try {
+      closeSync(logFd);
+    } catch {
+    }
+  }
+  child.on("error", () => {
+  });
+  child.unref();
+  return { pid: child.pid };
+}
+async function connectOrSpawn(endpoint, spawnIfMissing, spawnState) {
+  const existing = await tryConnect(endpoint);
+  if (existing) return existing;
+  if (!spawnIfMissing) {
+    throw new BrokerCallError("broker_not_running", `No computer-use broker is running at ${endpoint.path}.`, { exitCode: 0 });
+  }
+  if (!spawnState.spawned) {
+    spawnState.spawned = true;
+    spawnState.pid = spawnBroker().pid;
+  }
+  const deadline = Date.now() + 12e3;
+  while (Date.now() < deadline) {
+    const socket = await tryConnect(endpoint, 500);
+    if (socket) return socket;
+    await sleep(120);
+  }
+  throw new BrokerCallError(
+    "broker_unavailable",
+    `The local computer-use broker did not become available at ${endpoint.path}${spawnState.pid ? ` (spawned pid ${spawnState.pid})` : ""}. Run 'computer-use-axi status' or inspect the broker log.`,
+    { exitCode: 1 }
+  );
+}
+function isBrokerResponse(value) {
+  return Boolean(value) && typeof value === "object" && value.type === "response";
+}
+async function callBroker(options) {
+  const endpoint = resolveBrokerEndpoint();
+  const budgetMs = Math.min(Math.max(options.budgetMs ?? BROKER_DEFAULT_REQUEST_BUDGET_MS, 100), 15 * 6e4);
+  const spawnState = { spawned: false };
+  const control = options.command === "status" || options.command === "stop";
+  const drainRetryDeadline = Date.now() + 45e3;
+  for (; ; ) {
+    const socket = await connectOrSpawn(endpoint, options.spawnIfMissing !== false, spawnState);
+    const frames = new SocketFrames(socket);
+    try {
+      socket.write(encodeFrame({ type: "hello", protocolVersion: BROKER_PROTOCOL_VERSION, clientVersion: "cli" }));
+      const helloFrame = await frames.next(BROKER_HANDSHAKE_TIMEOUT_MS);
+      if (!helloFrame || typeof helloFrame !== "object" || helloFrame.type !== "hello") {
+        throw new BrokerCallError("broker_no_handshake", "The computer-use broker did not answer the protocol handshake.", { exitCode: 1 });
+      }
+      const hello = helloFrame;
+      if (hello.ok === false) {
+        if (hello.error.code === "broker_draining") {
+          if (options.command === "status") {
+            throw new BrokerCallError("broker_draining", "The computer-use broker is shutting down and draining in-flight work; status is unavailable until it exits.", { exitCode: 0 });
+          }
+          if (!control) {
+            socket.destroy();
+            if (Date.now() >= drainRetryDeadline) {
+              throw new BrokerCallError("broker_draining", "The computer-use broker is still draining in-flight work; no request was sent. Retry shortly.", { exitCode: 1 });
+            }
+            await sleep(150);
+            continue;
+          }
+        }
+        if (options.command !== "stop") {
+          const pidHint = hello.pid ? ` (pid ${hello.pid})` : "";
+          throw new BrokerCallError(
+            "broker_incompatible",
+            `A different computer-use broker is already running${pidHint}: ${hello.error.message}. Run 'computer-use-axi stop' to restart it safely, then retry. Refusing to start a second execution authority.`,
+            { exitCode: 3, incompatible: true, brokerPid: hello.pid }
+          );
+        }
+      }
+      const brokerProtocol = hello.protocolVersion ?? BROKER_PROTOCOL_VERSION;
+      const request = {
+        type: "request",
+        protocolVersion: brokerProtocol,
+        requestId: options.requestId,
+        ownerId: options.ownerId,
+        executionId: options.executionId,
+        command: options.command,
+        params: options.params,
+        cwd: options.cwd,
+        budgetMs
+      };
+      socket.write(encodeFrame(request));
+      const responseTimeout = budgetMs + 15e3;
+      for (; ; ) {
+        const frame = await frames.next(responseTimeout);
+        if (!frame) {
+          throw new BrokerCallError(
+            "outcome_unknown",
+            "The broker connection closed before a result arrived. The native action may have been dispatched; do not replay it. Run 'computer-use-axi observe' to establish a successor state.",
+            { exitCode: 1, dispatched: true, outcomeUnknown: true, brokerPid: hello.pid }
+          );
+        }
+        if (!isBrokerResponse(frame)) continue;
+        if (frame.requestId !== options.requestId) continue;
+        if (frame.state === "in-flight") {
+          throw new BrokerCallError(
+            "request_in_flight",
+            "This requestId is already in flight in the broker. Wait for its original result instead of dispatching again.",
+            { exitCode: 1, dispatched: true, brokerPid: hello.pid }
+          );
+        }
+        if (frame.state === "outcome-unknown") {
+          return { state: "outcome-unknown", result: frame.result, generation: frame.generation, helperGeneration: frame.helperGeneration, brokerPid: hello.pid };
+        }
+        if (frame.state === "error" || frame.ok === false) {
+          throw new BrokerCallError(frame.error?.code ?? "broker_error", frame.error?.message ?? "The computer-use broker rejected the request.", {
+            exitCode: 1,
+            dispatched: frame.error?.dispatched,
+            brokerPid: hello.pid
+          });
+        }
+        return { state: "done", result: frame.result, generation: frame.generation, helperGeneration: frame.helperGeneration, brokerPid: hello.pid };
+      }
+    } finally {
+      socket.destroy();
+    }
+  }
+}
+
+// vendor/computer-use-axi/src/cli.ts
+var USAGE = `computer-use-axi \u2014 desktop & browser UI automation
+
+Lifecycle: roots -> observe (returns stateId) -> search/expand/inspect -> act.
+@r refs come from roots; @e refs + stateId come from observe/search;
+@o refs continue long truncated output via read.
+
+Commands:
+  roots   [--text T] [--app A] [--bundle-id B] [--pid N] [--kind K]
+  observe [--root @rN] [--mode semantic|visual|fused]
+  search  --state S (--text T | --role R | --capability C)
+  expand  --state S --ref @eN [--depth 1-8]
+  inspect --state S --ref @eN
+  read    --ref @oN|--eN [--offset BYTES] [--state S]
+  wait    --state S (--text T | --role R | --ref @eN) [--until present|absent]
+          [--scope-ref @eN] [--value V] [--timeout-ms MS]
+  act     --state S --actions '<JSON array>' [--expect '<JSON object>']
+  browser launch [--url U]
+  browser navigate --state S --url U
+  browser eval --state S --expr '<JavaScript>'
+  status  Show the local broker status (never starts one)
+  stop    Stop the local broker and release processes it owns
+
+Options:
+  --json          Print { content, details, isError } as JSON
+  --request-id ID Reuse an id to retrieve the same result (at-most-once)
+  --owner ID      Opaque session identity (defaults to the standalone namespace)
+  --help, -h      Show this help
+
+Environment:
+  PIE_COMPUTER_USE_OWNER_ID       Set by the Pie bash tool at spawn time
+  PIE_COMPUTER_USE_AXI_TIMEOUT_MS Per-command broker budget (default 120000)
+
+Examples:
+  computer-use-axi roots --app Finder
+  computer-use-axi observe --root @r1 --mode visual
+  computer-use-axi search --state S1 --text Save
+  computer-use-axi act --state S1 --actions '[{"action":"press","ref":"@e12"}]'
+  computer-use-axi read --ref @o1 --offset 16384`;
+var FLAG_ALIASES = {
+  "-h": "--help",
+  "--state-id": "--state",
+  "--window": "--root",
+  "--capability-filter": "--capability",
+  "--scope": "--scope-ref",
+  "--timeout": "--timeout-ms",
+  "--expression": "--expr"
+};
+function parseArgs(argv) {
+  const rest = [];
+  const flags = /* @__PURE__ */ new Map();
+  let command = "";
+  let json = false;
+  let help = false;
+  const booleanFlags = /* @__PURE__ */ new Set(["--json", "--help"]);
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    const alias = FLAG_ALIASES[token] ?? token;
+    if (!alias.startsWith("-")) {
+      if (!command) command = token;
+      else rest.push(token);
+      continue;
+    }
+    if (alias === "--json") {
+      json = true;
+      continue;
+    }
+    if (alias === "--help") {
+      help = true;
+      continue;
+    }
+    let key = alias;
+    let value;
+    const eq = alias.indexOf("=");
+    if (eq >= 0) {
+      key = alias.slice(0, eq);
+      value = alias.slice(eq + 1);
+    }
+    if (!booleanFlags.has(key) && value === void 0) {
+      const next = argv[i + 1];
+      if (next !== void 0 && !next.startsWith("-")) {
+        value = next;
+        i += 1;
+      }
+    }
+    flags.set(key, value ?? "");
+  }
+  return { command, flags, json, help, rest };
+}
+function requiredFlag(args, name) {
+  const value = args.flags.get(name);
+  if (value === void 0 || value === "") usageError(`missing required option ${name}`);
+  return value;
+}
+function optionalFlag(args, name) {
+  const value = args.flags.get(name);
+  return value === void 0 || value === "" ? void 0 : value;
+}
+function numericFlag(args, name) {
+  const value = optionalFlag(args, name);
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) usageError(`${name} must be a number (got '${value}')`);
+  return parsed;
+}
+function jsonFlag(args, name) {
+  const value = requiredFlag(args, name);
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    usageError(`${name} must be valid JSON (${error.message})`);
+  }
+}
+function usageError(message) {
+  process.stderr.write(`computer-use-axi: ${message}
+
+${USAGE}
+`);
+  process.exit(2);
+}
+function buildCommand(args) {
+  if (args.command === "browser") {
+    const sub = args.rest[0] ?? usageError("browser requires a subcommand: launch | navigate | eval");
+    if (sub === "launch") return { command: "launch_browser", params: { url: optionalFlag(args, "--url") } };
+    if (sub === "navigate") return { command: "navigate_browser", params: { stateId: requiredFlag(args, "--state"), url: requiredFlag(args, "--url") } };
+    if (sub === "eval") return { command: "evaluate_browser", params: { stateId: requiredFlag(args, "--state"), expression: requiredFlag(args, "--expr") } };
+    usageError(`unknown browser subcommand '${sub}' (expected launch | navigate | eval)`);
+  }
+  switch (args.command) {
+    case "status":
+      return { command: "status", params: {} };
+    case "stop":
+      return { command: "stop", params: {} };
+    case "roots":
+      return {
+        command: "find_roots",
+        params: {
+          text: optionalFlag(args, "--text"),
+          app: optionalFlag(args, "--app"),
+          bundleId: optionalFlag(args, "--bundle-id"),
+          pid: numericFlag(args, "--pid"),
+          kind: optionalFlag(args, "--kind")
+        }
+      };
+    case "observe":
+      return {
+        command: "observe_ui",
+        params: { root: optionalFlag(args, "--root"), mode: optionalFlag(args, "--mode") }
+      };
+    case "search": {
+      const params = {
+        text: optionalFlag(args, "--text"),
+        role: optionalFlag(args, "--role"),
+        capability: optionalFlag(args, "--capability"),
+        stateId: requiredFlag(args, "--state")
+      };
+      if (!params.text && !params.role && !params.capability) usageError("search requires at least one of --text, --role, --capability");
+      return { command: "search_ui", params };
+    }
+    case "expand":
+      return { command: "expand_ui", params: { stateId: requiredFlag(args, "--state"), ref: requiredFlag(args, "--ref"), depth: numericFlag(args, "--depth") } };
+    case "inspect":
+      return { command: "inspect_ui", params: { stateId: requiredFlag(args, "--state"), ref: requiredFlag(args, "--ref") } };
+    case "read": {
+      const ref = requiredFlag(args, "--ref");
+      const params = { ref, offset: numericFlag(args, "--offset") };
+      if (ref.startsWith("@e")) params.stateId = requiredFlag(args, "--state");
+      else params.stateId = optionalFlag(args, "--state");
+      return { command: "read_text", params };
+    }
+    case "wait": {
+      const params = {
+        stateId: requiredFlag(args, "--state"),
+        text: optionalFlag(args, "--text"),
+        role: optionalFlag(args, "--role"),
+        value: optionalFlag(args, "--value"),
+        ref: optionalFlag(args, "--ref"),
+        scopeRef: optionalFlag(args, "--scope-ref"),
+        until: optionalFlag(args, "--until"),
+        timeoutMs: numericFlag(args, "--timeout-ms")
+      };
+      if (!params.text && !params.role && !params.ref && !params.value) usageError("wait requires at least one of --text, --role, --value, --ref");
+      if (params.role && !params.text && !params.value && !params.ref && !params.scopeRef) usageError("wait --role requires --ref or --scope-ref (role-only conditions must be scoped)");
+      if (params.value && !params.ref) usageError("wait --value requires --ref (exact element value checks need an exact ref)");
+      return { command: "wait_for", params };
+    }
+    case "act": {
+      const actions = jsonFlag(args, "--actions");
+      if (!Array.isArray(actions) || actions.length === 0) usageError("--actions must be a non-empty JSON array");
+      const params = { stateId: requiredFlag(args, "--state"), actions };
+      const expect = optionalFlag(args, "--expect");
+      if (expect !== void 0) {
+        try {
+          params.expect = JSON.parse(expect);
+        } catch (error) {
+          usageError(`--expect must be valid JSON (${error.message})`);
+        }
+      }
+      return { command: "act_ui", params };
+    }
+    default:
+      usageError(args.command ? `unknown command '${args.command}'` : "missing command");
+  }
+}
+function adaptGuidance(text) {
+  return text.replace(/observe_ui\(\{ root: "(@r\d+)" \}\)/g, "computer-use-axi observe --root $1").replace(/read_text\(\{ ref: "(@o\d+)", offset: (\d+) \}\)/g, "computer-use-axi read --ref $1 --offset $2").replace(/read_text\(\{ ref: "(@o\d+)" \}\)/g, "computer-use-axi read --ref $1").replace(/\bfind_roots\b/g, "computer-use-axi roots").replace(/\bobserve_ui\b/g, "computer-use-axi observe").replace(/\bsearch_ui\b/g, "computer-use-axi search").replace(/\bexpand_ui\b/g, "computer-use-axi expand").replace(/\binspect_ui\b/g, "computer-use-axi inspect").replace(/\bread_text\b/g, "computer-use-axi read").replace(/\bwait_for\b/g, "computer-use-axi wait").replace(/\bact_ui\b/g, "computer-use-axi act").replace(/\blaunch_browser\b/g, "computer-use-axi browser launch").replace(/\bnavigate_browser\b/g, "computer-use-axi browser navigate").replace(/\bevaluate_browser\b/g, "computer-use-axi browser eval").replace(/computer-use-axi observe\(\{ root: "([^"]+)" \}\)/g, 'computer-use-axi observe --root "$1"');
+}
+function renderText(result) {
+  const text = (result.content ?? []).map((part) => part.type === "text" && typeof part.text === "string" ? part.text : void 0).filter(Boolean).join("\n");
+  if (text) return adaptGuidance(text);
+  if ((result.content ?? []).some((part) => part.type === "image")) {
+    return "(image-only observation; use --mode semantic for a text outline or --json for raw content)";
+  }
+  return "";
+}
+function renderStatus(value) {
+  if (!value || typeof value !== "object") return JSON.stringify(value);
+  const status = value;
+  const artifacts = status.artifacts ?? {};
+  const legacy = status.legacyCache ?? {};
+  return [
+    "computer-use broker: running",
+    `pid: ${status.pid}`,
+    `generation: ${status.generation}`,
+    `helper generation: ${status.helperGeneration}`,
+    `build: ${status.build?.version} (${status.build?.identity})`,
+    `protocol: ${status.protocolVersion}`,
+    `endpoint: ${status.endpoint?.kind} ${status.endpoint?.path}`,
+    `transport security: ${status.transportAcl}`,
+    `uptime: ${Math.round((status.uptimeMs ?? 0) / 1e3)}s`,
+    `active: ${status.active}, queued: ${status.queued}, uncertain: ${status.uncertain}, cached requests: ${status.requests}`,
+    `owners: ${status.ownerCount ?? 0} (fingerprints: ${(status.ownerFingerprints ?? []).join(", ") || "none"})`,
+    `artifacts: ${artifacts.count ?? 0} files, ${artifacts.bytes ?? 0} bytes (max ${artifacts.maxCount ?? "?"} / ${artifacts.maxBytes ?? "?"} bytes)`,
+    `legacy cache cleared at startup: runtime.json=${legacy.runtimeFile ? "yes" : "no"}, states=${legacy.states ?? 0}, outputs=${legacy.outputs ?? 0}`,
+    `idle exit: ${Math.round((status.idleExitMs ?? 0) / 6e4)} minutes`
+  ].join("\n");
+}
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || !args.command && args.flags.size === 0) {
+    process.stdout.write(`${USAGE}
+`);
+    return 0;
+  }
+  const { command, params } = buildCommand(args);
+  const ownerId = normalizeComputerUseOwner(optionalFlag(args, "--owner") ?? computerUseOwnerFromEnv());
+  const executionId = optionalFlag(args, "--execution-id") ?? process.env[COMPUTER_USE_EXECUTION_ENV];
+  const requestId = optionalFlag(args, "--request-id") ?? randomUUID2();
+  const envBudget = Number(process.env.PIE_COMPUTER_USE_AXI_TIMEOUT_MS);
+  const budgetMs = Number.isFinite(envBudget) && envBudget > 0 ? envBudget : void 0;
+  const control = command === "status" || command === "stop";
+  try {
+    const outcome = await callBroker({
+      command,
+      params,
+      ownerId: ownerId === COMPUTER_USE_STANDALONE_OWNER ? ownerId : ownerId,
+      executionId,
+      requestId,
+      cwd: process.cwd(),
+      budgetMs,
+      spawnIfMissing: !control
+    });
+    if (outcome.state === "outcome-unknown") {
+      const message = `Outcome unknown (generation ${outcome.generation ?? "unknown"}). The native action may have been dispatched; do not replay it. Observe the resource again to establish a successor state.`;
+      if (args.json) process.stdout.write(`${JSON.stringify({ content: [{ type: "text", text: message }], isError: true, state: outcome.state, generation: outcome.generation, helperGeneration: outcome.helperGeneration })}
+`);
+      else process.stderr.write(`${message}
+`);
+      return 1;
+    }
+    const result = outcome.result ?? {};
+    if (args.json) {
+      const payload = command === "status" ? { ...result, broker: { requestId, owner: ownerId, generation: outcome.generation, state: outcome.state } } : { ...result, broker: { requestId, owner: ownerId, generation: outcome.generation, state: outcome.state } };
+      process.stdout.write(`${JSON.stringify(payload)}
+`);
+    } else if (command === "status") {
+      process.stdout.write(`${renderStatus(result)}
+`);
+    } else if (command === "stop") {
+      process.stdout.write("computer-use broker stop requested; owned processes are being released.\n");
+    } else {
+      const text = renderText(result);
+      if (text) process.stdout.write(`${text}
+`);
+    }
+    return result.isError ? 1 : 0;
+  } catch (error) {
+    if (error instanceof BrokerCallError && error.code === "broker_not_running") {
+      if (args.json) process.stdout.write(`${JSON.stringify({ running: false, content: [{ type: "text", text: error.message }] })}
+`);
+      else process.stdout.write(`${control ? "No computer-use broker is running" : error.message}.
+`);
+      return 0;
+    }
+    const brokerError = error instanceof BrokerCallError ? error : void 0;
+    const message = adaptGuidance(error instanceof Error ? error.message : String(error));
+    if (args.json) {
+      process.stdout.write(`${JSON.stringify({ content: [{ type: "text", text: message }], isError: true, ...brokerError ? { error: { code: brokerError.code, dispatched: brokerError.options.dispatched ?? false } } : {} })}
+`);
+    } else {
+      process.stderr.write(`${message}
+`);
+    }
+    return brokerError?.options.exitCode ?? 1;
+  }
+}
+var isDirectEntry = (() => {
+  try {
+    return import.meta.url === pathToFileURL(process.argv[1]).href;
+  } catch {
+    return false;
+  }
+})();
+if (isDirectEntry) {
+  main().then((code) => {
+    process.exitCode = code;
+  }).catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}
+`);
+    process.exitCode = 1;
+  });
+}
+export {
+  USAGE,
+  adaptGuidance,
+  buildCommand,
+  parseArgs,
+  usageError
+};