@nullplatform/mcp 0.1.2 → 0.1.4

package/dist/i18n.js

@@ -51,6 +51,9 @@ const english = {
     "header.live": "Live",
     "header.traffic": "Traffic",
     "header.when": "When",
+    "header.version": "Version",
+    "header.build": "Build",
+    "header.release": "Release",
     // — markdown design language —
     "md.next": "Next",
     "md.none": "_none_",
@@ -160,6 +163,7 @@ const english = {
     "builds.commit": "Commit",
     "builds.released": "Released",
     "builds.none": "**{app}** has no builds yet.",
+    "builds.noneForCommit": "No build in **{app}** for commit `{commit}` — it may not have built yet, or the commit isn't on a built branch.",
     "builds.noneHint": "push a commit so CI produces one, then `application_deployment_create`.",
     "builds.deployHint": "`application_deployment_create build_id:{build}` ships it (cuts the release for you).",
     "builds.waiting": "build #{build} is still running — `application_build_list` again in a moment to check.",
@@ -167,6 +171,16 @@ const english = {
     "builds.assetsTitle": "Assets of build #{build}",
     "builds.noAssets": "Build #{build} has no assets (it may still be building).",
     "builds.errorLabel": "Couldn't list builds",
+    "releaseList.title": "**{app}** · {count} release(s)",
+    "releaseList.none": "**{app}** has no releases yet.",
+    "releaseList.noneHint": "cut one from a successful build with `application_release_create`, or just `application_deployment_create`.",
+    "releaseList.deployHint": 'deploy an active release with `application_deployment_create version:"x.y.z"`.',
+    "releaseList.errorLabel": "Couldn't list releases",
+    "deploymentList.title": "**{app}** · {count} deployment(s)",
+    "deploymentList.none": "**{app}** has no deployments yet.",
+    "deploymentList.group": "{count} scopes (group)",
+    "deploymentList.hint": "`application_get` for the live picture, or `application_deployment_update` to drive a rollout.",
+    "deploymentList.errorLabel": "Couldn't list deployments",
     // — organization_get tool —
     "overview.title": "Organization overview · {count} application(s) scanned",
     "overview.truncated": '_(showing the first {count} — narrow with `organization_get query:"..."`)_',
@@ -324,6 +338,9 @@ const spanish = {
     "header.live": "En vivo",
     "header.traffic": "Tráfico",
     "header.when": "Cuándo",
+    "header.version": "Versión",
+    "header.build": "Build",
+    "header.release": "Release",
     "md.next": "Siguiente",
     "md.none": "_ninguno_",
     "md.justNow": "recién",
@@ -423,6 +440,7 @@ const spanish = {
     "builds.commit": "Commit",
     "builds.released": "Released",
     "builds.none": "**{app}** todavía no tiene builds.",
+    "builds.noneForCommit": "Ningún build en **{app}** para el commit `{commit}` — puede que todavía no haya buildeado, o que el commit no esté en una branch que buildea.",
     "builds.noneHint": "pusheá un commit para que CI genere uno, después `application_deployment_create`.",
     "builds.deployHint": "`application_deployment_create build_id:{build}` lo publica (crea la release por vos).",
     "builds.waiting": "el build #{build} sigue corriendo — `application_build_list` de nuevo en un momento para chequear.",
@@ -430,6 +448,16 @@ const spanish = {
     "builds.assetsTitle": "Assets del build #{build}",
     "builds.noAssets": "El build #{build} no tiene assets (puede estar compilando todavía).",
     "builds.errorLabel": "No pude listar los builds",
+    "releaseList.title": "**{app}** · {count} release(s)",
+    "releaseList.none": "**{app}** todavía no tiene releases.",
+    "releaseList.noneHint": "cortá uno desde un build exitoso con `application_release_create`, o directamente `application_deployment_create`.",
+    "releaseList.deployHint": 'deployá un release activo con `application_deployment_create version:"x.y.z"`.',
+    "releaseList.errorLabel": "No pude listar los releases",
+    "deploymentList.title": "**{app}** · {count} deployment(s)",
+    "deploymentList.none": "**{app}** todavía no tiene deployments.",
+    "deploymentList.group": "{count} scopes (grupo)",
+    "deploymentList.hint": "`application_get` para la foto en vivo, o `application_deployment_update` para conducir un rollout.",
+    "deploymentList.errorLabel": "No pude listar los deployments",
     // — organization_get tool —
     "overview.title": "Panorama de la organización · {count} aplicación(es) escaneada(s)",
     "overview.truncated": '_(muestro las primeras {count} — acotá con `organization_get query:"..."`)_',

package/dist/np/context.js

@@ -12,10 +12,15 @@ export function baseRepoUrl(provider, prefix) {
             : "https://github.com";
     return `${host}/${prefix}`;
 }
-/** Default ceiling for a single app search — used as the per-namespace fetch cap AND the
- *  overall result cap. Beyond it the tool reports truncation and asks the user to narrow.
- *  (The old value of 50 silently hid larger orgs behind a flat "50 applications".) */
-export const DEFAULT_APP_LIMIT = 200;
+/** Org-wide app discovery must fan out across namespaces: the public `/application` endpoint is
+ *  namespace-scoped, with no org-wide list and no name search — so the name filter is client-side
+ *  by necessity. We page each namespace to completion and bound the AGGREGATE at this cap, which
+ *  is generous and lift-able via NP_MAX_APPS, reporting truncation past it instead of silently
+ *  hiding a large org (the old code capped the whole org at 200 with a flat `.slice`). */
+const MAX_APPS = Math.max(1, Number(process.env.NP_MAX_APPS) || 1000);
+export const DEFAULT_APP_LIMIT = MAX_APPS;
+/** Safety ceiling when paging the account/namespace skeleton (both rarely exceed one page). */
+const SKELETON_CAP = 2000;
 /** Concurrency-limited parallel map — fast fan-out without hammering the API. */
 export async function pmap(items, mapItem, limit = 12) {
     const results = new Array(items.length);
@@ -29,6 +34,20 @@ export async function pmap(items, mapItem, limit = 12) {
     await Promise.all(Array.from({ length: Math.min(limit, items.length || 1) }, worker));
     return results;
 }
+/** Page an offset-based list endpoint to completion, bounded by `max` items. No list response
+ *  carries a total, so the boundary is the standard offset heuristic: a page shorter than the
+ *  requested limit is the last one. */
+async function fetchPaged(fetchPage, max, pageSize = 200) {
+    const rows = [];
+    for (let offset = 0; offset < max; offset += pageSize) {
+        const limit = Math.min(pageSize, max - offset);
+        const page = await fetchPage(offset, limit);
+        rows.push(...page);
+        if (page.length < limit)
+            break;
+    }
+    return rows;
+}
 /**
  * The public list endpoints are NRN-authorized and need explicit scoping (account needs
  * organization_id, namespace needs account_id, application needs namespace_id). There is no
@@ -53,16 +72,17 @@ export class NpContext {
         if (!refresh && this.skeleton && Date.now() - this.skeleton.at < NpContext.CACHE_TTL_MS)
             return this.skeleton;
         const orgId = await this.organizationId();
-        const accountsResp = await this.np.get("/account", {
-            organization_id: orgId,
-            limit: 200,
-        });
-        const perAccount = await pmap(accountsResp.results ?? [], async (account) => {
-            const namespacesPage = await this.np
-                .get("/namespace", { account_id: account.id, limit: 200 })
-                .catch(() => ({ results: [] }));
+        const accounts = await fetchPaged((offset, limit) => this.np
+            .get("/account", { organization_id: orgId, offset, limit })
+            .then((page) => page.results ?? [])
+            .catch(() => []), SKELETON_CAP);
+        const perAccount = await pmap(accounts, async (account) => {
+            const accountNamespaces = await fetchPaged((offset, limit) => this.np
+                .get("/namespace", { account_id: account.id, offset, limit })
+                .then((page) => page.results ?? [])
+                .catch(() => []), SKELETON_CAP);
             const accountBaseRepoUrl = baseRepoUrl(account.repository_provider, account.repository_prefix);
-            return (namespacesPage.results ?? []).map((namespace) => ({
+            return accountNamespaces.map((namespace) => ({
                 id: namespace.id,
                 name: namespace.name,
                 nrn: namespace.nrn,
@@ -109,21 +129,12 @@ export class NpContext {
             ? skeleton.namespaces.filter((namespace) => namespace.name.toLowerCase().includes(namespaceFilter))
             : skeleton.namespaces;
         const nameFilter = args.query?.toLowerCase();
-        const perNamespace = await pmap(namespaces, async (namespace) => {
-            try {
-                const query = {
-                    namespace_id: namespace.id,
-                    limit: DEFAULT_APP_LIMIT,
-                };
-                if (args.query)
-                    query["name:contains"] = args.query; // server-side when supported
-                const page = await this.np.get("/application", query);
-                return (page.results ?? []).map((app) => this.mapApp(app, namespace));
-            }
-            catch {
-                return [];
-            }
-        });
+        // `/application` is namespace-scoped with no name filter, so page each namespace to completion
+        // and filter by name client-side (below). This lifts the old silent 200-per-org cap.
+        const perNamespace = await pmap(namespaces, async (namespace) => fetchPaged((offset, limit) => this.np
+            .get("/application", { namespace_id: namespace.id, offset, limit })
+            .then((page) => page.results ?? [])
+            .catch(() => []), MAX_APPS).then((rows) => rows.map((app) => this.mapApp(app, namespace))));
         const seen = new Set();
         return perNamespace
             .flat()

package/dist/np/journey.js

@@ -11,13 +11,24 @@ const TERMINAL = new Set([
 ]);
 export const isDeploymentTerminal = (status) => !!status && TERMINAL.has(status);
 export function bumpSemver(semver) {
-    const parts = /^v?(\d+)\.(\d+)\.(\d+)/.exec(semver ?? "");
-    return parts ? `${parts[1]}.${parts[2]}.${Number(parts[3]) + 1}` : "0.0.1";
+    // Preserve the optional `v` prefix: an org that enforces a v-prefixed version pattern
+    // rejects a bare bump, and dropping it makes the release history inconsistent.
+    const parts = /^(v?)(\d+)\.(\d+)\.(\d+)/.exec(semver ?? "");
+    return parts ? `${parts[1]}${parts[2]}.${parts[3]}.${Number(parts[4]) + 1}` : "0.0.1";
 }
-export async function listBuilds(np, applicationId, limit = 10) {
-    const page = await np
-        .get("/build", { application_id: applicationId, sort: "created_at:desc", limit })
-        .catch(() => ({ results: [] }));
+export async function listBuilds(np, applicationId, options = {}) {
+    const query = {
+        application_id: applicationId,
+        sort: "created_at:desc",
+        limit: options.limit ?? 10,
+    };
+    // The public API filters builds by full commit SHA via the `commit.id` query param (in the
+    // canonical OpenAPI contract) — this is how a change is traced from a commit to its build.
+    if (options.commit)
+        query["commit.id"] = options.commit;
+    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,
@@ -43,6 +54,8 @@ export async function listReleases(np, applicationId, options = {}) {
     };
     if (options.status)
         query.status = options.status;
+    if (options.offset)
+        query.offset = options.offset;
     const page = await np
         .get("/release", query)
         .catch(() => ({ results: [] }));
@@ -186,6 +199,25 @@ export async function listScopeDeployments(np, scopeId, limit = 3) {
         .catch(() => ({ results: [] }));
     return (page.results ?? []).map(mapDeployment);
 }
+/** Every deployment of an application, newest first — the public `/deployment` endpoint accepts
+ *  `application_id`. Group rows (`type: "deployment_group"`) carry their per-scope children. */
+export async function listDeployments(np, applicationId, options = {}) {
+    const query = {
+        application_id: applicationId,
+        sort: "created_at:desc",
+        limit: options.limit ?? 50,
+    };
+    if (options.offset)
+        query.offset = options.offset;
+    const page = await np
+        .get("/deployment", query)
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map((row) => ({
+        ...mapDeployment(row),
+        type: row.type,
+        deployments: row.deployments?.map(mapDeployment),
+    }));
+}
 /**
  * Traffic switch — the public API takes desiredSwitchedTraffic (camelCase INSIDE the
  * snake_case strategy_data envelope; verified live) and moves traffic toward it.
@@ -234,9 +266,12 @@ export async function setParameters(np, nrn, params) {
     return { created, updated };
 }
 /** Read parameters — NRN-scoped on the public API; returns undefined when unavailable. */
-export async function listParameters(np, nrn) {
+export async function listParameters(np, nrn, options = {}) {
     try {
-        const page = await np.get("/parameter", { nrn, limit: 100 });
+        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,

package/dist/surfaces/developer.js

@@ -6,7 +6,9 @@ import { tools } from "../tools/index.js";
  */
 const INSTRUCTIONS = `nullplatform is where this code gets built, released, deployed and observed — these tools replace its web dashboard for the everyday developer journey.
 
-The tools are repo-aware: inside a git repo, omit \`app\` and the linked application is inferred from the git remote. Start with \`application_get\` — it shows what's live where and suggests the next action.
+The tools are repo-aware: inside a git repo, omit \`app\` and the linked application is inferred from the git remote. "This app", or a request that names nothing, means the repo's app — infer it; pass \`app\` only when the user means a different, explicitly named application. Start with \`application_get\` — it shows what's live where and suggests the next action.
+
+You run in the developer's own environment, so fuse the local repo with platform state. Read the git remote, branch, HEAD commit, the diff being shipped, and config files (\`.env\`, \`package.json\`, Dockerfile), and correlate them with what the platform reports: does the local HEAD match a built or released commit, does a local config value match what a scope resolves. That correlation is this integration's edge over the web dashboard, which only sees the platform half.
 
 Every tool accepts \`language\`: ALWAYS set it to the language the user is conversing in (ISO code, e.g. "es", "en") — answers come back in the user's language.
 

package/dist/tool-names.js

@@ -12,6 +12,8 @@ export const TOOL = {
     applicationLogList: "application_log_list",
     applicationMetricList: "application_metric_list",
     applicationBuildList: "application_build_list",
+    applicationReleaseList: "application_release_list",
+    applicationDeploymentList: "application_deployment_list",
     applicationParameterList: "application_parameter_list",
     applicationParameterCreate: "application_parameter_create",
     applicationDeploymentCreate: "application_deployment_create",

package/dist/tools/builds.js

@@ -4,7 +4,7 @@ import { ago, glyph, next, shortCommit, table } from "../md.js";
 import { listAssets, listBuilds, listReleases } from "../np/journey.js";
 import { defineTool, reply } from "../tool.js";
 import { TOOL } from "../tool-names.js";
-import { appArg, requireApp } from "./shared.js";
+import { appArg, offsetArg, pageOf, requireApp } from "./shared.js";
 /**
  * Closes the hole in the ship loop: between "push a commit" and "deploy" sits CI, and the
  * agent needs to see builds land. status only shows the latest; this lists recent builds,
@@ -12,14 +12,20 @@ import { appArg, requireApp } from "./shared.js";
  */
 export const buildsTool = defineTool({
     name: TOOL.applicationBuildList,
-    title: "List builds",
-    description: "List an application's recent CI builds — status, branch, commit, age, and whether each is already released. Use it to answer 'did my push build yet?' and to pick a build_id to deploy. Pass build:<id> to see that build's assets.",
+    title: "Builds",
+    description: "List an application's recent CI builds — status, branch, commit, age, and whether each is already released. Use it to answer 'did my push build yet?' and to pick a build_id to deploy. Pass build:<id> to see that build's assets, or commit:<sha> to find the build for a specific commit (tracing a change to its build and release).",
     annotations: { readOnlyHint: true, openWorldHint: true },
+    widget: "builds",
     errorKey: "builds.errorLabel",
     inputSchema: {
         app: appArg,
         build: z.number().optional().describe("Build id — show this build's assets instead of the list"),
         limit: z.number().optional().describe("How many recent builds (default 10)"),
+        commit: z
+            .string()
+            .optional()
+            .describe("Full commit SHA — list only the build(s) for that commit (tracing a change to its build/release)"),
+        offset: offsetArg,
     },
     async handler(args, context) {
         const resolved = await requireApp(context, args);
@@ -43,11 +49,14 @@ export const buildsTool = defineTool({
             return reply(markdown, { build_id: args.build, assets });
         }
         const [builds, releases] = await Promise.all([
-            listBuilds(context.np, app.id, args.limit ?? 10),
+            listBuilds(context.np, app.id, { limit: args.limit ?? 10, commit: args.commit, offset: args.offset }),
             listReleases(context.np, app.id, { limit: 50 }),
         ]);
         if (builds.length === 0) {
-            return reply(translate("builds.none", { app: app.name }) + next(translate("builds.noneHint")));
+            const empty = args.commit
+                ? translate("builds.noneForCommit", { app: app.name, commit: shortCommit(args.commit) })
+                : translate("builds.none", { app: app.name }) + next(translate("builds.noneHint"));
+            return reply(empty, { app: `#${app.id}`, app_name: app.name, builds: [], commit: args.commit ?? null });
         }
         const releasedBuildIds = new Set(releases.map((release) => release.build_id).filter(Boolean));
         const releaseByBuild = new Map(releases.map((release) => [release.build_id, release]));
@@ -79,6 +88,7 @@ export const buildsTool = defineTool({
                 released: releasedBuildIds.has(build.id),
                 release_semver: releaseByBuild.get(build.id)?.semver ?? null,
             })),
+            page: pageOf(builds.length, args.limit ?? 10, args.offset ?? 0),
         });
     },
 });

package/dist/tools/create-release.js

@@ -24,7 +24,7 @@ export const createReleaseTool = defineTool({
         let buildId = args.build_id;
         let buildNote = "";
         if (!buildId) {
-            const builds = await listBuilds(context.np, app.id, 5);
+            const builds = await listBuilds(context.np, app.id, { limit: 5 });
             const successful = builds.find((build) => build.status === "successful");
             if (!successful)
                 return fail(translate("createRelease.noBuilds", { app: app.name }));

package/dist/tools/deploy.js

@@ -15,7 +15,7 @@ async function resolveRelease(context, applicationId, args) {
     // code under its name — so search deep enough that only pathologically active apps miss.
     const [releases, builds] = await Promise.all([
         listReleases(context.np, applicationId, { status: "active", limit: 200 }),
-        listBuilds(context.np, applicationId, 5),
+        listBuilds(context.np, applicationId, { limit: 5 }),
     ]);
     const successfulBuild = builds.find((build) => build.status === "successful");
     if (args.release_id) {

package/dist/tools/deployments.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { ago, glyph, next, table } from "../md.js";
+import { listDeployments, listReleases, listScopes } from "../np/journey.js";
+import { defineTool, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { appArg, offsetArg, pageOf, requireApp } from "./shared.js";
+/**
+ * The deployments list — the end of build → release → deploy. Lists every deployment across an
+ * app's scopes (a deployment_group lands one release on several scopes and is shown as one row),
+ * resolving scope and release names so both the text reply and the bound widget read cleanly.
+ */
+export const deploymentsTool = defineTool({
+    name: TOOL.applicationDeploymentList,
+    title: "Deployments",
+    description: "List an application's deployments across all scopes — which release landed on which scope, the rollout status, and age; a deployment group (one release to several scopes) is shown as one row. Use to see deploy history or find an active rollout.",
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    widget: "deployments",
+    errorKey: "deploymentList.errorLabel",
+    inputSchema: {
+        app: appArg,
+        limit: z.number().optional().describe("How many recent deployments (default 50)"),
+        offset: offsetArg,
+    },
+    async handler(args, context) {
+        const resolved = await requireApp(context, args);
+        if ("out" in resolved)
+            return resolved.out;
+        const app = resolved.app;
+        const [rows, scopes, releases] = await Promise.all([
+            listDeployments(context.np, app.id, { limit: args.limit ?? 50, offset: args.offset }),
+            listScopes(context.np, app.id),
+            listReleases(context.np, app.id, { limit: 200 }),
+        ]);
+        if (rows.length === 0) {
+            return reply(translate("deploymentList.none", { app: app.name }), {
+                app: `#${app.id}`,
+                app_name: app.name,
+                deployments: [],
+            });
+        }
+        const scopeName = new Map(scopes.map((scope) => [scope.id, scope.name]));
+        const semverOf = new Map(releases.map((release) => [release.id, release.semver]));
+        const scopeLabel = (row) => row.type === "deployment_group"
+            ? translate("deploymentList.group", { count: row.deployments?.length ?? 0 })
+            : (scopeName.get(row.scope_id ?? -1) ?? `scope #${row.scope_id ?? "?"}`);
+        const releaseLabel = (releaseId) => releaseId ? (semverOf.get(releaseId) ?? `#${releaseId}`) : "";
+        const markdown = [
+            translate("deploymentList.title", { app: app.name, count: rows.length }),
+            "",
+            table([
+                translate("header.scope"),
+                translate("header.release"),
+                translate("header.status"),
+                translate("header.when"),
+            ], rows.map((row) => [
+                scopeLabel(row),
+                releaseLabel(row.release_id),
+                `${glyph(row.status)} ${row.status}`,
+                ago(row.created_at),
+            ])),
+            next(translate("deploymentList.hint")),
+        ].join("\n");
+        // Enrich the structured rows the widget renders: scope + release names resolved, children too.
+        const enrich = (row) => ({
+            ...row,
+            scope_name: scopeName.get(row.scope_id ?? -1) ?? null,
+            release_semver: row.release_id ? (semverOf.get(row.release_id) ?? null) : null,
+        });
+        const deployments = rows.map((row) => ({
+            ...enrich(row),
+            deployments: row.deployments?.map(enrich),
+        }));
+        return reply(markdown, {
+            app: `#${app.id}`,
+            app_name: app.name,
+            deployments,
+            page: pageOf(rows.length, args.limit ?? 50, args.offset ?? 0),
+        });
+    },
+});

package/dist/tools/find-apps.js

@@ -7,7 +7,7 @@ import { defineTool, reply } from "../tool.js";
 import { TOOL } from "../tool-names.js";
 export const findAppsTool = defineTool({
     name: TOOL.applicationList,
-    title: "Find applications",
+    title: "Applications",
     description: "Search applications across the whole organization by partial name (and optionally namespace). Fast (parallel + cached). Use when the repo isn't linked or the user names an app you don't know.",
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "find-apps",

package/dist/tools/index.js

@@ -4,12 +4,14 @@ import { createAppTool } from "./create-app.js";
 import { createReleaseTool } from "./create-release.js";
 import { createScopeTool } from "./create-scope.js";
 import { deployTool } from "./deploy.js";
+import { deploymentsTool } from "./deployments.js";
 import { findAppsTool } from "./find-apps.js";
 import { logsTool } from "./logs.js";
 import { metricsTool } from "./metrics.js";
 import { overviewTool } from "./overview.js";
 import { paramsTool } from "./params.js";
 import { playbookGetTool } from "./playbook.js";
+import { releasesTool } from "./releases.js";
 import { servicesTool } from "./services.js";
 import { setParamsTool } from "./set-params.js";
 import { statusTool } from "./status.js";
@@ -24,6 +26,8 @@ export const tools = [
     overviewTool,
     findAppsTool,
     buildsTool,
+    releasesTool,
+    deploymentsTool,
     logsTool,
     paramsTool,
     metricsTool,

package/dist/tools/logs.js

@@ -7,7 +7,7 @@ import { TOOL } from "../tool-names.js";
 import { appArg, chooseScope, requireApp } from "./shared.js";
 export const logsTool = defineTool({
     name: TOOL.applicationLogList,
-    title: "Read logs",
+    title: "Logs",
     description: "Read recent application logs (optionally for one scope). Returns the latest lines, newest last — good for a quick 'why is it failing?' look.",
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "logs",

package/dist/tools/params.js

@@ -3,15 +3,15 @@ import { dashboardLink, linkLine, next, table } from "../md.js";
 import { listParameters } from "../np/journey.js";
 import { defineTool, fail, reply } from "../tool.js";
 import { TOOL } from "../tool-names.js";
-import { appArg, requireApp } from "./shared.js";
+import { appArg, offsetArg, pageOf, requireApp } from "./shared.js";
 export const paramsTool = defineTool({
     name: TOOL.applicationParameterList,
-    title: "List parameters",
+    title: "Parameters",
     description: "List an application's configuration parameters (env vars / files; secret values are masked). Use application_parameter_create to add or change them.",
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "params",
     errorKey: "params.errorLabel",
-    inputSchema: { app: appArg },
+    inputSchema: { app: appArg, offset: offsetArg },
     async handler(args, context) {
         const resolved = await requireApp(context, args);
         if ("out" in resolved)
@@ -20,7 +20,7 @@ export const paramsTool = defineTool({
         if (!app.nrn)
             return fail(translate("resolve.noNrn", { app: app.name }));
         const [parameters, orgSlug] = await Promise.all([
-            listParameters(context.np, app.nrn),
+            listParameters(context.np, app.nrn, { offset: args.offset }),
             context.org.organizationSlug(),
         ]);
         const dashboard = dashboardLink(orgSlug, app.nrn);
@@ -53,6 +53,11 @@ export const paramsTool = defineTool({
             ])),
             next(translate("params.applyHint")),
         ].join("\n");
-        return reply(markdown, { available: true, params: parameters, ...appRef });
+        return reply(markdown, {
+            available: true,
+            params: parameters,
+            page: pageOf(parameters.length, 100, args.offset ?? 0),
+            ...appRef,
+        });
     },
 });

package/dist/tools/playbook.js

@@ -13,8 +13,8 @@ import { TOOL } from "../tool-names.js";
 const playbookBody = (markdown) => markdown.replace(/^---\n[\s\S]*?\n---\n?/, "").trim();
 export const playbookGetTool = defineTool({
     name: TOOL.playbookGet,
-    title: "Read an operating playbook",
-    description: "Read a nullplatform operating playbook — the methodology to follow before the matching non-trivial work: deploying-safely before a deploy/rollout, incident-response when something is broken, platform-conventions for entity/versioning/traffic semantics. Call with no name to list the available playbooks.",
+    title: "Operating playbooks",
+    description: "Read a nullplatform operating playbook — the methodology to follow BEFORE the matching non-trivial work (e.g. deploying-safely before a deploy, incident-response when something is broken, configuring-safely before changing parameters or secrets). The server instructions carry the full catalog; call this with no name to list them too.",
     annotations: { readOnlyHint: true },
     errorKey: "playbook.errorLabel",
     inputSchema: {

package/dist/tools/releases.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { ago, glyph, next, table } from "../md.js";
+import { 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";
+/**
+ * The releases list — the middle of build → release → deploy. A release is an immutable semver
+ * pointer to a build; this lists them so the model (and the bound widget) can pick one to deploy.
+ */
+export const releasesTool = defineTool({
+    name: TOOL.applicationReleaseList,
+    title: "Releases",
+    description: "List an application's releases — semver, status (active/deprecated/unstable/failed), the build each pins, and age. Use to pick a release to deploy or promote, or to see what's shippable.",
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    widget: "releases",
+    errorKey: "releaseList.errorLabel",
+    inputSchema: {
+        app: appArg,
+        limit: z.number().optional().describe("How many recent releases (default 25)"),
+        offset: offsetArg,
+    },
+    async handler(args, context) {
+        const resolved = await requireApp(context, args);
+        if ("out" in resolved)
+            return resolved.out;
+        const app = resolved.app;
+        const releases = await listReleases(context.np, app.id, {
+            limit: args.limit ?? 25,
+            offset: args.offset,
+        });
+        if (releases.length === 0) {
+            return reply(translate("releaseList.none", { app: app.name }) + next(translate("releaseList.noneHint")), { app: `#${app.id}`, app_name: app.name, releases: [] });
+        }
+        const markdown = [
+            translate("releaseList.title", { app: app.name, count: releases.length }),
+            "",
+            table([
+                translate("header.version"),
+                translate("header.status"),
+                translate("header.build"),
+                translate("header.when"),
+            ], releases.map((release) => [
+                release.semver,
+                `${glyph(release.status)} ${release.status}`,
+                release.build_id ? `#${release.build_id}` : "",
+                ago(release.created_at),
+            ])),
+            next(translate("releaseList.deployHint")),
+        ].join("\n");
+        return reply(markdown, {
+            app: `#${app.id}`,
+            app_name: app.name,
+            releases,
+            page: pageOf(releases.length, args.limit ?? 25, args.offset ?? 0),
+        });
+    },
+});

package/dist/tools/shared.js

@@ -11,6 +11,19 @@ export const appArg = z
     .string()
     .optional()
     .describe('Application name or "#id". Omit it to use the app linked to the current repo (git remote).');
+export const offsetArg = z
+    .number()
+    .optional()
+    .describe("Skip this many items to page through a long list (use page.next_offset from a prior call).");
+/**
+ * Pagination token for a list reply. No list endpoint returns a total, so the boundary is the
+ * standard offset heuristic: a full page means there is likely more. The widget/model pages by
+ * re-calling the tool with `offset: next_offset` until `has_more` is false.
+ */
+export function pageOf(count, limit, offset = 0) {
+    const hasMore = count >= limit;
+    return { has_more: hasMore, next_offset: hasMore ? offset + limit : null };
+}
 export function httpsRepoUrl(url) {
     const trimmed = url.trim().replace(/\.git$/, "");
     const sshForm = /^git@([^:]+):(.+)$/.exec(trimmed);

package/dist/tools/status.js

@@ -26,7 +26,7 @@ async function scopeViews(context, applicationId) {
 }
 export const statusTool = defineTool({
     name: TOOL.applicationGet,
-    title: "nullplatform status",
+    title: "Application status",
     description: "THE place to start. Shows an application's full picture: scopes with what's live on each (release + traffic), latest build, latest release, and the one obvious next action. Call with no arguments inside a repo to use the linked app. Pass deployment:<id> to watch one rollout in detail.",
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "np-panel",
@@ -54,7 +54,7 @@ export const statusTool = defineTool({
             return resolved.out;
         const [views, builds, releases, orgSlug] = await Promise.all([
             scopeViews(context, resolved.app.id),
-            listBuilds(context.np, resolved.app.id, 5),
+            listBuilds(context.np, resolved.app.id, { limit: 5 }),
             listReleases(context.np, resolved.app.id, { limit: 5 }),
             context.org.organizationSlug(),
         ]);

package/dist/tools/traffic.js

@@ -8,8 +8,8 @@ import { TOOL } from "../tool-names.js";
 import { appArg, delays, requireApp, sleep } from "./shared.js";
 export const trafficTool = defineTool({
     name: TOOL.applicationDeploymentUpdate,
-    title: "Traffic / finalize / rollback",
-    description: 'Drive an in-flight rollout: move traffic to the new version (percent snaps to 1,5,10,25,50,75,90,95,99,100), finalize it (action:"finalize" — retire the old version), or roll it back (action:"rollback" — traffic returns to the old version). Finds the app\'s active deployment automatically.',
+    title: "Update traffic",
+    description: 'Drive an in-flight rollout: move traffic to the new version (percent snaps to 0,1,5,10,25,50,75,90,95,99,100), finalize it (action:"finalize" — retire the old version), or roll it back (action:"rollback" — traffic returns to the old version). Finds the app\'s active deployment automatically.',
     annotations: { destructiveHint: true, openWorldHint: true },
     widget: "np-panel",
     errorKey: "traffic.errorLabel",