cloudgpu-mcp 0.16.2 → 0.16.4
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/README.md +67 -3
- package/package.json +1 -1
- package/skills/cloudgpu/SKILL.md +4 -0
- package/src/api.js +13 -0
- package/src/index.js +21 -8
- package/src/job-batches.js +20 -0
- package/src/job-input.js +2 -0
- package/src/regional-offers.js +25 -0
- package/src/strict-tools.js +13 -0
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
The agent checks live prices and quotes you, rents the GPU once you say yes, uploads your code and data, starts training in the background, watches the logs, downloads the adapter and destroys the instance. You get the files and the final cost.
|
|
8
8
|
|
|
9
|
-
It is a local (stdio) MCP server. It works with any MCP client that can start one: Claude Code, Cursor, Cline, opencode, goose, VS Code, Windsurf and others.
|
|
9
|
+
It is a local (stdio) MCP server. It works with any MCP client that can start one: Codex, Claude Code, Cursor, Cline, opencode, goose, VS Code, Windsurf and others. Remote Streamable HTTP with OAuth is also available at `https://cloudgpu.app/mcp`; see [remote MCP setup](https://cloudgpu.app/docs/mcp).
|
|
10
10
|
|
|
11
11
|
## Install
|
|
12
12
|
|
|
@@ -100,6 +100,26 @@ extensions:
|
|
|
100
100
|
|
|
101
101
|
To check the install, ask your agent: "List the GPUs available, then estimate the cost for a 24 GB GPU for one hour. Do not create anything." You should see `list_gpus` and `estimate_cost` calls and a quote, and nothing is rented.
|
|
102
102
|
|
|
103
|
+
## Codex MCP
|
|
104
|
+
|
|
105
|
+
Add the local stdio server without putting a key in your command history:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
codex mcp add cloudgpu -- npx -y cloudgpu-mcp
|
|
109
|
+
codex mcp list
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
In Codex, ask CloudGPU to call `connect_account`, open the returned link yourself, sign in, review the limits and approve, then ask it to call `finish_connect`. If needed, use `request_top_up` for an owner payment link and `wait_for_funds` to check the resulting balance. Never paste credentials into the conversation. Account connection does not approve paid compute; review a fresh quote and its billing terms before each allocation.
|
|
113
|
+
|
|
114
|
+
For a Codex client that supports remote MCP and OAuth, use this instead of the local entry:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
codex mcp add cloudgpu --url https://cloudgpu.app/mcp
|
|
118
|
+
codex mcp login cloudgpu
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
The remote and local transports expose different tool sets; consult the [current MCP documentation](https://cloudgpu.app/docs/mcp). Start with a read-only capability or GPU-price check and explicitly ask it not to create resources. This is direct MCP configuration, separate from the optional Codex plugin below.
|
|
122
|
+
|
|
103
123
|
## Agent Skill
|
|
104
124
|
|
|
105
125
|
The same guidance is available as two [Agent Skills](https://agentskills.io):
|
|
@@ -133,7 +153,7 @@ The same guidance is available as two [Agent Skills](https://agentskills.io):
|
|
|
133
153
|
| Tool | What it does |
|
|
134
154
|
|---|---|
|
|
135
155
|
| `get_account` | Balance, and how many instances the account may run at once |
|
|
136
|
-
| `list_gpus` | GPU models
|
|
156
|
+
| `list_gpus` | GPU models, live starting rates, availability and detailed native configurations (GPU count, CPU, RAM, disks, region, interconnect and total hourly price) when available |
|
|
137
157
|
| `list_templates` | Ready-made images: JupyterLab, Ollama, ComfyUI, LLaMA-Factory, … |
|
|
138
158
|
| `compare_compute_costs` | Compare live total billed GPU cost for up to eight compatible candidates; no reservation or creation approval |
|
|
139
159
|
| `estimate_cost` | Live quote for a GPU and a number of hours, plus your balance afterwards; returns a `quote_id` |
|
|
@@ -148,6 +168,8 @@ The same guidance is available as two [Agent Skills](https://agentskills.io):
|
|
|
148
168
|
| `get_job` / `list_jobs` | Job status, exit code, cost, the last ~4 KB of output and the job's history |
|
|
149
169
|
| `cancel_job` | Stops a job and destroys its GPU |
|
|
150
170
|
| `get_agent_readiness` / `assess_task_fit` | Anonymous capability, billing, task suitability and evidence checks; no GPU is created |
|
|
171
|
+
| `list_rental_regions` | Anonymous qualified continent catalog; use its enabled flag, then a continent-bound rental quote |
|
|
172
|
+
| `list_regional_offers` | Anonymous native regional inventory observations and independent price evidence; explicit owner country, freshness, unknowns and overlapping capacity; planning only |
|
|
151
173
|
| `request_top_up` / `wait_for_funds` | Human-only payment link and bounded polling for actual credit; no automatic charge or Job |
|
|
152
174
|
| `quote_storage_budget` / `confirm_storage_budget` | Quote and explicitly approve an earmarked storage transfer; backend rollout and owner permissions apply |
|
|
153
175
|
| `resume_artifact_upload` | Resume the same owned multipart reservation with the original local file and checksum |
|
|
@@ -396,7 +418,7 @@ With `persist_summary=true`, the Job draft explicitly collects only `pipeline-su
|
|
|
396
418
|
|
|
397
419
|
### Funded connection, storage growth and remote MCP
|
|
398
420
|
|
|
399
|
-
Version 0.16.0 was verified on npm and the official Registry on 2026-11-13. The current stdio inventory is
|
|
421
|
+
Version 0.16.0 was verified on npm and the official Registry on 2026-11-13. The current stdio inventory is 57 tools. The remote endpoint at `https://cloudgpu.app/mcp` uses Streamable HTTP JSON responses and OAuth authorization code with S256 PKCE; it exposes 23 tools safe without local filesystem/SSH access. Public discovery needs no login; account and paid operations require scoped owner authorization. Always check live backend capabilities and actual source-specific billing.
|
|
400
422
|
|
|
401
423
|
`connect_account` returns a direct Google link and email alternative. Pending connection state is private, origin-bound and survives restart; the server allows 30 minutes for approval. Browser payment does not approve compute. `request_top_up` creates only a short-lived owner link; `wait_for_funds` requires a real credit signal and sufficient live balance. Neither creates a Job.
|
|
402
424
|
|
|
@@ -411,3 +433,45 @@ The reviewed [Python SDK0.1.0 release](https://github.com/cloudgpu-app/cloudgpu-
|
|
|
411
433
|
### Reproducible paid task cases
|
|
412
434
|
|
|
413
435
|
See [environment check, synthetic causal-LM LoRA and tiny ComfyUI video cases](examples/verified-tasks/README.md) for pinned scripts, observed fees, download checksums and release evidence. They preview locally by default; paid submission needs owner approval. Resume an accepted Job by ID to download results without another GPU. For persistent tasks, `assess_task_fit` accepts `expected_output_bytes`; current direct collection and bounded network fallback limits are returned by the live contract.
|
|
436
|
+
|
|
437
|
+
### Durable server batches and whole-hour Jobs (0.16.3)
|
|
438
|
+
|
|
439
|
+
Use `prepare_job_batch` to review every command, fresh compute quote, deadline and aggregate GPU cap. Pass the exact manifest/hash and explicit user approval to `run_server_job_batch`. The server atomically commits all child Job rows or none; it dispatches from the database after client/server restarts, waiting for account/Key execution slots. `get_server_job_batch(batch_id)` returns bounded states/cost summaries; use individual `get_job` for detailed outputs. `cancel_server_job_batch` requires approval and preserves charges for already-started hours. Failed commands are not automatically rerun, and an uncertain provider result never authorizes another GPU.
|
|
440
|
+
|
|
441
|
+
REST equivalents: `POST /v1/job-batches` with `Idempotency-Key`, `total_budget_usd` and 1–32 `jobs`; `GET /v1/job-batches/{batch_id}`; `POST /v1/job-batches/{batch_id}/cancel`. The MCP reviewed manifest remains capped at eight children. Replaying the identical key/body returns the existing children. Existing `run_job_batch` retains its explicitly non-atomic client submission behavior for compatibility; the server tool never falls back to it.
|
|
442
|
+
|
|
443
|
+
For whole-hour Jobs, call `estimate_cost` for the exact configuration and accept the minimum/billing period. Supply its `billing_quote_id` plus `billing_accepted=true` to `run_job` or each batch child, in addition to the compute `quote_id` and execution approval. Each allocation needs a separate current billing quote. The Job cap must cover the minimum; elapsed portions of a started hour are not voluntarily refunded. Billing quotes last five minutes: an expired queued Job fails without allocation and requires a new reviewed request. It is never silently renewed or routed under different billing terms. Recovery uses durable provider receipts and independent upstream presence checks; ambiguous intents remain `needs_attention`.
|
|
444
|
+
|
|
445
|
+
### Regional facts before a compute decision
|
|
446
|
+
|
|
447
|
+
`list_regional_offers` calls anonymous `GET /v1/public/compute-offers`. Give the
|
|
448
|
+
human owner country explicitly as `user_country`; an Agent's hosting location
|
|
449
|
+
is not its owner's location. Optional filters are `country_code`, `gpu_model`,
|
|
450
|
+
`gpu_count`, `include_unavailable`, `limit` and the returned `after_id` cursor.
|
|
451
|
+
Stock and source-price evidence have separate ages. Failed, stale, unsupported
|
|
452
|
+
or missing observations do not prove zero stock. Counts are not reservations
|
|
453
|
+
or proof that multiple cards can be allocated on one host. Capacity groups are
|
|
454
|
+
known aliases only; do not sum them into an independent global total.
|
|
455
|
+
|
|
456
|
+
Native regional observations do not authorize execution or change retail
|
|
457
|
+
pricing. A published SKU reference is not an executable quote. For a hard
|
|
458
|
+
continent constraint, use the separately advertised rental capability below.
|
|
459
|
+
Country/datacenter constraints remain unsupported and must not be dropped. MCP also
|
|
460
|
+
rejects unknown argument fields instead of silently stripping them. Tasks that
|
|
461
|
+
do not require a location continue to use fresh standard quotes and their
|
|
462
|
+
source-specific billing/approval rules. No native mounted-volume product is
|
|
463
|
+
offered; Workspace still uses explicit file snapshots and restore.
|
|
464
|
+
|
|
465
|
+
|
|
466
|
+
## Continent-constrained rentals
|
|
467
|
+
|
|
468
|
+
Check anonymous `GET /v1/public/rental-regions` (MCP `list_rental_regions`) first. This staged capability is available only when its response says `enabled: true`. Select one of `asia`, `europe`, `north_america`, `oceania`, `south_america`, `africa`; country and datacenter selection are not supported. With no qualified supply, do not infer a region from the unfiltered legacy catalogue or the Agent's IP.
|
|
469
|
+
|
|
470
|
+
For a rental, pass the same `continent` to `estimate_cost` / `POST /v1/gpu/billing-quote`, then obtain explicit approval and pass it with the exact `billing_quote_id` and `billing_accepted: true` to `POST /v1/gpu/instances`. The stdio client's `create_instance` carries the approved continent automatically. Changes or missing continent bindings require a new quote. Minimum billing periods are unchanged; there is no automatic cross-continent fallback.
|
|
471
|
+
|
|
472
|
+
The generic `POST /v1/quotes`, Jobs and batches do not yet accept a hard continent constraint. Do not drop that constraint or substitute an unconstrained Job. Dynamic aggregate pricing remains an internal calculation module pending qualified supplier cost feeds and end-to-end billing activation; these endpoints do not promise an active global market.
|
|
473
|
+
### Detailed GPU configurations
|
|
474
|
+
|
|
475
|
+
`list_gpus` preserves the REST `/v1/gpu/offers` configuration data. `usd_per_gpu_hour` is a starting per-card rate; each `configurations[].hourlyPrice` is the **whole instance** price for `gpuCount` cards. Each entry includes per-card VRAM, CPU/RAM, system/local disk, interconnect, continent, current availability, billing minimum/increment in seconds and observation time in Unix milliseconds where supplied. Missing fields mean unknown.
|
|
476
|
+
|
|
477
|
+
`inventory_count_exact: false` means the source reports configuration availability, not a count of machines. Do not add overlapping 1/2/4/8-card alternatives or treat them as reserved stock. A catalog entry can be unavailable while retained for discovery. `estimate_cost` for the chosen card count remains required; GPU catalog membership does not imply Job or template compatibility.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cloudgpu-mcp",
|
|
3
|
-
"version": "0.16.
|
|
3
|
+
"version": "0.16.4",
|
|
4
4
|
"mcpName": "io.github.cloudgpu-app/cloudgpu-mcp",
|
|
5
5
|
"description": "MCP server and command-line tool for cloudgpu.app: let Claude Code, Cursor, Cline, opencode, goose and other MCP clients (or you, from a terminal) rent a GPU with explicit billing quotes, run a job, fetch the results and shut it down, with spending limits the platform enforces.",
|
|
6
6
|
"type": "module",
|
package/skills/cloudgpu/SKILL.md
CHANGED
|
@@ -97,3 +97,7 @@ In a configured MCP client, call `connect_account`, show the owner its link, the
|
|
|
97
97
|
## Several steps on one allocation
|
|
98
98
|
|
|
99
99
|
If installed, `prepare_task_pipeline` prepares up to eight reviewed sequential commands for one Job, or for `run_command` on an approved existing rental. It creates nothing. Commands share the filesystem and GPU but use separate shells; they do not share exported shell variables or a resident model process. Failure stops later steps. Python 3, bash and prepared dependencies are required. Review the returned command, obtain a compatible quote and explicit total budget/deadline approval, then submit one Job with a stable idempotency key. Preserve the original request on a lost response. The fingerprint is informational, not approval. Optional collection saves only pipeline-summary.json, never arbitrary results or logs; approve actual result persistence separately. Existing user instance limits and lifecycle remain unchanged.
|
|
100
|
+
|
|
101
|
+
## Regional discovery
|
|
102
|
+
|
|
103
|
+
Use `list_regional_offers` for recent native regional observations and independent price evidence. Ask for the human owner's country only when useful; do not infer it from the Agent server IP. Respect unknown/expired facts and shared pools. These are planning observations, not reservations, region-bound quotes or verified multi-card allocations. Exact-region execution and dynamic regional retail are not enabled in this release. If the task has a hard location requirement, explain the unsupported capability and do not submit an ordinary rental or Job in its place. Existing R2 Workspace is explicit file save/restore, not a mounted volume.
|
package/src/api.js
CHANGED
|
@@ -111,6 +111,19 @@ export class CloudGpuApi {
|
|
|
111
111
|
if (body.model_references?.length) return this.createModelJob(body,idempotencyKey);
|
|
112
112
|
return this.request("POST", "/v1/jobs", body, { idempotencyKey });
|
|
113
113
|
}
|
|
114
|
+
async createServerJobBatch(body,idempotencyKey) {
|
|
115
|
+
if(!idempotencyKey)throw new Error("Server batch requires a stable idempotency key");
|
|
116
|
+
const readiness=await this.request("GET","/v1/public/agent-self-check",undefined,{noAuth:true});
|
|
117
|
+
if(readiness.durable_batch?.enabled!==true)throw new ApiError(503,"durable_batch_unavailable","Durable batch is unavailable; no client-side submission fallback was attempted.");
|
|
118
|
+
if(body.jobs.some(j=>j.outputs||j.model_references?.length)){
|
|
119
|
+
const caps=await this.request("GET","/v1/public/compute-capabilities",undefined,{noAuth:true});
|
|
120
|
+
if(body.jobs.some(j=>j.outputs)&&(caps.automatic_output_collection!==true||caps.storage!==true))throw new ApiError(503,"outputs_unavailable","Output persistence unavailable; no batch submitted.");
|
|
121
|
+
if(body.jobs.some(j=>j.model_references?.length)&&caps.model_references!==true)throw new ApiError(503,"model_references_unavailable","Pinned model loading unavailable; no batch submitted.");
|
|
122
|
+
}
|
|
123
|
+
return this.request("POST","/v1/job-batches",body,{idempotencyKey});
|
|
124
|
+
}
|
|
125
|
+
serverJobBatch(id) {if(!/^[a-f0-9]{32}$/.test(id))throw Error("Invalid server batch id");return this.request("GET",`/v1/job-batches/${id}`);}
|
|
126
|
+
cancelServerJobBatch(id) {if(!/^[a-f0-9]{32}$/.test(id))throw Error("Invalid server batch id");return this.request("POST",`/v1/job-batches/${id}/cancel`,{});}
|
|
114
127
|
async createOutputJob(body,idempotencyKey) {
|
|
115
128
|
const caps=await this.request("GET","/v1/public/compute-capabilities",undefined,{noAuth:true});
|
|
116
129
|
if(caps.automatic_output_collection!==true || caps.storage!==true)
|
package/src/index.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import {registerFundingTools} from "./funding-tools.js";
|
|
3
3
|
import {registerAgentReadinessTools} from "./agent-readiness.js";
|
|
4
|
+
import {registerRegionalOfferTools,CONTINENTS} from "./regional-offers.js";
|
|
5
|
+
import {useStrictToolInputs} from "./strict-tools.js";
|
|
4
6
|
import {rentalBilling} from "./rental-billing.js";
|
|
5
7
|
import {registerComputePlanningTools} from './compute-planning.js';
|
|
6
8
|
import {registerTaskPipelineTools} from './task-pipelines.js';
|
|
@@ -40,7 +42,7 @@ import {
|
|
|
40
42
|
shq,
|
|
41
43
|
} from "./guards.js";
|
|
42
44
|
|
|
43
|
-
const VERSION = "0.16.
|
|
45
|
+
const VERSION = "0.16.4";
|
|
44
46
|
const HERE = path.dirname(fileURLToPath(import.meta.url));
|
|
45
47
|
const RULES = fs.readFileSync(path.join(HERE, "..", "rules", "cloudgpu.md"), "utf8");
|
|
46
48
|
|
|
@@ -66,8 +68,10 @@ const quotes = new Quotes();
|
|
|
66
68
|
const session = new Map();
|
|
67
69
|
|
|
68
70
|
const INSTRUCTIONS = `CloudGPU (cloudgpu.app) provides GPU compute scheduling for AI agents from a prepaid balance. Billing is source-specific: per-minute or minimum one hour with each started hour charged in full. Never infer the period from an hourly price label.
|
|
71
|
+
Regional discovery: list_regional_offers reads native observations with separate stock/price ages and explicit unknowns. Supply the owner country explicitly, never the Agent egress IP. Native observations are planning only. For continent-constrained rentals, first call list_rental_regions and require enabled=true, then estimate_cost with the chosen continent. create_instance carries that approved constraint. Countries/datacenters and continent-constrained Jobs are not supported; never drop a hard constraint. Dynamic aggregate retail is not activated.
|
|
69
72
|
Planning: compare_compute_costs compares billed GPU cost for explicit candidates and duration; it is not a benchmark or creation approval. Check existing list_instances before renting: multiple approved commands can use the same running rental within its existing budget, time and idle limits. Separate run_job calls each provision and release independently; prepare_job_rerun does not reuse a live GPU. Never extend limits or keep idle GPUs merely to consume prepaid time.
|
|
70
|
-
|
|
73
|
+
Server batches: prepare_job_batch also prepares the exact manifest for run_server_job_batch. The new tool atomically enqueues on the server, persists across client/server restarts, and requires an aggregate cap and individually approved billing. Use get_server_job_batch/cancel_server_job_batch; never substitute client partial submission when unavailable. No automatic failed-command retries.
|
|
74
|
+
Legacy client batches: prepare_job_batch reviews up to eight individually quoted Jobs and their combined GPU budget. run_job_batch requires an exact approved plan hash; partial submission is possible. Retain the manifest and stable batch key to reconcile lost responses. No automatic execution retries; get_job_batch never proves independent supplier release. Storage charges are additional to GPU caps.
|
|
71
75
|
Shared allocation: prepare_task_pipeline prepares 1–8 reviewed sequential commands as a single Job draft, or for an approved existing rental. It creates nothing. Independent run_job calls do not share a GPU. Pipeline summary persistence is explicit and does not save arbitrary results or authorize storage charges.
|
|
72
76
|
Task recipes: list_task_templates and prepare_task_template return local read-only drafts, never a paid submission. Check prerequisites, quote and obtain explicit approval before run_job. Prefer local CPU processing when a GPU is unnecessary.
|
|
73
77
|
Workflow: get_account and list_gpus -> estimate_cost -> show the quote to the user and get an explicit yes -> create_instance -> get_status until running -> upload -> run_command (background for long jobs) -> tail_logs -> download results -> stop_instance -> report the actual cost.
|
|
@@ -77,8 +81,10 @@ No API key yet? connect_account gives the user a link to approve this assistant
|
|
|
77
81
|
The same API key also works for the OpenAI-compatible model API at ${cfg.baseUrl}/v1 (see list_models).`;
|
|
78
82
|
|
|
79
83
|
const server = new McpServer({ name: "cloudgpu", version: VERSION }, { instructions: INSTRUCTIONS });
|
|
84
|
+
useStrictToolInputs(server);
|
|
80
85
|
registerFundingTools(server,{api,wrap,ok,readOnly:cfg.readOnly});
|
|
81
86
|
registerAgentReadinessTools(server,{api,wrap,ok});
|
|
87
|
+
registerRegionalOfferTools(server,{api,wrap,ok});
|
|
82
88
|
registerTaskTemplateTools(server, {wrap, ok});
|
|
83
89
|
registerComputePlanningTools(server,{api,wrap,ok});
|
|
84
90
|
registerTaskPipelineTools(server,{cfg,wrap,ok});
|
|
@@ -179,7 +185,7 @@ server.registerTool(
|
|
|
179
185
|
{
|
|
180
186
|
title: "List GPUs",
|
|
181
187
|
description:
|
|
182
|
-
"GPU
|
|
188
|
+
"GPU catalog with per-card VRAM, live starting price in USD, availability, and native configurations (GPU count, CPU, RAM, disks, region, interconnect and whole-instance price) when provided. Unavailable models remain discoverable. Request an exact quote before renting.",
|
|
183
189
|
inputSchema: {
|
|
184
190
|
min_vram_gb: z.number().optional().describe("Only GPUs with at least this much VRAM per card"),
|
|
185
191
|
gpu_model: z.string().optional().describe("Filter by name, e.g. 4090, A100, H20"),
|
|
@@ -200,8 +206,10 @@ server.registerTool(
|
|
|
200
206
|
usd_per_gpu_hour: r.hourly_usd,
|
|
201
207
|
available: r.available,
|
|
202
208
|
min_gpu_count: r.min_gpu_count,
|
|
209
|
+
inventory_count_exact: r.inventory_count_exact ?? null,
|
|
210
|
+
configurations: r.configurations ?? [],
|
|
203
211
|
})),
|
|
204
|
-
note: "Billing periods vary by allocated source
|
|
212
|
+
note: "usd_per_gpu_hour is a starting per-card rate; configurations[].hourlyPrice is the total for that single-host GPU count, not a per-card rate. Configuration availability is not a fleet count or reservation. Billing periods vary by allocated source; call estimate_cost for the selected count and current minimum charge, billing increment and exact total. Availability can change before you rent. Configuration fields are absent when the source has not supplied verified metadata.",
|
|
205
213
|
});
|
|
206
214
|
}),
|
|
207
215
|
);
|
|
@@ -225,6 +233,7 @@ server.registerTool(
|
|
|
225
233
|
description:
|
|
226
234
|
"Live price and estimated cost for a GPU, plus your balance after it. Returns a quote_id that create_instance needs. Show the quote to the user and get an explicit yes before renting.",
|
|
227
235
|
inputSchema: {
|
|
236
|
+
continent: z.enum(CONTINENTS).optional().describe("Hard continent constraint, from list_rental_regions"),
|
|
228
237
|
gpu_model: z.string().describe("GPU model exactly as list_gpus returns it"),
|
|
229
238
|
gpu_count: z.number().int().min(1).max(8).default(1),
|
|
230
239
|
hours: z.number().positive().describe("Expected run time in hours"),
|
|
@@ -232,7 +241,7 @@ server.registerTool(
|
|
|
232
241
|
},
|
|
233
242
|
annotations: { readOnlyHint: true, openWorldHint: true },
|
|
234
243
|
},
|
|
235
|
-
wrap(async ({ gpu_model, gpu_count = 1, hours, template }) => {
|
|
244
|
+
wrap(async ({ gpu_model, gpu_count = 1, hours, template, continent }) => {
|
|
236
245
|
const [offers, account] = await Promise.all([api.offers(), api.account().catch(() => null)]);
|
|
237
246
|
const offer = offers.find((o) => String(o.gpu_model).toLowerCase() === gpu_model.toLowerCase());
|
|
238
247
|
if (!offer) {
|
|
@@ -241,7 +250,8 @@ server.registerTool(
|
|
|
241
250
|
if (gpu_count < (offer.min_gpu_count || 1)) {
|
|
242
251
|
return fail(`${offer.gpu_model} is rented in groups of at least ${offer.min_gpu_count} GPUs.`);
|
|
243
252
|
}
|
|
244
|
-
const billing = await api.rentalBillingQuote({gpuModel:offer.gpu_model,gpuCount:gpu_count,...(template?{templateId:template}:{})});
|
|
253
|
+
const billing = await api.rentalBillingQuote({gpuModel:offer.gpu_model,gpuCount:gpu_count,...(continent?{continent}:{}),...(template?{templateId:template}:{})});
|
|
254
|
+
if(continent&&billing.continent!==continent)return fail("The billing quote did not bind the requested continent. No rental was started.");
|
|
245
255
|
const {hourly,increment,estimate}=rentalBilling(billing,hours);
|
|
246
256
|
const balance = account ? Number(account.balance_usd) : null;
|
|
247
257
|
const warnings = [];
|
|
@@ -252,9 +262,10 @@ server.registerTool(
|
|
|
252
262
|
`Balance $${balance} does not cover the estimate plus a 10% buffer. When the balance runs out the instance is destroyed and its disk erased. Call request_top_up and wait_for_funds; obtain approval before continuing.`,
|
|
253
263
|
);
|
|
254
264
|
}
|
|
255
|
-
const quote_id = quotes.put({ gpu_model: offer.gpu_model, gpu_count, template, hourly, hours, estimate, billingQuoteId:billing.billingQuoteId, billingExpiresAt:billing.expiresAt, minimumChargeUsd:Number(billing.minimumChargeUsd), billingIncrementSeconds:increment });
|
|
265
|
+
const quote_id = quotes.put({ continent, gpu_model: offer.gpu_model, gpu_count, template, hourly, hours, estimate, billingQuoteId:billing.billingQuoteId, billingExpiresAt:billing.expiresAt, minimumChargeUsd:Number(billing.minimumChargeUsd), billingIncrementSeconds:increment });
|
|
256
266
|
return ok({
|
|
257
267
|
quote_id,
|
|
268
|
+
continent:continent||null,
|
|
258
269
|
gpu_model: offer.gpu_model,
|
|
259
270
|
gpu_count,
|
|
260
271
|
template: template || null,
|
|
@@ -493,6 +504,7 @@ if (!cfg.readOnly) {
|
|
|
493
504
|
);
|
|
494
505
|
}
|
|
495
506
|
const body = {
|
|
507
|
+
...(quote.continent?{continent:quote.continent}:{}),
|
|
496
508
|
billing_quote_id:quote.billingQuoteId,
|
|
497
509
|
billing_accepted:true,
|
|
498
510
|
gpu_model: quote.gpu_model,
|
|
@@ -539,7 +551,7 @@ if (!cfg.readOnly) {
|
|
|
539
551
|
inputSchema: jobInputShape(cfg),
|
|
540
552
|
annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
|
|
541
553
|
},
|
|
542
|
-
wrap(async ({ command, gpu_model, template, gpu_count = 1, disk_gb, workspace_version_id, model_references, outputs, quote_id, max_spend_usd, max_hours, user_confirmed, idempotency_key }) => {
|
|
554
|
+
wrap(async ({ command, gpu_model, template, gpu_count = 1, disk_gb, workspace_version_id, model_references, outputs, quote_id, billing_quote_id, billing_accepted, max_spend_usd, max_hours, user_confirmed, idempotency_key }) => {
|
|
543
555
|
if (user_confirmed !== true) {
|
|
544
556
|
return fail("Not started: tell the user the GPU, budget and time limit, wait for an explicit yes, then call again with user_confirmed=true.");
|
|
545
557
|
}
|
|
@@ -561,6 +573,7 @@ if (!cfg.readOnly) {
|
|
|
561
573
|
if (outputs) body.outputs = outputs;
|
|
562
574
|
if (model_references?.length) body.model_references = model_references;
|
|
563
575
|
if (quote_id) body.quote_id = quote_id;
|
|
576
|
+
if (billing_quote_id) {if(billing_accepted!==true)return fail("Not started: accept the source-specific minimum charge and billing period first.");body.billing_quote_id=billing_quote_id;body.billing_accepted=true;}
|
|
564
577
|
const job = await api.createJob(body, key);
|
|
565
578
|
return ok({
|
|
566
579
|
...job,
|
package/src/job-batches.js
CHANGED
|
@@ -68,12 +68,32 @@ export async function getJobBatch(api,ids){
|
|
|
68
68
|
for(const id of ids){try{const j=await api.job(id);if(j.id!==id||!['queued','provisioning','running','stopping','needs_attention','succeeded','failed','cancelled'].includes(j.status))throw Error('Unrecognized Job response');items.push({job_id:id,status:j.status,cost_usd:j.cost_usd??null,cost_status:j.cost_status??null,automatic_retry_allowed:false,release_risk:j.status==='needs_attention'||j.status==='stopping'});}catch{items.push({job_id:id,status:'unavailable',automatic_retry_allowed:false,release_risk:true});}}
|
|
69
69
|
return {items,all_terminal:items.every(j=>['succeeded','failed','cancelled'].includes(j.status)),requires_reconciliation:items.some(j=>j.release_risk),automatic_retry_allowed:false,note:'Status and costs come from the existing Job API. Terminal state is not an independent supplier audit; stopping, needs_attention or unavailable must never trigger a new GPU.'};
|
|
70
70
|
}
|
|
71
|
+
export async function submitServerJobBatch(api,raw,cfg){
|
|
72
|
+
if(api instanceof CloudGpuApi)api=new CloudGpuApi({apiKey:api.apiKey,baseUrl:api.baseUrl,fetchImpl:api.fetch,userAgent:api.userAgent});
|
|
73
|
+
const {approved_plan_sha256,user_confirmed,...input}=raw;
|
|
74
|
+
if(user_confirmed!==true)throw Error('Approve every command, billing period and the aggregate budget first');
|
|
75
|
+
const plan=prepareJobBatch(input,cfg);
|
|
76
|
+
if(approved_plan_sha256!==plan.plan_sha256)throw Error('Approved batch manifest changed');
|
|
77
|
+
const quoteIds=new Set();
|
|
78
|
+
for(const item of plan.items)if(item.body.billing_quote_id){
|
|
79
|
+
if(item.body.billing_accepted!==true)throw Error('Accept the exact source billing period and minimum first');
|
|
80
|
+
if(quoteIds.has(item.body.billing_quote_id))throw Error('Each hourly allocation requires its own accepted billing quote');quoteIds.add(item.body.billing_quote_id);
|
|
81
|
+
}
|
|
82
|
+
const result=await api.createServerJobBatch({total_budget_usd:plan.total_budget_usd,jobs:plan.items.map(i=>i.body)},'server-batch:'+plan.batch_key);
|
|
83
|
+
if(!/^[a-f0-9]{32}$/.test(result?.batch_id)||result.durable!==true||!Array.isArray(result.jobs)||result.jobs.length!==plan.items.length||result.jobs.some(j=>!/^job_[a-f0-9]{32}$/.test(j.id)))
|
|
84
|
+
throw Error('Unrecognized batch receipt; reconcile with the identical manifest/key before retrying');
|
|
85
|
+
return {...result,batch_key:plan.batch_key,plan_sha256:plan.plan_sha256,atomic_enqueue:true,automatic_command_retries:false,next:'Use get_server_job_batch. Never replace an uncertain or failed task automatically; the same approved key replays this batch.'};
|
|
86
|
+
}
|
|
87
|
+
|
|
71
88
|
export function registerBatchTools(server,{api,cfg,wrap,ok}){
|
|
72
89
|
const input=schema(cfg);
|
|
73
90
|
const receipts=()=>new BatchReceipts({apiKey:'apiKey' in api?api.apiKey:cfg.apiKey,baseUrl:api.baseUrl||cfg.baseUrl});
|
|
74
91
|
server.registerTool('get_job_batch_receipt',{title:'Read a private local batch receipt',description:'Read only saved accepted Job IDs and uncertain submission intents for the original batch key, API key and endpoint. No API request or GPU creation. Local state is historical, not live release evidence; a missing entry does not prove non-creation. Commands, tokens and signed URLs are never stored.',inputSchema:{batch_key:z.string().min(1).max(80).regex(/^[A-Za-z0-9_-]+$/)},annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:false}},wrap(async({batch_key})=>ok(await receipts().snapshot(batch_key))));
|
|
75
92
|
server.registerTool('prepare_job_batch',{title:'Review a bounded Job batch',description:'Local, read-only preparation for up to eight Jobs with fresh per-Job quotes and one aggregate cap. No API requests, reservations, installations or automatic execution retries. Retain the immutable plan hash and batch key.',inputSchema:input.shape,annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:false}},wrap(async p=>ok(prepareJobBatch(p,cfg))));
|
|
76
93
|
server.registerTool('get_job_batch',{title:'Inspect a Job batch',description:'Read-only status and cost summary for explicit Job IDs. Does not retry, cancel, create or claim independent supplier release verification.',inputSchema:{job_ids:z.array(z.string().regex(/^job_[a-f0-9]{32}$/)).min(1).max(8)},annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:true}},wrap(async({job_ids})=>ok(await getJobBatch(api,job_ids))));
|
|
94
|
+
server.registerTool('get_server_job_batch',{title:'Read a durable server batch',description:'Read persisted child Job states and costs after either client or server restarts. Does not create or retry resources.',inputSchema:{batch_id:z.string().regex(/^[a-f0-9]{32}$/)},annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:true}},wrap(async({batch_id})=>ok(await api.serverJobBatch(batch_id))));
|
|
77
95
|
if(cfg.readOnly)return;
|
|
96
|
+
server.registerTool('run_server_job_batch',{title:'Atomically enqueue an approved server batch',description:'Paid. Use the exact reviewed prepare_job_batch manifest/hash. Enqueue is atomic and persists on the server; each Job reserves its own budget and waits for account/key concurrency. No automatic command retries and no partial client-side fallback. Whole-hour Jobs require a separate accepted current billing quote per allocation.',inputSchema:{...input.shape,approved_plan_sha256:z.string().regex(/^[a-f0-9]{64}$/),user_confirmed:z.boolean()},annotations:{readOnlyHint:false,destructiveHint:true,idempotentHint:true,openWorldHint:true}},wrap(async p=>ok(await submitServerJobBatch(api,p,cfg))));
|
|
97
|
+
server.registerTool('cancel_server_job_batch',{title:'Cancel a server batch',description:'Cancel queued children without starting a GPU; request safe shutdown of active children. Preserve outputs first. Previously started whole-hour charges remain payable.',inputSchema:{batch_id:z.string().regex(/^[a-f0-9]{32}$/),user_confirmed:z.boolean()},annotations:{readOnlyHint:false,destructiveHint:true,idempotentHint:true,openWorldHint:true}},wrap(async({batch_id,user_confirmed})=>{if(user_confirmed!==true)throw Error('Confirm output preservation and cancellation first');return ok(await api.cancelServerJobBatch(batch_id));}));
|
|
78
98
|
server.registerTool('run_job_batch',{title:'Submit an approved bounded Job batch',description:'Paid: submit an explicitly approved immutable manifest using existing durable Jobs, each with a quote, budget and deadline. Aggregate worst-case budget is capped. Partial success is possible. On lost responses replay the IDENTICAL manifest/key; never create replacement GPUs or retry failed execution automatically. Persist the returned receipt. No transaction rollback or independent batch scheduler.',inputSchema:{...input.shape,approved_plan_sha256:z.string().regex(/^[a-f0-9]{64}$/),user_confirmed:z.boolean()},annotations:{readOnlyHint:false,destructiveHint:true,idempotentHint:true,openWorldHint:true}},wrap(async p=>ok(await submitJobBatch(api,p,cfg,receipts()))));
|
|
79
99
|
}
|
package/src/job-input.js
CHANGED
|
@@ -14,6 +14,8 @@ export function jobInputShape(cfg){return {
|
|
|
14
14
|
accept_storage_charges: z.boolean().optional(),
|
|
15
15
|
}).strict().optional().describe("Explicit relative output files under $CLOUDGPU_OUTPUT_DIR; no globs, symlinks, hidden or credential files. Default total limit 10 MiB, maximum 100 MiB. Only set accept_storage_charges=true after the user agrees to existing paid storage terms. Inspect output_collection after completion; the GPU is released even if saving fails."),
|
|
16
16
|
quote_id: z.string().optional().describe("Server quote from quote_compute, starting quote_; binds configuration and checks price at submission"),
|
|
17
|
+
billing_quote_id: z.string().regex(/^[a-f0-9-]{36}$/).optional().describe("Accepted source-specific billing quote from estimate_cost; expires after five minutes. Required for whole-hour sources."),
|
|
18
|
+
billing_accepted: z.boolean().optional().describe("true only after the user accepts the quoted minimum and billing period; budget must cover that minimum"),
|
|
17
19
|
max_spend_usd: z.number().positive().describe(`Budget for this job in USD (at most ${cfg.maxSpend})`),
|
|
18
20
|
max_hours: z.number().positive().describe(`Hard time limit in hours (at most ${cfg.maxHours})`),
|
|
19
21
|
user_confirmed: z.boolean().describe("true only if the user explicitly approved the GPU, budget and time limit"),
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import {z} from "zod";
|
|
2
|
+
|
|
3
|
+
/** Discovery only; no implicit owner geolocation, quote, procurement or data migration. */
|
|
4
|
+
export const CONTINENTS=["asia","europe","north_america","oceania","south_america","africa"];
|
|
5
|
+
export function registerRegionalOfferTools(server,{api,wrap,ok}){
|
|
6
|
+
server.registerTool("list_rental_regions",{
|
|
7
|
+
title:"List rentable GPUs by continent",
|
|
8
|
+
description:"Read-only qualified continent catalog shared with the rental UI. Use enabled and inventory/capability/count constraints. Request estimate_cost with the same continent before renting. Countries and individual datacenters are not selectable. Empty inventory does not authorize renting in another continent.",
|
|
9
|
+
inputSchema:{continent:z.enum(CONTINENTS).optional()},
|
|
10
|
+
annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:true},
|
|
11
|
+
},wrap(async ({continent})=>ok(await api.request("GET","/v1/public/rental-regions"+(continent?"?continent="+encodeURIComponent(continent):""),undefined,{noAuth:true}))));
|
|
12
|
+
|
|
13
|
+
server.registerTool("list_regional_offers",{
|
|
14
|
+
title:"Inspect regional compute observations",
|
|
15
|
+
description:"Anonymous, read-only native regional stock observations, independent price evidence ages, billing references and known/unknown limits. Supply the human owner's country explicitly; the Agent server IP is not its owner's location. Counts are not reservations or verified single-host multi-GPU allocations. Published SKU references are not region-bound executable quotes; dynamic regional pricing and exact-region execution are not activated. Unsupported, stale or failed observations do not prove global stockout. Follow has_more/next_after_id; pagination is a live view, not a frozen snapshot.",
|
|
16
|
+
inputSchema:{user_country:z.string().regex(/^[A-Za-z]{2}$/).optional(),country_code:z.string().regex(/^[A-Za-z]{2}$/).optional(),gpu_model:z.string().max(100).optional(),gpu_count:z.number().int().min(1).max(8).default(1),include_unavailable:z.boolean().default(false),limit:z.number().int().min(1).max(200).default(100),after_id:z.string().regex(/^offer_[a-f0-9]{32}$/).optional()},
|
|
17
|
+
annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:true},
|
|
18
|
+
},wrap(async input=>{
|
|
19
|
+
const query=new URLSearchParams();
|
|
20
|
+
for(const field of ["user_country","country_code","gpu_model","gpu_count","include_unavailable","limit","after_id"])
|
|
21
|
+
if(input[field]!==undefined)query.set(field,String(input[field]));
|
|
22
|
+
const encoded=query.toString();
|
|
23
|
+
return ok(await api.request("GET","/v1/public/compute-offers"+(encoded?"?"+encoded:""),undefined,{noAuth:true}));
|
|
24
|
+
}));
|
|
25
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import {z} from "zod";
|
|
2
|
+
|
|
3
|
+
/** JSON tool contracts already advertise no extra fields; enforce that instead of stripping constraints. */
|
|
4
|
+
export function useStrictToolInputs(server){
|
|
5
|
+
const register=server.registerTool.bind(server);
|
|
6
|
+
server.registerTool=(name,config,...rest)=>{
|
|
7
|
+
if(config.inputSchema){
|
|
8
|
+
const schema=typeof config.inputSchema.safeParse==="function"?config.inputSchema:z.object(config.inputSchema);
|
|
9
|
+
config={...config,inputSchema:typeof schema.strict==="function"?schema.strict():schema};
|
|
10
|
+
}
|
|
11
|
+
return register(name,config,...rest);
|
|
12
|
+
};
|
|
13
|
+
}
|