@nullplatform/mcp 0.1.13 → 0.1.15

package/dist/tools/create-app.js

@@ -4,24 +4,24 @@ import { dashboardLink, glyph, linkLine, next } from "../md.js";
 import { createApplication, getApplication, listTemplates } from "../np/journey.js";
 import { defineTool, fail, reply } from "../tool.js";
 import { TOOL } from "../tool-names.js";
-import { delays, httpsRepoUrl, sleep } from "./shared.js";
-function pickNamespace(namespaces, hints) {
+import { delays, httpsRepoUrl, resolveChoice, sleep } from "./shared.js";
+export function pickNamespace(namespaces, hints) {
+    // Namespace is the generic resolveChoice with one extra twist — account narrowing. An explicit id is
+    // unambiguous, so honour it against the FULL list FIRST (the account filter only disambiguates a
+    // repeated NAME; it must never veto a real id). Then resolve the name within the named account, and
+    // fall back to all namespaces so a correct name still pins even when the account label doesn't line up.
+    const byId = resolveChoice(namespaces, { id: hints.namespace_id });
+    if (byId)
+        return byId;
     const accountQuery = hints.account?.toLowerCase();
-    const narrowed = accountQuery
+    const inAccount = accountQuery
         ? namespaces.filter((candidate) => (candidate.account_name ?? "").toLowerCase().includes(accountQuery))
         : namespaces;
-    const candidates = narrowed.length ? narrowed : namespaces;
-    if (hints.namespace_id) {
-        const byId = candidates.find((candidate) => candidate.id === hints.namespace_id);
-        if (byId)
-            return byId;
-    }
-    if (hints.namespace) {
-        const query = hints.namespace.toLowerCase();
-        const matches = candidates.filter((candidate) => candidate.name.toLowerCase().includes(query));
-        if (matches.length === 1)
-            return matches[0];
-    }
+    const named = resolveChoice(inAccount.length ? inAccount : namespaces, { text: hints.namespace }) ??
+        resolveChoice(namespaces, { text: hints.namespace });
+    if (named)
+        return named;
+    const candidates = inAccount.length ? inAccount : namespaces;
     if (candidates.length === 1)
         return candidates[0];
     return undefined;
@@ -41,11 +41,12 @@ async function buildFormReply(context, prefill) {
     // of the global set. Fetch only once a namespace is pinned (the widget refetches per namespace on
     // change); the org-level NRN returns a misleading near-empty subset.
     const templates = picked ? await listTemplates(context.np, picked.nrn).catch(() => []) : [];
-    // Same contract for the template: honour a passed id, pin the only one, else leave it unselected —
-    // never silently scaffold the first stack in the list (a wrong stack is worse than a deliberate pick).
-    const templateId = (prefill.template_id && templates.some((template) => template.id === prefill.template_id)
-        ? prefill.template_id
-        : null) ?? (templates.length === 1 ? (templates[0]?.id ?? null) : null);
+    // Same generic rule as the namespace: resolve the MODEL's stack hint (`template`) — or an explicit
+    // template_id — against THIS namespace's templates, matching on name + tags, and pin the only one.
+    // Inference is the model's job (it holds the context); the tool only resolves the hint it passes —
+    // no keyword guessing here. Leave it null on a genuine unhinted/ambiguous choice (a wrong stack is
+    // worse than a deliberate pick).
+    const templateId = resolveChoice(templates, { id: prefill.template_id, text: prefill.template }, { pinOnly: true, haystack: (template) => `${template.name} ${(template.tags ?? []).join(" ")}` })?.id ?? null;
     const namespaces = skeleton.namespaces.map((namespace) => ({
         id: namespace.id,
         name: namespace.name,
@@ -56,6 +57,9 @@ async function buildFormReply(context, prefill) {
         namespaces: namespaces.map((namespace) => namespace.name).join(", ") || "—",
     }), {
         mode: "form",
+        // Model-facing note (not rendered to the user): the form is already open with every template
+        // loaded in its dropdown, so the model must NOT re-call to "pre-select" a template it just saw.
+        note: "This create FORM is now OPEN with all of this namespace's templates loaded in its Template dropdown. Do NOT call application_create again to pre-select a template or refine the namespace you just learned about — re-opening renders a DUPLICATE form panel for the same app (the mistake to avoid). To steer the choice: either name the recommended template in your text reply for the user to pick in this form's dropdown, OR (better, next time) pass a `template` stack hint on the FIRST call so it pre-selects in one render. The user picks/confirms in THIS form.",
         namespaces,
         templates: templates.map((template) => ({
             id: template.id,
@@ -72,10 +76,109 @@ async function buildFormReply(context, prefill) {
         },
     });
 }
+/**
+ * Resolve where a new app lives — the (account, namespace) pair — from the create args. Mirrors
+ * requireApp's shape: returns the pinned namespace, or an `out` reply — a `fail` when a named
+ * account/namespace matches nothing, or the create FORM when it's a real choice that needs the
+ * picker rather than a dead-end ask. Narrows to the named account first (a namespace name can
+ * repeat across accounts), then matches by id/name and auto-picks the sole candidate.
+ */
+async function resolveCreateNamespace(context, args, name, repoUrl) {
+    const skeleton = await context.org.getSkeleton();
+    const accountQuery = args.account?.toLowerCase();
+    const candidates = accountQuery
+        ? skeleton.namespaces.filter((candidate) => (candidate.account_name ?? "").toLowerCase().includes(accountQuery))
+        : skeleton.namespaces;
+    if (accountQuery && candidates.length === 0) {
+        const accounts = [
+            ...new Set(skeleton.namespaces.map((candidate) => candidate.account_name).filter(Boolean)),
+        ];
+        return {
+            out: fail(translate("createApp.noAccountMatch", { account: args.account ?? "", names: accounts.join(", ") })),
+        };
+    }
+    let namespace = args.namespace_id
+        ? candidates.find((candidate) => candidate.id === args.namespace_id)
+        : undefined;
+    if (!namespace && args.namespace) {
+        const query = args.namespace.toLowerCase();
+        const matches = candidates.filter((candidate) => candidate.name.toLowerCase().includes(query));
+        if (matches.length === 1)
+            namespace = matches[0];
+        else if (matches.length === 0) {
+            return {
+                out: fail(translate("createApp.noNamespaceMatch", {
+                    namespace: args.namespace,
+                    names: candidates.map((candidate) => candidate.name).join(", "),
+                })),
+            };
+        }
+    }
+    // One namespace in scope (the whole org, or the chosen account) → auto-pick it.
+    if (!namespace && candidates.length === 1)
+        namespace = candidates[0];
+    if (!namespace) {
+        if (skeleton.namespaces.length === 0)
+            return { out: fail(translate("createApp.noNamespaces")) };
+        return {
+            out: await buildFormReply(context, {
+                name,
+                account: args.account,
+                namespace: args.namespace,
+                template: args.template,
+                template_id: args.template_id,
+                repository_url: repoUrl,
+            }),
+        };
+    }
+    return { namespace };
+}
+/** The convergent "this repo is already an app" reply — shared by the pre-create check and the
+ *  create-conflict recovery (a retried create that hit "already exists"), so both read identically. */
+async function reusedAppReply(context, app, repoUrl) {
+    const orgSlug = await context.org.organizationSlug();
+    return reply(translate("createApp.alreadyLinked", { name: app.name, id: app.id, repo: repoUrl }) +
+        next(translate("createApp.createdHint")) +
+        linkLine(translate("md.dashboard"), dashboardLink(orgSlug, app.nrn)), {
+        application: { id: app.id, name: app.name, status: app.status, nrn: app.nrn },
+        reused: true,
+    });
+}
+/** Poll a freshly-created app briefly (pending → active), then build its reply — ready vs still-
+ *  provisioning, with the next-step hint (a scaffolded NEW repo must be cloned before building). */
+async function provisioningReply(context, created, details) {
+    let app = created;
+    for (let attempt = 0; attempt < 8 && app.status === "pending"; attempt++) {
+        await sleep(delays.appPoll);
+        app = await getApplication(context.np, created.id).catch(() => app);
+    }
+    const orgSlug = await context.org.organizationSlug();
+    const dashboard = linkLine(translate("md.dashboard"), dashboardLink(orgSlug, app.nrn));
+    const recentMessages = (app.messages ?? [])
+        .slice(-3)
+        .map((entry) => `- ${entry.message ?? JSON.stringify(entry)}`)
+        .join("\n");
+    const structured = {
+        application: { id: app.id, name: details.name, status: app.status, nrn: app.nrn },
+        scaffolded: details.scaffolded,
+        repository_url: details.repoUrl,
+    };
+    const createdHint = details.scaffolded
+        ? translate("createApp.createdHintNew", { repo: details.repoUrl })
+        : translate("createApp.createdHint");
+    if (app.status === "active") {
+        return reply(`${glyph("active")} ${translate("createApp.created", { name: details.name, id: app.id, namespace: details.namespaceName, repo: details.repoUrl })}${recentMessages ? `\n${recentMessages}` : ""}` +
+            next(createdHint) +
+            dashboard, structured);
+    }
+    return reply(`${translate("createApp.pending", { name: details.name, id: app.id, status: app.status })}${recentMessages ? `\n${recentMessages}` : ""}` +
+        next(translate("createApp.pendingHint", { id: app.id })) +
+        dashboard, structured);
+}
 export const createAppTool = defineTool({
     name: TOOL.applicationCreate,
     title: "Create application",
-    description: "Create a nullplatform application. INFER the best-fitting namespace and account from what the app is FOR (a demo → a demos/examples namespace, a backend service → a services namespace) and pass them as `namespace`/`account` so the form opens pre-selected on your inference — the user can still change it. Calling with NO repository_url opens an interactive form and creates nothing — the user confirms the namespace, then either a NEW repository (scaffolded from a template, repo URL auto-generated) or IMPORTS an existing repository (optionally a monorepo folder), and the form calls back with a repository_url to actually create. Only an explicit repository_url performs the create, so opening the form never writes anything. Provisioning is async — the create waits briefly and reports progress.",
+    description: 'Create a nullplatform application. THIS IS THE ONE AND ONLY WAY to create/scaffold/set-up/bootstrap a new app, and it is the PLATFORM\'s job: nullplatform itself creates the git repository (on whatever provider the account is configured for — GitHub, GitLab, Bitbucket, …) from a template and provisions it. So for ANY "create / scaffold / set up / build a new app" request, route it HERE — do NOT brainstorm or design the app first, do NOT run an implementation process, do NOT `git init` or write files locally, and do NOT offer a "scaffold locally first" choice or ask "where should it live / how do we deploy": there is no local path, so that is not a real question. Infer the stack and pass it as `template` ON THE FIRST CALL — a SEMANTIC word ("frontend", "react", "go", "python", "api") is enough; the tool resolves it to the namespace\'s real templates and pre-selects the best fit, so do NOT open the form with the template blank and then recommend one in text. Never ask an open "what stack / what scope" brainstorm question. GATE FIRST: if the request is bare and gives you NOTHING to infer from (e.g. just "create an app" / "create a new application" with no hint of what it\'s for or what to name it), DO NOT call this tool yet — first ask the user, in chat, what the app is for AND what to name it, and WAIT for both; call this only once you have the purpose (to pre-fill the namespace) AND the name in hand. Do NOT call it in the meantime, while still waiting on the name — opening a blank or half-filled form and continuing to ask is a failure, not a fallback. When you DO have context, INFER the best-fitting namespace and account from what the app is FOR (a demo → a demos/examples namespace, a backend service → a services namespace) and pass them as `namespace`/`account` so the form opens pre-selected on your inference — the user can still change it. Calling without `provision:true` opens an interactive form and creates nothing — the user confirms the namespace, then either a NEW repository (scaffolded from a template, repo URL auto-generated) or IMPORTS an existing repository (optionally a monorepo folder), and the form itself submits with provision:true to actually create. Only the form\'s submit sets provision:true; you (the model) NEVER set it and NEVER pass a repository_url to "pre-fill" expecting a create — passing a repository_url without provision just opens the form, it does NOT write anything. Provisioning is async — the create waits briefly and reports progress.',
     annotations: { destructiveHint: false, openWorldHint: true },
     widget: "create-app",
     errorKey: "createApp.errorLabel",
@@ -94,6 +197,10 @@ export const createAppTool = defineTool({
             .string()
             .optional()
             .describe("Full git repo URL. New repos: auto-generated from the account + name. Import: the existing URL."),
+        template: z
+            .string()
+            .optional()
+            .describe('Stack to scaffold from — ALWAYS pass this on the first call so the form opens with the template ALREADY selected; never open the form with this blank and then recommend a template in text. Two ways to fill it: (1) if a single SEMANTIC word uniquely identifies the stack from the app\'s purpose/name (a Python service → "python", a Go API → "go"), pass that word — the tool matches it to the namespace\'s real templates by name + tags. (2) if a semantic word would be AMBIGUOUS — several templates could match (e.g. multiple frontend kits), or you want the BEST fit for the use case (a bank demo → a bank-themed frontend kit) — you MUST first LIST the templates headlessly with `entity_list entity:"template" parent_type:"namespace" parent_id:<namespace_id>` (NO panel), pick the SPECIFIC one, and pass its name here. Do the entity_list BEFORE opening this form. (prefer template_id only when you already know the exact id.)'),
         template_id: z
             .number()
             .optional()
@@ -102,44 +209,34 @@ export const createAppTool = defineTool({
             .string()
             .optional()
             .describe("Import only: the folder inside a monorepo that holds this application"),
+        provision: z
+            .boolean()
+            .optional()
+            .describe("Set true ONLY to actually create the app + repository — this is the form's Create button. Omit it to open/pre-fill the form, even when you pass a repository_url: opening or pre-filling NEVER creates anything. You (the model) must NOT set this; the user confirms by submitting the form."),
     },
     async handler(args, context) {
-        // Create ONLY on an explicit repository_url (the form's Create button, or a deliberate
-        // call). With none, return the form and create nothing. create_app does NOT read the
-        // ambient git remote: opening the form, switching namespace, or running the MCP inside some
-        // repo must never auto-create an app behind the user's back (the bug where "let's create an
-        // app" silently created the MCP's own repo). The user chooses the repository in the form.
+        // Create ONLY on an explicit provision:true (the form's Create button). The presence of a
+        // repository_url is NOT the trigger: the model routinely passes one to PRE-FILL the form, and
+        // treating that as "create now" silently provisioned an app the user never confirmed (the bug
+        // where the panel jumped straight to "Creating…"). So opening or pre-filling the form — with or
+        // without a repository_url — creates nothing; the user submits to create. create_app also does
+        // NOT read the ambient git remote, so running the MCP inside some repo never auto-creates either.
         const repoUrl = args.repository_url ? httpsRepoUrl(args.repository_url) : undefined;
-        if (!repoUrl) {
+        if (!args.provision || !repoUrl) {
             return buildFormReply(context, {
                 name: args.name,
                 account: args.account,
                 namespace: args.namespace,
                 namespace_id: args.namespace_id,
+                template: args.template,
                 template_id: args.template_id,
-                repository_url: null,
+                repository_url: args.repository_url ?? null,
             });
         }
         // Convergent under retries: a repo already linked to an app returns that app, never a duplicate.
         const alreadyLinked = await context.org.inferAppFromRepo(repoUrl);
-        if (alreadyLinked) {
-            const orgSlug = await context.org.organizationSlug();
-            return reply(translate("createApp.alreadyLinked", {
-                name: alreadyLinked.name,
-                id: alreadyLinked.id,
-                repo: repoUrl,
-            }) +
-                next(translate("createApp.createdHint")) +
-                linkLine(translate("md.dashboard"), dashboardLink(orgSlug, alreadyLinked.nrn)), {
-                application: {
-                    id: alreadyLinked.id,
-                    name: alreadyLinked.name,
-                    status: alreadyLinked.status,
-                    nrn: alreadyLinked.nrn,
-                },
-                reused: true,
-            });
-        }
+        if (alreadyLinked)
+            return reusedAppReply(context, alreadyLinked, repoUrl);
         const name = args.name ??
             repoUrl
                 .split("/")
@@ -147,49 +244,12 @@ export const createAppTool = defineTool({
                 ?.replace(/\.git$/, "");
         if (!name)
             return fail(translate("createApp.noName", { url: repoUrl }));
-        // Resolve where the app lives — an (account, namespace) pair. Narrow to the named account first
-        // (a namespace name can repeat across accounts), then match/auto-pick the namespace inside it.
-        // If it still can't be pinned down and there's a real choice, fall back to the form (a picker)
-        // rather than a dead-end ask.
-        const skeleton = await context.org.getSkeleton();
-        const accountQuery = args.account?.toLowerCase();
-        const candidates = accountQuery
-            ? skeleton.namespaces.filter((candidate) => (candidate.account_name ?? "").toLowerCase().includes(accountQuery))
-            : skeleton.namespaces;
-        if (accountQuery && candidates.length === 0) {
-            const accounts = [
-                ...new Set(skeleton.namespaces.map((candidate) => candidate.account_name).filter(Boolean)),
-            ];
-            return fail(translate("createApp.noAccountMatch", { account: args.account ?? "", names: accounts.join(", ") }));
-        }
-        let namespace = args.namespace_id
-            ? candidates.find((candidate) => candidate.id === args.namespace_id)
-            : undefined;
-        if (!namespace && args.namespace) {
-            const query = args.namespace.toLowerCase();
-            const matches = candidates.filter((candidate) => candidate.name.toLowerCase().includes(query));
-            if (matches.length === 1)
-                namespace = matches[0];
-            else if (matches.length === 0) {
-                return fail(translate("createApp.noNamespaceMatch", {
-                    namespace: args.namespace,
-                    names: candidates.map((candidate) => candidate.name).join(", "),
-                }));
-            }
-        }
-        // One namespace in scope (the whole org, or the chosen account) → auto-pick it.
-        if (!namespace && candidates.length === 1)
-            namespace = candidates[0];
-        if (!namespace) {
-            if (skeleton.namespaces.length === 0)
-                return fail(translate("createApp.noNamespaces"));
-            return buildFormReply(context, {
-                name,
-                account: args.account,
-                namespace: args.namespace,
-                repository_url: repoUrl,
-            });
-        }
+        // Resolve where the app lives — an (account, namespace) pair. Returns the pinned namespace, or
+        // an `out` reply (a fail on no match, or the form picker when it's a real choice) — see the helper.
+        const resolvedNamespace = await resolveCreateNamespace(context, args, name, repoUrl);
+        if ("out" in resolvedNamespace)
+            return resolvedNamespace.out;
+        const namespace = resolvedNamespace.namespace;
         let created;
         try {
             created = await createApplication(context.np, {
@@ -210,50 +270,16 @@ export const createAppTool = defineTool({
                 (await context.org.findApps({ query: name, namespace: namespace.name }).catch(() => [])).find((candidate) => candidate.name.toLowerCase() === name.toLowerCase() && candidate.namespace_id === namespace.id);
             if (!existing)
                 throw caught;
-            const orgSlug = await context.org.organizationSlug();
-            return reply(translate("createApp.alreadyLinked", { name: existing.name, id: existing.id, repo: repoUrl }) +
-                next(translate("createApp.createdHint")) +
-                linkLine(translate("md.dashboard"), dashboardLink(orgSlug, existing.nrn)), {
-                application: {
-                    id: existing.id,
-                    name: existing.name,
-                    status: existing.status,
-                    nrn: existing.nrn,
-                },
-                reused: true,
-            });
-        }
-        // Provisioning is async (pending -> active); wait briefly so the common case answers "ready".
-        let app = created;
-        for (let attempt = 0; attempt < 8 && app.status === "pending"; attempt++) {
-            await sleep(delays.appPoll);
-            app = await getApplication(context.np, created.id).catch(() => app);
+            return reusedAppReply(context, existing, repoUrl);
         }
-        const orgSlug = await context.org.organizationSlug();
-        const dashboard = linkLine(translate("md.dashboard"), dashboardLink(orgSlug, app.nrn));
-        const recentMessages = (app.messages ?? [])
-            .slice(-3)
-            .map((entry) => `- ${entry.message ?? JSON.stringify(entry)}`)
-            .join("\n");
         // A new repo scaffolded from a template is a fresh REMOTE repo the developer has never cloned —
-        // the next move is to pull it into a folder and build there. An import is already local, so its
-        // next move is just to push. The two paths get different guidance.
-        const scaffolded = args.template_id !== undefined;
-        const structured = {
-            application: { id: app.id, name, status: app.status, nrn: app.nrn },
-            scaffolded,
-            repository_url: repoUrl,
-        };
-        const createdHint = scaffolded
-            ? translate("createApp.createdHintNew", { repo: repoUrl })
-            : translate("createApp.createdHint");
-        if (app.status === "active") {
-            return reply(`${glyph("active")} ${translate("createApp.created", { name, id: app.id, namespace: namespace.name, repo: repoUrl })}${recentMessages ? `\n${recentMessages}` : ""}` +
-                next(createdHint) +
-                dashboard, structured);
-        }
-        return reply(`${translate("createApp.pending", { name, id: app.id, status: app.status })}${recentMessages ? `\n${recentMessages}` : ""}` +
-            next(translate("createApp.pendingHint", { id: app.id })) +
-            dashboard, structured);
+        // its next move is to clone-then-build; an import is already local, so it just pushes. The two
+        // paths get different guidance (carried by `scaffolded`). Poll briefly so the common case is ready.
+        return provisioningReply(context, created, {
+            name,
+            namespaceName: namespace.name,
+            repoUrl,
+            scaffolded: args.template_id !== undefined,
+        });
     },
 });

package/dist/tools/create-link.js

@@ -9,6 +9,71 @@ const slug = (text) => text
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-+|-+$/g, "");
+/**
+ * Pick which provisioned service to link from the `service` hint. Mirrors requireApp's shape:
+ * returns the single matched service, or an `out` reply — a `fail` when the app has no linkable
+ * services, or the pick-service panel when the hint is missing/ambiguous (zero or many matches).
+ */
+async function resolveLinkService(context, app, serviceHint, dashboard) {
+    const services = (await listAppServices(context.np, app.nrn)).filter((service) => service.status !== "failed");
+    if (services.length === 0) {
+        return {
+            out: fail(translate("createLink.noServices", { app: app.name }) + next(translate("createLink.noServicesHint"))),
+        };
+    }
+    const wanted = serviceHint?.toLowerCase();
+    const matched = wanted
+        ? services.filter((service) => service.name.toLowerCase().includes(wanted) || service.id === serviceHint)
+        : [];
+    if (matched.length === 1)
+        return { service: matched[0] };
+    // Zero or many matches → let the user pick (the panel lists the candidates, or all services).
+    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 {
+        out: reply(md, {
+            mode: "pick-service",
+            app: `#${app.id}`,
+            app_name: app.name,
+            services: list,
+            dashboard,
+        }),
+    };
+}
+/**
+ * Create the link, or reuse an existing non-failed one on the same target (convergent under
+ * retries). A credential link (linkCreate present) is created WITHOUT activate-now and then has its
+ * create-action enqueued — the agent provisions it; a plain link activates immediately on creation.
+ */
+async function createOrReuseLink(context, input) {
+    const { service, target, linkSpec, linkCreate } = input;
+    const existing = (await listLinks(context.np, target.nrn)).find((link) => link.service_id === service.id && link.status !== "failed");
+    if (existing) {
+        return { link: { id: existing.id, status: existing.status, service_id: service.id }, reused: true };
+    }
+    const 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.
+        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: input.parameters ?? {},
+        });
+    }
+    return { link, reused: false };
+}
 /**
  * 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
@@ -20,7 +85,7 @@ const slug = (text) => text
 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.",
+    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. Use it for "connect/link the database to <app/scope>", "wire up the queue". Pass `service` (by name) and optionally a `scope` (default: the whole app). 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. New parameters reach the runtime on the NEXT deploy. Provision the service first with application_service_create.',
     annotations: { destructiveHint: false, openWorldHint: true },
     widget: "service-link",
     errorKey: "createLink.errorLabel",
@@ -52,29 +117,11 @@ export const createLinkTool = defineTool({
             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 app's provisioned services — pick which one to link (or surface the picker / no-services fail).
+        const resolvedService = await resolveLinkService(context, { id: app.id, name: app.name, nrn: app.nrn }, args.service, dashboard);
+        if ("out" in resolvedService)
+            return resolvedService.out;
+        const service = resolvedService.service;
         // 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
@@ -116,37 +163,17 @@ export const createLinkTool = defineTool({
                 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 ?? {},
-                });
-            }
-        }
+        // Create the link (or reuse a non-failed one on this target — convergent under retries).
+        const { link: linked, reused } = await createOrReuseLink(context, {
+            service,
+            target,
+            linkSpec,
+            linkCreate,
+            parameters: args.parameters,
+        });
         await sleep(delays.appPoll);
-        link = await getLink(context.np, link.id).catch(() => link);
-        const headline = existing
+        const link = await getLink(context.np, linked.id).catch(() => linked);
+        const headline = reused
             ? 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)}`;
@@ -156,7 +183,7 @@ export const createLinkTool = defineTool({
             app_name: app.name,
             service: { id: service.id, name: service.name },
             link: { id: link.id, status: link.status, target: target.label },
-            reused: Boolean(existing),
+            reused,
             dashboard,
         });
     },

package/dist/tools/create-release.js

@@ -8,7 +8,7 @@ import { appArg, requireApp } from "./shared.js";
 export const createReleaseTool = defineTool({
     name: TOOL.applicationReleaseCreate,
     title: "Create release",
-    description: "Cut an active release from a build (default: the latest successful build; semver auto-bumps the patch). Usually you can just call deploy, which does this for you.",
+    description: 'Cut an active RELEASE from a build (default: the latest successful build; semver auto-bumps the patch) — a release is a deployable, versioned pin of a build. Use it for "cut a release", "create a release from build X" WITHOUT deploying. Usually you do NOT need this directly: application_deployment_create cuts the release for you as part of shipping — reach for this only when the user explicitly wants a release but not a deploy. Convergent: reuses the existing active release for the same build rather than duplicating. Renders the releases panel; deploy a release with application_deployment_create.',
     // Convergent under retries (reuses the active release-for-build), so idempotent.
     annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: true },
     widget: "releases",