warpmetal 0.4.2 → 0.5.0

package/README.md

@@ -4,10 +4,12 @@ The official command-line client and portable Agent Skill for WarpMetal.
 
 The CLI uses the public API at `https://api.warpmetal.com`, stores generated
 WarpMetal credentials in a user-private state file, and never reads or stores
-wallet private keys or SSH private-key contents. Version 0.4 adds a guarded
-x402api Agent Wallet handoff: WarpMetal writes the exact credential-free payment
-request, explains the next commands to an agent, validates the returned payment
-artifact, and submits it without absorbing wallet custody.
+wallet private keys or SSH private-key contents. Version 0.5 adds dedicated
+hostname-based VPS identities, bounded autonomous renewal, verified lifecycle
+email, and signed refill requests through the x402api Agent Wallet. WarpMetal
+writes the exact credential-free payment request, explains the next commands to
+an agent, validates the returned payment artifact, and submits it without
+absorbing wallet custody.
 
 ## Distribution
 
@@ -60,9 +62,18 @@ warpmetal order prepare \
   --plan agent \
   --hostname codex-workspace \
   --os '<exact name from warpmetal catalog>' \
-  --ssh-public-key-file ~/.ssh/id_ed25519.pub
+  --generate-ssh-key \
+  --json
 ```
 
+The generated key defaults to
+`${WARPMETAL_HOME:-~/.config/warpmetal}/ssh/warpmetal-codex-workspace`. A
+collision receives a random suffix; existing keys are never overwritten. Once
+checkout returns `serverId`, the CLI binds that ID to the identity so
+`warpmetal server login` and `warpmetal runtime install` can select it without
+an `--identity` flag. Use `--ssh-public-key-file` instead when supplying a
+user-managed public key.
+
 Pass `--json` for structured, secret-redacted output. Use
 `WARPMETAL_API_URL` for an alternate API origin and `WARPMETAL_HOME` for an
 alternate state directory.
@@ -137,6 +148,48 @@ recipient, and never sends ETH or SOL for a sponsored payment. In an unattended
 run, use a preconfigured refill or escalation mechanism or stop with
 `funding_required`.
 
+## Autonomous renewal and refill
+
+Configure renewal only with explicit bounds. This example allows at most 12
+renewals, enforces a 30 USDC per-payment ceiling and a 360 USDC cumulative
+budget, and requests a verified notification recipient:
+
+```sh
+warpmetal renewal configure \
+  --server <serverId> \
+  --renew-before-days 3 \
+  --maximum-payment-atomic 30000000 \
+  --maximum-renewals 12 \
+  --maximum-total-spend-atomic 360000000 \
+  --allowed-network eip155:8453 \
+  --allowed-asset 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
+  --wallet <dedicated-wallet> \
+  --email ops@example.com \
+  --json
+```
+
+The recipient must follow the one-time verification link before lifecycle or
+refill mail is sent. A recurring unattended agent can then run:
+
+```sh
+warpmetal renewal due --all --json
+warpmetal renewal run --all-due --json
+```
+
+Inside policy, the CLI returns the exact Agent Wallet authorization and submit
+argv. If balance is insufficient, run the returned `refillWorkflow.argv` with
+its `X402API_NOTIFICATION_URL` environment value. `x402api wallet
+notify-refill` signs an opaque subscription reference and wallet-produced
+balance fields; it cannot choose an email address. WarpMetal verifies the
+wallet signature and current on-chain balance before emailing the verified
+human the network, stablecoin, public wallet address, and required minimum
+top-up. The human may transfer more than that minimum; the renewal policy—not
+the refill target—remains the spending authority.
+
+The agent never sends a partial x402 payment. If no verified refill path
+exists, it reports `funding_required`. If a previous payment is pending or
+ambiguous, it reconciles the saved attempt and never signs a second payment.
+
 The x402api Agent Wallet is a separate, merchant-neutral executable. Install
 its matching `x402api-pay` skill with `x402api skill install --output <agent-skill-directory>/x402api-pay --json`.
 Do not use `x402api pay`, `payment submit`, or `payment reconcile` for WarpMetal:
@@ -180,7 +233,6 @@ compatible external signer.
 warpmetal runtime enable --server <serverId> --json
 warpmetal runtime install \
   --server <serverId> \
-  --identity ~/.ssh/warpmetal-owner \
   --ssh-user ubuntu \
   --confirm INSTALL \
   --wait \
@@ -202,7 +254,7 @@ cleanup, access-grant, and strict host-key connection workflow.
 
 ## Release status
 
-The initial development release is published at
+The package is published at
 `https://www.npmjs.com/package/warpmetal`. The source is publicly visible but
 remains `UNLICENSED`; choose an explicit license before describing the project
 as open source or inviting third-party reuse.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "warpmetal",
-  "version": "0.4.2",
-  "description": "Agent-safe CLI and skill for purchasing and managing WarpMetal VPS servers",
+  "version": "0.5.0",
+  "description": "Agent-safe CLI and skill for purchasing, renewing, and managing WarpMetal VPS servers",
   "type": "module",
   "bin": {
     "warpmetal": "bin/warpmetal.js"
@@ -38,6 +38,8 @@
     "agent-skills",
     "codex",
     "claude",
-    "x402"
+    "x402",
+    "autonomous-renewal",
+    "ssh"
   ]
 }

package/skills/warpmetal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: warpmetal
-description: Safely purchase and manage WarpMetal VPS servers and Agent Runtime sandboxes with the official warpmetal CLI, including x402api Agent Wallet payment handoff. Use when a shell-capable agent needs live VPS discovery, x402 payment authorization, ordering, provisioning, server management, optional runtime installation, fixed-size sandbox creation, persistent or temporary lifetime, per-agent SSH access, sandbox connection, access revocation, or workspace deletion.
+description: Safely purchase, renew, and manage WarpMetal VPS servers and Agent Runtime sandboxes with the official warpmetal CLI and x402api Agent Wallet. Use when a shell-capable agent needs live VPS discovery, hostname-based SSH identity creation, x402 payment or refill handling, bounded autonomous renewal, human lifecycle notifications, ordering, provisioning, server management, optional runtime installation, sandbox creation, per-agent SSH access, revocation, or deletion.
 ---
 
 # WarpMetal
@@ -23,6 +23,8 @@ with ad hoc HTTP commands.
    funding a wallet, authorizing payment, or resolving an ambiguous attempt.
 7. Read [references/runtime.md](references/runtime.md) before requesting,
    installing, accessing, expiring, or deleting Agent Runtime sandboxes.
+8. Read [references/renewals.md](references/renewals.md) before configuring or
+   executing an autonomous renewal or requesting a wallet refill.
 
 Never read, print, summarize, upload, or commit the WarpMetal state file,
 x402api keystore, password file, payment request envelope, or payment artifact.
@@ -52,18 +54,27 @@ or price from documentation or a previous session.
 
 ## Prepare an order
 
-Confirm the intended plan, exact OS, hostname, and existing SSH public-key file
-with the user. Ask before generating a new SSH key pair.
+Confirm the intended plan, exact OS, and actual hostname. In a live human
+conversation, ask before generating a new SSH key pair. In an unattended run,
+generate a dedicated identity only when the automation policy permits creating
+local credentials. Use the actual hostname as the readable key name; the CLI
+adds `warpmetal-` and a short suffix only when a file already exists.
 
 ```sh
 warpmetal order prepare \
   --plan <planId> \
   --hostname <hostname> \
   --os '<exact live OS name>' \
-  --ssh-public-key-file <public-key-path> \
+  --generate-ssh-key \
   --json
 ```
 
+Use `--ssh-public-key-file <public-key-path>` instead only when a suitable key
+was explicitly selected. Never run raw `ssh-keygen` for the VPS owner identity.
+The CLI creates and binds `serverId -> key name -> fingerprint -> local paths`.
+Inspect the safe mapping with `warpmetal server identity --server <serverId>
+--json`; do not open the state file.
+
 The CLI saves the generated recovery credential privately and does not print
 it. Preserve the reported task and server IDs in the conversation, but do not
 open the state file to retrieve the credential.
@@ -124,6 +135,31 @@ human is chatting and the terms changed; in an unattended run, proceed only if
 the replacement remains within standing authority. On `manual_review` or an
 ambiguous attempt, stop and never create another payment.
 
+## Renew autonomously within policy
+
+Configure a bounded server policy before unattended renewal. Require a
+per-payment ceiling and either a maximum renewal count or `renewThrough`; use a
+cumulative ceiling when required by the operator. Bind a local Agent Wallet
+whose network and asset exactly match the policy. See
+[references/renewals.md](references/renewals.md) for commands and the complete
+state machine.
+
+In a live human conversation, disclose the exact renewal terms before signing.
+In an unattended run, do not seek conversational approval when the policy,
+wallet ceiling, exact live challenge, and balance all permit payment. Stop on a
+price, asset, network, count, horizon, or total-budget mismatch.
+
+Run `warpmetal renewal prepare --server <serverId> --json`, then invoke only
+the returned `paymentWorkflow.authorize.argv` and
+`paymentWorkflow.submit.argv`. If authorization reports insufficient balance,
+set the returned `refillWorkflow.environment`, invoke its exact argv once, and
+stop until funding arrives. The signed refill intent resolves to a verified
+human contact; never add an email address to it. Never make a partial payment.
+
+After funding, prepare again, authorize exactly once, submit with WarpMetal,
+and confirm the returned `termEndsAt`. On `reconcile_pending` or
+`manual_review`, do not create another authorization.
+
 ## Provision and manage
 
 Poll a prepared or paid order with:
@@ -141,7 +177,7 @@ For routine management, prove possession of the installed SSH key without
 reading it:
 
 ```sh
-warpmetal server login --server <serverId> --identity <private-key-path> --json
+warpmetal server login --server <serverId> --json
 warpmetal server get --server <serverId> --json
 ```
 
@@ -182,7 +218,7 @@ preserve the key; update `known_hosts` only when the verified key changed and
 never bypass a mismatch. Then wait for grants to become applied and refresh
 every connection profile with `sandbox access refresh --confirm REFRESH`
 before connecting. Do not fall back to raw API calls for deletion, networking,
-renewal, or another unsupported mutation.
+or another unsupported mutation.
 
 ## Use Agent Runtime
 

package/skills/warpmetal/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "WarpMetal VPS"
-  short_description: "Purchase and manage WarpMetal compute safely"
-  default_prompt: "Use $warpmetal to purchase a VPS through the guarded x402 wallet handoff and manage isolated agent sandboxes safely."
+  short_description: "Purchase, renew, and manage WarpMetal compute"
+  default_prompt: "Use $warpmetal to purchase or renew a VPS with a dedicated SSH identity, bounded x402 payment policy, and safe lifecycle management."

package/skills/warpmetal/references/cli-reference.md

@@ -4,6 +4,8 @@
 
 - Discovery
 - Purchase and provisioning
+- SSH identities
+- Renewal and notifications
 - Server management
 - Agent Runtime and sandboxes
 - Per-agent access
@@ -27,7 +29,7 @@ warpmetal order prepare \
   --plan <live planId> \
   --hostname <dns-label> \
   --os '<exact live OS name>' \
-  --ssh-public-key-file <path> \
+  (--generate-ssh-key [--ssh-key-name <name>] | --ssh-public-key-file <path>) \
   [--runtime-file <runtime.json>] [--confirm TEMPORARY] \
   [--email <address>] \
   [--idempotency-key <key>] \
@@ -74,12 +76,53 @@ It reports only safe attempt metadata. The compatibility
 never creates, imports, reads, or stores wallet keys and does not sign x402
 challenges itself. See [payments.md](payments.md).
 
+## SSH identities
+
+```sh
+warpmetal identity generate --hostname <dns-label> [--ssh-key-name <name>] --json
+warpmetal identity list --json
+warpmetal server identity --server <serverId> --json
+warpmetal server identity attach \
+  --server <serverId> --identity <private-key-path> \
+  [--ssh-key-name <name>] --json
+```
+
+Generated identities live under the private WarpMetal state directory. The
+default name is `warpmetal-<actual-hostname>`. Existing files are never
+overwritten; a collision adds a short suffix. Order completion binds the local
+identity to `serverId`, and later SSH-backed commands select it automatically.
+
+## Renewal and notifications
+
+```sh
+warpmetal renewal configure \
+  --server <serverId> --renew-before-days <n> \
+  --maximum-payment-atomic <amount> \
+  (--maximum-renewals <n> | --renew-through <UTC>) \
+  [--maximum-total-spend-atomic <amount>] \
+  --allowed-network <network> --allowed-asset <asset> \
+  --wallet <name> [--refill-target-atomic <amount>] [--email <address>] --json
+warpmetal renewal status --server <serverId> --json
+warpmetal renewal due (--server <serverId> | --all) --json
+warpmetal renewal prepare --server <serverId> --json
+warpmetal renewal submit --server <serverId> \
+  --payment-artifact <path> [--wait] --json
+warpmetal renewal run (--server <serverId> | --all-due) --json
+warpmetal notifications configure --server <serverId> --email <address> \
+  [--events <comma-separated-events>] --json
+warpmetal notifications status --server <serverId> --json
+```
+
+`renewal prepare` returns exact payment and refill argv arrays. `renewal run`
+is an agent-facing state machine, not a wallet-signing daemon. See
+[renewals.md](renewals.md).
+
 ## Server management
 
 ```sh
 warpmetal server login \
   --server <serverId> \
-  --identity <private-key-path> \
+  [--identity <private-key-path>] \
   --json
 
 warpmetal server get --server <serverId> --json
@@ -95,7 +138,8 @@ warpmetal server power \
 warpmetal server reload \
   --server <serverId> --confirm ERASE --power-off-first \
   [--acknowledge-agent-runtime-reset] [--hostname <name>] \
-  [--os <exact-live-os-name>] [--ssh-public-key-file <public-key-path>] \
+  [--os <exact-live-os-name>] \
+  [--generate-ssh-key [--ssh-key-name <name>] | --ssh-public-key-file <path>] \
   [--idempotency-key <key>] [--wait] [--timeout-seconds <n>] --json
 
 warpmetal operation get \
@@ -122,7 +166,7 @@ process listings.
 warpmetal runtime enable --server <serverId> [--idempotency-key <key>] --json
 warpmetal runtime get --server <serverId> [--wait] [--timeout-seconds <n>] --json
 warpmetal runtime install \
-  --server <serverId> --identity <owner-key> --ssh-user <admin-user> \
+  --server <serverId> [--identity <owner-key>] --ssh-user <admin-user> \
   --confirm INSTALL [--wait] [--timeout-seconds <n>] --json
 
 warpmetal sandbox create \

package/skills/warpmetal/references/payments.md

@@ -5,6 +5,7 @@
 - Trust boundary
 - Wallet setup and funding
 - Exact purchase workflow
+- Exact renewal and refill workflow
 - Retries and recovery
 
 ## Trust boundary
@@ -70,8 +71,10 @@ skill automatically.
    contract/mint or `paymentTerms.recipient`. Sponsored launch payments never
    ask the buyer to fund ETH or SOL. Recheck the balance after the transfer.
 7. If funding is short in an unattended run, use only a preconfigured refill
-   or escalation mechanism. Otherwise report `funding_required` and stop; do
-   not invent a human approval step or funding source.
+   mechanism returned by WarpMetal. For a configured renewal, set the returned
+   `refillWorkflow.environment`, invoke `refillWorkflow.argv` once, and stop
+   until funding arrives. Otherwise report `funding_required` and stop; do not
+   invent a human approval step or funding source.
 
 Treat the dedicated wallet's funded balance as spend authority available to
 the agent, bounded by any wallet-local maximum payment policy and task or
@@ -137,6 +140,17 @@ expiry, sponsorship lifetime, file type, or permissions do not match the saved
 challenge. Keep `--payment-signature-file` only as a compatibility path for
 another external signer.
 
+## Exact renewal and refill workflow
+
+Renewal uses the same signer boundary and exact artifact checks as purchase,
+but the merchant body is `{"serverId":"..."}` and submission returns through
+`warpmetal renewal submit`. Read [renewals.md](renewals.md) for policy limits,
+scheduling, signed refill notification, and recovery states.
+
+Never use an initial-purchase artifact for renewal or a renewal artifact for a
+later term. The resource URL, body, challenge digest, gas reservation, and
+current `termEndsAt` generation are different.
+
 ## Retries and recovery
 
 - `payment_pending` or `payment_finalizing`: keep the same checkout bytes and

package/skills/warpmetal/references/renewals.md

@@ -0,0 +1,127 @@
+# WarpMetal renewal and refill workflow
+
+## Contents
+
+- Configure standing authority
+- Schedule renewal checks
+- Authorize and submit renewal
+- Request a refill
+- Stop and recovery states
+
+## Configure standing authority
+
+Create a durable backend policy and local Agent Wallet binding:
+
+```sh
+warpmetal renewal configure \
+  --server <serverId> \
+  --renew-before-days 3 \
+  --maximum-payment-atomic <per-renewal-cap> \
+  (--maximum-renewals <count> | --renew-through <UTC>) \
+  [--maximum-total-spend-atomic <total-cap>] \
+  --allowed-network <exact-CAIP-2-network> \
+  --allowed-asset <exact-contract-or-mint> \
+  --wallet <agent-wallet-name> \
+  [--refill-target-atomic <target>] \
+  [--email <human-address>] \
+  --json
+```
+
+`--email` queues verification; refill and expanded lifecycle notices remain
+disabled until the human opens the verification link. A refill target is a
+funding target, not spend permission, and cannot exceed the per-renewal cap.
+The human may transfer more than the displayed deficit. The agent may spend
+only the exact renewal amount allowed by policy.
+
+The WarpMetal CLI stores only the local wallet name. The backend stores
+non-secret limits, counters, payment rail, time horizon, and an opaque
+notification reference. WarpMetal never receives the wallet key.
+
+## Schedule renewal checks
+
+Use a recurring agent, scheduler, CI job, or cron to invoke:
+
+```sh
+warpmetal renewal due --all --json
+warpmetal renewal run --server <serverId> --json
+```
+
+The CLI does not install a daemon. Treat actions as follows:
+
+- `not_due`: stop successfully until the next scheduled check.
+- `policy_required`: configure or deliberately revise policy.
+- `approval_required`: stop; a ceiling or horizon prevents autonomous spend.
+- `sign_payment`: follow the returned exact payment workflow.
+- `refill_required`: follow the signed refill workflow and stop.
+- `reconcile_pending`: preserve the artifact and reconcile; never authorize again.
+- `manual_review`: stop all payment and mutation retries.
+- `renewed`: verify the new `termEndsAt` and stop successfully.
+
+## Authorize and submit renewal
+
+```sh
+warpmetal renewal prepare --server <serverId> --json
+```
+
+The command validates server state and policy, preserves the exact body
+`{"serverId":"..."}`, validates the sponsored x402 challenge, selects exactly
+one policy-compatible rail, and returns:
+
+```text
+paymentWorkflow.authorize.argv
+paymentWorkflow.submit.argv
+refillWorkflow.environment
+refillWorkflow.argv
+```
+
+Invoke the authorize argv once. It writes an owner-only artifact. Then invoke
+the submit argv, equivalent to:
+
+```sh
+warpmetal renewal submit \
+  --server <serverId> \
+  --payment-artifact <owner-only-artifact-path> \
+  --wait \
+  --json
+```
+
+WarpMetal validates the artifact against the saved renewal body, challenge,
+resource, policy network, policy asset, per-payment cap, sponsorship, and
+buyer payment identifier before adding the private management credential.
+
+## Request a refill
+
+When Agent Wallet reports insufficient asset balance, do not authorize a
+partial payment and do not create another wallet merely to bypass the policy.
+Set the exact returned `X402API_NOTIFICATION_URL`, then invoke the returned:
+
+```sh
+x402api wallet notify-refill \
+  --wallet <name> \
+  --subscription-reference <opaque-reference> \
+  --renew-by <UTC> \
+  --target-balance-atomic <amount> \
+  --reason renewal \
+  --json
+```
+
+The wallet independently reads its live balance and signs a 15-minute
+domain-separated intent. WarpMetal verifies the audience, time, nonce,
+signature, wallet address, network, asset, policy, subscription, and
+authoritative balance before queuing email. The intent cannot name a recipient
+email, tenant, or product.
+
+In a human conversation, also display the exact deficit, network, token symbol,
+contract or mint, and payer wallet address. Tell the human to fund the payer
+wallet address—not the token contract/mint and not WarpMetal's merchant
+recipient. Do not ask for ETH or SOL because supported network fees are
+sponsored.
+
+## Stop and recovery states
+
+- Insufficient balance: notify once, stop, and recheck later.
+- Signed HTTP 402: re-run prepare and re-evaluate the replacement challenge.
+- Pending or timeout after authorization: reuse the same artifact; do not sign again.
+- Price or payment rail outside policy: stop for deliberate policy revision.
+- Exhausted count, horizon, or cumulative budget: stop for deliberate policy revision.
+- Cancellation conflict or `manual_review`: payment may be final; stop all retries.

package/skills/warpmetal/references/safety.md

@@ -28,6 +28,12 @@
 - Never read or transmit an SSH private key. Pass only its filesystem path to
   `warpmetal server login`, `warpmetal runtime install`,
   `warpmetal sandbox connect`, or `ssh-keygen`.
+- Generate a VPS owner identity through `warpmetal order prepare
+  --generate-ssh-key` or `warpmetal identity generate`, not a raw shell
+  command. The actual hostname is the readable key name. Never reuse or
+  overwrite a generated owner key merely because another server has the same
+  hostname; let the CLI add its collision suffix and bind the identity to
+  `serverId`.
 - WarpMetal disables VPS password and keyboard-interactive SSH login after
   initial provisioning and every OS reload. Never request, store, invent, or
   expect a VPS login password; use the submitted public key and matching
@@ -72,6 +78,14 @@ use unsupported or buyer-funded payment rails. If the wallet is short and no
 preconfigured refill or escalation mechanism exists, report
 `funding_required` and stop.
 
+For renewal, require an enabled server policy with a per-payment ceiling and a
+bounded count or date horizon. Also enforce the exact network, asset, wallet
+ceiling, and cumulative budget when configured. A refill target is not a spend
+ceiling. Never pay outside policy, split a payment, or authorize twice to
+resolve ambiguity. A signed refill request may contain only the opaque
+subscription reference and wallet-produced fields; never add a recipient
+email or untrusted product text.
+
 A reload requires both `confirm: "ERASE"` and `powerOffFirst: true`. Treat
 `powerOffFirst` as explicit authorization for WarpMetal to shut down the
 server, wait until it is powered off, and then erase and reinstall it inside

package/src/api.js

@@ -176,6 +176,54 @@ export class WarpMetalClient {
     });
   }
 
+  getRenewalPolicy(serverId, token) {
+    return this.request(
+      "GET",
+      `/api/servers/${encodeURIComponent(serverId)}/renewal-policy`,
+      { token },
+    );
+  }
+
+  putRenewalPolicy(serverId, body, token) {
+    return this.request(
+      "PUT",
+      `/api/servers/${encodeURIComponent(serverId)}/renewal-policy`,
+      { body, token },
+    );
+  }
+
+  deleteRenewalPolicy(serverId, token) {
+    return this.request(
+      "DELETE",
+      `/api/servers/${encodeURIComponent(serverId)}/renewal-policy`,
+      { token },
+    );
+  }
+
+  getNotifications(serverId, token) {
+    return this.request(
+      "GET",
+      `/api/servers/${encodeURIComponent(serverId)}/notifications`,
+      { token },
+    );
+  }
+
+  putNotifications(serverId, body, token) {
+    return this.request(
+      "PUT",
+      `/api/servers/${encodeURIComponent(serverId)}/notifications`,
+      { body, token },
+    );
+  }
+
+  renewalCheckout(planId, { bodyText, token, paymentSignature }) {
+    return this.checkout(`/api/checkout/${encodeURIComponent(planId)}/renew`, {
+      bodyText,
+      token,
+      paymentSignature,
+    });
+  }
+
   powerServer(serverId, action, token, idempotencyKey) {
     return this.request(
       "POST",