viveworker 0.8.0 → 0.8.2

package/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "viveworker",
+  "interface": {
+    "displayName": "viveworker"
+  },
+  "plugins": [
+    {
+      "name": "viveworker-control-plane",
+      "source": {
+        "source": "local",
+        "path": "./plugins/viveworker-control-plane"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

package/README.md

@@ -151,6 +151,14 @@ Use these commands most often:
   install the Moltbook watcher and auto-scout after base setup
 - `npx viveworker enable scout`
   tune, reinstall, or uninstall the Moltbook auto-scout job
+- `npx viveworker stats`
+  show server-side adoption signals for npm, A2A, File Share, Remote connection, and local Moltbook state
+- `npx viveworker mcp`
+  start the stdio MCP server for MCP-compatible AI tools
+- `npx viveworker mcp config`
+  print a Claude Desktop / Cursor / Codex MCP config snippet
+- `npx viveworker enable mcp --target claude|cursor|codex|all`
+  install the MCP config entry after showing the exact change
 - `npx viveworker start`
   start `viveworker` again using the saved config
 - `npx viveworker stop`
@@ -173,6 +181,80 @@ Useful options:
 It does not change the main app URL, port, session secret, TLS, or Web Push settings.
 Use it only when you want to add another trusted device or browser.
 
+## MCP Integration
+
+`viveworker` can run as a local stdio MCP server, so MCP-compatible tools can use the same mobile control plane.
+
+Install it into a supported client:
+
+```bash
+npx viveworker enable mcp --target claude
+npx viveworker enable mcp --target cursor
+npx viveworker enable mcp --target codex
+```
+
+Use `--target all` to update every detected client, `--dry-run` to preview without writing, and `--yes` for non-interactive installs.
+`--target claude` configures Claude Desktop. Claude Code keeps a separate MCP config; add it with:
+
+```bash
+claude mcp add --scope user viveworker -- npx viveworker mcp
+```
+
+If you prefer manual setup, add this to an MCP client:
+
+```json
+{
+  "mcpServers": {
+    "viveworker": {
+      "command": "npx",
+      "args": ["viveworker", "mcp"]
+    }
+  }
+}
+```
+
+Available tools:
+
+- `viveworker_status` checks bridge, pairing, Remote connection, A2A, File Share, and Moltbook status
+- `viveworker_notify` sends an informational phone notification and timeline entry
+- `viveworker_ask` asks a question on the paired phone 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
+
+Available prompts include setup guidance, control-plane usage, risky-action approval, File Share deliverables, and A2A delegation.
+
+Security defaults:
+
+- MCP is stdio-only in this release; there is no HTTP MCP server
+- file sharing is limited to the current workspace and refuses `.env`, credential directories, private keys, and secret-looking paths
+- File Share and A2A task sending require phone approval
+- MCP tool calls are recorded locally with `provider: "mcp"`
+- prompts, message bodies, file contents, file paths, command text, tokens, public keys, and IP addresses are not sent to central analytics
+
+Bundled agent guidance:
+
+- `skills/viveworker-control-plane/SKILL.md` gives Codex-style agents a compact policy for when to use each viveworker MCP tool
+- `templates/CLAUDE.viveworker.md` can be copied into a repo `CLAUDE.md` so Claude knows when to ask, approve, share, hand off, or delegate through viveworker
+- `.agents/plugins/marketplace.json` and `plugins/viveworker-control-plane/` package the MCP config and Codex skill as a local Codex plugin for plugin-based installs
+- use these guides when you want agents to guide first-run setup, ask on mobile, request approval, share deliverables, hand off context, or delegate through A2A instead of guessing
+
+For local Codex plugin testing from a checkout, register this repo as a marketplace in `~/.codex/config.toml`:
+
+```toml
+[marketplaces.viveworker]
+source_type = "local"
+source = "/path/to/viveworker"
+
+[plugins."viveworker-control-plane@viveworker"]
+enabled = true
+```
+
+Restart Codex after changing the config. For normal MCP usage, `npx viveworker enable mcp --target codex` is still the recommended path.
+
+For plugin release readiness and submission notes, see [`plugins/viveworker-control-plane/DISTRIBUTION.md`](plugins/viveworker-control-plane/DISTRIBUTION.md).
+
 ## File Share
 
 `viveworker` includes **File Share**, a private file-hosting surface for agent outputs. It is useful when an agent generates a report, PDF, screenshot, interactive prototype, or CSV and should hand back a URL instead of pasting a blob into chat.
@@ -383,6 +465,63 @@ npx viveworker enable a2a --user-id <desired-id> \
 
 The bridge detects the new credentials within 30 seconds and auto-connects.
 
+### A2A Pro + x402 test flow
+
+Experimental paid deliverables can be tested by adding viveworker metadata to an incoming A2A task.
+The task still requires phone approval, executes locally, uploads the result to File Share with an x402 payment gate, and returns only the unlock URL to the requester.
+
+On the receiving side, set defaults if you do not want every caller to provide payment metadata:
+
+```bash
+A2A_PRO_MODEL=gpt-5.5
+A2A_PRO_PRICE=1.00
+A2A_PRO_PAY_TO=0x1111111111111111111111111111111111111111
+A2A_PRO_EXPIRES_DAYS=7
+```
+
+Only set `A2A_PRO_MODEL` / `requestedModel` to a model name supported by the local Codex or Claude CLI you will use for execution.
+
+Example requester payload:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "research-1",
+  "method": "message/send",
+  "params": {
+    "message": {
+      "role": "user",
+      "parts": [
+        {
+          "type": "text",
+          "text": "Research the current state of agent-to-agent paid deliverables and return a concise brief."
+        }
+      ],
+      "metadata": {
+        "viveworker": {
+          "mode": "x402-pro",
+          "requestedTier": "pro",
+          "requestedModel": "gpt-5.5",
+          "deliverableType": "research brief",
+          "payment": {
+            "price": "1.00",
+            "payTo": "0x1111111111111111111111111111111111111111"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+When completed, `tasks/get` returns an artifact that contains the File Share unlock URL. The requester can inspect the x402 requirement with:
+
+```bash
+npx viveworker share pay <unlock-url> --dry-run
+```
+
+Then they can unlock with their configured buyer wallet, for example `VIVEWORKER_BUYER_PRIVATE_KEY=0x... npx viveworker share pay <unlock-url> --output ./deliverable.html`.
+
 ### Key commands
 
 - `npx viveworker enable a2a --user-id <id>` — register with the relay via GitHub OAuth
@@ -500,6 +639,8 @@ If you can map your tool onto one of those paths, you probably do not need a bra
 - Remote connection uses a relay only for rendezvous/transport; paired-device traffic is end-to-end encrypted to your bridge
 - relay tokens can be rotated manually and are refreshed automatically during LAN enrollment after the rotation window
 - remote connection activity is recorded locally in `~/.viveworker/remote-pairing-audit.jsonl`
+- public relay analytics expose only coarse, delayed adoption counters; detailed relay health and abuse counters require an operator admin token
+- relay analytics never store prompts, replies, file contents, file paths, command text, relay tokens, public keys, or IP addresses
 - if you lose a paired device, revoke it from `Settings > Devices`
 - use `pair` only when you want to add another trusted device
 - A2A relay authentication: external agents must provide a valid API key (`X-A2A-Key` header), and registration requires GitHub OAuth

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viveworker",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Open mobile control surface for Codex, Claude, Thread Sharing, File Share, Moltbook, and A2A tasks on your trusted LAN.",
   "author": "Yuta Hoshino <hoshino.lireneo@gmail.com>",
   "license": "MIT",
@@ -52,7 +52,13 @@
     "scripts/a2a-executor.mjs",
     "scripts/a2a-relay-client.mjs",
     "scripts/share-cli.mjs",
+    "scripts/stats-cli.mjs",
+    "scripts/mcp-server.mjs",
     "scripts/lib",
+    ".agents",
+    "skills",
+    "templates",
+    "plugins",
     "web",
     "README.md",
     "viveworker.env.example",

package/plugins/viveworker-control-plane/.codex-plugin/plugin.json

@@ -0,0 +1,49 @@
+{
+  "name": "viveworker-control-plane",
+  "version": "0.8.1",
+  "description": "Run AI agent work from your phone.",
+  "author": {
+    "name": "viveworker team",
+    "email": "hello@viveworker.com",
+    "url": "https://viveworker.com/"
+  },
+  "homepage": "https://viveworker.com/",
+  "repository": "https://github.com/viveworker-dev/viveworker",
+  "license": "MIT",
+  "keywords": [
+    "viveworker",
+    "mcp",
+    "codex",
+    "mobile",
+    "approvals",
+    "thread-sharing",
+    "file-share",
+    "a2a"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "viveworker",
+    "shortDescription": "Control Codex, Claude, and agent tasks from your phone.",
+    "longDescription": "Pair your phone with viveworker to control Codex, Claude, File Share, Thread Share, A2A tasks, and social posting workflows like Moltbook. Approve actions, answer questions, receive updates, share deliverables, delegate work, and keep agent work moving without being tied to your computer.",
+    "developerName": "viveworker team",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "MCP",
+      "Mobile approvals",
+      "File sharing",
+      "Thread sharing",
+      "A2A delegation"
+    ],
+    "websiteURL": "https://viveworker.com/",
+    "defaultPrompt": [
+      "Set up viveworker and pair my phone.",
+      "Ask me on my phone before risky actions.",
+      "Share this result with another agent."
+    ],
+    "brandColor": "#64D99A",
+    "composerIcon": "./assets/viveworker-logo-v2.png",
+    "logo": "./assets/viveworker-logo-v2.png"
+  }
+}

package/plugins/viveworker-control-plane/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "viveworker": {
+      "command": "npx",
+      "args": [
+        "viveworker",
+        "mcp"
+      ]
+    }
+  }
+}

package/plugins/viveworker-control-plane/DISTRIBUTION.md

@@ -0,0 +1,96 @@
+# Codex Plugin Distribution Checklist
+
+This checklist tracks the release readiness for the `viveworker-control-plane` Codex plugin.
+
+## Plugin package
+
+- Plugin name: `viveworker-control-plane`
+- Display name: `viveworker`
+- Version: `0.8.1`
+- Category: `Productivity`
+- Developer name: `viveworker team`
+- Contact: `hello@viveworker.com`
+- Website: `https://viveworker.com/`
+- Repository: `https://github.com/viveworker-dev/viveworker`
+- License: `MIT`
+- Plugin manifest: `plugins/viveworker-control-plane/.codex-plugin/plugin.json`
+- Marketplace entry: `.agents/plugins/marketplace.json`
+
+## User-facing positioning
+
+Short description:
+
+> Control Codex, Claude, and agent tasks from your phone.
+
+Long description:
+
+> Pair your phone with viveworker to control Codex, Claude, File Share, Thread Share, A2A tasks, and social posting workflows like Moltbook. Approve actions, answer questions, receive updates, share deliverables, delegate work, and keep agent work moving without being tied to your computer.
+
+## Included capabilities
+
+- MCP stdio server config via `plugins/viveworker-control-plane/.mcp.json`
+- Codex skill guidance via `plugins/viveworker-control-plane/skills/viveworker-control-plane/SKILL.md`
+- Plugin logo and composer icon via `plugins/viveworker-control-plane/assets/viveworker-logo-v2.png`
+- First-run guidance for setup, pairing, MCP status checks, and smoke notifications
+- Tool policy for ask, approval, notify, File Share, Thread Share, and A2A delegation
+
+## Security posture
+
+- MCP is stdio-only.
+- No HTTP MCP server is exposed by the plugin.
+- The plugin does not execute arbitrary shell commands.
+- File Share requires phone approval and is restricted by viveworker's path safety rules.
+- A2A task sending uses registered target aliases and requires phone approval.
+- Secrets, credentials, private keys, relay tokens, public keys, file contents, and command text must not be sent through plugin guidance or central analytics.
+
+## Local validation
+
+Run these before proposing a plugin release:
+
+```bash
+node -e "JSON.parse(require('fs').readFileSync('plugins/viveworker-control-plane/.codex-plugin/plugin.json','utf8')); JSON.parse(require('fs').readFileSync('.agents/plugins/marketplace.json','utf8')); JSON.parse(require('fs').readFileSync('plugins/viveworker-control-plane/.mcp.json','utf8')); console.log('ok')"
+npm pack --dry-run
+```
+
+Manual smoke:
+
+1. Add the local marketplace to Codex.
+2. Enable `viveworker-control-plane@viveworker`.
+3. Restart Codex.
+4. Confirm the plugin is visible.
+5. Call `viveworker_status`.
+6. Send a `viveworker_notify` smoke message.
+7. Confirm the phone receives the notification and the timeline records `provider: "mcp"`.
+
+## Codex local marketplace config
+
+```toml
+[marketplaces.viveworker]
+source_type = "local"
+source = "/path/to/viveworker"
+
+[plugins."viveworker-control-plane@viveworker"]
+enabled = true
+```
+
+## Public distribution readiness
+
+Ready:
+
+- Plugin manifest exists and has production metadata.
+- Marketplace entry exists for local testing.
+- MCP config uses `npx viveworker mcp`.
+- Skill guidance is bundled.
+- Logo assets are bundled.
+- npm package includes the plugin directory.
+
+Open items before formal marketplace submission:
+
+- Confirm the current Codex plugin marketplace submission channel and required review format.
+- Confirm whether marketplace reviewers require screenshots, a privacy summary, or a demo video.
+- Confirm whether plugin version should track npm version for every patch release.
+- Confirm whether `policy.authentication` should remain `ON_INSTALL` or move to `ON_USE` if the marketplace review prefers deferred setup.
+
+## Suggested submission blurb
+
+viveworker is an AI agent lifecycle control plane that lets developers run Codex, Claude, File Share, Thread Share, A2A delegation, and Moltbook workflows from a paired phone. The Codex plugin bundles MCP configuration and agent guidance so Codex can ask questions, request approvals, send mobile notifications, share deliverables, hand off context, and delegate tasks through viveworker without requiring users to manually wire the workflow together.

package/plugins/viveworker-control-plane/assets/viveworker-logo-v2.svg

@@ -0,0 +1,39 @@
+<svg width="1024" height="1024" viewBox="0 0 1024 1024" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <radialGradient id="bg" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(238 164) rotate(43.8309) scale(925.664)">
+      <stop stop-color="#173448"/>
+      <stop offset="0.38" stop-color="#0F1F2B"/>
+      <stop offset="1" stop-color="#091117"/>
+    </radialGradient>
+    <radialGradient id="glow" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(760 248) rotate(130.1) scale(256.971)">
+      <stop stop-color="#5ED6FF" stop-opacity="0.34"/>
+      <stop offset="1" stop-color="#5ED6FF" stop-opacity="0"/>
+    </radialGradient>
+    <linearGradient id="vFill" x1="264" y1="286" x2="778" y2="776" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#FFFFFF"/>
+      <stop offset="0.5" stop-color="#F5FBFF"/>
+      <stop offset="1" stop-color="#E7F4F8"/>
+    </linearGradient>
+    <radialGradient id="vShade" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(512 674) rotate(90) scale(196 292)">
+      <stop stop-color="#CFEAF5" stop-opacity="0.46"/>
+      <stop offset="1" stop-color="#CFEAF5" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="soft" x="557" y="90" width="320" height="320" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+      <feGaussianBlur stdDeviation="24"/>
+    </filter>
+    <filter id="vShadow" x="190" y="240" width="650" height="630" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+      <feDropShadow dx="0" dy="24" stdDeviation="30" flood-color="#5ED6FF" flood-opacity="0.14"/>
+    </filter>
+  </defs>
+  <rect width="1024" height="1024" rx="224" fill="url(#bg)"/>
+  <circle cx="717" cy="250" r="112" fill="url(#glow)"/>
+  <g filter="url(#soft)">
+    <circle cx="717" cy="250" r="58" fill="#7DD3FC" fill-opacity="0.36"/>
+  </g>
+  <g filter="url(#vShadow)">
+    <path d="M270 292C235 304 220 342 237 376L421 729C458 800 566 800 603 729L787 376C804 342 789 304 754 292C719 280 684 301 670 335L534 657C525 679 499 679 490 657L354 335C340 301 305 280 270 292Z" fill="url(#vFill)"/>
+    <path d="M270 292C235 304 220 342 237 376L421 729C458 800 566 800 603 729L787 376C804 342 789 304 754 292C719 280 684 301 670 335L534 657C525 679 499 679 490 657L354 335C340 301 305 280 270 292Z" fill="url(#vShade)"/>
+  </g>
+  <path d="M697 180C748 180 789 221 789 272" stroke="#7DD3FC" stroke-width="40" stroke-linecap="round"/>
+  <path d="M667 120C752 120 821 189 821 274" stroke="#7DD3FC" stroke-width="28" stroke-linecap="round" opacity="0.92"/>
+</svg>

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

@@ -0,0 +1,83 @@
+---
+name: viveworker-control-plane
+description: Use viveworker MCP as the mobile control plane for Codex when work needs phone-based questions, approvals, File Share uploads, Thread Share handoffs, or A2A delegation. Use when the user asks to ask on mobile, approve before acting, share a deliverable, send context to another agent/session, or delegate work to an A2A target.
+---
+
+# viveworker Control Plane
+
+Use viveworker when the user wants the agent workflow to leave the chat and enter the mobile control plane: ask, approve, notify, share, hand off, or delegate.
+
+## First check
+
+If anything looks stale or disconnected, call `viveworker_status` before troubleshooting. It summarizes bridge, pairing, Remote connection, A2A, File Share, and Moltbook state.
+
+If viveworker MCP tools are unavailable, tell the user to run:
+
+```bash
+npx viveworker enable mcp --target codex
+```
+
+Then they should restart Codex.
+
+## First-run onboarding
+
+Use this flow when the user says "set up viveworker", "pair my phone", "viveworker を初期設定して", or "viveworker を使えるようにして".
+
+1. Try `viveworker_status` if MCP tools are available.
+2. If the bridge is missing or setup is incomplete, ask for confirmation before running or recommending `npx viveworker setup`.
+3. Do not silently run setup. It can install local certificates, write config, register launchd services, and update agent hooks.
+4. If setup exists but no phone is trusted, guide the user to run `npx viveworker pair` and open the pairing URL on the phone.
+5. Ask the user to allow notifications from the Home Screen app.
+6. Re-check with `viveworker_status`.
+7. Send a smoke notification with `viveworker_notify`.
+8. Summarize what is ready and what remains optional, such as Remote connection, File Share, A2A, or Moltbook.
+
+## Tool policy
+
+- Use `viveworker_ask` for a short user decision that blocks progress.
+- Use `viveworker_request_approval` before risky, external, irreversible, payment-related, or user-visible actions.
+- Use `viveworker_notify` for informational updates that should appear on the phone and timeline.
+- Use `viveworker_share_file` when a local deliverable should become a limited File Share URL.
+- Use `viveworker_thread_share` when context should move to another Codex / Claude / inbox thread.
+- Use `viveworker_send_a2a_task` when the user asks to delegate to a registered A2A target.
+
+## Safety rules
+
+- Keep phone prompts concise: action, reason, expected result, and choices.
+- Treat timeout, rejection, or missing response as not approved.
+- Do not send secrets, private keys, `.env` content, credentials, relay tokens, public keys, or unnecessary file contents through MCP.
+- Do not use MCP as a shell executor. It creates control-plane events; it should not run arbitrary commands.
+- Do not upload files through File Share without phone approval.
+- Use registered A2A target aliases only. Do not inline API keys.
+
+## Natural language triggers
+
+Use `viveworker_ask` for:
+
+- "ask me on my phone"
+- "スマホに聞いて"
+- "確認してから進めて"
+
+Use `viveworker_request_approval` for:
+
+- "approve this on my phone"
+- "承認してから実行して"
+- "外部に送る前に確認して"
+
+Use `viveworker_share_file` for:
+
+- "share this report"
+- "共有リンクにして"
+- "File Share にアップして"
+
+Use `viveworker_thread_share` for:
+
+- "share this with Claude"
+- "tell Codex what we decided"
+- "Aの内容をBに共有して"
+
+Use `viveworker_send_a2a_task` for:
+
+- "delegate this to another agent"
+- "A2Aで依頼して"
+- "registered target に送って"