@dvmkit/dvm-cli 0.3.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/dvm.js CHANGED
@@ -8471,74 +8471,67 @@ var {
8471
8471
  Help
8472
8472
  } = import_index.default;
8473
8473
 
8474
- // src/lib/expand-capabilities.ts
8475
- var CAPABILITY_PROBE_TIMEOUT_MS = 3e3;
8476
- var CAPABILITY_PROBE_CONCURRENCY = 8;
8477
- async function expandResultsWithCapabilities(results, transport) {
8478
- const infos = results.map(() => null);
8479
- const pending4 = results.flatMap((result, index) => result.identifier === null ? [] : [index]);
8480
- const deadline = Date.now() + CAPABILITY_PROBE_TIMEOUT_MS;
8481
- let next = 0;
8482
- async function probe() {
8483
- while (next < pending4.length) {
8484
- const resultIndex = pending4[next++];
8485
- const remainingMs = deadline - Date.now();
8486
- if (remainingMs <= 0) return;
8487
- try {
8488
- infos[resultIndex] = await transport.describe(
8489
- { endpoint: results[resultIndex].endpoint },
8490
- { timeoutMs: remainingMs }
8491
- );
8492
- } catch {
8474
+ // src/lib/discovery-rows.ts
8475
+ function buildDiscoveryRows(entries) {
8476
+ return entries.flatMap((entry) => {
8477
+ if (entry.identifier === null || !entry.capabilities?.length) return [{ ...entry }];
8478
+ return entry.capabilities.map((capability) => {
8479
+ const identifier = `${entry.identifier}/${capability.name}`;
8480
+ const endpointHint = entry.display?.endpoint_hint?.replace(
8481
+ `dvm request -d ${entry.identifier}`,
8482
+ `dvm request -d ${identifier}`
8483
+ );
8484
+ const row = {
8485
+ ...entry,
8486
+ identifier,
8487
+ capability: capability.name,
8488
+ capability_description: capability.description,
8489
+ price: capability.price,
8490
+ pricing: capability.price ? { max: { ...capability.price } } : null,
8491
+ quote_required: capability.quote_required,
8492
+ speed: capability.speed,
8493
+ display: {
8494
+ ...entry.display,
8495
+ ...capability.display,
8496
+ ...endpointHint !== void 0 ? { endpoint_hint: endpointHint } : {}
8497
+ }
8498
+ };
8499
+ delete row.price_raw;
8500
+ return row;
8501
+ });
8502
+ });
8503
+ }
8504
+ function discoveryCapabilityJson(row) {
8505
+ return {
8506
+ ...row.capabilities ? {
8507
+ capabilities: row.capabilities.map((capability) => ({
8508
+ ...capability,
8509
+ description: capability.description === null ? null : asProviderText(capability.description)
8510
+ }))
8511
+ } : {},
8512
+ ...row.capability_description !== void 0 ? {
8513
+ capability_description: row.capability_description === null ? null : asProviderText(row.capability_description)
8514
+ } : {}
8515
+ };
8516
+ }
8517
+ function renderDiscoveryDisplay(row, indent) {
8518
+ for (const [label, field] of [["Price", "price"], ["Delivered", "delivered"], ["Feedback", "feedback"]]) {
8519
+ const text = row.display?.[field];
8520
+ if (text != null) info(`${indent}${label}: ${text}`);
8521
+ }
8522
+ if (row.identifier === null) {
8523
+ for (const capability of row.capabilities ?? []) {
8524
+ if (capability.display.speed != null) {
8525
+ info(`${indent}Speed: ${capability.name}: ${capability.display.speed}`);
8493
8526
  }
8494
8527
  }
8528
+ } else if (row.display?.speed != null) {
8529
+ info(`${indent}Speed: ${row.display.speed}`);
8495
8530
  }
8496
- await Promise.all(
8497
- Array.from(
8498
- { length: Math.min(CAPABILITY_PROBE_CONCURRENCY, pending4.length) },
8499
- async () => probe()
8500
- )
8501
- );
8502
- const expanded = [];
8503
- for (let i = 0; i < results.length; i++) {
8504
- const r = results[i];
8505
- const info2 = infos[i];
8506
- if (r.identifier === null) {
8507
- expanded.push({ ...r, identifier: null });
8508
- continue;
8509
- }
8510
- const capabilities = info2?.capabilities;
8511
- if (!capabilities) {
8512
- expanded.push({ ...r, identifier: r.identifier });
8513
- continue;
8514
- }
8515
- const capNames = Object.keys(capabilities);
8516
- if (capNames.length === 0) {
8517
- expanded.push({ ...r, identifier: r.identifier });
8518
- continue;
8519
- }
8520
- for (const cap2 of capNames) {
8521
- const capEntry = capabilities[cap2];
8522
- const identifier = `${r.identifier}/${cap2}`;
8523
- const capabilitySpecific = withCapabilitySpecificHint(r, identifier);
8524
- expanded.push({
8525
- ...capabilitySpecific,
8526
- capability: cap2,
8527
- identifier,
8528
- ...capEntry.description ? { capability_description: capEntry.description } : {}
8529
- });
8530
- }
8531
+ for (const [label, field] of [["Status", "status"], ["Owner", "owner"], ["Warning", "warning"], ["Credit", "credit"]]) {
8532
+ const text = row.display?.[field];
8533
+ if (text != null) info(`${indent}${label}: ${text}`);
8531
8534
  }
8532
- return expanded;
8533
- }
8534
- function withCapabilitySpecificHint(entry, identifier) {
8535
- if (!entry.display || entry.identifier === null) return entry;
8536
- const baseCommand = `dvm request -d ${entry.identifier}`;
8537
- const endpointHint = entry.display.endpoint_hint.replace(
8538
- baseCommand,
8539
- `dvm request -d ${identifier}`
8540
- );
8541
- return { ...entry, display: { ...entry.display, endpoint_hint: endpointHint } };
8542
8535
  }
8543
8536
 
8544
8537
  // src/lib/messages/store.ts
@@ -9173,9 +9166,9 @@ async function handlePaymentRequest(jobId, request2, policy, transport, provider
9173
9166
  asset: request2.x402.asset,
9174
9167
  paymentRequired: request2.x402.payment_required,
9175
9168
  // Price the USDC against the rate the cap check used, so the signed
9176
- // amount and the ledger entry can't disagree (an internal review).
9169
+ // amount and the ledger entry can't disagree.
9177
9170
  btcRate,
9178
- // an internal review: when the server stamped a per-job nonce on the
9171
+ // when the server stamped a per-job nonce on the
9179
9172
  // payment-request, sign against that exact `bytes32` so the
9180
9173
  // SDK's verify-side binding accepts the credential.
9181
9174
  ...request2.x402.nonce && { nonce: request2.x402.nonce }
@@ -9304,7 +9297,7 @@ async function tryAgentWalletMidJobPayment(args) {
9304
9297
  prepared.error.code,
9305
9298
  prepared.error.message,
9306
9299
  prepared.error.hint,
9307
- // an internal review: the mints tried and why, so a mid-job payment failure names
9300
+ // the mints tried and why, so a mid-job payment failure names
9308
9301
  // the outage rather than a bare cashu-ts string.
9309
9302
  prepared.error.attempts ? { mint_attempts: prepared.error.attempts } : void 0
9310
9303
  );
@@ -9509,9 +9502,15 @@ async function streamLoop(opts) {
9509
9502
  let cursor = opts.afterSeq;
9510
9503
  let messageAppendSession = opts.messageAppendSession;
9511
9504
  const jobToken = opts.jobToken ?? loadJob(jobId)?.jobToken;
9505
+ const deadline = opts.timeoutMs === void 0 ? void 0 : Date.now() + Math.max(0, opts.timeoutMs);
9506
+ const nextPollOptions = () => {
9507
+ if (deadline === void 0) return { jobToken };
9508
+ const timeoutMs = Math.floor(deadline - Date.now());
9509
+ return timeoutMs > 0 ? { timeoutMs, jobToken } : null;
9510
+ };
9512
9511
  let controller;
9513
9512
  let timer;
9514
- if (opts.timeoutMs) {
9513
+ if (opts.timeoutMs !== void 0 && opts.timeoutMs > 0) {
9515
9514
  controller = new AbortController();
9516
9515
  timer = setTimeout(() => {
9517
9516
  controller?.abort();
@@ -9519,6 +9518,7 @@ async function streamLoop(opts) {
9519
9518
  }
9520
9519
  try {
9521
9520
  for (; ; ) {
9521
+ if (deadline !== void 0 && Date.now() >= deadline) break;
9522
9522
  const streamFn = transport.stream?.bind(transport);
9523
9523
  let batchMessages;
9524
9524
  if (streamFn) {
@@ -9531,12 +9531,19 @@ async function streamLoop(opts) {
9531
9531
  try {
9532
9532
  result = await streamFn(jobId, cursor, provider, streamOpts);
9533
9533
  } catch (err) {
9534
- if (isAbortError(err)) break;
9534
+ if (isAbortError(err) || deadline !== void 0 && isMessagePollTimeout(err)) break;
9535
9535
  throw err;
9536
9536
  }
9537
9537
  batchMessages = result.messages;
9538
9538
  } else {
9539
- batchMessages = await transport.getMessages(jobId, cursor, provider, { jobToken });
9539
+ const pollOptions = nextPollOptions();
9540
+ if (!pollOptions) break;
9541
+ try {
9542
+ batchMessages = await transport.getMessages(jobId, cursor, provider, pollOptions);
9543
+ } catch (err) {
9544
+ if (deadline !== void 0 && isMessagePollTimeout(err)) break;
9545
+ throw err;
9546
+ }
9540
9547
  for (const msg of batchMessages) {
9541
9548
  opts.onMessage?.(msg);
9542
9549
  }
@@ -9597,7 +9604,15 @@ async function streamLoop(opts) {
9597
9604
  if (timer) clearTimeout(timer);
9598
9605
  }
9599
9606
  if (justAutoPaid) {
9600
- const recheck = await transport.getMessages(jobId, cursor, provider, { jobToken });
9607
+ const pollOptions = nextPollOptions();
9608
+ let recheck = [];
9609
+ try {
9610
+ if (pollOptions) {
9611
+ recheck = await transport.getMessages(jobId, cursor, provider, pollOptions);
9612
+ }
9613
+ } catch (err) {
9614
+ if (deadline === void 0 || !isMessagePollTimeout(err)) throw err;
9615
+ }
9601
9616
  if (recheck.length > 0) {
9602
9617
  for (const msg of recheck) opts.onMessage?.(msg);
9603
9618
  allMessages.push(...recheck);
@@ -9622,6 +9637,9 @@ async function streamLoop(opts) {
9622
9637
  }
9623
9638
  return { messages: allMessages, autoPayments, refunds, nextAction, cursor };
9624
9639
  }
9640
+ function isMessagePollTimeout(err) {
9641
+ return isAbortError(err) || err instanceof DvmError && err.code === "timeout";
9642
+ }
9625
9643
  function findLastYield(messages2) {
9626
9644
  const yieldTypes = /* @__PURE__ */ new Set(["prompt", "payment-request", "working", "complete", "cancel"]);
9627
9645
  for (let i = messages2.length - 1; i >= 0; i--) {
@@ -9954,6 +9972,21 @@ function paramsToData(params) {
9954
9972
  function jobTokenHeader(jobToken) {
9955
9973
  return jobToken ? { "X-Job-Token": jobToken } : {};
9956
9974
  }
9975
+ function messagePollUnreachable(jobId) {
9976
+ return new DvmError(
9977
+ "provider_unreachable",
9978
+ `Could not reach the provider to fetch messages for job ${jobId}.`,
9979
+ "The provider may be down or unreachable from this network. Retry once it is back."
9980
+ );
9981
+ }
9982
+ async function readMessagePollBody(read, jobId) {
9983
+ try {
9984
+ return await read();
9985
+ } catch (err) {
9986
+ if (err instanceof TypeError && !isAbortError(err)) throw messagePollUnreachable(jobId);
9987
+ throw err;
9988
+ }
9989
+ }
9957
9990
  function captureTraceId(res) {
9958
9991
  const tp = res.headers.get("traceparent");
9959
9992
  if (tp) {
@@ -10012,7 +10045,7 @@ var HttpsTransport = class {
10012
10045
  cashu: data.cashu,
10013
10046
  sdkSha: data.sdk_sha,
10014
10047
  capabilities: data.capabilities,
10015
- // an internal review: the receipt trust anchor. `receipts` is emitted only when
10048
+ // the receipt trust anchor. `receipts` is emitted only when
10016
10049
  // true, so coerce rather than pass through — a DVM sending `false`
10017
10050
  // means the same thing as omitting it.
10018
10051
  ...data.receipts === true ? { receipts: true } : {},
@@ -10326,29 +10359,42 @@ var HttpsTransport = class {
10326
10359
  );
10327
10360
  }
10328
10361
  const url = `${endpoint}/v1/job/${jobId}`;
10329
- const res = await dvmFetch(url, { headers: jobTokenHeader(options?.jobToken) });
10330
- captureTraceId(res);
10331
- if (res.status === 404) {
10332
- throw new DvmError("job_not_found", `Job ${jobId} not found.`);
10333
- }
10334
- if (!res.ok) {
10335
- const credentialErr = jobCredentialError(res.status, await res.text());
10336
- if (credentialErr) throw credentialErr;
10337
- throw new DvmError("provider_error", `Status check failed (${res.status})`);
10362
+ const signal = options?.timeoutMs && options.timeoutMs > 0 ? AbortSignal.timeout(options.timeoutMs) : void 0;
10363
+ try {
10364
+ const res = await dvmFetch(url, { headers: jobTokenHeader(options?.jobToken), signal });
10365
+ captureTraceId(res);
10366
+ if (res.status === 404) {
10367
+ throw new DvmError("job_not_found", `Job ${jobId} not found.`);
10368
+ }
10369
+ if (!res.ok) {
10370
+ const credentialErr = jobCredentialError(res.status, await res.text());
10371
+ if (credentialErr) throw credentialErr;
10372
+ throw new DvmError("provider_error", `Status check failed (${res.status})`);
10373
+ }
10374
+ const data = await res.json();
10375
+ return {
10376
+ jobId,
10377
+ status: data.status,
10378
+ summary: data.summary,
10379
+ hasArtifacts: data.has_artifacts,
10380
+ artifactCount: data.artifact_count,
10381
+ payloadIn: data.payload_in,
10382
+ message: data.message,
10383
+ cashuChange: res.headers.get("X-Cashu-Change") ?? void 0,
10384
+ ...parseSignedReceipt(data.receipt),
10385
+ ...parseFundingResponse(data)
10386
+ };
10387
+ } catch (err) {
10388
+ if (err instanceof DvmError) throw err;
10389
+ if (isAbortError(err)) {
10390
+ throw new DvmError(
10391
+ "timeout",
10392
+ "Status check timed out.",
10393
+ `The provider may still be working. Retry with 'dvm status ${jobId}'.`
10394
+ );
10395
+ }
10396
+ throw err;
10338
10397
  }
10339
- const data = await res.json();
10340
- return {
10341
- jobId,
10342
- status: data.status,
10343
- summary: data.summary,
10344
- hasArtifacts: data.has_artifacts,
10345
- artifactCount: data.artifact_count,
10346
- payloadIn: data.payload_in,
10347
- message: data.message,
10348
- cashuChange: res.headers.get("X-Cashu-Change") ?? void 0,
10349
- ...parseSignedReceipt(data.receipt),
10350
- ...parseFundingResponse(data)
10351
- };
10352
10398
  }
10353
10399
  async getMessages(jobId, after, provider, options) {
10354
10400
  const endpoint = provider?.endpoint;
@@ -10359,15 +10405,37 @@ var HttpsTransport = class {
10359
10405
  );
10360
10406
  }
10361
10407
  const url = `${endpoint}/v1/job/${jobId}/messages?after=${after}`;
10362
- const res = await dvmFetch(url, { headers: jobTokenHeader(options?.jobToken) });
10363
- if (!res.ok) {
10364
- const text = await res.text();
10365
- const credentialErr = jobCredentialError(res.status, text);
10366
- if (credentialErr) throw credentialErr;
10367
- throw providerResponseError("provider_error", `getMessages failed (${res.status}): ${text}`);
10408
+ const signal = options?.timeoutMs && options.timeoutMs > 0 ? AbortSignal.timeout(options.timeoutMs) : void 0;
10409
+ try {
10410
+ let res;
10411
+ try {
10412
+ res = await dvmFetch(url, {
10413
+ headers: jobTokenHeader(options?.jobToken),
10414
+ signal
10415
+ });
10416
+ } catch (err) {
10417
+ if (err instanceof DvmError || isAbortError(err)) throw err;
10418
+ throw messagePollUnreachable(jobId);
10419
+ }
10420
+ if (!res.ok) {
10421
+ const text = await readMessagePollBody(() => res.text(), jobId);
10422
+ const credentialErr = jobCredentialError(res.status, text);
10423
+ if (credentialErr) throw credentialErr;
10424
+ throw providerResponseError("provider_error", `getMessages failed (${res.status}): ${text}`);
10425
+ }
10426
+ const data = await readMessagePollBody(() => res.json(), jobId);
10427
+ return data.messages;
10428
+ } catch (err) {
10429
+ if (err instanceof DvmError) throw err;
10430
+ if (isAbortError(err)) {
10431
+ throw new DvmError(
10432
+ "timeout",
10433
+ "Message poll timed out.",
10434
+ `The provider may still be working. Retry with 'dvm messages ${jobId}'.`
10435
+ );
10436
+ }
10437
+ throw err;
10368
10438
  }
10369
- const data = await res.json();
10370
- return data.messages;
10371
10439
  }
10372
10440
  async sendMessage(jobId, message2, provider, options) {
10373
10441
  const endpoint = provider?.endpoint;
@@ -10463,7 +10531,7 @@ var HttpsTransport = class {
10463
10531
  }
10464
10532
  /**
10465
10533
  * Issue a no-payment POST to `/v1/job` and parse the
10466
- * `WWW-Authenticate: Payment` headers from the 402 response (an internal review).
10534
+ * `WWW-Authenticate: Payment` headers from the 402 response.
10467
10535
  * Used by the Tempo upfront-payment path to surface live mppx challenges
10468
10536
  * before signing. Returns an empty array when the DVM responds 2xx
10469
10537
  * (no payment required) or 402 without MPP headers.
@@ -10769,10 +10837,10 @@ var CREDIT_CONTEXT_FIELDS = [
10769
10837
  "balance_micro",
10770
10838
  "expiry_ms",
10771
10839
  "fundable_micro",
10772
- // an internal review: without this the fund-and-draw correction belt is left regexing
10840
+ // without this the fund-and-draw correction belt is left regexing
10773
10841
  // a `message` the protocol declares non-contractual.
10774
10842
  "expected_micro",
10775
- // an internal review: `below_rail_minimum` states the rail's floor here — the number
10843
+ // `below_rail_minimum` states the rail's floor here — the number
10776
10844
  // the caller resizes against or falls back to another rail over.
10777
10845
  "min_micro"
10778
10846
  ];
@@ -10920,7 +10988,7 @@ async function browse(opts) {
10920
10988
  timeoutMs: timeout
10921
10989
  });
10922
10990
  if (result.summary) {
10923
- await outputResults(result.summary, opts.human, result.nextAction, transport);
10991
+ outputResults(result.summary, opts.human, result.nextAction);
10924
10992
  return;
10925
10993
  }
10926
10994
  const cancelMsg = result.messages.find((m) => m.type === "cancel");
@@ -10952,7 +11020,7 @@ function cancelMessageToError(content) {
10952
11020
  const message2 = match?.[2] ?? reason;
10953
11021
  return new DvmError(code, message2);
10954
11022
  }
10955
- async function outputResults(resultJson, human, nextAction, transport) {
11023
+ function outputResults(resultJson, human, nextAction) {
10956
11024
  let output;
10957
11025
  try {
10958
11026
  output = JSON.parse(resultJson);
@@ -10964,10 +11032,7 @@ async function outputResults(resultJson, human, nextAction, transport) {
10964
11032
  }
10965
11033
  return;
10966
11034
  }
10967
- const expanded = await expandResultsWithCapabilities(
10968
- output.entries,
10969
- transport
10970
- );
11035
+ const expanded = buildDiscoveryRows(output.entries);
10971
11036
  const favs = loadFavorites();
10972
11037
  const endpointToAlias = {};
10973
11038
  for (const [alias, fav] of Object.entries(favs)) {
@@ -10983,14 +11048,13 @@ async function outputResults(resultJson, human, nextAction, transport) {
10983
11048
  ...r,
10984
11049
  name: asProviderText(r.name),
10985
11050
  description: asProviderText(r.description),
10986
- tags: r.tags.map((t) => asProviderText(t))
11051
+ tags: r.tags.map((t) => asProviderText(t)),
11052
+ ...discoveryCapabilityJson(r)
10987
11053
  };
10988
- if (r.capability_description) {
10989
- wrapped.capability_description = asProviderText(r.capability_description);
10990
- }
10991
11054
  return alias ? { ...wrapped, favorite: alias } : wrapped;
10992
11055
  });
10993
11056
  const payload = {
11057
+ ...output,
10994
11058
  entries,
10995
11059
  total: output.total,
10996
11060
  offset: output.offset,
@@ -11017,13 +11081,12 @@ function renderHuman(expanded, output, endpointToAlias) {
11017
11081
  const title = r.identifier ?? `--endpoint ${r.endpoint}`;
11018
11082
  const alias = endpointToAlias[r.endpoint];
11019
11083
  const aliasMark = alias ? ` [* @${alias}]` : "";
11020
- const price = r.display?.price ?? formatRawPrice(r);
11021
- const reliability = r.display?.reliability ? ` \u2605 ${r.display.reliability}` : "";
11022
- info(`${title}${aliasMark} ${price}${reliability}`);
11023
- const desc = r.capability_description ?? r.description;
11084
+ info(`${title}${aliasMark}`);
11085
+ const desc = r.capability === void 0 ? r.description : r.capability_description;
11024
11086
  if (desc) info(` ${desc}`);
11025
11087
  if (r.display?.endpoint_hint) info(` ${r.display.endpoint_hint}`);
11026
- if (r.display?.warning) info(` Warning: ${r.display.warning}`);
11088
+ renderDiscoveryDisplay(r, " ");
11089
+ if (r.display?.price == null) info(` Price: ${formatRawPrice(r)}`);
11027
11090
  if (i < expanded.length - 1) info("");
11028
11091
  }
11029
11092
  info("");
@@ -11465,7 +11528,7 @@ async function configReset(opts) {
11465
11528
  takenNow,
11466
11529
  () => updateConfig({
11467
11530
  reason: "config_reset",
11468
- // Deliberately no `authorize` (an internal review review). The patch below names
11531
+ // Deliberately no `authorize`. The patch below names
11469
11532
  // settings only, so today the grant would be a no-op — and the day a rail
11470
11533
  // is added to the schema without being added to `PROTECTED_CONFIG_FIELDS`
11471
11534
  // and to `CONNECTED_RAILS`, a blanket grant turns the refusal that would
@@ -12578,7 +12641,7 @@ function sanitizeLabel(label, max = 40) {
12578
12641
  function ledgerRow(e) {
12579
12642
  return {
12580
12643
  timestamp: e.timestamp,
12581
- // an internal review: a Lightning float top-up sits in the same ledger as job
12644
+ // a Lightning float top-up sits in the same ledger as job
12582
12645
  // payments (the caps cover both), so name which one this is — without it a
12583
12646
  // top-up reads as a payment to a DVM called after the mint's hostname.
12584
12647
  kind: entryKind(e),
@@ -13326,7 +13389,7 @@ async function balanceAt(transport, endpoint, signer, headroomOf, advisoryRate,
13326
13389
  ...stored ? { targetMicro: stored.targetMicro } : {},
13327
13390
  // Recorded so a credit adopted through a balance read knows the builder's
13328
13391
  // bounds — otherwise its headroom reads "bounds unknown" forever, which is
13329
- // exactly the question the block exists to answer (an internal review).
13392
+ // exactly the question the block exists to answer.
13330
13393
  ...menu ? { menu } : {},
13331
13394
  ...builderPubkey ? { builderPubkey } : {},
13332
13395
  ...creditId ? { selectPrimary: true } : {}
@@ -13726,7 +13789,7 @@ async function runCreditDrain(dvm, opts) {
13726
13789
  // channel's reclaim is held by an earlier refund that reached the chain
13727
13790
  // and never booked, and the gate holding it admits exactly one drain id —
13728
13791
  // the one that settlement is recorded under, which the refusal now names
13729
- // (an internal review). Adopting it is what makes that exemption reachable from
13792
+ // Adopting it is what makes that exemption reachable from
13730
13793
  // here: without it a caller who lost the id, or raced a sibling drain,
13731
13794
  // posts a fresh one into the same gate on every run and waits on an
13732
13795
  // operator repair that re-presenting the named id would have finished.
@@ -14015,7 +14078,7 @@ async function runCreditReceipts(dvm, opts) {
14015
14078
  collected_at: epochMsToIso(r.evidence.collectedAt),
14016
14079
  // Whether the refund this evidence is about actually arrived. Absent
14017
14080
  // means still owed — the bundle is an open IOU, and the one kind this
14018
- // record never trims away (an internal review).
14081
+ // record never trims away.
14019
14082
  ...r.evidence.settledAt !== void 0 ? { settled_at: epochMsToIso(r.evidence.settledAt) } : {},
14020
14083
  anchor_source: anchorSource(r.anchor, opts.refetch === true),
14021
14084
  receipts_verified: r.bundle.verdict,
@@ -14040,7 +14103,7 @@ function localDrainCopy(wire, requested) {
14040
14103
  case "pending":
14041
14104
  if (wire.method === "cashu") {
14042
14105
  return {
14043
- // The in-kind figure leads when the DVM published one (an internal review): a
14106
+ // The in-kind figure leads when the DVM published one: a
14044
14107
  // Bitcoin refund owes the unspent share of the *sats* deposited,
14045
14108
  // fixed at the rates each funding landed at, and leading with the
14046
14109
  // fiat figure would read as a promise of that amount when the sats
@@ -14451,7 +14514,7 @@ async function runCreditFund(dvm, opts) {
14451
14514
  ...outcome.rail ? { rail: outcome.rail } : {},
14452
14515
  // The customer-level choice, and the wire instrument under it. Present
14453
14516
  // only on the stablecoin rails, which are the only ones that have one
14454
- // (an internal review) — and present whether or not `--funding-mode` asked for it,
14517
+ // — and present whether or not `--funding-mode` asked for it,
14455
14518
  // so an agent reads what happened rather than what it requested.
14456
14519
  ...outcome.fundingMode ? { funding_mode: outcome.fundingMode } : {},
14457
14520
  ...fundingInstrumentOf(outcome) ? { funding_instrument: fundingInstrumentOf(outcome) } : {},
@@ -14468,11 +14531,11 @@ async function runCreditFund(dvm, opts) {
14468
14531
  ...outcome.transactionHash ? { transaction_hash: outcome.transactionHash } : {},
14469
14532
  // `credit_id` above is already the credit the balance landed on. This
14470
14533
  // flags that it is not the one the funding was requested against, so an
14471
- // agent tracking the original id knows to follow it (an internal review).
14534
+ // agent tracking the original id knows to follow it.
14472
14535
  ...outcome.reconciled ? { reconciled: true } : {},
14473
14536
  ...outcome.credit ? { credit: outcome.credit } : {},
14474
14537
  // Whatever the run accumulated on the way here — today the rail-pin
14475
- // conflict this verb's own reconcile clears (an internal review). It is said once
14538
+ // conflict this verb's own reconcile clears. It is said once
14476
14539
  // and there is nothing left to re-derive afterwards, so dropping it on
14477
14540
  // the success path would lose it outright for the agent audience.
14478
14541
  // `error-handler.ts` covers the throw path.
@@ -15019,7 +15082,7 @@ function creditList(opts) {
15019
15082
  return;
15020
15083
  }
15021
15084
  json({
15022
- // an internal review: this is already the caller's policy projection surface, so the
15085
+ // this is already the caller's policy projection surface, so the
15023
15086
  // consent posture is inspected here rather than through a verb of its own.
15024
15087
  posture: {
15025
15088
  effective: globalPosture.posture,
@@ -15881,12 +15944,12 @@ var FILE_SPECS = [
15881
15944
  // 0600 since it was first written: the config carries the NWC connection
15882
15945
  // string, the Tempo API key and the x402 signing key in plaintext. The
15883
15946
  // rollback copy beside it gets its own row through `describeConfigBackup`,
15884
- // which reports the generation without opening it (an internal review).
15947
+ // which reports the generation without opening it.
15885
15948
  { name: "config", path: CONFIG_FILE, json: true, secret: true, directory: false },
15886
15949
  // JSONL, and 0600 because it records which rails and identities this caller
15887
15950
  // configures and when — behavioural state, even though it holds no values.
15888
15951
  { name: "config_audit", path: CONFIG_AUDIT_FILE, json: false, secret: true, directory: false },
15889
- // The two stored copies of the configuration (an internal review). `json: false`
15952
+ // The two stored copies of the configuration. `json: false`
15890
15953
  // because a copy deliberately retains bytes too corrupt to parse — that is
15891
15954
  // the case worth keeping, not a fault to report. `dvm doctor` carries their
15892
15955
  // recovery semantics in its own `config_rollback` / `config_pinned_snapshot`
@@ -15926,7 +15989,7 @@ var FILE_SPECS = [
15926
15989
  directory: false
15927
15990
  },
15928
15991
  { name: "budget", path: BUDGET_FILE, json: true, secret: false, directory: false },
15929
- // 0600 since an internal review: `drainEvidence` holds DVM-signed receipts for refunds
15992
+ // 0600 since `drainEvidence` holds DVM-signed receipts for refunds
15930
15993
  // still owed, which is money-recovery material and not world-readable state.
15931
15994
  // A store written by an older dvm keeps its old mode until the next write
15932
15995
  // replaces it — doctor warns, and the write repairs it.
@@ -15939,7 +16002,7 @@ var FILE_SPECS = [
15939
16002
  directory: false
15940
16003
  },
15941
16004
  { name: "favorites", path: FAVORITES_FILE, json: true, secret: false, directory: false },
15942
- // an internal review nudge cooldowns + intro stamp. Written 0600: the caller's own
16005
+ // Feedback nudge cooldowns + intro stamp. Written 0600: the caller's own
15943
16006
  // behavioural record — which DVMs it talks to and when — not shared state.
15944
16007
  {
15945
16008
  name: "feedback_nudges",
@@ -16289,6 +16352,13 @@ function invalidChainResponse() {
16289
16352
  var BTC_RATE_STALE_MS = 24 * 60 * 60 * 1e3;
16290
16353
  var DEFAULT_PROBE_TIMEOUT_MS = 3e3;
16291
16354
  async function doctor(opts) {
16355
+ if (opts.target && opts.network === false) {
16356
+ throw new DvmError(
16357
+ "invalid_argument",
16358
+ "A doctor target cannot be combined with --no-network.",
16359
+ "Remove --no-network to inspect the target, or omit the target to run local-only checks."
16360
+ );
16361
+ }
16292
16362
  const checks = [];
16293
16363
  checks.push(buildConfigDirModeCheck(repairConfigDirMode()));
16294
16364
  checks.push(...buildFileChecks());
@@ -16604,7 +16674,7 @@ function hintForCorruptFile(name) {
16604
16674
  return "Delete ~/.dvm/btc-rate.json; it will be re-fetched on the next command.";
16605
16675
  // Deliberately not "delete it": the file may hold DVM-signed drain
16606
16676
  // receipts for a refund still owed. The next dvm command moves it aside
16607
- // under a credits.json.corrupt-* name and reports where (an internal review).
16677
+ // under a credits.json.corrupt-* name and reports where.
16608
16678
  case "credits":
16609
16679
  return "Do not delete ~/.dvm/credits.json \u2014 it may hold signed proof of a refund you are owed. The next dvm command sets it aside as ~/.dvm/credits.json.corrupt-* and names the path; balances re-read from each DVM with 'dvm credit balance <dvm>'.";
16610
16680
  default:
@@ -16625,7 +16695,7 @@ function buildConfigChecks() {
16625
16695
  display: "Could not load config.json.",
16626
16696
  // Never "reinitialise": the bytes that will not parse still hold the
16627
16697
  // only copy of the NWC string and both private keys, and a fresh config
16628
- // written over them is the an internal review incident by another route. Restore,
16698
+ // written over them is the incident by another route. Restore,
16629
16699
  // or move the file aside deliberately.
16630
16700
  hint: `Restore a stored copy with 'dvm config rollback' ('--slot pinned' for the snapshot a reset took). Failing that, move ${CONFIG_FILE} aside yourself and run 'dvm init' \u2014 a wallet reconnect and a key re-import are the cost, and the existing wallet and identities files are untouched either way.`,
16631
16701
  details: { error: err instanceof Error ? err.message : String(err) }
@@ -17151,7 +17221,7 @@ async function buildTempoChannelOwnerChecks() {
17151
17221
  display: connected ? `${foreign.length} recorded Tempo channel${plural} ${foreign.length === 1 ? "was" : "were"} opened by a different Tempo key, so the connected wallet cannot close ${foreign.length === 1 ? "it" : "them"} or reach the collateral ${foreign.length === 1 ? "it holds" : "they hold"}.` : `${foreign.length} Tempo channel${plural} ${foreign.length === 1 ? "is" : "are"} still recorded here, but no Tempo key is connected, so nothing on this machine can close ${foreign.length === 1 ? "it" : "them"}.`,
17152
17222
  // `replacingConnectedKey` tracks `connected` because it is the same
17153
17223
  // fact: with a key configured the import is a replacement and refuses
17154
- // without `--force`, and with none it needs no flag (an internal review).
17224
+ // without `--force`, and with none it needs no flag.
17155
17225
  hint: connected ? `Run 'dvm wallet balance' to see what the escrow says each one holds. Reconnecting the exact key that opened one (${tempoKeyImportRoutes({ replacingConnectedKey: true })}) is what recovers its collateral; 'dvm wallet tempo-exit <dvm> --credit-id <id> --abandon' retires the record instead, discarding this machine's only descriptor for it. Neither the record nor this warning blocks disconnecting or replacing the Tempo key.` : `Run 'dvm wallet balance' to see what the escrow says each one holds. Connecting the key that opened one (${tempoKeyImportRoutes({ replacingConnectedKey: false })}) is what recovers its collateral \u2014 while none is connected there is nothing to compare these records against, so the exit will not retire one the escrow still holds collateral for. Neither the record nor this warning blocks connecting a key.`,
17156
17226
  details: { channels: records.length, foreign: foreign.length, entries: foreign }
17157
17227
  }
@@ -17511,7 +17581,7 @@ function railToCheck(rail) {
17511
17581
  group: "wallets",
17512
17582
  // A rail with no money is not a broken install: warn, never fail.
17513
17583
  status: "warn",
17514
- // an internal review: the endpoint sits with the amount, because "read the wrong
17584
+ // the endpoint sits with the amount, because "read the wrong
17515
17585
  // endpoint" is one of the ways a funded wallet reports $0.00 — and
17516
17586
  // `--human` doctor prints `display` and `hint`, nothing else.
17517
17587
  display: `${railLabelAtSentenceStart(probeRailLabel(rail.rail))} rail${tempoWhere} is reachable but holds no ${wrongAsset.assetLabel} ($0.00${rpcEndpointSuffix(rail)}), so it cannot pay for anything.`,
@@ -18000,9 +18070,9 @@ import { existsSync as existsSync5, readFileSync as readFileSync6, renameSync as
18000
18070
 
18001
18071
  // src/lib/feedback-notice.ts
18002
18072
  function buildFeedbackNudge(args) {
18003
- const command = feedbackCommand(args.jobId);
18073
+ const command = feedbackCommand(args.jobId, args.code === "feedback_job_failed" ? "down" : void 0);
18004
18074
  const display = args.code === "feedback_job_failed" ? `Job ${args.jobId} at ${args.dvmId} failed. A short note through '${command}' reaches the builder.` : `This was the first completed job with ${args.dvmId}. A first impression through '${command}' reaches the builder.`;
18005
- const coach = args.code === "feedback_job_failed" ? "Worth sending unless the failure was this request's own bad input \u2014 then skip it. Say what was expected and what came back instead, with concrete detail: the input shape, the error text, versions where they matter." : "Worth a line on anything that fell short of what was asked \u2014 expected versus got, with concrete detail, versions where they matter.";
18075
+ const coach = args.code === "feedback_job_failed" ? "Worth sending unless the failure was this request's own bad input \u2014 then skip it. Say what was expected and what came back instead, with concrete detail: the input shape, the error text, versions where they matter." : "After evaluating the output, add '--verdict up' if it met what was asked, or '--verdict down' if it fell short. If you cannot judge that, append a concrete note to the command for free-text feedback. Say what was expected versus what came back, with versions where they matter.";
18006
18076
  const approval = args.approval === "ask" ? "Describe the substance of that feedback to your user at a high level and get a yes before running the command." : "The feedback posture is 'auto', so sending needs no approval first.";
18007
18077
  return {
18008
18078
  code: args.code,
@@ -18017,7 +18087,7 @@ function buildFeedbackNudge(args) {
18017
18087
  };
18018
18088
  }
18019
18089
  function buildFeedbackHint(jobId) {
18020
- return `Fell short? '${feedbackCommand(jobId)}' reaches the builder.`;
18090
+ return `Fell short? '${feedbackCommand(jobId, "down")}' reaches the builder.`;
18021
18091
  }
18022
18092
  function noteFeedbackNudge(nudge, human) {
18023
18093
  info(`${nudge.display} ${nudge.hint}`);
@@ -18031,8 +18101,8 @@ function takeFeedbackNoticeFields() {
18031
18101
  pending2 = {};
18032
18102
  return taken;
18033
18103
  }
18034
- function feedbackCommand(jobId) {
18035
- return `dvm feedback --job ${shellQuoteArg(jobId)}`;
18104
+ function feedbackCommand(jobId, verdict) {
18105
+ return `dvm feedback --job ${shellQuoteArg(jobId)}${verdict ? ` --verdict ${verdict}` : ""}`;
18036
18106
  }
18037
18107
  function buildFeedbackIntro(approval) {
18038
18108
  const options = "Feedback nudges like this one are on by default. 'dvm feedback --posture ask' keeps the ask-first default, '--posture auto' sends without asking, and '--posture off' turns nudges off.";
@@ -18164,7 +18234,7 @@ function getPlatformUrl() {
18164
18234
  // src/commands/feedback.ts
18165
18235
  async function feedback(bodyParts, opts) {
18166
18236
  if (opts.posture !== void 0) {
18167
- if (opts.dvm != null || opts.job != null || opts.body != null || opts.as != null || bodyParts.length > 0) {
18237
+ if (opts.dvm != null || opts.job != null || opts.body != null || opts.as != null || opts.verdict != null || bodyParts.length > 0) {
18168
18238
  throw new DvmError(
18169
18239
  "bad_arguments",
18170
18240
  "`--posture` cannot be combined with submitting feedback.",
@@ -18181,6 +18251,22 @@ async function feedback(bodyParts, opts) {
18181
18251
  "Pick one: target a DVM directly with `--dvm <dvm-id>`, or a specific job with `--job <jobId>`."
18182
18252
  );
18183
18253
  }
18254
+ if (opts.verdict !== void 0) {
18255
+ if (opts.job == null) {
18256
+ throw new DvmError(
18257
+ "verdict_requires_job",
18258
+ "`--verdict` requires `--job`.",
18259
+ "Run 'dvm feedback --job <job-id> --verdict up|down [note]'."
18260
+ );
18261
+ }
18262
+ if (opts.verdict !== "up" && opts.verdict !== "down") {
18263
+ throw new DvmError(
18264
+ "invalid_argument",
18265
+ `Unknown feedback verdict '${opts.verdict}'.`,
18266
+ "Pass '--verdict up' or '--verdict down'."
18267
+ );
18268
+ }
18269
+ }
18184
18270
  if (opts.body != null && bodyParts.length > 0) {
18185
18271
  throw new DvmError(
18186
18272
  "bad_arguments",
@@ -18193,7 +18279,7 @@ async function feedback(bodyParts, opts) {
18193
18279
  body = await resolveBodyFlag(opts.body);
18194
18280
  } else {
18195
18281
  body = bodyParts.join(" ").trim();
18196
- if (body.length === 0) {
18282
+ if (body.length === 0 && opts.verdict === void 0) {
18197
18283
  throw new DvmError(
18198
18284
  "bad_arguments",
18199
18285
  "Feedback body is required.",
@@ -18201,7 +18287,8 @@ async function feedback(bodyParts, opts) {
18201
18287
  );
18202
18288
  }
18203
18289
  }
18204
- const signer = resolveSigningIdentity({ as: opts.as, config: loadConfig() });
18290
+ let receipt;
18291
+ let jobPubkey;
18205
18292
  let dvmId;
18206
18293
  let feedbackClaim;
18207
18294
  let feedbackEndpointHost;
@@ -18218,7 +18305,11 @@ async function feedback(bodyParts, opts) {
18218
18305
  "Submit it first with `dvm request` (or pass `--dvm <dvm-id>` for DVM-level feedback)."
18219
18306
  );
18220
18307
  }
18221
- if (!stored.feedbackClaim) {
18308
+ if (opts.verdict !== void 0) {
18309
+ receipt = loadReceipt(opts.job)?.receipt ?? stored.receipt;
18310
+ jobPubkey = receipt?.requester_pubkey ?? void 0;
18311
+ }
18312
+ if (!stored.feedbackClaim && !receipt) {
18222
18313
  throw new DvmError(
18223
18314
  "platform_dvm_id_unavailable",
18224
18315
  `Job ${opts.job} does not contain a routed feedback claim.`,
@@ -18226,8 +18317,10 @@ async function feedback(bodyParts, opts) {
18226
18317
  );
18227
18318
  }
18228
18319
  feedbackClaim = stored.feedbackClaim;
18229
- feedbackEndpointHost = normalizeFeedbackEndpointHost(stored.endpoint) ?? void 0;
18230
- if (!feedbackEndpointHost) {
18320
+ if (feedbackClaim) {
18321
+ feedbackEndpointHost = normalizeFeedbackEndpointHost(stored.endpoint) ?? void 0;
18322
+ }
18323
+ if (feedbackClaim && !feedbackEndpointHost) {
18231
18324
  throw new DvmError(
18232
18325
  "platform_dvm_id_unavailable",
18233
18326
  `Job ${opts.job} does not contain a valid submitted endpoint.`,
@@ -18247,7 +18340,21 @@ async function feedback(bodyParts, opts) {
18247
18340
  } else {
18248
18341
  scope = "platform";
18249
18342
  }
18343
+ const explicitIdentity = opts.as !== void 0 || Boolean(process.env.DVM_IDENTITY_KEY);
18344
+ const signer = jobPubkey && !explicitIdentity ? findSigningIdentityByPubkey(jobPubkey) : resolveSigningIdentity({ as: opts.as, config: loadConfig() });
18345
+ if (!signer) {
18346
+ throw new DvmError(
18347
+ "auth_required",
18348
+ "The identity that submitted this job is no longer configured.",
18349
+ "Restore that signing identity before rating the job. A different identity cannot prove ownership of its receipt."
18350
+ );
18351
+ }
18352
+ const identityWarning = receipt && jobPubkey && signer.pubkey !== jobPubkey ? "The selected identity differs from the job's requester. The platform will refuse this receipt." : void 0;
18353
+ if (identityWarning) info(`Warning: ${identityWarning}`);
18250
18354
  const payload = { body };
18355
+ if (opts.job !== void 0) payload.job_id = opts.job;
18356
+ if (opts.verdict !== void 0) payload.verdict = opts.verdict;
18357
+ if (receipt !== void 0) payload.receipt = receipt;
18251
18358
  if (dvmId !== void 0) payload.dvm_id = dvmId;
18252
18359
  if (feedbackClaim !== void 0) payload.feedback_claim = feedbackClaim;
18253
18360
  if (feedbackEndpointHost !== void 0) payload.feedback_endpoint_host = feedbackEndpointHost;
@@ -18258,9 +18365,16 @@ async function feedback(bodyParts, opts) {
18258
18365
  if (nudgeQuietKey) recordFeedbackSent(nudgeQuietKey);
18259
18366
  const attributedDvmId = result.dvm_id ?? dvmId;
18260
18367
  const attributedJobId = result.job_id ?? null;
18368
+ const unverifiedHint = opts.verdict !== void 0 && !receipt ? "No receipt is stored for this job, so the verdict was recorded as an unverified claim and does not count toward the provider's public record." : void 0;
18369
+ const warning = [
18370
+ ...warnMissingTrace ? ["no local trace_id for the referenced job"] : [],
18371
+ ...identityWarning ? [identityWarning] : []
18372
+ ].join(" ");
18261
18373
  if (opts.human) {
18262
18374
  info(`Feedback received (id=${result.id}).`);
18263
18375
  info(`Scope: ${scope}${attributedDvmId ? ` \u2014 ${attributedDvmId}` : ""}.`);
18376
+ if (opts.verdict !== void 0) info(`Verdict: ${opts.verdict}. Tier: ${result.tier ?? "unknown"}.`);
18377
+ if (unverifiedHint) info(unverifiedHint);
18264
18378
  if (warnMissingTrace) {
18265
18379
  info("Warning: no local trace_id for that job \u2014 submitted without trace context.");
18266
18380
  }
@@ -18272,7 +18386,10 @@ async function feedback(bodyParts, opts) {
18272
18386
  dvm_id: attributedDvmId ?? null,
18273
18387
  job_id: attributedJobId,
18274
18388
  trace_id: traceId ?? null,
18275
- ...warnMissingTrace ? { warning: "no local trace_id for the referenced job" } : {}
18389
+ verdict: opts.verdict ?? null,
18390
+ tier: opts.verdict !== void 0 ? result.tier ?? null : null,
18391
+ ...unverifiedHint ? { hint: unverifiedHint } : {},
18392
+ ...warning ? { warning } : {}
18276
18393
  });
18277
18394
  }
18278
18395
  }
@@ -18616,12 +18733,12 @@ async function init(opts) {
18616
18733
  ...provisioned ? { identity: { name: provisioned.name, pubkey: provisioned.entry.pubkey } } : {},
18617
18734
  // Only where there is one. A re-run on a machine that already has a wallet
18618
18735
  // has nothing left to point at, and naming a step that is already done is
18619
- // how an agent ends up walking a caller back through setup (an internal review).
18736
+ // how an agent ends up walking a caller back through setup.
18620
18737
  ...setupState.missing.wallet ? { nextStep: "wallet_setup" } : {},
18621
- // an internal review: state the posture a zero-config caller now has, so an agent
18738
+ // state the posture a zero-config caller now has, so an agent
18622
18739
  // learns the rule at setup rather than from the first suppressed purchase.
18623
18740
  creditPosture: creditPosture2,
18624
- // an internal review: same contract for feedback nudges — on by default, ask-first,
18741
+ // same contract for feedback nudges — on by default, ask-first,
18625
18742
  // and the knob is stated here rather than discovered at the first nudge.
18626
18743
  feedbackPosture: feedbackPosture2,
18627
18744
  display: created ? "Local setup is ready. Nothing has been funded yet, so nothing can be spent yet." : "Setup was already in place, and this run changed nothing that was already configured.",
@@ -18854,7 +18971,19 @@ async function messagesWithAccess(jobId, opts, access) {
18854
18971
  if (opts.stream === false) {
18855
18972
  const timeout = opts.timeout ? Number(opts.timeout) * 1e3 : 5e3;
18856
18973
  progressNotice("Fetching messages...", opts.human);
18857
- const msgs = await transport.getMessages(jobId, after, ref, { timeoutMs: timeout, jobToken });
18974
+ let msgs;
18975
+ try {
18976
+ msgs = await transport.getMessages(jobId, after, ref, { timeoutMs: timeout, jobToken });
18977
+ } catch (err) {
18978
+ if (err instanceof DvmError && err.code === "provider_unreachable" && isTerminal && !access.endpointOverridden && loadMessages(jobId).some((message2) => message2.type === "complete" || message2.type === "cancel")) {
18979
+ throw new DvmError(
18980
+ "retained_messages_offline",
18981
+ `Could not fetch messages for ${stored?.status} job ${jobId}; its provider is unreachable.`,
18982
+ `A terminal message is in the local message log. Inspect that log and run 'dvm receipts verify ${jobId}' to check any stored receipt and result hash offline, or restart the provider to fetch messages again.`
18983
+ );
18984
+ }
18985
+ throw err;
18986
+ }
18858
18987
  transport.close();
18859
18988
  if (!access.endpointOverridden) appendMessages(jobId, msgs);
18860
18989
  const newCursor = maxSeq(msgs, after);
@@ -19138,7 +19267,6 @@ async function messageWithAccess(jobId, text, opts, access) {
19138
19267
  jobId,
19139
19268
  sent: { type: outbound.type, content: outbound.content },
19140
19269
  messages: result.messages.map(serializeMessageForOutput),
19141
- // Deferred-notice sinks, spread blind — absent when nothing was stashed.
19142
19270
  ...takeCreditNoticeFields(),
19143
19271
  ...takeFeedbackNoticeFields(),
19144
19272
  next_action: result.nextAction,
@@ -19325,10 +19453,9 @@ async function payWithAccess(jobId, opts, access) {
19325
19453
  // here, and this path has no transport receipt to read the outcome off —
19326
19454
  // so without these an agent that pays sees `next_action: null` and can't
19327
19455
  // tell whether the payload is the summary or artifacts it must go fetch
19328
- // (an internal review). Mirrors what `dvm request` renders on the upfront-paid arc.
19456
+ // Mirrors what `dvm request` renders on the upfront-paid arc.
19329
19457
  ...completion?.summary !== void 0 ? { summary: completion.summary } : {},
19330
19458
  ...completion ? buildCompletionHintFields(jobId, completion) : {},
19331
- // Deferred-notice sinks, spread blind — absent when nothing was stashed.
19332
19459
  ...takeCreditNoticeFields(),
19333
19460
  ...takeFeedbackNoticeFields(),
19334
19461
  next_action: streamResult.nextAction,
@@ -19658,18 +19785,25 @@ async function warmupProvider(transport, ref, options = {}) {
19658
19785
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
19659
19786
  const remaining = deadline - Date.now();
19660
19787
  if (remaining <= 0) break;
19788
+ const attemptsLeft = maxAttempts - attempt + 1;
19789
+ const timeoutMs = Math.max(1, Math.floor(remaining / attemptsLeft));
19661
19790
  try {
19662
- return await describeWithTimeout(transport, ref, remaining);
19791
+ return await transport.describe(ref, { timeoutMs });
19663
19792
  } catch (err) {
19664
19793
  lastErr = err;
19665
19794
  if (err instanceof DvmError && err.code === "unsupported_version") throw err;
19666
19795
  const budgetLeft = deadline - Date.now();
19667
19796
  if (attempt >= maxAttempts || budgetLeft <= 0) break;
19668
- const backoff = Math.min(baseBackoffMs * 2 ** (attempt - 1), MAX_BACKOFF_MS, budgetLeft);
19797
+ const futureAttempts = maxAttempts - attempt;
19798
+ const backoff = Math.min(
19799
+ baseBackoffMs * 2 ** (attempt - 1),
19800
+ MAX_BACKOFF_MS,
19801
+ Math.max(0, budgetLeft - futureAttempts)
19802
+ );
19669
19803
  if (backoff > 0) await sleep(backoff);
19670
19804
  }
19671
19805
  }
19672
- if (isAbortError(lastErr)) {
19806
+ if (isAbortError(lastErr) || lastErr instanceof DvmError && lastErr.code === "timeout") {
19673
19807
  throw new DvmError(
19674
19808
  "endpoint_unreachable",
19675
19809
  `Provider at ${endpoint} did not respond within ${budgetMs / 1e3}s.`,
@@ -19683,21 +19817,6 @@ async function warmupProvider(transport, ref, options = {}) {
19683
19817
  );
19684
19818
  }
19685
19819
  var defaultSleep2 = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
19686
- async function describeWithTimeout(transport, ref, timeoutMs) {
19687
- let timer;
19688
- const timeout = new Promise((_, reject) => {
19689
- timer = setTimeout(() => {
19690
- const err = new Error("The operation timed out.");
19691
- err.name = "TimeoutError";
19692
- reject(err);
19693
- }, timeoutMs);
19694
- });
19695
- try {
19696
- return await Promise.race([transport.describe(ref), timeout]);
19697
- } finally {
19698
- if (timer) clearTimeout(timer);
19699
- }
19700
- }
19701
19820
 
19702
19821
  // src/commands/quote.ts
19703
19822
  async function quote(opts) {
@@ -19936,7 +20055,7 @@ async function quote(opts) {
19936
20055
  ...q.mints ? { mints: q.mints } : {},
19937
20056
  ...q.expiresAt ? { expiresAt: q.expiresAt } : {},
19938
20057
  ...q.payment ? { payment: q.payment } : {},
19939
- // an internal review: the prepaid-credit funding menu + balance echo, verbatim
20058
+ // the prepaid-credit funding menu + balance echo, verbatim
19940
20059
  // wire shape — an agent holding a credit sees cost and remaining
19941
20060
  // balance in one round trip.
19942
20061
  ...q.credit ? {
@@ -19944,7 +20063,7 @@ async function quote(opts) {
19944
20063
  credit_hint: repeatUseCreditHint(callerRef),
19945
20064
  ...creditHeadroom ? { credit_headroom: headroomJson(creditHeadroom) } : {}
19946
20065
  } : {},
19947
- // an internal review: show the post-defaults payload so an agent that called with
20066
+ // show the post-defaults payload so an agent that called with
19948
20067
  // a minimal `--data` can see (and cache) what the server actually
19949
20068
  // validated against. Only emitted when defaults were filled — keeps
19950
20069
  // existing JSON output unchanged for callers that already pass the
@@ -20278,7 +20397,7 @@ function reportRefillHeldByDrain(args, record, held, callerPubkey) {
20278
20397
  endpoint: args.ref.endpoint,
20279
20398
  creditId: record.creditId,
20280
20399
  drainId: held.drainId,
20281
- // The reclaim as the doors that record one spell it (an internal review, an internal review),
20400
+ // The reclaim as the doors that record one spell it ,
20282
20401
  // rather than a third spelling of the same command.
20283
20402
  drainCommand: reclaimCommand(noticeDvm(args), record, record.creditId),
20284
20403
  balanceMicro: record.remainingMicro,
@@ -20827,7 +20946,7 @@ function buildRow(url, list, fee, source) {
20827
20946
  proof_count: list.length,
20828
20947
  input_fee_ppk: fee ?? 0,
20829
20948
  // The fee probe *is* the reachability probe — a null fee means the mint
20830
- // didn't answer just now (an internal review). No extra round-trip.
20949
+ // didn't answer just now. No extra round-trip.
20831
20950
  reachable: fee !== null
20832
20951
  };
20833
20952
  }
@@ -21473,16 +21592,16 @@ async function request(opts) {
21473
21592
  pinnedMint: opts.mint,
21474
21593
  ...opts.strictPerCall ? { strictPerCall: true } : {},
21475
21594
  ...requestedMaxCashuFeeSats !== void 0 ? { maxCashuFeeSats: requestedMaxCashuFeeSats } : {},
21476
- // an internal review: the job cleared by drawing on a prepaid credit — no payment
21595
+ // the job cleared by drawing on a prepaid credit — no payment
21477
21596
  // attach, no budget-ledger entry (the funding already counted).
21478
21597
  ...probePlan.mode === "draw" ? { paymentMethod: "credit" } : {},
21479
- // an internal review: persist the anonymous-flow per-job token so subsequent
21598
+ // persist the anonymous-flow per-job token so subsequent
21480
21599
  // status/messages/pay/cancel commands can present it as `X-Job-Token`.
21481
21600
  jobToken: receipt.jobToken,
21482
- // an internal review: snapshot the platform trace_id captured from the submit
21601
+ // snapshot the platform trace_id captured from the submit
21483
21602
  // response so `dvm feedback --job <id>` can derive it locally.
21484
21603
  traceId: getOutputTraceId() ?? void 0,
21485
- // an internal review: snapshot the receipt trust anchor so verification stays
21604
+ // snapshot the receipt trust anchor so verification stays
21486
21605
  // offline and pins what this DVM advertised when the job ran.
21487
21606
  ...receiptTrustFields(providerInfo),
21488
21607
  ...localCorrelationJobFields(localCorrelationId)
@@ -21498,16 +21617,16 @@ async function request(opts) {
21498
21617
  ...requestIdOutputFields(opts),
21499
21618
  ...transactionOutputFields(receipt),
21500
21619
  ...dvmIdentity(dvmId, capability),
21501
- // an internal review: mirror `dvm quote`'s post-defaults diagnostic on the
21620
+ // mirror `dvm quote`'s post-defaults diagnostic on the
21502
21621
  // noStream branch (closest analog — one shot, no live stream).
21503
21622
  // Streaming paths surface the actual job result, which already
21504
21623
  // tells the agent what the server processed.
21505
21624
  ...normalizedInput && Object.keys(appliedDefaults).length > 0 ? { normalized_input: normalizedInput, applied_defaults: appliedDefaults } : {},
21506
21625
  // This branch returns before the job has an outcome, so it is the only
21507
21626
  // JSON the caller gets — a credit notice stashed during the probe has
21508
- // nowhere else to land (an internal review). The feedback sink deliberately does
21627
+ // nowhere else to land. The feedback sink deliberately does
21509
21628
  // NOT drain here: nothing may stash a feedback notice before a
21510
- // terminal, so there is nothing to carry (an internal review).
21629
+ // terminal, so there is nothing to carry.
21511
21630
  ...takeCreditNoticeFields(),
21512
21631
  next_action: {
21513
21632
  type: "poll",
@@ -21632,7 +21751,7 @@ async function request(opts) {
21632
21751
  // mid-job `requestPayment` — has no receipt carrying the outcome, so
21633
21752
  // these come off the streamed log instead. Without them this arc
21634
21753
  // returned `next_action: null` and nothing else: no summary, and no
21635
- // signal that a payload was waiting in artifacts (an internal review).
21754
+ // signal that a payload was waiting in artifacts.
21636
21755
  ...completion?.summary !== void 0 ? { summary: completion.summary } : {},
21637
21756
  ...completion ? buildCompletionHintFields(receipt.jobId, completion) : {},
21638
21757
  ...captured ? receiptJsonFields(captured) : {},
@@ -21990,7 +22109,7 @@ async function handleAutoPayQuotes(transport, ref, envelope, jobId, deadlineMs,
21990
22109
  receipts: loadReceipts(),
21991
22110
  stored: loadCredit(ref.endpoint, creditCtx.signing.pubkey, attestedIdentity),
21992
22111
  config: loadConfig()?.credit,
21993
- // an internal review: whether the float can carry a funding is half the rail rule,
22112
+ // whether the float can carry a funding is half the rail rule,
21994
22113
  // and it is caller-side state the planner is deliberately kept pure of.
21995
22114
  floatConnected: floatUsable(),
21996
22115
  // The chain rides along with the connection: a channel on a network this
@@ -22357,14 +22476,13 @@ async function payWithTempo(args, credential) {
22357
22476
  status: "submitted",
22358
22477
  submittedAt: Date.now(),
22359
22478
  policy,
22360
- // an internal review: persist the anonymous-flow per-job token returned by the
22479
+ // persist the anonymous-flow per-job token returned by the
22361
22480
  // paid submit so the follow-up SSE GET carries `X-Job-Token` and the
22362
22481
  // SDK's `isJobOwner` check succeeds.
22363
22482
  jobToken: receipt.jobToken,
22364
- // an internal review: snapshot the platform trace_id captured from the submit
22483
+ // snapshot the platform trace_id captured from the submit
22365
22484
  // response so `dvm feedback --job <id>` can derive it locally.
22366
22485
  traceId: getOutputTraceId() ?? void 0,
22367
- // an internal review: snapshot the receipt trust anchor for offline verification.
22368
22486
  ...receiptTrustFields(args.providerInfo),
22369
22487
  ...localCorrelationJobFields(normalizedLocalCorrelationId(opts))
22370
22488
  });
@@ -22561,13 +22679,13 @@ async function tryAgentWalletPayment(transport, ref, envelope, jobId, deadlineMs
22561
22679
  cashuP2pk: {
22562
22680
  mints,
22563
22681
  lock_pubkey: lockPubkey,
22564
- // an internal review: names the per-DVM refund subkey the outputs' NUT-11
22682
+ // names the per-DVM refund subkey the outputs' NUT-11
22565
22683
  // `refund` tag carries, and the locktime floor the DVM asked for.
22566
22684
  canonical_id: providerInfo.cashu?.canonical_id,
22567
22685
  min_locktime: providerInfo.cashu?.min_locktime
22568
22686
  },
22569
22687
  ...builderHandle ? { builderHandle } : {},
22570
- // an internal review: persist what a resume needs to re-POST this exact call. The
22688
+ // persist what a resume needs to re-POST this exact call. The
22571
22689
  // sweep can then re-ship a real submit and write a `JobRecord` from the
22572
22690
  // job id it gets back, instead of stranding the spend with no handle.
22573
22691
  submitContext: activeFund && signing && fundData ? {
@@ -22593,7 +22711,7 @@ async function tryAgentWalletPayment(transport, ref, envelope, jobId, deadlineMs
22593
22711
  prepared.error.code,
22594
22712
  prepared.error.message,
22595
22713
  prepared.error.hint,
22596
- // an internal review: name every mint the spend tried and why, so an agent reading
22714
+ // name every mint the spend tried and why, so an agent reading
22597
22715
  // the JSON error can tell "all my mints are down" from "this one is".
22598
22716
  prepared.error.attempts ? { mint_attempts: prepared.error.attempts } : void 0
22599
22717
  );
@@ -22725,7 +22843,7 @@ async function submitAgentWalletWithRetry(transport, ref, envelope, prepared, de
22725
22843
  intendedLockPubkey: prepared.intendedLockPubkey,
22726
22844
  refetchInfo: () => transport.describe(ref),
22727
22845
  sleep: opts.sleep,
22728
- // an internal review: one retry on a timeout/network failure, because the money has
22846
+ // one retry on a timeout/network failure, because the money has
22729
22847
  // already left. Idempotent by construction — the DVM keys the accumulator
22730
22848
  // on `(dvm_id, request_id)`, so a duplicate is a 409, never a second charge
22731
22849
  // or a second run of the job.
@@ -22836,16 +22954,15 @@ async function payWithAgentWallet(transport, ref, envelope, jobId, deadlineMs, c
22836
22954
  pinnedMint: opts.mint,
22837
22955
  ...opts.strictPerCall ? { strictPerCall: true } : {},
22838
22956
  ...opts.maxCashuFeeSats !== void 0 ? { maxCashuFeeSats: parseMaxCashuFeeSats(opts.maxCashuFeeSats) } : {},
22839
- // an internal review: the paid submit returns the per-job token for anonymous callers.
22957
+ // the paid submit returns the per-job token for anonymous callers.
22840
22958
  // Without persisting it here, the immediately-following SSE GET goes out
22841
22959
  // without `X-Job-Token`, the SDK's `isJobOwner` check fails, and the
22842
22960
  // caller sees `provider_error: stream failed (404)` despite the server
22843
22961
  // running the job to completion and billing it.
22844
22962
  jobToken: receipt.jobToken,
22845
- // an internal review: snapshot the platform trace_id captured from the submit
22963
+ // snapshot the platform trace_id captured from the submit
22846
22964
  // response so `dvm feedback --job <id>` can derive it locally.
22847
22965
  traceId: getOutputTraceId() ?? void 0,
22848
- // an internal review: snapshot the receipt trust anchor for offline verification.
22849
22966
  ...receiptTrustFields(providerInfo),
22850
22967
  ...localCorrelationJobFields(normalizedLocalCorrelationId(opts))
22851
22968
  });
@@ -22970,7 +23087,7 @@ async function tryX402UpfrontPayment(args) {
22970
23087
  network: x402Advert.network,
22971
23088
  asset: x402Advert.asset,
22972
23089
  // Price the USDC against the rate `enforceGlobalBudget` resolved, so the
22973
- // signed amount and the ledger entry can't disagree (an internal review).
23090
+ // signed amount and the ledger entry can't disagree.
22974
23091
  btcRate: args.btcRate
22975
23092
  },
22976
23093
  args.wallet
@@ -23026,7 +23143,6 @@ async function payWithX402(args, proof) {
23026
23143
  policy,
23027
23144
  jobToken: receipt.jobToken,
23028
23145
  traceId: getOutputTraceId() ?? void 0,
23029
- // an internal review: snapshot the receipt trust anchor for offline verification.
23030
23146
  ...receiptTrustFields(args.providerInfo),
23031
23147
  ...localCorrelationJobFields(normalizedLocalCorrelationId(opts))
23032
23148
  });
@@ -23252,7 +23368,7 @@ async function streamAfterPayment(args) {
23252
23368
  summary: null,
23253
23369
  ...paymentFields,
23254
23370
  // Paid, and the job is still live provider-side — the stream gave up,
23255
- // not the job. `poll`, not `null`: the result is still coming (an internal review).
23371
+ // not the job. `poll`, not `null`: the result is still coming.
23256
23372
  ...takeCreditNoticeFields(),
23257
23373
  ...takeFeedbackNoticeFields(),
23258
23374
  next_action: pollNextAction(
@@ -23282,7 +23398,7 @@ async function streamAfterPayment(args) {
23282
23398
  messages: result.messages.map(serializeMessageForOutput),
23283
23399
  // Same as the unpaid arc above: the outcome is only knowable from the
23284
23400
  // streamed log here, so render it rather than leaving the agent to dig
23285
- // the summary out of `messages` and guess about artifacts (an internal review).
23401
+ // the summary out of `messages` and guess about artifacts.
23286
23402
  ...completion?.summary !== void 0 ? { summary: completion.summary } : {},
23287
23403
  ...completion ? buildCompletionHintFields(jobId, completion) : {},
23288
23404
  ...captured ? receiptJsonFields(captured) : {},
@@ -23665,7 +23781,7 @@ async function search(opts) {
23665
23781
  timeoutMs: timeout
23666
23782
  });
23667
23783
  if (result.summary) {
23668
- await outputResults2(result.summary, opts.human, result.nextAction, transport);
23784
+ outputResults2(result.summary, opts.human, result.nextAction);
23669
23785
  return;
23670
23786
  }
23671
23787
  const cancelMsg = result.messages.find((m) => m.type === "cancel");
@@ -23705,7 +23821,7 @@ function cancelMessageToError2(content) {
23705
23821
  const hint = code === "nl_unavailable" ? "This discover instance has no LLM key. Re-run without --mode natural_language to use keyword search." : void 0;
23706
23822
  return new DvmError(code, message2, hint);
23707
23823
  }
23708
- async function outputResults2(resultJson, human, nextAction, transport) {
23824
+ function outputResults2(resultJson, human, nextAction) {
23709
23825
  let output;
23710
23826
  try {
23711
23827
  output = JSON.parse(resultJson);
@@ -23717,7 +23833,7 @@ async function outputResults2(resultJson, human, nextAction, transport) {
23717
23833
  }
23718
23834
  return;
23719
23835
  }
23720
- const expanded = await expandResultsWithCapabilities(output.results, transport);
23836
+ const expanded = buildDiscoveryRows(output.results);
23721
23837
  const favs = loadFavorites();
23722
23838
  const endpointToAlias = {};
23723
23839
  for (const [alias, fav] of Object.entries(favs)) {
@@ -23735,15 +23851,12 @@ async function outputResults2(resultJson, human, nextAction, transport) {
23735
23851
  const alias = endpointToAlias[r.endpoint];
23736
23852
  const label = alias ? ` [* @${alias}]` : "";
23737
23853
  info(` ${i + 1}. ${r.identifier ?? `--endpoint ${r.endpoint}`}${label}`);
23738
- const desc = r.capability_description ?? r.description;
23854
+ const desc = r.capability === void 0 ? r.description : r.capability_description;
23739
23855
  if (desc) info(` ${desc}`);
23740
23856
  if (r.tags.length) info(` Tags: ${r.tags.join(", ")}`);
23741
23857
  info(` Endpoint: ${r.endpoint}`);
23742
- if (r.display) {
23743
- info(` Price: ${r.display.price}`);
23744
- if (r.display.reliability) info(` Reliability: ${r.display.reliability}`);
23745
- if (r.display.credit) info(` Credit: ${r.display.credit}`);
23746
- } else if (r.pricing) {
23858
+ renderDiscoveryDisplay(r, " ");
23859
+ if (r.display?.price == null && r.pricing) {
23747
23860
  const { amount, currency } = r.pricing.max;
23748
23861
  info(
23749
23862
  ` Price: ${currency === "usd" ? `$${amount.toFixed(amount >= 0.01 ? 2 : 4)}` : `${amount.toString()} ${currency}`}`
@@ -23759,11 +23872,9 @@ async function outputResults2(resultJson, human, nextAction, transport) {
23759
23872
  name: asProviderText(r.name),
23760
23873
  description: asProviderText(r.description),
23761
23874
  match_reason: asProviderText(r.match_reason),
23762
- tags: r.tags.map((t) => asProviderText(t))
23875
+ tags: r.tags.map((t) => asProviderText(t)),
23876
+ ...discoveryCapabilityJson(r)
23763
23877
  };
23764
- if (r.capability_description) {
23765
- wrapped.capability_description = asProviderText(r.capability_description);
23766
- }
23767
23878
  return alias ? { ...wrapped, favorite: alias } : wrapped;
23768
23879
  });
23769
23880
  const payload = {
@@ -23912,10 +24023,10 @@ ${msgs.length} new message(s):`);
23912
24023
  ...completion.summary ? { summary: completion.summary } : {},
23913
24024
  ...jobStatus === "completed" ? buildCompletionHintFields(jobId, completion) : {},
23914
24025
  ...completion.message ? { message: completion.message } : {},
23915
- // an internal review: terminal responses only. On a still-running job "absent" would
24026
+ // terminal responses only. On a still-running job "absent" would
23916
24027
  // read as "this DVM doesn't issue receipts" rather than "not yet".
23917
24028
  ...receipt ? receiptJsonFields(receipt) : {},
23918
- // an internal review: `dvm status` is a job-terminal emission for `--no-stream`
24029
+ // `dvm status` is a job-terminal emission for `--no-stream`
23919
24030
  // jobs, so it drains the deferred-notice sinks like the request terminals
23920
24031
  // do. Both spread blind and are absent when nothing was stashed.
23921
24032
  ...takeCreditNoticeFields(),
@@ -24835,7 +24946,7 @@ Fund flow falls back to (built-in): ${DEFAULT_AGENT_MINT_URL}`);
24835
24946
  mints_checked_at: checkedAt,
24836
24947
  // `funding_mint` is what a no-`--mint` `dvm wallet fund` call targets now
24837
24948
  // (first configured mint, or the built-in fallback when none); distinct
24838
- // from `fallback_mint`, the static built-in constant (an internal review).
24949
+ // from `fallback_mint`, the static built-in constant.
24839
24950
  funding_mint: funding.url,
24840
24951
  funding_mint_source: funding.source,
24841
24952
  fallback_mint: DEFAULT_AGENT_MINT_URL,
@@ -25327,7 +25438,7 @@ async function walletBalance(opts) {
25327
25438
  chain_status: chain.status,
25328
25439
  // Only ever set beside a figure the contract did not supply: the record
25329
25440
  // took a local or DVM-reported balance that no chain read has confirmed
25330
- // since (an internal review, an internal review).
25441
+ // at the latest reconciliation.
25331
25442
  ...chain.balanceUnreconciledAt !== void 0 ? { balance_unreconciled_at: chain.balanceUnreconciledAt } : {},
25332
25443
  // Who the contract would repay. Always known here, because the payer is
25333
25444
  // channel-id material rather than something a descriptor carries.
@@ -25375,7 +25486,7 @@ async function walletBalance(opts) {
25375
25486
  address: x402Probe.details?.address,
25376
25487
  network: x402Probe.details?.network,
25377
25488
  ...x402Asset ? { asset: x402Asset.symbol, token: x402Asset.address } : {},
25378
- // an internal review: and the endpoint the number came from, plus whether the
25489
+ // and the endpoint the number came from, plus whether the
25379
25490
  // caller's own override put it there.
25380
25491
  ...rpcJson(x402Probe),
25381
25492
  balance_usdc: x402Probe.balanceUsdc ?? 0,
@@ -25393,14 +25504,10 @@ async function walletBalance(opts) {
25393
25504
  address: tempoProbe.details?.address,
25394
25505
  chain_id: tempoProbe.details?.chain_id,
25395
25506
  ...tempoAsset ? { asset: tempoAsset.symbol, token: tempoAsset.address } : {},
25396
- // an internal review: as on x402 above — which endpoint answered this read.
25507
+ // as on x402 above — which endpoint answered this read.
25397
25508
  ...rpcJson(tempoProbe),
25398
25509
  ...balanceUnknown ? { balance_unknown: true } : { balance_usdc: tempoProbe.balanceUsdc },
25399
25510
  ...tempoAsset && tempoProbe.balanceUsdc === 0 ? { hint: tempoWrongAssetHint(tempoAsset) } : {},
25400
- // an internal review: the probe's own diagnosis, in place of the fixed stderr
25401
- // nudge this used to print — which fired in JSON mode, where prose on
25402
- // stderr is the one place an agent isn't reading, and threw away the
25403
- // rail's own remedy (an internal review) for one generic line about the RPC URL.
25404
25511
  ...tempoProbe.reachable ? {} : unreachableRailJson(tempoProbe)
25405
25512
  };
25406
25513
  }
@@ -25853,7 +25960,7 @@ async function probeWalletConnection(nwcUri, statedBudgetRaw, human) {
25853
25960
  // The probe's own payload rides through — `next_step`, and for a
25854
25961
  // refusal the method and whether it was a permission or a cap. This is
25855
25962
  // also what `dvm wallet pair complete` relays, since it lets this
25856
- // error propagate verbatim (an internal review).
25963
+ // error propagate verbatim.
25857
25964
  ...probe.error?.data ?? {},
25858
25965
  display: probe.error?.display ?? "That Lightning wallet didn't answer, so nothing was saved."
25859
25966
  }
@@ -26354,6 +26461,7 @@ function toResult(pair, entry, nowMs, usedLastKnown) {
26354
26461
  }
26355
26462
 
26356
26463
  // src/lib/tempo-faucet.ts
26464
+ var FAUCET_REQUEST_ID = 2;
26357
26465
  async function fundTempoFromFaucet(account, opts = {}) {
26358
26466
  const network = tempoAccountNetwork(account);
26359
26467
  if (network !== "moderato") {
@@ -26374,7 +26482,13 @@ async function fundTempoFromFaucet(account, opts = {}) {
26374
26482
  fetchImpl,
26375
26483
  mismatchHint: "No faucet request was sent. Tempo's official Moderato endpoint did not serve Moderato; retry after the service recovers."
26376
26484
  });
26377
- await faucetCall(fetchImpl, account.address.toLowerCase());
26485
+ const asset = resolveTempoAsset(process.env, network);
26486
+ await faucetCall(fetchImpl, account.address.toLowerCase(), {
26487
+ network,
26488
+ chainId: chain.chainId,
26489
+ token: asset.address,
26490
+ assetLabel: asset.label
26491
+ });
26378
26492
  const attempts = opts.attempts ?? 12;
26379
26493
  const intervalMs = opts.intervalMs ?? 1e3;
26380
26494
  const sleep = opts.sleep ?? ((ms) => new Promise((resolve3) => setTimeout(resolve3, ms)));
@@ -26399,7 +26513,6 @@ async function fundTempoFromFaucet(account, opts = {}) {
26399
26513
  }
26400
26514
  if (attempt < attempts) await sleep(intervalMs);
26401
26515
  }
26402
- const asset = resolveTempoAsset(process.env, network);
26403
26516
  throw new DvmError(
26404
26517
  "tempo_faucet_balance_unconfirmed",
26405
26518
  `The Moderato faucet accepted the request, but ${asset.label} did not increase after ${String(attempts)} balance checks.`,
@@ -26414,7 +26527,7 @@ async function fundTempoFromFaucet(account, opts = {}) {
26414
26527
  }
26415
26528
  );
26416
26529
  }
26417
- async function faucetCall(fetchImpl, address) {
26530
+ async function faucetCall(fetchImpl, address, context) {
26418
26531
  let response;
26419
26532
  try {
26420
26533
  response = await fetchImpl(TEMPO_MODERATO_RPC, {
@@ -26422,7 +26535,7 @@ async function faucetCall(fetchImpl, address) {
26422
26535
  headers: { "Content-Type": "application/json" },
26423
26536
  body: JSON.stringify({
26424
26537
  jsonrpc: "2.0",
26425
- id: 2,
26538
+ id: FAUCET_REQUEST_ID,
26426
26539
  method: "tempo_fundAddress",
26427
26540
  params: [address]
26428
26541
  }),
@@ -26442,14 +26555,54 @@ async function faucetCall(fetchImpl, address) {
26442
26555
  "The Moderato faucet may be temporarily unavailable or rate limited. No mainnet funds are involved; retry after the service recovers."
26443
26556
  );
26444
26557
  }
26445
- const payload = await response.json();
26446
- if (payload.error) {
26447
- throw new DvmError(
26448
- "tempo_faucet_refused",
26449
- `Tempo faucet RPC refused the request${typeof payload.error.code === "number" ? ` (${String(payload.error.code)})` : ""}: ${typeof payload.error.message === "string" ? payload.error.message : "unknown error"}.`,
26450
- "The Moderato faucet may be rate limited. No mainnet funds are involved; wait before retrying."
26558
+ let payload;
26559
+ try {
26560
+ payload = await response.json();
26561
+ } catch {
26562
+ throw invalidFaucetResponse("malformed_json", context);
26563
+ }
26564
+ if (!isRecord2(payload)) throw invalidFaucetResponse("response_not_object", context);
26565
+ if (payload.jsonrpc !== "2.0") {
26566
+ throw invalidFaucetResponse("invalid_jsonrpc_version", context);
26567
+ }
26568
+ if (payload.id !== FAUCET_REQUEST_ID) {
26569
+ throw invalidFaucetResponse("mismatched_id", context);
26570
+ }
26571
+ const hasResult = Object.hasOwn(payload, "result");
26572
+ const hasError = Object.hasOwn(payload, "error");
26573
+ if (hasResult === hasError) {
26574
+ throw invalidFaucetResponse(
26575
+ hasResult ? "result_and_error" : "missing_result_or_error",
26576
+ context
26451
26577
  );
26452
26578
  }
26579
+ if (hasResult) return;
26580
+ const error = payload.error;
26581
+ if (!isRecord2(error) || typeof error.code !== "number" || !Number.isFinite(error.code) || typeof error.message !== "string") {
26582
+ throw invalidFaucetResponse("invalid_error_object", context);
26583
+ }
26584
+ throw new DvmError(
26585
+ "tempo_faucet_refused",
26586
+ `Tempo faucet RPC refused the request (${String(error.code)}): ${error.message}.`,
26587
+ "The Moderato faucet may be rate limited. No mainnet funds are involved; wait before retrying."
26588
+ );
26589
+ }
26590
+ function invalidFaucetResponse(reason, context) {
26591
+ return new DvmError(
26592
+ "tempo_faucet_outcome_unknown",
26593
+ "The Tempo faucet returned an invalid JSON-RPC response, so the funding outcome is unknown.",
26594
+ `Do not request again blindly. Run 'dvm wallet balance' to check ${context.assetLabel} (${context.token}) on ${tempoNetworkLabel(context.network)}; the request may already have reached the faucet.`,
26595
+ {
26596
+ status: "unknown",
26597
+ reason,
26598
+ network: context.network,
26599
+ chain_id: context.chainId,
26600
+ token: context.token
26601
+ }
26602
+ );
26603
+ }
26604
+ function isRecord2(value) {
26605
+ return typeof value === "object" && value !== null && !Array.isArray(value);
26453
26606
  }
26454
26607
 
26455
26608
  // src/lib/wallet-agent/amount.ts
@@ -26698,7 +26851,6 @@ function unknownErrorCode(err) {
26698
26851
  // src/lib/wallet-agent/mint-failure-observer.ts
26699
26852
  var MintFailureLog = class {
26700
26853
  byQuote = /* @__PURE__ */ new Map();
26701
- /** Open an observer that follows a quote across SDK wallet reacquisitions. */
26702
26854
  open() {
26703
26855
  return (err, quoteId) => {
26704
26856
  if (quoteId === void 0) return;
@@ -26707,11 +26859,9 @@ var MintFailureLog = class {
26707
26859
  this.byQuote.set(quoteId, bucket);
26708
26860
  };
26709
26861
  }
26710
- /** Forget transient failures after the mint answers successfully. */
26711
26862
  clear(quoteId) {
26712
26863
  if (quoteId !== void 0) this.byQuote.delete(quoteId);
26713
26864
  }
26714
- /** The last failure recorded for this quote. */
26715
26865
  claim(quoteId) {
26716
26866
  const bucket = this.byQuote.get(quoteId);
26717
26867
  this.byQuote.delete(quoteId);
@@ -27485,28 +27635,28 @@ async function walletShow(opts) {
27485
27635
  lock_pubkey: post.lock_pubkey,
27486
27636
  recent_spends: recentSpends,
27487
27637
  mints: rows,
27488
- // an internal review: each row's `reachable` was observed on this run and nowhere
27638
+ // each row's `reachable` was observed on this run and nowhere
27489
27639
  // else — the timestamp is here so an agent reads it as a live snapshot
27490
27640
  // rather than durable state about the mint.
27491
27641
  mints_checked_at: mintsCheckedAt,
27492
27642
  pending_mints: post.pending_mints,
27493
- // an internal review: sats that left the wallet but no DVM has confirmed. Excluded
27643
+ // sats that left the wallet but no DVM has confirmed. Excluded
27494
27644
  // from `total_sats` by construction (the proofs are locked to the DVM),
27495
27645
  // so without this block the balance just drops with nothing to point at.
27496
27646
  pending_submissions: submissions.entries,
27497
27647
  pending_submission_sats: submissions.at_risk_sats,
27498
- // an internal review: cash-outs the mint hasn't confirmed. Their proofs are still
27648
+ // cash-outs the mint hasn't confirmed. Their proofs are still
27499
27649
  // counted in `total_sats` but are in-flight and unspendable, so the two
27500
27650
  // numbers only reconcile with this block in view.
27501
27651
  pending_melts: pendingMelts,
27502
27652
  pending_melt_sats: pendingMeltSats,
27503
- // an internal review: submissions this call's sweep re-shipped and cleared, each with
27653
+ // submissions this call's sweep re-shipped and cleared, each with
27504
27654
  // the job id (or an honest null) the DVM handed back.
27505
27655
  resumed: resumedViews,
27506
- // an internal review: payments that expired unclaimed and were swapped back to
27656
+ // payments that expired unclaimed and were swapped back to
27507
27657
  // spendable on this call. No service was rendered for them.
27508
27658
  reclaimed: reclaimedViews,
27509
- // an internal review: reclaims that were due on this call and didn't happen, each
27659
+ // reclaims that were due on this call and didn't happen, each
27510
27660
  // with the reason. Empty is the normal case; a repeating entry here means
27511
27661
  // the self-heal needs a human.
27512
27662
  reclaim_skipped: skippedReclaimViews,
@@ -27588,7 +27738,7 @@ async function fundTempoRail(amount, opts) {
27588
27738
  network,
27589
27739
  network_label: chainLabel,
27590
27740
  chain_id: chain.chainId,
27591
- // an internal review: `token` is the contract; `asset` is the word an agent can
27741
+ // `token` is the contract; `asset` is the word an agent can
27592
27742
  // relay to a human deciding which dollar to buy. Null when an operator
27593
27743
  // override points at a contract we can't name.
27594
27744
  asset: asset.symbol,
@@ -28295,7 +28445,7 @@ function emit(outcomes, pubkey, fingerprint, opts) {
28295
28445
  info(` filtered spent: ${o.filtered_spent}`);
28296
28446
  if (o.skipped_non_master.length > 0) {
28297
28447
  info(
28298
- ` skipped (non-master lock target): ${o.skipped_non_master.length} \u2014 an internal review will surface these as reserved_for`
28448
+ ` skipped (non-master lock target): ${o.skipped_non_master.length} \u2014 not restored; counters advanced past them`
28299
28449
  );
28300
28450
  }
28301
28451
  info(` counters: ${JSON.stringify(o.counters)}`);
@@ -28323,7 +28473,7 @@ function emit(outcomes, pubkey, fingerprint, opts) {
28323
28473
  walletFile: WALLET_FILE,
28324
28474
  mnemonicFile: AGENT_MNEMONIC_FILE,
28325
28475
  display: `Restored ${totalProofs} proofs (${totalSats} sats) across ${outcomes.length} mint(s)`,
28326
- hint: totalSkipped > 0 ? "Some proofs were locked to a non-master pubkey (likely a pre-fund reserve at a DVM) \u2014 an internal review will surface them as `reserved_for` once it lands. Run restore again after an internal review ships to pick them up; counters are already advanced past them." : void 0
28476
+ hint: totalSkipped > 0 ? "Some proofs were locked to a non-master pubkey (likely a pre-fund reserve at a DVM) and were not restored. Scan counters advanced past them." : void 0
28327
28477
  });
28328
28478
  }
28329
28479
  function mnemonicValidationError2(result) {
@@ -28890,7 +29040,7 @@ async function walletMppExit(dvm, opts) {
28890
29040
  channel_id: result.channelId,
28891
29041
  // The token the exit's own fees are charged in, in full: the hint names it
28892
29042
  // too, but an agent funding the wallet needs a contract it can paste rather
28893
- // than prose to parse (an internal review).
29043
+ // than prose to parse.
28894
29044
  channel_token: result.channelToken,
28895
29045
  status: result.status,
28896
29046
  deposit_micro: result.depositMicro,
@@ -30465,10 +30615,10 @@ function listSubmissions(opts) {
30465
30615
  pending_submissions: summary.entries,
30466
30616
  pending_submission_sats: summary.at_risk_sats,
30467
30617
  stranded_count: summary.stranded_count,
30468
- // an internal review: entries that self-heal. Deliberately not folded into
30618
+ // entries that self-heal. Deliberately not folded into
30469
30619
  // `stranded_count` — `--forget` would throw away money that is coming back.
30470
30620
  reclaimable_count: summary.reclaimable_count,
30471
- // an internal review: entries whose self-heal has come due and keeps failing. Also
30621
+ // entries whose self-heal has come due and keeps failing. Also
30472
30622
  // not stranded — the sats are recoverable once the cause is fixed — but
30473
30623
  // unlike `reclaimable` this one needs someone to act.
30474
30624
  reclaim_failed_count: summary.reclaim_failed_count,
@@ -30524,7 +30674,7 @@ async function confirmForget(view, opts) {
30524
30674
  if (opts.yes) return;
30525
30675
  const consequence = !view.at_risk ? `clears the journal entry for ${view.endpoint} (nothing was spent)` : view.state === "reclaimable" || view.state === "reclaim_failed" ? (
30526
30676
  // Worth spelling out: this is the one case where forgetting *costs* the
30527
- // caller money they were otherwise getting back (an internal review). Reaching
30677
+ // caller money they were otherwise getting back. Reaching
30528
30678
  // here at all means they already passed --force.
30529
30679
  `throws away ${view.amount_sats} sats paid to ${view.endpoint} that the wallet can still reclaim by itself, so this cannot be undone`
30530
30680
  ) : view.state === "unreclaimable" ? `clears ${view.amount_sats} sats paid to ${view.endpoint} that are too small to be worth taking back, so nothing recoverable is lost \u2014 but this cannot be undone` : `abandons ${view.amount_sats} sats paid to ${view.endpoint} \u2014 the proofs are locked to the provider with no refund, so this cannot be undone`;
@@ -30956,7 +31106,7 @@ async function walletX402WithdrawFinalize(opts) {
30956
31106
  // A finalize that already succeeded reads identically to one that was
30957
31107
  // never started, so the advice has to cover both — telling a caller whose
30958
31108
  // exit just paid out to start another one is how a completed withdrawal
30959
- // gets mistaken for a lost one (an internal review).
31109
+ // gets mistaken for a lost one.
30960
31110
  `If a finalize was already submitted for this channel, it landed and the escrow is back in this wallet \u2014 check 'dvm wallet balance'. Otherwise run 'dvm wallet x402-withdraw-initiate --channel-id ${metadata.channelId}' first, or use 'dvm credit drain' for the cooperative no-wait exit.`,
30961
31111
  { channel_id: metadata.channelId, network: metadata.network }
30962
31112
  );
@@ -31437,7 +31587,10 @@ function buildProgram() {
31437
31587
  await configRollback(opts);
31438
31588
  }, opts.human);
31439
31589
  });
31440
- program2.command("doctor [target]").description("Diagnose caller-side state (files, config, wallet rails, network)").option("--no-network", "Skip live rail probes, mint health checks, and BTC rate fetch").option("--human", "Human-readable output instead of JSON").action((target, opts) => {
31590
+ program2.command("doctor [target]").description("Diagnose caller-side state (files, config, wallet rails, network)").option(
31591
+ "--no-network",
31592
+ "Skip live rail probes, mint health checks, and BTC rate fetch; cannot be used with [target]"
31593
+ ).option("--human", "Human-readable output instead of JSON").action((target, opts) => {
31441
31594
  return catchErrors(async () => {
31442
31595
  await doctor({ ...opts, target });
31443
31596
  }, opts.human);
@@ -31657,8 +31810,8 @@ function buildProgram() {
31657
31810
  return catchErrors(() => cancel(jobId, opts), opts.human);
31658
31811
  });
31659
31812
  program2.command("feedback [body...]").description(
31660
- "Submit signed-envelope feedback to the dvmkit platform (an internal review). No flags: platform-level. `--dvm <dvm-id>`: about a specific DVM. `--job <jobId>`: about a platform-routed job (router claim + trace_id from local state). Prefer `--body @-` or `--body @file` over positional text for multiline or programmatic feedback."
31661
- ).option("--dvm <dvm-id>", "Target a specific DVM by immutable ID").option("--job <job-id>", "Target a previously-submitted job (mutually exclusive with --dvm)").option(
31813
+ "Submit signed-envelope feedback to the dvmkit platform. No flags: platform-level. `--dvm <dvm-id>`: about a specific DVM. `--job <jobId>`: about a stored job; add `--verdict up|down` to rate it using its receipt. Prefer `--body @-` or `--body @file` over positional text for multiline or programmatic feedback."
31814
+ ).option("--dvm <dvm-id>", "Target a specific DVM by immutable ID").option("--job <job-id>", "Target a previously-submitted job (mutually exclusive with --dvm)").option("--verdict <up|down>", "Rate a job; requires --job, with an optional feedback note").option(
31662
31815
  "--body <text>",
31663
31816
  "Feedback text, or @path/to/file, or @- for stdin. Mutually exclusive with positional body text."
31664
31817
  ).option(