@dvmkit/dvm-cli 0.20.0 → 0.22.0

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.
Files changed (29) hide show
  1. package/dist/{chunk-QXXPXQLM.js → chunk-23FGJKIX.js} +2 -2
  2. package/dist/{chunk-2B2MCZ2I.js → chunk-AFR5KKJX.js} +4 -4
  3. package/dist/{chunk-DOAMK5C6.js → chunk-AWK22TUP.js} +2 -2
  4. package/dist/{chunk-4RINUKY4.js → chunk-AWWLO2WW.js} +8330 -27312
  5. package/dist/{chunk-ZZCYSYXR.js → chunk-EA6RU4OR.js} +10 -10
  6. package/dist/{chunk-WCX4PNEF.js → chunk-GEG2YAIB.js} +19 -1
  7. package/dist/{chunk-2YPUKPJN.js → chunk-ITESN5XP.js} +3 -3
  8. package/dist/chunk-MP63OWTD.js +27343 -0
  9. package/dist/{chunk-W4ADV3HW.js → chunk-NSHMTEFJ.js} +27 -17
  10. package/dist/{chunk-4S6TNP4N.js → chunk-WGZ3HBST.js} +388 -92
  11. package/dist/{chunk-MSQJWCPT.js → chunk-X2CKIG2D.js} +3 -3
  12. package/dist/{chunk-EEQPFGPM.js → chunk-YSALCR5X.js} +3 -5
  13. package/dist/{client-FKYQXFBN.js → client-5SB2HSH5.js} +6 -6
  14. package/dist/dvm.js +5969 -772
  15. package/dist/{internal-EQJXMIR2.js → internal-EVD5WVAK.js} +5 -5
  16. package/dist/{lifecycle-3IBVUCTB.js → lifecycle-GR7WGYVQ.js} +6 -6
  17. package/dist/{payout-reporter-5PH53T44-7IA4NGIN.js → payout-reporter-O4OLJXKQ-7N2HPPPY.js} +2 -2
  18. package/dist/{pocket-refill-M65PPCN3.js → pocket-refill-TF7M2XCZ.js} +10 -10
  19. package/dist/{revenue-reporter-4XV3OO5O-RYHS3M34.js → revenue-reporter-RMK4HFEW-7HGJQOXL.js} +2 -2
  20. package/dist/{tempo-lifecycle-Q3N5GGIQ.js → tempo-lifecycle-7EYW5W5Z.js} +8 -8
  21. package/dist/{tempo-wallet-AY6R3E4Z.js → tempo-wallet-QOC3BHVE.js} +7 -7
  22. package/dist/{wallet-J7JCMFZ2.js → wallet-RIHHIQRK.js} +7 -7
  23. package/dist/{x402-FHHB3V4V-CM6OMLHE.js → x402-JCKCGEM3-NFTGP54F.js} +2 -2
  24. package/package.json +2 -2
  25. package/skills/dvm/SKILL.md +1 -1
  26. package/skills/dvm/calling.md +22 -4
  27. package/skills/dvm/credit.md +2 -0
  28. package/skills/dvm/wallets.md +3 -1
  29. package/dist/chunk-DF2OWCRY.js +0 -11127
@@ -467,7 +467,7 @@ import {
467
467
  x402SettledShare,
468
468
  x402VoucherPendingState,
469
469
  x402WalletFromConfig
470
- } from "./chunk-4RINUKY4.js";
470
+ } from "./chunk-AWWLO2WW.js";
471
471
  import "./chunk-JBU7RKQ3.js";
472
472
  import "./chunk-KDNFUDOG.js";
473
473
  import "./chunk-IUTVV6N5.js";
@@ -529,15 +529,15 @@ import {
529
529
  x402NetworkListForCopy,
530
530
  x402NetworkToCaip2,
531
531
  x402SupportedNetworksHint
532
- } from "./chunk-DF2OWCRY.js";
532
+ } from "./chunk-MP63OWTD.js";
533
533
  import {
534
534
  RevenueReporter
535
- } from "./chunk-ZZCYSYXR.js";
535
+ } from "./chunk-EA6RU4OR.js";
536
536
  import {
537
537
  PayoutReporter,
538
538
  applyRetryToPool,
539
539
  withInitRetry
540
- } from "./chunk-W4ADV3HW.js";
540
+ } from "./chunk-NSHMTEFJ.js";
541
541
  import "./chunk-R2DSAZBO.js";
542
542
  import {
543
543
  DIAGNOSTIC_CATALOGUE,
@@ -549,7 +549,7 @@ import {
549
549
  projectDiagnosticFields,
550
550
  projectEventName,
551
551
  projectSpanRow
552
- } from "./chunk-WCX4PNEF.js";
552
+ } from "./chunk-GEG2YAIB.js";
553
553
  import "./chunk-EVQERRCP.js";
554
554
  import "./chunk-RA24J4QM.js";
555
555
  import "./chunk-B4WHUMZM.js";
@@ -3,8 +3,8 @@ import { createRequire as __dvmCreateRequire } from "node:module";
3
3
  const require = __dvmCreateRequire(import.meta.url);
4
4
  import {
5
5
  assertX402WalletIdle
6
- } from "./chunk-DOAMK5C6.js";
7
- import "./chunk-4RINUKY4.js";
6
+ } from "./chunk-AWK22TUP.js";
7
+ import "./chunk-AWWLO2WW.js";
8
8
  import "./chunk-JBU7RKQ3.js";
9
9
  import "./chunk-KDNFUDOG.js";
10
10
  import "./chunk-IUTVV6N5.js";
@@ -13,11 +13,11 @@ import "./chunk-6LP4EGKA.js";
13
13
  import "./chunk-N3UJT2NJ.js";
14
14
  import "./chunk-SYFKO6BA.js";
15
15
  import "./chunk-PUOXBKY2.js";
16
- import "./chunk-DF2OWCRY.js";
17
- import "./chunk-ZZCYSYXR.js";
18
- import "./chunk-W4ADV3HW.js";
16
+ import "./chunk-MP63OWTD.js";
17
+ import "./chunk-EA6RU4OR.js";
18
+ import "./chunk-NSHMTEFJ.js";
19
19
  import "./chunk-R2DSAZBO.js";
20
- import "./chunk-WCX4PNEF.js";
20
+ import "./chunk-GEG2YAIB.js";
21
21
  import "./chunk-EVQERRCP.js";
22
22
  import "./chunk-RA24J4QM.js";
23
23
  import "./chunk-B4WHUMZM.js";
@@ -7,9 +7,9 @@ import {
7
7
  PayoutReporter,
8
8
  PostgresX402BatchStore,
9
9
  x402EarnedCeiling
10
- } from "./chunk-W4ADV3HW.js";
10
+ } from "./chunk-NSHMTEFJ.js";
11
11
  import "./chunk-R2DSAZBO.js";
12
- import "./chunk-WCX4PNEF.js";
12
+ import "./chunk-GEG2YAIB.js";
13
13
  import "./chunk-IYHTITNZ.js";
14
14
  export {
15
15
  MemoryX402BatchStore,
@@ -13,22 +13,22 @@ import {
13
13
  recordFloatSpend,
14
14
  resolveFundMint,
15
15
  sweepPendingMints
16
- } from "./chunk-4S6TNP4N.js";
17
- import "./chunk-2B2MCZ2I.js";
18
- import "./chunk-2YPUKPJN.js";
16
+ } from "./chunk-WGZ3HBST.js";
17
+ import "./chunk-AFR5KKJX.js";
18
+ import "./chunk-ITESN5XP.js";
19
19
  import {
20
20
  loadConfig
21
- } from "./chunk-EEQPFGPM.js";
21
+ } from "./chunk-YSALCR5X.js";
22
22
  import {
23
23
  info,
24
24
  tryResolveBtcUsdRate
25
- } from "./chunk-QXXPXQLM.js";
25
+ } from "./chunk-23FGJKIX.js";
26
26
  import {
27
27
  effectiveFundingMint,
28
28
  effectiveMints,
29
29
  formatUsd,
30
30
  loadAgentWallet
31
- } from "./chunk-4RINUKY4.js";
31
+ } from "./chunk-AWWLO2WW.js";
32
32
  import "./chunk-JBU7RKQ3.js";
33
33
  import "./chunk-KDNFUDOG.js";
34
34
  import "./chunk-IUTVV6N5.js";
@@ -40,11 +40,11 @@ import "./chunk-PUOXBKY2.js";
40
40
  import {
41
41
  microToSats,
42
42
  msatsToMicro
43
- } from "./chunk-DF2OWCRY.js";
44
- import "./chunk-ZZCYSYXR.js";
45
- import "./chunk-W4ADV3HW.js";
43
+ } from "./chunk-MP63OWTD.js";
44
+ import "./chunk-EA6RU4OR.js";
45
+ import "./chunk-NSHMTEFJ.js";
46
46
  import "./chunk-R2DSAZBO.js";
47
- import "./chunk-WCX4PNEF.js";
47
+ import "./chunk-GEG2YAIB.js";
48
48
  import "./chunk-EVQERRCP.js";
49
49
  import "./chunk-RA24J4QM.js";
50
50
  import "./chunk-B4WHUMZM.js";
@@ -3,9 +3,9 @@ import { createRequire as __dvmCreateRequire } from "node:module";
3
3
  const require = __dvmCreateRequire(import.meta.url);
4
4
  import {
5
5
  RevenueReporter
6
- } from "./chunk-ZZCYSYXR.js";
6
+ } from "./chunk-EA6RU4OR.js";
7
7
  import "./chunk-R2DSAZBO.js";
8
- import "./chunk-WCX4PNEF.js";
8
+ import "./chunk-GEG2YAIB.js";
9
9
  import "./chunk-IYHTITNZ.js";
10
10
  export {
11
11
  RevenueReporter
@@ -3,10 +3,10 @@ import { createRequire as __dvmCreateRequire } from "node:module";
3
3
  const require = __dvmCreateRequire(import.meta.url);
4
4
  import {
5
5
  assertTempoWalletIdle
6
- } from "./chunk-MSQJWCPT.js";
7
- import "./chunk-2B2MCZ2I.js";
8
- import "./chunk-EEQPFGPM.js";
9
- import "./chunk-4RINUKY4.js";
6
+ } from "./chunk-X2CKIG2D.js";
7
+ import "./chunk-AFR5KKJX.js";
8
+ import "./chunk-YSALCR5X.js";
9
+ import "./chunk-AWWLO2WW.js";
10
10
  import "./chunk-JBU7RKQ3.js";
11
11
  import "./chunk-KDNFUDOG.js";
12
12
  import "./chunk-IUTVV6N5.js";
@@ -15,11 +15,11 @@ import "./chunk-6LP4EGKA.js";
15
15
  import "./chunk-N3UJT2NJ.js";
16
16
  import "./chunk-SYFKO6BA.js";
17
17
  import "./chunk-PUOXBKY2.js";
18
- import "./chunk-DF2OWCRY.js";
19
- import "./chunk-ZZCYSYXR.js";
20
- import "./chunk-W4ADV3HW.js";
18
+ import "./chunk-MP63OWTD.js";
19
+ import "./chunk-EA6RU4OR.js";
20
+ import "./chunk-NSHMTEFJ.js";
21
21
  import "./chunk-R2DSAZBO.js";
22
- import "./chunk-WCX4PNEF.js";
22
+ import "./chunk-GEG2YAIB.js";
23
23
  import "./chunk-EVQERRCP.js";
24
24
  import "./chunk-RA24J4QM.js";
25
25
  import "./chunk-B4WHUMZM.js";
@@ -6,9 +6,9 @@ import {
6
6
  generateTempoKey,
7
7
  tempoBalanceCheckHint,
8
8
  tempoWrongAssetHint
9
- } from "./chunk-2B2MCZ2I.js";
10
- import "./chunk-EEQPFGPM.js";
11
- import "./chunk-4RINUKY4.js";
9
+ } from "./chunk-AFR5KKJX.js";
10
+ import "./chunk-YSALCR5X.js";
11
+ import "./chunk-AWWLO2WW.js";
12
12
  import "./chunk-JBU7RKQ3.js";
13
13
  import "./chunk-KDNFUDOG.js";
14
14
  import "./chunk-IUTVV6N5.js";
@@ -17,11 +17,11 @@ import "./chunk-6LP4EGKA.js";
17
17
  import "./chunk-N3UJT2NJ.js";
18
18
  import "./chunk-SYFKO6BA.js";
19
19
  import "./chunk-PUOXBKY2.js";
20
- import "./chunk-DF2OWCRY.js";
21
- import "./chunk-ZZCYSYXR.js";
22
- import "./chunk-W4ADV3HW.js";
20
+ import "./chunk-MP63OWTD.js";
21
+ import "./chunk-EA6RU4OR.js";
22
+ import "./chunk-NSHMTEFJ.js";
23
23
  import "./chunk-R2DSAZBO.js";
24
- import "./chunk-WCX4PNEF.js";
24
+ import "./chunk-GEG2YAIB.js";
25
25
  import "./chunk-EVQERRCP.js";
26
26
  import "./chunk-RA24J4QM.js";
27
27
  import "./chunk-B4WHUMZM.js";
@@ -7,9 +7,9 @@ import {
7
7
  removeX402Wallet,
8
8
  repinX402WalletNetwork,
9
9
  saveX402Wallet
10
- } from "./chunk-2YPUKPJN.js";
11
- import "./chunk-EEQPFGPM.js";
12
- import "./chunk-4RINUKY4.js";
10
+ } from "./chunk-ITESN5XP.js";
11
+ import "./chunk-YSALCR5X.js";
12
+ import "./chunk-AWWLO2WW.js";
13
13
  import "./chunk-JBU7RKQ3.js";
14
14
  import "./chunk-KDNFUDOG.js";
15
15
  import "./chunk-IUTVV6N5.js";
@@ -18,11 +18,11 @@ import "./chunk-6LP4EGKA.js";
18
18
  import "./chunk-N3UJT2NJ.js";
19
19
  import "./chunk-SYFKO6BA.js";
20
20
  import "./chunk-PUOXBKY2.js";
21
- import "./chunk-DF2OWCRY.js";
22
- import "./chunk-ZZCYSYXR.js";
23
- import "./chunk-W4ADV3HW.js";
21
+ import "./chunk-MP63OWTD.js";
22
+ import "./chunk-EA6RU4OR.js";
23
+ import "./chunk-NSHMTEFJ.js";
24
24
  import "./chunk-R2DSAZBO.js";
25
- import "./chunk-WCX4PNEF.js";
25
+ import "./chunk-GEG2YAIB.js";
26
26
  import "./chunk-EVQERRCP.js";
27
27
  import "./chunk-RA24J4QM.js";
28
28
  import "./chunk-B4WHUMZM.js";
@@ -30,8 +30,8 @@ import {
30
30
  x402NetworkListForCopy,
31
31
  x402NetworkToCaip2,
32
32
  x402SupportedNetworksHint
33
- } from "./chunk-DF2OWCRY.js";
34
- import "./chunk-WCX4PNEF.js";
33
+ } from "./chunk-MP63OWTD.js";
34
+ import "./chunk-GEG2YAIB.js";
35
35
  import "./chunk-IYHTITNZ.js";
36
36
  export {
37
37
  X402_DEFAULT_FACILITATOR,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dvmkit/dvm-cli",
3
- "version": "0.20.0",
3
+ "version": "0.22.0",
4
4
  "description": "Command-line client and agent skill for Digital Vending Machines: pay-per-use HTTPS services AI agents can find, pay, and call with no account or API key",
5
5
  "author": "DVM Technologies Ltd",
6
6
  "keywords": [
@@ -69,7 +69,7 @@
69
69
  },
70
70
  "dependencies": {
71
71
  "@cashu/cashu-ts": "4.10.2",
72
- "@dvmkit/sdk": "0.36.0",
72
+ "@dvmkit/sdk": "0.41.0",
73
73
  "@scure/base": "2.0.0",
74
74
  "@x402/evm": "2.21.0",
75
75
  "commander": "14.0.3",
@@ -26,7 +26,7 @@ Read the matching file before acting. Load another only when the task reaches th
26
26
 
27
27
  | Task | Read |
28
28
  | --- | --- |
29
- | Find or favourite a DVM, reuse a saved service, call it, or retrieve a result | [Calling](calling.md) |
29
+ | Find or favourite a DVM, reuse a saved service, call it, schedule check-ins for a long job, or retrieve a result | [Calling](calling.md) |
30
30
  | Set up, connect, fund, or inspect a wallet | [Wallets](wallets.md) |
31
31
  | Prepay for repeated use, change credit settings, or reclaim a balance | [Credit](credit.md) |
32
32
  | Resolve an uncertain request, payment, funding, or refund | [Recovery](recovery.md) |
@@ -27,19 +27,25 @@ Check the existing mapping before replacing an alias. Reuse it with `dvm request
27
27
 
28
28
  For metered DVMs, size `--auto-pay-below` for the largest authorized charge (the default is 20% of `--budget`); relay quote `warnings` and use the suggested value only within approved limits, including with `--credit-only`.
29
29
 
30
+ When paying from prepaid credit with explicit `--auto-pay-below` and `--budget`, `dvm request` signs a standing mandate if the provider advertises support and the limits allow later charges. This lets the provider pay later asks from credit while the agent sleeps. The mandate expires after 24h by default. Set `--mandate-until <duration>` for up to 7 days, or use `--no-mandate` to opt out.
31
+
30
32
  ## Run and deliver
31
33
 
32
- Submit once with `dvm request`, preserving the approved input and spending limits. Save the returned request and job identifiers. `--no-stream` returns immediately; it leaves no process attached to pay later asks, even with prepaid credit, a budget, and `--max-payments` greater than one. Keep `dvm messages <job-id> --wait` running to pay within the saved policy, or run `dvm pay <job-id>` for each ask. An unanswered ask ends the job; `dvm status` and `dvm messages --no-stream` pay nothing. Do not promise the full planned duration merely because submission succeeded.
34
+ Submit once with `dvm request`, preserving the approved input and spending limits. Save the returned request and job identifiers. Use `--no-stream` to return after submission. With `mandate.status: "active"`, relay `mandate.display` verbatim at job start so the human knows the total including upfront, the per-charge limit, and when automatic credit charges end. Do not promise the full planned duration merely because submission succeeded.
35
+
36
+ `mandate.status: "unsupported"` means the provider does not advertise automatic credit payments. Relay `mandate.display` if present. If the mandate is unsupported, skipped, or absent, keep a payer attached with `dvm messages <job-id> --wait`, or check in and use `dvm pay <job-id>` for open asks within authorization before they expire. An unanswered payment ask ends the job. `dvm status` and `dvm messages --no-stream` pay nothing.
37
+
38
+ To stop a mandated job and keep finished work, run `dvm decline <job-id>` even between asks. When it returns `stop_requested: true`, relay its `display` and keep checking until the job ends at its next payment ask or finishes. Use `dvm cancel <job-id>` to halt immediately. See [Stop a job](#stop-a-job).
33
39
 
34
40
  Successful upfront Cashu fallback includes optional `mint_attempts`: an array of `{ mint, reason, message }` for earlier failed candidates in the order tried. Reasons are `unreachable`, `keys_unavailable`, `swap_disabled`, `fee_cap_exceeded`, `insufficient_balance`, `no_eligible_mint`, or `swap_rejected`. Messages are bounded CLI-authored explanations, never raw dependency errors; mint URLs are redacted and limited to 2,048 characters. These observations explain why the selected `mint` was used; they do not mark the request failed or represent extra payments. The field is omitted when no candidate failed, including reserve-direct success. Attempts are temporary diagnostics and are not persisted for later status or recovery commands.
35
41
 
36
42
  Failed Cashu spend preparation, including mid-job payment, reports the same ordered entries under `error.mint_attempts`. Dependency prose is replaced with CLI-authored explanations; credential-bearing mint URLs are redacted in both entries and the summary. The summary is limited to 4,096 characters, with all attempted mints retained in the array. Error codes, reason codes, and field shapes are preserved. Consumers that parsed dependency prose must use `error.code` and attempt `reason` instead; message wording is not a compatibility promise. `swap_rejected` covers both definite refusals and unknown swap outcomes: follow the error's recovery hint. Definite refusals restore inputs before another mint is tried; an unknown outcome stops failover and requires `dvm wallet show` reconciliation before those inputs can be reused.
37
43
 
38
- When `dvm request` returns for a still-running job, tell the human at once that the job has started, what was paid, and what happens next. Only then run `dvm messages <job-id> --wait` in the background with its output going to a file (default limit `12h`, override with `--until 30m`). It keeps paying charges authorised by the stored policy while attached. It writes one JSON object per line as each event happens, whether its output is a terminal, a pipe or a file. Read new lines on your own schedule; do not wait for the task to report before answering the human. Each line has an `event`:
44
+ When `dvm request` returns for a still-running job, tell the human at once that the job has started, what was paid, and what happens next. On an always-on host that keeps running between turns, run `dvm messages <job-id> --wait` in the background with its output going to a file (default limit `12h`, override with `--until 30m`) to receive messages and artifacts promptly. It keeps paying charges authorised by the stored policy while attached; an active mandate makes `--wait` optional for payment, but it still delivers artifacts and messages as they arrive. It writes one JSON object per line as each event happens, whether its output is a terminal, a pipe or a file. Read new lines on your own schedule; do not wait for the task to report before answering the human. Hosted agents pause between turns: use [scheduled check-ins](#scheduled-check-ins) instead of a background process. Each line has an `event`:
39
45
 
40
46
  - `message`: one job message, in the shape of a `messages` entry from `dvm messages` (`seq`, `type`, `content`, `display`). When `type` is `artifact`, such as a picture or a report, forward it to the human as it arrives, not when the wait ends.
41
- - `payment`: one charge the CLI paid automatically, with `amount_msats`, `rail`, `reason` and a `display` to relay.
42
- - `result`: the last line when the wait ends: `jobId`, `cursor`, `next_action`, `message_count`, `auto_payment_count` and the job's status fields, including `wallet_remaining` when the job ended. Act on its `next_action`.
47
+ - `payment`: one automatic charge, with `amount_msats`, `rail`, `reason`, and a `display` to relay. `mandate: true` marks a charge the provider paid from credit. Relay its `display` for the amount and any overcharge warning. The CLI checks the signed limits when it has a local copy and says in `display` when it cannot check them. `request_seq_unverified: true` means the available messages could not confirm which ask the payment answered.
48
+ - `result`: the last line when the wait ends: `jobId`, `cursor`, `next_action`, `message_count`, `auto_payment_count` and the job's status fields, including `wallet_remaining` when the job ended. When present, `mandate_payments` gives the latest payment checks. A final history read can resolve a request link that was unverified in a live line. Act on `next_action`.
43
49
  - `error`: the last line when the wait fails, in the usual `{ "error": … }` shape, with exit status 1. Every message and payment before it has already been written.
44
50
 
45
51
  The wait ends when the job ends (`next_action: null`), at a charge or question it cannot answer on its own, at an error, or at the wait limit. At the limit it returns a `poll` action whose hint names the wait limit: with the job still running it gives the command to keep watching, and with an earlier payment unconfirmed it says so and how to resolve it. If the output stops without a `result` or `error` line, the process was stopped from outside: run the same command again. A rerun can repeat a message that is still waiting for an answer, so skip any `seq` you have already handled and forward each artifact once. Silent stream reads reconnect after 60 seconds by default; use `--timeout <seconds>` to change that interval.
@@ -54,6 +60,18 @@ Terminal status and messages may include `unanswered_payment_request` when retai
54
60
 
55
61
  A charge above the job's `--auto-pay-below` limit is never paid automatically. The command exits 0 with a `pay` action and sends nothing. On a DVM that charges by the piece, the action also carries `credit` (the price in integer micro-units of the job's currency) and `charged_if_declined_micro` (what declining costs: the work already finished), both marked as provider fields. Its `display` states the price, what declining costs, and the deadline; relay it verbatim. Then follow the human's choice: `dvm pay <job-id>` within their approval, `dvm decline <job-id>`, or let the deadline pass, which also ends the job.
56
62
 
63
+ If a payment lands as provider credit, it has not necessarily paid the open charge. The CLI tries the job's bound credit within the approved policy before returning a human-choice stop. If credit is refused or cannot pay, relay that stop's `display` and `hint`: they show how to pay explicitly with a different rail and name the command to decline the charge, and, for owned credit, the drain command to use after the job ends and the remaining balance is checked. Never repeat a rail whose payment already landed as credit. An `imp:` credit has no caller key that can reclaim it; contact the provider. The offline credit list offers no drain while the job is still running. A payment whose acceptance details are missing stays unresolved and returns a settling action; follow that action without preparing a new payment.
64
+
65
+ ### Scheduled check-ins
66
+
67
+ For a long, time-sensitive job, use your harness's scheduled task, routine, or automation to wake you between turns. A hosted agent's sandbox pauses; background `--wait` and `nohup` loops pause with it. Keep the background pattern above for always-on hosts only.
68
+
69
+ Choose an interval shorter than the provider's payment ask deadline (`expires_at_ms`; Stakeout allows 30 minutes) and no longer than the alert delay the person accepts. Suggest 5–15 minutes, or the DVM's stated reading interval, within those limits. At job start, state the interval and give the delay as an estimate: "I'll check every 10 minutes, so it can take about 10 minutes for me to see a reading, longer if a check runs late." Never promise "the moment". Explain that frequent checks use the person's agent allowance.
70
+
71
+ Save the job ID, spending policy, alert rule, handled message sequences, and schedule ID for each wake. Each check-in runs `dvm messages <job-id> --wait --until 2m` (or another short limit). Without `--after`, its first read can pay an already-open ask within the stored policy. Do not pass `--after`: an explicit cursor skips the first read's rewind to that open ask. `dvm status` and `dvm messages --no-stream` pay nothing. On a mandated job, the check-in normally just reads and relays. Once the CLI sees an eligible open ask, it gives the provider about 80 seconds to pay it. A 2-minute wait covers that window for an ask seen at the start of the check-in. If the ask stays open, the CLI can try to pay it within the stored policy.
72
+
73
+ Relay each reading that meets the person's rule with its artifact, such as a picture, once. Persist handled `seq` values and skip them on later check-ins. Follow returned actions within authorization. Remove the schedule when the job ends or the person stops it. A finished job usually returns `next_action: null`. On any `refund` action, follow its guidance and run `dvm status <job-id>`; remove the schedule if the status is `completed`, `failed`, or `cancelled`.
74
+
57
75
  ### Budgets
58
76
 
59
77
  A `--budget` given in dollars caps dollar-priced charges in dollars, so a charge that lands exactly on it is paid. A charge that would take the job past its `--budget` also returns `pay`, and its `display` and hint give the spend so far, the charge, the budget and the overrun, in dollars when dollars decided. Ask the human to approve a new total first, then run `dvm pay <job-id> --budget '$1.00'` (substitute the approved total) to save it and pay the open ask. The flag accepts the same dollars or integer millisats as `dvm request --budget`; it replaces the total, rather than adding to it, and refuses a total below spend so far. Alternatively, offer `dvm decline <job-id>`. Restarting `--wait` alone returns the same charge. An implicit per-ask cap follows the new total; an explicitly set `--max-increment` stays fixed. Older jobs whose increment equals their original budget are treated as implicit. `--max-payments` and the automatic payment threshold stay fixed. A used-up payment count cannot be raised here. The total may also be lowered to spend so far or more. A proposed total is saved only when a new payment is about to be sent; if that send fails, output says the total was saved and plain `dvm pay <job-id>` retries or resolves it. A charge above an explicit `--max-increment` cannot be paid on this job; relay it and offer decline or a new request with approved limits.
@@ -46,6 +46,8 @@ Return to [calling](calling.md) for jobs. Keep the same signing identity. If the
46
46
 
47
47
  To reclaim unused credit, inspect the balance and use `dvm credit drain <dvm>` with the indicated credit ID when necessary. Distinguish a requested refund, a pending settlement, and funds actually returned. Provider-marked refund text is the provider's account of events; it does not override the CLI's verified state.
48
48
 
49
+ If a drain returns `drain_outcome_unknown`, the DVM may already have recorded or paid it. Run the error's `next_command` with the same signing identity and `drain_id` to recover the result of that drain.
50
+
49
51
  A Tempo drain with status `exit_required` cannot return the money directly. Relay the CLI's `display` and `hint` and stop polling a terminal drain. The `tempo_channel_exit_required` HTTP 409 form exits 1 and the `exit_required` status form exits 0; both mean run the timed exit, although a 409 with `status: "pending"` still permits a retry of the same drain with a valid close credential (approval to close the deposit). Use the named `dvm wallet tempo-exit <dvm> --credit-id <id>` command, preserving any `--as <name>` selector or the same `DVM_IDENTITY_KEY`. If this machine has no channel recovery record, run the exit from the wallet and machine that opened the channel. This timed exit returns the remaining channel funds after its delay; already approved payments and chain fees can reduce the return. Keep any recovery records until the funds arrive. An `unknown_drain_status` error requires upgrading `dvm` before continuing, not repeated polling.
50
52
 
51
53
  If the provider cannot answer, the available recovery depends on the original funding instrument. Channel exits can recover remaining collateral after the required delay; one-payment funding may depend on a provider refund. Follow [recovery](recovery.md) and the published contract before promising an amount or a completion time. Expiry alone is not proof of a refund or continued recoverability.
@@ -20,7 +20,9 @@ To claim an existing Cashu token, run `dvm wallet receive-token < token.txt` wit
20
20
 
21
21
  Check the required amount and existing balance before topping up. Wallet funding and job payments both count toward spending caps; leave enough authorized headroom for both. Quote shell amounts containing a dollar sign, for example `dvm wallet fund '$5'`, so the shell does not substitute them.
22
22
 
23
- For autonomous funding, follow the output until it reports the observed result. When a human pays a Cashu Lightning invoice, run `dvm wallet fund '<amount>' --no-float --no-wait`, then run the returned `next_step` (`dvm wallet show`) after payment to collect it. An existing unpaid-quote warning names an earlier invoice: avoid asking the human to pay both for the same top-up. Collect before the returned `collect_before` time: a mint can refuse to issue for a paid invoice once its quote has expired. `dvm wallet show` keeps an unpaid invoice past its expiry and keeps checking it for a late payment for 24 hours (`sweep.kept_past_expiry`); it removes one only when the mint no longer honors it (`sweep.expired`). An invoice whose mint named no expiry stays pending until it is paid or you run `dvm wallet forget-quote <quote-id> --yes`. Forget a quote only when you are sure its invoice will not be paid: a payment made afterwards cannot be collected.
23
+ For autonomous funding, follow the output until it reports the observed result. When a human pays a Cashu Lightning invoice and you can relay output while the command runs, use `dvm wallet fund '<amount>' --no-float --no-wait --collect-for 2m`. Relay the `awaiting_payment` handoff immediately. The command checks for payment in the foreground until collection, the duration limit, or quote expiry. A `minted` event confirms collection. If the command reports `collection_stopped`, follow its `next_step` (`dvm wallet show`) and the `collect_before` deadline. If your harness only returns output after the command exits, use `--no-float --no-wait` and run the returned `next_step` after payment.
24
+
25
+ An existing unpaid-quote warning names an earlier invoice. Avoid asking the human to pay both for the same top-up. Collect before `collect_before`. A mint can refuse to issue for a paid invoice once its quote has expired. `dvm wallet show` keeps checking unpaid quotes past expiry for late payment for 24 hours (`sweep.kept_past_expiry`) and reports removed quotes in `sweep.expired`. An invoice whose mint named no expiry stays pending until payment, a final answer from the mint, or `dvm wallet forget-quote <quote-id> --yes`. Forget a quote only when you are sure its invoice will not be paid, since a later payment cannot be collected.
24
26
 
25
27
  For human-assisted funding, show the invoice as soon as the CLI prints it; never wait for the funding command to finish. Send:
26
28