@nullplatform/mcp 0.1.5 → 0.1.7

package/dist/tools/create-link.js

@@ -0,0 +1,163 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { dashboardLink, linkLine, next, table } from "../md.js";
+import { createLink, createLinkAction, getLink, linkCreateActionSpec, linkSpecsForService, listAppServices, listLinks, listScopes, } from "../np/journey.js";
+import { defineTool, fail, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { appArg, delays, pickScope, requireApp, sleep } from "./shared.js";
+const slug = (text) => text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+/**
+ * Link a provisioned dependency service to an application or one of its scopes — a SEPARATE
+ * operation from provisioning it (`application_service_create`). Creating the link is one or two
+ * POSTs depending on whether the link spec carries a create-action: a credential link (Postgres
+ * `database-user`) provisions a DB user via `POST /link/{id}/action`; a plain link activates on the
+ * `POST /link` itself. `status` is DERIVED, never an input — sending `active` on a credential link
+ * would skip provisioning and yield a user-less link.
+ */
+export const createLinkTool = defineTool({
+    name: TOOL.applicationLinkCreate,
+    title: "Link service",
+    description: "Link a provisioned dependency service (a database, queue, cache, …) to an application or one of its scopes so its connection details flow in as read-only parameters. Pass `service` to choose which one (by name). A credential link (e.g. a Postgres database-user) provisions a user with the permissions you pick, so call WITHOUT `create:true` first to open the form; the user confirms by submitting it. New parameters reach the runtime on the NEXT deploy.",
+    annotations: { destructiveHint: false, openWorldHint: true },
+    widget: "service-link",
+    errorKey: "createLink.errorLabel",
+    inputSchema: {
+        app: appArg,
+        service: z
+            .string()
+            .optional()
+            .describe("Which provisioned service to link, by name (or the service id returned by a provision)"),
+        scope: z
+            .string()
+            .optional()
+            .describe("Link to this scope (name or dimension) so its params land there; default: the whole app"),
+        parameters: z
+            .record(z.unknown())
+            .optional()
+            .describe("Values for the link create-action parameters (e.g. a database user's permissions)"),
+        create: z
+            .boolean()
+            .optional()
+            .describe("Set true to actually create the link (the form's submit sets it). Omit to return the form."),
+    },
+    async handler(args, context) {
+        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 orgSlug = await context.org.organizationSlug();
+        const dashboard = dashboardLink(orgSlug, app.nrn);
+        // The app's provisioned services — pick which one to link.
+        const services = (await listAppServices(context.np, app.nrn)).filter((service) => service.status !== "failed");
+        if (services.length === 0) {
+            return fail(translate("createLink.noServices", { app: app.name }) + next(translate("createLink.noServicesHint")));
+        }
+        const wanted = args.service?.toLowerCase();
+        const matched = wanted
+            ? services.filter((service) => service.name.toLowerCase().includes(wanted) || service.id === args.service)
+            : [];
+        if (matched.length !== 1) {
+            const list = matched.length > 1 ? matched : services;
+            const md = `${translate(matched.length > 1 ? "createLink.matchAmbiguous" : "createLink.pickService", {
+                app: app.name,
+            })}\n\n${table([translate("header.name"), translate("header.status")], list.map((service) => [service.name, service.status]))}${next(translate("createLink.pickHint"))}`;
+            return reply(md, {
+                mode: "pick-service",
+                app: `#${app.id}`,
+                app_name: app.name,
+                services: list,
+                dashboard,
+            });
+        }
+        const service = matched[0];
+        // The link spec that applies to this service + its create-action (the form's params). Prefer the
+        // spec that PROVISIONS credentials (use_default_actions) — e.g. Postgres `database-user`.
+        const linkSpecs = service.specification_id
+            ? await linkSpecsForService(context.np, service.specification_id)
+            : [];
+        const linkSpec = linkSpecs.find((candidate) => candidate.use_default_actions) ?? linkSpecs[0];
+        if (!linkSpec) {
+            return fail(translate("createLink.noLinkSpec", { service: service.name }) +
+                linkLine(translate("md.dashboard"), dashboard));
+        }
+        const linkCreate = await linkCreateActionSpec(context.np, linkSpec.id);
+        // Resolve the target scope (its dimensions decide where the connection params inject); else app.
+        const scopes = await listScopes(context.np, app.id);
+        let target = { nrn: app.nrn, dimensions: {}, label: app.name };
+        if (args.scope) {
+            const picked = pickScope(scopes, args.scope);
+            if ("scope" in picked && picked.scope.nrn) {
+                target = { nrn: picked.scope.nrn, dimensions: {}, label: picked.scope.name };
+            }
+        }
+        // Form-first: no explicit create OR a required link-param still missing → show the form.
+        const requiredKeys = linkCreate?.schema?.required ?? [];
+        const missing = requiredKeys.filter((key) => args.parameters?.[key] === undefined);
+        if (!args.create || missing.length > 0) {
+            return reply(translate("createLink.form", { service: service.name, app: app.name }) +
+                next(translate("createLink.formHint")), {
+                mode: "form",
+                app: `#${app.id}`,
+                app_name: app.name,
+                service: { id: service.id, name: service.name, status: service.status },
+                link_spec_name: linkSpec.name,
+                parameters_schema: linkCreate?.schema ?? null,
+                scopes: scopes.map((scope) => ({
+                    id: scope.id,
+                    name: scope.name,
+                    dimensions: scope.dimensions ?? {},
+                })),
+                target: target.label,
+                dashboard,
+            });
+        }
+        // ---- CREATE LINK ----
+        // Convergent: an existing link for this service on this target → reuse, never duplicate.
+        const existing = (await listLinks(context.np, target.nrn)).find((link) => link.service_id === service.id && link.status !== "failed");
+        let link;
+        if (existing) {
+            link = { id: existing.id, status: existing.status, service_id: service.id };
+        }
+        else {
+            link = await createLink(context.np, {
+                name: `lnk ${slug(service.name)}`,
+                service_id: service.id,
+                entity_nrn: target.nrn,
+                specification_id: linkSpec.id,
+                dimensions: target.dimensions,
+                // No create action → no agent will provision it, so it MUST be sent active or it sticks
+                // `pending` forever. With one, OMIT status and enqueue the create action below.
+                activateImmediately: !linkCreate,
+            });
+            if (linkCreate) {
+                // THE link action — POST /link/{id}/action with the link's own parameters (e.g. the
+                // database-user's permissions). Without it the link is `pending` with no credentials.
+                await createLinkAction(context.np, link.id, {
+                    name: `create-${slug(service.name)}-link`,
+                    specification_id: linkCreate.id,
+                    parameters: args.parameters ?? {},
+                });
+            }
+        }
+        await sleep(delays.appPoll);
+        link = await getLink(context.np, link.id).catch(() => link);
+        const headline = existing
+            ? translate("createLink.reused", { service: service.name, target: target.label, status: link.status })
+            : translate("createLink.linking", { service: service.name, target: target.label, status: link.status });
+        const md = `${headline}${next(translate("createLink.linkedHint"))}${linkLine(translate("md.dashboard"), dashboard)}`;
+        return reply(md, {
+            mode: "progress",
+            app: `#${app.id}`,
+            app_name: app.name,
+            service: { id: service.id, name: service.name },
+            link: { id: link.id, status: link.status, target: target.label },
+            reused: Boolean(existing),
+            dashboard,
+        });
+    },
+});

package/dist/tools/create-service.js

@@ -0,0 +1,149 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { dashboardLink, linkLine, next, table } from "../md.js";
+import { createServiceAction, getService, listAppServices, listDependencySpecs, provisionService, serviceCreateActionSpec, } from "../np/journey.js";
+import { defineTool, fail, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { appArg, delays, requireApp, sleep } from "./shared.js";
+const slug = (text) => text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+/** Specs whose name / category / sub-category contain EVERY token of the query (fuzzy "postgres",
+ *  "sql database", "redis"…). */
+function matchSpecs(specs, query) {
+    const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+    return specs.filter((spec) => {
+        const haystack = `${spec.name} ${spec.category ?? ""} ${spec.subCategory ?? ""}`.toLowerCase();
+        return tokens.every((token) => haystack.includes(token));
+    });
+}
+const specCategory = (spec) => [spec.category, spec.subCategory].filter(Boolean).join(" › ");
+/**
+ * Provision a dependency service (the service record + its create action). Linking it to an app or
+ * scope is a SEPARATE operation (`application_link_create`) — two distinct platform entities with
+ * distinct lifecycles, so two tools (the model provisions, then links).
+ */
+export const createServiceTool = defineTool({
+    name: TOOL.applicationServiceCreate,
+    title: "Provision service",
+    description: 'Provision a dependency service (SQL database, queue, cache, …) for an application. Pass `type` to choose the dependency (e.g. "postgres", "redis"). Provisioning creates real cloud resources (cost-bearing) and runs asynchronously, so call WITHOUT `provision:true` first to open the form; the user confirms by submitting it. Once it is active, LINK it to a scope with application_link_create so its connection details flow in as parameters.',
+    annotations: { destructiveHint: false, openWorldHint: true },
+    widget: "service-create",
+    errorKey: "createService.errorLabel",
+    inputSchema: {
+        app: appArg,
+        type: z
+            .string()
+            .optional()
+            .describe('Dependency to provision — matched against the catalog (e.g. "postgres", "redis", "queue")'),
+        specification_id: z
+            .string()
+            .optional()
+            .describe("Exact dependency spec id (the form submits this for a deterministic match; else use `type`)"),
+        name: z.string().optional().describe("Service name (default: the dependency type)"),
+        parameters: z
+            .record(z.unknown())
+            .optional()
+            .describe("Values for the create-action parameters (per the spec's schema shown in the form)"),
+        provision: z
+            .boolean()
+            .optional()
+            .describe("Set true to actually provision (creates cloud resources). Omit to return the form to fill."),
+    },
+    async handler(args, context) {
+        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 orgSlug = await context.org.organizationSlug();
+        const dashboard = dashboardLink(orgSlug, app.nrn);
+        // The provisionable catalog (core API — carries the action specs the write path needs).
+        const specs = await listDependencySpecs(context.np, app.nrn);
+        if (specs.length === 0) {
+            return fail(translate("createService.noSpecs", { app: app.name }) +
+                linkLine(translate("md.dashboard"), dashboard));
+        }
+        // Match the requested dependency: exact id (form submit) wins; else fuzzy `type`. None or
+        // ambiguous → return the catalog to pick from.
+        const direct = args.specification_id
+            ? specs.find((spec) => spec.id === args.specification_id)
+            : undefined;
+        const matches = direct ? [direct] : args.type ? matchSpecs(specs, args.type) : [];
+        if (matches.length !== 1) {
+            const list = matches.length > 1 ? matches : specs;
+            const heading = translate(matches.length > 1 ? "createService.matchAmbiguous" : "createService.pickSpec", {
+                app: app.name,
+                query: args.type ?? "",
+                count: specs.length,
+            });
+            const md = `${heading}\n\n${table([translate("header.name"), translate("createService.category"), translate("createService.provider")], list.map((spec) => [spec.name, specCategory(spec), spec.provider ?? ""]))}${next(translate("createService.pickHint"))}`;
+            return reply(md, { mode: "pick-spec", app: `#${app.id}`, app_name: app.name, specs: list, dashboard });
+        }
+        const spec = matches[0];
+        const createAction = await serviceCreateActionSpec(context.np, spec.id);
+        const name = (args.name ?? spec.name).trim();
+        // Form-first: no explicit provision OR a required create-action param still missing → show the
+        // form (the submit IS the cost confirmation — no silent money-spend).
+        const requiredKeys = createAction?.schema?.required ?? [];
+        const missing = requiredKeys.filter((key) => args.parameters?.[key] === undefined);
+        if (!args.provision || missing.length > 0) {
+            return reply(translate("createService.form", { spec: spec.name, app: app.name }) +
+                next(translate("createService.formHint")), {
+                mode: "form",
+                app: `#${app.id}`,
+                app_name: app.name,
+                spec: {
+                    id: spec.id,
+                    name: spec.name,
+                    category: specCategory(spec),
+                    provider: spec.provider ?? null,
+                },
+                parameters_schema: createAction?.schema ?? null,
+                name_default: name,
+                dashboard,
+            });
+        }
+        // ---- PROVISION (cost-bearing) ----
+        // Convergent under retries: a same-name dependency already on the app (not failed) → reuse it,
+        // never spin up a second one.
+        const existing = (await listAppServices(context.np, app.nrn)).find((service) => service.name.toLowerCase() === name.toLowerCase() && service.status !== "failed");
+        let service = existing
+            ? { id: existing.id, name: existing.name, status: existing.status }
+            : await provisionService(context.np, {
+                name,
+                specification_id: spec.id,
+                entity_nrn: app.nrn,
+                linkable_to: [app.nrn],
+            });
+        if (!existing && createAction) {
+            // THE create action — POST /service/{id}/action. Without it the service is `pending` forever
+            // (the external agent only processes the enqueued create action).
+            await createServiceAction(context.np, service.id, {
+                name: `create-${slug(name)}`,
+                specification_id: createAction.id,
+                parameters: args.parameters ?? {},
+            });
+        }
+        await sleep(delays.appPoll);
+        service = await getService(context.np, service.id).catch(() => service);
+        const headline = existing
+            ? translate("createService.reused", { name: service.name, status: service.status })
+            : translate("createService.provisioning", {
+                spec: spec.name,
+                name: service.name,
+                status: service.status,
+            });
+        const md = `${headline}${next(translate("createService.provisioningHint", { name: service.name }))}${linkLine(translate("md.dashboard"), dashboard)}`;
+        return reply(md, {
+            mode: "progress",
+            app: `#${app.id}`,
+            app_name: app.name,
+            service: { id: service.id, name: service.name, status: service.status, spec: spec.name },
+            reused: Boolean(existing),
+            dashboard,
+        });
+    },
+});

package/dist/tools/delete-flow.js

@@ -0,0 +1,30 @@
+import { translate } from "../i18n.js";
+import { linkLine, next } from "../md.js";
+import { reply } from "../tool.js";
+/**
+ * The destructive delete flow shared by `application_service_delete` and `application_link_delete`:
+ * confirm-first (nothing is destroyed without `confirm:true`, the widget's danger button sets it),
+ * then run the delete and report whether it finished or is deprovisioning. Delete is naturally
+ * idempotent — deleting an already-gone entity is reported, never an error.
+ */
+export async function deleteFlow(config, args) {
+    const base = {
+        entity: config.entity,
+        tool: config.tool,
+        app: config.appRef,
+        app_name: config.appName,
+        target: { id: config.entityId, name: config.entityName, status: config.entityStatus },
+        dashboard: config.dashboard,
+    };
+    // Confirm-first: a delete is destructive, so the submit IS the confirmation — no silent destroy.
+    if (!args.confirm) {
+        return reply(translate("deleteEntity.confirm", { name: config.entityName }) +
+            next(translate("deleteEntity.confirmHint")), { ...base, mode: "confirm" });
+    }
+    const { async } = await config.performDelete();
+    const headline = async
+        ? translate("deleteEntity.deprovisioning", { name: config.entityName })
+        : translate("deleteEntity.removed", { name: config.entityName });
+    const md = `${headline}${async ? next(translate("deleteEntity.deprovisioningHint")) : ""}${linkLine(translate("md.dashboard"), config.dashboard)}`;
+    return reply(md, { ...base, mode: "progress", removed: !async, deprovisioning: async });
+}

package/dist/tools/delete-link.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { dashboardLink, next, table } from "../md.js";
+import { createLinkAction, deleteLink, linkActionSpecs, listLinks } from "../np/journey.js";
+import { defineTool, fail, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { deleteFlow } from "./delete-flow.js";
+import { appArg, requireApp } from "./shared.js";
+const slug = (text) => text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+/**
+ * Delete a link (a service↔application connection). A link whose spec has a delete-action runs it so
+ * an agent deprovisions credentials (DB user, permissions) before the record is removed; a plain link
+ * (no delete-action) is removed directly. Deleting a link removes the parameters it exported — a
+ * redeploy applies that to the runtime.
+ */
+export const deleteLinkTool = defineTool({
+    name: TOOL.applicationLinkDelete,
+    title: "Delete link",
+    description: "Delete a link between a service and an application, removing the parameters it exported. Pass `link` to choose which one (by name); call WITHOUT `confirm:true` first to preview, the user confirms by submitting. A credential link deprovisions its database user before the record is removed; a redeploy applies the parameter removal to the runtime.",
+    annotations: { destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    widget: "service-delete",
+    errorKey: "deleteEntity.linkErrorLabel",
+    inputSchema: {
+        app: appArg,
+        link: z.string().optional().describe("Which link to delete, by name (or id)"),
+        confirm: z
+            .boolean()
+            .optional()
+            .describe("Set true to actually delete (the confirm button sets it). Omit to preview."),
+    },
+    async handler(args, context) {
+        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 orgSlug = await context.org.organizationSlug();
+        const dashboard = dashboardLink(orgSlug, app.nrn);
+        const links = await listLinks(context.np, app.nrn);
+        if (links.length === 0) {
+            return fail(translate("deleteEntity.noLinks", { app: app.name }));
+        }
+        const wanted = args.link?.toLowerCase();
+        const matched = wanted
+            ? links.filter((link) => link.name.toLowerCase().includes(wanted) || link.id === args.link)
+            : [];
+        if (matched.length !== 1) {
+            const list = matched.length > 1 ? matched : links;
+            const md = `${translate(matched.length > 1 ? "deleteEntity.linkAmbiguous" : "deleteEntity.pickLink", {
+                app: app.name,
+            })}\n\n${table([translate("header.name"), translate("header.status")], list.map((link) => [link.name, link.status]))}${next(translate("deleteEntity.pickLinkHint"))}`;
+            return reply(md, {
+                mode: "pick-target",
+                entity: "link",
+                tool: TOOL.applicationLinkDelete,
+                app: `#${app.id}`,
+                app_name: app.name,
+                targets: list,
+                dashboard,
+            });
+        }
+        const link = matched[0];
+        const config = {
+            tool: TOOL.applicationLinkDelete,
+            entity: "link",
+            appRef: `#${app.id}`,
+            appName: app.name,
+            entityId: link.id,
+            entityName: link.name,
+            entityStatus: link.status,
+            dashboard,
+            performDelete: async () => {
+                // A delete-action deprovisions (DB user, grants); without one, a direct DELETE removes it.
+                const deleteSpec = link.specification_id
+                    ? (await linkActionSpecs(context.np, link.specification_id)).find((spec) => spec.type === "delete")
+                    : undefined;
+                if (deleteSpec) {
+                    await createLinkAction(context.np, link.id, {
+                        name: `delete-${slug(link.name)}`,
+                        specification_id: deleteSpec.id,
+                        parameters: {},
+                    });
+                    return { async: true };
+                }
+                await deleteLink(context.np, link.id);
+                return { async: false };
+            },
+        };
+        return deleteFlow(config, args);
+    },
+});

package/dist/tools/delete-param.js

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { next } from "../md.js";
+import { deleteParameter, listParameters, listScopes } from "../np/journey.js";
+import { defineTool, errorMessage, fail, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { appArg, requireApp } from "./shared.js";
+/**
+ * Delete a configuration parameter (the whole definition and all its values). Link-injected
+ * parameters are `read_only` — they're removed by deleting the link, not here — so the tool refuses
+ * those and points at `application_link_delete`. The change applies on the next deploy.
+ */
+export const deleteParamTool = defineTool({
+    name: TOOL.applicationParameterDelete,
+    title: "Delete parameter",
+    description: "Delete an application configuration parameter (the whole variable and all its values). Pass `name`; call WITHOUT `confirm:true` first to preview, the user confirms by submitting. Read-only parameters injected by a service link can't be deleted here — delete the link instead. Applies on the next deploy.",
+    annotations: { destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    widget: "params",
+    errorKey: "deleteParam.errorLabel",
+    inputSchema: {
+        app: appArg,
+        name: z.string().describe("The parameter (variable) name to delete, e.g. MAX_PAGE_SIZE"),
+        confirm: z
+            .boolean()
+            .optional()
+            .describe("Set true to actually delete (the confirm button sets it). Omit to preview."),
+    },
+    async handler(args, context) {
+        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 nrn = app.nrn;
+        const scopes = await listScopes(context.np, app.id).catch(() => []);
+        const scopeData = scopes.map((scope) => ({
+            id: scope.id,
+            name: scope.name,
+            dimensions: scope.dimensions ?? {},
+        }));
+        const renderSet = async (extra) => {
+            const remaining = await listParameters(context.np, nrn).catch(() => undefined);
+            return {
+                app: `#${app.id}`,
+                app_name: app.name,
+                scopes: scopeData,
+                ...(remaining === undefined ? { available: false } : { available: true, params: remaining }),
+                ...extra,
+            };
+        };
+        const parameters = (await listParameters(context.np, nrn)) ?? [];
+        const target = parameters.find((param) => param.name.toLowerCase() === args.name.toLowerCase());
+        if (!target) {
+            // Idempotent: a name that isn't there (already deleted, or a typo) reports done, never errors.
+            return reply(translate("deleteParam.absent", { name: args.name, app: app.name }), await renderSet({ deleted: args.name, removed: true }));
+        }
+        if (target.read_only) {
+            return fail(translate("deleteParam.readOnly", { name: target.name }) +
+                next(translate("deleteParam.readOnlyHint")));
+        }
+        // Confirm-first: deleting a parameter is destructive, so the submit IS the confirmation.
+        if (!args.confirm) {
+            return reply(translate("deleteParam.confirm", { name: target.name, app: app.name }) +
+                next(translate("deleteParam.confirmHint")), await renderSet({ pending_delete: target.name }));
+        }
+        try {
+            await deleteParameter(context.np, target.id);
+        }
+        catch (caught) {
+            return fail(translate("deleteParam.failed", { name: target.name, message: errorMessage(caught) }));
+        }
+        return reply(translate("deleteParam.deleted", { name: target.name, app: app.name }) +
+            next(translate("deleteParam.deletedHint")), await renderSet({ deleted: target.name, removed: true }));
+    },
+});

package/dist/tools/delete-service.js

@@ -0,0 +1,108 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { dashboardLink, next, table } from "../md.js";
+import { createServiceAction, deleteService, listAppServices, listLinks, serviceActionSpecs, } from "../np/journey.js";
+import { defineTool, fail, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { deleteFlow } from "./delete-flow.js";
+import { appArg, requireApp } from "./shared.js";
+const slug = (text) => text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+/**
+ * Delete a provisioned service and destroy its resources. A `failed` service (no provisioned
+ * resources) deletes directly; an active one runs its delete-action so an agent deprovisions
+ * (DB, pods, …) before the record is removed. A service can't be deleted while it has links — the
+ * tool surfaces that rather than orphaning them.
+ */
+export const deleteServiceTool = defineTool({
+    name: TOOL.applicationServiceDelete,
+    title: "Delete service",
+    description: "Delete a provisioned service and destroy its cloud resources. Pass `service` to choose which one (by name); call WITHOUT `confirm:true` first to see what will be destroyed, the user confirms by submitting. A service with active links can't be deleted — remove the links first (application_link_delete).",
+    annotations: { destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    widget: "service-delete",
+    errorKey: "deleteEntity.serviceErrorLabel",
+    inputSchema: {
+        app: appArg,
+        service: z.string().optional().describe("Which provisioned service to delete, by name (or id)"),
+        confirm: z
+            .boolean()
+            .optional()
+            .describe("Set true to actually delete (the confirm button sets it). Omit to preview."),
+    },
+    async handler(args, context) {
+        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 orgSlug = await context.org.organizationSlug();
+        const dashboard = dashboardLink(orgSlug, app.nrn);
+        const services = await listAppServices(context.np, app.nrn);
+        if (services.length === 0) {
+            return fail(translate("deleteEntity.noServices", { app: app.name }));
+        }
+        const wanted = args.service?.toLowerCase();
+        const matched = wanted
+            ? services.filter((service) => service.name.toLowerCase().includes(wanted) || service.id === args.service)
+            : [];
+        if (matched.length !== 1) {
+            const list = matched.length > 1 ? matched : services;
+            const md = `${translate(matched.length > 1 ? "deleteEntity.serviceAmbiguous" : "deleteEntity.pickService", {
+                app: app.name,
+            })}\n\n${table([translate("header.name"), translate("header.status")], list.map((service) => [service.name, service.status]))}${next(translate("deleteEntity.pickServiceHint"))}`;
+            return reply(md, {
+                mode: "pick-target",
+                entity: "service",
+                tool: TOOL.applicationServiceDelete,
+                app: `#${app.id}`,
+                app_name: app.name,
+                targets: list,
+                dashboard,
+            });
+        }
+        const service = matched[0];
+        // A service can't be deleted while links depend on it — surface that instead of orphaning them.
+        if (args.confirm) {
+            const blockingLinks = (await listLinks(context.np, app.nrn)).filter((link) => link.service_id === service.id && link.status !== "failed");
+            if (blockingLinks.length > 0) {
+                return fail(translate("deleteEntity.hasLinks", { name: service.name, count: blockingLinks.length }) +
+                    next(translate("deleteEntity.hasLinksHint")));
+            }
+        }
+        const config = {
+            tool: TOOL.applicationServiceDelete,
+            entity: "service",
+            appRef: `#${app.id}`,
+            appName: app.name,
+            entityId: service.id,
+            entityName: service.name,
+            entityStatus: service.status,
+            dashboard,
+            performDelete: async () => {
+                // A failed service has no provisioned resources → direct DELETE (200), no deprovisioning.
+                if (service.status === "failed") {
+                    await deleteService(context.np, service.id);
+                    return { async: false };
+                }
+                // An active service deprovisions via its delete-action; without one, force-delete the record.
+                const deleteSpec = service.specification_id
+                    ? (await serviceActionSpecs(context.np, service.specification_id)).find((spec) => spec.type === "delete")
+                    : undefined;
+                if (deleteSpec) {
+                    await createServiceAction(context.np, service.id, {
+                        name: `delete-${slug(service.name)}`,
+                        specification_id: deleteSpec.id,
+                        parameters: {},
+                    });
+                    return { async: true };
+                }
+                await deleteService(context.np, service.id, true);
+                return { async: false };
+            },
+        };
+        return deleteFlow(config, args);
+    },
+});

package/dist/tools/deployments.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { translate } from "../i18n.js";
+import { plural, translate } from "../i18n.js";
 import { ago, glyph, next, table } from "../md.js";
 import { isDeploymentTerminal, listDeployments, listReleases, listScopes, } from "../np/journey.js";
 import { defineTool, reply } from "../tool.js";
@@ -60,7 +60,7 @@ export const deploymentsTool = defineTool({
             return children[0]?.status ?? "pending";
         };
         const markdown = [
-            translate("deploymentList.title", { app: app.name, count: rows.length }),
+            plural(rows.length, "deploymentList.title.one", "deploymentList.title.many", { app: app.name }),
             "",
             table([
                 translate("header.scope"),