voroa-cli 0.0.0-stage → 0.3.0

package/src/mcp/tools/_shape.js

@@ -0,0 +1,318 @@
+// Response shaping for the customer token API (backend/src/routes/customerMcpApi.js re-mounts the SPA's
+// own routers, so these envelopes are the SPA's - verified against the handlers, not guessed; bug #26's
+// rule about inventing a shape applies here too).
+//
+// Every shaper is a WHITELIST pick. A new upstream field is DROPPED by default until somebody deliberately
+// adds it here. That default matters more on this surface than on the SPA, for two reasons:
+//
+//   1. GOLDEN RULE 6. Whatever a tool returns lands in the customer's AI client transcript verbatim. The
+//      SPA renders a subset of what it receives; an MCP tool would print all of it. So fields that are
+//      merely unused in the UI (a raw container state token, a build-server flag, a platform IP) become
+//      LEAKS here. They are dropped below, each with the reason.
+//   2. GOLDEN RULE 13. A transcript is stored, like a git commit. "Only what the decision needs" is the
+//      same discipline the dev MCP's env_var_catalog follows (names, never values).
+
+export function pick(obj, fields) {
+  if (!obj || typeof obj !== 'object') return {};
+  const out = {};
+  for (const f of fields) if (obj[f] !== undefined) out[f] = obj[f];
+  return out;
+}
+
+// placementOf - WHERE a service/database lives and its plan, from the API's `placement` (plan 2026-10-31: Provider ->
+// Region -> Plan; the server is never sent). Only the customer-meaningful fields - never a plan key.
+function placementOf(p) {
+  if (!p || typeof p !== 'object') return undefined;
+  const out = { provider: p.providerLabel || p.provider, region: p.label || p.region };
+  if (p.plan && typeof p.plan === 'object') out.plan = { name: p.plan.label || null, priceInrMonthly: p.plan.priceInr };
+  return out;
+}
+
+// ---- Services list (GET /apps -> { apps: [...] }) -----------------------------------------------------
+// DROPPED: installationId (a GitHub App installation id - our integration's internal key, useless to the
+// customer and meaningless outside our plumbing), projectId / environmentId / computeSizeKey (internal
+// ids; the NAMES are surfaced instead), sleepable / healthCheckPath / buildFilter* / preDeployCommand
+// (configuration an agent cannot change on this surface, so printing it is noise that costs transcript).
+//
+// DROPPED, and this one is a RULE 6 fix rather than a tidiness one: `buildPack`. Its values name the
+// build tooling underneath the platform. The dashboard BRANCHES on that value and never prints it, so no
+// customer has ever seen those words - surfacing them here would put them into a stored AI transcript,
+// which is precisely the leak rule 6 exists to stop. `serviceType` already answers the only question an
+// agent has ("what kind of service is this"), in Voroa's own vocabulary. There is no customer-safe mapping
+// worth inventing for a field nothing on this surface acts on. (The words themselves are deliberately not
+// written in this comment: backend/tests/staticScan.test.js scans this package INCLUDING comments, because
+// it ships to customers and there is no build step between this source and whoever installs it.)
+export function service(row) {
+  if (!row || typeof row !== 'object') return {};
+  const out = pick(row, ['uuid', 'name', 'subdomain', 'serviceType', 'rootDirectory']);
+  // Postgres lower-cases unquoted aliases (known bug #21), so these arrive snake_cased. Renamed here so a
+  // tool result reads like an API and not like a table.
+  if (row.git_repository !== undefined) out.repo = row.git_repository;
+  if (row.git_branch !== undefined) out.branch = row.git_branch;
+  if (row.created_at !== undefined) out.createdAt = row.created_at;
+  if (row.projectName !== undefined) out.project = row.projectName;
+  if (row.environmentName !== undefined) out.environment = row.environmentName;
+  if (row.placement !== undefined) out.placement = placementOf(row.placement);
+  return out;
+}
+
+// ---- Service status (GET /apps/:uuid/status) ----------------------------------------------------------
+// The upstream payload carries `status`, the RAW `state:health` token (e.g. "running:unknown",
+// "exited:unhealthy"). It is NEVER surfaced. Two reasons, both already written down in this codebase:
+// known bug #3 (an `unknown` health suffix is not "unhealthy", and showing the raw string produced a
+// scary badge on a healthy app) and golden rule 6 (it is a container-runtime token, i.e. substrate).
+//
+// `runningState` / `health` / `crashLooping` are NOT decoded here. They are computed ONCE on the platform
+// by `backend/src/lib/runtimeState.js` and travel as real fields. This file previously derived its own
+// four-value bucket and got it wrong in the way that matters: it merged `restarting:unhealthy` (a crash
+// loop - the whole reason bug #30 added a container health check) into the same value as
+// `restarting:unknown` (one ordinary post-deploy restart), so a crash-looping service read as "coming back
+// up". A whitelist pick cannot make that mistake; a second decoder can, and did.
+export function serviceStatus(data) {
+  const out = pick(data, ['uuid', 'verdict', 'runningState', 'health', 'crashLooping']);
+  // A platform that has not shipped the fields yet (or a read that degraded) is the COULD-NOT-READ case,
+  // not the unmodeled-token case - so the fallback is 'unavailable', matching the server decoder's own
+  // vocabulary (review E7: both of this comment's examples ARE the unavailable case, and asserting a
+  // successful read that never happened is the same conflation one layer up). Never fall back to decoding
+  // the raw string - that is how a second decoder returns.
+  if (out.runningState === undefined) out.runningState = 'unavailable';
+  if (out.health === undefined) out.health = 'unknown';
+  if (out.crashLooping === undefined) out.crashLooping = false;
+  // deploymentStatus is upstream's in-flight-build axis; surface it as a plain boolean rather than the
+  // engine's queue vocabulary.
+  out.deploying = !!(data && data.deploymentStatus);
+  // fqdn is a comma-separated "https://host" list built from OUR OWN domains (the handler strips the raw
+  // upstream host precisely because a partial setup yields a box-IP host - rule 6). Safe, and it is the
+  // one field a human actually wants.
+  if (data && data.fqdn) out.urls = String(data.fqdn).split(',').map((s) => s.trim()).filter(Boolean);
+  if (data && data.projectName !== undefined) out.project = data.projectName;
+  if (data && data.environmentName !== undefined) out.environment = data.environmentName;
+  return out;
+}
+
+// ---- Deploy history (GET /apps/:uuid/deployments -> { deployments: [...] }) ---------------------------
+// `status` is the RAW BUILD status (building|live|failed|cancelled|skipped) and `verdict` is the honest
+// state -
+// the contract bug #24 locked. Both are customer-facing by design, so both are surfaced.
+// DROPPED: `source` (null on most paths and an engine-classification concept when it is not).
+const DEPLOY_FIELDS = [
+  'deploymentUuid', 'status', 'verdict', 'commit', 'commitMessage',
+  'createdAt', 'finishedAt', 'authorName', 'authorLogin',
+];
+export function deployment(row) {
+  return pick(row, DEPLOY_FIELDS);
+}
+
+// ---- Build log (GET /apps/:uuid/deployments/:d/log) ---------------------------------------------------
+// `lines` are ALREADY redacted server-side per engine (surfaceBodyForEngine + assembleDeployLog); this
+// client does not re-redact and must not pretend to.
+// DROPPED: `isolated` - it says the build ran on a separate build machine, which is pure infrastructure
+// (rule 6) and means nothing to the customer.
+const BUILD_LOG_FIELDS = ['available', 'status', 'verdict', 'lines', 'phases', 'buildMs', 'reason', 'retentionDays'];
+export function buildLog(data) {
+  return pick(data, BUILD_LOG_FIELDS);
+}
+
+// ---- Domains (GET /apps/:uuid/domains) ----------------------------------------------------------------
+// DROPPED per custom-domain row: `dns` (the registrar instructions) and `aRecordIp` (the PLATFORM's IP
+// address). Both are legitimately shown in the dashboard, where the human is about to type them into a
+// registrar. Neither is something an agent acts on, and an infrastructure IP address in a stored
+// transcript is exactly what rule 6 exists to prevent - so the tool says "set this up in your dashboard"
+// instead.
+// `wildcard` / `ownership` (ADR-0268) ride along so an agent can tell a pending wildcard - which serves nothing
+// until its owner verifies it in the dashboard - from a broken domain. Absent on exact rows.
+// edgeProtection (ADR-0264): { state, reason } of the domain's own edge state - present only once the edge
+// network is in play for this service, so the shape is unchanged until then.
+const DOMAIN_FIELDS = ['id', 'domain', 'status', 'verifiedStatus', 'certificateStatus', 'wildcard', 'ownership', 'edgeProtection'];
+export function domains(data) {
+  const out = {};
+  if (data && data.defaultDomain) out.defaultDomain = data.defaultDomain;
+  out.custom = Array.isArray(data && data.custom) ? data.custom.map((d) => pick(d, DOMAIN_FIELDS)) : [];
+  const q = data && data.quota;
+  if (q && typeof q === 'object') out.quota = pick(q, ['used', 'limit', 'unlimited']);
+  return out;
+}
+
+// ---- Databases (GET /databases -> { databases: [...] }) ----------------------------------------------
+// Connection credentials are NOT on this surface at all (the /connection route is absent from the
+// capability allow-list), so there is nothing secret to drop here - only a rename.
+export function database(row) {
+  if (!row || typeof row !== 'object') return {};
+  const out = pick(row, ['uuid', 'name', 'type', 'status']);
+  if (row.created_at !== undefined) out.createdAt = row.created_at;
+  if (row.placement !== undefined) out.placement = placementOf(row.placement);
+  return out;
+}
+
+// ---- Usage (GET /usage) -------------------------------------------------------------------------------
+// GRAIN, stated because the fields mix two (review M5): buildMinutes/egressGb are ACCOUNT-wide totals
+// (account_usage has no workspace grain), workspaceEgressGb is THIS workspace's own figure. The tool
+// description says the same; here the account fields are grouped under `account` so the result itself
+// cannot be misread as all-workspace.
+const USAGE_ACCOUNT_FIELDS = ['buildMinutes', 'buildMinutesIncluded', 'egressGb'];
+const USAGE_WORKSPACE_FIELDS = ['workspaceEgressGb', 'bandwidthGbIncluded'];
+export function usage(data) {
+  if (!data || typeof data !== 'object') return {};
+  const out = { ...pick(data, ['period']), account: pick(data, USAGE_ACCOUNT_FIELDS) };
+  const ws = pick(data, USAGE_WORKSPACE_FIELDS);
+  // A NULL workspace figure means "the platform does not measure this yet" - the backend sets it null on
+  // purpose so a consumer can tell that apart from "you used 0 GB", and pick() passing the null through
+  // made the agent report a fake zero on a billable quota (review M1: the exact misreading the SPA path
+  // was built to prevent). Say it explicitly instead of handing over a null. `== null` on purpose
+  // (review M-L1): an ABSENT key - a version-skewed or degraded response - must read as not-measured
+  // too, never as a quota with no usage figure and no flag (serviceStatus handles absence the same way).
+  if (ws.workspaceEgressGb == null) {
+    delete ws.workspaceEgressGb;
+    ws.bandwidthMeasured = false;
+  } else {
+    ws.bandwidthMeasured = true;
+  }
+  out.workspace = ws;
+  return out;
+}
+
+// ---- Billing reads (ADR-0164 D7) ----------------------------------------------------------------------
+// The four billing shapers are the tightest whitelists in this file, and golden rule 13 is the governing
+// rule rather than golden rule 4 - nothing on these paths is encrypted at rest, so the question is not
+// "may this be decrypted" but "does the decision need it in a stored transcript".
+//
+// DROPPED, and this is the largest exposure on the surface: the GST identity block that GET /billing/me
+// returns to anyone holding billing.manage - `gstin`, `billingName`, `billingState`, `billingAddress`,
+// `contactPhone`, plus `canEditBillingIdentity`. A registered business address and a phone number are
+// DPDP-weight fields and they buy an agent nothing. DROPPED for the same reason on the summary:
+// `mandateInstrument` (the card last four / the payment handle) and `placeOfSupply` (the registered State).
+//
+// DROPPED as ROLLOUT STATE, not as secrets: `billingEnabled`, `paidCheckoutLive`, `multiMethodBilling`,
+// `multiPaymentMethods`, `horizontalScalingEnabled`, `paidAtCreate` and `workspacePlan.autoscalingAvailable`
+// on /billing/me, and `methods` on the quote. They say what Voroa has switched on this week, which is our
+// business and not the customer's decision.
+//
+// DROPPED as internal ids: `workspace.id`, `items[].id`, `items[].appUuid`, `items[].sizeKey` and the
+// invoice `id`. The size-key rule, stated once because it decides four fields: a size key is dropped where
+// a LABEL already says the same thing (`items[].sizeKey` has `sizeLabel` beside it) and KEPT where nothing
+// else does (`pendingSizeKey`, `scheduledChange.sizeKey` and `workspacePlan.planKey` name the TARGET of an
+// in-flight, booked or active change, for which no label field exists - dropping them would leave an agent
+// able to say a change is coming and not what to).
+//
+// NESTED PICKS, not top-level names. `pick` is SHALLOW, so naming `workspacePlan` or `scheduledChange` at
+// the top level would pass those objects through whole and a field added upstream next month would enter
+// this surface silently - which is the one property the whitelist exists to have.
+const BILLING_ME_WORKSPACE = ['name'];
+const BILLING_ME_BILLING = ['mandateStatus', 'mandateMethod', 'mandateUsable', 'mandateNeedsAction', 'anchorDay'];
+// `billing.paymentDue` (PR #1086) is the ONE honest money field on this endpoint: null unless a charge has
+// actually failed or stuck, and an amount with a date when it has. It is named here because dropping it
+// would leave this surface able to say "next charge Rs X on the 8th, payment method working" and unable to
+// say "you owe Rs Y since the 15th" - the two halves of the same customer's truth, with only the flattering
+// one reaching the agent.
+// `payUrl` and `expiresAt` are NOT named: a live payment door does not belong in a stored AI transcript
+// (golden rule 13), and the rest of this surface already sends the customer to their dashboard to act -
+// the same reason invoice PDFs are not here.
+const BILLING_ME_PAYMENT_DUE = ['amountInr', 'since'];
+const BILLING_ME_ITEM = [
+  'serviceName', 'kind', 'sizeLabel', 'priceInrMonthly', 'status', 'provisionedAt', 'isComp',
+  'pendingAction', 'pendingSizeKey', 'inFlightChange', 'quantity', 'pendingQuantity',
+  'storageGb', 'pendingStorageGb',
+];
+const BILLING_ME_SCHEDULED_CHANGE = ['action', 'sizeKey', 'quantity', 'effectiveAt'];
+const BILLING_ME_PLAN = ['active', 'planKey', 'isComp', 'priceInrMonthly', 'maxInstancesPerService'];
+const BILLING_ME_NEXT_DEBIT = ['estimateInrTotal', 'date'];
+
+export function billingMe(data) {
+  if (!data || typeof data !== 'object') return {};
+  return {
+    workspace: pick(data.workspace, BILLING_ME_WORKSPACE),
+    billing: (() => {
+      const b = pick(data.billing, BILLING_ME_BILLING);
+      // Always present, explicitly null when nothing is owed - the same distinction scheduledChange draws.
+      // An absent key would read as "not checked"; null reads as "checked, nothing due".
+      b.paymentDue = data.billing && data.billing.paymentDue
+        ? pick(data.billing.paymentDue, BILLING_ME_PAYMENT_DUE)
+        : null;
+      return b;
+    })(),
+    items: (Array.isArray(data.items) ? data.items : []).map((r) => {
+      const out = pick(r, BILLING_ME_ITEM);
+      // Always present, explicitly null when there is no booked change - {} would read as "a change, with
+      // no fields", the same distinction pickOrNull draws for an absent deploy.
+      out.scheduledChange = r && r.scheduledChange ? pick(r.scheduledChange, BILLING_ME_SCHEDULED_CHANGE) : null;
+      return out;
+    }),
+    workspacePlan: pick(data.workspacePlan, BILLING_ME_PLAN),
+    nextDebit: data.nextDebit ? pick(data.nextDebit, BILLING_ME_NEXT_DEBIT) : null,
+  };
+}
+
+// ---- Invoices (GET /billing/invoices -> a bare array) -------------------------------------------------
+// `status` is the DERIVED paid/unpaid state (captured -> paid, refunded -> refunded, else issued), not the
+// raw payment alias. `id` is dropped: it addresses the PDF route, which is not on this surface.
+const BILLING_INVOICE_FIELDS = ['invoiceNumber', 'totalInr', 'issuedAt', 'status'];
+export function billingInvoices(rows) {
+  return pickAll(rows, BILLING_INVOICE_FIELDS);
+}
+
+// ---- Billing summary (GET /billing/summary) -----------------------------------------------------------
+const BILLING_SUMMARY_FIELDS = [
+  'currency', 'subtotalExGst', 'intraState', 'total', 'debitDate',
+  'mandateStatus', 'mandateMethod', 'mandateUsable', 'mandateNeedsAction',
+  'mandateMaxPaise', 'mandateExpiresAt', 'itemCount',
+];
+const BILLING_SUMMARY_GST = ['cgst', 'sgst', 'igst', 'total'];
+const BILLING_SUMMARY_LINE = ['service', 'size', 'priceInrMonthly'];
+export function billingSummary(data) {
+  if (!data || typeof data !== 'object') return {};
+  const out = pick(data, BILLING_SUMMARY_FIELDS);
+  out.gst = pick(data.gst, BILLING_SUMMARY_GST);
+  out.lines = pickAll(data.lines, BILLING_SUMMARY_LINE);
+  return out;
+}
+
+// ---- Quote (GET /billing/quote) -----------------------------------------------------------------------
+// Three shapes, one per arm the route answers with. `intent` is a ROUTING declaration nobody acts on, so it
+// is kept ONLY on the two refusal arms, where it IS the answer, and dropped from the money arm.
+const BILLING_QUOTE_FIELDS = [
+  'currency', 'dueNowInr', 'dueNowExGstInr', 'gstInr', 'gstPercent', 'monthlyInr', 'monthlyExGstInr',
+  'storageGb', 'storageMonthlyInr', 'storageRatePerGbInr', 'prorationDays', 'cycleDays', 'nextAnchorDate',
+];
+const BILLING_QUOTE_REFUSAL_FIELDS = ['capExceeded', 'chargeable', 'downgrade', 'intent'];
+export function billingQuote(data) {
+  if (!data || typeof data !== 'object') return {};
+  if (data.capExceeded === true || data.chargeable === false) return pick(data, BILLING_QUOTE_REFUSAL_FIELDS);
+  return pick(data, BILLING_QUOTE_FIELDS);
+}
+
+// ---- Action results -----------------------------------------------------------------------------------
+// The lifecycle routes answer `{ ok: true }`. Redeploy/rollback answer `{ ok, building?, deployment }`
+// where `deployment` is the ENGINE's own envelope - which on one path is the upstream provider's raw
+// response and can carry an upstream message string. That envelope is therefore NEVER passed through:
+// only the deployment id is extracted, and only if it is a plain scalar (rule 6, rule 3).
+export function actionResult(data, { message } = {}) {
+  const out = { ok: !!(data && data.ok === true) };
+  if (data && data.building === true) out.queued = true;
+  const dep = data && data.deployment;
+  const first = dep && Array.isArray(dep.deployments) ? dep.deployments[0] : null;
+  const id = first && first.deployment_uuid;
+  if (typeof id === 'string' && id) out.deploymentId = id;
+  if (message) out.message = message;
+  return out;
+}
+
+// pick / pickAll - the projection primitive the Phase B and C tools are built from. `pick` is the one
+// that has been here since v1; it is EXPORTED rather than copied, because a second implementation of the
+// projection rule is the drift this file exists to prevent.
+//
+// They live HERE rather than in tools/reads.js because of what tests/staticScan asserts: every tool module
+// must project through this file, so that the value-level scan sweeps every shaper in one place. A tool
+// with an inline projection is invisible to that scan, which is the shape of bugs #26 and #34 - the guard
+// stays green while the thing it guards has moved out from under it.
+//
+// The rule they enforce is the conservative one golden rule 6 needs: a tool forwards a NAMED subset of a
+// response, never the raw envelope, so a payload that grows an infra field upstream does not start leaking
+// it here by default.
+export const pickAll = (rows, keys) => (Array.isArray(rows) ? rows.map((r) => pick(r, keys)) : []);
+
+// Every shaper, by name, so a test can sweep ALL of them against realistic payloads in one place. A
+// whitelist that a new shaper forgets to join is a whitelist with a hole in it.
+export const ALL_SHAPERS = {
+  service, serviceStatus, deployment, buildLog, domains, database, usage, actionResult,
+  billingMe, billingInvoices, billingSummary, billingQuote,
+};

package/src/mcp/tools/actions.js

@@ -0,0 +1,94 @@
+// The six REVERSIBLE action tools (scope services:act). Each row here must have a matching entry in
+// ../reversibilityMap.json AND a matching services:act capability in the backend allow-list - both
+// directions are CI-asserted by backend/tests/customerMcpCapabilities.test.js, so a tool cannot exist here
+// without a server capability, and a server capability cannot exist without a declared reversibility.
+//
+// Descriptions are written for a MODEL to reason about, not just for a human to read: each one states
+// plainly what happens and, where it matters, what the customer will notice. `stop` says the service goes
+// down, because a description that undersells the effect is how an agent takes a site offline on a vague
+// instruction.
+
+import { makeServiceAction } from './_action.js';
+
+export const redeploy = makeServiceAction({
+  name: 'redeploy',
+  path: 'redeploy',
+  successMessage: 'Deploy started. Use get_deploy_history and get_build_log to follow it.',
+  description:
+    'Build and deploy the current code on the service\'s configured branch. The service keeps serving the '
+    + 'existing version while the build runs, and a failed build changes nothing. Reversible: the previous '
+    + 'version stays available through rollback. Rate limited - a repeated call within a short window is '
+    + 'refused.',
+});
+
+export const restart = makeServiceAction({
+  name: 'restart',
+  path: 'restart',
+  successMessage: 'Restart requested.',
+  description:
+    'Restart the running service without rebuilding it. Brief interruption while the container comes back. '
+    + 'No code, configuration or data changes. Reversible.',
+});
+
+export const stop = makeServiceAction({
+  name: 'stop',
+  path: 'stop',
+  successMessage: 'Service stopped. It will not serve traffic until you start it again.',
+  description:
+    'Stop the service. IT WILL STOP SERVING TRAFFIC and will stay down until someone starts it again - '
+    + 'confirm with the person before using this on anything live. Nothing is deleted and no data is lost; '
+    + 'start reverses it.',
+});
+
+export const start = makeServiceAction({
+  name: 'start',
+  path: 'start',
+  successMessage: 'Service started.',
+  description:
+    'Start a stopped service so it serves traffic again. Reversible: stop reverses it.',
+});
+
+export const cancelDeploy = makeServiceAction({
+  name: 'cancel_deploy',
+  path: 'deploy/cancel',
+  successMessage: 'Cancel requested. Use get_deploy_history to confirm what stopped.',
+  description:
+    'Stop a deploy that is still running or waiting. A queued deploy is dropped and a running build is '
+    + 'killed; whatever is serving right now keeps serving. If the new version has already gone live it is '
+    + 'too late and nothing is undone - use rollback for that. Cancelling nothing is not an error. '
+    + 'Reversible: deploy again to re-run it. A cancelled deploy still counts toward the plan\'s build '
+    + 'minutes (time rounds up to whole minutes), so avoid deploy/cancel loops.',
+});
+
+// Wave 2 (plan 2026-10-27). Both reversible in the plain sense: nothing is destroyed and nothing changes
+// that does not refill or re-read itself.
+export const purgeEdgeCache = makeServiceAction({
+  name: 'purge_edge_cache',
+  path: 'edge-cache/purge',
+  successMessage: 'Cache cleared. Visitors fetch fresh copies on their next request.',
+  description:
+    'Clear the edge cache of a web service, so every visitor gets the current files on their next request. '
+    + 'Nothing is deleted from the service; the cache simply refills. Does nothing when edge caching is off. '
+    + 'Reversible - there is nothing to reverse.',
+});
+
+export const scanDisk = makeServiceAction({
+  name: 'scan_disk',
+  path: 'disk/scan',
+  successMessage: 'Scan complete.',
+  description:
+    'Measure what is using the service\'s disk right now and return the largest paths. Read-only: it changes '
+    + 'nothing on the service. Rate limited - call it once, not in a loop.',
+});
+
+export const rollback = makeServiceAction({
+  name: 'rollback',
+  path: 'rollback',
+  successMessage: 'Rollback started. Use get_service_status to confirm the previous version is serving.',
+  description:
+    'Serve the previous version of the service again, using the copy already on the host - no rebuild, so '
+    + 'it is fast. If there is no previous version, or the previous version fails to come up, the current '
+    + 'version keeps serving and nothing changes. Reversible: redeploy moves forward again. Not available '
+    + 'for every service; the tool says so plainly when it is not. Each rollback attempt still counts '
+    + 'toward the plan\'s build minutes (rounded up to whole minutes), even when nothing was restored.',
+});

package/src/mcp/tools/getBuildLog.js

@@ -0,0 +1,39 @@
+// get_build_log - READ (scope services:read). The build output for one deploy.
+// Maps to GET /apps/:uuid/deployments/:deploymentId/log.
+//
+// The log body is redacted SERVER-side (per engine) before it leaves Voroa, so this tool does not - and
+// must not claim to - redact anything itself. Old deploys report available:false with reason 'retention'
+// rather than an empty log, so "nothing to show" and "we no longer keep this" stay distinguishable.
+
+import { jsonResponse, badInput } from '../lib/response.js';
+import { serviceId, deploymentId } from './_ids.js';
+import { buildLog } from './_shape.js';
+
+export const getBuildLog = {
+  name: 'get_build_log',
+  kind: 'read',
+  scope: 'services:read',
+  description:
+    'Read the build log for one deploy: the phase timeline (clone, install, build, deploy) plus the build '
+    + 'output. This is the tool for "why did my deploy fail". Logs are kept for a limited window; an older '
+    + 'deploy returns available:false with reason "retention". Read-only.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      serviceId: { type: 'string', description: 'The service id, from list_services.' },
+      deployId: { type: 'string', description: 'The deploy id, from get_deploy_history.' },
+    },
+    required: ['serviceId', 'deployId'],
+    additionalProperties: false,
+  },
+  async handler(args, ctx) {
+    const id = serviceId(args.serviceId);
+    if (!id) throw badInput('serviceId is required and must be a valid service id from list_services.');
+    const dep = deploymentId(args.deployId);
+    if (!dep) throw badInput('deployId is required and must be a deploy id from get_deploy_history.');
+    const data = await ctx.http.get(
+      `/apps/${encodeURIComponent(id)}/deployments/${encodeURIComponent(dep)}/log`
+    );
+    return jsonResponse(buildLog(data));
+  },
+};

package/src/mcp/tools/getDeployHistory.js

@@ -0,0 +1,42 @@
+// get_deploy_history - READ (scope services:read). Recent deploys for a service, newest first.
+// Maps to GET /apps/:uuid/deployments.
+
+import { jsonResponse, badInput } from '../lib/response.js';
+import { serviceId } from './_ids.js';
+import { deployment } from './_shape.js';
+
+// Upper bound on what a single tool call prints into the transcript. The API returns its own page; this
+// clamps what we surface so one call cannot flood a conversation window.
+const MAX_ROWS = 30;
+
+export const getDeployHistory = {
+  name: 'get_deploy_history',
+  kind: 'read',
+  scope: 'services:read',
+  description:
+    'List recent deploys for a service, newest first: deploy id, build outcome, honest verdict, commit, '
+    + 'commit message, and start/finish times. Use the deploy id with get_build_log to see why one '
+    + 'failed. Read-only.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      serviceId: { type: 'string', description: 'The service id, from list_services.' },
+      limit: { type: 'integer', description: `How many deploys to return (1-${MAX_ROWS}, default 10).` },
+    },
+    required: ['serviceId'],
+    additionalProperties: false,
+  },
+  async handler(args, ctx) {
+    const id = serviceId(args.serviceId);
+    if (!id) throw badInput('serviceId is required and must be a valid service id from list_services.');
+    const want = Number.isFinite(Number(args.limit)) ? Number(args.limit) : 10;
+    const limit = Math.min(Math.max(Math.trunc(want), 1), MAX_ROWS);
+    const data = await ctx.http.get(`/apps/${encodeURIComponent(id)}/deployments`);
+    const rows = Array.isArray(data && data.deployments) ? data.deployments : [];
+    return jsonResponse({
+      deploys: rows.slice(0, limit).map(deployment),
+      returned: Math.min(rows.length, limit),
+      total: rows.length,
+    });
+  },
+};

package/src/mcp/tools/getRuntimeLogs.js

@@ -0,0 +1,44 @@
+// get_runtime_logs - READ (scope services:read). What the running service has printed.
+// Maps to GET /apps/:uuid/logs?lines=N[&q=TEXT]. `search` (ADR-0370) is the dashboard's search: lines containing the
+// text, case-insensitive, matched by the server over the last 24 hours - so an agent can find one error line
+// without pulling a thousand. Checked here too (<= 200 chars, one line, no backtick) so a bad value is BAD_INPUT
+// before any request, the same rule the backend enforces.
+//
+// `lines` is ALWAYS sent (known bug #8: an unbounded log read is a huge payload). The backend clamps to
+// 1-1000 as well - this clamp is the client half, so a model asking for 100000 gets a sensible answer
+// rather than a rejection.
+
+import { jsonResponse, badInput } from '../lib/response.js';
+import { serviceId } from './_ids.js';
+
+const DEFAULT_LINES = 200;
+const MAX_LINES = 1000;
+
+export const getRuntimeLogs = {
+  name: 'get_runtime_logs',
+  kind: 'read',
+  scope: 'services:read',
+  description:
+    'Read the most recent output from a running service (its own application logs). Use this for "my app '
+    + 'is up but behaving wrong"; use get_build_log instead for "my deploy failed". Read-only.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      serviceId: { type: 'string', description: 'The service id, from list_services.' },
+      lines: { type: 'integer', description: `How many recent lines (1-${MAX_LINES}, default ${DEFAULT_LINES}).` },
+      search: { type: 'string', description: 'Optional. Only lines containing this text (case-insensitive), up to 200 characters.' },
+    },
+    required: ['serviceId'],
+    additionalProperties: false,
+  },
+  async handler(args, ctx) {
+    const id = serviceId(args.serviceId);
+    if (!id) throw badInput('serviceId is required and must be a valid service id from list_services.');
+    const want = Number.isFinite(Number(args.lines)) ? Number(args.lines) : DEFAULT_LINES;
+    const lines = Math.min(Math.max(Math.trunc(want), 1), MAX_LINES);
+    const search = typeof args.search === 'string' ? args.search.trim() : '';
+    if (search.length > 200 || /[`\r\n]/.test(search)) throw badInput('search must be one line of up to 200 characters, without backticks.');
+    const data = await ctx.http.get(`/apps/${encodeURIComponent(id)}/logs`, search ? { lines, q: search } : { lines });
+    return jsonResponse({ logs: typeof (data && data.logs) === 'string' ? data.logs : '', lines, ...(search && { search }) });
+  },
+};

package/src/mcp/tools/getServiceStatus.js

@@ -0,0 +1,41 @@
+// get_service_status - READ (scope services:read). The honest current state of one service.
+// Maps to GET /apps/:uuid/status.
+
+import { jsonResponse, badInput } from '../lib/response.js';
+import { serviceId } from './_ids.js';
+import { serviceStatus } from './_shape.js';
+
+export const getServiceStatus = {
+  name: 'get_service_status',
+  kind: 'read',
+  scope: 'services:read',
+  description:
+    'Check one service: whether it is running, whether a deploy is in progress, the outcome of the latest '
+    + 'deploy, and its live addresses. Read-only. Fields: `verdict` is the honest outcome of the LATEST '
+    + 'deploy (building, starting, live, failed_to_start, failed, sleeping, suspended - or '
+    + 'skipped/cancelled when the '
+    + 'latest request did not run, e.g. a rollback with nothing to restore). "suspended" means Voroa '
+    + 'stopped the service because it kept restarting without ever staying up; nothing was deleted, and '
+    + 'starting or redeploying it is all it takes to bring it back. `runningState` is what the '
+    + 'service is doing RIGHT NOW (running, starting, restarting, deploying, degraded, failed, stopped, '
+    + 'unknown - or unavailable, meaning the platform could not read the state at that moment: retry '
+    + 'before concluding anything). `health` is its own health check (healthy, unhealthy, unknown - '
+    + '"unknown" usually means no '
+    + 'health check is configured, NOT that anything is wrong). `crashLooping` is true when the service is '
+    + 'repeatedly restarting AND failing its health check: that means it starts, dies, and starts again, so '
+    + 'read the recent output with get_runtime_logs rather than deploying again.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      serviceId: { type: 'string', description: 'The service id, from list_services.' },
+    },
+    required: ['serviceId'],
+    additionalProperties: false,
+  },
+  async handler(args, ctx) {
+    const id = serviceId(args.serviceId);
+    if (!id) throw badInput('serviceId is required and must be a valid service id from list_services.');
+    const data = await ctx.http.get(`/apps/${encodeURIComponent(id)}/status`);
+    return jsonResponse(serviceStatus(data));
+  },
+};

package/src/mcp/tools/getUsage.js

@@ -0,0 +1,34 @@
+// get_usage - READ (scope services:read). Metered usage for a billing period against the plan's pools.
+// Maps to GET /usage?period=YYYY-MM.
+
+import { jsonResponse, badInput } from '../lib/response.js';
+import { period as parsePeriod } from './_ids.js';
+import { usage } from './_shape.js';
+
+export const getUsage = {
+  name: 'get_usage',
+  kind: 'read',
+  scope: 'services:read',
+  description:
+    'Read usage for a billing period, against what the plan includes. The result is grouped by grain: '
+    + '`account` fields (build minutes, total bandwidth) cover the WHOLE account across every workspace; '
+    + '`workspace` fields cover only the workspace this token is bound to. `bandwidthMeasured: false` '
+    + 'means the platform does not measure workspace bandwidth yet - it does NOT mean zero was used. '
+    + 'Read-only - this shows usage, not charges, and nothing here can change a plan or a bill.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      period: { type: 'string', description: 'Billing period as YYYY-MM. Omit for the current period.' },
+    },
+    additionalProperties: false,
+  },
+  async handler(args, ctx) {
+    let period;
+    if (args.period != null && args.period !== '') {
+      period = parsePeriod(args.period);
+      if (!period) throw badInput('period must be in YYYY-MM form, for example 2026-08.');
+    }
+    const data = await ctx.http.get('/usage', period ? { period } : undefined);
+    return jsonResponse(usage(data));
+  },
+};

package/src/mcp/tools/listDatabases.js

@@ -0,0 +1,25 @@
+// list_databases - READ (scope services:read). The managed databases in this workspace.
+// Maps to GET /databases.
+//
+// Connection credentials are NOT reachable from this surface at all: GET /databases/:uuid/connection is
+// absent from the backend capability allow-list, so there is no argument by which this tool could return
+// a password (golden rule 4 - a stored secret is write-only, and it is certainly not going in a
+// transcript).
+
+import { jsonResponse } from '../lib/response.js';
+import { database } from './_shape.js';
+
+export const listDatabases = {
+  name: 'list_databases',
+  kind: 'read',
+  scope: 'services:read',
+  description:
+    'List the managed databases in your workspace with their name, type and state. Connection details and '
+    + 'passwords are NOT available here - get them from your Voroa dashboard. Read-only.',
+  inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  async handler(_args, ctx) {
+    const data = await ctx.http.get('/databases');
+    const rows = Array.isArray(data && data.databases) ? data.databases : [];
+    return jsonResponse({ databases: rows.map(database), count: rows.length });
+  },
+};