@conto_finance/create-conto-agent 0.4.4 → 0.4.5

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/CHANGELOG.md CHANGED
@@ -1,5 +1,20 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.4.5
4
+
5
+ - `sandbox claim` and `sandbox claim-status` hand an anonymous sandbox to its owner through the
6
+ existing claim link, from a remote or headless shell. A repeated `sandbox claim` reuses a pending
7
+ link, and `--wait` checks until the sandbox is claimed or the timeout passes. The polling token
8
+ stays in the owner-only `.conto/sandbox-claim.json`. Exit codes: 0 link issued or sandbox claimed,
9
+ 1 request failed, 2 credential or local state problem, 3 expired, 4 wait timed out, 5 rate
10
+ limited, 130 interrupted.
11
+ - `init` records its progress and stops with a partial result (exit 3) when a later step, such as
12
+ creating the default policy, fails. Earlier versions reported success. `--resume` creates only
13
+ what is missing and `--restart` discards the record. Agents created by `init` carry an external
14
+ reference so a resume can find them.
15
+ - `doctor --json` prints one JSON document that includes the setup diagnostics when the server
16
+ returns them. Exit codes: 0 no action needed, 1 action required, 2 the check could not complete.
17
+
3
18
  ## 0.4.4
4
19
 
5
20
  - `--sandbox` stores the new sandbox setup key in `.conto/sandbox-setup.env`, an owner-only file
package/README.md CHANGED
@@ -47,6 +47,68 @@ This sends one synthetic signed event to a loopback address. It creates no payme
47
47
  locally and prints the request it would send. It contacts nothing and does not evaluate policy. Use
48
48
  `npx @conto_finance/create-conto-agent limits` to see current limits.
49
49
 
50
+ ## Hand a sandbox to its owner
51
+
52
+ ```bash
53
+ npx @conto_finance/create-conto-agent sandbox claim --json
54
+ npx @conto_finance/create-conto-agent sandbox claim --wait --timeout 300 --json
55
+ npx @conto_finance/create-conto-agent sandbox claim-status --json
56
+ ```
57
+
58
+ `sandbox claim` uses the sandbox organization key, `CONTO_SANDBOX_API_KEY` from the environment or
59
+ `.env.local`, and no other key. It returns a `verificationUrl`, its `expiresAt`, and the
60
+ `requestedPermission`. Send the URL only to the person who will own the sandbox. It holds a
61
+ temporary secret. The polling token stays in `.conto/sandbox-claim.json`, which is owner-only and
62
+ git-ignored, and is never printed.
63
+
64
+ Running `sandbox claim` again reuses a pending link. `--wait` checks the claim at the interval the
65
+ server returns, backs off when rate limited, and stops at `--timeout` (default 300 seconds). A
66
+ timeout or Ctrl+C keeps the link, so the next run continues with it. With `--json`, a newly issued
67
+ link is returned right away so it can be delivered, and the next `--wait` waits on it.
68
+ `claim-status` reports `pending`, `claimed`, or `expired` without printing the link.
69
+
70
+ Claiming makes that person the owner and revokes the sandbox setup key. The sandbox stays in test
71
+ mode. A claim does not fund a wallet, change spending limits, grant scopes, or enable live
72
+ payments.
73
+
74
+ | Exit code | Meaning |
75
+ | --------- | ---------------------------------------------------------- |
76
+ | 0 | Link issued or reused, or the sandbox was claimed |
77
+ | 1 | Request failed |
78
+ | 2 | Missing or wrong credential, or unusable local claim state |
79
+ | 3 | The link or the sandbox expired |
80
+ | 4 | `--wait` timed out and the link is still valid |
81
+ | 5 | Rate limited, see `retryAfterSeconds` |
82
+ | 130 | Interrupted while waiting, the link is still valid |
83
+
84
+ ## Finish an interrupted setup
85
+
86
+ Organization setup records each step in `.conto/init-checkpoint.json` before it creates anything.
87
+ The record holds resource IDs and the requested configuration, never a key. When a step fails,
88
+ setup stops with `"status": "partial"`, the failed step, the IDs it created, and a resume command.
89
+ It writes no agent credentials until every step succeeds.
90
+
91
+ ```bash
92
+ npx @conto_finance/create-conto-agent --resume --api-key <org-api-key> --json
93
+ ```
94
+
95
+ Resume checks each recorded resource and creates only what is missing. It refuses a different
96
+ base URL, organization, or configuration. When the answer to a create request was lost, setup
97
+ stops with `"status": "reconciliation_required"` and the resume looks the resource up before
98
+ creating anything. An SDK key whose secret never reached this machine cannot be recovered. An
99
+ owner revokes it, and the resume issues a new one. `--restart` discards the record and starts a
100
+ new setup. Resources the old setup created stay in the organization.
101
+
102
+ | Exit code | Meaning |
103
+ | --------- | -------------------------------------------------------------------- |
104
+ | 0 | Setup complete |
105
+ | 1 | Setup failed before anything was created |
106
+ | 2 | Refused: unfinished setup, mismatched resume, or rejected credential |
107
+ | 3 | Partial setup, run the resume command |
108
+ | 4 | Reconciliation or owner action needed first, see the output |
109
+
110
+ ## Documentation
111
+
50
112
  - [CLI quickstart](https://conto.finance/docs/cli/quickstart)
51
113
  - [First payment](https://conto.finance/docs/quickstart/setup)
52
114
  - [Commands](https://conto.finance/docs/cli/commands)