cloudgpu-mcp 0.11.0 → 0.12.1
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 +17 -0
- package/package.json +1 -1
- package/src/batch-receipts.js +99 -0
- package/src/index.js +1 -1
- package/src/job-batches.js +20 -6
package/README.md
CHANGED
|
@@ -337,3 +337,20 @@ Both recipes require `persist_results=true` and an immutable Workspace. They do
|
|
|
337
337
|
5. Poll `get_job_batch` with the explicit Job IDs. `stopping`, `needs_attention`, unknown or unavailable state requires reconciliation. Do not treat a failed status or a destroy request as independent supplier release evidence. Cancel individual Jobs only through the existing `cancel_job` tool when authorized.
|
|
338
338
|
|
|
339
339
|
There are **no automatic failed-execution retries**. Each submitted Job survives a client disconnect using the existing durable backend queue. Unsubmitted members do not continue in the background if the MCP process exits. Fresh-attempt retry automation and a durable batch-level coordinator are not included. No warm GPU pool or new infrastructure is required.
|
|
340
|
+
|
|
341
|
+
|
|
342
|
+
### Private local batch receipts (0.12.0)
|
|
343
|
+
|
|
344
|
+
`run_job_batch` now journals submission intents and accepted Job IDs under `CLOUDGPU_CONFIG_DIR` (default `~/.config/cloudgpu`), in a private `batch-receipts-v1` directory. `get_job_batch_receipt({batch_key})` reads this local metadata without an API request. It records no commands, complete manifests, API keys, model URLs or signed links. Keep your original reviewed manifest separately.
|
|
345
|
+
|
|
346
|
+
After a client restart, reconnect with the **same scoped API key and endpoint**. Inspect the receipt, then use `get_job_batch` for live status. Replaying the exact approved manifest queries known accepted Jobs; only an uncertain acknowledgement is reconciled by the original create request/key. Unavailable, `stopping` or `needs_attention` stops progress. A local historical status is not a current supplier release audit. A missing receipt (another device/key, an older client, or lost files) is never proof that no GPU exists.
|
|
347
|
+
|
|
348
|
+
The local store must support private file permissions, no-follow file opens and atomic hard links. An unsafe/unavailable store refuses new batch submissions; a write failure after acceptance returns the known Job ID and stops later members. Do not silently switch to a new key or discard uncertain records. New entries are refused once 1,024 batch directories are observed for a key/endpoint; this local housekeeping check is not a concurrent server quota. Archive **verified terminal** receipts explicitly. Original single-Job tools remain available.
|
|
349
|
+
|
|
350
|
+
This is client-local receipt durability, not a server-side batch coordinator. Unsubmitted members do not run while the client is closed. No automatic retry of failed execution, new-attempt spending, refund or cancellation is added. Preparing a plan still creates no GPU and requires no account; paid submission still requires exact plan approval, fresh quotes and existing GPU/storage limits. Scopes on different keys or endpoints are separate; inspect existing resources before intentionally changing either.
|
|
351
|
+
|
|
352
|
+
Keep the exact original manifest outside the receipt store. Expired quotes for unsubmitted members may require reconciliation followed by a newly reviewed plan for the remaining work; do not overwrite the old ledger or regenerate keys merely to bypass expiry. Terminal status without final cost evidence also stops a journaled resume.
|
|
353
|
+
|
|
354
|
+
One in-flight batch retains its original API credential and endpoint even if another tool connects a different account concurrently. `not_submitted` in a returned call receipt means unvisited **in that invocation only**; those entries may have accepted Jobs from an earlier call. Inspect the saved receipt and live Job IDs before deciding what remains.
|
|
355
|
+
|
|
356
|
+
Use 0.12.1 or newer for directory-entry durability: newly created config/receipt directories and their parent entries are synced before paid submission. A parent-directory sync failure refuses new batch work. Existing 0.12.0 receipt records remain readable; preserve their IDs and original keys rather than deleting them. Process-exit tests alone do not constitute physical power-loss testing.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cloudgpu-mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.12.1",
|
|
4
4
|
"mcpName": "io.github.mrhy7176/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 per minute, run a job, fetch the results and shut it down, with spending limits the platform enforces.",
|
|
6
6
|
"type": "module",
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
// 本地受理回执:只保存哈希、Job ID与状态,不保存命令、凭证、签名URL或完整任务清单。
|
|
2
|
+
import fs from 'node:fs/promises';
|
|
3
|
+
import {constants} from 'node:fs';
|
|
4
|
+
import path from 'node:path';
|
|
5
|
+
import {createHash,randomBytes} from 'node:crypto';
|
|
6
|
+
import {z} from 'zod';
|
|
7
|
+
import {configDir} from './credentials.js';
|
|
8
|
+
const sha=s=>createHash('sha256').update(s).digest('hex');
|
|
9
|
+
const states=z.enum(['queued','provisioning','running','stopping','needs_attention','succeeded','failed','cancelled']);
|
|
10
|
+
const key=z.string().regex(/^batch_[a-f0-9]{64}$/);
|
|
11
|
+
const meta=z.object({version:z.literal(1),plan_sha256:z.string().regex(/^[a-f0-9]{64}$/),total_budget_usd:z.number().positive(),item_keys:z.array(key).min(1).max(8)}).strict();
|
|
12
|
+
const intent=z.object({version:z.literal(1),index:z.number().int().min(0).max(7),idempotency_key:key}).strict();
|
|
13
|
+
const accepted=intent.extend({job_id:z.string().regex(/^job_[a-f0-9]{32}$/),status_at_acceptance:states}).strict();
|
|
14
|
+
const safeError=()=>new Error('Local batch receipt is unavailable or inconsistent. No replacement key or GPU may be created; retain the original manifest and reconcile existing Jobs.');
|
|
15
|
+
async function syncDirectory(p){
|
|
16
|
+
const f=await fs.open(p,constants.O_RDONLY|constants.O_DIRECTORY|constants.O_NOFOLLOW);
|
|
17
|
+
try{await f.sync();}finally{await f.close();}
|
|
18
|
+
}
|
|
19
|
+
// 目录项属于父目录;先同步父目录,才能在付费提交前确认新树已持久化。
|
|
20
|
+
async function directory(p,create=false){
|
|
21
|
+
try{
|
|
22
|
+
const s=await fs.lstat(p);if(s.isSymbolicLink()||!s.isDirectory()||(s.mode&0o077)!==0||(process.getuid&&s.uid!==process.getuid()))throw safeError();
|
|
23
|
+
}catch(e){
|
|
24
|
+
if(e.code!=='ENOENT'||!create)throw e;
|
|
25
|
+
await fs.mkdir(p,{mode:0o700}).catch(e=>{if(e.code!=='EEXIST')throw e;});
|
|
26
|
+
await directory(p,false);
|
|
27
|
+
}
|
|
28
|
+
if(create)await syncDirectory(path.dirname(p));
|
|
29
|
+
}
|
|
30
|
+
async function configRoot(p){
|
|
31
|
+
try{if(!(await fs.stat(p)).isDirectory())throw safeError();}
|
|
32
|
+
catch(e){
|
|
33
|
+
if(e.code!=='ENOENT')throw e;
|
|
34
|
+
const parent=path.dirname(p);if(parent===p)throw safeError();await configRoot(parent);
|
|
35
|
+
await fs.mkdir(p,{mode:0o700}).catch(e=>{if(e.code!=='EEXIST')throw e;});
|
|
36
|
+
}
|
|
37
|
+
await syncDirectory(path.dirname(p));
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
async function read(p,schema){
|
|
41
|
+
let f;try{f=await fs.open(p,constants.O_RDONLY|constants.O_NOFOLLOW);const s=await f.stat();if(!s.isFile()||s.size>8192||(s.mode&0o077)!==0||(process.getuid&&s.uid!==process.getuid()))throw safeError();return schema.parse(JSON.parse(await f.readFile('utf8')));}
|
|
42
|
+
catch(e){if(e.code==='ENOENT')return null;throw safeError();}finally{await f?.close();}
|
|
43
|
+
}
|
|
44
|
+
// 独立不可变文件避免进程退出或并发覆盖已受理ID。后端幂等仍是创建资源的最终防线。
|
|
45
|
+
async function put(p,value,schema,equal=(a,b)=>JSON.stringify(a)===JSON.stringify(b)){
|
|
46
|
+
schema.parse(value);
|
|
47
|
+
const tmp=p+'.tmp-'+randomBytes(12).toString('hex');let f;
|
|
48
|
+
try{
|
|
49
|
+
f=await fs.open(tmp,constants.O_WRONLY|constants.O_CREAT|constants.O_EXCL|constants.O_NOFOLLOW,0o600);
|
|
50
|
+
await f.writeFile(JSON.stringify(value)+'\n');await f.sync();await f.close();f=null;
|
|
51
|
+
try{await fs.link(tmp,p);}catch(e){if(e.code!=='EEXIST')throw e;const old=await read(p,schema);if(!equal(old,value))throw safeError();}
|
|
52
|
+
const d=await fs.open(path.dirname(p),constants.O_RDONLY|constants.O_DIRECTORY|constants.O_NOFOLLOW);try{await d.sync();}finally{await d.close();}
|
|
53
|
+
}catch{throw safeError();}finally{await f?.close();await fs.unlink(tmp).catch(()=>{});}
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
export class BatchReceipts{
|
|
57
|
+
constructor({apiKey,baseUrl,root=configDir(),maxBatches=1024}){this.apiKey=apiKey;this.root=root;this.scope=sha(String(baseUrl||'https://cloudgpu.app')+'\0'+String(apiKey||''));this.maxBatches=maxBatches;}
|
|
58
|
+
async locate(batchKey,create){
|
|
59
|
+
if(!this.apiKey)throw Error('Connect the original scoped account before reading or submitting a batch receipt. Never paste the key into chat.');
|
|
60
|
+
if(!/^[A-Za-z0-9_-]{1,80}$/.test(batchKey))throw Error('Invalid batch key');
|
|
61
|
+
// 配置目录由用户选择;回执树及下级目录必须为当前用户私有,拒绝符号链接。
|
|
62
|
+
if(create)await configRoot(path.resolve(this.root)).catch(()=>{throw safeError();});
|
|
63
|
+
const base=path.join(this.root,'batch-receipts-v1');
|
|
64
|
+
try{await directory(base,create);}catch(e){if(e.code==='ENOENT')return null;throw safeError();}
|
|
65
|
+
const scope=path.join(base,this.scope);
|
|
66
|
+
try{await directory(scope,create);}catch(e){if(e.code==='ENOENT')return null;throw safeError();}
|
|
67
|
+
const dir=path.join(scope,sha(batchKey));
|
|
68
|
+
try{await directory(dir,false);}catch(e){if(e.code!=='ENOENT')throw safeError();if(!create)return null;
|
|
69
|
+
if((await fs.readdir(scope).catch(()=>{throw safeError();})).length>=this.maxBatches)throw Error('Local batch receipt limit reached. Archive verified terminal receipts explicitly; do not discard uncertain receipts.');
|
|
70
|
+
await directory(dir,true);
|
|
71
|
+
}
|
|
72
|
+
return dir;
|
|
73
|
+
}
|
|
74
|
+
async bind(plan){
|
|
75
|
+
const dir=await this.locate(plan.batch_key,true);
|
|
76
|
+
const value={version:1,plan_sha256:plan.plan_sha256,total_budget_usd:plan.total_budget_usd,item_keys:plan.items.map(x=>x.idempotency_key)};
|
|
77
|
+
await put(path.join(dir,'plan.json'),value,meta);
|
|
78
|
+
return this.handle(dir,value);
|
|
79
|
+
}
|
|
80
|
+
handle(dir,value){return {
|
|
81
|
+
accepted:async index=>{const row=await read(path.join(dir,index+'.accepted.json'),accepted);if(row&&(row.index!==index||row.idempotency_key!==value.item_keys[index]))throw safeError();return row;},
|
|
82
|
+
intent:async item=>put(path.join(dir,item.index+'.intent.json'),{version:1,index:item.index,idempotency_key:item.idempotency_key},intent),
|
|
83
|
+
accept:async(item,job)=>{
|
|
84
|
+
const p=path.join(dir,item.index+'.accepted.json'),row={version:1,index:item.index,idempotency_key:item.idempotency_key,job_id:job.id,status_at_acceptance:job.status};
|
|
85
|
+
const prior=await read(p,accepted);if(prior){if(prior.job_id!==job.id||prior.idempotency_key!==item.idempotency_key)throw safeError();return;}
|
|
86
|
+
await put(p,row,accepted,(a,b)=>a?.job_id===b.job_id&&a?.idempotency_key===b.idempotency_key&&a?.index===b.index);
|
|
87
|
+
},
|
|
88
|
+
};}
|
|
89
|
+
async snapshot(batchKey){
|
|
90
|
+
const dir=await this.locate(batchKey,false);
|
|
91
|
+
if(!dir)return {found:false,items:[],note:'No local receipt was found. This does not prove that a GPU was never created; older clients or another key/device may hold the receipt.'};
|
|
92
|
+
const value=await read(path.join(dir,'plan.json'),meta);if(!value)throw safeError();const h=this.handle(dir,value),items=[];
|
|
93
|
+
for(let i=0;i<value.item_keys.length;i++){
|
|
94
|
+
const a=await h.accepted(i),n=await read(path.join(dir,i+'.intent.json'),intent);if(n&&(n.index!==i||n.idempotency_key!==value.item_keys[i]))throw safeError();
|
|
95
|
+
items.push({index:i,idempotency_key:value.item_keys[i],job_id:a?.job_id??null,local_state:a?'accepted':n?'submission_uncertain':'not_observed_locally',observed_status_at_acceptance:a?.status_at_acceptance??null});
|
|
96
|
+
}
|
|
97
|
+
return {found:true,plan_sha256:value.plan_sha256,total_budget_usd:value.total_budget_usd,items,live_status:false,execution_retries:0,note:'Private local metadata only, scoped to the original key and API endpoint. Query get_job_batch for live status. Resume only the identical approved manifest; no absent local entry proves non-creation. No automatic execution retry or durable server batch coordinator.'};
|
|
98
|
+
}
|
|
99
|
+
}
|
package/src/index.js
CHANGED
package/src/job-batches.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
// D17第一阶段:复用现有持久化Job队列。部分提交可恢复,不伪装成原子事务。
|
|
2
2
|
import {createHash} from 'node:crypto';
|
|
3
3
|
import {z} from 'zod';
|
|
4
|
+
import {CloudGpuApi} from './api.js';
|
|
5
|
+
import {BatchReceipts} from './batch-receipts.js';
|
|
4
6
|
import {jobInputShape} from './job-input.js';
|
|
5
7
|
import {checkCommand} from './guards.js';
|
|
6
8
|
const sha=value=>createHash('sha256').update(value).digest('hex');
|
|
@@ -28,26 +30,36 @@ export function prepareJobBatch(raw,cfg){
|
|
|
28
30
|
atomic:false,execution_retries:0,scope:'GPU Job spending caps only; separately approved storage charges are additional. Immutable manifest; unused GPU budget is not automatically reassigned.',
|
|
29
31
|
next:'Review every command, GPU quote, time limit and storage choice. Retain this exact manifest, plan hash and batch key. Submission may partially succeed; resume the identical manifest, never invent new keys after a lost response.'};
|
|
30
32
|
}
|
|
31
|
-
export async function submitJobBatch(api,raw,cfg){
|
|
33
|
+
export async function submitJobBatch(api,raw,cfg,receipts=null){
|
|
34
|
+
// 固定本次批量调用的凭证/端点,避免并行connect或轮换让重试跨账户。
|
|
35
|
+
if(api instanceof CloudGpuApi)api=new CloudGpuApi({apiKey:api.apiKey,baseUrl:api.baseUrl,fetchImpl:api.fetch,userAgent:api.userAgent});
|
|
32
36
|
const {approved_plan_sha256,user_confirmed,...input}=raw;
|
|
33
37
|
if(user_confirmed!==true)throw Error('Obtain explicit approval for all Jobs and the aggregate budget before submission');
|
|
34
38
|
const plan=prepareJobBatch(input,cfg);
|
|
35
39
|
if(approved_plan_sha256!==plan.plan_sha256)throw Error('The approved batch manifest changed; review it again before submitting');
|
|
40
|
+
const journal=receipts?await receipts.bind(plan):null;
|
|
36
41
|
const results=[];
|
|
37
42
|
for(const item of plan.items){
|
|
43
|
+
let known;
|
|
44
|
+
if(journal){
|
|
45
|
+
try{known=await journal.accepted(item.index);if(!known)await journal.intent(item);}
|
|
46
|
+
catch{return receipt('receipt_unavailable',results,item.index);}
|
|
47
|
+
}
|
|
38
48
|
try{
|
|
39
|
-
const job=await api.createJob(item.body,item.idempotency_key);
|
|
49
|
+
const job=known?await api.job(known.job_id):await api.createJob(item.body,item.idempotency_key);
|
|
50
|
+
if(known&&job?.id!==known.job_id)throw Error('Mismatched recorded Job');
|
|
40
51
|
if(!job||!/^job_[a-f0-9]{32}$/.test(job.id)||!['queued','provisioning','running','stopping','needs_attention','succeeded','failed','cancelled'].includes(job.status))throw Error('Invalid submission response');
|
|
41
52
|
results.push({index:item.index,idempotency_key:item.idempotency_key,job_id:job.id,status:job.status});
|
|
42
|
-
if(
|
|
53
|
+
if(journal&&!known){try{await journal.accept(item,job);}catch{return receipt('receipt_persistence_failed',results,item.index+1);}}
|
|
54
|
+
if(job.status==='needs_attention'||job.status==='stopping'||(journal&&['succeeded','failed','cancelled'].includes(job.status)&&job.cost_status!=='final'))return receipt('reconciliation_required',results,item.index+1);
|
|
43
55
|
}catch{
|
|
44
56
|
// Even a server error may follow an accepted create. Never turn uncertainty into another GPU.
|
|
45
|
-
results.push({index:item.index,idempotency_key:item.idempotency_key,job_id:null,status:'submission_uncertain'});
|
|
57
|
+
results.push({index:item.index,idempotency_key:item.idempotency_key,job_id:known?.job_id??null,status:known?'status_unavailable':'submission_uncertain'});
|
|
46
58
|
return receipt('submission_stopped',results,item.index+1);
|
|
47
59
|
}
|
|
48
60
|
}
|
|
49
61
|
return receipt('submitted',results,plan.items.length);
|
|
50
|
-
function receipt(status,items,next){return {batch_key:plan.batch_key,plan_sha256:plan.plan_sha256,status,atomic:false,total_budget_usd:plan.total_budget_usd,items,not_submitted:plan.items.slice(next).map(i=>({index:i.index,idempotency_key:i.idempotency_key})),execution_retries:0,next:status==='submitted'?'Poll get_job_batch. A failed command is not automatically retried.':'Reconcile or replay only the identical approved manifest with the same batch key. No automatic new-attempt retry or cancellation was performed.'};}
|
|
62
|
+
function receipt(status,items,next){return {batch_key:plan.batch_key,plan_sha256:plan.plan_sha256,status,atomic:false,total_budget_usd:plan.total_budget_usd,items,not_submitted_scope:'this_invocation_only; entries may already exist from an earlier invocation',not_submitted:plan.items.slice(next).map(i=>({index:i.index,idempotency_key:i.idempotency_key})),execution_retries:0,local_receipts_enabled:!!journal,next:status==='submitted'?'Poll get_job_batch. A failed command is not automatically retried.':'Reconcile or replay only the identical approved manifest with the same batch key. No automatic new-attempt retry or cancellation was performed.'};}
|
|
51
63
|
}
|
|
52
64
|
export async function getJobBatch(api,ids){
|
|
53
65
|
z.array(z.string().regex(/^job_[a-f0-9]{32}$/)).min(1).max(8).parse(ids);
|
|
@@ -58,8 +70,10 @@ export async function getJobBatch(api,ids){
|
|
|
58
70
|
}
|
|
59
71
|
export function registerBatchTools(server,{api,cfg,wrap,ok}){
|
|
60
72
|
const input=schema(cfg);
|
|
73
|
+
const receipts=()=>new BatchReceipts({apiKey:'apiKey' in api?api.apiKey:cfg.apiKey,baseUrl:api.baseUrl||cfg.baseUrl});
|
|
74
|
+
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))));
|
|
61
75
|
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))));
|
|
62
76
|
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))));
|
|
63
77
|
if(cfg.readOnly)return;
|
|
64
|
-
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))));
|
|
78
|
+
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()))));
|
|
65
79
|
}
|