xytara 2.5.0 → 2.6.0

package/bin/xytara-first-run.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const DEFAULT_SERVICE_URL = "https://xytara.onrender.com";
+const DEFAULT_KIT_URL = "https://www.naxytra.com/v1/first-run-kit";
+const DEFAULT_TEXT = "Summarize the Naxytra first-run path in one sentence.";
+const ACCOUNT_PLACEHOLDER = "ACCOUNT_REF";
+
+function buildDefaultMcpBody(text) {
+  return {
+    tool_name: "summarize",
+    arguments: {
+      text
+    }
+  };
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) continue;
+    const key = token.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      args[key] = true;
+      continue;
+    }
+    args[key] = next;
+    index += 1;
+  }
+  return args;
+}
+
+function buildLocalKit(args = {}) {
+  const serviceUrl = String(args.url || DEFAULT_SERVICE_URL).replace(/\/$/, "");
+  const account = String(args.account || ACCOUNT_PLACEHOLDER).trim();
+  const text = String(args.text || DEFAULT_TEXT);
+  const bodyJson = JSON.stringify(buildDefaultMcpBody(text));
+  const quoteCommand = [
+    "xytara-run",
+    "--url", serviceUrl,
+    "--account", account,
+    "--task", "adapter.mcp.invoke",
+    "--command", "mcp.invoke:summarize",
+    "--body-json", JSON.stringify(bodyJson),
+    "--quote-only",
+    "--pretty"
+  ].join(" ");
+  const creditsFirstCommand = [
+    "xytara",
+    "first-run",
+    "--execute-with-credits",
+    "--account", account,
+    "--pretty"
+  ].join(" ");
+  return {
+    ok: true,
+    product: "xytara",
+    category: "xytara-first-run-guide",
+    guide_version: "xytara-first-run-guide-v1",
+    public_command_kit_url: DEFAULT_KIT_URL,
+    recommended_public_mode: "quote_only_first_then_funded_execute_then_xoonya_proof",
+    safe_quote_command: quoteCommand,
+    credits_first_execute_command: creditsFirstCommand,
+    runnable_quote_command: account !== ACCOUNT_PLACEHOLDER,
+    runnable_credits_first_execute_command: account !== ACCOUNT_PLACEHOLDER,
+    proof_followthrough: [
+      "xoonya start-here",
+      "xoonya first-run --verify-native --pretty"
+    ],
+    boundaries: [
+      "quote_only_mode_needs_no_wallet_secret",
+      "funded_execution_needs_direct_payment_material_or_reusable_credits",
+      "proof_verification_continues_in_xoonya"
+    ]
+  };
+}
+
+async function fetchPublicKit(url) {
+  const response = await fetch(url, { headers: { accept: "application/json" } });
+  if (!response.ok) {
+    throw new Error(`first_run_kit_fetch_failed_${response.status}`);
+  }
+  return response.json();
+}
+
+async function postJson(url, payload) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      accept: "application/json"
+    },
+    body: JSON.stringify(payload)
+  });
+  const text = await response.text();
+  let json = null;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch (_) {
+    json = null;
+  }
+  return {
+    status: response.status,
+    ok: response.ok,
+    json,
+    text
+  };
+}
+
+function writeJson(payload, pretty) {
+  process.stdout.write(`${JSON.stringify(payload, null, pretty ? 2 : 0)}\n`);
+}
+
+function printUsage() {
+  process.stdout.write([
+    "Usage: xytara first-run [options]",
+    "",
+    "Options:",
+    "  --json                    Print the guided first-run object",
+    "  --offline                 Do not fetch the public command kit",
+    "  --run-quote               Execute the safe quote-only path",
+    "  --execute-with-credits    Execute the default task with account credits",
+    "  --account ACCOUNT_REF     Account ref for quote or credits-first execution",
+    `  --url <service_url>       Xytara service URL, default ${DEFAULT_SERVICE_URL}`,
+    "  --text <text>             Text for the default summarize task",
+    "  --pretty                  Pretty-print JSON output",
+    "  --help                    Show this help message"
+  ].join("\n"));
+}
+
+function runQuote(args) {
+  const account = String(args.account || "").trim();
+  if (!account) {
+    throw new Error("account_required_for_run_quote");
+  }
+  const serviceUrl = String(args.url || DEFAULT_SERVICE_URL).replace(/\/$/, "");
+  const text = String(args.text || DEFAULT_TEXT);
+  const scriptPath = path.join(__dirname, "xytara-run.js");
+  const result = spawnSync(process.execPath, [
+    scriptPath,
+    "--url", serviceUrl,
+    "--account", account,
+    "--task", "adapter.mcp.invoke",
+    "--command", "mcp.invoke:summarize",
+    "--body-json", JSON.stringify(buildDefaultMcpBody(text)),
+    "--quote-only",
+    ...(args.pretty ? ["--pretty"] : [])
+  ], { stdio: "inherit" });
+  process.exitCode = typeof result.status === "number" ? result.status : 1;
+}
+
+async function executeWithCredits(args) {
+  const account = String(args.account || "").trim();
+  if (!account) {
+    throw new Error("account_required_for_execute_with_credits");
+  }
+  const serviceUrl = String(args.url || DEFAULT_SERVICE_URL).replace(/\/$/, "");
+  const text = String(args.text || DEFAULT_TEXT);
+  const payload = {
+    account_id: account,
+    command: "mcp.invoke:summarize",
+    task_ref: "adapter.mcp.invoke",
+    payment_preference: "credits_first",
+    body: buildDefaultMcpBody(text)
+  };
+  const result = await postJson(`${serviceUrl}/v1/commands/execute`, payload);
+  writeJson(result.json || {
+    ok: false,
+    status: result.status,
+    body: result.text || null
+  }, args.pretty);
+  if (!result.ok) {
+    process.exitCode = 1;
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printUsage();
+    return;
+  }
+  if (args["run-quote"]) {
+    runQuote(args);
+    return;
+  }
+  if (args["execute-with-credits"]) {
+    await executeWithCredits(args);
+    return;
+  }
+
+  const localGuide = buildLocalKit(args);
+  if (args.json) {
+    if (args.offline) {
+      writeJson(localGuide, args.pretty);
+      return;
+    }
+    try {
+      const publicKit = await fetchPublicKit(DEFAULT_KIT_URL);
+      writeJson({
+        ...localGuide,
+        public_command_kit: publicKit
+      }, args.pretty);
+    } catch (error) {
+      writeJson({
+        ...localGuide,
+        public_command_kit_fetch_error: error.message
+      }, args.pretty);
+    }
+    return;
+  }
+
+  process.stdout.write([
+    "xytara first-run",
+    "",
+    "Safe first step:",
+    `  ${localGuide.safe_quote_command}`,
+    "",
+    "Run the safe quote-only path:",
+    `  xytara first-run --run-quote --account ACCOUNT_REF --pretty`,
+    "",
+    "Run the funded credits-first path:",
+    `  xytara first-run --execute-with-credits --account ACCOUNT_REF --pretty`,
+    "",
+    "Inspect the public command kit:",
+    `  ${DEFAULT_KIT_URL}`,
+    "",
+    "Then prove with:",
+    "  xoonya first-run --verify-native --pretty",
+    "",
+    "Boundary:",
+    "  quote-only mode needs no wallet secret; funded execution needs payment material or reusable credits."
+  ].join("\n"));
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+});

package/bin/xytara.js

@@ -11,11 +11,15 @@ function printUsage() {
     "Commands:",
     "  release [args]    Open the release/adoption/reporting surface",
     "  run [args]        Execute the paid runtime command path",
+    "  first-run [args]  Guide or run the safe public quote-first path",
     "  start-here        Print the shortest first-run path",
     "  help              Show this help message",
     "",
     "Fastest first run:",
     "  xytara start-here",
+    "  xytara first-run",
+    "  xytara first-run --run-quote --account ACCOUNT_REF --pretty",
+    "  xytara first-run --execute-with-credits --account ACCOUNT_REF --pretty",
     "  xytara release --summary",
     "  xytara run --help"
   ].join("\n"));
@@ -25,11 +29,30 @@ function printStartHere() {
   process.stdout.write([
     "xytara start-here",
     "",
-    "1. xytara release --summary",
-    "2. node examples/quickstart.js",
-    "3. npm run verify:all",
-    "4. Inspect /v1/providers, /v1/frameworks, /v1/protocols, /v1/integration-matrix",
-    "5. Continue into MCP/A2A/A2C/x402/settlement lanes as needed"
+    "Public first-run spine:",
+    "  quote -> pay/credits -> execute -> prove",
+    "",
+    "Guided CLI:",
+    "  xytara first-run",
+    "  xytara first-run --run-quote --account ACCOUNT_REF --pretty",
+    "  xytara first-run --execute-with-credits --account ACCOUNT_REF --pretty",
+    "",
+    "1. Open https://www.naxytra.com/v1/first-run-path",
+    "2. Open https://www.naxytra.com/v1/first-run-kit for copyable commands.",
+    "3. Quote safely first:",
+    "   xytara-run --url https://xytara.onrender.com --account ACCOUNT_REF --task adapter.mcp.invoke --command mcp.invoke:summarize --body-json \"{\\\"tool_name\\\":\\\"summarize\\\",\\\"arguments\\\":{\\\"text\\\":\\\"Summarize the Naxytra first-run path in one sentence.\\\"}}\" --quote-only --pretty",
+    "4. Execute with direct signed payment or credits-first on a funded account.",
+    "5. Hand the result into xoonya for proof review and verification.",
+    "",
+    "Boundaries:",
+    "  quote-only mode needs no wallet secret",
+    "  funded execution needs direct payment material or reusable credits",
+    "  proof stays in xoonya; runtime payment state stays in xytara",
+    "",
+    "Local package confidence:",
+    "  node examples/quickstart.js",
+    "  npm run verify:all",
+    "  xytara release --summary"
   ].join("\n"));
 }
 
@@ -49,6 +72,8 @@ if (!command || command === "help" || command === "--help" || command === "-h")
   delegate("xytara-release.js", rest);
 } else if (command === "run") {
   delegate("xytara-run.js", rest);
+} else if (command === "first-run" || command === "firstrun") {
+  delegate("xytara-first-run.js", rest);
 } else {
   printUsage();
   process.exitCode = 1;

package/integrations/dispatch.js

@@ -79,7 +79,11 @@ function chooseIntegration(options) {
   });
   const candidates = listIntegrations({ class: opts.adapterClass }).filter((integration) => {
     if (requestedIdsForClass.length > 0 && !requestedIdsForClass.includes(integration.integration_id)) return false;
-    if (requestedIdsForClass.length === 0 && integration.registration.default_selection_enabled !== true) return false;
+    if (
+      requestedIdsForClass.length === 0
+      && opts.allowNonDefaultSelection !== true
+      && integration.registration.default_selection_enabled !== true
+    ) return false;
     if (typeof opts.predicate === "function" && !opts.predicate(integration)) return false;
     return true;
   });
@@ -181,8 +185,9 @@ function resolveIntegrationSelection(payload) {
   const executionIntegrations = resolveExecutionIntegrations(taskRefs, adapterLanes, requestedIds);
   const identityIntegrations = resolveIdentityIntegrations(taskRefs, requestedIds);
   const protocolIntegrations = protocols.map((protocol) => chooseIntegration({
-    adapterClass: protocol === "x402" ? "payment_rail_adapter" : "agent_protocol_adapter",
+    adapterClass: protocol === "x402" || protocol === "l402" || protocol === "bolt" || protocol === "mpp" ? "payment_rail_adapter" : "agent_protocol_adapter",
     requestedIds,
+    allowNonDefaultSelection: explicitProtocol === protocol || explicitPaymentProtocol === protocol,
     predicate: (integration) => integration.protocols.includes(protocol)
   })).filter(Boolean);
   const settlementIntegration = chooseIntegration({

package/integrations/registry.js

@@ -40,6 +40,8 @@ function createBuiltinBreadthIntegration({
   adapter_lanes = [],
   task_refs = [],
   workflow_refs = [],
+  required_secrets = [],
+  required_permissions = [],
   supported_profiles = ["default"],
   pricing_basis = "per_task",
   latency_class = "mixed",
@@ -66,8 +68,8 @@ function createBuiltinBreadthIntegration({
     adapter_lanes: sortStrings(adapter_lanes),
     task_refs: sortStrings(task_refs),
     workflow_refs: sortStrings(workflow_refs),
-    required_secrets: [],
-    required_permissions: [],
+    required_secrets: sortStrings(required_secrets),
+    required_permissions: sortStrings(required_permissions),
     supported_profiles: sortStrings(supported_profiles),
     supported_regions: ["global"],
     pricing_basis,
@@ -1521,6 +1523,124 @@ function buildBuiltInIntegrations() {
         default_for_settlement_modes: sortStrings(settlementModes)
       }
     },
+    {
+      integration_id: "builtin.payment.l402",
+      display_name: "Built-In L402 Payment Admission",
+      description: "Built-in L402-style Lightning payment admission through a gateway-signed payment front.",
+      adapter_class: "payment_rail_adapter",
+      adapter_version: "1.4.0",
+      interface_version: "commerce-adapter-interface/v1",
+      bundled: true,
+      source: "builtin",
+      status: "available",
+      certification_state: "certified",
+      certification_scope: ["builtin_runtime", "service_contract", "sdk_contract"],
+      integration_maturity: "production_supported",
+      selection_priority: 65,
+      capabilities: ["payment.admission", "payment.challenge", "payment.permissionless_front"],
+      protocols: ["l402"],
+      settlement_modes: sortStrings(settlementModes),
+      execution_backends: [],
+      adapter_lanes: ["l402"],
+      task_refs: [],
+      workflow_refs: [],
+      required_secrets: ["XYTARA_L402_SHARED_SECRET"],
+      required_permissions: [],
+      supported_profiles: ["default"],
+      supported_regions: ["global"],
+      pricing_basis: "quote_then_settle",
+      latency_class: "near_real_time",
+      proof_contract: {
+        emits_proof_compatible_facts: true,
+        proof_mode: "payment_admission_facts"
+      },
+      health_contract: {
+        check_kind: "internal",
+        supports_readiness: true
+      },
+      idempotency_contract: {
+        strategy: "quote_id",
+        scope: "payment_admission"
+      },
+      failure_contract: {
+        categories: ["invalid_input", "quote_expired", "payment_missing"],
+        retryable_categories: []
+      },
+      compatibility: {
+        node: ">=18",
+        commerce_contract: "xytara/v1"
+      },
+      operational_readiness: {
+        supports_default_selection: false,
+        supports_forced_selection: true,
+        lifecycle: "managed_builtin",
+        health_source: "internal"
+      },
+      selection_hints: {
+        default_for_task_refs: [],
+        default_for_protocols: [],
+        default_for_settlement_modes: sortStrings(settlementModes)
+      }
+    },
+    {
+      integration_id: "builtin.payment.bolt",
+      display_name: "Built-In BOLT Payment Admission",
+      description: "Built-in BOLT-style UTXO/SPV payment admission through a signed proof-carrying payment front.",
+      adapter_class: "payment_rail_adapter",
+      adapter_version: "1.4.0",
+      interface_version: "commerce-adapter-interface/v1",
+      bundled: true,
+      source: "builtin",
+      status: "available",
+      certification_state: "certified",
+      certification_scope: ["builtin_runtime", "service_contract", "sdk_contract"],
+      integration_maturity: "production_supported",
+      selection_priority: 66,
+      capabilities: ["payment.admission", "payment.challenge", "payment.permissionless_front", "payment.spv_proof"],
+      protocols: ["bolt"],
+      settlement_modes: sortStrings(settlementModes),
+      execution_backends: [],
+      adapter_lanes: ["bolt"],
+      task_refs: [],
+      workflow_refs: [],
+      required_secrets: ["XYTARA_BOLT_SHARED_SECRET"],
+      required_permissions: [],
+      supported_profiles: ["default"],
+      supported_regions: ["global"],
+      pricing_basis: "quote_then_settle",
+      latency_class: "near_real_time",
+      proof_contract: {
+        emits_proof_compatible_facts: true,
+        proof_mode: "spv_or_block_header_verifiable_payment_facts"
+      },
+      health_contract: {
+        check_kind: "internal",
+        supports_readiness: true
+      },
+      idempotency_contract: {
+        strategy: "quote_id",
+        scope: "payment_admission"
+      },
+      failure_contract: {
+        categories: ["invalid_input", "quote_expired", "payment_missing"],
+        retryable_categories: []
+      },
+      compatibility: {
+        node: ">=18",
+        commerce_contract: "xytara/v1"
+      },
+      operational_readiness: {
+        supports_default_selection: false,
+        supports_forced_selection: true,
+        lifecycle: "managed_builtin",
+        health_source: "internal"
+      },
+      selection_hints: {
+        default_for_task_refs: [],
+        default_for_protocols: [],
+        default_for_settlement_modes: sortStrings(settlementModes)
+      }
+    },
     {
       integration_id: "builtin.settlement.chain",
       display_name: "Built-In Chain Settlement",
@@ -1791,6 +1911,7 @@ function buildBuiltInIntegrations() {
       protocols: ["mpp"],
       settlement_modes: sortStrings(settlementModes),
       adapter_lanes: ["mpp"],
+      required_secrets: ["XYTARA_MPP_SHARED_SECRET"],
       supported_profiles: ["payment"]
     }),
     createBuiltinBreadthIntegration({