neoagent 3.0.1-beta.2 → 3.0.1-beta.21

package/server/services/ai/tools.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const { analyzeImageForUser } = require('./imageAnalysis');
+const { isPrivateHost, validateCloudUrl } = require('../../utils/cloud-security');
 const db = require('../../db/database');
 const { DATA_DIR } = require('../../../runtime/paths');
 const { isMainAgent } = require('../agents/manager');
@@ -96,12 +97,35 @@ function compactToolDefinition(tool, options = {}) {
     return compact;
 }
 
+// A bare 5-field cron expression: "m h dom mon dow" (seconds unsupported).
+const CRON_5_FIELD_RE = /^(\S+\s+){4}\S+$/;
+
+function coerceScheduleTriggerConfig(inputConfig) {
+    // Models frequently pass the schedule config as a JSON string, or as a bare
+    // cron expression / ISO datetime instead of an object. Coerce those shapes to
+    // an object so a correct intent is not rejected over packaging.
+    if (typeof inputConfig !== 'string') return inputConfig;
+    const raw = inputConfig.trim();
+    if (!raw) return inputConfig;
+    if (raw.startsWith('{') || raw.startsWith('[')) {
+        try {
+            return JSON.parse(raw);
+        } catch {
+            return inputConfig;
+        }
+    }
+    if (CRON_5_FIELD_RE.test(raw)) return { mode: 'recurring', cronExpression: raw };
+    if (!Number.isNaN(Date.parse(raw))) return { mode: 'one_time', runAt: raw };
+    return inputConfig;
+}
+
 function normalizeScheduleTriggerConfig(inputConfig = {}) {
-    if (!inputConfig || typeof inputConfig !== 'object' || Array.isArray(inputConfig)) {
-        return inputConfig;
+    const coerced = coerceScheduleTriggerConfig(inputConfig);
+    if (!coerced || typeof coerced !== 'object' || Array.isArray(coerced)) {
+        return coerced;
     }
 
-    const normalized = { ...inputConfig };
+    const normalized = { ...coerced };
     const schedule = (normalized.schedule && typeof normalized.schedule === 'object' && !Array.isArray(normalized.schedule))
         ? normalized.schedule
         : null;
@@ -216,7 +240,7 @@ function validateProactiveSendMessageArgs({ purpose, normalizedMessage }) {
     }
 
     if (normalizedPurpose === 'no_response') {
-        if (normalizedMessage !== '[NO RESPONSE]') {
+        if (normalizedMessage && normalizedMessage !== '[NO RESPONSE]') {
             return {
                 ok: false,
                 error: 'purpose=no_response requires content "[NO RESPONSE]".',
@@ -252,7 +276,33 @@ function getRunState(engine, runId) {
 
 function hasAlreadySentProactiveMessage({ triggerSource, runState, deliveryState, allowMultipleProactiveMessages }) {
     if (!isProactiveTrigger(triggerSource) || allowMultipleProactiveMessages) return false;
-    return Boolean(runState?.messagingSent || deliveryState?.messagingSent);
+    return Boolean(
+        runState?.messagingSent
+        || deliveryState?.messagingSent
+        || runState?.proactiveMessageStaged
+        || deliveryState?.proactiveMessageStaged
+    );
+}
+
+function markProactiveMessageStaged({ runState, deliveryState, platform, to, content, purpose, mediaPath = null }) {
+    const staged = {
+        platform: String(platform || '').trim(),
+        to: String(to || '').trim(),
+        content: String(content || '').trim(),
+        purpose: String(purpose || '').trim().toLowerCase(),
+        mediaPath: mediaPath || null,
+        stagedAt: new Date().toISOString(),
+    };
+
+    if (runState) {
+        runState.proactiveMessageStaged = true;
+        runState.stagedProactiveMessage = staged;
+    }
+
+    if (deliveryState) {
+        deliveryState.proactiveMessageStaged = true;
+        deliveryState.stagedProactiveMessage = staged;
+    }
 }
 
 function markProactiveMessageSent({ runState, deliveryState, content }) {
@@ -866,7 +916,7 @@ function getAvailableTools(app, options = {}) {
         },
         {
             name: 'send_message',
-            description: `Send a message on a connected messaging platform. Supports WhatsApp (text/media), Telnyx Voice (phone calls — TTS), Discord, Telegram, Slack, Google Chat, Microsoft Teams, Matrix, Signal, iMessage/BlueBubbles, IRC, Feishu, LINE, Mattermost, Nextcloud Talk, Nostr, Synology Chat, Tlon, Twitch, Zalo, WeChat, WebChat, and configurable webhook bridges. ${buildSendMessageFormattingReference()} For WhatsApp: use media_path to attach files. Use content "[NO RESPONSE]" only when the user explicitly asked for silence or no reply. For background task or schedule runs, set purpose to final_result, blocker, or no_response.`,
+            description: `Send a message on a connected messaging platform. Supports WhatsApp (text/media), Telnyx Voice (phone calls — TTS), Discord, Telegram, Slack, Google Chat, Microsoft Teams, Matrix, Signal, iMessage/BlueBubbles, IRC, Feishu, LINE, Mattermost, Nextcloud Talk, Nostr, Synology Chat, Tlon, Twitch, Zalo, WeChat, WebChat, and configurable webhook bridges. ${buildSendMessageFormattingReference()} For WhatsApp: use media_path to attach files. Use content "[NO RESPONSE]" only when the user explicitly asked for silence/no reply, or when a background task intentionally decides no user-visible update is needed with purpose="no_response". For background task or schedule runs, set purpose to final_result, blocker, or no_response.`,
             parameters: {
                 type: 'object',
                 properties: {
@@ -1452,6 +1502,30 @@ function getAvailableTools(app, options = {}) {
                 required: ['query']
             }
         },
+        {
+            name: 'list_chats',
+            description: 'List all known groups and conversations across connected messaging platforms. Use this when the user doesn\'t know the exact group name or chat ID — it returns every chat that has ever sent a message, with platform, chat ID, display name, and whether it\'s a group or DM.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    platform: { type: 'string', description: 'Filter to a specific platform (e.g. telegram, whatsapp, discord). Omit to list chats across all platforms.' },
+                }
+            }
+        },
+        {
+            name: 'read_messages',
+            description: 'Read recent messages from a connected messaging platform group or conversation. Use this to get recaps, search history, or summarize what\'s been going on in a Telegram group, WhatsApp chat, Discord channel, Slack channel, or any other connected platform. Messages are stored locally from inbound traffic.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    platform: { type: 'string', description: 'Platform name (e.g. telegram, whatsapp, discord, slack, signal, teams). Omit to search across all connected platforms.' },
+                    chat_id: { type: 'string', description: 'Exact platform chat or group ID. Use this when known.' },
+                    group_name: { type: 'string', description: 'Group, channel, or chat name to find (case-insensitive partial match). Use when you don\'t know the exact chat_id.' },
+                    limit: { type: 'number', description: 'Max messages to return (default 20, max 100).' },
+                    search: { type: 'string', description: 'Optional keyword to filter messages by content.' },
+                }
+            }
+        },
         {
             name: 'social_video_extract',
             description: 'Extract title, description, transcript, and one representative frame image from a public social video URL (YouTube, TikTok, Instagram, or X) without social API keys.',
@@ -1503,11 +1577,11 @@ function getAvailableTools(app, options = {}) {
             0,
             {
                 name: 'send_interim_update',
-                description: 'Send a short real interim assistant update when it helps.',
+                description: 'Send a short user-visible interim update only when there is materially useful new progress, a real blocker, or a blocking question. Never use this for internal monologue, self-checks, tool bookkeeping, or "nothing happened" status.',
                 parameters: {
                     type: 'object',
                     properties: {
-                        content: { type: 'string', description: 'Natural assistant message derived from the current task state.' },
+                        content: { type: 'string', description: 'Natural assistant message derived from user-relevant task state, not internal reasoning or progress-supervisor bookkeeping.' },
                         kind: { type: 'string', enum: Array.from(INTERIM_KINDS), description: 'ack, progress, question, or blocker' },
                         expects_reply: { type: 'boolean', description: 'Set true only when the current run should pause for the user to answer.' },
                         defer_follow_up: { type: 'boolean', description: 'Set true when you choose to deliver the final result later via the user\'s last connected chat target.' }
@@ -1592,14 +1666,6 @@ function normalizeReadFileArgs(args = {}) {
     };
 }
 
-/**
- * Executes a tool by name.
- * @param {string} toolName - Name of the tool.
- * @param {object} args - Tool arguments.
- * @param {object} context - Execution context (userId, runId, etc).
- * @param {object} engine - AgentEngine instance.
- * @returns {Promise<any>} Execution result.
- */
 async function executeTool(toolName, args, context, engine) {
     const {
         userId,
@@ -1714,6 +1780,8 @@ async function executeTool(toolName, args, context, engine) {
         }
 
         case 'browser_navigate': {
+            const urlCheck = validateCloudUrl(args.url);
+            if (!urlCheck.allowed) return { error: 'URL is not allowed: blocked scheme or private/internal network address.' };
             const { provider, backend } = await bc();
             if (!provider) return { error: 'Browser controller not available' };
             return { ...await provider.navigate(args.url, {
@@ -2227,6 +2295,91 @@ async function executeTool(toolName, args, context, engine) {
             };
         }
 
+        case 'list_chats': {
+            const listPlatform = typeof args.platform === 'string' ? args.platform.trim().toLowerCase() : null;
+
+            let listQuery = `SELECT platform, platform_chat_id, metadata
+                FROM messages
+                WHERE user_id = ? AND platform_chat_id IS NOT NULL AND platform != 'web'`;
+            const listParams = [userId];
+
+            if (listPlatform) { listQuery += ' AND platform = ?'; listParams.push(listPlatform); }
+            listQuery += ' ORDER BY id DESC LIMIT 2000';
+
+            const listRows = db.prepare(listQuery).all(...listParams);
+
+            const chatMap = new Map();
+            for (const row of listRows) {
+                const key = `${row.platform}:${row.platform_chat_id}`;
+                if (chatMap.has(key)) continue;
+                let meta = {};
+                try { meta = row.metadata ? JSON.parse(row.metadata) : {}; } catch {}
+                const isGroup = String(meta.isGroup || '').match(/^(true|1)$/i) != null && String(meta.isGroup || '') !== '';
+                const name = (meta.groupName || meta.group_name || meta.guildName || meta.guild_name || meta.chatName || meta.chat_name || '').trim()
+                    || (meta.senderName || meta.sender_name || '').trim()
+                    || null;
+                chatMap.set(key, {
+                    platform: row.platform,
+                    chat_id: row.platform_chat_id,
+                    name,
+                    type: isGroup ? 'group' : 'dm',
+                });
+            }
+
+            const chats = Array.from(chatMap.values());
+            return {
+                count: chats.length,
+                chats,
+            };
+        }
+
+        case 'read_messages': {
+            const msgLimit = Math.max(1, Math.min(Number(args.limit) || 20, 100));
+            const msgPlatform = typeof args.platform === 'string' ? args.platform.trim().toLowerCase() : null;
+            const msgChatId = typeof args.chat_id === 'string' ? args.chat_id.trim() : null;
+            const msgGroupName = typeof args.group_name === 'string' ? args.group_name.trim().toLowerCase() : null;
+            const msgSearch = typeof args.search === 'string' ? args.search.trim() : null;
+
+            let msgQuery = "SELECT role, content, platform, platform_chat_id, metadata, created_at FROM messages WHERE user_id = ? AND role = 'user'";
+            const msgParams = [userId];
+
+            if (msgPlatform) { msgQuery += ' AND platform = ?'; msgParams.push(msgPlatform); }
+            if (msgChatId) { msgQuery += ' AND platform_chat_id = ?'; msgParams.push(msgChatId); }
+            if (msgSearch) { msgQuery += ' AND content LIKE ?'; msgParams.push(`%${msgSearch}%`); }
+
+            msgQuery += ' ORDER BY created_at DESC LIMIT ?';
+            msgParams.push(msgGroupName ? Math.min(msgLimit * 10, 500) : msgLimit);
+
+            const msgRows = db.prepare(msgQuery).all(...msgParams);
+
+            let filteredRows = msgRows;
+            if (msgGroupName) {
+                filteredRows = msgRows.filter((row) => {
+                    try {
+                        const meta = row.metadata ? JSON.parse(row.metadata) : {};
+                        const name = (meta.groupName || meta.group_name || meta.guildName || meta.guild_name || meta.chatName || meta.chat_name || row.platform_chat_id || '').toLowerCase();
+                        return name.includes(msgGroupName);
+                    } catch { return false; }
+                }).slice(0, msgLimit);
+            }
+
+            return {
+                count: filteredRows.length,
+                messages: filteredRows.reverse().map((row) => {
+                    let meta = {};
+                    try { meta = row.metadata ? JSON.parse(row.metadata) : {}; } catch {}
+                    return {
+                        platform: row.platform,
+                        chat_id: row.platform_chat_id,
+                        group_name: meta.groupName || meta.group_name || meta.guildName || meta.guild_name || null,
+                        sender: meta.senderName || meta.sender_name || null,
+                        content: row.content,
+                        timestamp: row.created_at,
+                    };
+                }),
+            };
+        }
+
         case 'social_video_extract': {
             const service = socialVideo();
             if (!service || typeof service.extractFromUrl !== 'function') {
@@ -2358,6 +2511,26 @@ async function executeTool(toolName, args, context, engine) {
                 };
             }
 
+            if (isProactiveTrigger(triggerSource) && context.stageProactiveMessages === true && !suppressReply) {
+                markProactiveMessageStaged({
+                    runState,
+                    deliveryState,
+                    platform: args.platform,
+                    to: args.to,
+                    content: normalizedMessage,
+                    purpose: args.purpose,
+                    mediaPath: args.media_path,
+                });
+                return {
+                    success: true,
+                    staged: true,
+                    purpose: normalizeSendMessagePurpose(args.purpose),
+                    platform: args.platform,
+                    to: args.to,
+                    content: normalizedMessage,
+                };
+            }
+
             const sendResult = await manager.sendMessage(userId, args.platform, args.to, args.content, {
                 agentId,
                 mediaPath: args.media_path,
@@ -2555,6 +2728,22 @@ async function executeTool(toolName, args, context, engine) {
         }
 
         case 'http_request': {
+            let parsedUrl;
+            try { parsedUrl = new URL(args.url); } catch {
+                return { error: 'Invalid URL' };
+            }
+            const scheme = parsedUrl.protocol.replace(/:$/, '').toLowerCase();
+            if (!['http', 'https'].includes(scheme)) {
+                return { error: 'URL scheme not allowed. Only http and https are permitted.' };
+            }
+            const h = parsedUrl.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+            if (h === 'localhost' || h === '127.0.0.1' || h === '::1' || h.endsWith('.localhost')) {
+                return { error: 'Loopback addresses are not permitted.' };
+            }
+            const allowPrivate = process.env.NEOAGENT_HTTP_ALLOW_PRIVATE !== 'false';
+            if (!allowPrivate && isPrivateHost(parsedUrl.hostname)) {
+                return { error: 'Private/internal network addresses are not permitted.' };
+            }
             const controller = new AbortController();
             const timeoutMs = args.timeout_ms || 30000;
             const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -2571,11 +2760,28 @@ async function executeTool(toolName, args, context, engine) {
                     }
                 }
                 const res = await fetch(args.url, options);
-                const text = await res.text();
+                const MAX_BODY = 512 * 1024;
+                const reader = res.body.getReader();
+                const chunks = [];
+                let total = 0;
+                let truncated = false;
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) break;
+                    total += value.length;
+                    if (total > MAX_BODY) {
+                        const take = MAX_BODY - (total - value.length);
+                        if (take > 0) chunks.push(value.slice(0, take));
+                        truncated = true;
+                        break;
+                    }
+                    chunks.push(value);
+                }
+                const text = Buffer.concat(chunks.map(c => Buffer.from(c))).toString('utf-8');
                 return {
                     status: res.status,
                     headers: Object.fromEntries(res.headers.entries()),
-                    body: text.length > 50000 ? text.slice(0, 50000) + '\n...[truncated]' : text
+                    body: truncated ? text + '\n...[truncated]' : text,
                 };
             } catch (err) {
                 if (err.name === 'AbortError') return { error: `Request timed out after ${timeoutMs} ms` };
@@ -3058,7 +3264,6 @@ async function executeTool(toolName, args, context, engine) {
 
         case 'ocr_extract': {
             try {
-                const fs = require('fs');
                 if (!fs.existsSync(args.image_path)) {
                     return { error: 'File not found: ' + args.image_path };
                 }
@@ -3175,4 +3380,10 @@ async function executeTool(toolName, args, context, engine) {
     }
 }
 
-module.exports = { getAvailableTools, executeTool, validateProactiveSendMessageArgs };
+module.exports = {
+    getAvailableTools,
+    executeTool,
+    validateProactiveSendMessageArgs,
+    resolveTaskTriggerArgs,
+    normalizeScheduleTriggerConfig,
+};

package/server/services/android/controller.js

@@ -582,7 +582,8 @@ class AndroidController {
     });
 
     progress('Waiting for Android to boot (can take 2–5 min on first run)…');
-    await this.#waitForBoot();
+    // Abort early if the emulator process dies, instead of polling until timeout.
+    await this.#waitForBoot({ isAlive: () => this.#isPidAlive(proc.pid) });
 
     writeState(this.userId, { bootstrapped: true, starting: false, startupPhase: null, lastStartError: null });
     console.log(`[Android] Emulator ready on ${this.adbSerial}`);
@@ -593,10 +594,13 @@ class AndroidController {
     });
   }
 
-  async #waitForBoot(timeoutMs = 10 * 60 * 1000) {
+  async #waitForBoot({ timeoutMs = 10 * 60 * 1000, isAlive = () => true } = {}) {
     const adb = adbBin(this.sdkDir);
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
+      if (!isAlive()) {
+        throw new Error('Emulator process exited before Android finished booting (check virtualization/KVM support and the system image).');
+      }
       try {
         const r = spawnSync(adb, ['-s', this.adbSerial, 'shell', 'getprop', 'sys.boot_completed'], { encoding: 'utf8', timeout: 5000 });
         if (r.stdout?.trim() === '1') return;

package/server/services/billing/billing_email.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const { isBillingEnabled } = require('./config');
+
+// Lazy-load to avoid circular dependencies at startup.
+function sendServiceEmail() {
+  return require('../account/service_email').sendServiceEmail;
+}
+
+function isEmailAvailable() {
+  try {
+    return require('../account/service_email').isServiceEmailConfigured();
+  } catch {
+    return false;
+  }
+}
+
+function fmtDate(tsOrSeconds) {
+  if (!tsOrSeconds) return 'unknown';
+  const ms = typeof tsOrSeconds === 'number' && tsOrSeconds < 1e12
+    ? tsOrSeconds * 1000
+    : Number(tsOrSeconds);
+  return new Date(ms).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
+}
+
+async function send(user, message) {
+  if (!isBillingEnabled() || !isEmailAvailable()) return;
+  if (!user?.email) return;
+  try {
+    await sendServiceEmail()(user.email, message);
+  } catch {
+    // Best-effort; billing emails are non-critical.
+  }
+}
+
+async function sendTrialStarted(user, plan, trialEndTs) {
+  await send(user, {
+    subject: `Your ${plan?.name || 'trial'} trial has started`,
+    heading: 'Trial started',
+    body: `Your free trial of the ${plan?.name || 'plan'} plan is now active.`,
+    details: [{ label: 'Trial ends', value: fmtDate(trialEndTs) }],
+  });
+}
+
+async function sendTrialEnding(user, plan, trialEndTs) {
+  await send(user, {
+    subject: `Your ${plan?.name || ''} trial ends soon`,
+    heading: 'Trial ending soon',
+    body: `Your free trial of the ${plan?.name || 'plan'} plan will end on ${fmtDate(trialEndTs)}. Add a payment method to continue without interruption.`,
+    details: [{ label: 'Trial ends', value: fmtDate(trialEndTs) }],
+  });
+}
+
+async function sendSubscriptionStarted(user, plan) {
+  await send(user, {
+    subject: `Welcome to ${plan?.name || 'your subscription'}`,
+    heading: 'Subscription active',
+    body: `Your ${plan?.name || 'subscription'} plan is now active.`,
+  });
+}
+
+async function sendSubscriptionRenewed(user, plan) {
+  await send(user, {
+    subject: `Your ${plan?.name || 'subscription'} has been renewed`,
+    heading: 'Subscription renewed',
+    body: `Your ${plan?.name || 'subscription'} plan has been successfully renewed.`,
+  });
+}
+
+async function sendPaymentFailed(user, plan, nextRetryAt) {
+  const details = nextRetryAt
+    ? [{ label: 'Next retry', value: fmtDate(nextRetryAt) }]
+    : [];
+  await send(user, {
+    subject: 'Payment failed — action required',
+    heading: 'Payment failed',
+    body: `We were unable to charge your payment method for the ${plan?.name || 'subscription'} plan. Please update your billing details to avoid losing access.`,
+    details,
+  });
+}
+
+async function sendSubscriptionCanceled(user, plan) {
+  await send(user, {
+    subject: `Your ${plan?.name || 'subscription'} has been canceled`,
+    heading: 'Subscription canceled',
+    body: `Your ${plan?.name || 'subscription'} plan has been canceled. You may resubscribe at any time.`,
+  });
+}
+
+async function sendPlanChanged(user, _oldPlan, newPlan) {
+  await send(user, {
+    subject: `Your plan has changed to ${newPlan?.name || 'a new plan'}`,
+    heading: 'Plan updated',
+    body: `Your subscription has been updated to the ${newPlan?.name || 'new'} plan.`,
+  });
+}
+
+module.exports = {
+  sendTrialStarted,
+  sendTrialEnding,
+  sendSubscriptionStarted,
+  sendSubscriptionRenewed,
+  sendPaymentFailed,
+  sendSubscriptionCanceled,
+  sendPlanChanged,
+};

package/server/services/billing/config.js

@@ -0,0 +1,17 @@
+'use strict';
+
+function isBillingEnabled() {
+  const v = process.env.NEOAGENT_BILLING_ENABLED;
+  return v === '1' || v === 'true';
+}
+
+function getStripeConfig() {
+  return {
+    secretKey: process.env.STRIPE_SECRET_KEY,
+    webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+    publicKey: process.env.STRIPE_PUBLISHABLE_KEY,
+    trialDays: parseInt(process.env.BILLING_TRIAL_DAYS || '14', 10),
+  };
+}
+
+module.exports = { isBillingEnabled, getStripeConfig };

package/server/services/billing/plans.js

@@ -0,0 +1,121 @@
+'use strict';
+
+const { randomUUID } = require('crypto');
+const db = require('../../db/database');
+
+function listPlans({ includeInactive = false } = {}) {
+  const sql = includeInactive
+    ? 'SELECT * FROM billing_plans ORDER BY sort_order ASC, created_at ASC'
+    : 'SELECT * FROM billing_plans WHERE is_active = 1 ORDER BY sort_order ASC, created_at ASC';
+  return db.prepare(sql).all().map(parsePlan);
+}
+
+function getPlan(planId) {
+  const row = db.prepare('SELECT * FROM billing_plans WHERE id = ?').get(planId);
+  return row ? parsePlan(row) : null;
+}
+
+function getFreePlan() {
+  const row = db.prepare(
+    'SELECT * FROM billing_plans WHERE price_cents = 0 AND is_active = 1 ORDER BY sort_order ASC LIMIT 1',
+  ).get();
+  return row ? parsePlan(row) : null;
+}
+
+function validatePlanData(data, requireName = true) {
+  if (requireName && !data.name?.trim()) {
+    throw Object.assign(new Error('Plan name is required.'), { statusCode: 400 });
+  }
+  if (data.price_cents !== undefined && (!Number.isInteger(data.price_cents) || data.price_cents < 0)) {
+    throw Object.assign(new Error('price_cents must be a non-negative integer.'), { statusCode: 400 });
+  }
+  if (data.currency !== undefined && !/^[a-z]{3}$/i.test(data.currency)) {
+    throw Object.assign(new Error('currency must be a 3-letter ISO code.'), { statusCode: 400 });
+  }
+  if (data.interval !== undefined && data.interval !== null && !['month', 'year'].includes(data.interval)) {
+    throw Object.assign(new Error('interval must be "month", "year", or null.'), { statusCode: 400 });
+  }
+  if (data.id !== undefined && !/^[a-zA-Z0-9_-]+$/.test(data.id)) {
+    throw Object.assign(new Error('Plan ID may only contain letters, numbers, underscores, and hyphens.'), { statusCode: 400 });
+  }
+}
+
+function createPlan(data) {
+  validatePlanData(data, true);
+  const id = data.id || `plan_${randomUUID().replace(/-/g, '')}`;
+  // UTC timestamp without timezone marker — SQLite stores it as TEXT in ISO-like format.
+  const now = new Date().toISOString().replace('T', ' ').replace(/\.\d{3}Z$/, '');
+  db.prepare(`
+    INSERT INTO billing_plans
+      (id, name, description, price_cents, currency, interval, stripe_price_id,
+       token_limit_4h, token_limit_weekly, allowed_models_json, features_json,
+       is_active, sort_order, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    id,
+    data.name,
+    data.description || '',
+    data.price_cents ?? 0,
+    data.currency || 'usd',
+    data.interval ?? 'month',
+    data.stripe_price_id ?? null,
+    data.token_limit_4h ?? null,
+    data.token_limit_weekly ?? null,
+    JSON.stringify(data.allowed_models ?? []),
+    JSON.stringify(data.features ?? []),
+    data.is_active !== false ? 1 : 0,
+    data.sort_order ?? 0,
+    now,
+    now,
+  );
+  return getPlan(id);
+}
+
+function updatePlan(planId, data) {
+  validatePlanData(data, false);
+  const now = new Date().toISOString().replace('T', ' ').replace(/\.\d{3}Z$/, '');
+  const fields = [];
+  const values = [];
+
+  if (data.name !== undefined) { fields.push('name = ?'); values.push(data.name); }
+  if (data.description !== undefined) { fields.push('description = ?'); values.push(data.description); }
+  if (data.price_cents !== undefined) { fields.push('price_cents = ?'); values.push(data.price_cents); }
+  if (data.currency !== undefined) { fields.push('currency = ?'); values.push(data.currency); }
+  if (data.interval !== undefined) { fields.push('interval = ?'); values.push(data.interval); }
+  if (data.stripe_price_id !== undefined) { fields.push('stripe_price_id = ?'); values.push(data.stripe_price_id); }
+  if (data.token_limit_4h !== undefined) { fields.push('token_limit_4h = ?'); values.push(data.token_limit_4h); }
+  if (data.token_limit_weekly !== undefined) { fields.push('token_limit_weekly = ?'); values.push(data.token_limit_weekly); }
+  if (data.allowed_models !== undefined) { fields.push('allowed_models_json = ?'); values.push(JSON.stringify(data.allowed_models)); }
+  if (data.features !== undefined) { fields.push('features_json = ?'); values.push(JSON.stringify(data.features)); }
+  if (data.is_active !== undefined) { fields.push('is_active = ?'); values.push(data.is_active ? 1 : 0); }
+  if (data.sort_order !== undefined) { fields.push('sort_order = ?'); values.push(data.sort_order); }
+
+  if (!fields.length) return getPlan(planId);
+
+  fields.push('updated_at = ?');
+  values.push(now);
+  values.push(planId);
+
+  db.prepare(`UPDATE billing_plans SET ${fields.join(', ')} WHERE id = ?`).run(...values);
+  return getPlan(planId);
+}
+
+function deletePlan(planId) {
+  const now = new Date().toISOString().replace('T', ' ').replace(/\.\d{3}Z$/, '');
+  db.prepare('UPDATE billing_plans SET is_active = 0, updated_at = ? WHERE id = ?').run(now, planId);
+}
+
+function parsePlan(row) {
+  return {
+    ...row,
+    allowed_models: tryParseJson(row.allowed_models_json, []),
+    features: tryParseJson(row.features_json, []),
+    is_active: Boolean(row.is_active),
+  };
+}
+
+function tryParseJson(str, fallback) {
+  try { return JSON.parse(str); } catch { return fallback; }
+}
+
+module.exports = { listPlans, getPlan, getFreePlan, createPlan, updatePlan, deletePlan };

package/server/services/billing/stripe_client.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const { isBillingEnabled, getStripeConfig } = require('./config');
+
+let _client = null;
+
+function getStripeClient() {
+  if (!isBillingEnabled()) {
+    throw new Error('Billing is not enabled.');
+  }
+  if (_client) return _client;
+  const { secretKey } = getStripeConfig();
+  if (!secretKey) {
+    throw new Error('STRIPE_SECRET_KEY is not configured.');
+  }
+  const Stripe = require('stripe');
+  _client = new Stripe(secretKey);
+  return _client;
+}
+
+module.exports = { getStripeClient };