@nullplatform/mcp 0.1.0

package/dist/render.js

@@ -0,0 +1,236 @@
+import { translate } from "./i18n.js";
+import { ago, glyph, linkLine, next, shortCommit, statusLabel, table } from "./md.js";
+import { isDeploymentTerminal } from "./np/journey.js";
+export function renderAppHeader(app) {
+    const where = [app.namespace, app.account].filter(Boolean).join(" / ");
+    const repo = app.repository_url ? `\nrepo ${app.repository_url}` : "";
+    return `**${app.name}** · #${app.id}${where ? ` · ${where}` : ""}${repo}`;
+}
+function trafficBar(percent) {
+    if (percent === undefined || percent === null || Number.isNaN(percent))
+        return "";
+    const filled = Math.round(percent / 10);
+    return `\`${"▓".repeat(filled)}${"░".repeat(10 - filled)}\` ${percent}%`;
+}
+function releaseLabel(release, releaseId) {
+    if (release)
+        return release.semver;
+    return releaseId ? `release #${releaseId}` : "—";
+}
+export function renderScopeRows(views) {
+    if (views.length === 0)
+        return translate("render.noScopes");
+    const domains = views
+        .filter((view) => view.scope.domain && view.current && view.current.status === "finalized")
+        .map((view) => `- ${view.scope.name}: https://${view.scope.domain}`);
+    const scopeTable = table([
+        translate("header.scope"),
+        translate("header.status"),
+        translate("header.live"),
+        translate("header.traffic"),
+        translate("header.when"),
+    ], views.map((view) => {
+        const deployment = view.current;
+        const rollingOut = deployment && !isDeploymentTerminal(deployment.status);
+        const traffic = deployment?.strategy_data?.switchedTraffic;
+        const dimensions = Object.values(view.scope.dimensions ?? {}).join("/");
+        return [
+            view.scope.name + (dimensions ? ` (${dimensions})` : ""),
+            rollingOut ? statusLabel(deployment.status) : statusLabel(view.scope.status),
+            deployment
+                ? releaseLabel(view.live_release, deployment.release_id) + (rollingOut ? " ⏳" : "")
+                : translate("render.nothingDeployed"),
+            traffic !== undefined ? `${traffic}%` : "",
+            ago(deployment?.created_at),
+        ];
+    }));
+    return domains.length ? `${scopeTable}\n${domains.join("\n")}` : scopeTable;
+}
+export function statusNextHint(args) {
+    const { views, latestBuild, latestRelease } = args;
+    const activeView = views.find((view) => view.current && !isDeploymentTerminal(view.current.status));
+    if (activeView?.current) {
+        const deployment = activeView.current;
+        const traffic = deployment.strategy_data?.switchedTraffic;
+        if (deployment.status === "running" && traffic !== undefined && traffic < 100) {
+            return translate("hint.rolloutTraffic", {
+                id: deployment.id,
+                scope: activeView.scope.name,
+                traffic,
+            });
+        }
+        return translate("hint.rolloutStatus", {
+            id: deployment.id,
+            scope: activeView.scope.name,
+            status: deployment.status.replace(/_/g, " "),
+        });
+    }
+    if (views.length === 0)
+        return translate("hint.noScopes");
+    if (latestBuild?.status === "successful" && latestRelease && latestRelease.build_id !== latestBuild.id) {
+        return translate("hint.buildNewer", {
+            id: latestBuild.id,
+            branch: latestBuild.branch ?? "?",
+            commit: shortCommit(latestBuild.commit),
+            semver: latestRelease.semver,
+        });
+    }
+    if (latestBuild?.status === "successful" && !latestRelease) {
+        return translate("hint.buildUnreleased", { id: latestBuild.id });
+    }
+    if (latestRelease) {
+        const liveSomewhere = views.some((view) => view.current && view.current.release_id === latestRelease.id);
+        if (!liveSomewhere)
+            return translate("hint.releaseNotLive", { semver: latestRelease.semver });
+    }
+    if (!latestBuild)
+        return translate("hint.noBuilds");
+    return translate("hint.upToDate");
+}
+export function renderStatus(args) {
+    const { app, views, builds, releases, dashboard } = args;
+    const latestBuild = builds[0];
+    const latestRelease = releases[0];
+    const liveOn = (releaseId) => views.filter((view) => view.current?.release_id === releaseId).map((view) => view.scope.name);
+    const releaseList = releases
+        .slice(0, 4)
+        .map((release) => {
+        const scopes = liveOn(release.id);
+        return `${release.semver}${scopes.length
+            ? ` ${glyph("active")} ${translate("render.liveOn", { scopes: scopes.join(", ") })}`
+            : ""}`;
+    })
+        .join(" · ");
+    const latestBuildLine = latestBuild
+        ? `${glyph(latestBuild.status)} #${latestBuild.id} ${latestBuild.branch ?? ""} @${shortCommit(latestBuild.commit)} (${ago(latestBuild.created_at)})`
+        : translate("render.noBuilds");
+    const lines = [
+        renderAppHeader(app),
+        "",
+        renderScopeRows(views),
+        "",
+        `**${translate("render.latestBuild")}** ${latestBuildLine}`,
+        `**${translate("render.releases")}** ${releaseList || translate("md.none")}`,
+        next(statusNextHint({ views, latestBuild, latestRelease })) +
+            linkLine(translate("md.dashboard"), dashboard),
+    ];
+    return {
+        md: lines.join("\n"),
+        structured: {
+            application: app,
+            scopes: views.map((view) => ({
+                ...view.scope,
+                current_deployment: view.current
+                    ? {
+                        id: view.current.id,
+                        status: view.current.status,
+                        release_id: view.current.release_id,
+                        traffic: view.current.strategy_data?.switchedTraffic,
+                    }
+                    : null,
+                live_release: view.live_release ?? null,
+            })),
+            latest_build: latestBuild ?? null,
+            releases: releases.map((release) => ({
+                id: release.id,
+                semver: release.semver,
+                status: release.status,
+                created_at: release.created_at,
+                live_on: liveOn(release.id),
+            })),
+            hint: statusNextHint({ views, latestBuild, latestRelease }),
+            dashboard: dashboard ?? null,
+        },
+    };
+}
+export function rolloutNextHint(deployment) {
+    const traffic = deployment.strategy_data?.switchedTraffic;
+    const desired = deployment.strategy_data?.desiredSwitchedTraffic;
+    switch (deployment.status) {
+        case "running":
+            if (traffic === 100)
+                return translate("rollout.full");
+            if (desired !== undefined && desired !== traffic) {
+                return translate("rollout.moving", { from: traffic ?? 0, to: desired, id: deployment.id });
+            }
+            return translate("rollout.at", { traffic: traffic ?? 0 });
+        case "creating":
+        case "waiting_for_instances":
+            return translate("rollout.instances", { id: deployment.id });
+        case "switching_traffic":
+            return translate("rollout.switching", { id: deployment.id });
+        case "finalizing":
+            return translate("rollout.finalizing");
+        case "finalized":
+            return translate("rollout.done");
+        case "creating_approval":
+            return translate("rollout.approval");
+        case "failed":
+            return translate("rollout.failed");
+        case "cancelled":
+        case "rolled_back":
+            return translate("rollout.rolledBack");
+        default:
+            return translate("hint.watch", { id: deployment.id });
+    }
+}
+export function renderRollout(args) {
+    const { deployment, scope, release, dashboard } = args;
+    const traffic = deployment.strategy_data?.switchedTraffic;
+    const desired = deployment.strategy_data?.desiredSwitchedTraffic;
+    const recent = (deployment.messages ?? []).slice(-5).map((entry) => {
+        const time = entry.timestamp ? new Date(entry.timestamp).toISOString().slice(11, 19) : "";
+        return `- ${time} ${entry.source ? `[${entry.source}] ` : ""}${entry.message}`.trim();
+    });
+    const startedWhen = ago(deployment.created_at) || translate("render.now");
+    const lines = [
+        `${args.title ?? translate("render.deployment")} #${deployment.id}${scope ? ` on **${scope.name}**` : ""} — ${statusLabel(deployment.status)}`,
+        release
+            ? `${translate("render.release")} **${release.semver}** · ${translate("render.started", { when: startedWhen })}`
+            : translate("render.started", { when: startedWhen }),
+        traffic !== undefined
+            ? `${translate("header.traffic")} ${trafficBar(traffic)}${desired !== undefined && desired !== traffic
+                ? ` ${translate("render.desired", { pct: desired })}`
+                : ""}`
+            : "",
+        recent.length ? `\n${recent.join("\n")}` : "",
+        next(rolloutNextHint(deployment)) + linkLine(translate("md.dashboard"), dashboard),
+    ].filter(Boolean);
+    return {
+        md: lines.join("\n"),
+        structured: {
+            deployment: {
+                id: deployment.id,
+                status: deployment.status,
+                terminal: isDeploymentTerminal(deployment.status),
+                traffic: traffic ?? null,
+                desired_traffic: desired ?? null,
+                scope_id: deployment.scope_id ?? scope?.id ?? null,
+                scope_name: scope?.name ?? null,
+                application_id: scope?.application_id ?? null,
+                release_id: deployment.release_id ?? null,
+                release_semver: release?.semver ?? null,
+                messages: (deployment.messages ?? []).slice(-40).map((entry) => ({
+                    timestamp: entry.timestamp ?? null,
+                    source: entry.source ?? null,
+                    message: entry.message,
+                })),
+            },
+        },
+    };
+}
+export function renderAppsTable(apps) {
+    return table([
+        translate("header.app"),
+        translate("header.id"),
+        translate("header.namespace"),
+        translate("header.account"),
+        translate("header.status"),
+    ], apps.map((app) => [
+        app.name,
+        `#${app.id}`,
+        app.namespace ?? "",
+        app.account ?? "",
+        statusLabel(app.status),
+    ]));
+}

package/dist/server.js

@@ -0,0 +1,91 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { detectRepoUrl } from "./git.js";
+import { TokenManager } from "./np/auth.js";
+import { NpClient } from "./np/client.js";
+import { NpContext } from "./np/context.js";
+import { loadSkills, registerPlaybookResources, skillsInstructionBlock } from "./skills.js";
+import { defaultSurface } from "./surfaces/index.js";
+import { registerTools } from "./tool.js";
+import { EXTENSION_ID, RESOURCE_MIME_TYPE, registerWidgets, uiNegotiated } from "./ui.js";
+export function buildDeps(config, fetchImpl = fetch, tokenSource) {
+    const tokens = tokenSource ??
+        new TokenManager({ apiBase: config.apiBase, apiKey: config.apiKey, bearer: config.bearer }, fetchImpl);
+    const np = new NpClient({
+        apiBase: config.apiBase,
+        getToken: () => tokens.getToken(),
+        onUnauthorized: async () => tokens.invalidate(),
+    }, fetchImpl);
+    const org = new NpContext(np);
+    const bff = new NpClient({
+        apiBase: config.bffBase,
+        getToken: () => tokens.getToken(),
+        onUnauthorized: async () => tokens.invalidate(),
+        getExtraHeaders: async () => {
+            const orgSlug = await org.organizationSlug();
+            return orgSlug ? { "Np-Organization-Slug": orgSlug } : {};
+        },
+    }, fetchImpl);
+    return { np, org, bff, tokens };
+}
+export function buildServer(deps, options = {}) {
+    const surface = options.surface ?? defaultSurface;
+    // Operating playbooks (skills/*.md) are inlined straight into the instructions below, so the
+    // model always has the methodology in context — nothing to fetch, nothing to "run as a skill".
+    const skills = loadSkills();
+    const server = new McpServer({ name: surface.serverName, version: "0.1.0" }, {
+        capabilities: {
+            logging: {},
+            // MCP Apps capability negotiation (SEP-1724/SEP-1865): hosts gate widget
+            // rendering on the server advertising the ui extension.
+            extensions: { [EXTENSION_ID]: { mimeTypes: [RESOURCE_MIME_TYPE] } },
+        },
+        instructions: surface.instructions + skillsInstructionBlock(skills),
+    });
+    // Workspace repo detection: prefer the client's MCP roots, fall back to our cwd.
+    let cachedRepoUrl = null;
+    const repoUrl = async () => {
+        if (cachedRepoUrl && Date.now() - cachedRepoUrl.at < 30_000)
+            return cachedRepoUrl.url;
+        let url;
+        try {
+            const clientCapabilities = server.server.getClientCapabilities();
+            if (clientCapabilities?.roots) {
+                const { roots } = await server.server.listRoots();
+                for (const root of roots ?? []) {
+                    const path = root.uri.startsWith("file://")
+                        ? decodeURIComponent(new URL(root.uri).pathname)
+                        : root.uri;
+                    url = await detectRepoUrl(path);
+                    if (url)
+                        break;
+                }
+            }
+        }
+        catch {
+            /* client without roots support */
+        }
+        if (!url)
+            url = await detectRepoUrl(options.cwd ?? process.cwd());
+        cachedRepoUrl = { at: Date.now(), url };
+        return url;
+    };
+    const toolContext = { np: deps.np, org: deps.org, bff: deps.bff, repoUrl };
+    registerTools(server, surface.tools, toolContext);
+    surface.registerPrompts(server);
+    // Passive playbook:// resources (the model reads playbooks via the playbook_get tool, not these);
+    // also the one build-time resource that keeps resources/list available for widget negotiation.
+    registerPlaybookResources(server);
+    // ui mode: widgets bound by the tool specs. Text-only hosts never see them in
+    // "negotiated" mode; in "eager" mode they simply ignore the resources (per spec).
+    const widgetNames = surface.tools.flatMap((tool) => (tool.widget ? [tool.widget] : []));
+    if ((options.uiRegistration ?? "eager") === "eager") {
+        registerWidgets(server, widgetNames);
+    }
+    else {
+        server.server.oninitialized = () => {
+            if (uiNegotiated(server))
+                registerWidgets(server, widgetNames);
+        };
+    }
+    return server;
+}

package/dist/skills.js

@@ -0,0 +1,84 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Operating playbooks — markdown methodology under skills/<name>/SKILL.md, edited by the platform
+ * team without touching server code.
+ *
+ * THE MODEL reads them through the `playbook_get` TOOL (see src/tools/playbook.ts): tools are the
+ * one MCP primitive every coding assistant exposes to the model, so this works uniformly across
+ * Claude Code, Cursor, Claude Desktop, etc. The server instructions carry the catalog so the model
+ * knows which playbook to read before which task; the tool returns the text on demand.
+ *
+ * They are ALSO registered as passive `playbook://nullplatform/<name>` resources — NOT how the
+ * model gets them (it never sees these URIs), but a standard listing for clients/users, and it
+ * keeps the server's `resources` capability alive for widget negotiation. The neutral
+ * `playbook://` scheme is deliberate: the old `skill://` scheme made Claude Desktop route to its
+ * native Agent Skills executor ("Unknown skill") instead of reading the resource.
+ */
+const skillsDir = join(dirname(fileURLToPath(import.meta.url)), "..", "skills");
+function frontmatter(markdown) {
+    const block = /^---\n([\s\S]*?)\n---/.exec(markdown);
+    const fields = {};
+    if (!block?.[1])
+        return fields;
+    for (const line of block[1].split("\n")) {
+        const field = /^([a-zA-Z_-]+):\s*(.+)$/.exec(line);
+        if (field?.[1] && field[2] !== undefined)
+            fields[field[1]] = field[2].trim();
+    }
+    return fields;
+}
+export function loadSkills() {
+    let dirs;
+    try {
+        dirs = readdirSync(skillsDir).filter((entry) => {
+            try {
+                return statSync(join(skillsDir, entry)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+    const skills = [];
+    for (const dir of dirs) {
+        try {
+            const markdown = readFileSync(join(skillsDir, dir, "SKILL.md"), "utf8");
+            const fields = frontmatter(markdown);
+            skills.push({ name: fields.name ?? dir, description: fields.description ?? "", markdown });
+        }
+        catch {
+            /* directory without SKILL.md */
+        }
+    }
+    return skills;
+}
+/**
+ * Register the playbooks as passive `playbook://` resources — a standard listing, and the only
+ * resource registered at build time, which keeps `resources/list` working for negotiated widget
+ * sessions. The model is pointed at the `playbook_get` tool, never at these URIs.
+ */
+export function registerPlaybookResources(server) {
+    for (const skill of loadSkills()) {
+        const uri = `playbook://nullplatform/${skill.name}`;
+        server.registerResource(`Playbook: ${skill.name}`, uri, { description: skill.description, mimeType: "text/markdown" }, async () => ({ contents: [{ uri, mimeType: "text/markdown", text: skill.markdown }] }));
+    }
+}
+/**
+ * The playbook catalog appended to the server instructions — names + when-to-use, plus the
+ * pointer to the `playbook_get` tool. No skill:// URIs and no "skill" wording (that is exactly
+ * what made Claude Desktop try to execute a skill).
+ */
+export function skillsInstructionBlock(skills) {
+    if (!skills.length)
+        return "";
+    const catalog = skills.map((skill) => `- \`${skill.name}\` — ${skill.description}`).join("\n");
+    return ("\n\n# Operating playbooks\n\nThese encode how to do non-trivial work safely. BEFORE the matching " +
+        'task, call the `playbook_get` tool to read the relevant one (e.g. `playbook_get name:"deploying-safely"` ' +
+        "before any deploy) and follow it — do not improvise:\n" +
+        catalog);
+}

package/dist/surfaces/developer.js

@@ -0,0 +1,29 @@
+import { registerPrompts } from "../prompts.js";
+import { tools } from "../tools/index.js";
+/**
+ * The developer surface — the flagship `@nullplatform/mcp`. Audience: app developers
+ * driving build → release → deploy → observe of *their* application from a code assistant.
+ */
+const INSTRUCTIONS = `nullplatform is where this code gets built, released, deployed and observed — these tools replace its web dashboard for the everyday developer journey.
+
+The tools are repo-aware: inside a git repo, omit \`app\` and the linked application is inferred from the git remote. Start with \`application_get\` — it shows what's live where and suggests the next action.
+
+Every tool accepts \`language\`: ALWAYS set it to the language the user is conversing in (ISO code, e.g. "es", "en") — answers come back in the user's language.
+
+Most tools render an interactive panel in clients that support it — the user sees apps, status, logs, metrics and parameters as live UI. When that panel renders, the user can already see the result: do NOT restate or summarise it in text (no re-listing applications, reprinting tables, or repeating status/metrics). Reply with at most one short sentence — the single key takeaway or next step — or nothing at all. Add prose only for something the panel doesn't already show.
+
+When the user wants to create, scaffold, set up or import an application, call \`application_create\` right away — pass a name if they gave one, otherwise no arguments. Its panel is an interactive FORM that collects the namespace, template and repository itself. Do NOT gather those details in conversation first, and while that form is on screen do NOT ask the user clarifying questions or use any question-asking tool for fields the form already covers (namespace, template, new-vs-import repository, monorepo path) — the form is the input surface. Just call \`application_create\` and let it drive; react only to what it reports back.
+
+Typical flows:
+- Ship: \`application_deployment_create\` (picks the latest build, cuts the release for you) → \`application_deployment_update percent:25/50/100\` → \`application_deployment_update action:"finalize"\`.
+- First time on a repo: \`application_create\` → push a commit (CI builds) → \`application_deployment_create\`.
+- Trouble: \`application_get\` → \`application_log_list\` + \`application_metric_list\` (golden signals) → \`application_deployment_update action:"rollback"\` if needed.
+
+\`application_deployment_create\`/\`application_scope_create\` provision real infrastructure. Rollback is the safety hatch — it returns traffic to the previous version.`;
+export const developerSurface = {
+    key: "developer",
+    serverName: "nullplatform",
+    instructions: INSTRUCTIONS,
+    tools,
+    registerPrompts,
+};

package/dist/surfaces/index.js

@@ -0,0 +1,17 @@
+import { developerSurface } from "./developer.js";
+/**
+ * The surface registry — the extension point for new audiences. To add one (operator,
+ * insights): create src/surfaces/<name>.ts exporting a Surface and list it here. The entry
+ * point selects a surface by key (NP_SURFACE); a sibling published package just defaults to
+ * a different key.
+ */
+export const surfaces = {
+    developer: developerSurface,
+};
+export const defaultSurface = developerSurface;
+/** Resolve a surface by key, falling back to the developer surface. */
+export function selectSurface(key) {
+    if (key && key in surfaces)
+        return surfaces[key];
+    return defaultSurface;
+}

package/dist/surfaces/surface.js

@@ -0,0 +1 @@
+export {};

package/dist/tool-names.js

@@ -0,0 +1,25 @@
+/**
+ * Single source of truth for the model-facing tool names — `<entity>[_<subentity>]_<action>`
+ * (the convention is documented in CLAUDE.md). Every tool definition, widget `callServerTool`
+ * and test references a `TOOL.*` member instead of re-typing the literal, so a rename is a
+ * one-line change here and a typo can't silently break a widget's tool call. This is a pure
+ * leaf module (no imports) so both the server build and the sandboxed widget bundle can share it.
+ */
+export const TOOL = {
+    applicationCreate: "application_create",
+    applicationList: "application_list",
+    applicationGet: "application_get",
+    applicationLogList: "application_log_list",
+    applicationMetricList: "application_metric_list",
+    applicationBuildList: "application_build_list",
+    applicationParameterList: "application_parameter_list",
+    applicationParameterCreate: "application_parameter_create",
+    applicationDeploymentCreate: "application_deployment_create",
+    applicationDeploymentUpdate: "application_deployment_update",
+    applicationReleaseCreate: "application_release_create",
+    applicationScopeCreate: "application_scope_create",
+    applicationServiceList: "application_service_list",
+    applicationApprovalList: "application_approval_list",
+    organizationGet: "organization_get",
+    playbookGet: "playbook_get",
+};

package/dist/tool.js

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { currentLocale, matchLocale, translate, withLocale } from "./i18n.js";
+import { uiMeta, widgetUri } from "./ui.js";
+/** Markdown for the human + JSON for the model/widget. */
+export function reply(markdown, data) {
+    return { markdown, ...(data ? { data } : {}) };
+}
+export function fail(markdown, data) {
+    return { ...reply(markdown, data), isError: true };
+}
+/** Identity helper: full arg-type inference inside the spec, erased registry type outside. */
+export function defineTool(spec) {
+    // Sound in practice: the SDK validates args against the same inputSchema before calling.
+    return spec;
+}
+/** ToolReply -> wire result. The single place replies become protocol shapes. */
+export function present(toolReply) {
+    return {
+        content: [{ type: "text", text: toolReply.markdown.trim() }],
+        ...(toolReply.data ? { structuredContent: toolReply.data } : {}),
+        ...(toolReply.isError ? { isError: true } : {}),
+    };
+}
+/**
+ * Injected into every tool: only the model knows what language the user is conversing
+ * in, so the model declares it per call and replies come back localized. Takes priority
+ * over the transport/env locale.
+ */
+const languageArg = z
+    .string()
+    .optional()
+    .describe('Reply language — the language the user is conversing in, as an ISO code (e.g. "en", "es"). Set it on every call.');
+export function registerTools(server, tools, context) {
+    for (const tool of tools) {
+        if ("language" in tool.inputSchema) {
+            throw new Error(`tool "${tool.name}" must not define its own "language" argument — the framework injects it`);
+        }
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            annotations: tool.annotations,
+            ...(tool.widget ? { _meta: uiMeta(widgetUri(tool.widget)) } : {}),
+            inputSchema: { ...tool.inputSchema, language: languageArg },
+        }, async (rawArgs) => present(await runInUserLanguage(tool, rawArgs, context)));
+    }
+}
+/** Honour the LLM-declared conversation language, falling back to the ambient locale. */
+async function runInUserLanguage(tool, rawArgs, context) {
+    const { language, ...args } = (rawArgs ?? {});
+    const requested = typeof language === "string" ? matchLocale(language) : undefined;
+    const locale = requested ?? currentLocale();
+    const toolReply = requested
+        ? await withLocale(requested, () => run(tool, args, context))
+        : await run(tool, args, context);
+    // Stamp the effective locale so ui-mode widgets can localize their own chrome
+    // (the data channel is the only way the locale reaches the sandboxed widget).
+    if (toolReply.data)
+        toolReply.data._locale = locale;
+    return toolReply;
+}
+/** One error net for every tool — no reply ever escapes as a raw protocol error. */
+async function run(tool, args, context) {
+    try {
+        return await tool.handler(args, context);
+    }
+    catch (caught) {
+        const message = errorMessage(caught);
+        return tool.onError?.(message) ?? fail(`${translate(tool.errorKey)}: ${message}`);
+    }
+}
+/** Bound a detail string: an unexpected or large upstream body must not flood the answer. */
+function clampDetail(text, max = 300) {
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+export function errorMessage(caught) {
+    const failure = caught;
+    const body = failure?.body;
+    const detail = body && typeof body === "object" ? (body.message ?? body.error ?? JSON.stringify(body)) : body;
+    // RBAC is the platform's, enforced with the caller's own token — say so plainly.
+    const friendly = failure?.status === 401
+        ? translate("error.credentialRejected", { status: 401 })
+        : failure?.status === 403
+            ? translate("error.permission")
+            : "";
+    return [
+        friendly,
+        failure?.message ?? String(caught),
+        detail && detail !== failure?.message ? clampDetail(String(detail)) : "",
+    ]
+        .filter(Boolean)
+        .join(" — ");
+}

package/dist/tools/approvals.js

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { ago, dashboardLink, glyph, linkLine, next, table } from "../md.js";
+import { cancelApproval, executeApproval, isSafeApprovalId, listApprovals } from "../np/journey.js";
+import { defineTool, fail, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { appArg, requireApp } from "./shared.js";
+/**
+ * Approvals as a first-class loop. On the web an approval is a notification; for an agent
+ * driving a deploy it's a blocking state it must see and (where RBAC allows) act on. List
+ * is fully grounded; approve/cancel call the exact endpoints the dashboard uses, gated by
+ * the caller's own token — so a user without permission gets the platform's 403 verbatim.
+ */
+export const approvalsTool = defineTool({
+    name: TOOL.applicationApprovalList,
+    title: "Approvals",
+    description: 'List the approvals gating an application\'s actions (e.g. a deployment waiting on a policy), and act on one. action:"approve" lets the gated action proceed; action:"cancel" cancels the request. Both use your own permissions — the platform denies what you\'re not allowed to do. Use this when a deploy is stuck in creating_approval.',
+    annotations: { destructiveHint: false, openWorldHint: true },
+    errorKey: "approvals.errorLabel",
+    inputSchema: {
+        app: appArg,
+        action: z.enum(["approve", "cancel"]).optional().describe("Act on an approval (requires approval_id)"),
+        approval_id: z.string().optional().describe("The approval to act on"),
+        status: z.string().optional().describe('Filter the list (e.g. "pending"); default shows pending'),
+    },
+    async handler(args, context) {
+        if (args.action) {
+            if (!args.approval_id)
+                return fail(translate("approvals.needId"));
+            // The approval id lands in a URL path — reject anything that isn't a platform-id shape
+            // so a steered/injected value can't redirect the authenticated POST elsewhere.
+            if (!isSafeApprovalId(args.approval_id))
+                return fail(translate("approvals.invalidId"));
+            if (args.action === "approve")
+                await executeApproval(context.bff, args.approval_id);
+            else
+                await cancelApproval(context.bff, args.approval_id);
+            return reply(translate(args.action === "approve" ? "approvals.approved" : "approvals.cancelled", {
+                id: args.approval_id,
+            }), { approval_id: args.approval_id, action: args.action });
+        }
+        const resolved = await requireApp(context, args);
+        if ("out" in resolved)
+            return resolved.out;
+        const app = resolved.app;
+        if (!app.nrn)
+            return fail(translate("resolve.noNrn", { app: app.name }));
+        const approvals = await listApprovals(context.bff, app.nrn, { status: args.status ?? "pending" });
+        const orgSlug = await context.org.organizationSlug();
+        if (approvals.length === 0) {
+            return reply(translate("approvals.none", { app: app.name }), { app: `#${app.id}`, approvals: [] });
+        }
+        const markdown = [
+            translate("approvals.title", { app: app.name, count: approvals.length }),
+            "",
+            table([
+                translate("header.id"),
+                translate("approvals.action"),
+                translate("approvals.entity"),
+                translate("header.status"),
+                translate("approvals.requestedBy"),
+                translate("header.when"),
+            ], approvals.map((approval) => [
+                approval.id,
+                approval.action ?? "",
+                approval.entity ?? "",
+                `${glyph(approval.status)} ${approval.status}`,
+                approval.requestedBy ?? "",
+                ago(approval.created_at),
+            ])),
+            next(translate("approvals.actHint", { id: approvals[0]?.id ?? "<id>" })) +
+                linkLine(translate("md.dashboard"), dashboardLink(orgSlug, app.nrn)),
+        ].join("\n");
+        return reply(markdown, {
+            app: `#${app.id}`,
+            app_name: app.name,
+            approvals,
+        });
+    },
+});