machine-bridge-mcp 0.15.0 → 0.16.0

package/src/local/call-registry.mjs

@@ -0,0 +1,113 @@
+import { randomBytes } from "node:crypto";
+import { BridgeError } from "./errors.mjs";
+
+export class CallRegistry {
+  constructor(options = {}) {
+    this.maximum = positiveInteger(options.maximum, 16);
+    this.now = typeof options.now === "function" ? options.now : Date.now;
+    this.scheduler = options.scheduler || { setTimeout, clearTimeout };
+    this.onCancel = typeof options.onCancel === "function" ? options.onCancel : () => {};
+    this.onFinish = typeof options.onFinish === "function" ? options.onFinish : () => {};
+    this.calls = new Map();
+  }
+
+  open({ callId = "", tool = "", origin = "local", timeoutMs = 0 } = {}) {
+    const id = String(callId || `call_${randomBytes(16).toString("hex")}`);
+    if (this.calls.has(id)) throw new BridgeError("conflict", "duplicate in-flight call id");
+    if (this.calls.size >= this.maximum) throw new BridgeError("limit_exceeded", `too many concurrent tool calls (${this.maximum})`, { retryable: true });
+    const controller = new AbortController();
+    const startedAt = this.now();
+    const timeout = positiveInteger(timeoutMs, 0);
+    const record = {
+      id,
+      tool: String(tool || ""),
+      origin: String(origin || "local"),
+      startedAt,
+      deadlineAt: timeout ? startedAt + timeout : null,
+      controller,
+      cancelReason: "",
+      timer: null,
+    };
+    if (timeout) {
+      record.timer = this.scheduler.setTimeout(() => this.cancel(id, "deadline exceeded", "timeout"), timeout);
+      record.timer?.unref?.();
+    }
+    this.calls.set(id, record);
+    return Object.freeze({
+      callId: id,
+      tool: record.tool,
+      origin: record.origin,
+      startedAt,
+      deadlineAt: record.deadlineAt,
+      signal: controller.signal,
+    });
+  }
+
+  cancel(callId, reason = "cancelled", code = "cancelled") {
+    const record = this.calls.get(String(callId || ""));
+    if (!record || record.controller.signal.aborted) return false;
+    record.cancelReason = String(reason || "cancelled").slice(0, 256);
+    record.controller.abort(new BridgeError(code, code === "timeout" ? "tool call timed out" : "tool call cancelled"));
+    this.onCancel(record);
+    return true;
+  }
+
+  finish(callId) {
+    const id = String(callId || "");
+    const record = this.calls.get(id);
+    if (!record) return false;
+    if (record.timer) this.scheduler.clearTimeout(record.timer);
+    this.calls.delete(id);
+    this.onFinish(record);
+    return true;
+  }
+
+  cancelAll(reason = "runtime stopped") {
+    for (const id of [...this.calls.keys()]) {
+      this.cancel(id, reason);
+      this.finish(id);
+    }
+  }
+
+  context(callId) {
+    const record = this.calls.get(String(callId || ""));
+    if (!record) return null;
+    return {
+      callId: record.id,
+      tool: record.tool,
+      origin: record.origin,
+      startedAt: record.startedAt,
+      deadlineAt: record.deadlineAt,
+      signal: record.controller.signal,
+    };
+  }
+
+  throwIfCancelled(context = {}) {
+    const signal = context.signal || this.calls.get(String(context.callId || ""))?.controller.signal;
+    if (!signal?.aborted) return;
+    const reason = signal.reason;
+    if (reason instanceof Error) throw reason;
+    throw new BridgeError("cancelled", "tool call cancelled");
+  }
+
+  snapshot() {
+    const now = this.now();
+    const byOrigin = {};
+    let oldestMs = 0;
+    for (const call of this.calls.values()) {
+      byOrigin[call.origin] = (byOrigin[call.origin] || 0) + 1;
+      oldestMs = Math.max(oldestMs, now - call.startedAt);
+    }
+    return {
+      active: this.calls.size,
+      maximum: this.maximum,
+      by_origin: byOrigin,
+      oldest_ms: oldestMs,
+    };
+  }
+}
+
+function positiveInteger(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
+}

package/src/local/capability-ranking.mjs

@@ -0,0 +1,103 @@
+const TOKEN_STOP_WORDS = new Set(["the", "and", "for", "with", "from", "this", "that", "use", "using", "into", "of", "to", "a", "an", "in", "on", "is", "are", "or", "及", "和", "的", "了", "在", "用", "使用", "进行", "根据"]);
+const ENGLISH_TOKEN_CANONICAL = new Map([
+  ["created", "create"], ["creating", "create"], ["creation", "create"], ["creator", "create"],
+  ["improved", "improve"], ["improving", "improve"], ["improvement", "improve"],
+  ["installed", "install"], ["installing", "install"], ["installation", "install"], ["installer", "install"],
+  ["searched", "search"], ["searching", "search"], ["finder", "find"],
+  ["documentation", "docs"], ["document", "docs"], ["documents", "docs"],
+  ["validated", "verify"], ["validate", "verify"], ["validation", "verify"], ["verification", "verify"],
+  ["factcheck", "verify"], ["fact-check", "verify"], ["testing", "test"], ["tests", "test"],
+  ["building", "build"], ["built", "build"], ["deployment", "deploy"], ["deployed", "deploy"],
+]);
+const HAN_TOKEN_ALIASES = Object.freeze([
+  [/创建|新建|编写/u, ["create", "creator"]],
+  [/改进|优化|更新|维护/u, ["improve", "update"]],
+  [/技能/u, ["skill"]],
+  [/安装/u, ["install", "installer"]],
+  [/部署/u, ["deploy", "deployment"]],
+  [/查找|搜索|检索/u, ["search", "find"]],
+  [/最新|当前/u, ["latest", "current"]],
+  [/官方/u, ["official"]],
+  [/文档|资料/u, ["docs", "documentation"]],
+  [/事实核查|核查|验证|校验/u, ["verify", "factcheck"]],
+  [/测试/u, ["test"]],
+  [/前端/u, ["frontend"]],
+  [/设计/u, ["design"]],
+  [/邮件|邮箱/u, ["email"]],
+  [/浏览器|网页|网站/u, ["browser", "web"]],
+  [/性能/u, ["performance"]],
+  [/安全|漏洞/u, ["security", "audit"]],
+]);
+
+export function commandMatchText(command) {
+  return `${command.name} ${command.description} ${command.argv.join(" ")} ${command.searchTerms || ""}`;
+}
+
+export function relevanceScore(task, candidate, identity = "") {
+  const taskTokens = tokenize(task);
+  const candidateTokens = tokenize(candidate);
+  if (!taskTokens.size || !candidateTokens.size) return 0;
+  const identityTokens = tokenize(identity);
+  let score = 0;
+  for (const token of taskTokens) {
+    if (candidateTokens.has(token)) score += token.length >= 6 ? 2 : 1;
+    if (identityTokens.has(token)) score += token.length >= 6 ? 4 : 3;
+  }
+  const taskComparable = comparableText(task);
+  const candidateComparable = comparableText(candidate);
+  const identityComparable = comparableText(identity);
+  if (candidateComparable.includes(taskComparable) || taskComparable.includes(candidateComparable)) score += 4;
+  if (identityComparable.length >= 3 && ` ${taskComparable} `.includes(` ${identityComparable} `)) score += 12;
+  return score;
+}
+
+export function recommendTools(task, { commandsAvailable, commandRelevant, skillRelevant }) {
+  const lower = String(task || "").toLowerCase();
+  const tools = ["agent_context"];
+  if (skillRelevant) tools.push("load_local_skill");
+  if (commandRelevant) tools.push("run_local_command");
+  if (/browser|chrome|edge|brave|网页|浏览器|表单|网站/.test(lower)) tools.push("browser_status", "browser_list_tabs", "browser_manage_tabs", "browser_inspect_page", "browser_wait", "browser_action", "browser_fill_form");
+  if (/app|application|gui|window|应用|软件|窗口|界面/.test(lower)) tools.push("list_local_applications", "inspect_local_application", "operate_local_application");
+  if (/git|commit|branch|diff|仓库|提交|分支/.test(lower)) tools.push("git_status", "git_diff");
+  if (/test|build|lint|command|terminal|测试|构建|命令|终端/.test(lower)) tools.push(commandsAvailable ? "run_local_command" : "run_process");
+  if (/file|code|source|edit|write|文件|代码|源码|修改|写入/.test(lower)) tools.push("read_file", "search_text", "edit_file", "apply_patch");
+  return [...new Set(tools)];
+}
+
+export function tokenize(value) {
+  const text = String(value || "").toLowerCase();
+  const tokens = new Set();
+  for (const raw of text.match(/[a-z0-9_][a-z0-9_.-]{1,}/g) || []) {
+    const token = raw.replace(/^[.-]+|[.-]+$/g, "");
+    addToken(tokens, token);
+    for (const part of token.split(/[._-]+/)) addToken(tokens, part);
+  }
+  for (const sequence of text.match(/[\p{Script=Han}]{1,}/gu) || []) {
+    addToken(tokens, sequence);
+    const minimumSize = sequence.length === 1 ? 1 : 2;
+    for (let size = minimumSize; size <= Math.min(3, sequence.length); size += 1) {
+      for (let index = 0; index + size <= sequence.length; index += 1) addToken(tokens, sequence.slice(index, index + size));
+    }
+  }
+  for (const [pattern, aliases] of HAN_TOKEN_ALIASES) {
+    if (!pattern.test(text)) continue;
+    for (const alias of aliases) addToken(tokens, alias);
+  }
+  return tokens;
+}
+
+function comparableText(value) {
+  return String(value || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9\p{Script=Han}]+/gu, " ")
+    .trim()
+    .replace(/\s+/g, " ");
+}
+
+function addToken(tokens, raw) {
+  const token = String(raw || "").replace(/^[.-]+|[.-]+$/g, "");
+  if (token.length < 2 || TOKEN_STOP_WORDS.has(token)) return;
+  tokens.add(token);
+  const canonical = ENGLISH_TOKEN_CANONICAL.get(token);
+  if (canonical) tokens.add(canonical);
+}

package/src/local/cli-local-admin.mjs

@@ -0,0 +1,308 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import process from "node:process";
+import { createLogger } from "./log.mjs";
+import { inspectResourceFile, loadManagedJobPlan, ManagedJobManager, publicResourceRegistry, validateResourceName } from "./managed-jobs.mjs";
+import { generateRegisteredSshKey } from "./resource-operations.mjs";
+import { readBoundedRegularFileSync } from "./secure-file.mjs";
+import {
+  acquireStartupLockWithWait, expandHome, loadState, ownerOnlyFile, packageRoot, saveState,
+} from "./state.mjs";
+import { resolvePolicy } from "./cli-policy.mjs";
+
+export function createLocalAdminCommands(dependencies) {
+  const chooseWorkspace = dependencies.chooseWorkspace;
+  const confirm = dependencies.confirm;
+  if (typeof chooseWorkspace !== "function" || typeof confirm !== "function") {
+    throw new TypeError("local admin commands require chooseWorkspace and confirm dependencies");
+  }
+  const context = Object.freeze({ chooseWorkspace, confirm });
+  return Object.freeze({
+    resourceCommand: (args) => resourceCommand(args, context),
+    browserCommand: (args) => browserCommand(args, context),
+    jobCommand: (args) => jobCommand(args, context),
+  });
+}
+
+const RESOURCE_ACTION_HANDLERS = Object.freeze({
+  list: resourceListAction,
+  add: resourceAddAction,
+  "generate-ssh-key": resourceGenerateSshKeyAction,
+  remove: resourceRemoveAction,
+  check: resourceCheckAction,
+});
+
+async function resourceCommand(args, { chooseWorkspace }) {
+  const action = String(args._[0] || "list").toLowerCase();
+  const handler = RESOURCE_ACTION_HANDLERS[action];
+  if (!handler) throw new Error(`Unknown resource action: ${action}`);
+  const workspace = await chooseWorkspace({ ...args, _: [] }, { promptOnFirstRun: false, save: false, allowPositional: false });
+  const state = loadState(workspace, { stateDir: args.stateDir });
+  state.resources ||= {};
+  return handler({ args, workspace, state });
+}
+
+function resourceListAction({ args, workspace, state }) {
+  const includePaths = args.showPaths === true;
+  const resources = publicResourceRegistry(state.resources, { includePaths });
+  if (args.json) {
+    console.log(JSON.stringify({
+      workspace: includePaths ? workspace : "<local-workspace>",
+      paths_exposed: includePaths,
+      resources,
+    }, null, 2));
+    return;
+  }
+  if (!Object.keys(resources).length) {
+    console.log("No local resources registered.");
+    return;
+  }
+  for (const [name, value] of Object.entries(resources)) {
+    const fields = [name, value.mode || "n/a", `${value.size ?? "n/a"} bytes`];
+    if (includePaths) fields.splice(1, 0, value.path);
+    console.log(fields.join("	"));
+  }
+}
+
+async function resourceAddAction({ args, workspace, state }) {
+  const name = validateResourceName(args._[1]);
+  const inputPath = args._[2];
+  if (!inputPath) throw new Error("resource add requires NAME and FILE_PATH");
+  const lock = await acquireStartupLockWithWait(state, { operation: "resource-add" });
+  try {
+    const latest = loadState(workspace, { stateDir: args.stateDir });
+    latest.resources ||= {};
+    const inspected = inspectResourceFile(expandHome(inputPath), { allowInsecurePermissions: args.allowInsecurePermissions === true });
+    if (!Object.prototype.hasOwnProperty.call(latest.resources, name) && Object.keys(latest.resources).length >= 64) {
+      throw new Error("local resource registry limit reached (64)");
+    }
+    latest.resources[name] = inspected;
+    saveState(latest);
+    const result = publicResourceInspection(name, inspected, {
+      includePath: args.showPaths === true,
+      available_to_new_jobs_immediately: true,
+    });
+    if (args.json) console.log(JSON.stringify(result, null, 2));
+    else {
+      console.log(`Registered local resource: ${name}`);
+      if (args.showPaths === true) console.log(`Path: ${inspected.path}`);
+      console.log(`Mode: ${inspected.mode || "n/a"}; size: ${inspected.size} bytes`);
+      console.log("The resource is available to newly submitted managed jobs immediately.");
+    }
+  } finally {
+    lock.release();
+  }
+}
+
+async function resourceGenerateSshKeyAction({ args, workspace }) {
+  const name = validateResourceName(args._[1]);
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) throw new Error("HOME or USERPROFILE is required to choose a default SSH key path");
+  const requestedPath = args._[2] ? expandHome(args._[2]) : join(home, ".ssh", `machine-mcp-${name}-ed25519`);
+  const key = await generateRegisteredSshKey({
+    workspace,
+    stateDir: args.stateDir,
+    name,
+    targetPath: requestedPath,
+    comment: `machine-mcp:${name}`,
+  });
+  const includePaths = args.showPaths === true;
+  const result = {
+    name: key.name,
+    created: key.created,
+    fingerprint: key.fingerprint,
+    key_type: key.keyType,
+    private_mode: key.privateMode,
+    public_mode: key.publicMode,
+    private_key_content_exposed: key.privateKeyContentExposed,
+    registered: key.registered,
+    available_to_new_jobs_immediately: key.availableToNewJobsImmediately,
+    paths_exposed: includePaths,
+    ...(includePaths ? { private_key_path: key.privateKeyPath, public_key_path: key.publicKeyPath } : {}),
+  };
+  if (args.json) console.log(JSON.stringify(result, null, 2));
+  else {
+    console.log(`${key.created ? "Generated and registered" : "Reused and registered"} SSH key resource: ${name}`);
+    if (includePaths) {
+      console.log(`Private key: ${key.privateKeyPath}`);
+      console.log(`Public key: ${key.publicKeyPath}`);
+    }
+    console.log(`Fingerprint: ${key.fingerprint}`);
+    console.log("Private key content was not printed or sent through MCP.");
+  }
+}
+
+async function resourceRemoveAction({ args, workspace, state }) {
+  const name = validateResourceName(args._[1]);
+  const lock = await acquireStartupLockWithWait(state, { operation: "resource-remove" });
+  try {
+    const latest = loadState(workspace, { stateDir: args.stateDir });
+    latest.resources ||= {};
+    const existed = Object.prototype.hasOwnProperty.call(latest.resources, name);
+    delete latest.resources[name];
+    saveState(latest);
+    const result = { name, removed: existed, affects_new_jobs_immediately: true };
+    if (args.json) console.log(JSON.stringify(result, null, 2));
+    else {
+      console.log(existed ? `Removed local resource: ${name}` : `Local resource was not registered: ${name}`);
+      console.log("The change applies to newly submitted managed jobs immediately.");
+    }
+  } finally {
+    lock.release();
+  }
+}
+
+function resourceCheckAction({ args, state }) {
+  const name = validateResourceName(args._[1]);
+  const resource = state.resources[name];
+  if (!resource) throw new Error(`local resource is not registered: ${name}`);
+  const inspected = inspectResourceFile(resource.path, { allowInsecurePermissions: resource.allowInsecurePermissions === true });
+  const result = publicResourceInspection(name, inspected, { includePath: args.showPaths === true });
+  if (args.json) console.log(JSON.stringify(result, null, 2));
+  else {
+    const pathDetail = args.showPaths === true ? ` at ${inspected.path}` : "";
+    console.log(`${name}: available${pathDetail} (${inspected.mode || "n/a"}, ${inspected.size} bytes)`);
+  }
+}
+
+function publicResourceInspection(name, inspected, { includePath = false, ...extra } = {}) {
+  return {
+    name,
+    kind: inspected.kind,
+    size: inspected.size ?? null,
+    mode: inspected.mode ?? null,
+    updated_at: inspected.updatedAt ?? null,
+    allow_insecure_permissions: inspected.allowInsecurePermissions === true,
+    ...extra,
+    paths_exposed: includePath,
+    contents_exposed: false,
+    ...(includePath ? { path: inspected.path } : {}),
+  };
+}
+
+async function browserCommand(args, { chooseWorkspace }) {
+  const action = String(args._[0] || "status").toLowerCase();
+  const extensionPath = resolve(packageRoot, "browser-extension");
+  if (action === "path") {
+    if (args.json) console.log(JSON.stringify({ extension_path: extensionPath }, null, 2));
+    else console.log(extensionPath);
+    return;
+  }
+  if (!["status", "setup", "pair"].includes(action)) throw new Error(`Unknown browser action: ${action}`);
+  const workspace = await chooseWorkspace({ ...args, _: [] }, { promptOnFirstRun: false, save: false, allowPositional: false });
+  const state = loadState(workspace, { stateDir: args.stateDir });
+  const pairingFile = join(state.paths.stateRoot, "browser-bridge.json");
+  if (!existsSync(pairingFile)) {
+    throw new Error("browser bridge is not initialized; start machine-mcp once, then run this command again");
+  }
+  ownerOnlyFile(pairingFile);
+  let pairing;
+  try {
+    pairing = JSON.parse(readBoundedRegularFileSync(pairingFile, 64 * 1024).toString("utf8"));
+  } catch {
+    throw new Error("browser bridge state is invalid; restart machine-mcp to repair it");
+  }
+  const port = Number(pairing.port);
+  if (!/^[A-Za-z0-9_-]{32,100}$/.test(String(pairing.token || ""))) throw new Error("browser bridge state contains an invalid token");
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error("browser bridge state contains an invalid port");
+  const pairingUrl = `http://127.0.0.1:${port}/pair`;
+  const healthUrl = `http://127.0.0.1:${port}/healthz`;
+  const health = await fetch(healthUrl, { signal: AbortSignal.timeout(2000), cache: "no-store" })
+    .then(async (response) => response.ok ? await response.json() : null)
+    .catch(() => null);
+  const result = {
+    running: health?.ok === true && health?.broker === "machine-bridge-browser",
+    connected: health?.broker === "machine-bridge-browser" && health?.connected === true,
+    extension_path: extensionPath,
+    pairing_url: pairingUrl,
+    expected_extension_version: typeof health?.expected_extension_version === "string" ? health.expected_extension_version : "",
+    extension_protocol: Number.isInteger(health?.extension_protocol) ? health.extension_protocol : null,
+    extension_version: typeof health?.extension_version === "string" ? health.extension_version : "",
+    extension_capabilities: Array.isArray(health?.extension_capabilities) ? health.extension_capabilities : [],
+    extension_reload_required: health?.extension_reload_required === true,
+    controls_existing_profile: health?.controls_existing_profile === true,
+    controls_extension_profile: health?.controls_extension_profile === true,
+    machine_bridge_launches_browser: health?.machine_bridge_launches_browser === true,
+    profile_identity_verifiable: health?.profile_identity_verifiable === true,
+    token_exposed: false,
+  };
+  if (action === "status") {
+    if (args.json) console.log(JSON.stringify(result, null, 2));
+    else {
+      console.log(`Browser bridge: ${result.running ? "running" : "not reachable"}`);
+      console.log(`Extension: ${result.connected ? "connected" : result.extension_reload_required ? "reload required" : "not connected"}`);
+      if (result.expected_extension_version) console.log(`Expected extension build: ${result.expected_extension_version}`);
+      if (result.extension_version || result.extension_protocol) console.log(`Connected extension build: ${result.extension_version || "unknown"} (protocol ${result.extension_protocol ?? "unknown"})`);
+      console.log(`Browser profile: ${result.controls_extension_profile ? "the Chromium profile where this extension is installed" : "unknown"}`);
+      if (result.controls_extension_profile) console.log(`Profile provenance: Machine Bridge did not launch the browser; daily-vs-isolated profile identity is not machine-verifiable.`);
+      console.log(`Extension path: ${extensionPath}`);
+    }
+    return;
+  }
+  if (!result.running) throw new Error("browser bridge is not reachable; keep machine-mcp running and retry");
+  await openExternal(pairingUrl);
+  if (args.json) console.log(JSON.stringify({ ...result, pairing_page_opened: true }, null, 2));
+  else {
+    console.log(`Extension path: ${extensionPath}`);
+    console.log("Load this directory in the Chromium profile you use every day; Machine Bridge does not install it into Playwright or a separate automation profile.");
+    console.log("Enable Developer mode, choose Load unpacked, and reload the extension after each Machine Bridge upgrade.");
+    console.log(`Pairing page opened: ${pairingUrl}`);
+  }
+}
+
+function openExternal(target) {
+  const command = process.platform === "darwin"
+    ? { file: "open", args: [target] }
+    : process.platform === "win32"
+      ? { file: "cmd.exe", args: ["/d", "/s", "/c", "start", "", target] }
+      : { file: "xdg-open", args: [target] };
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(command.file, command.args, { detached: true, stdio: "ignore", windowsHide: true });
+    child.once("spawn", () => {
+      child.unref();
+      resolvePromise();
+    });
+    child.once("error", rejectPromise);
+  });
+}
+
+async function jobCommand(args, { chooseWorkspace, confirm }) {
+  const action = String(args._[0] || "list").toLowerCase();
+  const workspace = await chooseWorkspace({ ...args, _: [] }, { promptOnFirstRun: false, save: false, allowPositional: false });
+  const state = loadState(workspace, { stateDir: args.stateDir });
+  const manager = new ManagedJobManager({
+    jobRoot: join(state.paths.profileDir, "jobs"),
+    workspace,
+    policy: resolvePolicy({}, state.policy),
+    resources: state.resources,
+    resourceStatePath: state.paths.statePath,
+    stateRoot: state.paths.stateRoot,
+    logger: createLogger({ level: "warn", component: "job" }),
+  });
+  let result;
+  if (action === "list") result = manager.list({ limit: 50 });
+  else if (action === "read") result = manager.read({ job_id: args._[1] });
+  else if (action === "inspect") result = manager.inspectLocal({ job_id: args._[1] });
+  else if (action === "cancel") result = manager.cancel({ job_id: args._[1] });
+  else if (action === "approve") {
+    if (args.json && !args.yes) throw new Error("job approve --json requires --yes");
+    const inspection = manager.inspectLocal({ job_id: args._[1] });
+    if (!args.yes) {
+      console.log(JSON.stringify(inspection, null, 2));
+      const approved = await confirm(`Approve and execute managed job ${args._[1]}?`, false);
+      if (!approved) {
+        console.log("Managed job approval cancelled. Re-run with --yes after review to skip confirmation.");
+        return;
+      }
+    }
+    result = manager.approve({ job_id: args._[1] }, { localOperator: true });
+  }
+  else if (action === "submit") {
+    const planPath = args._[1];
+    if (!planPath) throw new Error("job submit requires a JSON plan file");
+    const plan = loadManagedJobPlan(expandHome(planPath));
+    result = manager.start(plan);
+  } else throw new Error(`Unknown job action: ${action}`);
+  console.log(JSON.stringify(result, null, 2));
+}

package/src/local/cli-options.mjs

@@ -0,0 +1,151 @@
+import { normalizeLogLevel } from "./log.mjs";
+
+const BOOLEAN_OPTIONS = new Set([
+  "help", "version", "quiet", "json", "verbose", "rotateSecrets", "forceWorker",
+  "daemonOnly", "noAutostart", "noPrintCredentials", "printMcpCredentials",
+  "printCredentials", "noWrite", "noExec", "fullEnv", "unrestrictedPaths", "absolutePaths",
+  "yes", "keepWorker", "allowInsecurePermissions", "showPaths",
+]);
+const VALUE_OPTIONS = new Set([
+  "workspace", "stateDir", "workerName", "profile", "execMode", "client", "logLevel", "logFormat",
+]);
+
+const LOG_FORMATS = new Set(["text", "json"]);
+
+const COMMAND_OPTIONS = {
+  start: new Set([
+    "workspace", "stateDir", "workerName", "quiet", "json", "verbose", "logLevel", "logFormat", "rotateSecrets", "forceWorker",
+    "daemonOnly", "noAutostart", "noPrintCredentials", "printMcpCredentials", "printCredentials",
+    "profile", "execMode", "noWrite", "noExec", "fullEnv", "unrestrictedPaths", "absolutePaths",
+  ]),
+  stdio: new Set(["workspace", "stateDir", "profile", "execMode", "noWrite", "noExec", "fullEnv", "unrestrictedPaths", "absolutePaths", "verbose", "quiet", "logLevel", "logFormat"]),
+  "client-config": new Set(["workspace", "stateDir", "profile", "client", "json"]),
+  status: new Set(["workspace", "stateDir"]),
+  doctor: new Set(["workspace", "stateDir"]),
+  "full-test": new Set(["workspace", "stateDir", "json"]),
+  "rotate-secrets": new Set(["workspace", "stateDir", "workerName", "noPrintCredentials", "printMcpCredentials", "printCredentials", "quiet"]),
+  workspace: new Set(["workspace", "stateDir"]),
+  service: new Set(["workspace", "stateDir", "quiet"]),
+  autostart: new Set(["workspace", "stateDir", "quiet"]),
+  resource: new Set(["workspace", "stateDir", "allowInsecurePermissions", "showPaths", "json"]),
+  browser: new Set(["workspace", "stateDir", "json"]),
+  job: new Set(["workspace", "stateDir", "json", "yes"]),
+  uninstall: new Set(["stateDir", "keepWorker", "yes"]),
+};
+
+const SINGLE_WORKSPACE_POSITIONAL_COMMANDS = new Set(["start", "stdio", "status", "doctor", "full-test", "rotate-secrets"]);
+const STATIC_POSITIONAL_RULES = Object.freeze({
+  "client-config": Object.freeze({ max: 1, tooMany: "client-config accepts at most one positional client name" }),
+  uninstall: Object.freeze({ max: 0, tooMany: "uninstall does not accept positional arguments" }),
+});
+const RESOURCE_POSITIONAL_LIMITS = Object.freeze({ add: 3, "generate-ssh-key": 3, remove: 2, check: 2 });
+const JOB_POSITIONAL_LIMITS = Object.freeze({ read: 2, inspect: 2, cancel: 2, approve: 2, submit: 2 });
+const ACTION_POSITIONAL_RULES = Object.freeze({
+  workspace(args) {
+    const action = String(args._[0] || "show");
+    return { max: action === "set" || action === "select" ? 2 : 1, tooMany: `workspace ${action} received too many positional arguments`, workspaceConflictAfter: 1 };
+  },
+  service(args) {
+    const action = String(args._[0] || "status");
+    return { max: ["install", "status", "stop", "uninstall", "remove"].includes(action) ? 2 : 1, tooMany: `service ${action} received too many positional arguments`, workspaceConflictAfter: 1 };
+  },
+  autostart(args) { return ACTION_POSITIONAL_RULES.service(args); },
+  resource(args) {
+    const action = String(args._[0] || "list");
+    return { max: RESOURCE_POSITIONAL_LIMITS[action] ?? 1, tooMany: `resource ${action} received too many positional arguments` };
+  },
+  browser(args) {
+    const action = String(args._[0] || "status");
+    return { max: 1, tooMany: `browser ${action} received too many positional arguments` };
+  },
+  job(args) {
+    const action = String(args._[0] || "list");
+    return { max: JOB_POSITIONAL_LIMITS[action] ?? 1, tooMany: `job ${action} received too many positional arguments` };
+  },
+});
+
+export function normalizeCommand(argv) {
+  if (!argv.length || argv[0].startsWith("--")) return ["start", argv];
+  return [argv[0], argv.slice(1)];
+}
+
+export function parseArgs(argv) {
+  const out = { _: [] };
+  let positionalOnly = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const raw = argv[index];
+    if (positionalOnly || raw === "-" || !raw.startsWith("--")) {
+      out._.push(raw);
+      continue;
+    }
+    if (raw === "--") {
+      positionalOnly = true;
+      continue;
+    }
+    const separator = raw.indexOf("=");
+    const rawKey = raw.slice(2, separator >= 0 ? separator : undefined);
+    if (!rawKey) throw new Error("invalid empty option");
+    const key = toCamel(rawKey);
+    if (!BOOLEAN_OPTIONS.has(key) && !VALUE_OPTIONS.has(key)) throw new Error(`Unknown option: --${rawKey}`);
+    if (Object.prototype.hasOwnProperty.call(out, key)) throw new Error(`Duplicate option: --${rawKey}`);
+    if (BOOLEAN_OPTIONS.has(key)) {
+      out[key] = separator >= 0 ? parseBooleanOption(raw.slice(separator + 1), rawKey) : true;
+      continue;
+    }
+    const value = separator >= 0 ? raw.slice(separator + 1) : argv[++index];
+    if (value === undefined || value === "" || value.startsWith("--")) throw new Error(`Option --${rawKey} requires a value`);
+    out[key] = value;
+  }
+  return out;
+}
+
+export function validateCommandOptions(command, args) {
+  const allowed = COMMAND_OPTIONS[command];
+  if (!allowed) return;
+  for (const key of Object.keys(args)) {
+    if (key === "_" || key === "help" || key === "version") continue;
+    if (!allowed.has(key)) throw new Error(`Option --${toKebab(key)} is not valid for ${command}`);
+  }
+}
+
+export function validateLoggingOptions(args = {}) {
+  if (args.quiet && args.verbose) throw new Error("--quiet and --verbose cannot be used together");
+  if (args.logLevel !== undefined && (args.quiet || args.verbose)) throw new Error("--log-level cannot be combined with --quiet or --verbose");
+  if (args.logLevel !== undefined) normalizeLogLevel(args.logLevel);
+  if (args.logFormat !== undefined && !LOG_FORMATS.has(String(args.logFormat).toLowerCase())) throw new Error("--log-format must be text or json");
+}
+
+export function validatePositionals(command, args) {
+  const rule = positionalRule(command, args);
+  if (!rule) return;
+  if (args._.length > rule.max) throw new Error(rule.tooMany);
+  if (args.workspace && Number.isInteger(rule.workspaceConflictAfter) && args._.length > rule.workspaceConflictAfter) {
+    throw new Error("workspace path was provided both positionally and with --workspace");
+  }
+}
+
+export function effectiveLogLevel(args = {}) {
+  if (args.logLevel !== undefined) return normalizeLogLevel(args.logLevel);
+  if (args.quiet) return "error";
+  if (args.verbose) return "debug";
+  return "info";
+}
+
+export function effectiveLogFormat(args = {}) {
+  return String(args.logFormat || "text").toLowerCase();
+}
+
+function positionalRule(command, args) {
+  if (SINGLE_WORKSPACE_POSITIONAL_COMMANDS.has(command)) {
+    return { max: 1, tooMany: `${command} accepts at most one positional workspace path`, workspaceConflictAfter: 0 };
+  }
+  if (STATIC_POSITIONAL_RULES[command]) return STATIC_POSITIONAL_RULES[command];
+  return ACTION_POSITIONAL_RULES[command]?.(args) || null;
+}
+function parseBooleanOption(value, key) {
+  if (value === "true" || value === "1") return true;
+  if (value === "false" || value === "0") return false;
+  throw new Error(`Option --${key} expects true or false when using =`);
+}
+function toCamel(key) { return key.replace(/-([a-z])/g, (_, character) => character.toUpperCase()); }
+function toKebab(value) { return String(value).replace(/[A-Z]/g, (character) => `-${character.toLowerCase()}`); }