run402 4.16.1 → 4.17.0

package/README.md

@@ -74,7 +74,7 @@ This links two separately held public identities through fresh signatures; it ne
 
 ### Buzz community control plane
 
-`run402 buzz status` reports skill installation, human adoption, community installation, and this agent's enrollment independently, and safely reports `supported: false` against an older gateway. Goal-shaped workflows are `buzz adopt`, `buzz install`, and `buzz enroll`; explicit decisions are `buzz adopt complete|cancel`, `buzz install activate|update|revoke`, and `buzz approve|deny|revoke`. `buzz install discover --community <buzz:community:host>` lists Run402-owned active descriptors without authentication. Activation alone accepts the ordinary Buzz kind-1 approval proof; updates and revocation are Run402-owner decisions and require no new Buzz signature. All print JSON to stdout, advice to stderr, have zero spend impact, and never accept Nostr/wallet secrets, session material, service keys, delegates, or payment credentials. Failure JSON preserves the gateway's code-specific `next_actions`, exact repair `field`, and retry safety; never replace it with a generic edit-and-retry. See the [Fizz/Honey examples](../buzz/references/community-control-plane.md).
+`run402 buzz status` reports skill installation, human-adoption offers/adoptions, community installation, and this agent's enrollment independently, and safely reports `supported: false` against an older gateway. The canonical ownership workflow is `buzz adopt offer --org … --identity-link …`: it capability-checks before mutation and returns a normal durable HTTPS handoff. Poll with `buzz adopt offer show <buzzhao_id>` and cancel with `buzz adopt offer cancel <buzzhao_id>`. The raw challenge command is explicitly advanced as `buzz adopt direct …`; direct completion/cancellation remain `buzz adopt complete|cancel`. Other goal workflows are `buzz install` and `buzz enroll`; decisions are `buzz install activate|update|revoke` and `buzz approve|deny|revoke`. `buzz install discover --community <buzz:community:host>` lists Run402-owned active descriptors without authentication. MCP intentionally has no signing/passkey mutation and only renders exact HTTPS/CLI handoffs. All commands print JSON to stdout, advice to stderr, have zero spend impact, and never accept Nostr/wallet secrets, session material, service keys, delegates, or payment credentials. Failure JSON preserves the gateway's code-specific `next_actions`, exact repair `field`, and retry safety; never replace it with a generic edit-and-retry. See the [Fizz/Honey examples](../buzz/references/community-control-plane.md).
 
 ### Buy from an x402 URL
 

package/cli.mjs

@@ -67,7 +67,7 @@ Commands:
   operator    Operator (human/email) session — login, then overview across your wallets
   service     Run402 service health and availability (status, health)
   cache       Inspect and invalidate the SSR origin cache (inspect, invalidate)
-  doctor      Health and config diagnostics (machine-readable with --json)
+  doctor      Health and config diagnostics (JSON by default; includes --buzz preflight)
   dev         Run Astro dev with Run402 env + credentials in scope
   logs        Fetch function logs by request id (--request-id req_...)
 

package/lib/buzz-doctor-contract.mjs

@@ -0,0 +1,97 @@
+import { readFileSync } from "node:fs";
+
+const CONTRACT_URL = new URL("../../buzz/fixtures/run402-buzz-doctor-v1-contract.json", import.meta.url);
+
+export const BUZZ_DOCTOR_CONTRACT = deepFreeze(JSON.parse(readFileSync(CONTRACT_URL, "utf8")));
+export const BUZZ_DOCTOR_CONTRACT_ID = BUZZ_DOCTOR_CONTRACT.contract_id;
+export const BUZZ_DOCTOR_CHECK_ORDER = BUZZ_DOCTOR_CONTRACT.check_order;
+export const BUZZ_DOCTOR_STATUSES = new Set(BUZZ_DOCTOR_CONTRACT.statuses);
+export const BUZZ_DOCTOR_ACTION_SURFACES = new Set(BUZZ_DOCTOR_CONTRACT.next_action.surfaces);
+export const BUZZ_DOCTOR_MAX_AGE_MS = BUZZ_DOCTOR_CONTRACT.freshness.max_age_seconds * 1000;
+
+export function validateBuzzDoctorAction(action, { surface } = {}) {
+  if (!action || typeof action !== "object" || Array.isArray(action)) return "action_not_object";
+  for (const field of BUZZ_DOCTOR_CONTRACT.next_action.required_fields) {
+    if (!(field in action)) return `action_missing_${field}`;
+  }
+  if (!BUZZ_DOCTOR_ACTION_SURFACES.has(action.surface)) return "action_surface_invalid";
+  if (surface && action.surface !== surface) return "action_surface_mismatch";
+  if (typeof action.type !== "string" || action.type.length === 0) return "action_type_invalid";
+  if (typeof action.command !== "string" || action.command.length === 0) return "action_command_invalid";
+  if (typeof action.why !== "string" || action.why.length === 0) return "action_why_invalid";
+  for (const field of ["safe_to_auto_execute", "requires_approval", "destructive", "idempotent"]) {
+    if (typeof action[field] !== "boolean") return `action_${field}_invalid`;
+  }
+  if (!action.spend_impact || action.spend_impact.currency !== "USD" || action.spend_impact.max_amount !== "0") {
+    return "action_spend_impact_invalid";
+  }
+  if (action.surface === "shell") {
+    if (!Array.isArray(action.argv) || action.argv.length === 0 || action.argv.some((part) => typeof part !== "string")) {
+      return "action_argv_invalid";
+    }
+  } else {
+    for (const field of BUZZ_DOCTOR_CONTRACT.next_action.non_shell_forbidden_fields) {
+      if (field in action) return `action_${field}_forbidden`;
+    }
+  }
+  return null;
+}
+
+export function validateBuzzDoctorReport(report, {
+  expectedSubjectHex,
+  walletProfile,
+  nodeExecutable,
+  run402Executable,
+  relayOrigin,
+  now = Date.now(),
+} = {}) {
+  if (!report || typeof report !== "object" || Array.isArray(report)) return { valid: false, reason: "report_not_object" };
+  if (report.contract_id !== BUZZ_DOCTOR_CONTRACT_ID || report.mode !== "buzz") return { valid: false, reason: "contract_mismatch" };
+  if (!Array.isArray(report.checks)) return { valid: false, reason: "checks_not_array" };
+  if (report.checks.length !== BUZZ_DOCTOR_CHECK_ORDER.length) return { valid: false, reason: "check_count_mismatch" };
+  for (let index = 0; index < BUZZ_DOCTOR_CHECK_ORDER.length; index += 1) {
+    const check = report.checks[index];
+    const expectedName = BUZZ_DOCTOR_CHECK_ORDER[index];
+    if (!check || check.name !== expectedName) return { valid: false, reason: "check_order_mismatch" };
+    if (!BUZZ_DOCTOR_STATUSES.has(check.status)) return { valid: false, reason: "check_status_invalid" };
+    if (check.status === "blocked" && !BUZZ_DOCTOR_CONTRACT.codes_by_check[expectedName]?.includes(check.code)) {
+      return { valid: false, reason: "check_code_invalid" };
+    }
+    const actionable = check.status === "blocked" || (check.status === "warning" && Array.isArray(check.next_actions));
+    if (actionable) {
+      if (!Array.isArray(check.next_actions) || check.next_actions.length !== 1) return { valid: false, reason: "action_cardinality_invalid" };
+      const actionReason = validateBuzzDoctorAction(check.next_actions[0]);
+      if (actionReason) return { valid: false, reason: actionReason };
+    } else if ("next_actions" in check) {
+      return { valid: false, reason: "passing_action_forbidden" };
+    }
+  }
+  const generatedAt = Date.parse(report.generated_at);
+  if (!Number.isFinite(generatedAt) || generatedAt > now || now - generatedAt > BUZZ_DOCTOR_MAX_AGE_MS) {
+    return { valid: false, reason: "report_stale" };
+  }
+  const binding = report.binding;
+  if (!binding || typeof binding !== "object") return { valid: false, reason: "binding_missing" };
+  const expected = {
+    contract_id: BUZZ_DOCTOR_CONTRACT_ID,
+    expected_subject_hex: expectedSubjectHex,
+    wallet_profile: walletProfile,
+    node_executable: nodeExecutable,
+    run402_executable: run402Executable,
+    relay_origin: relayOrigin,
+  };
+  for (const field of BUZZ_DOCTOR_CONTRACT.freshness.binding_fields) {
+    if (expected[field] !== undefined && binding[field] !== expected[field]) return { valid: false, reason: `binding_${field}_mismatch` };
+  }
+  const computedOk = report.checks.every((check) => check.status !== "blocked");
+  if (report.ok !== computedOk) return { valid: false, reason: "verdict_mismatch" };
+  if (report.mutation_state !== BUZZ_DOCTOR_CONTRACT.zero_mutation.mutation_state) return { valid: false, reason: "mutation_state_invalid" };
+  return { valid: true, reason: null };
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const child of Object.values(value)) deepFreeze(child);
+  return value;
+}

package/lib/buzz-doctor-contract.test.mjs

@@ -0,0 +1,127 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { describe, it } from "node:test";
+import {
+  BUZZ_DOCTOR_CHECK_ORDER,
+  BUZZ_DOCTOR_CONTRACT,
+  BUZZ_DOCTOR_CONTRACT_ID,
+  validateBuzzDoctorAction,
+  validateBuzzDoctorReport,
+} from "./buzz-doctor-contract.mjs";
+
+const FIXTURE = JSON.parse(readFileSync(new URL("../../buzz/fixtures/buzz-v0.5.2-cli-capabilities.json", import.meta.url), "utf8"));
+
+function shellAction() {
+  return {
+    type: "upgrade_client",
+    surface: "shell",
+    command: "npm install -g run402@latest",
+    argv: ["npm", "install", "-g", "run402@latest"],
+    why: "Install the compatible Run402 CLI.",
+    safe_to_auto_execute: true,
+    requires_approval: false,
+    destructive: false,
+    idempotent: true,
+    spend_impact: { currency: "USD", max_amount: "0" },
+  };
+}
+
+function passingReport(now) {
+  return {
+    ok: true,
+    mode: "buzz",
+    contract_id: BUZZ_DOCTOR_CONTRACT_ID,
+    generated_at: new Date(now).toISOString(),
+    mutation_state: "not_started",
+    binding: {
+      contract_id: BUZZ_DOCTOR_CONTRACT_ID,
+      expected_subject_hex: "a".repeat(64),
+      wallet_profile: "buzz-fizz",
+      node_executable: "/usr/local/bin/node",
+      run402_executable: "/usr/local/bin/run402",
+      relay_origin: "wss://community.example",
+    },
+    checks: BUZZ_DOCTOR_CHECK_ORDER.map((name) => ({ name, status: "ok" })),
+    telemetry: { status: "disabled" },
+  };
+}
+
+describe("Buzz doctor v1 frozen contract", () => {
+  it("freezes the ordered checks, flags, statuses, exit streams, freshness binding, and zero-mutation verdict", () => {
+    assert.equal(BUZZ_DOCTOR_CONTRACT_ID, "run402.buzz-doctor.v1");
+    assert.deepEqual(BUZZ_DOCTOR_CHECK_ORDER, [
+      "session_shell", "node_runtime", "run402_cli", "buzz_cli", "buzz_agent_target",
+      "run402_api", "run402_console", "buzz_relay", "wallet_profile",
+    ]);
+    assert.deepEqual(BUZZ_DOCTOR_CONTRACT.statuses, ["ok", "warning", "blocked"]);
+    assert.deepEqual(BUZZ_DOCTOR_CONTRACT.flags, { mode: "--buzz", agent: "--buzz-agent", profile: "--wallet" });
+    assert.deepEqual(BUZZ_DOCTOR_CONTRACT.exit_behavior, {
+      passed_or_warning_only: 0,
+      completed_with_blocked_checks: 1,
+      usage_error: 1,
+      completed_report_stream: "stdout",
+      usage_error_stream: "stderr",
+    });
+    assert.equal(BUZZ_DOCTOR_CONTRACT.freshness.max_age_seconds, 60);
+    assert.deepEqual(BUZZ_DOCTOR_CONTRACT.setup_rejection_codes, [
+      "BUZZ_PREFLIGHT_REPORT_INVALID",
+      "BUZZ_PREFLIGHT_REPORT_STALE",
+      "BUZZ_PREFLIGHT_REPORT_MISMATCH",
+    ]);
+    assert.equal(BUZZ_DOCTOR_CONTRACT.zero_mutation.mutation_state, "not_started");
+    assert.ok(BUZZ_DOCTOR_CONTRACT.zero_mutation.forbidden.includes("buzz_event_publish"));
+    assert.ok(BUZZ_DOCTOR_CONTRACT.zero_mutation.forbidden.includes("run402_identity_link_mutation"));
+  });
+
+  it("requires exactly one complete destination-specific action on every actionable check", () => {
+    assert.equal(validateBuzzDoctorAction(shellAction()), null);
+    assert.equal(validateBuzzDoctorAction({ ...shellAction(), argv: undefined }), "action_argv_invalid");
+    const chat = { ...shellAction(), surface: "buzz_chat", command: "@Fizz restart setup" };
+    delete chat.argv;
+    assert.equal(validateBuzzDoctorAction(chat), null);
+    assert.equal(validateBuzzDoctorAction({ ...chat, argv: ["echo", "wrong"] }), "action_argv_forbidden");
+  });
+
+  it("rejects stale, reordered, mismatched, edited, or verdict-inconsistent reports", () => {
+    const now = Date.parse("2026-07-31T12:00:00.000Z");
+    const expected = {
+      expectedSubjectHex: "a".repeat(64),
+      walletProfile: "buzz-fizz",
+      nodeExecutable: "/usr/local/bin/node",
+      run402Executable: "/usr/local/bin/run402",
+      relayOrigin: "wss://community.example",
+      now,
+    };
+    assert.deepEqual(validateBuzzDoctorReport(passingReport(now), expected), { valid: true, reason: null });
+    assert.equal(validateBuzzDoctorReport(passingReport(now - 61_000), expected).reason, "report_stale");
+    const reordered = passingReport(now);
+    reordered.checks.reverse();
+    assert.equal(validateBuzzDoctorReport(reordered, expected).reason, "check_order_mismatch");
+    assert.equal(validateBuzzDoctorReport(passingReport(now), { ...expected, walletProfile: "buzz-honey" }).reason, "binding_wallet_profile_mismatch");
+    const edited = passingReport(now);
+    edited.checks[0] = { name: "session_shell", status: "blocked", code: "MADE_UP", next_actions: [shellAction()] };
+    assert.equal(validateBuzzDoctorReport(edited, expected).reason, "check_code_invalid");
+    const falseVerdict = passingReport(now);
+    falseVerdict.ok = false;
+    assert.equal(validateBuzzDoctorReport(falseVerdict, expected).reason, "verdict_mismatch");
+  });
+
+  it("freezes released Buzz v0.5.2 as capability-first with JSON outputs and no version flag", () => {
+    assert.equal(FIXTURE.fixture_id, "buzz-cli-v0.5.2-capabilities");
+    assert.equal(FIXTURE.buzz_release.release_tag_commit, "3e48f1b2365d326ee1c9582448d86a99b44ecd5d");
+    assert.deepEqual(FIXTURE.help_probes.map((probe) => probe.argv.slice(1)), [
+      ["--help"],
+      ["users", "get", "--help"],
+      ["social", "publish", "--help"],
+      ["social", "event", "--help"],
+    ]);
+    assert.equal(FIXTURE.version_probe.supported, false);
+    assert.equal(FIXTURE.version_probe.stderr_json.error, "user_error");
+    assert.equal(FIXTURE.json_contract.default_output_format, "json");
+    assert.equal(FIXTURE.json_contract.users_get_success_stdout.type, "array");
+    assert.equal(FIXTURE.managed_sidecar.public_package_manager_install, false);
+    assert.equal(FIXTURE.managed_sidecar.repair_surface, "buzz_settings");
+    assert.equal(FIXTURE.public_self_observation.requires_private_key_value_inspection, false);
+    assert.equal(FIXTURE.write_surface_policy.publish_is_never_invoked_by_doctor, true);
+  });
+});