routstrd 0.4.10 → 0.4.12

package/src/daemon/wallet/trusted-mints.ts

@@ -0,0 +1,87 @@
+import { normalizeMintUrl } from "@cashu/coco-core";
+
+/**
+ * Mint used as the default for wallets that have no configured default. It is
+ * always trusted, and a wallet is never allowed to point its default at a mint
+ * it could not fetch.
+ */
+export const DEFAULT_MINT_URL = "https://mint.minibits.cash/Bitcoin";
+
+/**
+ * Mints routstrd trusts out of the box. Every entry is added as a trusted mint
+ * on startup so users can send/receive without an explicit
+ * `wallet mints add`. `DEFAULT_MINT_URL` is listed first because it seeds the
+ * default mint of a fresh wallet; extra entries never change an existing
+ * default.
+ */
+export const DEFAULT_TRUSTED_MINT_URLS: readonly string[] = [
+  DEFAULT_MINT_URL,
+  "https://mint.cubabitcoin.org",
+];
+
+export interface TrustedMintSeeder {
+  /** Mint URLs the wallet currently trusts. */
+  trustedMints: readonly string[];
+  /** Trust a mint, fetching its info and keysets from the mint itself. */
+  addMint: (mintUrl: string) => Promise<unknown>;
+}
+
+export interface SeedTrustedMintsOptions {
+  /** Mints to ensure are trusted, in order. Defaults to the shipped seeds. */
+  seeds?: readonly string[];
+  /** Called before each mint fetch with a user-facing progress message. */
+  onProgress?: (message: string) => void;
+  /** Called when a non-default seed could not be added. */
+  onError?: (message: string, error: unknown) => void;
+}
+
+// Stored and configured mint URLs come from SQLite and JSON, so a malformed
+// value must never crash startup. Normalization only strips the default port
+// and a trailing slash, so falling back to the raw string keeps comparisons
+// meaningful.
+function safeNormalizeMintUrl(mintUrl: string): string {
+  try {
+    return normalizeMintUrl(mintUrl);
+  } catch {
+    return mintUrl;
+  }
+}
+
+/**
+ * Ensure the mint seeds routstrd ships are trusted, without ever moving a
+ * wallet's default away from `defaultMintUrl`.
+ *
+ * The default mint is seeded strictly: if it cannot be fetched the error is
+ * rethrown, because persisting an unusable default is worse than failing
+ * startup. Every other seed is best-effort — sending the mint fetch failure to
+ * `onError` — so a single unreachable mint cannot keep the daemon down.
+ */
+export async function seedTrustedMints(
+  wallet: TrustedMintSeeder,
+  defaultMintUrl: string,
+  options: SeedTrustedMintsOptions = {},
+): Promise<void> {
+  const seeds = options.seeds ?? DEFAULT_TRUSTED_MINT_URLS;
+  const target = safeNormalizeMintUrl(defaultMintUrl);
+  const trusted = new Set(wallet.trustedMints.map(safeNormalizeMintUrl));
+  const attempted = new Set<string>();
+
+  for (const seed of [defaultMintUrl, ...seeds]) {
+    const mintUrl = safeNormalizeMintUrl(seed);
+    if (attempted.has(mintUrl)) continue;
+    attempted.add(mintUrl);
+    if (trusted.has(mintUrl)) continue;
+
+    const isDefault = mintUrl === target;
+    try {
+      options.onProgress?.(
+        `Adding ${isDefault ? "default" : "trusted"} mint: ${mintUrl}`,
+      );
+      await wallet.addMint(mintUrl);
+      trusted.add(mintUrl);
+    } catch (error) {
+      if (isDefault) throw error;
+      options.onError?.(`Could not add trusted mint ${mintUrl}`, error);
+    }
+  }
+}

package/src/daemon/wallet/wallet-client.ts

@@ -0,0 +1,206 @@
+import type { HistoryEntry } from "@cashu/coco-core";
+
+/**
+ * Contract shared by every wallet implementation.
+ *
+ * The wallet runs in-process (`createCocoClient` in `./coco-client`); this
+ * module only describes what the rest of routstrd is allowed to ask of it.
+ * Historically this lived in a `cocod-client` module that also shipped an
+ * HTTP/unix-socket client for the external `cocod` binary. That client was
+ * removed once the in-process wallet replaced it — see `./migration` and the
+ * `legacyCocod*` path helpers in `./paths` for the migration-only code that
+ * still knows about external cocod installs.
+ */
+
+export type WalletRuntimeState =
+  | "UNINITIALIZED"
+  | "LOCKED"
+  | "UNLOCKED"
+  | "RECOVERING"
+  | "ERROR";
+
+/** Live progress for background wallet recovery started at daemon startup. */
+export interface WalletRecoveryProgress {
+  state: "RECOVERING" | "UNLOCKED" | "ERROR";
+  /** Current recovery phase, e.g. "Mint recovery" or "done". */
+  phase: string;
+  pendingSends: number;
+  inflightProofs: number;
+  pendingMints: number;
+  /** Expired unpaid mint quotes failed locally without a mint round-trip. */
+  failedMintQuotes: number;
+  error?: string;
+}
+
+/** NPC (npubx.cash) Lightning address details for this wallet. */
+export interface NpcAddress {
+  /** Full Lightning address, e.g. "alice@npubx.cash" (npub fallback when no username is set). */
+  address: string;
+  /** NPC username, when one has been claimed. */
+  name?: string;
+  /** Nostr hex pubkey of the NPC account (only available from the in-process wallet). */
+  pubkey?: string;
+}
+
+/** Result of an NPC username claim attempt. */
+export interface NpcUsernameResult {
+  success: boolean;
+  /** Present when NPC requires payment to claim the username. */
+  paymentRequest?: {
+    amount?: number;
+    mints?: string[];
+    [key: string]: unknown;
+  };
+}
+
+/** Options for the wallet cleanup command. */
+export interface WalletCleanupOptions {
+  /** Only clean up operations for this mint URL. */
+  mintUrl?: string;
+  /** Minimum operation age in milliseconds (defaults to 7 days / 1 week). */
+  minAgeMs?: number;
+  /** Report what would be cleaned without applying changes. */
+  dryRun?: boolean;
+  /**
+   * Fail expired mint quotes without confirming UNPAID with the mint. Only for
+   * operators who accept the risk of stranding a quote that was paid before
+   * its invoice expired; recovery is the safe default.
+   */
+  force?: boolean;
+}
+
+/** Summary of a wallet cleanup run. */
+export interface WalletCleanupResult {
+  dryRun: boolean;
+  /** Expired quotes selected for checking; dry runs do not contact the mint. */
+  mintQuoteCandidates: number;
+  /** Number actually marked failed (always zero in a dry run). */
+  failedMintQuotes: number;
+  /** Expired quotes kept pending because they are paid/issued or unverified. */
+  leftForRecovery: number;
+  /** Number of stale pending send operations reclaimed. */
+  reclaimedSends: number;
+  /** Number of stale prepared melt operations cancelled. */
+  cancelledMelts: number;
+  /** Number of in-flight operations that were left untouched. */
+  skipped: number;
+  errors: Array<{ operationId: string; error: string }>;
+}
+
+export class WalletHttpError extends Error {
+  status: number;
+
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "WalletHttpError";
+    this.status = status;
+  }
+}
+
+/** Progress of a Lightning top-up created with `receiveBolt11`. */
+export interface MintQuoteStatus {
+  operationId: string;
+  state: "pending" | "executing" | "finalized" | "failed";
+  /** Last quote state reported by the mint (UNPAID, PAID, ISSUED). */
+  mintState?: string;
+  amount: number;
+  mintUrl: string;
+  error?: string;
+}
+
+/** Options for explicit PAID mint-quote recovery. */
+export interface WalletMintQuoteRecoveryOptions {
+  /** Target only these operation ids (may include failed operations). */
+  operationIds?: string[];
+  /** Re-open failed operations instead of skipping them. */
+  includeFailed?: boolean;
+  /** Per-quote mint timeout in milliseconds. */
+  timeoutMs?: number;
+}
+
+/** Summary of a PAID mint-quote recovery run. */
+export interface WalletMintQuoteRecoveryResult {
+  /** Operations whose quote state was checked with the mint. */
+  checked: number;
+  /** Operations whose paid sats were minted or restored. */
+  recovered: number;
+  /** Quotes the mint still reports UNPAID; left pending. */
+  waiting: number;
+  /** Quotes the mint can no longer issue. */
+  terminal: number;
+  /** Failed operations moved back to pending before checking. */
+  reopened: number;
+  /** Operations left to a later run (mint unreachable, budget spent, non-terminal). */
+  retryable: number;
+  /** Operations skipped because an earlier recovery of them is still running. */
+  busy: number;
+  errors: Array<{ operationId: string; error: string }>;
+}
+
+/** Summary of a stuck-operation (send/melt/mint) recovery run. */
+export interface WalletStuckOperationRecoveryResult {
+  /** Timed-out waits; the underlying operation remains tracked. */
+  timedOut: number;
+  /** Operations for which recovery was attempted (not necessarily completed). */
+  attempted: number;
+  /** Locked operations or unfinished work from another pass; retry later. */
+  busy: number;
+  /** Operations skipped for unreachable mints, shutdown, or pass budget exhaustion. */
+  skipped: number;
+  /** Operations at reachable mints whose recovery still failed. */
+  failed: number;
+  /** Unreachable mint URL -> number of operations skipped there. */
+  skippedMints: Record<string, number>;
+}
+
+export interface WalletClient {
+  ping(): Promise<boolean>;
+  getStatus(): Promise<WalletRuntimeState>;
+  unlock(passphrase: string): Promise<string>;
+  getBalances(): Promise<Record<string, number>>;
+  receiveCashu(token: string): Promise<string>;
+  receiveBolt11(
+    amount: number,
+    mintUrl?: string,
+  ): Promise<{ invoice: string; operationId?: string }>;
+  /** Progress of a top-up, when the wallet tracks mint operations. */
+  getMintQuote?(operationId: string): Promise<MintQuoteStatus | null>;
+  sendCashu(amount: number, mintUrl?: string): Promise<string>;
+  sendBolt11(invoice: string, mintUrl?: string): Promise<string>;
+  listMints(): Promise<string[]>;
+  addMint(url: string): Promise<string>;
+  getMintInfo(url: string): Promise<unknown>;
+  getDefaultMint(): Promise<string | null>;
+  setDefaultMint(url: string): Promise<string>;
+  /** Release resources held by in-process wallet implementations. */
+  dispose?(): Promise<void>;
+  getHistory(offset?: number, limit?: number): Promise<HistoryEntry[]>;
+  /** Look up a single transaction by its history entry ID. */
+  getHistoryEntryById(id: string): Promise<HistoryEntry | null>;
+  /** NPC (npubx.cash) Lightning address for this wallet. */
+  getNpcAddress(): Promise<NpcAddress>;
+  /** Claim an NPC username; pass confirm=true to pay the claim fee from the wallet. */
+  setNpcUsername(username: string, confirm?: boolean): Promise<NpcUsernameResult>;
+  /** Manually trigger an NPC quote sync into the wallet. */
+  syncNpc(): Promise<void>;
+  /** Clear stuck pending/in-flight wallet operations that are safe to resolve. */
+  cleanupStuckOperations?(
+    options?: WalletCleanupOptions,
+  ): Promise<WalletCleanupResult>;
+  /**
+   * Re-issue PAID mint quotes whose sats were never claimed, optionally
+   * targeting specific operations (including ones coco already failed).
+   */
+  recoverMintQuotes?(
+    options?: WalletMintQuoteRecoveryOptions,
+    onProgress?: (message: string) => void,
+  ): Promise<WalletMintQuoteRecoveryResult>;
+  /**
+   * Recover stuck send/melt/mint operations whose mints answer a
+   * reachability probe. Operations a live execute holds are reported busy,
+   * never driven. Receive stays startup-only (receive dedup classification).
+   */
+  recoverStuckOperations?(): Promise<WalletStuckOperationRecoveryResult>;
+  /** Report background wallet recovery progress, when the wallet supports it. */
+  getRecoveryProgress?(): Promise<WalletRecoveryProgress>;
+}

package/src/integrations/pi.ts

@@ -5,17 +5,173 @@ import type { RoutstrdConfig } from "../utils/config";
 import type { IntegrationConfig, RoutstrModel } from "./registry";
 import { callDaemon, getDaemonBaseUrl } from "../utils/daemon-client";
 
-type PiModelEntry = {
+export type PiThinkingLevel =
+  | "off"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh"
+  | "max";
+
+export type ThinkingLevelMap = Partial<Record<PiThinkingLevel, string | null>>;
+
+export type PiModelEntry = {
   id: string;
+  api?: string;
   contextWindow?: number;
   name?: string;
   input?: string[];
-  // Thinking/reasoning config is user-curated and preserved across refreshes.
   reasoning?: boolean;
-  thinkingLevelMap?: Record<string, string | null>;
+  thinkingLevelMap?: ThinkingLevelMap;
   compat?: Record<string, unknown>;
 };
 
+/** pi thinking levels, in pi's documented order. */
+export const PI_THINKING_LEVELS: readonly PiThinkingLevel[] = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+];
+
+/**
+ * pi level -> the value sent to the provider. routstr-core publishes its
+ * allowlist in this same vocabulary (`none`/`minimal`/`low`/`medium`/`high`/
+ * `xhigh`/`max`), so the mapping is identity apart from `off`.
+ */
+const THINKING_LEVEL_VALUES: Record<PiThinkingLevel, string> = {
+  off: "none",
+  minimal: "minimal",
+  low: "low",
+  medium: "medium",
+  high: "high",
+  xhigh: "xhigh",
+  max: "max",
+};
+
+/**
+ * Build pi's thinking fields from the daemon's per-model `reasoning` object.
+ *
+ * Every level is written explicitly: pi treats an omitted level as "use the
+ * provider's default mapping" for standard levels (through `high`) and as
+ * "unsupported" for `xhigh`/`max`, so a partial map would silently advertise
+ * levels the model rejects. `null` hides the level in pi's UI.
+ *
+ * Returns null when the daemon publishes no effort allowlist (models whose
+ * upstream only reports `mandatory`, or that report no reasoning at all).
+ * Those are not guessable, so the caller keeps whatever the user curated.
+ */
+export function deriveThinkingFields(
+  model: RoutstrModel,
+): { reasoning: true; thinkingLevelMap: ThinkingLevelMap } | null {
+  const reasoning = model.reasoning;
+  if (!reasoning) return null;
+
+  const supported = (reasoning.supported_efforts ?? [])
+    .filter((effort): effort is string => typeof effort === "string")
+    .map((effort) => effort.trim().toLowerCase())
+    .filter(Boolean);
+  if (supported.length === 0) return null;
+
+  const allowed = new Set(supported);
+  // routstr-core strips `none` from mandatory models, so never offer `off` there.
+  if (reasoning.mandatory === true) allowed.delete("none");
+
+  const thinkingLevelMap: ThinkingLevelMap = {};
+  for (const level of PI_THINKING_LEVELS) {
+    const value = THINKING_LEVEL_VALUES[level];
+    thinkingLevelMap[level] = allowed.has(value) ? value : null;
+  }
+
+  return { reasoning: true, thinkingLevelMap };
+}
+
+const isDeepSeekModel = (id: string): boolean => id.startsWith("deepseek");
+const isGptModel = (id: string): boolean => id.startsWith("gpt-");
+/**
+ * Anthropic-served models (claude-opus-5.5, claude-sonnet-5, claude-fable-5.1,
+ * ...). routstr nodes proxy the Anthropic-native `messages` route, so pi's
+ * Anthropic transport can talk to the node's own endpoint instead of the
+ * OpenAI-shaped translation.
+ */
+const isClaudeModel = (id: string): boolean => id.startsWith("claude");
+
+/** Project one daemon model onto a pi config entry. */
+export function buildPiModelEntry(
+  model: RoutstrModel,
+  previous?: PiModelEntry,
+): PiModelEntry {
+  const entry: PiModelEntry = { id: model.id };
+
+  if (model.context_length !== undefined && model.context_length > 0) {
+    entry.contextWindow = model.context_length;
+  }
+
+  if (model.name) {
+    entry.name = model.name;
+  }
+
+  // Map the daemon's input modalities to Pi's ["text", "image"] vocabulary.
+  const mods = model.architecture?.input_modalities ?? [];
+  const input: string[] = [];
+  if (mods.includes("text")) input.push("text");
+  if (mods.includes("image")) input.push("image");
+  entry.input = input;
+
+  // Per-model transport pins. `api` is per-model while the provider `baseUrl`
+  // is shared, and the transports disagree about what a base URL means: the
+  // OpenAI SDKs append only their endpoint (`/chat/completions`, `/responses`)
+  // while Anthropic SDKs append `/v1/messages` themselves. The provider base
+  // URL is therefore the daemon ROOT (see installPiIntegration), which is the
+  // one spelling that resolves correctly for every transport:
+  //   gpt-*   -> {root}/responses        -> `responses`
+  //   claude* -> {root}/v1/messages      -> `messages`
+  //   other   -> {root}/chat/completions -> `chat/completions`
+  // Pins override a curated value: a stale `anthropic-messages` left on a
+  // non-claude model picks an endpoint the daemon is not expecting, and the
+  // user cannot see from models.json which family needs which transport.
+  if (isGptModel(model.id)) {
+    entry.api = "openai-responses";
+  } else if (isClaudeModel(model.id)) {
+    entry.api = "anthropic-messages";
+  } else if (previous?.api !== undefined) {
+    entry.api = previous.api;
+  }
+
+  const derived = deriveThinkingFields(model);
+  if (derived) {
+    entry.reasoning = derived.reasoning;
+    entry.thinkingLevelMap = derived.thinkingLevelMap;
+  } else {
+    // No allowlist to derive from: keep the user's hand-curated fields rather
+    // than guessing which levels the model accepts.
+    if (previous?.reasoning !== undefined) entry.reasoning = previous.reasoning;
+    if (previous?.thinkingLevelMap !== undefined) {
+      entry.thinkingLevelMap = previous.thinkingLevelMap;
+    }
+  }
+
+  // `compat` is never published by the daemon; it stays user-curated — except
+  // for deepseek* models, where the role spelling below is authoritative.
+  if (isDeepSeekModel(model.id)) {
+    // DeepSeek-backed models reject the `developer` role (OpenAI's newer
+    // spelling of `system`) on strict upstreams with a hard 400. Pi sends
+    // `developer` for reasoning models on unrecognized providers because its
+    // provider heuristics only see the local daemon URL and can't know
+    // DeepSeek sits behind it — force the universally-accepted `system`
+    // spelling for every deepseek* model, keeping any other user-set keys.
+    entry.compat = { ...(previous?.compat ?? {}), supportsDeveloperRole: false };
+  } else if (previous?.compat !== undefined) {
+    entry.compat = previous.compat;
+  }
+
+  return entry;
+}
+
 type PiProviderConfig = {
   baseUrl?: string;
   api?: string;
@@ -27,17 +183,36 @@ type PiConfig = {
   providers?: Record<string, PiProviderConfig>;
 };
 
+export type PiIntegrationDeps = {
+  callDaemon: typeof callDaemon;
+  getDaemonBaseUrl: typeof getDaemonBaseUrl;
+};
+
 export async function installPiIntegration(
   config: RoutstrdConfig,
   apiKey: string,
   integrationConfig: IntegrationConfig,
+  // Injectable I/O so tests don't need mock.module, whose overrides leak
+  // across test files for the rest of the run under bun's runner.
+  deps: Partial<PiIntegrationDeps> = {},
 ): Promise<void> {
   const { name, configPath } = integrationConfig;
+  const callDaemonFn = deps.callDaemon ?? callDaemon;
+  const getDaemonBaseUrlFn = deps.getDaemonBaseUrl ?? getDaemonBaseUrl;
 
   console.log("\nInstalling routstr models in pi models.json...");
   console.log(`Using API key for ${name}`);
 
-  const baseUrl = `${getDaemonBaseUrl(config)}/v1`;
+  // The daemon ROOT, deliberately without `/v1`. Every transport appends its
+  // own endpoint path, and only the Anthropic ones add a version prefix
+  // (`/v1/messages`); a base URL that already carries `/v1` therefore yields
+  // the doubled `/v1/v1/messages`, which routstr-core rejects with a 404 from
+  // every provider in the pool (it canonicalizes exactly one optional `v1/`).
+  // At the root, openai-completions -> `/chat/completions`, openai-responses
+  // -> `/responses` and anthropic-messages -> `/v1/messages` all land on an
+  // allowed route. getDaemonBaseUrl() strips any trailing slash, so no path
+  // can be double-slashed either.
+  const baseUrl = getDaemonBaseUrlFn(config);
 
   let piConfig: PiConfig = {};
 
@@ -59,7 +234,7 @@ export async function installPiIntegration(
     // Ensure directory exists
     mkdirSync(dirname(configPath), { recursive: true });
 
-    const data = await callDaemon("/models");
+    const data = await callDaemonFn("/models");
     const models = (data.output as { models: RoutstrModel[] } | undefined)?.models || [];
 
     if (models.length === 0) {
@@ -68,39 +243,19 @@ export async function installPiIntegration(
     }
 
     // Rebuild every model entry from scratch from the daemon, so the generated
-    // models.json is always a faithful projection of the daemon's state. The only
-    // exception is thinking/reasoning config (reasoning, thinkingLevelMap, compat),
-    // which the daemon does not provide and the user curates by hand — preserve it.
+    // models.json is always a faithful projection of the daemon's state.
+    // Thinking fields are derived from the model's published reasoning allowlist;
+    // when the daemon has none, the user's hand-curated values are preserved.
+    // `compat` stays user-curated, except for the deepseek* pin applied below;
+    // `api` is pinned per family (see buildPiModelEntry), since the family
+    // decides which transport — and so which endpoint — the model is served by.
     const existingModels = new Map<string, PiModelEntry>(
       (piConfig.providers["routstr"]?.models ?? []).map((m) => [m.id, m]),
     );
 
-    const providerModels: PiModelEntry[] = models.map((model) => {
-      const previous = existingModels.get(model.id);
-      const entry: PiModelEntry = { id: model.id };
-
-      if (model.context_length !== undefined && model.context_length > 0) {
-        entry.contextWindow = model.context_length;
-      }
-
-      if (model.name) {
-        entry.name = model.name;
-      }
-
-      // Map the daemon's input modalities to Pi's ["text", "image"] vocabulary.
-      const mods = model.architecture?.input_modalities ?? [];
-      const input: string[] = [];
-      if (mods.includes("text")) input.push("text");
-      if (mods.includes("image")) input.push("image");
-      entry.input = input;
-
-      // Preserve user-curated thinking fields from the previous entry.
-      if (previous?.reasoning !== undefined) entry.reasoning = previous.reasoning;
-      if (previous?.thinkingLevelMap !== undefined) entry.thinkingLevelMap = previous.thinkingLevelMap;
-      if (previous?.compat !== undefined) entry.compat = previous.compat;
-
-      return entry;
-    });
+    const providerModels: PiModelEntry[] = models.map((model) =>
+      buildPiModelEntry(model, existingModels.get(model.id)),
+    );
 
     // Rebuild provider from scratch too; only write routstrd-managed fields.
     piConfig.providers["routstr"] = {

package/src/integrations/registry.ts

@@ -14,6 +14,19 @@ export interface IntegrationConfig {
   configPath: string;
 }
 
+/**
+ * Per-model reasoning metadata as published by routstr-core (OpenRouter shape).
+ * Models with no reasoning support omit the whole object, and models whose
+ * upstream publishes no effort allowlist carry only `mandatory`.
+ */
+export type RoutstrReasoning = {
+  mandatory?: boolean | null;
+  default_enabled?: boolean | null;
+  supported_efforts?: string[] | null;
+  default_effort?: string | null;
+  supports_max_tokens?: boolean | null;
+};
+
 export type RoutstrModel = {
   id: string;
   name?: string;
@@ -27,6 +40,7 @@ export type RoutstrModel = {
     context_length?: number;
     max_completion_tokens?: number;
   };
+  reasoning?: RoutstrReasoning | null;
 };
 
 export type IntegrationFn = (