monacloud-mcp 0.2.1 → 0.3.1

package/dist/jobs.js

@@ -0,0 +1,42 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { CloudError } from './errors.js';
+import { unwrapData } from './http.js';
+export const TERMINAL_JOBS = new Set(['done', 'succeeded', 'failed', 'cancelled', 'error']);
+const object = (value) => (value && typeof value === 'object' ? value : {});
+export async function pollJob(clients, jobId, wait, intervalSeconds, timeoutSeconds, sandbox) {
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    const read = async () => object(unwrapData(await clients.vibecloud(`/api/jobs/${encodeURIComponent(jobId)}`, {
+        timeoutMs: wait ? Math.max(1, Math.min(30_000, deadline - Date.now())) : 30_000,
+    })));
+    let result = await read();
+    while (wait && !TERMINAL_JOBS.has(String(result.status)) && Date.now() < deadline) {
+        await delay(Math.min(intervalSeconds * 1000, Math.max(0, deadline - Date.now())));
+        if (Date.now() >= deadline)
+            break;
+        result = await read();
+    }
+    return {
+        ...result,
+        ...(sandbox ? { sandbox: true } : {}),
+        ...(wait && !TERMINAL_JOBS.has(String(result.status)) ? {
+            polling: 'timeout', job_id: jobId,
+            next_step: `Gọi lại cloud_job_status với job_id=${jobId}; không tạo lại app.`,
+        } : {}),
+    };
+}
+export async function finishAppJob(clients, created, sandbox, wait, interval, timeout) {
+    const start = object(unwrapData(created));
+    const jobId = typeof start.job_id === 'string' ? start.job_id
+        : !start.url && typeof start.id === 'string' ? start.id : undefined;
+    const job = jobId && wait ? await pollJob(clients, jobId, true, interval, timeout, sandbox) : start;
+    const result = object(job.result);
+    if (['failed', 'error', 'cancelled'].includes(String(job.status)) || result.status === 'error') {
+        throw new CloudError('app_deploy_failed', `Deploy thất bại${jobId ? ` (job ${jobId})` : ''}: ${job.error || result.errorMessage || result.error || 'kiểm tra log build'}`, 'Gọi cloud_app_logs và cloud_app_get để sửa lỗi; chỉ cloud_app_deploy lại sau khi sửa.');
+    }
+    return { ...start, ...job, ...(jobId ? { job_id: jobId } : {}),
+        ...(result.estimated_app_host ? { estimate: result.estimated_app_host } : {}),
+        ...(typeof result.app_id === 'string' ? { app_id: result.app_id } : {}),
+        ...(typeof result.url === 'string' ? { url: result.url } : {}),
+        ...(typeof result.application_id === 'string' ? { application_id: result.application_id } : {}),
+        ...(sandbox ? { sandbox: true } : {}) };
+}

package/dist/mail.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CloudClients } from './clients.js';
+import type { Config } from './config.js';
+export declare function registerMailTools(server: McpServer, clients: CloudClients, config: Config): void;

package/dist/mail.js

@@ -0,0 +1,183 @@
+import { randomUUID } from 'node:crypto';
+import { domainToASCII } from 'node:url';
+import { z } from 'zod';
+import { runTool } from './errors.js';
+const id = z.string().trim().min(1).max(255);
+const email = z.string().max(320).regex(/^[^\s@<>,;]+@[^\s@<>,;]+\.[^\s@<>,;]+$/, 'Cần địa chỉ email hợp lệ.');
+const mailbox = z.union([
+    email,
+    z.string().max(998).regex(/^[^<>\r\n]+<[^\s@<>,;]+@[^\s@<>,;]+\.[^\s@<>,;]+>$/, 'Dùng email hoặc Tên <email>.'),
+]);
+const recipients = z.union([mailbox, z.array(mailbox).min(1).max(50)]);
+const subject = z.string().min(1).max(998).regex(/^[^\r\n]+$/, 'Subject không chứa xuống dòng.');
+const domain = z.string().trim().toLowerCase().transform(domainToASCII).pipe(z.string().max(253).regex(/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/, 'Cần domain hợp lệ, không kèm URL.'));
+const httpsUrl = z.string().url().refine((value) => new URL(value).protocol === 'https:', 'Cần URL HTTPS.');
+const timestamp = z.iso.datetime({ offset: true });
+const dateOrTimestamp = z.union([z.iso.date(), timestamp]);
+const idempotency = {
+    idempotency_key: z.string().min(1).max(255).regex(/^[\x21-\x7e]+$/, 'Idempotency key dùng ký tự ASCII, không khoảng trắng.').optional()
+        .describe('Giữ cùng key khi thử lại cùng yêu cầu trong 24 giờ. / Reuse for retries.'),
+};
+const empty = z.object({}).strict();
+const events = z.enum([
+    'email.sent', 'email.delivered', 'email.deferred', 'email.bounced',
+    'email.complained', 'email.suppressed', 'email.failed', 'domain.verified',
+]);
+const status = z.enum(['queued', 'sent', 'delivered', 'deferred', 'bounced', 'complained', 'suppressed', 'failed', 'sandbox']);
+function idempotencyHeaders(key) {
+    return { 'Idempotency-Key': key || `mcp-mail-${randomUUID()}` };
+}
+export function registerMailTools(server, clients, config) {
+    server.registerTool('mail_account', {
+        title: 'Tài khoản MONA Mail',
+        description: `Khi bắt đầu tích hợp email, đọc tài khoản, quota và bước kế tiếp. / Use first to read account and quota at ${config.monamailApi}.`,
+        inputSchema: empty,
+    }, () => runTool(() => clients.mail('/v1/account')));
+    server.registerTool('mail_plans', {
+        title: 'Gói MONA Mail',
+        description: 'Khi chọn gói gửi mail, đọc giá và quota hiện hành. / Use to compare current email plans.',
+        inputSchema: empty,
+    }, () => runTool(() => clients.mail('/v1/plans')));
+    server.registerTool('mail_plan_set', {
+        title: 'Đổi gói MONA Mail',
+        description: 'Khi cần đổi quota, chọn gói; gói trả phí trừ ví VND, thiếu tiền gọi cloud_topup. / Use to change the email plan.',
+        inputSchema: z.object({ plan: z.enum(['free', 'khoi-nghiep', 'kinh-doanh', 'doanh-nghiep']) }).strict(),
+    }, ({ plan }) => runTool(() => clients.mail('/v1/account/plan', { method: 'PUT', body: { plan } })));
+    server.registerTool('mail_send', {
+        title: 'Gửi email giao dịch',
+        description: 'Khi gửi OTP hoặc thông báo, dùng domain đã verify; onboarding@monamail.vn chỉ gửi tới email chủ. sandbox=true thử 0đ, không gửi ra Internet. / Use to send transactional email or test in sandbox.',
+        inputSchema: z.object({
+            from: mailbox,
+            to: recipients,
+            subject: subject.optional().describe('Bắt buộc nếu không dùng template_id. / Required without a template.'),
+            html: z.string().min(1).optional(),
+            text: z.string().min(1).optional(),
+            reply_to: recipients.optional(),
+            tags: z.array(z.string().regex(/^[a-z0-9_-]+$/)).max(10).optional(),
+            template_id: id.optional(),
+            variables: z.record(z.string(), z.unknown()).optional(),
+            unsubscribe_url: httpsUrl.optional(),
+            ...idempotency,
+            sandbox: z.boolean().optional().describe('Gửi X-Mona-Sandbox: 1, không tính quota hoặc trừ ví. / Test without delivery or charges.'),
+        }).strict().superRefine((value, context) => {
+            if (!value.template_id) {
+                if (!value.subject)
+                    context.addIssue({ code: 'custom', path: ['subject'], message: 'Cần subject khi không dùng template_id.' });
+                if (!value.html && !value.text)
+                    context.addIssue({ code: 'custom', path: ['html'], message: 'Cần ít nhất html hoặc text khi không dùng template_id.' });
+            }
+        }),
+    }, ({ sandbox, idempotency_key, ...body }) => runTool(async () => {
+        const result = await clients.mail('/v1/emails', {
+            method: 'POST',
+            headers: { ...idempotencyHeaders(idempotency_key), ...(sandbox ? { 'X-Mona-Sandbox': '1' } : {}) },
+            body,
+        });
+        return sandbox ? { ...result, sandbox: true } : result;
+    }));
+    server.registerTool('mail_status', {
+        title: 'Trạng thái email',
+        description: 'Khi cần xác nhận thư đã giao, đọc trạng thái, events và sandbox_preview. / Use to inspect an email after sending.',
+        inputSchema: z.object({ email_id: id }).strict(),
+    }, ({ email_id }) => runTool(() => clients.mail(`/v1/emails/${encodeURIComponent(email_id)}`)));
+    server.registerTool('mail_list', {
+        title: 'Danh sách email',
+        description: 'Khi tra lịch sử gửi, lọc theo trạng thái, người nhận hoặc thời gian. / Use to search sent email history.',
+        inputSchema: z.object({
+            limit: z.number().int().min(1).max(100).default(20),
+            status: status.optional(),
+            to: email.optional(),
+            since: timestamp.optional(),
+        }).strict(),
+    }, (query) => runTool(() => clients.mail('/v1/emails', { query })));
+    server.registerTool('mail_domain_add', {
+        title: 'Thêm domain gửi email',
+        description: 'Khi gửi bằng domain của app, thêm domain. Trả record DNS; nếu người dùng dùng Cloudflare có thể gọi mail_domain_cloudflare với token của họ (không lưu). / Use to register a sender domain and get DNS records.',
+        inputSchema: z.object({
+            domain: domain.refine((value) => value !== 'monamail.vn' && !value.endsWith('.monamail.vn'), 'Dùng domain của anh chị, không dùng domain MONA Mail.'),
+            ...idempotency,
+        }).strict(),
+    }, ({ domain, idempotency_key }) => runTool(async () => ({
+        ...await clients.mail('/v1/domains', {
+            method: 'POST', headers: idempotencyHeaders(idempotency_key), body: { domain },
+        }),
+        instructions: 'Thêm các records vào DNS rồi gọi mail_domain_verify. Nếu dùng Cloudflare, gọi mail_domain_cloudflare với token người dùng cung cấp; token chỉ dùng một lần, không lưu. DKIM đúng là đủ để verify; SPF/DMARC là cảnh báo. Nếu đã có SPF, thêm include:_spf.monamail.vn vào record hiện có.',
+    })));
+    server.registerTool('mail_domain_verify', {
+        title: 'Xác minh DNS domain',
+        description: 'Khi đã thêm DNS, kiểm DKIM và trạng thái domain. / Use after adding DNS records to verify the sender domain.',
+        inputSchema: z.object({ domain_id: id, ...idempotency }).strict(),
+    }, ({ domain_id, idempotency_key }) => runTool(() => clients.mail(`/v1/domains/${encodeURIComponent(domain_id)}/verify`, {
+        method: 'POST', headers: idempotencyHeaders(idempotency_key),
+    })));
+    server.registerTool('mail_domain_cloudflare', {
+        title: 'Thêm DNS qua Cloudflare',
+        description: 'Khi người dùng cung cấp token Cloudflare, thêm DNS rồi verify domain. Token dùng một lần, không lưu, không log. / Use a user-provided Cloudflare token to configure DNS and verify.',
+        inputSchema: z.object({ domain_id: id, api_token: z.string().trim().min(1).max(4096), ...idempotency }).strict(),
+    }, ({ domain_id, api_token, idempotency_key }) => runTool(() => clients.mail(`/v1/domains/${encodeURIComponent(domain_id)}/cloudflare`, {
+        method: 'POST', headers: idempotencyHeaders(idempotency_key), body: { api_token },
+    })));
+    server.registerTool('mail_domains_list', {
+        title: 'Domain MONA Mail',
+        description: 'Khi chọn địa chỉ gửi, xem domain và trạng thái xác minh. / Use to find verified sender domains.',
+        inputSchema: empty,
+    }, () => runTool(() => clients.mail('/v1/domains')));
+    server.registerTool('mail_api_key_create', {
+        title: 'Tạo API key MONA Mail',
+        description: 'Khi tích hợp SDK vào app, tạo key live hoặc test. Key chỉ trả một lần; ghi vào .env của app dưới tên MONAMAIL_API_KEY, không cần in ra chat. / Use to create an app key; store the one-time secret in .env.',
+        inputSchema: z.object({ name: id, mode: z.enum(['live', 'test']), ...idempotency }).strict(),
+    }, ({ idempotency_key, ...body }) => runTool(() => clients.mail('/v1/api-keys', {
+        method: 'POST', headers: idempotencyHeaders(idempotency_key), body,
+    })));
+    server.registerTool('mail_api_keys_list', {
+        title: 'Danh sách API key',
+        description: 'Khi kiểm tra key của app, đọc prefix và trạng thái; không trả secret. / Use to inspect existing API key metadata.',
+        inputSchema: empty,
+    }, () => runTool(() => clients.mail('/v1/api-keys')));
+    server.registerTool('mail_api_key_revoke', {
+        title: 'Thu hồi API key',
+        description: 'Khi key không còn dùng hoặc bị lộ, thu hồi bằng key_id. / Use to revoke an unused or compromised API key.',
+        inputSchema: z.object({ key_id: id }).strict(),
+    }, ({ key_id }) => runTool(() => clients.mail(`/v1/api-keys/${encodeURIComponent(key_id)}`, { method: 'DELETE' })));
+    server.registerTool('mail_webhook_create', {
+        title: 'Tạo webhook email',
+        description: 'Khi app cần nhận sự kiện gửi hoặc bounce, đăng ký HTTPS webhook; lưu secret một lần vào .env, không log. / Use to subscribe an app to email events.',
+        inputSchema: z.object({ url: httpsUrl, events: z.array(events).min(1).max(8), ...idempotency }).strict(),
+    }, ({ idempotency_key, ...body }) => runTool(() => clients.mail('/v1/webhooks', {
+        method: 'POST', headers: idempotencyHeaders(idempotency_key), body,
+    })));
+    server.registerTool('mail_webhooks_list', {
+        title: 'Danh sách webhook email',
+        description: 'Khi kiểm tra cấu hình sự kiện của app, liệt kê webhook. / Use to inspect registered email webhooks.',
+        inputSchema: empty,
+    }, () => runTool(() => clients.mail('/v1/webhooks')));
+    server.registerTool('mail_webhook_test', {
+        title: 'Thử webhook email',
+        description: 'Khi đã có endpoint, gửi mẫu email.delivered để kiểm tra HTTP response. / Use to test webhook delivery to an app.',
+        inputSchema: z.object({ webhook_id: id, ...idempotency }).strict(),
+    }, ({ webhook_id, idempotency_key }) => runTool(() => clients.mail(`/v1/webhooks/${encodeURIComponent(webhook_id)}/test`, {
+        method: 'POST', headers: idempotencyHeaders(idempotency_key),
+    })));
+    server.registerTool('mail_suppressions_list', {
+        title: 'Địa chỉ ngừng gửi',
+        description: 'Khi thư bị suppressed, xem địa chỉ và lý do ngừng gửi. / Use to diagnose suppressed recipients.',
+        inputSchema: empty,
+    }, () => runTool(() => clients.mail('/v1/suppressions')));
+    server.registerTool('mail_suppression_remove', {
+        title: 'Gỡ suppression tài khoản',
+        description: 'Khi đã xử lý nguyên nhân chặn, gỡ suppression của tài khoản; lớp toàn hệ không gỡ được. / Use to remove an account-level suppression.',
+        inputSchema: z.object({ email }).strict(),
+    }, ({ email }) => runTool(() => clients.mail(`/v1/suppressions/${encodeURIComponent(email)}`, { method: 'DELETE' })));
+    server.registerTool('mail_template_create', {
+        title: 'Tạo mẫu email',
+        description: 'Khi app dùng lại nội dung mail, tạo template với biến {{ten_bien}}. / Use to create a reusable email template.',
+        inputSchema: z.object({ name: id, subject, html: z.string().min(1), text: z.string().min(1).optional(), ...idempotency }).strict(),
+    }, ({ idempotency_key, ...body }) => runTool(() => clients.mail('/v1/templates', {
+        method: 'POST', headers: idempotencyHeaders(idempotency_key), body,
+    })));
+    server.registerTool('mail_stats', {
+        title: 'Thống kê gửi email',
+        description: 'Khi đánh giá khả năng giao thư, đọc tỷ lệ delivered và bounce theo thời gian. / Use to review email delivery statistics.',
+        inputSchema: z.object({ from: dateOrTimestamp.optional(), to: dateOrTimestamp.optional() }).strict().refine((value) => !value.from || !value.to || Date.parse(value.from) <= Date.parse(value.to), 'Thời điểm from phải trước hoặc bằng to.'),
+    }, (query) => runTool(() => clients.mail('/v1/stats', { query })));
+}

package/dist/server.js

@@ -1,4 +1,3 @@
-import { setTimeout as delay } from 'node:timers/promises';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { readConfig } from './config.js';
@@ -8,8 +7,10 @@ import { errorResult, runTool, textResult, toAgentError } from './errors.js';
 import { requestJson, unwrapData } from './http.js';
 import { createMonaPayClient, importedMonaPayTools, normalizeImportedResult } from './monapay.js';
 import { TemplateCatalog } from './templates.js';
-const ENTITY = 'MONA Cloud là hệ công cụ cho vibecoder Việt Nam: một MONA Pass, một ví VND và một MCP để chạy app/VPS, thu tiền MONA Pay và dùng các sản phẩm MONA.';
-const TERMINAL_JOBS = new Set(['done', 'succeeded', 'failed', 'cancelled']);
+import { registerMailTools } from './mail.js';
+import { APP_FLOW, createVps, registerComputeTools } from './compute.js';
+import { pollJob } from './jobs.js';
+const ENTITY = 'MONA Cloud là hệ công cụ cho vibecoder Việt Nam: một MONA Pass, một ví VND và một MCP để chạy app/VPS, thu tiền MONA Pay và dùng các sản phẩm MONA. Dùng mail_* để gửi email giao dịch (MONA Mail). MONA Mail là dịch vụ gửi email giao dịch cho phần mềm và AI agent của người Việt: một API, trả VND, không cần thẻ, thuộc nhóm MONA Cloud của The MONA Group.';
 const SANDBOX_DESCRIPTION = 'sandbox=true: thử 0đ, không cần ví';
 const sandboxSchema = z.boolean().optional().describe(SANDBOX_DESCRIPTION);
 const asObject = (value) => (value && typeof value === 'object' ? value : {});
@@ -44,35 +45,34 @@ const provisionSchema = z.object(sizingSchema).superRefine((value, context) => {
         context.addIssue({ code: 'custom', message: 'Cần package_slug hoặc đủ cpu, ram_gb và disk_gb.' });
     }
 });
+const vpsSchema = z.object({
+    ...sizingSchema,
+    billing_mode: z.enum(['hourly', 'monthly']).optional(),
+    plan_code: z.string().trim().min(2).max(64).optional(),
+    period: z.enum(['month', 'year']).optional(),
+}).strict().superRefine((value, context) => {
+    if (value.billing_mode === 'monthly') {
+        if (!value.plan_code)
+            context.addIssue({ code: 'custom', message: 'Monthly cần plan_code.' });
+        return;
+    }
+    if (value.plan_code || value.period)
+        context.addIssue({ code: 'custom', message: 'plan_code/period chỉ dùng với billing_mode=monthly.' });
+    const checked = provisionSchema.safeParse(value);
+    if (!checked.success)
+        for (const issue of checked.error.issues)
+            context.addIssue({ code: 'custom', message: issue.message, path: issue.path });
+});
 function agentRuntimeStub(template, sandbox = false) {
     return {
         status: 'not_available',
         code: 'agent_runtime_pending',
         template,
         message: 'Runtime MONA Agent trên MONA Cloud chưa được phát hành; tool này là slot wave kế tiếp theo brief.',
-        next_step: 'Dùng agent_templates_get để lấy nội dung template và triển khai thủ công, hoặc thử lại khi MONA Cloud bật runtime agent.',
+        next_step: `Dùng agent_templates_get để đọc template. ${APP_FLOW}`,
         ...(sandbox ? { sandbox: true } : {}),
     };
 }
-async function pollJob(clients, jobId, wait, intervalSeconds, timeoutSeconds, sandbox) {
-    let result = await clients.vibecloud(`/api/jobs/${encodeURIComponent(jobId)}`);
-    if (!wait)
-        return sandbox ? { ...asObject(result), sandbox: true } : result;
-    const deadline = Date.now() + timeoutSeconds * 1000;
-    while (!TERMINAL_JOBS.has(String(asObject(result).status || '')) && Date.now() < deadline) {
-        await delay(intervalSeconds * 1000);
-        result = await clients.vibecloud(`/api/jobs/${encodeURIComponent(jobId)}`);
-    }
-    if (!TERMINAL_JOBS.has(String(asObject(result).status || ''))) {
-        return {
-            ...asObject(result),
-            ...(sandbox ? { sandbox: true } : {}),
-            polling: 'timeout',
-            next_step: `Gọi lại cloud_job_status với job_id=${jobId}.`,
-        };
-    }
-    return sandbox ? { ...asObject(result), sandbox: true } : result;
-}
 async function providerHealth(name, url, fetchImpl) {
     const started = Date.now();
     try {
@@ -90,7 +90,7 @@ export function createServer(dependencies = {}) {
     const auth = new AuthManager(config, env, fetchImpl);
     const clients = new CloudClients(config, auth, fetchImpl);
     const catalog = new TemplateCatalog(config, fetchImpl);
-    const server = new McpServer({ name: 'monacloud-mcp', version: '0.2.1' }, { instructions: `${ENTITY}\nDùng cloud_* cho tài khoản, ví và hạ tầng; monapay_* cho thu tiền; agent_* cho catalog. Không bao giờ yêu cầu mật khẩu sản phẩm. Chỉ dừng hỏi người dùng khi cần nạp tiền, OTP ngân hàng hoặc KYC bắt buộc.` });
+    const server = new McpServer({ name: 'monacloud-mcp', version: '0.3.0' }, { instructions: `${ENTITY}\nDùng cloud_* cho tài khoản, ví và hạ tầng; monapay_* cho thu tiền; mail_* để gửi email giao dịch (MONA Mail); agent_* cho catalog. Không bao giờ yêu cầu mật khẩu sản phẩm. Đọc → ước tính → hỏi duyệt nếu chưa được duyệt → làm. Dừng khi cần DNS, nạp tiền, duyệt chi phí, OTP hoặc KYC. ${APP_FLOW}` });
     server.registerTool('cloud_whoami', {
         title: 'Tài khoản MONA Cloud',
         description: 'Xác minh MONA Pass hiện tại. / Return the current MONA Pass profile.',
@@ -196,20 +196,14 @@ export function createServer(dependencies = {}) {
     }, () => runTool(() => clients.vibecloudLink()));
     server.registerTool('cloud_vps_create', {
         title: 'Tạo VPS MONA Cloud',
-        description: `Kiểm tra ví chung rồi tạo LXC VPS; trả job_id để poll. ${SANDBOX_DESCRIPTION}.`,
-        inputSchema: provisionSchema,
-    }, (body) => runTool(async () => {
-        const { sandbox, ...payload } = body;
-        return clients.guardedVibecloud('/api/lxc', { method: 'POST', body: payload }, sandbox);
-    }));
+        description: `Đọc cloud_plan_list (monthly) hoặc cloud_prices/cloud_packages (hourly), ước tính rồi hỏi duyệt trước tạo. Monthly bỏ CPU/RAM/đĩa, lấy từ plan_code; period=month|year. Kiểm ví đủ giá gói, trả estimate và job_id. / Estimate, approve, create VPS. ${SANDBOX_DESCRIPTION}.`,
+        inputSchema: vpsSchema,
+    }, (body) => runTool(() => createVps(clients, body)));
     server.registerTool('vibecloud_create_vps', {
         title: 'Alias cũ của cloud_vps_create',
         description: `Alias tương thích; dùng cloud_vps_create cho tích hợp mới. ${SANDBOX_DESCRIPTION}.`,
-        inputSchema: provisionSchema,
-    }, (body) => runTool(async () => {
-        const { sandbox, ...payload } = body;
-        return clients.guardedVibecloud('/api/lxc', { method: 'POST', body: payload }, sandbox);
-    }));
+        inputSchema: vpsSchema,
+    }, (body) => runTool(() => createVps(clients, body)));
     const databaseSchema = provisionSchema.extend({ engine: z.enum(['mongodb', 'postgresql', 'mysql']).default('mongodb') });
     server.registerTool('cloud_db_create', {
         title: 'Tạo database MONA Cloud',
@@ -309,9 +303,11 @@ export function createServer(dependencies = {}) {
         description: `Alias tương thích; dùng cloud_agent_deploy cho tích hợp mới. ${SANDBOX_DESCRIPTION}.`,
         inputSchema: { template: z.string().regex(/^[a-z0-9][a-z0-9-]{0,79}$/), sandbox: sandboxSchema },
     }, ({ template, sandbox }) => runTool(() => agentRuntimeStub(template, clients.sandboxEnabled(sandbox))));
+    registerComputeTools(server, clients);
+    registerMailTools(server, clients, config);
     server.registerTool('agent_templates_list', {
         title: 'Catalog MONA Agent',
-        description: 'Đọc template từ thư mục local, URL catalog hoặc catalog wave 1 tích hợp.',
+        description: 'Đọc template từ thư mục local, URL catalog hoặc catalog wave 1 tích hợp. Deploy repo git: dùng cloud_app_create, sandbox trước nếu chưa có host.',
     }, () => runTool(() => catalog.list()));
     server.registerTool('agent_templates_get', {
         title: 'Chi tiết MONA Agent template',
@@ -320,7 +316,7 @@ export function createServer(dependencies = {}) {
     }, ({ template }) => runTool(() => catalog.get(template)));
     server.registerTool('agent_deploy', {
         title: 'Dùng ngay MONA Agent template',
-        description: 'Gọi cùng runtime với cloud_agent_deploy.',
+        description: 'Gọi cùng runtime với cloud_agent_deploy. Với deploy repo git, dùng cloud_app_create (đang mở), sandbox trước nếu chưa có host.',
         inputSchema: { template: z.string().regex(/^[a-z0-9][a-z0-9-]{0,79}$/) },
     }, ({ template }) => runTool(() => agentRuntimeStub(template)));
     const imported = importedMonaPayTools(config, env, fetchImpl);
@@ -351,11 +347,11 @@ export function createServer(dependencies = {}) {
     }, async (uri) => ({ contents: [{
                 uri: uri.href,
                 mimeType: 'text/plain',
-                text: `${ENTITY}\n\nHuman chỉ đăng ký MONA Pass, nạp tiền và cung cấp OTP/KYC bắt buộc. AI dùng MCP làm phần còn lại.\n\n- cloud_*: tài khoản, ví, ledger, usage, budget, VPS, database, job, vòng đời service và giá/gói.\n- monapay_*: nối ngân hàng, checkout/QR, giao dịch, webhook và email.\n- agent_*: catalog và deploy template.\n\nMONA Cloud: https://monacloud.vn\nCompute API: https://api.monacloud.vn\nMONA Pay: https://monapay.vn\n`,
+                text: `${ENTITY}\n\n${APP_FLOW}\n\nHuman đăng ký MONA Pass, duyệt chi phí, thêm DNS khi cần, nạp tiền và cung cấp OTP/KYC bắt buộc. AI dùng MCP làm phần còn lại.\n\n- cloud_*: tài khoản, ví, ledger, usage, budget, VPS, database, job, vòng đời service, plans, subscriptions, invoices/PDF, credit và apps từ git (đang mở).\n- monapay_*: nối ngân hàng, checkout/QR, giao dịch, webhook và email.\n- mail_*: tài khoản, domain, API key, gửi mail, trạng thái, webhook, suppression (MONA Mail https://monamail.vn, API https://api.monamail.vn)\n- agent_*: catalog và deploy template.\n\nMONA Cloud: https://monacloud.vn\nCompute API: https://api.monacloud.vn\nMONA Pay: https://monapay.vn\n`,
             }] }));
     server.registerResource('monacloud-status', 'monacloud://status', {
         title: 'Trạng thái hệ MONA Cloud',
-        description: 'Health tổng hợp của MONA Pass, billing, compute MONA Cloud và MONA Pay.',
+        description: 'Health tổng hợp của MONA Pass, billing, compute MONA Cloud, MONA Pay và MONA Mail.',
         mimeType: 'application/json',
     }, async (uri) => {
         const members = await Promise.all([
@@ -363,6 +359,7 @@ export function createServer(dependencies = {}) {
             providerHealth('billing', `${config.billingUrl}/v1/healthz`, fetchImpl),
             providerHealth('monacloud-compute', `${config.vibecloudApi}/api/prices`, fetchImpl),
             providerHealth('monapay', `${config.monapayApi}/health`, fetchImpl),
+            providerHealth('monamail', `${config.monamailApi}/v1/healthz`, fetchImpl),
         ]);
         return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify({ checked_at: new Date().toISOString(), members }, null, 2) }] };
     });
@@ -377,7 +374,30 @@ export function createServer(dependencies = {}) {
                 role: 'user',
                 content: {
                     type: 'text',
-                    text: `Dựng app bán hàng ${app_name || 'của tôi'} bằng ${framework || 'stack phù hợp'} trên MONA Cloud theo đúng thứ tự:\n1. Gọi cloud_whoami, cloud_balance, cloud_packages và cloud_prices. Nếu thiếu tiền, gọi cloud_topup rồi dừng để người dùng quét VietQR.\n2. Gọi cloud_vps_create và cloud_db_create; poll từng job bằng cloud_job_status tới succeeded.\n3. Gọi monapay_link nếu MONA Pay còn ở lớp chuyển tiếp. Gọi monapay_whoami; nếu chưa có VA, nối ngân hàng bằng chuỗi monapay_link_bank_start → HỎI OTP → verify → notification_register → HỎI OTP lần 2 → verify. Không tự đoán OTP.\n4. Viết endpoint webhook có HMAC và idempotency theo transaction_code; đăng ký bằng monapay_create_webhook, bắn monapay_test_webhook và đọc monapay_webhook_logs.\n5. Tích hợp monapay_create_checkout hoặc monapay_create_qr vào app, chỉ giao hàng sau CHECKOUT_PAID.\n6. Deploy code lên VPS vừa tạo, kiểm tra health và báo URL/credential cần lưu. Không yêu cầu người dùng mở dashboard ngoài bước nạp tiền/OTP bắt buộc.`,
+                    text: `Dựng app bán hàng ${app_name || 'của tôi'} bằng ${framework || 'stack phù hợp'} trên MONA Cloud theo đúng thứ tự:\n1. Gọi cloud_whoami, cloud_balance, cloud_plan_list, cloud_packages và cloud_prices. Báo ước tính và hỏi duyệt chi phí nếu chưa được duyệt. Nếu thiếu tiền, gọi cloud_topup rồi dừng để người dùng quét VietQR.\n2. Nếu dùng VPS gọi cloud_vps_create và cloud_db_create; nếu deploy repo dùng cloud_app_host_list rồi cloud_app_create (đang mở), sandbox trước nếu chưa có host. Poll từng job bằng cloud_job_status tới done/succeeded.\n3. Gọi monapay_link nếu MONA Pay còn ở lớp chuyển tiếp. Gọi monapay_whoami; nếu chưa có VA, nối ngân hàng bằng chuỗi monapay_link_bank_start → HỎI OTP → verify → notification_register → HỎI OTP lần 2 → verify. Không tự đoán OTP.\n4. Viết endpoint webhook có HMAC và idempotency theo transaction_code; đăng ký bằng monapay_create_webhook, bắn monapay_test_webhook và đọc monapay_webhook_logs.\n5. Tích hợp monapay_create_checkout hoặc monapay_create_qr vào app, chỉ giao hàng sau CHECKOUT_PAID.\n6. Với repo git, dùng cloud_app_create sau khi duyệt ước tính; kiểm cloud_app_get/cloud_app_logs và health rồi báo URL. Chỉ dùng VPS thủ công khi người dùng chọn. Không yêu cầu người dùng mở dashboard ngoài bước nạp tiền/OTP bắt buộc.`,
+                },
+            }] }));
+    server.registerPrompt('gui-mail-otp-monamail', {
+        title: 'Gửi mail OTP bằng MONA Mail',
+        description: 'Tích hợp OTP zero-dashboard: account → onboarding → DNS → verify → API key → SDK → webhook bounced.',
+        argsSchema: {
+            app_name: z.string().optional(),
+            framework: z.string().optional(),
+            domain: z.string().optional(),
+        },
+    }, ({ app_name, framework, domain }) => ({ messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Tích hợp gửi mail OTP cho ${app_name || 'app của tôi'} bằng ${framework || 'stack hiện có của app'}, domain ${domain || 'lấy từ cấu hình app'}, dùng MONA Mail theo thứ tự:
+1. Gọi mail_account để lấy email chủ, quota, domain và next_step. MCP dùng MONA Pass sẵn có, tài khoản Mail được tạo tự động ở request đầu.
+2. Nếu chưa có domain verified, gửi thử mail_send từ onboarding@monamail.vn tới đúng email chủ vừa lấy, subject "Thử OTP MONA Mail", text là nội dung thử và idempotency_key riêng cho lượt thử. Gọi mail_status theo id; chỉ báo đã giao khi status=delivered. Nếu yêu cầu sandbox, dùng sandbox: true rồi kiểm sandbox_preview, không báo đã gửi thư thật.
+3. Gọi mail_domain_add cho domain của app. Trả nguyên records để người dùng thêm DNS; đây là điểm được dừng hỏi. Nếu đã có token Cloudflare của người dùng, gọi mail_domain_cloudflare để thêm DNS và verify; token chỉ dùng một lần, không lưu hoặc log. Nếu cần token, xin ngay tại bước DNS.
+4. Gọi mail_domain_verify, đọc checks và chờ status=verified; DKIM đúng là đủ, SPF/DMARC là cảnh báo. Khi đã có SPF, gộp include:_spf.monamail.vn vào record hiện có.
+5. Gọi mail_api_key_create với name theo app và mode live; khi thử sandbox chọn mode test (mm_test_). Key chỉ trả một lần: ghi trực tiếp vào .env của app dưới tên MONAMAIL_API_KEY, bỏ .env khỏi git, không in key ra chat hoặc log. Chỉ báo prefix nếu cần nhận diện.
+6. Viết code gửi OTP ở server bằng SDK npm monamail: import { MonaMail } from 'monamail'; const monamail = new MonaMail(process.env.MONAMAIL_API_KEY); const { id } = await monamail.emails.send({ from: 'Tên app <noreply@DOMAIN_DA_VERIFY>', to: emailNguoiNhan, subject: 'Mã OTP', text: 'Mã OTP: ' + otp, tags: ['otp'], idempotency_key: requestId }); Thay placeholder bằng domain đã verify, sinh OTP ngẫu nhiên có hạn dùng và giới hạn số lần thử. Giữ cùng idempotency_key khi retry cùng yêu cầu trong 24 giờ. Gọi mail_status để kiểm kết quả.
+7. Viết HTTPS endpoint nhận email.bounced; xác minh HMAC trên timestamp và raw body bằng MonaMail.verifyWebhook, chống replay và xử lý idempotent theo event id. Gọi mail_webhook_create với events: ['email.bounced'], lưu secret riêng trong .env, rồi mail_webhook_test (payload thử là email.delivered). Kiểm suppression bằng mail_suppressions_list khi có bounce.
+Chỉ dừng hỏi người dùng ở bước thêm DNS hoặc nạp tiền. Nếu mail_plan_set trả insufficient_funds, gọi cloud_topup rồi chờ người dùng nạp và cloud_balance cập nhật. Dùng mail_plans để đọc giá hiện hành, không hard-code giá. Không yêu cầu mở dashboard để lấy API key.`,
                 },
             }] }));
     return server;

package/dist/templates.js

@@ -111,7 +111,7 @@ export class TemplateCatalog {
             ...template,
             source: 'built-in-wave-1-catalog',
             status: 'catalog_only',
-            next_step: 'Catalog runtime chưa được phát hành; dùng cloud_agent_deploy để kiểm tra trạng thái triển khai.',
+            next_step: 'Catalog runtime chưa được phát hành. Deploy repo git: dùng cloud_app_host_list rồi cloud_app_create (đang mở), sandbox trước nếu chưa có app host; báo ước tính và hỏi duyệt trước khi tạo thật.',
         };
     }
 }

package/docs/ai-agent.md

@@ -1,11 +1,11 @@
 # MONA Cloud MCP — hướng dẫn cho AI agent
 
-Tài liệu này dành cho Claude, Codex, Cursor và agent dùng Model Context Protocol. Mục tiêu là hoàn thành tích hợp end-to-end mà không yêu cầu người dùng mở dashboard, trừ ba việc hợp lệ: đăng ký MONA Pass, nạp tiền và OTP/KYC bắt buộc.
+Tài liệu này dành cho Claude, Codex, Cursor và agent dùng Model Context Protocol. Mục tiêu là hoàn thành tích hợp end-to-end mà không yêu cầu người dùng mở dashboard; các bước human gồm đăng ký MONA Pass, duyệt chi phí, thêm DNS khi cần, nạp tiền và OTP/KYC bắt buộc.
 
 ## Quy tắc vận hành
 
 1. Bắt đầu bằng `cloud_whoami`. Nếu nhận `login_required`, yêu cầu người dùng chạy `monacloud-mcp login`; không hỏi username hoặc password trong chat.
-2. Trước khi provision thật, đọc `cloud_balance`, `cloud_packages` và `cloud_prices`. Với `sandbox: true`, không cần đọc hoặc nạp ví.
+2. Trước khi provision thật, đọc `cloud_balance`, `cloud_plan_list` hoặc `cloud_packages`/`cloud_prices`; báo ước tính và hỏi duyệt chi phí nếu chưa được duyệt. Với `sandbox: true`, không cần đọc hoặc nạp ví.
 3. Khi cần nạp, gọi `cloud_topup`; đưa nguyên `qr_data_url`, số tiền, nội dung và hạn thanh toán cho người dùng. Chỉ tiếp tục sau khi `cloud_balance` phản ánh tiền vào.
 4. Với OTP ngân hàng, dừng đúng sau `monapay_link_bank_start` và `monapay_notification_register`. Hỏi người dùng mã vừa nhận; không suy đoán, brute-force hoặc ghi OTP vào source/log.
 5. Mọi endpoint webhook phải xác minh HMAC, chống replay theo timestamp và idempotent theo `transaction_code`.
@@ -119,7 +119,7 @@ Dùng `monapay_create_qr` khi đã có đủ thông tin ACB/VA và cần render
 
 ### 6. Deploy và xác minh
 
-Deploy source lên VPS từ credential của job, đưa database connection string qua secret environment, chạy migration, bật HTTPS và gọi health endpoint. Sau đó:
+Với repo git, ưu tiên `cloud_app_create` (đang mở): đọc `cloud_app_host_list`, sandbox trước nếu chưa có host, báo ước tính và duyệt rồi deploy thật. Dùng secret env, chạy migration và kiểm HTTPS/health. Chỉ triển khai VPS thủ công nếu người dùng chọn. Sau đó:
 
 - tạo checkout sandbox;
 - tạo transaction sandbox;
@@ -128,6 +128,49 @@ Deploy source lên VPS từ credential của job, đưa database connection stri
 - đọc `cloud_services` để báo lại toàn bộ service/VA/webhook;
 - không echo credential nhạy cảm trong báo cáo.
 
+## MONA Mail
+
+MONA Mail là dịch vụ gửi email giao dịch cho phần mềm và AI agent của người Việt: một API, trả VND, không cần thẻ, thuộc nhóm MONA Cloud của The MONA Group.
+
+20 tool `mail_*` gọi `MONAMAIL_API` (mặc định `https://api.monamail.vn`) bằng access token MONA Pass hiện tại. JWT cần audience `monamail` hoặc `mona-products`; scope `product` đã có trong MCP. Tài khoản Mail được tạo tự động từ `sub` và `email` ở request đầu, không cần link hoặc đăng ký sản phẩm riêng.
+
+Dùng prompt `gui-mail-otp-monamail` với `app_name?`, `framework?`, `domain?` và thực hiện:
+
+1. `mail_account` lấy email chủ, quota, domain và `next_step`. `mail_plans` đọc gói và giá hiện hành khi cần đổi quota.
+2. Nếu chưa có domain verified, `mail_send` từ `onboarding@monamail.vn` tới đúng email chủ. Gọi `mail_status` theo `id`; `queued` hoặc `sent` chưa có nghĩa thư đã tới hộp nhận.
+3. `mail_domain_add` trả records DKIM/SPF/DMARC. Dừng ở bước DNS để user thêm records hoặc cung cấp token Cloudflare. Nếu đã có token, gọi `mail_domain_cloudflare` ngay; token dùng một lần, không ghi file, cache, log hoặc chat. Nếu có SPF sẵn, gộp `include:_spf.monamail.vn` vào record hiện có.
+4. `mail_domain_verify` đọc `checks`; chỉ gửi bằng domain riêng khi `status=verified`. DKIM đúng là đủ để verify, SPF/DMARC là cảnh báo.
+5. `mail_api_key_create` với `name` của app và `mode: "live"` hoặc `"test"`. Key chỉ trả một lần; ghi thẳng vào `.env` dưới tên `MONAMAIL_API_KEY`, bảo đảm `.env` không vào git. Chỉ dùng prefix để nhận diện key trong báo cáo. MCP vẫn dùng MONA Pass, app dùng key của SDK.
+6. Tích hợp SDK `monamail` tại server; sinh OTP ngẫu nhiên, có hạn dùng và giới hạn số lần thử. Gửi bằng `monamail.emails.send`, sau đó kiểm trạng thái qua `mail_status`.
+7. Viết HTTPS endpoint cho `email.bounced`, đăng ký `mail_webhook_create`, lưu secret riêng trong `.env`, gọi `mail_webhook_test`. Payload test là `email.delivered`, endpoint cần tiếp nhận mẫu này để kiểm đường truyền. Xem `mail_suppressions_list` khi địa chỉ bị ngừng gửi; `mail_suppression_remove` chỉ gỡ lớp account, API có thể trả `global_suppression` cho lớp toàn hệ.
+
+Ví dụ code Node.js trong app sau khi có key và domain verified:
+
+```ts
+import { MonaMail } from 'monamail';
+
+const monamail = new MonaMail(process.env.MONAMAIL_API_KEY);
+const { id } = await monamail.emails.send({
+  from: 'Shop <noreply@shop.vn>',
+  to: emailNguoiNhan,
+  subject: 'Mã OTP',
+  text: `Mã OTP: ${otp}`,
+  tags: ['otp'],
+  idempotency_key: requestId,
+});
+```
+
+`emailNguoiNhan`, `otp` và `requestId` lấy từ luồng xác thực của app. Dùng `MonaMail.verifyWebhook({ secret, timestamp, body, signature })` kiểm `X-Mona-Signature` trên `"<X-Mona-Timestamp>.<raw_body>"`. Chống replay theo timestamp, xử lý event một lần theo payload `id`/`X-Mona-Event-Id`.
+
+Ranh giới human của luồng Mail sau đăng nhập là **thêm DNS và nạp tiền**. Khi `mail_plan_set` trả `insufficient_funds`, gọi `cloud_topup`, đưa VietQR cho user và chờ `cloud_balance` cập nhật trước khi thử lại. Không yêu cầu user mở dashboard lấy API key. Lỗi Mail giữ `code`, `message`, `next_step`, `request_id` từ API, gồm `domain_not_verified`, `quota_exceeded`, `budget_exceeded` và `idempotency_conflict`.
+
+### Sandbox và idempotency Mail
+
+- MCP: `mail_send({ ..., sandbox: true })` gửi `X-Mona-Sandbox: 1`, kết quả có `sandbox: true`.
+- App: key `mm_test_` bật sandbox qua SDK; key `mm_live_` dùng để gửi thật. `MONACLOUD_SANDBOX` dành cho compute, không tự bật sandbox Mail.
+- Sandbox đi qua pipeline nhưng không gửi ra Internet, không tính quota hoặc trừ ví. Dùng `mail_status` để đọc trạng thái `sandbox` và `sandbox_preview`; không báo thư sandbox đã được giao thật.
+- Mọi POST Mail có header `Idempotency-Key`: dùng tham số `idempotency_key` hoặc MCP tự tạo `mcp-mail-<uuid>`. Khi retry phải truyền cùng key và giữ nguyên body trong TTL 24 giờ. Cùng key/body trả response cũ, khác body trả 409 `idempotency_conflict`. Nếu bỏ key, mỗi lần gọi MCP là yêu cầu mới.
+
 ## Spend guard
 
 `cloud_vps_create`, `cloud_db_create`, `cloud_service_start` và `cloud_service_rebuild` đọc `GET /v1/balance` trước khi gọi sản phẩm thật. Upstream vẫn là nguồn quyết định cuối và có thể trả:
@@ -168,7 +211,12 @@ Sandbox không gọi Proxmox, không cấp IP thật, không trừ tiền và c
 - Đọc `monacloud://llms` khi cần bối cảnh toàn hệ sinh thái.
 - Đọc `monacloud://status` trước khi kết luận lỗi là do credential hoặc request.
 - Dùng prompt `dung-app-ban-hang-monacloud` để lấy chuỗi tác vụ chuẩn.
+- Dùng prompt `gui-mail-otp-monamail` để tích hợp OTP, DNS, API key và webhook Mail.
 
 ## Tiêu chí hoàn tất
 
 Một lượt được coi là xong khi app và database chạy, webhook HMAC test pass, sandbox checkout chuyển `paid`, credential nằm trong secret store, và agent báo lại URL cùng trạng thái dịch vụ. Không coi việc “đã tạo job” là hoàn tất; phải poll tới terminal state và kiểm health thực tế.
+
+## Wave A/B (0.3.0)
+
+Xem [bảng tool và hợp đồng HTTP](wave-ab.md) cho 15 tool mới, VPS monthly, subscriptions, invoices/PDF, credit và app từ git. Khi user nói “deploy repo”, dùng `cloud_app_create`; `agent_deploy` vẫn là stub cho runtime template. Đọc → ước tính → hỏi duyệt nếu chưa được duyệt → làm. Chưa có app host thì sandbox trước, sau khi hoàn tất kiểm URL thật.

package/docs/wave-ab.md

@@ -0,0 +1,73 @@
+# Wave A/B — gói tháng, hoá đơn và app từ git (0.3.0)
+
+Luồng mặc định: **đọc → ước tính VND → hỏi duyệt nếu chưa được duyệt → làm → kiểm kết quả**. Các tool dưới đây đều có alias `vibecloud_` cùng hậu tố, schema và hành vi; riêng alias VPS cũ vẫn là `vibecloud_create_vps`.
+
+## Bảng tool
+
+| Tool | HTTP compute | Dùng khi |
+|---|---|---|
+| `cloud_plan_list` | GET `/api/plans` | Xem giá tháng/năm, cấu hình, included_db/backup; gợi ý gói rẻ nhất đủ CPU/RAM/đĩa yêu cầu, không tự chọn admin_only |
+| `cloud_vps_create` | POST `/api/lxc` | Hourly như cũ; monthly nhận `plan_code`, `period: month|year`, trả `estimate` và job |
+| `cloud_subscription_list` | GET `/api/subscriptions` | Đọc gói, kỳ gia hạn, auto-renew |
+| `cloud_subscription_update` | POST `/api/services/{service_id}/subscription` | `plan_code`, `period`, `auto_renew`, `cancel_action: hourly|stop`; ít nhất một thay đổi |
+| `cloud_invoice_list` | GET `/api/invoices` | Đọc hoá đơn tài khoản |
+| `cloud_invoice_pdf` | GET `/api/invoices/{invoice_id}.pdf` | Lưu nguyên bytes vào file tạm 0600 trong thư mục riêng 0700, trả `path` |
+| `cloud_credit_redeem` | POST `/api/credit-codes/redeem` | Body `{code}`, trim/uppercase; không tự đoán mã |
+| `cloud_app_create` | POST `/api/apps` → GET `/api/jobs/{id}` | Deploy public repo HTTPS, tự poll và trả URL; **đang mở** |
+| `cloud_app_list` | GET `/api/apps` | Tránh tạo trùng app; **đang mở** |
+| `cloud_app_get` | GET `/api/apps/{app_id}` | Status, URL, last_deploy, app host; **đang mở** |
+| `cloud_app_deploy` | POST `/api/apps/{app_id}/deploy` → job | Deploy lại sau sửa code/env; **đang mở** |
+| `cloud_app_env_set` | PUT `/api/apps/{app_id}/env` | Body `{env: {KEY: "value"}}`, thay toàn bộ env; deploy lại để áp dụng; **đang mở** |
+| `cloud_app_domain_add` | POST `/api/apps/{app_id}/domains` | Body `{host}`, trả hướng dẫn CNAME; **đang mở** |
+| `cloud_app_logs` | GET `/api/apps/{app_id}/logs?deployment=...` | Tối đa 500 dòng, giữ log có secret riêng tư; **đang mở** |
+| `cloud_app_delete` | DELETE `/api/apps/{app_id}` | Xoá app/domain/A record sau khi được duyệt; host vẫn có thể tính phí; **đang mở** |
+| `cloud_app_host_list` | GET `/api/app-hosts` | Đọc host, tài nguyên và phí; **đang mở** |
+
+## Gói tháng/năm
+
+```text
+cloud_plan_list({ ram_gb: 4 })
+cloud_balance()
+# Báo đúng price_month_vnd hoặc price_year_vnd, hỏi duyệt nếu chưa có.
+cloud_vps_create({ app_name: "shop", billing_mode: "monthly", plan_code: "kinh-doanh", period: "month" })
+cloud_job_status({ job_id: "<id trả về>" })
+cloud_subscription_list()
+cloud_subscription_update({ service_id: "<service_id>", auto_renew: false, cancel_action: "stop" })
+cloud_invoice_list()
+cloud_invoice_pdf({ invoice_id: "<invoice_id>" })
+cloud_credit_redeem({ code: "<mã người dùng cung cấp>" })
+```
+
+Monthly bỏ `package_slug`, CPU/RAM/đĩa trong payload trước khi gửi, lấy cấu hình từ plan. Spend guard so sánh số dư với **toàn bộ giá kỳ đã chọn**, không chỉ số dư dương. Plan giá 0 được phép với ví 0; API vẫn kiểm quyền gói admin. Giá đọc từ API, không hard-code. Nâng gói tính prorate và hạ gói kỳ sau do backend quyết định; MCP không tự tính khoản prorate hoặc chặn huỷ khi ví hết tiền.
+
+Wave A hiện từ chối monthly trong sandbox. `cloud_vps_create` monthly + sandbox lấy CPU/RAM/đĩa từ plan, gửi request **hourly sandbox** với `X-Vibecloud-Sandbox: 1`; trả `estimate` là giá gói thật, `requested_billing_mode: monthly`, `preview_billing_mode: hourly`. Không tạo subscription và không trừ tiền. Được duyệt rồi mới gọi monthly thật, tắt cả tham số sandbox và `MONACLOUD_SANDBOX` nếu env đang bật.
+
+PDF là file tạm trên máy chạy MCP, không phải máy từ xa của người chat. Sao chép file nếu cần giữ lâu; hệ điều hành có thể dọn thư mục tạm. Không dùng filename từ server làm đường dẫn local, không follow redirect có bearer token, không chuyển PDF qua text/JSON.
+
+## Deploy repo: 3 bước
+
+1. Đọc repo/nhánh/build/domain, `cloud_app_list`, `cloud_app_host_list`, `cloud_prices`, `cloud_packages`. Nếu chưa có host, gọi `cloud_app_create` sandbox trước để lấy `result.estimated_app_host` (MCP cũng trả thành `estimate`) và URL thử. Đọc `cloud_balance` trước tạo thật.
+2. Báo chi phí host, repo, nhánh và domain, hỏi duyệt nếu chưa được duyệt. Gói tháng cần giá đúng kỳ; app dùng host hiện có vẫn tiếp tục phí host. Sandbox không cần ví, không cần duyệt chi phí.
+3. `cloud_app_create` thật, chờ terminal job, đọc `cloud_app_get`/`cloud_app_logs`, kiểm HTTPS/health rồi báo URL. Khi có host, truyền `app_host_id` để dùng lại. Custom domain dùng `cloud_app_domain_add`, làm theo CNAME và chờ SSL.
+
+```text
+cloud_app_create({ repo_url: "https://github.com/example/shop.git", branch: "main", build_type: "nixpacks", port: 3000, env: {}, sandbox: true })
+# Đọc estimate, duyệt, rồi:
+cloud_app_create({ repo_url: "https://github.com/example/shop.git", branch: "main", build_type: "nixpacks", port: 3000, env: {}, sandbox: false })
+cloud_app_env_set({ app_id: "<app_id>", env: { NODE_ENV: "production" } })
+cloud_app_deploy({ app_id: "<app_id>" })
+cloud_app_domain_add({ app_id: "<app_id>", host: "shop.example.vn" })
+cloud_app_logs({ app_id: "<app_id>", deployment: "<deployment_id>" })
+```
+
+`cloud_app_create` mặc định branch=`main`, build_type=`dockerfile`, dockerfile=`Dockerfile`, env=`{}`, port=`3000`, wait=`true`, interval_sec=`3`, timeout_sec=`600`. Build có `dockerfile|nixpacks|static`. `wait: false` trả job để client tự poll; nên dùng nếu MCP host giới hạn mỗi tool dưới 10 phút. `done`/`succeeded` là hoàn tất; `failed`/`error`/`cancelled` trả lỗi `app_deploy_failed`. Timeout giữ job_id và next_step để poll tiếp; không tự gửi lại POST.
+
+Wave B hiện nhận **public HTTPS repo** không credential/query/fragment. CLI đổi remote `git@host:owner/repo.git` hoặc `ssh://git@host/owner/repo.git` sang HTTPS; điều đó không cấp quyền repo private. Không đưa token vào URL. Env là map string, tối đa 200 key/64 KiB; không in secret hoặc log build ra công khai.
+
+Sandbox app dùng `X-Vibecloud-Sandbox: 1` cho các endpoint app. Job được tìm theo ID; không cần header khi poll. `MONACLOUD_SANDBOX=1` cũng bật sandbox và không thể bị `sandbox:false` ghi đè. Lỗi 404/503 khi endpoint chưa mở được trả nguyên theo API, không có thành công giả.
+
+Prompt mẫu: “Deploy repo hiện tại lên MONA Cloud. Kiểm host và giá, sandbox trước nếu chưa có host, báo chi phí để tôi duyệt rồi deploy thật và kiểm URL.”
+
+## Nguồn hợp đồng offline
+
+Snapshot `ctx/openapi.json` được giao vẫn ghi API `0.2.0`, chưa có Wave A/B. Đã đối chiếu **file local** `vibecloud/app/schemas.py`, `app/routers/api.py` cho Wave A; Wave B theo `ctx/BRIEF-CODEX-WAVE-B-APPS.md` §2–4 và đối chiếu thêm `vibecloud/app/routers/apps.py`, `app/sandbox.py`. Vì brief cũ trong `SPEC-WAVE-B-APP-TU-GIT.md` ghi POST env và `?deploy=`, implementation dùng hợp đồng mới hơn: **PUT env, `?deployment=`**. Không sửa snapshot cũ để tránh gán nhầm provenance; không gọi endpoint production.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monacloud-mcp",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Unified MCP server for MONA Cloud, MONA Pay and MONA Agent.",
   "license": "MIT",
   "type": "module",