viveworker 0.7.0 → 0.8.1

package/scripts/viveworker.mjs

@@ -75,6 +75,17 @@ if (rawArgs[0] === "stats") {
   }
 }
 
+if (rawArgs[0] === "mcp") {
+  const { runMcpCli } = await import("./mcp-server.mjs");
+  try {
+    await runMcpCli(rawArgs.slice(1));
+    process.exit(0);
+  } catch (error) {
+    console.error(error.message || String(error));
+    process.exit(1);
+  }
+}
+
 const cli = parseArgs(rawArgs);
 
 try {
@@ -388,7 +399,7 @@ async function runPair(cliOptions) {
 async function runEnable(cliOptions) {
   const target = String(cliOptions.enableTarget || "").trim().toLowerCase();
   if (!target) {
-    throw new Error("Usage: viveworker enable <claude|a2a|moltbook|scout> [...]");
+    throw new Error("Usage: viveworker enable <claude|a2a|moltbook|scout|mcp> [...]");
   }
 
   switch (target) {
@@ -406,11 +417,248 @@ async function runEnable(cliOptions) {
     case "scout":
       await runEnableScout(cliOptions);
       return;
+    case "mcp":
+      await runEnableMcp(cliOptions);
+      return;
     default:
       throw new Error(`Unknown feature: ${target}`);
   }
 }
 
+async function runEnableMcp(cliOptions) {
+  const target = normalizeMcpInstallTarget(cliOptions.mcpTarget || "all");
+  const allTargets = target === "all" ? ["claude", "cursor", "codex"] : [target];
+  const entries = [];
+  const config = mcpServerConfigSnippet();
+
+  for (const item of allTargets) {
+    const entry = await prepareMcpConfigChange(item, config, { explicit: target !== "all" });
+    if (entry) entries.push(entry);
+  }
+
+  if (entries.length === 0) {
+    console.log("");
+    console.log("No supported MCP client config was found.");
+    console.log("Run `npx viveworker mcp config` to print a manual config snippet.");
+    return;
+  }
+
+  console.log("");
+  console.log("viveworker MCP setup");
+  console.log("");
+  console.log("The following MCP client config changes will be applied:");
+  for (const entry of entries) {
+    console.log(`- ${entry.label}: ${entry.status} ${entry.path}`);
+  }
+  console.log("");
+  console.log("MCP server entry:");
+  console.log(JSON.stringify({ mcpServers: { viveworker: config } }, null, 2));
+
+  if (cliOptions.mcpDryRun) {
+    console.log("");
+    console.log("Dry run only. No files were changed.");
+    return;
+  }
+
+  const changedEntries = entries.filter((entry) => entry.changed);
+  if (changedEntries.length === 0) {
+    console.log("");
+    console.log("MCP config is already up to date.");
+    return;
+  }
+
+  if (!cliOptions.yes) {
+    const confirmed = await confirmCli("Write these MCP config changes? [y/N] ");
+    if (!confirmed) {
+      console.log("Cancelled.");
+      return;
+    }
+  }
+
+  for (const entry of changedEntries) {
+    await fs.mkdir(path.dirname(entry.path), { recursive: true });
+    await fs.writeFile(entry.path, entry.nextText, entry.mode || "utf8");
+  }
+
+  console.log("");
+  console.log("MCP config updated.");
+  console.log("Restart the target app so it reloads the MCP server list.");
+}
+
+function normalizeMcpInstallTarget(value) {
+  const target = String(value || "all").trim().toLowerCase();
+  if (["claude", "cursor", "codex", "all"].includes(target)) {
+    return target;
+  }
+  throw new Error("Use --target claude, --target cursor, --target codex, or --target all.");
+}
+
+function mcpServerConfigSnippet() {
+  return {
+    command: "npx",
+    args: ["viveworker", "mcp"],
+  };
+}
+
+async function prepareMcpConfigChange(target, serverConfig, { explicit = false } = {}) {
+  const descriptor = mcpConfigDescriptor(target);
+  if (!descriptor) {
+    return null;
+  }
+  if (!explicit && !(await fileExists(descriptor.parentDir))) {
+    return null;
+  }
+  const currentText = await readOptionalText(descriptor.path);
+  const result = descriptor.kind === "toml"
+    ? upsertCodexMcpConfig(currentText, serverConfig)
+    : upsertJsonMcpConfig(currentText, serverConfig);
+  return {
+    target,
+    label: descriptor.label,
+    path: descriptor.path,
+    status: result.changed
+      ? (currentText.trim() ? "update" : "create")
+      : "unchanged",
+    changed: result.changed,
+    nextText: result.text,
+  };
+}
+
+function mcpConfigDescriptor(target) {
+  if (target === "claude") {
+    const override = process.env.VIVEWORKER_MCP_CLAUDE_CONFIG_FILE || "";
+    const defaultPath = path.join(os.homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    const configPath = resolvePath(override || defaultPath);
+    return {
+      kind: "json",
+      label: "Claude Desktop",
+      path: configPath,
+      parentDir: path.dirname(configPath),
+    };
+  }
+  if (target === "cursor") {
+    const override = process.env.VIVEWORKER_MCP_CURSOR_CONFIG_FILE || "";
+    const defaultPath = path.join(os.homedir(), ".cursor", "mcp.json");
+    const configPath = resolvePath(override || defaultPath);
+    return {
+      kind: "json",
+      label: "Cursor",
+      path: configPath,
+      parentDir: path.dirname(configPath),
+    };
+  }
+  if (target === "codex") {
+    const override = process.env.VIVEWORKER_MCP_CODEX_CONFIG_FILE || "";
+    const defaultPath = path.join(os.homedir(), ".codex", "config.toml");
+    const configPath = resolvePath(override || defaultPath);
+    return {
+      kind: "toml",
+      label: "Codex",
+      path: configPath,
+      parentDir: path.dirname(configPath),
+    };
+  }
+  return null;
+}
+
+function upsertJsonMcpConfig(currentText, serverConfig) {
+  let data = {};
+  if (currentText.trim()) {
+    try {
+      data = JSON.parse(currentText);
+    } catch (error) {
+      throw new Error(`Unable to parse existing MCP JSON config: ${error.message}`);
+    }
+  }
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    data = {};
+  }
+  const previous = JSON.stringify(data);
+  const mcpServers = data.mcpServers && typeof data.mcpServers === "object" && !Array.isArray(data.mcpServers)
+    ? data.mcpServers
+    : {};
+  data.mcpServers = {
+    ...mcpServers,
+    viveworker: serverConfig,
+  };
+  const text = `${JSON.stringify(data, null, 2)}\n`;
+  return {
+    changed: JSON.stringify(data) !== previous,
+    text,
+  };
+}
+
+function upsertCodexMcpConfig(currentText, serverConfig) {
+  const block = [
+    "[mcp_servers.viveworker]",
+    `command = ${tomlString(serverConfig.command)}`,
+    `args = [${serverConfig.args.map((arg) => tomlString(arg)).join(", ")}]`,
+    "",
+  ].join("\n");
+  const withoutExisting = removeTomlTable(currentText, "mcp_servers.viveworker").replace(/\s+$/u, "");
+  const text = `${withoutExisting ? `${withoutExisting}\n\n` : ""}${block}`;
+  return {
+    changed: normalizeConfigText(text) !== normalizeConfigText(currentText),
+    text,
+  };
+}
+
+function removeTomlTable(text, tableName) {
+  const lines = String(text || "").split(/\r?\n/u);
+  const out = [];
+  let skipping = false;
+  const header = `[${tableName}]`;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === header) {
+      skipping = true;
+      continue;
+    }
+    if (skipping && /^\[[^\]]+\]\s*$/u.test(trimmed)) {
+      skipping = false;
+    }
+    if (!skipping) {
+      out.push(line);
+    }
+  }
+  return out.join("\n");
+}
+
+function tomlString(value) {
+  return JSON.stringify(String(value || ""));
+}
+
+function normalizeConfigText(value) {
+  return String(value || "").replace(/\r\n/gu, "\n").trim();
+}
+
+async function readOptionalText(filePath) {
+  try {
+    return await fs.readFile(filePath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return "";
+    }
+    throw error;
+  }
+}
+
+async function confirmCli(prompt) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error("Refusing to write MCP config without an interactive terminal. Re-run with --yes or --dry-run.");
+  }
+  const rl = createReadlineInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    const answer = await rl.question(prompt);
+    return /^y(es)?$/iu.test(String(answer || "").trim());
+  } finally {
+    rl.close();
+  }
+}
+
 async function runEnableClaude(cliOptions) {
   const setup = await loadExistingSetup(cliOptions);
   const settingsFile = resolvePath(
@@ -863,13 +1111,16 @@ async function runStart(cliOptions) {
   }
 
   progress.update("cli.start.progress.bridge");
-  await startDetachedBridge({
-    envFile,
-    logFile: resolvePath(cliOptions.logFile || defaultLogFile),
-    pidFile,
-  });
+  const alreadyHealthy = await waitForHealth(healthUrl, { attempts: 1, intervalMs: 0 });
+  if (!alreadyHealthy) {
+    await startDetachedBridge({
+      envFile,
+      logFile: resolvePath(cliOptions.logFile || defaultLogFile),
+      pidFile,
+    });
+  }
   progress.update("cli.start.progress.health");
-  const healthy = await waitForHealth(healthUrl);
+  const healthy = alreadyHealthy || await waitForHealth(healthUrl);
   const pairingReady = healthy && rotatedPairing.rotated
     ? await waitForExpectedPairing(config.NATIVE_APPROVAL_SERVER_PUBLIC_BASE_URL || "", rotatedPairing.pairingToken)
     : true;
@@ -1394,6 +1645,9 @@ function parseArgs(argv) {
     autoScoutHarness: "auto",
     autoScoutSubmolts: "",
     autoScoutMaxDaily: 0,
+    mcpTarget: "",
+    mcpDryRun: false,
+    yes: false,
   };
 
   if (argv[0] && !argv[0].startsWith("-")) {
@@ -1549,6 +1803,13 @@ function parseArgs(argv) {
     } else if (arg === "--auto-scout-max-daily") {
       parsed.autoScoutMaxDaily = Number(next) || 0;
       index += 1;
+    } else if (arg === "--target") {
+      parsed.mcpTarget = next;
+      index += 1;
+    } else if (arg === "--dry-run") {
+      parsed.mcpDryRun = true;
+    } else if (arg === "--yes" || arg === "-y") {
+      parsed.yes = true;
     } else if (arg === "--help" || arg === "-h") {
       parsed.command = "help";
     } else {
@@ -1576,6 +1837,8 @@ ${t(locale, "cli.help.commands")}
   ${t(locale, "cli.help.status")}
   ${t(locale, "cli.help.doctor")}
   ${t(locale, "cli.help.update")}
+  mcp           Start the stdio MCP server
+  mcp config    Print MCP client config snippets
 
 ${t(locale, "cli.help.commonOptions")}
   --port <n>
@@ -1604,6 +1867,7 @@ ${t(locale, "cli.help.featureOptions")}
   ${t(locale, "cli.help.enableA2a")}
   ${t(locale, "cli.help.enableMoltbook")}
   ${t(locale, "cli.help.enableScout")}
+  enable mcp --target <claude|cursor|codex|all> [--dry-run|--yes]
   ${t(locale, "cli.help.doctorFix")}
 `);
 }
@@ -1691,6 +1955,11 @@ function buildLaunchAgentPlist({ label, nodePath, bridgeScript, envFile, logFile
 }
 
 async function startDetachedBridge({ envFile, logFile, pidFile }) {
+  const existingPid = await maybeReadPid(pidFile);
+  if (existingPid && isProcessRunning(existingPid)) {
+    return { pid: existingPid, alreadyRunning: true };
+  }
+
   await fs.mkdir(path.dirname(logFile), { recursive: true });
   const logHandle = await fs.open(logFile, "a");
   const child = spawn(process.execPath, [bridgeScript, "--env-file", envFile], {
@@ -1700,6 +1969,7 @@ async function startDetachedBridge({ envFile, logFile, pidFile }) {
   child.unref();
   await logHandle.close();
   await fs.writeFile(pidFile, `${child.pid}\n`, "utf8");
+  return { pid: child.pid, alreadyRunning: false };
 }
 
 async function maybeReadPid(pidFile) {
@@ -1712,6 +1982,18 @@ async function maybeReadPid(pidFile) {
   }
 }
 
+function isProcessRunning(pid) {
+  if (!Number.isFinite(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function maybeReadEnvFile(filePath) {
   const output = {};
   try {

package/skills/viveworker-control-plane/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: viveworker-control-plane
+description: Route AI agent operations through the user's viveworker mobile control plane. Use when Codex has access to the viveworker MCP tools and needs to notify the phone, ask the user a question, request human approval, share a workspace deliverable through File Share, hand off context to another Codex/Claude/inbox thread, or delegate a bounded task to a registered A2A target. Especially use for externally visible, irreversible, sensitive, or cross-agent actions.
+---
+
+# viveworker Control Plane
+
+Use viveworker as the mobile control surface around agent work. Keep normal local work moving, but route decisions, confirmations, handoffs, deliverables, and delegation through the paired phone when that improves safety or flow.
+
+## First Check
+
+- If tool availability is uncertain, call `viveworker_status` first.
+- If viveworker MCP is unavailable, do not pretend the action happened. Tell the user to run `npx viveworker enable mcp --target codex` or add the config from `npx viveworker mcp config`.
+- Do not use viveworker for every routine local read/edit. Use it when a human decision, mobile notification, external handoff, or durable record is useful.
+
+## First-Run Onboarding
+
+Use this flow when the user asks to set up viveworker, pair a phone, install the control plane, or "make viveworker work here".
+
+1. Check whether MCP tools are available.
+   - If available, call `viveworker_status` first and use the result to decide what is missing.
+   - If unavailable, explain that the MCP entry is not loaded yet and guide the user through `npx viveworker enable mcp --target codex`, then ask them to restart Codex.
+2. If the bridge is not running or no local setup exists, ask for confirmation before running or recommending `npx viveworker setup`.
+   - Do not auto-run setup silently. It can install local certificates, write config, register launchd services, and change agent hooks.
+   - If the user explicitly asks you to execute setup, use the normal shell tool with clear confirmation, not MCP.
+3. If setup exists but no phone is trusted, guide the user to run `npx viveworker pair` and open the pairing URL on the phone.
+4. Ask the user to allow notifications from the Home Screen app when prompted.
+5. Re-check with `viveworker_status`.
+6. Send a final smoke notification with `viveworker_notify`.
+7. Summarize what is ready: bridge, pairing, notifications, Remote connection, File Share, A2A, and Moltbook where applicable.
+
+Keep onboarding calm and step-by-step. Do not make the user debug config files unless the status output points there.
+
+## Tool Selection
+
+- Use `viveworker_notify` for informational milestones that should appear on the phone or timeline, such as "build finished", "review ready", or "agent is blocked".
+- Use `viveworker_ask` when the next step depends on a human preference, missing requirement, or choice that should not be guessed.
+- Use `viveworker_request_approval` before actions that are externally visible, hard to undo, risky, sensitive, delegated, paid, or likely to surprise the user.
+- Use `viveworker_share_file` when the user wants a workspace deliverable shared as a limited File Share URL. Good fits include `.html`, `.htm`, `.pdf`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, and `.csv`.
+- Use `viveworker_thread_share` when context should move to another Codex session, Claude session, or viveworker inbox while preserving a human-visible handoff.
+- Use `viveworker_send_a2a_task` only for registered A2A target aliases and bounded tasks with clear acceptance criteria.
+
+## Approval And Question Style
+
+- Keep phone prompts short and concrete.
+- Include the action, expected result, and specific risk.
+- Include relevant file refs, but never include secrets, tokens, private keys, or unnecessary file contents.
+- Treat timeout, rejection, or transport failure as "not approved". Do not continue as if approval was granted.
+- After the tool returns, summarize the decision or returned artifact to the user.
+
+## File Share Rules
+
+- Share only files inside the workspace root.
+- Do not share `.env`, credential files, private keys, `.ssh`, `.aws`, `.gnupg`, or secret-looking paths.
+- Prefer sharing final deliverables, not internal source files, unless the user explicitly asks.
+- For unsupported file types, explain the accepted types and suggest exporting to HTML, PDF, image, or CSV first.
+- Do not use File Share to bypass a user's explicit request not to upload or publish content.
+
+## Thread Share Rules
+
+- Use `targetConversationId` when the user names a specific thread.
+- Use `targetTool` when the user says "send this to Codex", "share with Claude", or "put this in the inbox" without a specific thread ID.
+- Send a compact handoff: current goal, decisions made, blockers, and concrete next action.
+- Attach `contextFiles` only when they help the receiver act.
+
+## A2A Delegation Rules
+
+- Use only aliases from `~/.viveworker/a2a-targets.json`; never inline API keys in tool arguments.
+- Keep delegated tasks self-contained and limited in scope.
+- Include success criteria, constraints, and any deadline or budget.
+- Ask for approval before sending, even if the task looks harmless.
+- Do not send secrets, private repo data, or local paths unless the user clearly approves that exposure.
+
+## Examples
+
+Ask before a risky action:
+
+```json
+{
+  "title": "Approve release publish",
+  "message": "Publish viveworker 0.8.0 to npm. Risk: this makes the package public and hard to fully undo.",
+  "approvalKind": "release"
+}
+```
+
+Share a deliverable:
+
+```json
+{
+  "path": "/workspace/report.html",
+  "workspaceRoot": "/workspace",
+  "expiresDays": "3"
+}
+```
+
+Delegate through A2A:
+
+```json
+{
+  "target": "reviewer",
+  "instruction": "Review the remote connection security notes and return only concrete risks with file references.",
+  "metadata": { "scope": "security-review" }
+}
+```

package/skills/viveworker-control-plane/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "viveworker Control Plane"
+  short_description: "Route AI agent decisions through viveworker"
+  default_prompt: "Use $viveworker-control-plane to route approvals, questions, file shares, thread handoffs, and A2A delegation through viveworker."
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "viveworker"
+      description: "Local viveworker stdio MCP server"
+      transport: "stdio"
+policy:
+  allow_implicit_invocation: true

package/templates/CLAUDE.viveworker.md

@@ -0,0 +1,67 @@
+# viveworker MCP guide for Claude
+
+Use viveworker as the mobile control plane for this Claude session when the user wants phone-based questions, approvals, file sharing, thread sharing, or A2A delegation.
+
+## Setup
+
+For Claude Desktop, the user should install the MCP entry once:
+
+```bash
+npx viveworker enable mcp --target claude
+```
+
+Then restart Claude Desktop.
+
+For Claude Code, the MCP config is separate from Claude Desktop. Install it once with:
+
+```bash
+claude mcp add --scope user viveworker -- npx viveworker mcp
+```
+
+Then restart the Claude Code session. If the tools are not available, ask the user to run the setup command for the Claude surface they are using.
+
+## Tools
+
+- `viveworker_status` checks bridge, pairing, Remote connection, A2A, File Share, and Moltbook state.
+- `viveworker_notify` sends an informational phone notification and records a timeline entry.
+- `viveworker_ask` asks the paired phone a question and waits for the answer.
+- `viveworker_request_approval` asks the phone to approve or reject a proposed action.
+- `viveworker_share_file` uploads a workspace file to File Share after phone approval.
+- `viveworker_thread_share` shares context into another Codex / Claude / inbox thread.
+- `viveworker_send_a2a_task` sends a task to a registered A2A target after phone approval.
+
+## When to use viveworker
+
+- If the user says "ask me on my phone", "スマホに聞いて", or a short decision blocks progress, use `viveworker_ask`.
+- If the user asks you to proceed with a risky, external, irreversible, payment-related, or user-visible action, use `viveworker_request_approval`.
+- If the user asks for a report, prototype, screenshot, PDF, CSV, or standalone HTML to become a shareable link, use `viveworker_share_file`.
+- If the user says "share this with Codex/Claude", "Aの内容をBに共有して", or wants context handed to another session, use `viveworker_thread_share`.
+- If the user wants another registered agent to do work, use `viveworker_send_a2a_task`.
+
+## Prompting rules
+
+- Keep phone prompts short and concrete.
+- Include the action, why it matters, expected outcome, and clear choices.
+- Do not send secrets, private keys, `.env` content, credentials, or unnecessary file contents.
+- Treat timeout, rejection, or missing response as not approved.
+- Do not spam the phone for routine local reads or low-risk edits unless the user asked for mobile confirmation.
+
+## Thread sharing
+
+Thread Share is useful for handoffs such as:
+
+- "Tell Codex what we just decided."
+- "Share this Claude result with the Codex thread."
+- "Aの内容をBに共有して。"
+
+Send a compact summary with the decision, relevant context, and the exact next action expected from the recipient.
+
+Claude may not automatically notice newly shared messages from another session. If the user says something arrived or asks you to pull shared context, inspect the viveworker timeline/inbox surface available in the current environment, or ask the user to open the relevant shared item.
+
+## Safety defaults
+
+- MCP is a control-plane surface, not a shell executor.
+- Do not run shell strings through MCP.
+- File Share and A2A task sending require phone approval.
+- Use registered A2A aliases only; do not ask the user to paste API keys into prompts.
+- Prefer `viveworker_status` before troubleshooting a missing notification, stale pairing, or remote connectivity issue.