@nullplatform/mcp 0.1.6 → 0.1.7

package/dist/np/journey.js

@@ -16,6 +16,17 @@ export function bumpSemver(semver) {
     const parts = /^(v?)(\d+)\.(\d+)\.(\d+)/.exec(semver ?? "");
     return parts ? `${parts[1]}${parts[2]}.${parts[3]}.${Number(parts[4]) + 1}` : "0.0.1";
 }
+function mapBuild(build) {
+    return {
+        id: build.id,
+        status: build.status,
+        branch: build.branch,
+        commit: String(build.commit?.id ?? build.commit_id ?? "") || undefined,
+        commit_url: build.commit?.permalink,
+        description: build.description ?? undefined,
+        created_at: build.created_at,
+    };
+}
 export async function listBuilds(np, applicationId, options = {}) {
     const query = {
         application_id: applicationId,
@@ -29,13 +40,13 @@ export async function listBuilds(np, applicationId, options = {}) {
     if (options.offset)
         query.offset = options.offset;
     const page = await np.get("/build", query).catch(() => ({ results: [] }));
-    return (page.results ?? []).map((build) => ({
-        id: build.id,
-        status: build.status,
-        branch: build.branch,
-        commit: String(build.commit?.id ?? build.commit_id ?? "") || undefined,
-        created_at: build.created_at,
-    }));
+    return (page.results ?? []).map(mapBuild);
+}
+/** A single build by id (GET /build/{id}) — titles a build's asset view with its real status,
+ *  commit and description even when reached directly (not drilled in from the list). */
+export async function getBuild(np, buildId) {
+    const raw = await np.get(`/build/${buildId}`).catch(() => null);
+    return raw ? mapBuild(raw) : null;
 }
 function mapRelease(raw) {
     return {
@@ -232,11 +243,43 @@ export async function deploymentAction(np, deploymentId, action) {
         status: action === "finalize" ? "finalizing" : "cancelling",
     });
 }
+/** The scope id encoded in a value's NRN (…:scope=<id>), or null for an application-level value. */
+function scopeIdFromNrn(nrn) {
+    const match = nrn?.match(/:scope=(\d+)/);
+    return match ? Number(match[1]) : null;
+}
+function mapParameter(raw) {
+    const secret = !!raw.secret;
+    return {
+        id: raw.id,
+        name: raw.name,
+        variable: raw.variable,
+        destination_path: raw.destination_path,
+        type: raw.type,
+        secret,
+        read_only: raw.read_only,
+        values: (raw.values ?? []).map((entry) => {
+            const dimensions = entry.dimensions && Object.keys(entry.dimensions).length ? entry.dimensions : null;
+            const scopeId = scopeIdFromNrn(entry.nrn);
+            return {
+                id: entry.id,
+                // a value row only exists where a value is set, so secrets become a fixed marker (never plaintext)
+                value: secret ? "•••" : entry.value,
+                nrn: entry.nrn,
+                scope_id: scopeId,
+                dimensions,
+                base: !scopeId && !dimensions,
+            };
+        }),
+    };
+}
 /**
- * Upsert parameters. Agents retry, and re-running "set DATABASE_URL" must not accrete a
- * duplicate definition — so reuse the existing definition (matched by variable/name at this
- * NRN) and just add a value; only POST a new definition when none exists. Reports how many
- * were created vs updated.
+ * Upsert parameters, optionally targeting a scope (pin `nrn`) or a dimension set (`dimensions`).
+ * Agents retry, and re-running "set DATABASE_URL" must not accrete a duplicate definition — so
+ * reuse the existing definition (matched by variable/name at this NRN) and just add a value; only
+ * POST a new definition when none exists. The value write is convergent on (nrn, dimensions,
+ * value) server-side, so a retried set is a no-op new version, never a duplicate. Reports how
+ * many definitions were created vs reused.
  */
 export async function setParameters(np, nrn, params) {
     const existing = (await listParameters(np, nrn)) ?? [];
@@ -261,28 +304,24 @@ export async function setParameters(np, nrn, params) {
             definitionId = definition.id;
             created++;
         }
-        await np.post(`/parameter/${definitionId}/values`, { values: [{ nrn, value: param.value }] });
+        const valueBody = { nrn: param.nrn ?? nrn, value: param.value };
+        if (param.dimensions && Object.keys(param.dimensions).length) {
+            valueBody.dimensions = param.dimensions;
+        }
+        await np.post(`/parameter/${definitionId}/values`, { values: [valueBody] });
     }
     return { created, updated };
 }
-/** Read parameters — NRN-scoped on the public API; returns undefined when unavailable. */
+/** Read parameters with their full value set — NRN-scoped on the public API. Pass an application
+ *  NRN to get EVERY value (all dimensions + scopes); pass a scope NRN and the platform collapses
+ *  each parameter to the single effective value for that scope. undefined when unavailable. */
 export async function listParameters(np, nrn, options = {}) {
     try {
         const query = { nrn, limit: options.limit ?? 100 };
         if (options.offset)
             query.offset = options.offset;
         const page = await np.get("/parameter", query);
-        return (page.results ?? []).map((parameter) => ({
-            id: parameter.id,
-            name: parameter.name,
-            variable: parameter.variable,
-            type: parameter.type,
-            secret: !!parameter.secret,
-            values: (parameter.values ?? []).map((entry) => ({
-                value: parameter.secret ? "•••" : entry.value,
-                nrn: entry.nrn,
-            })),
-        }));
+        return (page.results ?? []).map(mapParameter);
     }
     catch {
         return undefined;
@@ -436,3 +475,176 @@ export async function listServiceSpecifications(bff, nrn) {
         .catch(() => ({ results: [] }));
     return (page.results ?? []).map((spec) => ({ id: spec.id, name: spec.name ?? spec.id }));
 }
+// ---- service provisioning & linking (WRITES — core API, like scopes/deployments) ----
+//
+// Grounded against the public service-api OpenAPI (request/response SHAPE) and the platform team's
+// np-developer-actions skill (BEHAVIOUR — the working implementation of exactly this flow).
+//
+// Provisioning is TWO sequential POSTs: `POST /service` creates the record in `pending`, then
+// `POST /service/{id}/action` enqueues the "create" action an external agent processes to `active`
+// (without #2 the service is `pending` forever). Linking is one OR two POSTs depending on the LINK
+// spec's `use_default_actions` — the SQL landmine, encoded in `linkService` so `status` is derived,
+// never an input. Reads `.catch` to empty; writes throw so the tool surfaces the platform error.
+const TERMINAL_SERVICE = new Set(["active", "failed", "cancelled"]);
+export const isServiceTerminal = (status) => TERMINAL_SERVICE.has(status ?? "");
+/**
+ * Provisionable dependency specs at an entity NRN, read from the CORE API (not the BFF projection
+ * that `listServiceSpecifications` uses) so the write flow can reach the action specs and
+ * `use_default_actions` the dashboard list omits.
+ */
+export async function listDependencySpecs(np, nrn) {
+    const page = await np
+        .get("/service_specification", { nrn, type: "dependency", limit: 100 })
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map((spec) => ({
+        id: spec.id,
+        name: spec.name ?? spec.id,
+        category: spec.selectors?.category,
+        subCategory: spec.selectors?.sub_category,
+        provider: spec.selectors?.provider,
+    }));
+}
+const mapActionSpec = (spec) => ({
+    id: spec.id,
+    type: spec.type ?? "",
+    name: spec.name,
+    slug: spec.slug,
+    schema: spec.parameters?.schema,
+});
+/** Every action spec of a service spec (`create`/`update`/`delete`/`custom`), mapped. The caller
+ *  filters by `type` — `custom` for run-an-action, `delete` for deprovision, `create` for provision. */
+export async function serviceActionSpecs(np, serviceSpecId) {
+    const page = await np
+        .get(`/service_specification/${serviceSpecId}/action_specification`)
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map(mapActionSpec);
+}
+/** The "create" action spec drives provisioning; its `parameters.schema` is the input form. */
+export async function serviceCreateActionSpec(np, serviceSpecId) {
+    return (await serviceActionSpecs(np, serviceSpecId)).find((spec) => spec.type === "create");
+}
+/**
+ * `POST /service` — creates the record in `pending`. Never sends `status` (the backend sets it).
+ * Provisioning does NOT start until `createServiceAction` enqueues the create action.
+ */
+export async function provisionService(np, input) {
+    return np.post("/service", {
+        name: input.name,
+        specification_id: input.specification_id,
+        entity_nrn: input.entity_nrn,
+        linkable_to: input.linkable_to ?? [input.entity_nrn],
+        dimensions: input.dimensions ?? {},
+        selectors: { imported: false },
+    });
+}
+/** `POST /service/{id}/action` — enqueue an action (the create action provisions). */
+export async function createServiceAction(np, serviceId, action) {
+    return np.post(`/service/${serviceId}/action`, {
+        name: action.name,
+        specification_id: action.specification_id,
+        parameters: action.parameters ?? {},
+    });
+}
+export async function getService(np, serviceId) {
+    return np.get(`/service/${serviceId}`);
+}
+/** The link spec(s) that apply to a service spec — the OpenAPI maps them directly. Each carries
+ *  `use_default_actions`, which decides the linking flow (see `linkService`). */
+export async function linkSpecsForService(np, serviceSpecId) {
+    const page = await np
+        .get(`/service_specification/${serviceSpecId}/link_specification`)
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map((spec) => ({
+        id: spec.id,
+        name: spec.name ?? spec.id,
+        use_default_actions: spec.use_default_actions ?? false,
+    }));
+}
+/** Every action spec of a link spec — the caller filters by `type` (`custom`/`delete`/`create`). */
+export async function linkActionSpecs(np, linkSpecId) {
+    const page = await np
+        .get(`/link_specification/${linkSpecId}/action_specification`)
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map(mapActionSpec);
+}
+/** The create action spec of a LINK spec (only present when `use_default_actions` is true). */
+export async function linkCreateActionSpec(np, linkSpecId) {
+    return (await linkActionSpecs(np, linkSpecId)).find((spec) => spec.type === "create");
+}
+/** `POST /link`. `status` is the SQL landmine: it is DERIVED from the link spec's
+ *  `use_default_actions`, never passed in. Caller passes the resolved spec; this never takes a free
+ *  `status`. */
+export async function createLink(np, input) {
+    const body = {
+        name: input.name,
+        service_id: input.service_id,
+        entity_nrn: input.entity_nrn,
+        specification_id: input.specification_id,
+        dimensions: input.dimensions ?? {},
+    };
+    // use_default_actions=false → no agent exists, so `active` must be set or the link is stuck
+    // `pending` forever. use_default_actions=true → OMIT status; a follow-up create-action provisions
+    // credentials. Sending `active` there yields an active-but-credential-less, unrecoverable link.
+    if (input.activateImmediately)
+        body.status = "active";
+    return np.post("/link", body);
+}
+export async function createLinkAction(np, linkId, action) {
+    return np.post(`/link/${linkId}/action`, {
+        name: action.name,
+        specification_id: action.specification_id,
+        parameters: action.parameters ?? {},
+    });
+}
+export async function getLink(np, linkId) {
+    return np.get(`/link/${linkId}`);
+}
+/** Existing dependency services on an app (core API) — for convergence: a retried provision must
+ *  reuse a same-name service rather than spin up a second (cost-bearing) one. */
+export async function listAppServices(np, nrn) {
+    const page = await np
+        .get("/service", { nrn, type: "dependency", limit: 100 })
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map((service) => ({
+        id: service.id,
+        name: service.name ?? service.id,
+        status: service.status ?? "",
+        specification_id: service.specification_id,
+    }));
+}
+/** Existing links on an app (core API) — for convergence: a retried link must reuse an existing one
+ *  for the same service+target rather than create a duplicate; also feeds the link picker (name) and
+ *  the link-action / link-delete flows (specification_id → the link spec's action specs). */
+export async function listLinks(np, nrn) {
+    const page = await np.get("/link", { nrn }).catch(() => ({ results: [] }));
+    return (page.results ?? []).map((link) => ({
+        id: link.id,
+        name: link.name ?? link.id,
+        status: link.status ?? "",
+        service_id: link.service_id,
+        entity_nrn: link.entity_nrn,
+        specification_id: link.specification_id,
+    }));
+}
+/** Poll one action of a service — `pending` → `in_progress` → `success`|`failed`. */
+export async function getServiceAction(np, serviceId, actionId) {
+    return np.get(`/service/${serviceId}/action/${actionId}`);
+}
+/** Poll one action of a link. */
+export async function getLinkAction(np, linkId, actionId) {
+    return np.get(`/link/${linkId}/action/${actionId}`);
+}
+/** `DELETE /service/{id}`. A `failed` service (no provisioned resources) deletes directly; an active
+ *  one needs `force` OR a prior delete-action that deprovisions — the tool decides which path. */
+export async function deleteService(np, serviceId, force = false) {
+    await np.del(`/service/${serviceId}`, force ? { force: true } : undefined);
+}
+/** `DELETE /link/{id}`. `force` skips the deprovisioning delete-action (orphans credentials), so the
+ *  tool only forces when there's no delete-action to run; otherwise it runs the action first. */
+export async function deleteLink(np, linkId, force = false) {
+    await np.del(`/link/${linkId}`, force ? { force: true } : undefined);
+}
+/** `DELETE /parameter/{id}` — removes a whole parameter definition (and all its values). */
+export async function deleteParameter(np, parameterId) {
+    await np.del(`/parameter/${parameterId}`);
+}

package/dist/tool-names.js

@@ -21,6 +21,13 @@ export const TOOL = {
     applicationReleaseCreate: "application_release_create",
     applicationScopeCreate: "application_scope_create",
     applicationServiceList: "application_service_list",
+    applicationServiceCreate: "application_service_create",
+    applicationServiceUpdate: "application_service_update",
+    applicationServiceDelete: "application_service_delete",
+    applicationLinkCreate: "application_link_create",
+    applicationLinkUpdate: "application_link_update",
+    applicationLinkDelete: "application_link_delete",
+    applicationParameterDelete: "application_parameter_delete",
     applicationApprovalList: "application_approval_list",
     organizationGet: "organization_get",
     playbookGet: "playbook_get",

package/dist/tools/action-flow.js

@@ -0,0 +1,94 @@
+import { translate } from "../i18n.js";
+import { linkLine, next, table } from "../md.js";
+import { fail, reply } from "../tool.js";
+import { delays, sleep } from "./shared.js";
+const slug = (text) => text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+const actionLabel = (spec) => spec.name ?? spec.slug ?? spec.id;
+/**
+ * The run-a-custom-action flow shared by `application_service_update` and `application_link_update`:
+ * pick which action → fill its parameters (form-first; nothing runs without `run:true`) → POST the
+ * action → poll it once → report. A custom action is an explicit operation (it is NOT idempotent —
+ * running a DML twice runs it twice), so the safety here is the form gate, not convergence.
+ */
+export async function runActionFlow(config, args) {
+    const { entity, entityName, specs, dashboard } = config;
+    if (specs.length === 0) {
+        return fail(translate("runAction.noActions", { name: entityName }) + linkLine(translate("md.dashboard"), dashboard));
+    }
+    // Match the requested action by name/slug; none or ambiguous → list the runnable actions.
+    const wanted = args.action?.toLowerCase();
+    const matched = wanted
+        ? specs.filter((spec) => actionLabel(spec).toLowerCase().includes(wanted) ||
+            (spec.slug ?? "").toLowerCase() === wanted ||
+            spec.id === args.action)
+        : [];
+    if (matched.length !== 1) {
+        const list = matched.length > 1 ? matched : specs;
+        const heading = translate(matched.length > 1 ? "runAction.matchAmbiguous" : "runAction.pickAction", {
+            name: entityName,
+        });
+        const md = `${heading}\n\n${table([translate("header.name"), translate("runAction.paramsHeader")], list.map((spec) => [
+            actionLabel(spec),
+            (spec.schema?.required ?? []).join(", ") || "—",
+        ]))}${next(translate("runAction.pickHint"))}`;
+        return reply(md, {
+            mode: "pick-action",
+            entity,
+            tool: config.tool,
+            app: config.appRef,
+            app_name: config.appName,
+            target: { id: config.entityId, name: entityName, status: config.entityStatus },
+            actions: list.map((spec) => ({ id: spec.id, name: actionLabel(spec), slug: spec.slug })),
+            dashboard,
+        });
+    }
+    const spec = matched[0];
+    // Form-first: no explicit run OR a required parameter still missing → return the form.
+    const requiredKeys = spec.schema?.required ?? [];
+    const missing = requiredKeys.filter((key) => args.parameters?.[key] === undefined);
+    if (!args.run || missing.length > 0) {
+        return reply(translate("runAction.form", { action: actionLabel(spec), name: entityName }) +
+            next(translate("runAction.formHint")), {
+            mode: "form",
+            entity,
+            tool: config.tool,
+            app: config.appRef,
+            app_name: config.appName,
+            target: { id: config.entityId, name: entityName, status: config.entityStatus },
+            action: { id: spec.id, name: actionLabel(spec), slug: spec.slug },
+            parameters_schema: spec.schema ?? null,
+            dashboard,
+        });
+    }
+    // ---- RUN THE ACTION ----
+    const fired = await config.run({
+        name: spec.slug ?? slug(actionLabel(spec)),
+        specification_id: spec.id,
+        parameters: args.parameters ?? {},
+    });
+    await sleep(delays.appPoll);
+    const action = await config
+        .poll(fired.id)
+        .catch(() => ({ id: fired.id, status: fired.status ?? "pending" }));
+    const md = `${translate("runAction.running", { action: actionLabel(spec), name: entityName, status: action.status })}` +
+        next(translate("runAction.ranHint")) +
+        linkLine(translate("md.dashboard"), dashboard);
+    return reply(md, {
+        mode: "progress",
+        entity,
+        tool: config.tool,
+        app: config.appRef,
+        app_name: config.appName,
+        target: { id: config.entityId, name: entityName, status: config.entityStatus },
+        action: {
+            id: action.id,
+            name: actionLabel(spec),
+            status: action.status,
+            results: action.results ?? null,
+        },
+        dashboard,
+    });
+}

package/dist/tools/approvals.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { translate } from "../i18n.js";
+import { plural, 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";
@@ -52,7 +52,7 @@ export const approvalsTool = defineTool({
             return reply(translate("approvals.none", { app: app.name }), { app: `#${app.id}`, approvals: [] });
         }
         const markdown = [
-            translate("approvals.title", { app: app.name, count: approvals.length }),
+            plural(approvals.length, "approvals.title.one", "approvals.title.many", { app: app.name }),
             "",
             table([
                 translate("header.id"),

package/dist/tools/builds.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { translate } from "../i18n.js";
+import { plural, translate } from "../i18n.js";
 import { ago, glyph, next, shortCommit, table } from "../md.js";
-import { listAssets, listBuilds, listReleases } from "../np/journey.js";
+import { getBuild, listAssets, listBuilds, listReleases } from "../np/journey.js";
 import { defineTool, reply } from "../tool.js";
 import { TOOL } from "../tool-names.js";
 import { appArg, offsetArg, pageOf, requireApp } from "./shared.js";
@@ -33,10 +33,17 @@ export const buildsTool = defineTool({
             return resolved.out;
         const app = resolved.app;
         if (args.build) {
-            const assets = await listAssets(context.np, args.build);
+            // Fetch the build alongside its assets so the asset view shows the real status/commit and
+            // a no-assets message that fits the build's state (running vs failed vs simply none).
+            const [build, assets] = await Promise.all([
+                getBuild(context.np, args.build),
+                listAssets(context.np, args.build),
+            ]);
+            const buildData = build ?? { id: args.build, status: "" };
             if (assets.length === 0) {
-                return reply(translate("builds.noAssets", { build: args.build }), {
+                return reply(noAssetsText(build?.status, args.build), {
                     build_id: args.build,
+                    build: buildData,
                     assets: [],
                 });
             }
@@ -46,7 +53,7 @@ export const buildsTool = defineTool({
                 table([translate("header.asset"), translate("header.type"), translate("header.platform")], assets.map((asset) => [asset.name, asset.type, asset.platform ?? ""])),
                 next(translate("builds.deployHint", { build: args.build })),
             ].join("\n");
-            return reply(markdown, { build_id: args.build, assets });
+            return reply(markdown, { build_id: args.build, build: buildData, assets });
         }
         const [builds, releases] = await Promise.all([
             listBuilds(context.np, app.id, { limit: args.limit ?? 10, commit: args.commit, offset: args.offset }),
@@ -61,7 +68,7 @@ export const buildsTool = defineTool({
         const releasedBuildIds = new Set(releases.map((release) => release.build_id).filter(Boolean));
         const releaseByBuild = new Map(releases.map((release) => [release.build_id, release]));
         const markdown = [
-            translate("builds.title", { app: app.name, count: builds.length }),
+            plural(builds.length, "builds.title.one", "builds.title.many", { app: app.name }),
             "",
             table([
                 translate("header.id"),
@@ -92,6 +99,16 @@ export const buildsTool = defineTool({
         });
     },
 });
+/** No-assets message keyed to the build's state — "may still be running" only fits a build that
+ *  actually still is; a failed or finished one needs the truth. */
+function noAssetsText(status, build) {
+    if (status === "pending" || status === "in_progress") {
+        return translate("builds.noAssetsRunning", { build });
+    }
+    if (status === "failed")
+        return translate("builds.noAssetsFailed", { build });
+    return translate("builds.noAssets", { build });
+}
 function buildsHint(builds, releasedBuildIds) {
     const newestSuccessful = builds.find((build) => build.status === "successful");
     if (newestSuccessful && !releasedBuildIds.has(newestSuccessful.id)) {

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,
+        });
+    },
+});