@tokenbuddy/tb-admin 1.0.13 → 1.0.15

package/src/ui-actions.ts

@@ -0,0 +1,901 @@
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import YAML from "js-yaml";
+import type { SellerRegistryDocument, SellerRegistryEntry } from "./bootstrap-registry.js";
+import { ConfigManager } from "./config.js";
+import { AdminUiState } from "./ui-state.js";
+
+export interface UiActionResult {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  command: string[];
+}
+
+export interface CreateSellerRequest {
+  sellerName: string;
+  region: string;
+  image: string;
+  upstreamWebsite: string;
+  upstreamUrl: string;
+  upstreamApiKey: string;
+  upstreamBalanceProbeTemplate?: string;
+  upstreamBalanceProbeUrl?: string;
+  upstreamBalanceProbeUserId?: string;
+  upstreamBalanceProbeRechargeUrl?: string;
+  upstreamBalanceUrl?: string;
+  upstreamUserId?: string;
+  upstreamRechargeUrl?: string;
+  maxConnections: number;
+  maxQueueDepth: number;
+  markupRatio: number;
+  discountRatio: number;
+  paymentMethods?: string[] | string;
+  paymentMethod?: string;
+  clawtipPayTo?: string;
+  clawtipSm4KeyBase64?: string;
+  clawtipSkillSlug?: string;
+  clawtipSkillId?: string;
+  clawtipDescription?: string;
+  clawtipResourceUrl?: string;
+  clawtipActivationFeeFen?: number;
+  clawtipMicrosPerFen?: number;
+  flyConfig?: string;
+  operatorSecret?: string;
+  app?: string;
+  dryRun?: boolean;
+}
+
+export interface UiActionsOptions {
+  configManager: ConfigManager;
+  configPath?: string;
+  profile?: string;
+  url?: string;
+  token?: string;
+  fetchJson?: (url: string, init?: RequestInit) => Promise<unknown>;
+  commandRunner?: (args: string[], timeoutMs: number) => Promise<UiActionResult>;
+}
+
+type ConfigPatch = Record<string, unknown>;
+export type UiActionProgressStatus = "pending" | "running" | "succeeded" | "failed" | "skipped";
+export type UiActionProgressStepId = "check_registry" | "validate_config" | "create_deployment" | "wait_seller" | "apply_config" | "refresh_models" | "publish_registry";
+
+export interface UiActionProgressEvent {
+  stepId: UiActionProgressStepId;
+  status: UiActionProgressStatus;
+  title: string;
+  message?: string;
+  result?: UiActionResult;
+}
+
+type UiActionProgressReporter = (event: UiActionProgressEvent) => void;
+
+export class UiActions {
+  private readonly state: AdminUiState;
+  private readonly options: UiActionsOptions;
+  private readonly commandRunner?: (args: string[], timeoutMs: number) => Promise<UiActionResult>;
+
+  constructor(options: UiActionsOptions) {
+    this.options = options;
+    this.commandRunner = options.commandRunner;
+    this.state = new AdminUiState(options);
+  }
+
+  public async updateSellerConfig(id: string, patch: ConfigPatch): Promise<UiActionResult> {
+    const { profileName, config } = await this.state.rawSellerConfig(id);
+    if (!profileName) {
+      throw new Error(`seller \`${id}\` has no local profile for seller-config put`);
+    }
+    const next = mergeSellerConfigPatch(config, patch);
+    return this.withTempYaml(next, async (filePath) => {
+      const validate = await this.runAdmin(profileArgs(this.options, profileName, ["seller-config", "validate", "--file", filePath]), 30000);
+      if (!validate.ok) {
+        return validate;
+      }
+      return this.runAdmin(profileArgs(this.options, profileName, ["seller-config", "put", "--file", filePath]), 30000);
+    });
+  }
+
+  public async createSeller(request: CreateSellerRequest, progress?: UiActionProgressReporter): Promise<{ result: UiActionResult; configValidation: UiActionResult; readiness?: UiActionResult; configPut?: UiActionResult; modelsRefresh?: UiActionResult; registryPublish?: UiActionResult; configPreview: Record<string, unknown>; publishRegistry: "completed" | "failed" | "skipped" }> {
+    const normalizedRequest = normalizeCreateSellerRequest(request);
+    const report = progress || (() => undefined);
+    validateCreateSellerRequest(normalizedRequest);
+    report({ stepId: "check_registry", status: "running", title: "Check bootstrap registry", message: "Checking seller name conflicts before creating Fly resources." });
+    const registry = await this.state.fetchRegistry();
+    const appName = normalizedRequest.app || normalizedRequest.sellerName;
+    const conflict = registry.sellers.find((seller) => {
+      return seller.id === normalizedRequest.sellerName || seller.name === normalizedRequest.sellerName || seller.app === appName;
+    });
+    if (conflict) {
+      throw new Error(`seller \`${normalizedRequest.sellerName}\` already exists in bootstrap registry`);
+    }
+    report({ stepId: "check_registry", status: "succeeded", title: "Check bootstrap registry", message: "No registry conflict found." });
+    const provider = this.options.configManager.getSellerProvider("fly");
+    const operatorSecret = normalizedRequest.operatorSecret || provider?.operator_secret;
+    const flyConfig = normalizedRequest.flyConfig;
+    if (!operatorSecret) {
+      throw new Error("operatorSecret is required in local admin config seller_providers.fly.operator_secret or request body");
+    }
+    if (!flyConfig) {
+      throw new Error("flyConfig is required before creating a seller deployment");
+    }
+    const configRequest = {
+      ...normalizedRequest,
+      operatorSecret
+    };
+
+    return this.withTempYaml(initialSellerConfig(configRequest, false), async (filePath) => {
+      const normalizedUpstreamMessage = normalizedRequest.upstreamUrl !== request.upstreamUrl
+        ? `Normalized upstreamUrl to ${normalizedRequest.upstreamUrl} before validation.`
+        : "";
+      report({ stepId: "validate_config", status: "running", title: "Validate seller config", message: normalizedUpstreamMessage || "Validating generated seller config." });
+      const configValidation = await this.runAdmin(globalArgs(this.options, ["seller-config", "validate", "--file", filePath]), 30000);
+      report({
+        stepId: "validate_config",
+        status: configValidation.ok ? "succeeded" : "failed",
+        title: "Validate seller config",
+        message: configValidation.ok ? `${normalizedUpstreamMessage} Seller config is valid.`.trim() : "Seller config validation failed.",
+        result: configValidation
+      });
+      if (!configValidation.ok) {
+        return {
+          result: configValidation,
+          configValidation,
+          configPreview: initialSellerConfig(configRequest, true),
+          publishRegistry: "skipped"
+        };
+      }
+      const args = [
+        "seller",
+        "create",
+        normalizedRequest.sellerName,
+        "--region",
+        normalizedRequest.region,
+        "--image",
+        normalizedRequest.image,
+        "--fly-config",
+        flyConfig,
+        "--initial-config",
+        filePath,
+        "--operator-secret",
+        operatorSecret
+      ];
+      if (normalizedRequest.app) {
+        args.push("--app", normalizedRequest.app);
+      }
+      if (normalizedRequest.dryRun) {
+        args.push("--dry-run");
+      }
+      report({ stepId: "create_deployment", status: "running", title: "Create Fly deployment", message: `Creating ${appName} in ${normalizedRequest.region}.` });
+      const result = await this.runAdmin(globalArgs(this.options, args), 10 * 60 * 1000);
+      report({
+        stepId: "create_deployment",
+        status: result.ok ? "succeeded" : "failed",
+        title: "Create Fly deployment",
+        message: result.ok ? "Fly deployment command completed." : "Fly deployment command failed.",
+        result
+      });
+      let configPut: UiActionResult | undefined;
+      let modelsRefresh: UiActionResult | undefined;
+      let readiness: UiActionResult | undefined;
+      if (result.ok && !normalizedRequest.dryRun) {
+        readiness = await this.waitForSellerReady(appName, operatorSecret, report);
+        if (!readiness.ok) {
+          return {
+            result,
+            configValidation,
+            readiness,
+            configPreview: initialSellerConfig(configRequest, true),
+            publishRegistry: "skipped"
+          };
+        }
+        report({ stepId: "apply_config", status: "running", title: "Apply seller config", message: `Writing config to ${sellerOperatorUrl(appName)}.` });
+        configPut = await this.runAdmin(globalArgs(
+          {
+            ...this.options,
+            profile: undefined,
+            url: sellerOperatorUrl(appName),
+            token: operatorSecret
+          },
+          ["seller-config", "put", "--file", filePath]
+        ), 30000);
+        report({
+          stepId: "apply_config",
+          status: configPut.ok ? "succeeded" : "failed",
+          title: "Apply seller config",
+          message: configPut.ok ? "Seller config was written to the deployment." : "Seller config write failed.",
+          result: configPut
+        });
+        if (configPut.ok) {
+          report({ stepId: "refresh_models", status: "running", title: "Refresh upstream models", message: `Refreshing model catalog from ${sellerOperatorUrl(appName)}.` });
+          modelsRefresh = await this.runAdmin(globalArgs(
+            {
+              ...this.options,
+              profile: undefined,
+              url: sellerOperatorUrl(appName),
+              token: operatorSecret
+            },
+            ["upstreams", "refresh", "--auto-models"]
+          ), 30000);
+          report({
+            stepId: "refresh_models",
+            status: modelsRefresh.ok ? "succeeded" : "failed",
+            title: "Refresh upstream models",
+            message: modelsRefresh.ok ? "Upstream model catalog was refreshed." : "Upstream model refresh failed.",
+            result: modelsRefresh
+          });
+        }
+      } else if (normalizedRequest.dryRun) {
+        report({ stepId: "apply_config", status: "skipped", title: "Apply seller config", message: "Skipped because this is a dry run." });
+        report({ stepId: "refresh_models", status: "skipped", title: "Refresh upstream models", message: "Skipped because this is a dry run." });
+      }
+      const registryPublish = await this.publishCreatedSellerRegistryEntry({
+        registry,
+        request: normalizedRequest,
+        appName,
+        operatorSecret,
+        enabled: Boolean(result.ok && !normalizedRequest.dryRun && readiness?.ok && configPut?.ok && modelsRefresh?.ok),
+        report
+      });
+      return {
+        result,
+        configValidation,
+        readiness,
+        configPut,
+        modelsRefresh,
+        registryPublish,
+        configPreview: initialSellerConfig(configRequest, true),
+        publishRegistry: registryPublish ? (registryPublish.ok ? "completed" : "failed") : "skipped"
+      };
+    });
+  }
+
+  public async setRegistryStatus(id: string, status: "active" | "draining" | "offline"): Promise<UiActionResult> {
+    const registry = await this.state.fetchRegistry();
+    const target = registry.sellers.find((seller) => seller.id === id || seller.name === id || seller.app === id);
+    if (!target) {
+      throw new Error(`seller \`${id}\` not found in bootstrap registry`);
+    }
+    const next = {
+      ...registry,
+      updatedAt: new Date().toISOString(),
+      sellers: registry.sellers.map((seller) => seller === target ? { ...seller, status } : seller)
+    };
+    return this.withTempJson(next, async (filePath) => {
+      const validate = await this.runAdmin(globalArgs(this.options, ["bootstrap", "sellers", "validate", "--file", filePath]), 30000);
+      if (!validate.ok) {
+        return validate;
+      }
+      return this.runAdmin(globalArgs(this.options, ["bootstrap", "sellers", "put", "--file", filePath]), 30000);
+    });
+  }
+
+  public async deleteDeployment(id: string, confirm: boolean): Promise<UiActionResult> {
+    const registry = await this.state.fetchRegistry();
+    const target = registry.sellers.find((seller) => seller.id === id || seller.name === id || seller.app === id);
+    if (!target) {
+      throw new Error(`seller \`${id}\` not found in bootstrap registry`);
+    }
+    const app = target.app || target.id || target.name;
+    const args = ["seller", "remove", app, "--app", app];
+    if (!confirm) {
+      args.push("--dry-run");
+    }
+    return this.runAdmin(globalArgs(this.options, args), confirm ? 10 * 60 * 1000 : 30000);
+  }
+
+  private async withTempYaml<T>(document: unknown, callback: (filePath: string) => Promise<T>): Promise<T> {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "tb-admin-ui-"));
+    const filePath = path.join(dir, "seller-config.yaml");
+    try {
+      fs.writeFileSync(filePath, YAML.dump(document, { lineWidth: 120, noRefs: true, sortKeys: false }), "utf8");
+      return await callback(filePath);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  }
+
+  private async withTempJson<T>(document: unknown, callback: (filePath: string) => Promise<T>): Promise<T> {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "tb-admin-ui-"));
+    const filePath = path.join(dir, "registry.json");
+    try {
+      fs.writeFileSync(filePath, JSON.stringify(document, null, 2), "utf8");
+      return await callback(filePath);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  }
+
+  private runAdmin(args: string[], timeoutMs: number): Promise<UiActionResult> {
+    if (this.commandRunner) {
+      return this.commandRunner(args, timeoutMs);
+    }
+    return runTbAdmin(args, timeoutMs);
+  }
+
+  private async waitForSellerReady(appName: string, operatorSecret: string, report: UiActionProgressReporter): Promise<UiActionResult> {
+    const maxAttempts = 18;
+    const delayMs = 5000;
+    let last: UiActionResult | undefined;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      report({
+        stepId: "wait_seller",
+        status: "running",
+        title: "Wait for seller service",
+        message: `Waiting for operator API to become ready (${attempt}/${maxAttempts}).`
+      });
+      last = await this.runAdmin(globalArgs(
+        {
+          ...this.options,
+          profile: undefined,
+          url: sellerOperatorUrl(appName),
+          token: operatorSecret
+        },
+        ["status"]
+      ), 30000);
+      if (last.ok) {
+        report({
+          stepId: "wait_seller",
+          status: "succeeded",
+          title: "Wait for seller service",
+          message: "Seller operator API is ready.",
+          result: last
+        });
+        return last;
+      }
+      if (attempt < maxAttempts) {
+        await sleep(delayMs);
+      }
+    }
+    const failed = last || {
+      ok: false,
+      stdout: "",
+      stderr: "seller service did not become ready",
+      command: []
+    };
+    report({
+      stepId: "wait_seller",
+      status: "failed",
+      title: "Wait for seller service",
+      message: "Seller operator API did not become ready before config write.",
+      result: failed
+    });
+    return failed;
+  }
+
+  private async publishCreatedSellerRegistryEntry(options: {
+    registry: SellerRegistryDocument;
+    request: CreateSellerRequest;
+    appName: string;
+    operatorSecret: string;
+    enabled: boolean;
+    report: UiActionProgressReporter;
+  }): Promise<UiActionResult | undefined> {
+    const { registry, request, appName, operatorSecret, enabled, report } = options;
+    if (!enabled) {
+      report({
+        stepId: "publish_registry",
+        status: "skipped",
+        title: "Publish bootstrap registry",
+        message: "Skipped because the deployment workflow did not complete successfully."
+      });
+      return undefined;
+    }
+
+    report({
+      stepId: "publish_registry",
+      status: "running",
+      title: "Publish bootstrap registry",
+      message: `Publishing ${request.sellerName} to bootstrap registry.`
+    });
+
+    let next: SellerRegistryDocument;
+    try {
+      const upstreams = await this.fetchSellerOperatorJson(appName, operatorSecret, "/operator/admin/upstreams");
+      const service = await this.fetchSellerOperatorJson(appName, operatorSecret, "/operator/admin/service");
+      next = nextRegistryDocument(registry, request, appName, upstreams, service);
+    } catch (err: any) {
+      const failed = {
+        ok: false,
+        stdout: "",
+        stderr: redactSensitive(err.message || "failed to build bootstrap registry entry"),
+        command: ["fetch", `${sellerOperatorUrl(appName)}/operator/admin/upstreams`]
+      };
+      report({
+        stepId: "publish_registry",
+        status: "failed",
+        title: "Publish bootstrap registry",
+        message: "Failed to read seller metadata for bootstrap registry.",
+        result: failed
+      });
+      return failed;
+    }
+    return this.withTempJson(next, async (filePath) => {
+      const validate = await this.runAdmin(globalArgs(this.options, ["bootstrap", "sellers", "validate", "--file", filePath]), 30000);
+      if (!validate.ok) {
+        report({
+          stepId: "publish_registry",
+          status: "failed",
+          title: "Publish bootstrap registry",
+          message: "Generated bootstrap registry entry failed validation.",
+          result: validate
+        });
+        return validate;
+      }
+      const put = await this.runAdmin(globalArgs(this.options, ["bootstrap", "sellers", "put", "--file", filePath]), 30000);
+      report({
+        stepId: "publish_registry",
+        status: put.ok ? "succeeded" : "failed",
+        title: "Publish bootstrap registry",
+        message: put.ok ? "Bootstrap registry was published with the new seller." : "Bootstrap registry publish failed.",
+        result: put
+      });
+      return put;
+    });
+  }
+
+  private async fetchSellerOperatorJson(appName: string, operatorSecret: string, pathName: string): Promise<Record<string, unknown>> {
+    const fetchJson = this.options.fetchJson || defaultFetchJson;
+    const response = await fetchJson(`${sellerOperatorUrl(appName)}${pathName}`, {
+      headers: { Authorization: `Bearer ${operatorSecret}` }
+    });
+    if (response && typeof response === "object" && !Array.isArray(response)) {
+      return response as Record<string, unknown>;
+    }
+    return {};
+  }
+}
+
+function nextRegistryDocument(
+  registry: SellerRegistryDocument,
+  request: CreateSellerRequest,
+  appName: string,
+  upstreams: Record<string, unknown>,
+  service: Record<string, unknown>
+): SellerRegistryDocument {
+  const entry = registryEntryFromCreatedSeller(request, appName, upstreams, service);
+  const sellers = registry.sellers.filter((seller) => {
+    return seller.id !== entry.id && seller.name !== entry.name && seller.app !== entry.app;
+  });
+  return {
+    ...registry,
+    version: Number(registry.version || 0) + 1,
+    updatedAt: new Date().toISOString(),
+    sellers: [...sellers, entry]
+  };
+}
+
+function registryEntryFromCreatedSeller(
+  request: CreateSellerRequest,
+  appName: string,
+  upstreams: Record<string, unknown>,
+  service: Record<string, unknown>
+): SellerRegistryEntry {
+  const models = modelIdsFrom(upstreams.models) || modelIdsFrom(service.models);
+  if (!models || models.length === 0) {
+    throw new Error("seller operator upstreams did not return models for bootstrap registry");
+  }
+  const supportedProtocols = supportedProtocolsFrom(service.supportedProtocols)
+    || supportedProtocolsFrom(upstreams.supportedProtocols)
+    || ["chat_completions"];
+  const paymentMethods = paymentMethodsFromRequest(request);
+  return {
+    id: request.sellerName,
+    name: request.sellerName,
+    app: appName,
+    url: sellerOperatorUrl(appName),
+    status: "pending",
+    region: stringValue(request.region),
+    modelsCount: models.length || undefined,
+    sampleModels: models.slice(0, 5),
+    models,
+    supportedProtocols,
+    paymentMethods,
+    recommendedFor: models.slice(0, 5)
+  };
+}
+
+function modelIdsFrom(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  return Array.from(new Set(value.map((entry) => {
+    if (typeof entry === "string") {
+      return entry;
+    }
+    if (entry && typeof entry === "object" && "id" in entry) {
+      const id = (entry as { id?: unknown }).id;
+      return typeof id === "string" && id.trim() ? id.trim() : undefined;
+    }
+    return undefined;
+  }).filter((entry): entry is string => Boolean(entry))));
+}
+
+function supportedProtocolsFrom(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const protocols = value.map((entry) => stringValue(entry)).filter((entry): entry is string => Boolean(entry));
+  return protocols.length > 0 ? Array.from(new Set(protocols)) : undefined;
+}
+
+export function runTbAdmin(args: string[], timeoutMs: number): Promise<UiActionResult> {
+  const entry = adminEntryPath();
+  const command = [process.execPath, entry, ...args];
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [entry, ...args], {
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+    }, timeoutMs);
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({
+        ok: code === 0,
+        stdout: redactSensitive(stdout),
+        stderr: redactSensitive(stderr),
+        command: redactCommand(command)
+      });
+    });
+  });
+}
+
+async function defaultFetchJson(url: string, init?: RequestInit): Promise<unknown> {
+  const response = await fetch(url, init);
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`HTTP Error ${response.status}: ${redactSensitive(text || response.statusText)}`);
+  }
+  const text = await response.text();
+  return text ? JSON.parse(text) : {};
+}
+
+function adminEntryPath(): string {
+  const current = process.argv[1] || "";
+  if (current.endsWith("tb-admin.js")) {
+    return current;
+  }
+  return path.resolve(process.cwd(), "packages/admin-cli/bin/tb-admin.js");
+}
+
+function globalArgs(options: UiActionsOptions, args: string[]): string[] {
+  const output: string[] = [];
+  if (options.configPath) {
+    output.push("--config", options.configPath);
+  }
+  if (options.profile) {
+    output.push("--profile", options.profile);
+  }
+  if (options.url) {
+    output.push("--url", options.url);
+  }
+  if (options.token) {
+    output.push("--token", options.token);
+  }
+  output.push(...args);
+  return output;
+}
+
+function profileArgs(options: UiActionsOptions, profileName: string, args: string[]): string[] {
+  return globalArgs({ ...options, profile: profileName, url: undefined, token: undefined }, args);
+}
+
+function mergeSellerConfigPatch(config: Record<string, unknown>, patch: ConfigPatch): Record<string, unknown> {
+  const next = { ...config };
+  copyIfPresent(next, patch, "upstreamUrl");
+  copyIfPresent(next, patch, "upstreamApiKey");
+  applyBalanceProbePatch(next, patch);
+  copyIfPresent(next, patch, "upstreamBalanceUrl");
+  copyIfPresent(next, patch, "upstreamUserId");
+  copyIfPresent(next, patch, "upstreamRechargeUrl");
+  copyIfPresent(next, patch, "markupRatio");
+  copyIfPresent(next, patch, "discountRatio");
+  copyIfPresent(next, patch, "maxConnections");
+  copyIfPresent(next, patch, "maxQueueDepth");
+  if (Array.isArray(patch.models)) {
+    next.models = patch.models;
+  }
+  if (patch.modelAliases && typeof patch.modelAliases === "object" && !Array.isArray(patch.modelAliases)) {
+    next.modelAliases = patch.modelAliases;
+  }
+  return next;
+}
+
+function copyIfPresent(target: Record<string, unknown>, source: ConfigPatch, key: string): void {
+  if (source[key] !== undefined) {
+    target[key] = source[key];
+  }
+}
+
+function validateCreateSellerRequest(request: CreateSellerRequest): void {
+  requireString(request.sellerName, "sellerName");
+  requireString(request.region, "region");
+  requireString(request.image, "image");
+  requireString(request.upstreamWebsite, "upstreamWebsite");
+  requireString(request.upstreamUrl, "upstreamUrl");
+  requireString(request.upstreamApiKey, "upstreamApiKey");
+  if (stringValue(request.upstreamBalanceProbeTemplate) !== "none") {
+    requireString(balanceProbeUrl(request), "upstreamBalanceProbeUrl");
+  }
+  requirePositiveInteger(request.maxConnections, "maxConnections");
+  requirePositiveInteger(request.maxQueueDepth, "maxQueueDepth");
+  requireFiniteNumber(request.markupRatio, "markupRatio");
+  requireFiniteNumber(request.discountRatio, "discountRatio");
+  const paymentMethods = paymentMethodsFromRequest(request);
+  const invalidPaymentMethod = paymentMethods.find((method) => !["clawtip", "mock"].includes(method));
+  if (invalidPaymentMethod) {
+    throw new Error("paymentMethods must contain only clawtip or mock");
+  }
+  if (paymentMethods.includes("clawtip")) {
+    requireString(request.clawtipPayTo, "clawtipPayTo");
+    requireString(request.clawtipSm4KeyBase64, "clawtipSm4KeyBase64");
+  }
+}
+
+function normalizeCreateSellerRequest(request: CreateSellerRequest): CreateSellerRequest {
+  const upstreamUrl = stripTrailingV1(request.upstreamUrl);
+  const app = stringValue(request.app) || request.sellerName;
+  const normalized = {
+    ...request,
+    app,
+    image: stringValue(request.image) || "registry.fly.io/tb-seller:latest",
+    flyConfig: stringValue(request.flyConfig) || "deploy/fly.io/fly.tb-seller.toml",
+    upstreamUrl
+  };
+  if (paymentMethodsFromRequest(normalized).includes("clawtip")) {
+    normalized.clawtipSkillSlug = stringValue(normalized.clawtipSkillSlug) || app;
+    normalized.clawtipSkillId = stringValue(normalized.clawtipSkillId) || `si-${app}`;
+    normalized.clawtipDescription = stringValue(normalized.clawtipDescription) || `TokenBuddy Seller ${request.sellerName}`;
+    normalized.clawtipResourceUrl = stringValue(normalized.clawtipResourceUrl) || sellerOperatorUrl(app);
+    normalized.clawtipActivationFeeFen = Number(normalized.clawtipActivationFeeFen || 1);
+    normalized.clawtipMicrosPerFen = Number(normalized.clawtipMicrosPerFen || 10000);
+  }
+  return normalized;
+}
+
+function initialSellerConfig(request: CreateSellerRequest, masked: boolean): Record<string, unknown> {
+  const upstreamBalanceProbe = balanceProbeConfigFromRequest(request);
+  const upstreamBalanceUrl = balanceProbeUrl(request);
+  const upstreamUserId = balanceProbeUserId(request);
+  const upstreamRechargeUrl = balanceProbeRechargeUrl(request);
+  const paymentConfig = paymentConfigFromRequest(request, masked);
+  return {
+    upstreamUrl: request.upstreamUrl,
+    upstreamApiKey: masked ? "********" : request.upstreamApiKey,
+    upstreamWebsite: request.upstreamWebsite,
+    upstreamBalanceUrl,
+    upstreamUserId,
+    upstreamRechargeUrl,
+    upstreamBalanceProbe,
+    maxConnections: request.maxConnections,
+    maxQueueDepth: request.maxQueueDepth,
+    markupRatio: request.markupRatio,
+    discountRatio: request.discountRatio,
+    operatorSecret: masked ? "********" : stringValue(request.operatorSecret),
+    ...paymentConfig
+  };
+}
+
+function paymentConfigFromRequest(request: CreateSellerRequest, masked: boolean): Record<string, unknown> {
+  const paymentMethods = paymentMethodsFromRequest(request);
+  const config: Record<string, unknown> = {
+    allowMock: paymentMethods.includes("mock")
+  };
+  if (!paymentMethods.includes("clawtip")) {
+    return config;
+  }
+  return {
+    ...config,
+    clawtip: {
+      payTo: stringValue(request.clawtipPayTo),
+      sm4KeyBase64: masked ? "********" : stringValue(request.clawtipSm4KeyBase64),
+      skillSlug: stringValue(request.clawtipSkillSlug),
+      skillId: stringValue(request.clawtipSkillId),
+      description: stringValue(request.clawtipDescription),
+      resourceUrl: stringValue(request.clawtipResourceUrl),
+      activationFeeFen: Number(request.clawtipActivationFeeFen),
+      microsPerFen: Number(request.clawtipMicrosPerFen)
+    }
+  };
+}
+
+function paymentMethodsFromRequest(request: CreateSellerRequest): string[] {
+  const values = request.paymentMethods !== undefined
+    ? arrayStringValues(request.paymentMethods)
+    : legacyPaymentMethodsFromRequest(request);
+  return Array.from(new Set(values));
+}
+
+function legacyPaymentMethodsFromRequest(request: CreateSellerRequest): string[] {
+  const paymentMethod = stringValue(request.paymentMethod);
+  if (paymentMethod === "none") {
+    return [];
+  }
+  return [paymentMethod || "clawtip"];
+}
+
+function arrayStringValues(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.map((entry) => stringValue(entry)).filter((entry): entry is string => Boolean(entry));
+  }
+  const single = stringValue(value);
+  return single ? single.split(",").map((entry) => entry.trim()).filter(Boolean) : [];
+}
+
+function applyBalanceProbePatch(target: Record<string, unknown>, patch: ConfigPatch): void {
+  const template = stringValue(patch.upstreamBalanceProbeTemplate);
+  const url = stringValue(patch.upstreamBalanceProbeUrl) || stringValue(patch.upstreamBalanceUrl);
+  const userId = stringValue(patch.upstreamBalanceProbeUserId) || stringValue(patch.upstreamUserId);
+  const rechargeUrl = stringValue(patch.upstreamBalanceProbeRechargeUrl) || stringValue(patch.upstreamRechargeUrl);
+  if (template === undefined && url === undefined && userId === undefined && rechargeUrl === undefined) {
+    return;
+  }
+  const current = objectValue(target.upstreamBalanceProbe) || {};
+  target.upstreamBalanceProbe = {
+    ...current,
+    ...(template !== undefined ? { template } : {}),
+    ...(url !== undefined ? { url } : {}),
+    ...(userId !== undefined ? { userId } : {}),
+    ...(rechargeUrl !== undefined ? { rechargeUrl } : {})
+  };
+  if (url !== undefined) {
+    target.upstreamBalanceUrl = url;
+  }
+  if (userId !== undefined) {
+    target.upstreamUserId = userId;
+  }
+  if (rechargeUrl !== undefined) {
+    target.upstreamRechargeUrl = rechargeUrl;
+  }
+}
+
+function balanceProbeConfigFromRequest(request: CreateSellerRequest): Record<string, unknown> {
+  return {
+    template: stringValue(request.upstreamBalanceProbeTemplate) || "auto",
+    url: balanceProbeUrl(request),
+    userId: balanceProbeUserId(request),
+    rechargeUrl: balanceProbeRechargeUrl(request)
+  };
+}
+
+function balanceProbeUrl(request: CreateSellerRequest): string | undefined {
+  const explicit = stringValue(request.upstreamBalanceProbeUrl) || stringValue(request.upstreamBalanceUrl);
+  if (explicit) {
+    return explicit;
+  }
+  const template = stringValue(request.upstreamBalanceProbeTemplate) || "auto";
+  const upstreamUrl = stringValue(request.upstreamUrl);
+  const host = hostName(upstreamUrl);
+  if (template === "none") {
+    return undefined;
+  }
+  if (template === "openrouter") {
+    return "https://openrouter.ai/api/v1/credits";
+  }
+  if (template === "deepseek") {
+    return "https://api.deepseek.com/user/balance";
+  }
+  if (template === "stepfun") {
+    return "https://api.stepfun.com/v1/accounts";
+  }
+  if (template === "novita") {
+    return "https://api.novita.ai/v3/user/balance";
+  }
+  if (template === "siliconflow") {
+    return host.endsWith(".com") ? "https://api.siliconflow.com/v1/user/info" : "https://api.siliconflow.cn/v1/user/info";
+  }
+  if (template === "usage_generic") {
+    return upstreamUrl ? usageUrl(upstreamUrl) : undefined;
+  }
+  if (template === "auto") {
+    if (host === "api.deepseek.com") {
+      return "https://api.deepseek.com/user/balance";
+    }
+    if (host === "api.stepfun.ai" || host === "api.stepfun.com") {
+      return "https://api.stepfun.com/v1/accounts";
+    }
+    if (host === "api.siliconflow.cn") {
+      return "https://api.siliconflow.cn/v1/user/info";
+    }
+    if (host === "api.siliconflow.com") {
+      return "https://api.siliconflow.com/v1/user/info";
+    }
+    if (host === "openrouter.ai") {
+      return "https://openrouter.ai/api/v1/credits";
+    }
+    if (host === "api.novita.ai") {
+      return "https://api.novita.ai/v3/user/balance";
+    }
+    return upstreamUrl ? usageUrl(upstreamUrl) : undefined;
+  }
+  return undefined;
+}
+
+function balanceProbeUserId(request: CreateSellerRequest): string | undefined {
+  return stringValue(request.upstreamBalanceProbeUserId) || stringValue(request.upstreamUserId);
+}
+
+function balanceProbeRechargeUrl(request: CreateSellerRequest): string | undefined {
+  return stringValue(request.upstreamBalanceProbeRechargeUrl) || stringValue(request.upstreamRechargeUrl);
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function objectValue(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function stripTrailingV1(value: string): string {
+  return String(value || "").trim().replace(/\/v1\/?$/i, "");
+}
+
+function usageUrl(value: string): string {
+  const base = String(value || "").trim().replace(/\/+$/, "");
+  return /\/v1$/i.test(base) ? `${base}/usage` : `${base}/v1/usage`;
+}
+
+function hostName(value: unknown): string {
+  try {
+    return new URL(String(value || "")).hostname.toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
+function sellerOperatorUrl(appName: string): string {
+  return `https://${appName}.fly.dev`;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function requireString(value: unknown, field: string): void {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${field} is required`);
+  }
+}
+
+function requirePositiveInteger(value: unknown, field: string): void {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new Error(`${field} must be >= 1`);
+  }
+}
+
+function requireFiniteNumber(value: unknown, field: string): void {
+  if (!Number.isFinite(Number(value))) {
+    throw new Error(`${field} must be a number`);
+  }
+}
+
+function redactCommand(command: string[]): string[] {
+  return command.map((part, index) => {
+    const prev = command[index - 1];
+    if (prev === "--operator-secret" || prev === "--token" || prev === "--api-key") {
+      return "********";
+    }
+    return redactSensitive(part);
+  });
+}
+
+function redactSensitive(value: string): string {
+  return value.replace(/(sk-[A-Za-z0-9_-]+)/g, "********")
+    .replace(/(operatorSecret|upstreamApiKey|token|apiKey|sm4KeyBase64|clawtipSm4KeyBase64)["'=:\s]+([^"',\s]+)/gi, "$1=********");
+}