voroa-cli 0.0.0-stage → 0.2.0

package/src/mcp/tools/reads.js

@@ -0,0 +1,756 @@
+// Phase B read tools - read parity with what a customer can SEE in the dashboard.
+//
+// Grouped in ONE file the way actions.js groups the six action tools, rather than 23 near-identical files
+// (CLAUDE.md "simplicity first"). Each tool is still a full, separately-registered entry with its own
+// description and schema - the model reads those, and they are the real UX.
+//
+// PROJECTION IS DELIBERATE AND CONSERVATIVE (golden rule 6). Every tool forwards a NAMED subset of the
+// response, never the raw envelope: a payload that grows an infra field upstream must not start leaking it
+// here by default. Where a row's full shape was not enumerated when this was written, the subset is the
+// small obviously-safe part (id, name, state, timestamps). Under-forwarding is a visible gap somebody can
+// widen deliberately; over-forwarding is a rule-6 breach nobody sees. Widen a pick list only after reading
+// the handler that produces it.
+//
+// NOTHING HERE RETURNS A SECRET VALUE. list_env_vars and list_secret_files return NAMES only, because that
+// is all their endpoints return (routes/apps/env.js getEnvKeysForApp; routes/apps/secrets.js maps to
+// filename + createdAt). Database connection credentials are not on this surface at all.
+
+import { jsonResponse, badInput } from '../lib/response.js';
+import { serviceId } from './_ids.js';
+// The projection primitives live in _shape.js so every tool's shaping is swept by one scan - see its
+// header, and tests/staticScan, which refuses a tool module that projects inline.
+import { pick, pickAll, billingMe, billingInvoices, billingSummary, billingQuote } from './_shape.js';
+
+// `pick` returns {} for an absent source, which is right for a shaper that always has a subject. Some
+// reads here answer "there is nothing", and {} would read as "something, with no fields" - a deploy that
+// is not running must not look like a deploy with no id. This says nothing, explicitly.
+const pickOrNull = (obj, keys) => (obj && typeof obj === 'object' ? pick(obj, keys) : null);
+
+// A read tool over a path built from at most two validated ids. `project` receives the parsed body.
+function readTool({ name, description, params = [], path, project }) {
+  const properties = {};
+  for (const p of params) properties[p.name] = { type: 'string', description: p.description };
+  return {
+    name,
+    kind: 'read',
+    scope: 'services:read',
+    description,
+    inputSchema: {
+      type: 'object',
+      properties,
+      required: params.filter((p) => !p.optional).map((p) => p.name),
+      additionalProperties: false,
+    },
+    async handler(args, ctx) {
+      const values = {};
+      for (const p of params) {
+        const raw = args[p.name];
+        if (raw == null || raw === '') {
+          if (!p.optional) throw badInput(`${p.name} is required.`);
+          continue;
+        }
+        const ok = serviceId(raw);
+        if (!ok) throw badInput(`${p.name} is not a valid id.`);
+        values[p.name] = ok;
+      }
+      const url = path(values);
+      return jsonResponse(project(await ctx.http.get(url)));
+    },
+  };
+}
+
+const SERVICE_ARG = { name: 'serviceId', description: 'The service id, from list_services.' };
+const svc = (v) => encodeURIComponent(v.serviceId);
+
+export const getCurrentDeployment = readTool({
+  name: 'get_current_deployment',
+  description:
+    'The deploy currently running for a service, or nothing if none is in progress. Use get_deploy_history '
+    + 'for finished deploys.',
+  params: [SERVICE_ARG],
+  path: (v) => `/apps/${svc(v)}/deployment`,
+  // The handler returns { deployment: <row|null> }.
+  project: (d) => ({
+    deployment: pickOrNull(d && d.deployment, ['id', 'status', 'verdict', 'commit', 'commitMessage', 'createdAt', 'finishedAt']),
+  }),
+});
+
+export const listBranches = readTool({
+  name: 'list_branches',
+  description:
+    'The branches available on the connected repository for a service, and whether a repository is '
+    + 'connected at all.',
+  params: [SERVICE_ARG],
+  path: (v) => `/apps/${svc(v)}/branches`,
+  project: (d) => ({ branches: Array.isArray(d && d.branches) ? d.branches : [], connected: !!(d && d.connected) }),
+});
+
+export const listEnvVars = readTool({
+  name: 'list_env_vars',
+  description:
+    'The NAMES of a service\'s environment variables. Values are never returned by Voroa to anyone, '
+    + 'including you - they are stored encrypted and can be replaced but not read back. Say that plainly '
+    + 'if asked for a value.',
+  params: [SERVICE_ARG],
+  path: (v) => `/apps/${svc(v)}/env`,
+  project: (d) => ({ env: pickAll(d && d.env, ['key', 'hasValue', 'isBuildTime']) }),
+});
+
+export const listSecretFiles = readTool({
+  name: 'list_secret_files',
+  description:
+    'The FILENAMES of a service\'s secret files. Contents are never returned - they are stored encrypted '
+    + 'and can be replaced but not read back.',
+  params: [SERVICE_ARG],
+  path: (v) => `/apps/${svc(v)}/secret-files`,
+  project: (d) => ({ secretFiles: pickAll(d && d.secretFiles, ['filename', 'createdAt']) }),
+});
+
+export const listPreviewVariables = readTool({
+  name: 'list_preview_variables',
+  description:
+    'The NAMES of the environment variables applied to a service\'s preview environments. Values are never '
+    + 'returned.',
+  params: [SERVICE_ARG],
+  path: (v) => `/apps/${svc(v)}/preview-variables`,
+  project: (d) => ({ variables: pickAll(d && d.variables, ['key', 'hasValue']) }),
+});
+
+export const listPreviews = readTool({
+  name: 'list_previews',
+  description: 'The preview environments open for a service, and whether previews are switched on for it.',
+  params: [SERVICE_ARG],
+  path: (v) => `/apps/${svc(v)}/previews`,
+  project: (d) => ({
+    previewEnabled: !!(d && d.previewEnabled),
+    previews: pickAll(d && d.previews, ['id', 'number', 'title', 'state', 'url', 'createdAt']),
+  }),
+});
+
+export const getMaintenanceMode = readTool({
+  name: 'get_maintenance_mode',
+  description:
+    'Whether a service is in maintenance mode - visitors see a maintenance page instead of the service '
+    + 'while it is on.',
+  params: [SERVICE_ARG],
+  path: (v) => `/apps/${svc(v)}/maintenance`,
+  project: (d) => pickOrNull(d, ['enabled', 'since', 'message']),
+});
+
+// ADR-0263. Whether the service's own name is served through the edge network, and if not, why not.
+export const getEdgeProtection = readTool({
+  name: 'get_edge_protection',
+  description:
+    'Whether edge protection is on for a service - its address is served through an edge network that '
+    + 'absorbs floods before they reach it. `available` false means the platform does not offer it yet; '
+    + '`effective` false with a `reason` of custom_domain or ip_rules means it cannot apply to this service.',
+  params: [SERVICE_ARG],
+  path: (v) => `/apps/${svc(v)}/edge-protection`,
+  project: (d) => pickOrNull(d, ['available', 'enabled', 'effective', 'reason', 'settling', 'changedAt']),
+});
+
+export const listInboundRules = readTool({
+  name: 'list_inbound_rules',
+  description:
+    'The inbound IP rules for a service - which addresses may reach it. An empty list means no restriction.',
+  params: [SERVICE_ARG],
+  path: (v) => `/apps/${svc(v)}/inbound-rules`,
+  project: (d) => ({ rules: pickAll(d && d.rules, ['id', 'cidr', 'action', 'note', 'createdAt']) }),
+});
+
+export const listScheduledTasks = readTool({
+  name: 'list_scheduled_tasks',
+  description: 'The scheduled tasks (cron jobs) attached to a service, with their commands and frequency.',
+  params: [SERVICE_ARG],
+  path: (v) => `/apps/${svc(v)}/scheduled-tasks`,
+  project: (d) => ({ tasks: pickAll(d && d.tasks, ['taskUuid', 'name', 'command', 'frequency', 'enabled', 'createdAt']) }),
+});
+
+export const getScheduledTaskRuns = readTool({
+  name: 'get_scheduled_task_runs',
+  description:
+    'Recent runs of one scheduled task. Voroa records when each run started, ended and whether it '
+    + 'succeeded; it does not keep the task\'s own output.',
+  params: [SERVICE_ARG, { name: 'taskId', description: 'The task id, from list_scheduled_tasks.' }],
+  path: (v) => `/apps/${svc(v)}/scheduled-tasks/${encodeURIComponent(v.taskId)}/executions`,
+  project: (d) => ({ executions: pickAll(d && d.executions, ['id', 'status', 'startedAt', 'finishedAt']) }),
+});
+
+export const listServiceEnvGroups = readTool({
+  name: 'list_service_env_groups',
+  description: 'The environment groups linked to a service, in the order they are applied.',
+  params: [SERVICE_ARG],
+  path: (v) => `/apps/${svc(v)}/env-groups`,
+  project: (d) => ({ groups: pickAll(d && d.groups, ['id', 'name', 'position']) }),
+});
+
+export const getServiceUsage = readTool({
+  name: 'get_service_usage',
+  description:
+    'Recent resource usage for one service. Returns nothing when per-service usage is not being recorded '
+    + 'for this account.',
+  params: [SERVICE_ARG],
+  path: (v) => `/apps/${svc(v)}/service-usage`,
+  project: (d) => pickOrNull(d, ['cpuPercent', 'memoryMb', 'memoryLimitMb', 'measuredAt']),
+});
+
+export const getDatabaseCapabilities = readTool({
+  name: 'get_database_capabilities',
+  description: 'Which database features are available on this account - backups, imports, external access.',
+  params: [],
+  path: () => '/databases/capabilities',
+  project: (d) => d || null,
+});
+
+const DB_ARG = { name: 'databaseId', description: 'The database id, from list_databases.' };
+const db = (v) => encodeURIComponent(v.databaseId);
+
+export const getDatabase = readTool({
+  name: 'get_database',
+  description:
+    'One database: its name, engine, size, state and storage. Connection credentials are NOT available '
+    + 'from here - get them from your Voroa dashboard.',
+  params: [DB_ARG],
+  path: (v) => `/databases/${db(v)}`,
+  project: (d) => pickOrNull(d && (d.database || d), [
+    'uuid', 'name', 'engine', 'version', 'status', 'state', 'createdAt',
+    'computeSizeKey', 'storageQuotaMb', 'storageUsedMb',
+    // What the detail route actually sends: `type` (postgres | mysql | redis) and the engine's major -
+    // `pgVersion` on Postgres, `engineVersion` on MySQL (ADR-0343). `engine`/`version` stay for older servers.
+    'type', 'pgVersion', 'engineVersion',
+  ]),
+});
+
+export const listDatabaseUsers = readTool({
+  name: 'list_database_users',
+  description: 'The database users defined on a database. Passwords are never returned.',
+  params: [DB_ARG],
+  path: (v) => `/databases/${db(v)}/users`,
+  project: (d) => ({ users: pickAll(d && d.users, ['name', 'isDefault', 'createdAt']) }),
+});
+
+export const listImports = readTool({
+  name: 'list_imports',
+  description: 'Recent data imports for a database, with the state of each.',
+  params: [DB_ARG],
+  path: (v) => `/databases/${db(v)}/import`,
+  project: (d) => ({ imports: pickAll(d && (d.imports || d.jobs), ['id', 'status', 'createdAt', 'finishedAt']) }),
+});
+
+export const getImportStatus = readTool({
+  name: 'get_import_status',
+  description: 'The state of one data import, including why it failed if it did.',
+  params: [DB_ARG, { name: 'jobId', description: 'The import id, from list_imports.' }],
+  path: (v) => `/databases/${db(v)}/import/${encodeURIComponent(v.jobId)}`,
+  project: (d) => pickOrNull(d && (d.job || d), ['id', 'status', 'createdAt', 'finishedAt', 'error', 'message']),
+});
+
+export const listProjects = readTool({
+  name: 'list_projects',
+  description: 'The projects in this workspace. A project groups services and their environments.',
+  params: [],
+  path: () => '/projects',
+  project: (d) => ({ projects: pickAll(d && d.projects, ['id', 'name', 'environmentCount', 'serviceCount', 'createdAt']) }),
+});
+
+export const getProject = readTool({
+  name: 'get_project',
+  description:
+    'One project: its name, the environments inside it and the services that belong to them. Use '
+    + 'list_projects first to find the id.',
+  params: [{ name: 'projectId', description: 'The project id, from list_projects.' }],
+  path: (v) => `/projects/${encodeURIComponent(v.projectId)}`,
+  project: (d) => pickOrNull(d, ['id', 'name', 'environments', 'services', 'createdAt']),
+});
+
+export const listEnvironments = readTool({
+  name: 'list_environments',
+  description: 'The environments inside a project, and which of them are protected.',
+  params: [{ name: 'projectId', description: 'The project id, from list_projects.' }],
+  path: (v) => `/projects/${encodeURIComponent(v.projectId)}/environments`,
+  project: (d) => ({ environments: pickAll(d && d.environments, ['id', 'name', 'protected', 'serviceCount']) }),
+});
+
+export const listEnvGroups = readTool({
+  name: 'list_env_groups',
+  description:
+    'The environment groups in this workspace. A group holds environment variables shared by several '
+    + 'services; values are never returned.',
+  params: [],
+  path: () => '/env-groups',
+  project: (d) => ({ groups: pickAll(d && d.groups, ['id', 'name', 'variableCount', 'serviceCount', 'updatedAt']) }),
+});
+
+export const getEnvGroup = readTool({
+  name: 'get_env_group',
+  description:
+    'One environment group: its name, the NAMES of the variables in it, and the services it is linked to. '
+    + 'Values are never returned.',
+  params: [{ name: 'groupId', description: 'The group id, from list_env_groups.' }],
+  path: (v) => `/env-groups/${encodeURIComponent(v.groupId)}`,
+  project: (d) => {
+    const g = (d && d.group) || d || {};
+    return {
+      id: g.id,
+      name: g.name,
+      variables: pickAll(g.variables, ['key', 'hasValue', 'isBuildTime']),
+      services: pickAll(g.services, ['uuid', 'name']),
+    };
+  },
+});
+
+export const listServiceTypes = readTool({
+  name: 'list_service_types',
+  description: 'The kinds of service that can be created on this account today.',
+  params: [],
+  path: () => '/service-types',
+  project: (d) => ({ types: (d && d.types) || null }),
+});
+
+// ---- Billing reads (ADR-0164 D7) ----------------------------------------------------------------------
+// READING a bill is not MOVING money, and that is the whole of what these four open. Nothing that moves
+// money is on this surface: changing a plan, cancelling a subscription, choosing which payment method is
+// debited and every other billing write are absent from the capability allow-list and answer 404 here.
+//
+// THREE CAVEATS LIVE IN THE DESCRIPTIONS BELOW, because the description is what the model reads. Each is
+// true in EVERY state of the platform, not only during an incident:
+//   A. a next-charge date is when a charge is SCHEDULED, not evidence the last one succeeded. It is
+//      computed from the billing anchor day and today's date - it reads no payment at all - so it is in
+//      the future for a subscription that has been failing for months.
+//   B. `mandateUsable` says the payment method is registered and unexpired. It is NOT evidence that
+//      charges are going through. It is on the two tools that return the field, and on no other.
+//   C. the next-debit ESTIMATE on billing_me is the subscription total and excludes usage overage, so the
+//      real charge can be higher. The exact figure is on the dashboard.
+// The one honest cross-check an agent has is the invoice list: a failed cycle produces no invoice, so a
+// gap between the newest issuedAt and the next-charge date is visible there and nowhere else.
+
+export const billingMeTool = readTool({
+  name: 'billing_me',
+  description:
+    'What this workspace is paying for: each billable line with its price and any change already booked, '
+    + 'the active plan, whether a payment method is set up, and the next scheduled charge. '
+    + '`paymentDue` is the field that says whether anything has actually gone wrong: null when nothing is '
+    + 'owed, and an amount with a date when a charge has failed or stuck. Read it BEFORE the next-charge '
+    + 'date - a workspace can owe money and still show a future scheduled charge. '
+    + 'The next-charge DATE is when a charge is scheduled - not evidence that the last one succeeded; '
+    + 'check billing_invoices for what has actually been issued. `mandateUsable` means the payment method '
+    + 'is registered and unexpired, NOT that charges are going through. The next-charge AMOUNT is the '
+    + 'subscription estimate and excludes usage overage, so the real charge can be higher - point the '
+    + 'customer at their Voroa dashboard for the exact number. Billing identity (GSTIN, registered name, '
+    + 'address, phone) and payment-instrument details are never returned.',
+  params: [],
+  path: () => '/billing/me',
+  project: billingMe,
+});
+
+export const billingInvoicesTool = readTool({
+  name: 'billing_invoices',
+  description:
+    'The GST invoices issued for this workspace, newest first, each with its number, total, date and '
+    + 'whether it is paid. This is the one billing read that reflects what actually happened: a cycle that '
+    + 'failed to charge produces no invoice, so a gap here is real. Invoice PDFs are downloaded from the '
+    + 'Voroa dashboard, not from here.',
+  params: [],
+  path: () => '/billing/invoices',
+  project: billingInvoices,
+});
+
+export const billingSummaryTool = readTool({
+  name: 'billing_summary',
+  description:
+    'The full breakdown of the next charge for this workspace: every line with its price, the taxable '
+    + 'subtotal, the CGST/SGST or IGST split, the GST-inclusive total, and the approved ceiling and expiry '
+    + 'of the saved payment method. Use this for "why did my bill go up" - it is the same computation the '
+    + 'charge itself runs, including any usage overage. The DATE is when the charge is scheduled, not '
+    + 'evidence that the last one succeeded; check billing_invoices. `mandateUsable` means the payment '
+    + 'method is registered and unexpired, NOT that charges are going through. Rate-limited more tightly '
+    + 'than other reads because it recomputes the bill - call it once per question, not in a loop.',
+  params: [],
+  path: () => '/billing/summary',
+  project: billingSummary,
+});
+
+// The only billing tool that takes arguments, and the only one that is not a plain GET of a fixed path.
+// Its ids are catalog KEYS (acct_growth, starter_512), not resource ids, so they do not go through
+// serviceId() - the backend validates them against its own catalog and answers 400 on anything else.
+export const billingQuoteTool = {
+  name: 'billing_quote',
+  kind: 'read',
+  scope: 'services:read',
+  description:
+    'What an upgrade would cost, before anyone commits to it: the prorated amount due today, the monthly '
+    + 'amount after that, the GST on each, and the next billing date. Give EITHER planKey (to price a '
+    + 'workspace plan) OR serviceId with sizeKey (to price a service resize). Answers '
+    + '{chargeable: false, downgrade: true} when the target costs less than the current one - a downgrade '
+    + 'takes effect at the end of the period and is never charged for. This tool only PRICES; it cannot '
+    + 'buy anything, and the customer completes an upgrade in their Voroa dashboard. The next billing DATE '
+    + 'is when a charge is scheduled, not evidence that the last one succeeded - check billing_invoices. '
+    + 'Answers 503 while billing is unavailable.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      planKey: { type: 'string', description: 'A workspace plan key, to price a plan change.' },
+      serviceId: { type: 'string', description: 'The service id, from list_services. Use with sizeKey.' },
+      sizeKey: { type: 'string', description: 'The target size key for a service, from billing_me.' },
+      storageGb: { type: 'string', description: 'Optional. Extra storage in GB to include in the quote.' },
+    },
+    required: [],
+    additionalProperties: false,
+  },
+  async handler(args, ctx) {
+    const q = new URLSearchParams();
+    const planKey = typeof args.planKey === 'string' ? args.planKey.trim() : '';
+    const sizeKey = typeof args.sizeKey === 'string' ? args.sizeKey.trim() : '';
+    const storageGb = typeof args.storageGb === 'string' ? args.storageGb.trim() : '';
+    if (planKey) {
+      // The backend refuses a mixed target with its own 400; this says the same thing earlier, in words
+      // the model can act on rather than as a code it has to look up.
+      if (args.serviceId || sizeKey) throw badInput('Quote a workspace plan or a service, not both.');
+      q.set('planKey', planKey);
+    } else {
+      const id = serviceId(args.serviceId);
+      if (!id) throw badInput('Give either planKey, or serviceId with sizeKey.');
+      if (!sizeKey) throw badInput('sizeKey is required when quoting a service.');
+      q.set('appUuid', id);
+      q.set('sizeKey', sizeKey);
+      if (storageGb) q.set('storageGb', storageGb);
+    }
+    return jsonResponse(billingQuote(await ctx.http.get(`/billing/quote?${q.toString()}`)));
+  },
+};
+
+// ---- Object Storage (buckets). Read-only views of what the Buckets pages show. NOT here, on purpose: the
+// access-key secret and key regeneration (credentials - the same line /databases/:uuid/connection stays
+// behind), file download links (a presigned link is a bearer credential to the file), and create/delete
+// (create needs a payment; delete is permanent with no undo). The customer does those in the dashboard.
+const BUCKET_ARG = { name: 'bucketId', description: 'The bucket id, from list_buckets.' };
+const bkt = (v) => encodeURIComponent(v.bucketId);
+const BUCKET_FIELDS = ['id', 'name', 'state', 'freeze', 'plan', 'billingHold', 'createdAt'];
+
+export const listBuckets = readTool({
+  name: 'list_buckets',
+  description:
+    'The Object Storage buckets in this workspace: name, plan, state, and the S3 endpoint to use. The '
+    + 'access key secret is never returned - it is shown once in the dashboard when the key is created.',
+  path: () => '/buckets',
+  project: (d) => ({ endpoint: (d && d.endpoint) || null, buckets: pickAll(d && d.buckets, BUCKET_FIELDS) }),
+});
+
+export const listBucketPlans = readTool({
+  name: 'list_bucket_plans',
+  description: 'The Object Storage plans on sale: storage and storage transfer included, and the monthly price.',
+  path: () => '/buckets/plans',
+  project: (d) => ({ plans: pickAll(d && d.plans, ['code', 'sizeKey', 'storageGb', 'transferGb', 'priceInrMonthly']) }),
+});
+
+export const getBucket = readTool({
+  name: 'get_bucket',
+  description: 'One bucket: its name, plan, state (active, pending_payment, frozen) and the S3 endpoint.',
+  params: [BUCKET_ARG],
+  path: (v) => `/buckets/${bkt(v)}`,
+  project: (d) => ({ endpoint: (d && d.endpoint) || null, bucket: pickOrNull(d && d.bucket, BUCKET_FIELDS) }),
+});
+
+export const getBucketUsage = readTool({
+  name: 'get_bucket_usage',
+  description:
+    'This IST month for one bucket against its plan: bytes stored, storage transfer, upload and download '
+    + 'requests, whether uploads or downloads are paused, and the estimated charge above the plan so far.',
+  params: [BUCKET_ARG],
+  path: (v) => `/buckets/${bkt(v)}/usage`,
+  project: (d) => pick(d || {}, [
+    'period', 'plan', 'storage', 'storageTransfer', 'uploadRequests', 'downloadRequests', 'paused',
+    'estimatedExtra', 'complete',
+  ]),
+});
+
+export const listBucketFiles = {
+  name: 'list_bucket_files',
+  kind: 'read',
+  scope: 'services:read',
+  description:
+    'Files and folders in a bucket, one folder level at a time (200 per page). Give prefix to open a folder '
+    + '(for example "images/"), and nextToken from the previous answer for the next page. Names, sizes and '
+    + 'dates only - file contents and download links are not available here.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      bucketId: { type: 'string', description: BUCKET_ARG.description },
+      prefix: { type: 'string', description: 'Optional. A folder path ending in "/".' },
+      nextToken: { type: 'string', description: 'Optional. The nextToken from the previous page.' },
+    },
+    required: ['bucketId'],
+    additionalProperties: false,
+  },
+  async handler(args, ctx) {
+    const id = serviceId(args.bucketId);
+    if (!id) throw badInput('bucketId is not a valid id.');
+    const q = new URLSearchParams();
+    if (typeof args.prefix === 'string' && args.prefix) q.set('prefix', args.prefix);
+    if (typeof args.nextToken === 'string' && args.nextToken) q.set('token', args.nextToken);
+    const qs = q.toString();
+    const d = await ctx.http.get(`/buckets/${encodeURIComponent(id)}/files${qs ? `?${qs}` : ''}`);
+    return jsonResponse({
+      prefix: (d && d.prefix) || '',
+      folders: Array.isArray(d && d.folders) ? d.folders.filter((f) => typeof f === 'string') : [],
+      files: pickAll(d && d.files, ['key', 'size', 'lastModified']),
+      nextToken: (d && d.nextToken) || null,
+    });
+  },
+};
+
+// ---- Wave 2 reads (plan 2026-10-27) - the features that shipped after Phase B --------------------------
+const DB_ARG2 = { name: 'databaseId', description: 'The database id, from list_databases.' };
+const SVC_ARG2 = { name: 'serviceId', description: 'The service id, from list_services.' };
+const db2 = (v) => encodeURIComponent(v.databaseId);
+const svc2 = (v) => encodeURIComponent(v.serviceId);
+
+export const listRepos = readTool({
+  name: 'list_repos',
+  description:
+    'Repositories the connected GitHub account(s) can deploy from - full_name and default branch, plus the '
+    + 'installation id a create_service proposal needs. connected:false means GitHub is not connected yet; '
+    + 'that is done in the dashboard. degraded:true means one account could not be listed just now.',
+  path: () => '/github/repos',
+  project: (d) => ({
+    connected: !!(d && d.connected),
+    repos: pickAll(d && d.repos, ['full_name', 'default_branch', 'installation_id', 'private']),
+    degraded: !!(d && d.degraded),
+    needsReconnect: !!(d && d.needsReconnect),
+  }),
+});
+
+export const listGitConnections = readTool({
+  name: 'list_git_connections',
+  description:
+    'The GitHub accounts connected to this workspace: installation id, account name, and whether the '
+    + 'connection is still working. Connecting or disconnecting is done in the dashboard.',
+  path: () => '/github/installations',
+  project: (d) => ({
+    installations: pickAll(d && d.installations, ['installationId', 'accountLogin', 'disconnected', 'removedOnGitHub']),
+  }),
+});
+
+export const listGitlabRepos = readTool({
+  name: 'list_gitlab_repos',
+  description:
+    'Repositories the connected GitLab account(s) can deploy from - full_name, default branch and project '
+    + 'id. connected:false means GitLab is not connected (or not offered); connecting is done in the dashboard.',
+  path: () => '/gitlab/repos',
+  project: (d) => ({
+    connected: !!(d && d.connected),
+    repos: pickAll(d && d.repos, ['full_name', 'default_branch', 'project_id', 'connection_id']),
+    needsReconnect: !!(d && d.needsReconnect),
+  }),
+});
+
+export const listDatabaseBackups = readTool({
+  name: 'list_database_backups',
+  description:
+    'Backups of a database that are still within retention: id, status, size, when taken and when it '
+    + 'expires, plus whether nightly backups are on. Paid databases only. Downloading a backup is not '
+    + 'available here; restoring one is proposed with propose(restore_database_backup).',
+  params: [DB_ARG2],
+  path: (v) => `/databases/${db2(v)}/backups`,
+  project: (d) => ({
+    backups: pickAll(d && d.backups, ['id', 'status', 'trigger', 'sizeBytes', 'createdAt', 'finishedAt', 'expiresAt']),
+    retentionDays: d && d.retentionDays,
+    backupsEnabled: !!(d && d.backupsEnabled),
+    paid: !!(d && d.paid),
+  }),
+});
+
+export const getBackupRestoreStatus = readTool({
+  name: 'get_backup_restore_status',
+  description:
+    'Progress of a backup restore: status, the id of the NEW database, and timestamps. The restore id is '
+    + 'shown to the person who approved propose(restore_database_backup) - ask them for it.',
+  params: [DB_ARG2, { name: 'backupId', description: 'The backup id, from list_database_backups.' },
+    { name: 'restoreId', description: 'The restore id returned when the restore was approved.' }],
+  path: (v) => `/databases/${db2(v)}/backups/${encodeURIComponent(v.backupId)}/restore/${encodeURIComponent(v.restoreId)}`,
+  project: (d) => pick(d || {}, ['id', 'status', 'newDbUuid', 'createdAt', 'finishedAt']),
+});
+
+export const getDatabaseMetrics = readTool({
+  name: 'get_database_metrics',
+  description:
+    'Latest CPU, memory and disk readings of a database, with connections (PostgreSQL) or client/ops/hit-rate '
+    + 'figures (key-value store). available:false with a reason means nothing has been collected yet.',
+  params: [DB_ARG2],
+  path: (v) => `/databases/${db2(v)}/metrics`,
+  project: (d) => pick(d || {}, ['available', 'reason', 'collectedAt', 'freshness', 'cpu', 'ram', 'disk', 'connections', 'redis']),
+});
+
+export const getDatabaseLogs = readTool({
+  name: 'get_database_logs',
+  description:
+    'The slowest queries of a PostgreSQL database (first 60 characters of each, with call count and mean '
+    + 'time) or the INFO stats of a key-value store. No row data. available:false carries a reason.',
+  params: [DB_ARG2],
+  path: (v) => `/databases/${db2(v)}/logs`,
+  project: (d) => ({
+    ...pick(d || {}, ['available', 'reason', 'type', 'freshness', 'collectedAt', 'connectedClients', 'opsPerSec', 'hitRate', 'usedMemoryMb']),
+    queries: pickAll(d && d.queries, ['rank', 'calls', 'meanTimeMs', 'totalTimeMs', 'rowsAffected', 'query']),
+  }),
+});
+
+export const listDatabaseExtensions = readTool({
+  name: 'list_database_extensions',
+  description:
+    'PostgreSQL extensions available for a database and their state (available, pending, enabled, failed). '
+    + 'Enabling one is proposed with propose(enable_database_extension) because it cannot be turned off again.',
+  params: [DB_ARG2],
+  path: (v) => `/databases/${db2(v)}/extensions`,
+  project: (d) => ({
+    extensions: pickAll(d && d.extensions, ['extension', 'displayName', 'description', 'status', 'enabledAt', 'failureReason', 'canEnable']),
+  }),
+});
+
+export const getAutoscale = readTool({
+  name: 'get_autoscale',
+  description:
+    'The autoscaling policy of a service - min/max instances and the CPU or memory target - or null when '
+    + 'autoscaling is off. Changing it is proposed (every extra instance is billed).',
+  params: [SVC_ARG2],
+  path: (v) => `/apps/${svc2(v)}/autoscale`,
+  project: (d) => pickOrNull(d, ['minInstances', 'maxInstances', 'cpuTargetPct', 'memTargetPct', 'currentInstances', 'updatedAt']),
+});
+
+export const getDiskLimit = readTool({
+  name: 'get_disk_limit',
+  description: 'The disk allowance of a service: included MB, extra MB bought, and the resulting limit.',
+  params: [SVC_ARG2],
+  path: (v) => `/apps/${svc2(v)}/disk-limit`,
+  project: (d) => pick(d || {}, ['includedMb', 'extraMb', 'limitMb']),
+});
+
+export const getPersistentDisk = readTool({
+  name: 'get_persistent_disk',
+  description: 'The persistent disk of a web service or worker: size in GB, mount path, how much is used, and '
+    + 'whether this service may add one (and why not). Null size = no disk yet.',
+  params: [SVC_ARG2],
+  path: (v) => `/apps/${svc2(v)}/persistent-disk`,
+  project: (d) => pick(d || {}, ['gb', 'mountPath', 'mounted', 'usedMb', 'totalMb', 'eligible', 'ratePerGbInr']),
+});
+
+export const getEdgeCache = readTool({
+  name: 'get_edge_cache',
+  description:
+    'Edge caching state of a web service: mode (none, static or all), whether the plan allows it, which '
+    + 'domains are cached, and when the cache was last cleared. Changing the mode is proposed; clearing it '
+    + 'is purge_edge_cache.',
+  params: [SVC_ARG2],
+  path: (v) => `/apps/${svc2(v)}/edge-cache`,
+  project: (d) => ({
+    ...pick(d || {}, ['available', 'mode', 'paid', 'extensions', 'lastPurgedAt', 'purgePending', 'atCapacity']),
+    domains: pickAll(d && d.domains, ['host', 'state', 'atCapacity']),
+  }),
+});
+
+export const getServiceUsageHistory = readTool({
+  name: 'get_service_usage_history',
+  description:
+    'CPU and memory readings of a service over the last hours (default 24), as time points. available:false '
+    + 'with a reason when the service is not reporting yet.',
+  params: [SVC_ARG2, { name: 'hours', description: 'Optional. How many hours back, as digits (1-168).', optional: true }],
+  path: (v) => `/apps/${svc2(v)}/service-usage/history${v.hours ? `?hours=${encodeURIComponent(v.hours)}` : ''}`,
+  project: (d) => ({
+    ...pick(d || {}, ['available', 'reason', 'hours', 'since', 'until']),
+    points: pickAll(d && d.points, ['t', 'cpuUsedPct', 'cpuCapCores', 'ramUsedMb', 'ramCapMb']),
+  }),
+});
+
+export const getDeployHookStatus = readTool({
+  name: 'get_deploy_hook_status',
+  description:
+    'Whether a service has a deploy hook URL. The URL itself is never readable - it is shown once in the '
+    + 'dashboard when propose(create_deploy_hook) is approved.',
+  params: [SVC_ARG2],
+  path: (v) => `/apps/${svc2(v)}/deploy-hook`,
+  project: (d) => pick(d || {}, ['enabled']),
+});
+
+export const getMyPermissions = readTool({
+  name: 'get_my_permissions',
+  description:
+    'The role this token acts as in the workspace and the permission keys it holds - check before an '
+    + 'action that may be refused with 403.',
+  path: () => '/members/me',
+  project: (d) => ({ role: pickOrNull(d && d.role, ['key', 'label']), permissions: Array.isArray(d && d.permissions) ? d.permissions.filter((p) => typeof p === 'string') : [] }),
+});
+
+export const getWorkspace = readTool({
+  name: 'get_workspace',
+  description:
+    'The workspace this token belongs to - its name and plan - and a one-line count of its services. '
+    + 'The billing contact is not available here.',
+  path: () => '/workspace',
+  project: (d) => ({
+    workspace: pickOrNull(d && d.workspace, ['id', 'name', 'accountPlanKey']),
+    serviceCount: d && typeof d.serviceCount === 'number' ? d.serviceCount : undefined,
+  }),
+});
+
+export const getNotificationSettings = readTool({
+  name: 'get_notification_settings',
+  description: 'Which workspace email alerts are on: deploy (failed deploys) and usage (approaching limits).',
+  path: () => '/workspace/notifications',
+  project: (d) => pick(d || {}, ['deploy', 'usage']),
+});
+
+// CTO decision 2026-10-27: who has access is readable (never an email); access can only be proposed AWAY.
+export const listMembers = readTool({
+  name: 'list_members',
+  description:
+    'People in this workspace: member id, name (when they set one) and role. Email addresses are never '
+    + 'returned, and the whole list is unavailable when team members are not enabled for the account. A member can '
+    + 'be removed or moved to a LOWER role with propose(remove_member / change_member_role); inviting '
+    + 'someone or raising a role is done in the dashboard.',
+  path: () => '/members',
+  project: (d) => ({ members: pickAll(d && d.members, ['customerId', 'fullName', 'role', 'isOwner', 'joinedAt']) }),
+});
+
+export const listSshKeys = readTool({
+  name: 'list_ssh_keys',
+  description:
+    'Your SSH public keys for shell access to services: id, label, fingerprint and when added. Removing one '
+    + 'is propose(delete_ssh_key); adding a key is done in the dashboard only.',
+  path: () => '/ssh-keys',
+  project: (d) => ({
+    keys: pickAll(d && d.keys, ['id', 'label', 'fingerprint', 'createdAt', 'lastUsedAt']),
+    maxKeys: d && d.maxKeys,
+  }),
+});
+
+export const listTickets = readTool({
+  name: 'list_tickets',
+  description: 'Support tickets of this workspace: id, subject, status, priority and dates.',
+  path: () => '/support/tickets',
+  project: (d) => ({
+    tickets: pickAll(d && d.tickets, ['id', 'subject', 'status', 'priority', 'category', 'appUuid', 'createdAt', 'updatedAt']),
+  }),
+});
+
+export const getTicket = readTool({
+  name: 'get_ticket',
+  description: 'One support ticket with its conversation (customer and support replies, in order).',
+  params: [{ name: 'ticketId', description: 'The ticket id, from list_tickets.' }],
+  path: (v) => `/support/tickets/${encodeURIComponent(v.ticketId)}`,
+  project: (d) => ({
+    ticket: pickOrNull(d && d.ticket, ['id', 'subject', 'body', 'status', 'priority', 'category', 'appUuid', 'createdAt', 'updatedAt']),
+    thread: pickAll(d && d.thread, ['kind', 'body', 'createdAt']),
+  }),
+});
+
+export const READ_TOOLS = [
+  listMembers, listSshKeys, listTickets, getTicket,
+  listRepos, listGitConnections, listGitlabRepos, listDatabaseBackups, getBackupRestoreStatus, getDatabaseMetrics,
+  getDatabaseLogs, listDatabaseExtensions, getAutoscale, getDiskLimit, getPersistentDisk, getEdgeCache, getServiceUsageHistory,
+  getDeployHookStatus, getMyPermissions, getWorkspace, getNotificationSettings,
+  getCurrentDeployment, listBranches, listEnvVars, listSecretFiles, listPreviewVariables, listPreviews,
+  getMaintenanceMode, getEdgeProtection, listInboundRules, listScheduledTasks, getScheduledTaskRuns, listServiceEnvGroups,
+  getServiceUsage, getDatabaseCapabilities, getDatabase, listDatabaseUsers, listImports, getImportStatus,
+  listProjects, getProject, listEnvironments, listEnvGroups, getEnvGroup, listServiceTypes,
+  billingMeTool, billingInvoicesTool, billingSummaryTool, billingQuoteTool,
+  listBuckets, listBucketPlans, getBucket, getBucketUsage, listBucketFiles,
+];