viveworker 0.8.1 → 0.8.3

package/README.md

@@ -253,6 +253,8 @@ 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.
@@ -384,18 +386,18 @@ Because the Claude hook opens browser windows and returns focus to Claude Deskto
 
 ### What it does
 
-- **Incoming replies**: detects when other agents comment on your posts and notifies your phone so you can draft a reply
+- **Incoming reply drafts**: detects when other agents comment on your posts, drafts a contextual reply first, and sends it to your phone for approval
 - **Draft approval on phone**: reply drafts and original post drafts appear in `Tasks` and `Timeline`, where you can approve, deny, or edit them from your phone
-- **Auto-scout replies**: every 2 minutes, scans the Moltbook feed, scores posts against your agent's persona (0–100), batches candidates over a 30-minute window, picks the best match, drafts a reply via LLM, and proposes it for your approval
+- **Auto-scout replies**: every 2 minutes, handles pending incoming comments first, then scans the Moltbook feed, scores posts against your agent's persona (0–100), batches candidates over a 30-minute window, picks the best match, drafts a reply via LLM, and proposes it for your approval
 - **Original post drafts**: based on your daily coding activity, composes new posts in your agent's voice and proposes them at natural intervals — morning (yesterday recap), noon (morning progress), and evening (full-day summary). Up to 3 per day; deny any slot you don't want
 
 ### How it works
 
 1. Define your agent's persona in `~/.viveworker/moltbook-persona.md` — voice, expertise, interests, topics to avoid
 2. The system filters all content through this persona: only activities and posts that match your agent's expertise are surfaced
-3. The Moltbook watcher pushes incoming replies and draft proposals into `Tasks` and `Timeline`
+3. The Moltbook watcher saves incoming replies; auto-scout turns pending comments and discovery candidates into draft proposals
 4. On your phone, you can approve, deny, or edit the draft body before sending
-5. The Moltbook CLI long-polls for that decision, then posts to Moltbook and solves the verification puzzle automatically
+5. After approval, the bridge posts to Moltbook and solves the verification puzzle automatically
 
 ### Setup
 
@@ -426,6 +428,7 @@ Open `Settings > Moltbook` in the phone app to see the current auto-scout postin
 - `npx viveworker moltbook list` — show pending comment notifications
 - `npx viveworker moltbook poll` — manually refresh Moltbook notifications once
 - `npx viveworker moltbook reconcile` — resolve inbox items that were already replied to elsewhere
+- `npx viveworker moltbook inbox-pick` — manually pick one pending incoming comment for a reply draft
 - `npx viveworker moltbook scout` — manually pick a feed candidate
 - `npx viveworker moltbook propose <postId> --text "..."` — submit a reply draft for phone approval
 - `npx viveworker moltbook compose` — inspect today's activity for original-post material
@@ -463,6 +466,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viveworker",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "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",

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

@@ -1,6 +1,6 @@
 {
   "name": "viveworker-control-plane",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Run AI agent work from your phone.",
   "author": {
     "name": "viveworker team",

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/scripts/a2a-executor.mjs

@@ -10,6 +10,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { Blob, File } from "node:buffer";
 import { completeA2ATask, failA2ATask } from "./a2a-handler.mjs";
 
 const APP_BUNDLE_PATH = "/Applications/Codex.app/Contents/Resources/codex";
@@ -176,13 +177,39 @@ export async function executeA2ATask(task, config, runtime, state, { recordTimel
     executor = available.codex ? "codex" : available.claude ? "claude" : "codex";
   }
 
-  console.log(`[a2a-exec] Starting task ${task.id} via ${executor}: ${instruction.slice(0, 80)}`);
+  const executionOptions = resolveA2AExecutionOptions(task, config, executor);
+  const executionInstruction = buildA2AExecutionInstruction(instruction, task);
+
+  console.log(
+    `[a2a-exec] Starting task ${task.id} via ${executor}${executionOptions.model ? ` model=${executionOptions.model}` : ""}: ${instruction.slice(0, 80)}`
+  );
 
   try {
     const result = executor === "claude"
-      ? await runClaudeExec(instruction)
-      : await runCodexExec(instruction, config);
-    completeA2ATask(task, result);
+      ? await runClaudeExec(executionInstruction, executionOptions)
+      : await runCodexExec(executionInstruction, config, executionOptions);
+
+    if (shouldUploadPaidDeliverable(task)) {
+      const paidShare = await uploadPaidA2ADeliverable({ config, task, resultText: result });
+      const responseText = buildPaidUnlockResponse({ task, paidShare });
+      completeA2ATask(task, responseText);
+      task.paidDeliverable = paidShare;
+      if (task.artifacts?.[0]) {
+        task.artifacts[0].name = "x402 unlockable deliverable";
+        task.artifacts[0].metadata = {
+          viveworker: {
+            mode: "x402-pro",
+            url: paidShare.url,
+            slug: paidShare.slug,
+            price: paidShare.price,
+            payTo: paidShare.payTo,
+            network: paidShare.network,
+          },
+        };
+      }
+    } else {
+      completeA2ATask(task, result);
+    }
     console.log(`[a2a-exec] Task ${task.id} completed via ${executor} (${result.length} chars)`);
   } catch (error) {
     failA2ATask(task, error.message);
@@ -206,6 +233,8 @@ export async function executeA2ATask(task, config, runtime, state, { recordTimel
     messageText: task.status === "completed"
       ? (task.artifacts?.[0]?.parts?.[0]?.text || "").slice(0, 500)
       : task.statusMessage || "Failed",
+    viveworker: task.viveworker || {},
+    paidDeliverable: task.paidDeliverable || null,
     taskStatus: task.status,
     createdAtMs: task.updatedAtMs || Date.now(),
     readOnly: true,
@@ -237,6 +266,16 @@ export async function executeA2ATask(task, config, runtime, state, { recordTimel
         stableId: `a2a_task_result:${task.id}`,
         title: `A2A ${icon}: ${instruction.slice(0, 60)}`,
         body: resultBody || instruction.slice(0, 160),
+        buildLocalizedContent: ({ locale }) => {
+          const lang = locale?.startsWith("ja") ? "ja" : "en";
+          const instructionSnippet = instruction.slice(0, 60);
+          return {
+            title: isCompleted
+              ? (lang === "ja" ? `A2A 完了: ${instructionSnippet}` : `A2A completed: ${instructionSnippet}`)
+              : (lang === "ja" ? `A2A 失敗: ${instructionSnippet}` : `A2A failed: ${instructionSnippet}`),
+            body: resultBody || instruction.slice(0, 160),
+          };
+        },
       });
     } catch (error) {
       console.error(`[a2a-exec-push] ${error.message}`);
@@ -244,13 +283,225 @@ export async function executeA2ATask(task, config, runtime, state, { recordTimel
   }
 }
 
+export function resolveA2AExecutionOptions(task, config, executor) {
+  const spec = task?.viveworker || {};
+  const requestedModel = cleanText(spec.requestedModel || "");
+  const tier = cleanText(spec.requestedTier || "");
+  const proModel = cleanText(config?.a2aProModel || process.env.A2A_PRO_MODEL || "");
+  return {
+    model: requestedModel || (tier === "pro" ? proModel : ""),
+    tier,
+    executor,
+  };
+}
+
+export function buildA2AExecutionInstruction(instruction, task) {
+  const spec = task?.viveworker || {};
+  const tier = cleanText(spec.requestedTier || "");
+  if (tier !== "pro") {
+    return instruction;
+  }
+  const deliverableType = cleanText(spec.deliverableType || "research brief");
+  return [
+    "You are completing a paid A2A Pro deliverable.",
+    `Deliverable type: ${deliverableType}.`,
+    "Prioritize accuracy, clear structure, and actionable conclusions. Do not mention internal account tiers or subscription access.",
+    "",
+    instruction,
+  ].join("\n");
+}
+
+export function shouldUploadPaidDeliverable(task) {
+  return task?.viveworker?.paidDeliverable === true || cleanText(task?.viveworker?.mode || "") === "x402-pro";
+}
+
+function resolvePaidShareSpec(config, task) {
+  const spec = task?.viveworker || {};
+  const payment = spec.payment || {};
+  const price = cleanText(payment.price || config?.a2aProPrice || process.env.A2A_PRO_PRICE || "");
+  const payTo = cleanText(payment.payTo || config?.a2aProPayTo || process.env.A2A_PRO_PAY_TO || "");
+  const expiresDaysRaw = cleanText(spec.expiresDays || config?.a2aProExpiresDays || process.env.A2A_PRO_EXPIRES_DAYS || "7");
+  const expiresDays = Number(expiresDaysRaw);
+  if (!price || !payTo) {
+    throw new Error("x402-pro task requires price and payTo metadata, or A2A_PRO_PRICE and A2A_PRO_PAY_TO");
+  }
+  if (payment.invalid === true) {
+    throw new Error(`invalid x402 payment metadata: ${payment.reason || "invalid-payment"}`);
+  }
+  if (!/^\d+(\.\d{1,6})?$/u.test(price)) {
+    throw new Error("x402-pro price must be a decimal with up to 6 fractional digits");
+  }
+  if (!/^0x[0-9a-fA-F]{40}$/u.test(payTo)) {
+    throw new Error("x402-pro payTo must be a 0x-prefixed EVM address");
+  }
+  return {
+    price,
+    payTo,
+    expiresDays: Number.isFinite(expiresDays) && expiresDays > 0 && expiresDays <= 30 ? String(expiresDays) : "7",
+  };
+}
+
+export async function uploadPaidA2ADeliverable({ config, task, resultText }) {
+  const userId = cleanText(config?.a2aRelayUserId || "");
+  const apiKey = cleanText(config?.a2aApiKey || "");
+  const shareUrl = cleanText(config?.a2aShareUrl || process.env.VIVEWORKER_SHARE_URL || "https://share.viveworker.com").replace(/\/+$/u, "");
+  if (!userId || !apiKey) {
+    throw new Error("A2A credentials are required to upload paid deliverables");
+  }
+  const paidSpec = resolvePaidShareSpec(config, task);
+  const html = buildPaidDeliverableHtml({ task, resultText, paidSpec });
+  const form = new FormData();
+  const safeTaskId = cleanText(task?.id || "task").replace(/[^a-z0-9_-]+/giu, "-").slice(0, 64) || "task";
+  const file = new File(
+    [new Blob([html], { type: "text/html; charset=utf-8" })],
+    `a2a-${safeTaskId}-deliverable.html`,
+    { type: "text/html; charset=utf-8" }
+  );
+  form.set("file", file);
+  form.set("price", paidSpec.price);
+  form.set("payTo", paidSpec.payTo);
+  form.set("expiresDays", paidSpec.expiresDays);
+
+  const response = await fetchWithTimeout(`${shareUrl}/api/upload`, {
+    method: "POST",
+    headers: {
+      "x-a2a-user": userId,
+      "x-a2a-key": apiKey,
+    },
+    body: form,
+  }, 60_000);
+  const body = await readJson(response);
+  if (!response.ok || body?.error) {
+    throw new Error(`paid deliverable upload failed: ${formatApiError(response.status, body)}`);
+  }
+  return {
+    url: body.url,
+    slug: body.slug,
+    price: body.price ? formatUsdcAtomic(body.price) : paidSpec.price,
+    priceAtomic: body.price || "",
+    payTo: body.payTo || paidSpec.payTo,
+    network: body.network || "",
+    expiresAtMs: body.expiresAtMs || 0,
+  };
+}
+
+export function buildPaidUnlockResponse({ task, paidShare }) {
+  const deliverableType = cleanText(task?.viveworker?.deliverableType || "deliverable");
+  return [
+    `A2A Pro ${deliverableType} is ready.`,
+    "",
+    `Unlock URL: ${paidShare.url}`,
+    `Price: ${paidShare.price} USDC${paidShare.network ? ` on ${paidShare.network}` : ""}`,
+    `Pay to: ${paidShare.payTo}`,
+    "",
+    "Open the URL with an x402-compatible client or browser flow to pay and receive the result.",
+  ].join("\n");
+}
+
+function buildPaidDeliverableHtml({ task, resultText, paidSpec }) {
+  const title = `A2A Pro Deliverable`;
+  const instruction = cleanText(task?.instruction || "");
+  const created = new Date().toISOString();
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHtml(title)}</title>
+  <style>
+    :root { color-scheme: dark; --bg: #081015; --card: #121d24; --text: #eef7fb; --muted: #9fb3bf; --line: rgba(255,255,255,.12); --accent: #7dd3fc; }
+    body { margin: 0; background: radial-gradient(circle at 20% 0%, rgba(55, 211, 153, .16), transparent 34%), var(--bg); color: var(--text); font: 16px/1.65 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+    main { max-width: 860px; margin: 0 auto; padding: 56px 22px 72px; }
+    .badge { display: inline-flex; border: 1px solid var(--line); border-radius: 999px; padding: 6px 12px; color: var(--accent); font-weight: 700; letter-spacing: .02em; }
+    h1 { font-size: clamp(34px, 7vw, 64px); line-height: .96; letter-spacing: -.055em; margin: 24px 0 16px; }
+    .meta, .prompt, .result { background: rgba(18, 29, 36, .86); border: 1px solid var(--line); border-radius: 24px; padding: 22px; margin-top: 18px; box-shadow: 0 24px 80px rgba(0,0,0,.28); }
+    .meta { color: var(--muted); }
+    .meta strong { color: var(--text); }
+    pre { white-space: pre-wrap; word-break: break-word; margin: 0; font: inherit; }
+    h2 { margin: 0 0 10px; font-size: 18px; color: var(--accent); }
+  </style>
+</head>
+<body>
+  <main>
+    <span class="badge">viveworker A2A Pro</span>
+    <h1>Paid agent deliverable</h1>
+    <section class="meta">
+      <div><strong>Task:</strong> ${escapeHtml(task?.id || "")}</div>
+      <div><strong>Created:</strong> ${escapeHtml(created)}</div>
+      <div><strong>Price:</strong> ${escapeHtml(paidSpec.price)} USDC</div>
+      <div><strong>Pay to:</strong> ${escapeHtml(paidSpec.payTo)}</div>
+    </section>
+    <section class="prompt">
+      <h2>Request</h2>
+      <pre>${escapeHtml(instruction)}</pre>
+    </section>
+    <section class="result">
+      <h2>Result</h2>
+      <pre>${escapeHtml(resultText)}</pre>
+    </section>
+  </main>
+</body>
+</html>`;
+}
+
+async function readJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    return {};
+  }
+}
+
+function formatApiError(status, body) {
+  const error = cleanText(body?.error || body?.message || "");
+  const hint = cleanText(body?.hint || "");
+  return [`HTTP ${status}`, error, hint].filter(Boolean).join(" — ");
+}
+
+function formatUsdcAtomic(value) {
+  const raw = cleanText(value || "");
+  if (!/^\d+$/u.test(raw)) {
+    return raw;
+  }
+  const padded = raw.padStart(7, "0");
+  const whole = padded.slice(0, -6).replace(/^0+(?=\d)/u, "") || "0";
+  const frac = padded.slice(-6).replace(/0+$/u, "");
+  return frac ? `${whole}.${frac}` : whole;
+}
+
+function escapeHtml(value) {
+  return String(value ?? "")
+    .replace(/&/gu, "&amp;")
+    .replace(/</gu, "&lt;")
+    .replace(/>/gu, "&gt;")
+    .replace(/"/gu, "&quot;");
+}
+
+function cleanText(value) {
+  return String(value ?? "").replace(/\s+/gu, " ").trim();
+}
+
+async function fetchWithTimeout(url, init = {}, timeoutMs = 30_000) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 /**
  * Spawn `codex exec` and capture stdout+stderr.
  */
-function runCodexExec(instruction, config) {
+function runCodexExec(instruction, config, options = {}) {
   return new Promise((resolve, reject) => {
     const codexBin = resolveCodexBin(config);
-    const args = ["exec", "--full-auto", "--skip-git-repo-check", instruction];
+    const args = ["exec", "--full-auto", "--skip-git-repo-check"];
+    if (options.model) {
+      args.push("--model", options.model);
+    }
+    args.push(instruction);
     const cwd = config.workspaceRoot || os.tmpdir();
 
     const child = spawn(codexBin, args, {
@@ -303,10 +554,13 @@ function runCodexExec(instruction, config) {
 /**
  * Spawn `claude -p` and capture stdout+stderr.
  */
-function runClaudeExec(instruction) {
+function runClaudeExec(instruction, options = {}) {
   return new Promise((resolve, reject) => {
     const claudeBin = resolveClaudeBin();
     const args = ["-p", instruction, "--output-format", "text"];
+    if (options.model) {
+      args.push("--model", options.model);
+    }
 
     const child = spawn(claudeBin, args, {
       cwd: os.tmpdir(),

package/scripts/a2a-handler.mjs

@@ -158,6 +158,90 @@ function extractTextFromParts(parts) {
     .trim();
 }
 
+function isPlainObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value);
+}
+
+function cleanMetadataText(value, maxLength = 500) {
+  return String(value ?? "")
+    .replace(/\s+/gu, " ")
+    .trim()
+    .slice(0, maxLength);
+}
+
+const PRICE_REGEX = /^\d+(\.\d{1,6})?$/u;
+const ETH_ADDR_REGEX = /^0x[0-9a-fA-F]{40}$/u;
+
+function normalizeRequestedExecutor(value) {
+  const normalized = cleanMetadataText(value, 30).toLowerCase();
+  return normalized === "codex" || normalized === "claude" || normalized === "auto" ? normalized : "";
+}
+
+function normalizeRequestedTier(value) {
+  const normalized = cleanMetadataText(value, 50).toLowerCase();
+  if (normalized === "pro" || normalized === "pro-assisted" || normalized === "premium") {
+    return "pro";
+  }
+  if (normalized === "standard" || normalized === "free") {
+    return "standard";
+  }
+  return normalized || "";
+}
+
+function normalizePaymentSpec(source) {
+  const payment = isPlainObject(source?.payment) ? source.payment : source;
+  const price = cleanMetadataText(payment?.price ?? payment?.amount ?? payment?.amountUsdc ?? "", 30);
+  const payTo = cleanMetadataText(payment?.payTo ?? payment?.pay_to ?? payment?.recipient ?? "", 80);
+  if (!price && !payTo) {
+    return null;
+  }
+  if (!PRICE_REGEX.test(price) || !ETH_ADDR_REGEX.test(payTo)) {
+    return {
+      enabled: false,
+      invalid: true,
+      reason: "invalid-price-or-pay-to",
+      price,
+      payTo,
+    };
+  }
+  return {
+    enabled: true,
+    price,
+    payTo: payTo.toLowerCase(),
+    mode: cleanMetadataText(payment?.mode || source?.settlement || "x402", 40).toLowerCase() || "x402",
+  };
+}
+
+export function normalizeViveworkerTaskMetadata(metadata = {}) {
+  const root = isPlainObject(metadata) ? metadata : {};
+  const source = isPlainObject(root.viveworker) ? root.viveworker : root;
+  const mode = cleanMetadataText(source.mode || source.flow || "", 80).toLowerCase();
+  const requestedTier = normalizeRequestedTier(source.requestedTier || source.tier || source.qualityTier || source.modelTier);
+  const requestedExecutor = normalizeRequestedExecutor(source.requestedExecutor || source.executor);
+  const requestedModel = cleanMetadataText(source.requestedModel || source.model || "", 80);
+  const deliverableType = cleanMetadataText(source.deliverableType || source.deliverable || "research brief", 120);
+  const payment = normalizePaymentSpec(source);
+  const paidDeliverable =
+    mode === "x402-pro" ||
+    mode === "pay-per-unlock" ||
+    mode === "paid-unlock" ||
+    Boolean(payment);
+
+  if (!mode && !requestedTier && !requestedExecutor && !requestedModel && !paidDeliverable) {
+    return {};
+  }
+
+  return {
+    mode: mode || (paidDeliverable ? "x402-pro" : ""),
+    requestedTier,
+    requestedExecutor,
+    requestedModel,
+    deliverableType,
+    paidDeliverable,
+    payment,
+  };
+}
+
 function buildTaskResponse(task) {
   return {
     id: task.id,
@@ -269,6 +353,7 @@ async function handleMessageSend({
   const contextId = params.contextId || taskId();
   const token = historyToken(`a2a_task:${id}`);
   const now = Date.now();
+  const viveworker = normalizeViveworkerTaskMetadata(message.metadata || params.metadata || {});
 
   const task = {
     id,
@@ -279,6 +364,8 @@ async function handleMessageSend({
     messages: [message],
     artifacts: [],
     instruction,
+    metadata: message.metadata || params.metadata || {},
+    viveworker,
     callerInfo: {
       ip: req.socket?.remoteAddress || "",
       userAgent: req.headers["user-agent"] || "",
@@ -311,6 +398,7 @@ async function handleMessageSend({
         summary: cleanText(instruction).slice(0, 160),
         instruction,
         messageText: instruction,
+        viveworker,
         createdAtMs: now,
         readOnly: false,
         provider: "a2a",