@dvmkit/dvmctl 0.3.4-rc.1 → 0.3.5-rc.1

package/skills/build-dvm/references/configure-context.md

@@ -1,273 +0,0 @@
-## Quickstart — scaffold with `dvmctl create`
-
-```bash
-dvmctl create my-dvm           # scaffolds ./my-dvm/
-cd my-dvm
-npm install
-npm test                       # the scaffold ships a passing test
-dvmctl dev handler.ts          # http://localhost:3000, hot reload, /_dev test page
-```
-
-> Zod ships with the SDK — `import { z } from "@dvmkit/sdk"` for typed `input:` schemas, no extra
-> install. Using the SDK's own zod guarantees a builder schema and the SDK validate against one
-> instance. Skip the schema and `ctx.input` is a raw string you parse yourself.
-
-`dvmctl create <name>` writes a standalone npm project:
-
-```
-my-dvm/
-  handler.ts        # your DVM — a configureDVM(...) descriptor (the file you edit)
-  serve.ts          # production entry point — calls serve(handler, {...})
-  handler.test.ts   # vitest unit tests
-  package.json      # depends on @dvmkit/sdk; scripts: test / dev / deploy
-  tsconfig.json
-  Dockerfile        # two-stage Node 22 build (add system deps here)
-  .env.example      # copy to .env for API keys / secrets
-  README.md
-```
-
-The generated `handler.ts` is a one-capability echo stub. Replace its `onJob` body with your
-logic; everything below is how to grow it.
-
-> **Self-hosting instead of deploying to the platform?** Run `dvmctl init <handle> --self-hosted`
-> once to generate a stable `canonical_dvm_id` and persist it to `~/.dvmkit/builder.json` (a
-> platform deploy assigns this ID for you at deploy time). You then `serve(dvm)` on your own
-> infrastructure.
-
-**Imports** (the SDK ships three entry points):
-
-```typescript
-import { configureDVM } from "@dvmkit/sdk"; // descriptor + types
-import { serve, createDVMHost } from "@dvmkit/sdk/server"; // hosting
-import { secp256k1Auth } from "@dvmkit/sdk/server"; // descriptor-level signed-request auth
-import { createTestContext } from "@dvmkit/sdk/testing"; // unit tests
-```
-
----
-
-## Quick example — single-capability DVM
-
-`handler.ts`:
-
-```typescript
-import { configureDVM, z } from "@dvmkit/sdk";
-
-const inputSchema = z.object({ text: z.string() });
-
-export function createUppercaseDVM() {
-  return configureDVM({
-    name: "uppercase",
-    description: "Convert text to uppercase.",
-    capability: "uppercase",
-    tags: ["text", "uppercase"],
-    input: inputSchema,
-    price: "$0.01",
-
-    async onJob(ctx) {
-      ctx.complete(ctx.input.text.toUpperCase());
-    },
-  });
-}
-
-export default createUppercaseDVM();
-```
-
-`serve.ts`:
-
-```typescript
-import { serve } from "@dvmkit/sdk/server";
-import dvm from "./handler";
-
-await serve(dvm);
-```
-
-`serve(dvm)` reads all wiring (port, `DATABASE_URL`, `DVMKIT_CASHU_MINTS`, Tempo, x402, FX,
-platform reporter) from env. Pass `opts` to override; reach for `createDVMHost` when you need
-custom HTTP routes or to mount several DVMs on one host.
-
----
-
-## configureDVM() reference
-
-```typescript
-configureDVM({
-  // --- DVM-level (always at top level) ---
-  name: string,
-  description?: string,
-  tag?: string,
-  tags?: string[],
-  idleTimeout?: number,        // seconds before auto-cancel (default: 3600)
-
-  auth?: DVMAuthScheme,        // descriptor-level signed-request auth (secp256k1Auth({...}))
-
-  onBoot?(env): void | Promise<void>,    // run once at server start
-  onShutdown?(): void | Promise<void>,   // run once at server stop
-  routes?(app: Hono): void | Promise<void>, // DVM-scoped non-protocol routes
-
-  paymentMethods?: PaymentMethod[],      // ["cashu" | "x402" | "tempo"]; auto-derived from configured rails
-
-  // --- Pick one of the two shapes below ---
-
-  // Flat single-capability shape (most DVMs):
-  capability?: string,                   // e.g. "synthesise" — names this one capability
-                                         // (auto-slugified from `name` if omitted)
-  input?: ZodSchema,                     // ctx.input is typed
-  state?: object,                        // ctx.state defaults, typed
-  price?: PriceValue,                    // "$0.05" — USD literal, the only form
-  onQuote?: QuoteConfig,                 // dynamic pricing
-  onJob(ctx): void | Promise<void>,      // required
-  onResponse?(ctx, content): void | Promise<void>,
-  onPayment?(ctx, content): void | Promise<void>,
-  onApproval?(ctx, content): void | Promise<void>,
-  onCancel?(ctx, content): void | Promise<void>,
-  onMessage?(ctx, msg): void | Promise<void>,
-
-  // OR multi-capability block (mutually exclusive with flat shape):
-  capabilities?: Record<string, CapabilityConfig>,
-});
-```
-
-`configureDVM` returns a frozen `DVMDescriptor`. The flat shape desugars internally to a
-one-entry `capabilities` map — `dvm.capabilities[<name>].onJob` works in either form (tests rely
-on this).
-
-### Per-capability fields (multi-capability shape)
-
-Each entry in `capabilities` accepts: `description`, `input`, `state`, `price`, `onQuote`,
-`onJob` (required), and the same message hooks (`onResponse`, `onPayment`, `onApproval`,
-`onCancel`, `onMessage`). DVM-level concerns (`name`, `description`, `tags`, `auth`,
-`paymentMethods`, `routes`, lifecycle hooks) stay on the parent and are shared across every
-capability.
-
----
-
-## SDKJobContext reference
-
-### Identity (readonly)
-
-| Property      | Type                                | Description                                                                                               |
-| ------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `jobId`       | `string`                            | Server-assigned job ID                                                                                    |
-| `tags`        | `string[]`                          | Tags from the DVM descriptor                                                                              |
-| `input`       | `Input`                             | Job input (raw string, or parsed object when `input` schema is set)                                       |
-| `params`      | `Record<string, string>`            | Key-value parameters                                                                                      |
-| `requesterId` | `string`                            | Opaque requester ID (derived from auth or "anonymous")                                                    |
-| `paidMsats`   | `number`                            | Total msats paid so far                                                                                   |
-| `auth`        | `{ pubkey, envelope } \| undefined` | Verified caller identity — present only when the descriptor declares `auth: secp256k1Auth(...)` |
-
-### Messaging
-
-```typescript
-ctx.text(message: string): void
-ctx.artifact(content: ArtifactContent): void
-ctx.sendMessage(type: MessageType, content: object): void
-ctx.progress(percentComplete: number, phase?: string, hint?: string): void
-```
-
-`ArtifactContent`: `{ data: string, mime_type: string, name?: string, encoding?: "base64" }`
-
-### Flow control
-
-```typescript
-ctx.prompt(id: string, text: string, opts?): Promise<ResponseContent>
-ctx.requestPayment(
-  amount: number | { amount: number; currency: "usd" },
-  reason: string,
-  opts?: SDKPaymentRequestOpts,
-): Promise<PaymentContent>
-ctx.working(estimateSeconds?: number, hint?: string): void
-ctx.complete(summary: string): void                 // one-liner; artifacts carry the payload
-ctx.fail(error: string, opts?: { refund?: boolean }): void
-ctx.cost({ amount, currency }): void                 // your serving cost, in major units
-```
-
-`requestPayment` takes msats (`number`) or a fiat envelope (`{ amount, currency: "usd" }`) — the
-SDK converts to sats at send-time. The legacy `"$0.05"` string form was removed. On counter-based
-auto-credit, `requestPayment` resolves synchronously when the upfront pool already
-covers the amount and only suspends when the pool is exhausted. The caller sees whatever currency
-you name; the ledger records the charge in the DVM's own `currency`, converted at the moment the
-charge is made, so the anti-double-charge ceiling on the job's credit stays exact.
-
-Pass `{ refund: true }` to `ctx.fail` to return Cashu proofs to the caller — typical when the
-failure isn't operator fault (a network glitch, an upstream provider error). Don't refund on
-operator-fault failures (misconfiguration, your own upload failing). See [Refund-on-failure
-policy](patterns-auth.md#refund-on-failure-policy).
-
-### Cancellation — `ctx.signal`
-
-```typescript
-ctx.signal: AbortSignal           // aborts on caller cancel, idle timeout, stale sweep, supersession
-```
-
-Cancel is **terminal**: after it, `ctx.complete` / `ctx.fail` / `ctx.working` and the message
-emitters are no-ops that log a warning (a cancelled job can never come back as `completed`, and no
-revenue is booked on it), and `ctx.prompt` / `ctx.requestPayment` reject instead of hanging. This
-holds across machines — a terminal status is sticky in the job store and the runtime re-reads it
-before persisting, so a handler on a machine that never saw the cancel still can't overwrite it.
-
-### Report serving costs
-
-Use `ctx.cost({ amount, currency })` immediately after a paid provider call or other builder-side
-expense. Amounts are major units, repeated calls add, and only the job total is rounded to
-millionths. Every declaration in one job must use the same lowercase ISO currency; a mixed-currency
-job reports no total rather than guessing an exchange rate.
-
-No call means “unknown”; `{ amount: 0, currency: "usd" }` explicitly means free. Cost declarations
-inside `ctx.step()` are cached with the result and replay exactly once when the body is skipped, so
-declare the cost where it is incurred. Paid completions attach it to revenue, while free completions,
-failures, and cancellations use the separate cost-only report and create no revenue row.
-
-`ctx.fetch` already carries the signal — every request through it aborts on cancel, merged with any
-per-request signal you pass. Thread `ctx.signal` into everything else that can be torn down
-(provider SDK `signal` options, spawned processes, your own sleeps): that is where provider spend
-actually stops.
-
-```typescript
-async onJob(ctx) {
-  const audio = await client.tts.generate(text, { signal: ctx.signal });
-
-  for (const chunk of chunks) {
-    if (ctx.signal.aborted) return; // already terminal — don't call ctx.fail()
-    await process(chunk);
-  }
-
-  ctx.complete("Done");
-}
-```
-
-Return early on abort; the runtime has written the terminal status already. `onCancel` still fires if
-you declare one — use it for cleanup (release a lock, delete a staged upload); the signal is raised
-before the hook runs, so a slow cleanup can't hold the abort back.
-
-**`onCancel` is cleanup only — it can't emit.** The job is terminal before the hook runs, so a
-`ctx.text()` / `ctx.artifact()` / `ctx.complete()` inside it is ignored with a
-`ctx.<op>() ignored — job already cancelled` warning. Emit partial results as you go, not on the way
-out.
-
-**Multi-machine DVMs are covered.** On a DVM with `max_machines > 1`, a cancel that lands on a machine
-other than the one running the handler is committed to the store there; the machine running the
-handler subscribes to its own jobs' notifications, so it picks the cancel up within a notification
-round-trip — `ctx.signal` fires, `onCancel` runs on the machine holding the resources, the cancel
-lands in the job's message log, and the handler's late writes are rejected. Same behaviour whichever
-machine the cancel hits.
-
-**Isolate tier.** An isolate-hosted handler runs in its own Machine, so it learns of a cancel by
-polling its job's durable status on the platform (default every 2 s, `DVMKIT_ISOLATE_CANCEL_POLL_MS`).
-The contract above is identical — `ctx.signal` aborts, `ctx.fetch` tears down, emitters no-op, yields
-reject — just one poll tick behind the cancel.
-
-### Platform services
-
-```typescript
-ctx.state: State                  // typed from defaults; auto-persisted on every yield
-ctx.store: KVStore                // cross-job async KV storage
-ctx.fetch: typeof fetch           // instrumented fetch — dvm.fetch spans + auto-aborts on cancel
-ctx.env: Record<string, string>   // environment variables (read at job time, not boot)
-ctx.log: Logger                   // structured logging (.debug, .info, .warn, .error)
-ctx.step<T>(id: string, fn: () => Promise<T>): Promise<T>  // cached on yield
-```
-
-Prefer `ctx.fetch` over the global `fetch` for outbound HTTP: calls show up in traces, and they
-abort when the caller cancels the job.
-
----

package/skills/build-dvm/references/operating-feedback.md

@@ -1,153 +0,0 @@
-## Operating a deployed DVM
-
-Once a DVM is live, `dvmctl` is the full operational surface — you never need `flyctl`.
-Every command emits JSON by default and takes `--human`; `<slug>` is the DVM's deployed name.
-Exceptions noted inline (`logs` and `revenue csv` emit raw output, not JSON).
-
-Every DVM-specific command resolves its bare `<slug>` only inside the active `dvmctl switch` context. Pass `--org <handle>` for a one-shot override without changing that context. The CLI resolves that scoped slug to an immutable DVM ID before it reads, changes, or opens a machine resource, so a matching slug in another org is never selected accidentally.
-
-### Fleet introspection
-
-| Command                 | Purpose                                                      | Key flags                   |
-| ----------------------- | ------------------------------------------------------------ | --------------------------- |
-| `dvmctl list`           | List your deployed DVMs                                      |                             |
-| `dvmctl info <slug>`    | Deployed-DVM details                                         | `--org`                     |
-| `dvmctl status <slug>`  | Live Fly runtime state (machines, region, image, health)     | `--org`                     |
-| `dvmctl metrics <slug>` | Request metrics                                              | `--hours` (default 24), `--org` |
-| `dvmctl events <slug>`  | Recent events (deploys, restarts, scale, env, machine state) | `--since` (e.g. `2h`, `7d`), `--org` |
-
-### Runtime ops
-
-| Command                     | Purpose                                                         | Key flags                          |
-| --------------------------- | --------------------------------------------------------------- | ---------------------------------- |
-| `dvmctl logs <slug>`        | View or stream logs (**raw output**, not JSON)                  | `--tail`, `--since`, `--lines`, `--org` |
-| `dvmctl ssh <slug>`         | Interactive shell, or one-shot command, on the Fly machine      | `--command`, `--machine`, `--org`  |
-| `dvmctl restart <slug>`     | Restart machines without a redeploy                             | `--machine` (default: all), `--org` |
-| `dvmctl rollback <slug>`    | Revert to a previous successful deploy's image                  | `--to <deploy-id>` (default: prev), `--org` |
-| `dvmctl scale <slug>`       | Change machine count and/or VM size without a redeploy          | `--count` (1–8), `--size`, `--org` |
-| `dvmctl destroy <slug>`     | Destroy the DVM and its paired Postgres cluster                 | `--confirm`, `--keep-db`, `--org`  |
-| `dvmctl deploy-status <id>` | Status of a deploy by ID — recovery handle for a stuck `deploy` |                                    |
-
-### Config, data & tracing
-
-| Command                             | Purpose                                                                       | Key flags                      |
-| ----------------------------------- | ----------------------------------------------------------------------------- | ------------------------------ |
-| `dvmctl env <slug>`                 | View or update environment variables                                          | `--set KEY=val`, `--unset KEY`, `--org` |
-| `dvmctl secrets list <slug>`        | List secret names + last-applied times (never values)                         | `--org`                       |
-| `dvmctl db connect <slug>`          | Interactive `psql` against the DVM's database (needs local `psql`)            | `--machine`, `--org`          |
-| `dvmctl db proxy <slug>`            | Bind a local port to the DVM's database (`pg_dump`, drizzle-kit, GUI clients) | `--port`, `--machine`, `--org` |
-| `dvmctl trace get <traceId>`        | Fetch a trace by ID (isolate-dataset spans)                                   | `--no-color`                   |
-
-### Custom domains
-
-| Command                                 | Purpose                                         |
-| --------------------------------------- | ----------------------------------------------- |
-| `dvmctl domains add <slug> <domain>`    | Attach a custom domain (e.g. `api.example.com`); `--org` selects its org |
-| `dvmctl domains list <slug>`            | List attached domains; `--org` selects its org                              |
-| `dvmctl domains verify <slug> <domain>` | Verify DNS/TLS provisioning; `--org` selects its org                        |
-| `dvmctl domains remove <slug> <domain>` | Remove a custom domain; `--org` selects its org                             |
-
-### Revenue & payout
-
-Reporting, the path to collect your earnings off the Cashu accumulator, and the operator queues for refunds
-and settlements no automatic loop will ever clear.
-
-| Command                                | Purpose                                                              | Key flags                                                    |
-| -------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------ |
-| `dvmctl revenue summary`               | Totals + per-rail breakdown                                          | `--from`, `--to` (required), `--currency`                    |
-| `dvmctl revenue events`                | Individual revenue events                                            | `--from`, `--to`, `--rail`, `--limit`                        |
-| `dvmctl revenue csv`                   | Export revenue as CSV (**raw CSV output**)                           | `--from`, `--to` (required), `--currency`, `--rail`, `--out` |
-| `dvmctl set-payout <handle> <ln-addr>` | Persist the default Lightning payout address for `melt-pending`      | `--skip-preflight`, `--self-hosted`, `--org`                  |
-| `dvmctl melt-pending <handle>`         | Drain pending Cashu accumulator batches to the Lightning payout addr | `--payout`, `--endpoint`, `--watch`, `--interval`, `--org`   |
-| `dvmctl rotate <handle>`               | Rotate the per-DVM Cashu lock pubkey (publishes next BIP-32 child)   | `--endpoint`, `--org`                                        |
-| `dvmctl credit blocked <handle>`       | Lightning top-ups the ledger could never credit — the operator queue | `--include-resolved`, `--limit`, `--after`, `--endpoint`, `--org` |
-| `dvmctl credit reconcile <handle> <payment-hash>` | Credit a blocked payment onto a credit the caller holds    | `--credit-id` (required), `--endpoint`, `--org`              |
-| `dvmctl credit write-off <handle> <payment-hash>` | Reviewed, not crediting — moves no money, reversible       | `--note`, `--endpoint`, `--org`                               |
-| `dvmctl credit drains-owed <handle>`     | One-payment stablecoin refunds you owe (channel-backed ones settle themselves) | `--endpoint`, `--org`                              |
-| `dvmctl credit drain-settle <handle> <credit-id> <drain-id>` | Record a refund you sent on chain — idempotent   | `--tx` (required), `--note`, `--endpoint`, `--org`           |
-| `dvmctl credit x402-wedged <handle>`     | x402 refunds that settled on chain but never booked — the repair queue | `--include-resolved`, `--limit`, `--after`, `--min-age-ms`, `--no-evidence`, `--endpoint`, `--org` |
-| `dvmctl credit x402-reconcile <handle> <settlement-id>` | Finish one at the chain's own figure — never one you supply | `--endpoint`, `--org`                        |
-| `dvmctl credit x402-write-off <handle> <settlement-id>` | Reviewed, not booking — moves no money, reversible | `--note`, `--endpoint`, `--org`                    |
-| `dvmctl credit tempo-wedged <handle>`    | Tempo closes that landed on chain but never booked the drain | `--include-resolved`, `--limit`, `--after`, `--min-age-ms`, `--no-evidence`, `--endpoint`, `--org` |
-| `dvmctl credit tempo-reconcile <handle> <credit-id> <drain-id>` | Book one against the close receipt's own refund figure | `--endpoint`, `--org`                  |
-| `dvmctl credit tempo-write-off <handle> <credit-id> <drain-id>` | Reviewed, not booking — moves no money, reversible | `--note`, `--endpoint`, `--org`            |
-
-### Account, org & auth
-
-| Command                        | Purpose                                                  | Key flags                        |
-| ------------------------------ | -------------------------------------------------------- | -------------------------------- |
-| `dvmctl auth`                  | Authenticate with the platform                           | `--status`, `--logout`           |
-| `dvmctl switch [handle]`       | Set the active org context for deploys (omit = show)     | `--personal` (clear)             |
-| `dvmctl transfer <slug> <to>`  | Transfer a DVM to an org (by handle) or back to personal | `--create-org`, `--display-name`, `--org` |
-| `dvmctl api-keys list`         | List builder API keys                                    |                                  |
-| `dvmctl api-keys create`       | Create a builder API key                                 | `--label`                        |
-| `dvmctl api-keys revoke <id>`  | Revoke a builder API key                                 |                                  |
-| `dvmctl handle set <handle>`   | Claim a builder handle for `*.dvmkit.ai` subdomains      |                                  |
-| `dvmctl handle check <handle>` | Check handle availability                                |                                  |
-| `dvmctl identity create`       | Generate a per-workstation secp256k1 builder identity    | `--force`                        |
-| `dvmctl identity show`         | Print the builder identity pubkey                        |                                  |
-
-## Caller feedback
-
-Callers can send signed-envelope feedback about a DVM via `dvm feedback --dvm <slug> "..."` (or
-`--job <jobId>` to attach a trace_id). The platform persists every submission per-slug; as the
-builder, you read and toggle collection through `dvmctl feedback`.
-
-```bash
-dvmctl feedback list <slug>              # newest-first, JSON
-dvmctl feedback list <slug> --since 24h  # relative duration ("24h", "7d") or ISO 8601
-dvmctl feedback list <slug> --limit 100 --cursor <c> --org acme
-```
-
-`list` is cursor-paginated, capped at 100 per page (default 50). Walk older pages by passing the
-response's `next_cursor` back via `--cursor`. JSON shape:
-
-```json
-{
-  "slug": "...",
-  "feedback": [
-    { "id": "...", "slug": "...", "created_at": "...", "caller_pubkey": "...",
-      "body": "...", "trace_id": "..." | null, "job_id": "..." | null }
-  ],
-  "next_cursor": "..." | undefined
-}
-```
-
-Toggle collection per-DVM:
-
-```bash
-dvmctl feedback enable <slug>    # flips dvms.feedback_enabled = true
-dvmctl feedback disable <slug>   # flips dvms.feedback_enabled = false
-```
-
-When disabled, subsequent caller submissions to that slug fail with `409 feedback_disabled` and a
-`display` field the calling agent can relay to its user. `list` keeps returning previously-stored
-rows either way — the toggle gates collection, not retrieval.
-
-All three commands require `dvmctl auth` (org-scoped); `list` only returns feedback for DVMs owned
-by the authenticated org.
-
----
-
-## Verification
-
-After writing or modifying DVM code, run the generated project's test command. Add project-owned
-`lint` and `typecheck` scripts before relying on them, then run all three from the project directory:
-
-```bash
-npm run lint
-npm run typecheck
-npm test
-```
-
-**If the capability charges and calls a paid third-party API, there is a fourth rung** — the
-[live provider contract](testing.md#live-provider-contracts):
-
-```bash
-<PROVIDER_KEY>=… npm run test:providers:live
-```
-
-This is a project-owned opt-in script: add it as described in the
-[live provider contract](testing.md#live-provider-contracts). It is key-gated and spends real vendor
-money, so it skips cleanly without the key. If you don't have one, **say so** and hand the operator
-a green static pass — don't report the provider contract as verified when the suite skipped.