@wardby/cli 0.2.1 → 0.3.0

package/dist/mcp/tools/repositories.js

@@ -0,0 +1,181 @@
+/**
+ * AgentRepository CRUD — which repositories on which code-review host a
+ * native agent may act on, and which host events trigger it. Linking needs
+ * more than owning the agent: the owner's own linked GitHub account must have
+ * the link's access on the repository (write for a write link, read for a
+ * read link), or a wardby admin must approve it explicitly (adminOverride).
+ * The authorization is stamped on the link and re-checked whenever the link
+ * is used (core/repo-access.ts). A repository is an owner binding (resource-
+ * sharing grants spec §3.4.3): link/unlink are the agent owner's alone (or
+ * an admin's explicit approval), whatever grants others hold on the agent,
+ * and owner-less agents can't be linked.
+ * See docs/private/2026-09-26-repo-access-authorization-spec-and-plan.md.
+ */
+import { Prisma } from "#prisma";
+import { normalizeGitHubRepository } from "../../coding/protocol.js";
+import { requireAgentAccess, requireBindingOwner } from "../auth/access.js";
+import { authorizeRepositoryForSet } from "../auth/repo-authorization.js";
+import { requireScope } from "../auth/resource-server.js";
+import { McpError } from "../errors.js";
+import { textResult } from "./text-result.js";
+const PROVIDERS = ["github"];
+const TRIGGERS = ["pull_request", "mention"];
+const CHECK_NAME = /^[A-Za-z0-9][A-Za-z0-9 ._/()-]{0,99}$/;
+function normalizeRepository(provider, repository) {
+    try {
+        if (provider === "github")
+            return normalizeGitHubRepository(repository);
+    }
+    catch {
+        // fall through
+    }
+    throw new McpError(400, `invalid repository "${repository}" for provider ${provider}`);
+}
+async function assertNoConflicts(tx, args) {
+    if (args.triggers.length === 0 && args.checkName === null)
+        return;
+    const others = await tx.agentRepository.findMany({
+        where: { provider: args.provider, repository: args.repository, NOT: { agentId: args.agentId } },
+    });
+    if (args.triggers.includes("mention") && others.some((o) => o.triggers.includes("mention"))) {
+        throw new McpError(409, `Another agent already handles @-mentions on ${args.repository}.`);
+    }
+    // Against every other link, whatever its triggers: a check name identifies
+    // one agent's verdict on the repository (also a unique index).
+    if (args.checkName !== null && others.some((o) => o.checkName === args.checkName)) {
+        throw checkNameTaken(args.checkName, args.repository);
+    }
+}
+function checkNameTaken(checkName, repository) {
+    return new McpError(409, `Another agent already uses check name "${checkName}" on ${repository}.`);
+}
+export function registerRepositoryTools(mcp) {
+    mcp.registerTool({
+        name: "link_repository",
+        scope: "agents:write",
+        description: "Links a native agent you own to a repository on a code-review host, with its access, event triggers, and checkName. " +
+            "Your linked GitHub account (link_host_account) must have write access to the repository for a write link, or read for a " +
+            "read link; a wardby admin may instead approve it with adminOverride. checkName is only allowed (and required) with the " +
+            "pull_request trigger, and is unique per repository. Re-linking an already-linked repository replaces its access, " +
+            "triggers, and checkName (an omitted field is cleared, not kept) and re-checks access — always send the full desired state.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                agentId: { type: "string" },
+                provider: { type: "string", enum: [...PROVIDERS] },
+                repository: { type: "string", minLength: 1, maxLength: 300 },
+                access: { type: "string", enum: ["read", "write"] },
+                triggers: { type: "array", items: { type: "string", enum: [...TRIGGERS] }, uniqueItems: true },
+                checkName: { type: "string", minLength: 1, maxLength: 100 },
+                adminOverride: {
+                    type: "boolean",
+                    description: "Admins only (agents:admin with the admin role): approve this link without checking GitHub access, recorded as an admin approval. Allowed on any agent that has an owner, not only the admin's own.",
+                },
+            },
+            required: ["agentId", "repository", "access"],
+        },
+        handler: async (args, ctx) => {
+            // An admin approving a repository explicitly may do it on any agent
+            // (the role already allows reassigning any agent with make_owner);
+            // everyone else, admins included, links only agents they own.
+            let agent;
+            if (args.adminOverride === true) {
+                requireScope(ctx, ctx.canonicalUri, "agents:admin");
+                agent = await ctx.db.agent.findUnique({ where: { id: args.agentId } });
+                if (!agent)
+                    throw new McpError(404, `Agent "${args.agentId}" not found.`);
+            }
+            else {
+                agent = (await requireAgentAccess(ctx, args.agentId, "read")).agent;
+                requireBindingOwner(ctx, agent);
+            }
+            if (agent.kind !== "native") {
+                throw new McpError(400, "Repository links are for native agents only; coding agents use codingProfile.repository.");
+            }
+            const provider = args.provider ?? "github";
+            const repository = normalizeRepository(provider, args.repository);
+            const triggers = [...new Set(args.triggers ?? [])];
+            if (triggers.length > 0 && args.access !== "write")
+                throw new McpError(400, "Event triggers need write access.");
+            const checkName = args.checkName ?? null;
+            if (triggers.includes("pull_request") && !checkName) {
+                throw new McpError(400, "checkName is required with the pull_request trigger.");
+            }
+            if (checkName !== null && !triggers.includes("pull_request")) {
+                throw new McpError(400, "checkName needs the pull_request trigger (a check is only published for a dispatched PR).");
+            }
+            if (checkName !== null && !CHECK_NAME.test(checkName))
+                throw new McpError(400, "invalid checkName");
+            // The host call happens before, and outside, the serializable transaction.
+            const authorization = await authorizeRepositoryForSet(ctx, {
+                ownerId: agent.ownerId,
+                provider,
+                repository,
+                kind: args.access,
+                adminOverride: args.adminOverride === true,
+            });
+            let link;
+            try {
+                link = await ctx.db.$transaction(async (tx) => {
+                    await assertNoConflicts(tx, { agentId: args.agentId, provider, repository, triggers, checkName });
+                    const fields = { access: args.access, triggers, checkName, ...authorization };
+                    return tx.agentRepository.upsert({
+                        where: { agentId_provider_repository: { agentId: args.agentId, provider, repository } },
+                        create: { agentId: args.agentId, provider, repository, ...fields },
+                        update: fields,
+                    });
+                }, { isolationLevel: "Serializable" });
+            }
+            catch (err) {
+                if (checkName !== null && err instanceof Prisma.PrismaClientKnownRequestError && err.code === "P2002") {
+                    throw checkNameTaken(checkName, repository);
+                }
+                throw err;
+            }
+            return textResult({ linked: true, link });
+        },
+    });
+    mcp.registerTool({
+        name: "unlink_repository",
+        scope: "agents:write",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                agentId: { type: "string" },
+                provider: { type: "string", enum: [...PROVIDERS] },
+                repository: { type: "string", minLength: 1, maxLength: 300 },
+            },
+            required: ["agentId", "repository"],
+        },
+        handler: async (args, ctx) => {
+            const { agent } = await requireAgentAccess(ctx, args.agentId, "read");
+            requireBindingOwner(ctx, agent);
+            const provider = args.provider ?? "github";
+            const repository = normalizeRepository(provider, args.repository);
+            const { count } = await ctx.db.agentRepository.deleteMany({
+                where: { agentId: args.agentId, provider, repository },
+            });
+            return textResult({ unlinked: count > 0 });
+        },
+    });
+    mcp.registerTool({
+        name: "list_repositories",
+        scope: "agents:read",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: { agentId: { type: "string" } },
+            required: ["agentId"],
+        },
+        handler: async (args, ctx) => {
+            await requireAgentAccess(ctx, args.agentId, "read");
+            const links = await ctx.db.agentRepository.findMany({
+                where: { agentId: args.agentId },
+                orderBy: { createdAt: "asc" },
+            });
+            return textResult({ repositories: links });
+        },
+    });
+}

package/dist/mcp/tools/runs.d.ts

@@ -1,2 +1,8 @@
 import type { WardbyMcpServer } from "../server.js";
+/**
+ * Run visibility (resource-sharing grants spec §3.5, A6): a run's output is
+ * the triggerer's and the agent owner's, never every reader's. The owner
+ * (and the stdio operator) sees every run; anyone else only runs with
+ * Run.triggeredById equal to themselves.
+ */
 export declare function registerRunTools(mcp: WardbyMcpServer): void;

package/dist/mcp/tools/runs.js

@@ -1,7 +1,15 @@
 import { McpError } from "../errors.js";
-import { requireReadableAgent } from "../auth/ownership.js";
+import { agentAccess, requireAgentAccess } from "../auth/access.js";
 import { publicCodingRunResult } from "../../coding/protocol.js";
+import { countPlanRefusals, summarizeRegistryFetches } from "../../coding/registry/report.js";
+import { storedServiceLabels } from "../../coding/services/catalog.js";
 import { textResult } from "./text-result.js";
+/**
+ * Run visibility (resource-sharing grants spec §3.5, A6): a run's output is
+ * the triggerer's and the agent owner's, never every reader's. The owner
+ * (and the stdio operator) sees every run; anyone else only runs with
+ * Run.triggeredById equal to themselves.
+ */
 export function registerRunTools(mcp) {
     mcp.registerTool({
         name: "list_runs",
@@ -12,9 +20,13 @@ export function registerRunTools(mcp) {
             required: ["agentId"],
         },
         handler: async (args, ctx) => {
-            await requireReadableAgent(ctx.db, args.agentId, ctx.principal.id);
+            const { access } = await requireAgentAccess(ctx, args.agentId, "read");
             const runs = await ctx.db.run.findMany({
-                where: { agentId: args.agentId, ...(args.status ? { status: args.status } : {}) },
+                where: {
+                    agentId: args.agentId,
+                    ...(args.status ? { status: args.status } : {}),
+                    ...(access === "owner" ? {} : { triggeredById: ctx.principal.id }),
+                },
                 take: args.limit,
                 orderBy: { startedAt: "desc" },
             });
@@ -40,21 +52,63 @@ export function registerRunTools(mcp) {
         inputSchema: { type: "object", properties: { runId: { type: "string" } }, required: ["runId"] },
         handler: async (args, ctx) => {
             const run = await ctx.db.run.findUnique({ where: { id: args.runId } });
+            const notFound = new McpError(404, `Run "${args.runId}" not found.`);
             if (!run)
-                throw new McpError(404, `Run "${args.runId}" not found.`);
-            await requireReadableAgent(ctx.db, run.agentId, ctx.principal.id);
+                throw notFound;
+            // Its triggerer keeps seeing it even after losing access to the agent;
+            // otherwise only the agent's owner. read on the agent is not enough.
+            if (run.triggeredById !== ctx.principal.id) {
+                const agent = await ctx.db.agent.findUnique({ where: { id: run.agentId } });
+                if (!agent || (await agentAccess(ctx, agent)) !== "owner")
+                    throw notFound;
+            }
             const codingRun = await ctx.db.codingRun.findUnique({
                 where: { runId: run.id },
-                select: { result: true, queuedAt: true },
+                select: {
+                    result: true,
+                    queuedAt: true,
+                    failureCategory: true,
+                    diagnosticId: true,
+                    debugTrace: true,
+                    services: true,
+                },
             });
             const codingResult = publicCodingRunResult(codingRun?.result);
             // A pending coding run with queuedAt is waiting for a concurrency slot
             // (CODING_MAX_CONCURRENT), not stuck.
             const codingQueuedAt = run.status === "pending" && codingRun?.queuedAt ? codingRun.queuedAt.toISOString() : undefined;
+            // Packages served/refused only exist for coding runs; a non-coding run
+            // has no RegistryFetch rows at all, so skip the query entirely.
+            const registryFetches = codingRun
+                ? await ctx.db.registryFetch.findMany({ where: { runId: run.id }, orderBy: { createdAt: "asc" } })
+                : [];
+            const { packages, packageRefusals } = summarizeRegistryFetches(registryFetches);
+            // Lockfile verification (POST /registry/<ecosystem>/-/plan): exact
+            // versions approved for the run, and distinct entries it refused.
+            const packagePlan = codingRun
+                ? {
+                    approved: await ctx.db.registryApprovedVersion.count({ where: { runId: run.id } }),
+                    refused: countPlanRefusals(registryFetches),
+                }
+                : undefined;
+            // A failed coding run's error is only an opaque id; these two say which
+            // stage failed and are the key an operator searches the control-plane
+            // log for (the real reason is logged there, never persisted). Both are
+            // designed to be safe to show the agent's owner (schema.prisma).
+            const failureCategory = codingRun?.failureCategory ?? undefined;
+            const diagnosticId = codingRun?.diagnosticId ?? undefined;
+            // Which services the run started with ("postgres 16"); never their images or environments.
+            const services = codingRun ? storedServiceLabels(codingRun.services) : [];
             return textResult({
                 ...run,
                 ...(codingResult ? { codingResult } : {}),
+                ...(failureCategory ? { failureCategory } : {}),
+                ...(diagnosticId ? { diagnosticId } : {}),
                 ...(codingQueuedAt ? { codingQueuedAt } : {}),
+                // An admin turned on the debug trace: the worker's full trace is in its pod log.
+                ...(codingRun?.debugTrace ? { debugTrace: true } : {}),
+                ...(services.length > 0 ? { services } : {}),
+                ...(codingRun ? { packages, packageRefusals, packagePlan } : {}),
             });
         },
     });

package/dist/mcp/tools/scheduling.js

@@ -1,7 +1,7 @@
 import { Prisma } from "#prisma";
 import { validateCronExpression } from "../../core/cron.js";
 import { McpError } from "../errors.js";
-import { assertCanMutate, requireOwnedAgent } from "../auth/ownership.js";
+import { assertAgentAccess, requireAgentAccess } from "../auth/access.js";
 import { textResult } from "./text-result.js";
 export function registerSchedulingTools(mcp) {
     mcp.registerTool({
@@ -20,10 +20,7 @@ export function registerSchedulingTools(mcp) {
                 throw new McpError(400, `Invalid schedule/timezone: ${err instanceof Error ? err.message : String(err)}`);
             }
             const agent = await ctx.db.$transaction(async (tx) => {
-                const existing = await tx.agent.findUnique({ where: { id: args.agentId }, include: { codingProfile: true } });
-                if (!existing)
-                    throw new McpError(404, `Agent "${args.agentId}" not found.`);
-                assertCanMutate(existing.ownerId, ctx.principal.id, `Agent "${args.agentId}" is not owned by the caller.`);
+                const { agent: existing } = await assertAgentAccess(ctx, await tx.agent.findUnique({ where: { id: args.agentId }, include: { codingProfile: true } }), args.agentId, "write", tx);
                 if (existing.kind === "coding" && !existing.codingProfile?.defaultTask) {
                     throw new McpError(400, "A default task is required before enabling a coding-agent schedule.");
                 }
@@ -40,7 +37,7 @@ export function registerSchedulingTools(mcp) {
         scope: "agents:write",
         inputSchema: { type: "object", properties: { agentId: { type: "string" } }, required: ["agentId"] },
         handler: async (args, ctx) => {
-            await requireOwnedAgent(ctx.db, args.agentId, ctx.principal.id);
+            await requireAgentAccess(ctx, args.agentId, "write");
             const agent = await ctx.db.agent.update({ where: { id: args.agentId }, data: { scheduleEnabled: false } });
             return textResult(agent);
         },

package/dist/mcp/tools/secrets.js

@@ -6,7 +6,8 @@
 import { inputRequired, inputResponse } from "@modelcontextprotocol/server";
 import { createSecret, listSecrets, attachSecret, detachSecret, deleteSecret } from "../../core/secrets.js";
 import { McpError } from "../errors.js";
-import { requireOwnedAgent, requireOwnedSecret } from "../auth/ownership.js";
+import { requireOwnedSecret } from "../auth/ownership.js";
+import { requireAgentAccess, requireBindingOwner } from "../auth/access.js";
 import { getSecretElicitationOutcome } from "./secret-elicitation.js";
 import { textResult } from "./text-result.js";
 export function registerSecretsTools(mcp, opts) {
@@ -87,9 +88,15 @@ export function registerSecretsTools(mcp, opts) {
             required: ["agentId", "name"],
         },
         handler: async (args, ctx) => {
-            await requireOwnedAgent(ctx.db, args.agentId, ctx.principal.id);
+            // Strictly the agent owner's own secret on the owner's own agent
+            // (A2/S2-2): a binding hands the value to every tool the owner lets
+            // read it. Not even the stdio operator crosses owners.
+            const { agent } = await requireAgentAccess(ctx, args.agentId, "read");
+            requireBindingOwner(ctx, agent);
+            const ownerId = agent.ownerId;
             try {
-                await attachSecret(args.agentId, args.name, ctx.principal.id, ctx.db, args.alias ?? args.name);
+                // Resolved among the agent owner's secrets (== the caller here).
+                await attachSecret(args.agentId, args.name, ownerId, ctx.db, args.alias ?? args.name);
             }
             catch (err) {
                 throw new McpError(404, err instanceof Error ? err.message : String(err));
@@ -100,15 +107,20 @@ export function registerSecretsTools(mcp, opts) {
     mcp.registerTool({
         name: "detach_secret",
         scope: "secrets:write",
+        description: "Detaches a secret from an agent. `name` is the alias it was attached under; the secret's own name also works when no attachment has that alias.",
         inputSchema: {
             type: "object",
             properties: { agentId: { type: "string" }, name: { type: "string" } },
             required: ["agentId", "name"],
         },
         handler: async (args, ctx) => {
-            await requireOwnedAgent(ctx.db, args.agentId, ctx.principal.id);
-            await detachSecret(args.agentId, args.name, ctx.db);
-            return textResult({ detached: true });
+            const { agent } = await requireAgentAccess(ctx, args.agentId, "read");
+            requireBindingOwner(ctx, agent);
+            const count = await detachSecret(args.agentId, args.name, ctx.db);
+            if (count === 0) {
+                throw new McpError(404, `No secret is attached to agent "${args.agentId}" as "${args.name}".`);
+            }
+            return textResult({ detached: true, count });
         },
     });
     mcp.registerTool({

package/dist/mcp/tools/services.d.ts

@@ -0,0 +1,2 @@
+import type { WardbyMcpServer } from "../server.js";
+export declare function registerServiceTools(mcp: WardbyMcpServer): void;

package/dist/mcp/tools/services.js

@@ -0,0 +1,222 @@
+/**
+ * The coding-run service catalog over MCP (docs/coding-services.md). Reading
+ * it needs only agents:read: agent owners need to see which services exist and
+ * the variables (testEnv) their tests will get before allowing one, and entries
+ * hold no secrets (serviceEnv values are throwaway per-run test credentials).
+ * Changing it needs services:manage, a privileged scope honoured only with a
+ * role granting it (service-manager or admin; resource-server.ts): an entry
+ * decides which image runs next to every coding run that names it, and with
+ * what. Each change is audit-logged (event coding.service_catalog.<action>).
+ * Built-in entries ship with wardby and change only with a release.
+ */
+import { z } from "zod";
+import { CodingServiceDefinitionSchema, catalogEntryFromRow, codingServiceNameSchema, codingServiceVersionSchema, } from "../../coding/services/catalog.js";
+import { logger } from "../../core/logger.js";
+import { McpError } from "../errors.js";
+import { textResult } from "./text-result.js";
+const servicesLog = logger.child({ module: "mcp-services" });
+const KeySchema = z.object({ name: codingServiceNameSchema, version: codingServiceVersionSchema }).strict();
+/** Everything but the key is optional here; the merged entry is validated in full. */
+const UpdateSchema = z
+    .object({
+    name: codingServiceNameSchema,
+    version: codingServiceVersionSchema,
+    image: z.unknown().optional(),
+    port: z.unknown().optional(),
+    serviceEnv: z.unknown().optional(),
+    testEnv: z.unknown().optional(),
+    readiness: z.unknown().optional(),
+    resources: z.unknown().optional(),
+    dataPath: z.unknown().optional(),
+    writablePaths: z.unknown().optional(),
+})
+    .strict();
+function parse(schema, label, value) {
+    const result = schema.safeParse(value);
+    if (!result.success) {
+        const details = result.error.issues
+            .map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`)
+            .join("; ");
+        throw new McpError(400, `Invalid ${label}: ${details}`);
+    }
+    return result.data;
+}
+function audit(ctx, action, entry) {
+    servicesLog.info({
+        event: `coding.service_catalog.${action}`,
+        name: entry.name,
+        version: entry.version,
+        ...(entry.image ? { image: entry.image } : {}),
+        by: ctx.principal.id,
+    }, "coding service catalog changed");
+}
+async function findEntry(ctx, key) {
+    const row = await ctx.db.codingService.findUnique({ where: { name_version: key } });
+    if (!row)
+        throw new McpError(404, `No coding service "${key.name} ${key.version}" in the catalog.`);
+    return row;
+}
+function refuseBuiltin(key) {
+    return new McpError(403, `"${key.name} ${key.version}" is built in: built-in services change only with a wardby release. Create an entry under another name or version instead.`);
+}
+function view(row) {
+    return { ...catalogEntryFromRow(row), builtin: row.builtin, createdAt: row.createdAt, updatedAt: row.updatedAt };
+}
+const keyJsonSchema = {
+    name: { type: "string", description: 'Catalog name a repository declares, e.g. "postgres".' },
+    version: { type: "string", description: 'Version a repository declares, e.g. "16".' },
+};
+const definitionProperties = {
+    ...keyJsonSchema,
+    image: { type: "string", description: "Registry digest to run: repo@sha256:<64 hex>. Tags are refused." },
+    port: {
+        type: "integer",
+        minimum: 1,
+        maximum: 65535,
+        description: "The port the service listens on (informational).",
+    },
+    serviceEnv: {
+        type: "object",
+        additionalProperties: { type: "string" },
+        description: "Environment for the service container. Throwaway per-run values only, never secrets.",
+    },
+    testEnv: {
+        type: "object",
+        additionalProperties: { type: "string" },
+        description: "Variables the agent's shells receive (e.g. DATABASE_URL). Upper-case names; wardby's own names (PATH, HOME, PIP_*, WARDBY_*, ...) are refused.",
+    },
+    readiness: {
+        type: "object",
+        additionalProperties: false,
+        required: ["command", "periodSeconds", "timeoutSeconds", "failureThreshold"],
+        properties: {
+            command: { type: "array", minItems: 1, maxItems: 16, items: { type: "string" } },
+            periodSeconds: { type: "integer", minimum: 1, maximum: 60 },
+            timeoutSeconds: { type: "integer", minimum: 1, maximum: 60 },
+            failureThreshold: { type: "integer", minimum: 1, maximum: 120 },
+        },
+        description: "Startup probe: a command in the service's image that succeeds once it accepts connections on 127.0.0.1.",
+    },
+    resources: {
+        type: "object",
+        additionalProperties: false,
+        required: ["cpuMillicores", "memoryMib", "diskMib"],
+        properties: {
+            cpuMillicores: { type: "integer", minimum: 100, maximum: 4000 },
+            memoryMib: { type: "integer", minimum: 64, maximum: 16384 },
+            diskMib: { type: "integer", minimum: 64, maximum: 8192 },
+        },
+        description: "Requests equal limits. diskMib sizes the data volume.",
+    },
+    dataPath: {
+        type: "string",
+        description: "Absolute directory the service writes its data to: an empty volume in each run.",
+    },
+    writablePaths: {
+        type: "array",
+        maxItems: 4,
+        items: { type: "string" },
+        description: "Further directories the image writes to (a socket directory, /tmp); its root filesystem is read-only.",
+    },
+};
+export function registerServiceTools(mcp) {
+    mcp.registerTool({
+        name: "list_services",
+        scope: "agents:read",
+        description: "The coding-run service catalog (name, version, image, built in or not): the names a coding agent's codingProfile.services can allow.",
+        inputSchema: { type: "object", additionalProperties: false, properties: {} },
+        handler: async (_args, ctx) => {
+            const rows = await ctx.db.codingService.findMany({ orderBy: [{ name: "asc" }, { version: "asc" }] });
+            return textResult(rows.map((row) => ({
+                name: row.name,
+                version: row.version,
+                kind: row.kind,
+                image: row.image,
+                port: row.port,
+                builtin: row.builtin,
+            })));
+        },
+    });
+    mcp.registerTool({
+        name: "get_service",
+        scope: "agents:read",
+        description: "One catalog entry in full, including the variables (testEnv) a run's shells receive — the contract a repository's tests rely on.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["name", "version"],
+            properties: keyJsonSchema,
+        },
+        handler: async (rawArgs, ctx) => {
+            const key = parse(KeySchema, "get_service arguments", rawArgs);
+            return textResult(view(await findEntry(ctx, key)));
+        },
+    });
+    mcp.registerTool({
+        name: "create_service",
+        scope: "services:manage",
+        description: "Service managers (services:manage): add a catalog entry repositories can then declare in .wardby/services.yaml. The image must be pinned by digest; kind is sidecar (a fresh instance in each run's pod).",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["name", "version", "image", "port", "readiness", "resources", "dataPath"],
+            // kind is checked by the zod schema (only "sidecar" today), so a refusal names the field.
+            properties: { ...definitionProperties, kind: { type: "string", description: 'Only "sidecar" today.' } },
+        },
+        handler: async (rawArgs, ctx) => {
+            const definition = parse(CodingServiceDefinitionSchema, "create_service arguments", rawArgs);
+            const key = { name: definition.name, version: definition.version };
+            if (await ctx.db.codingService.findUnique({ where: { name_version: key } })) {
+                throw new McpError(409, `The catalog already has "${key.name} ${key.version}"; use update_service to change it.`);
+            }
+            const row = await ctx.db.codingService.create({
+                data: { ...definition, builtin: false, createdById: ctx.principal.id },
+            });
+            audit(ctx, "create", definition);
+            return textResult(view(row));
+        },
+    });
+    mcp.registerTool({
+        name: "update_service",
+        scope: "services:manage",
+        description: "Service managers (services:manage): change a non-built-in catalog entry (name and version identify it and never change). Runs already dispatched keep the entry they started with.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["name", "version"],
+            properties: definitionProperties,
+        },
+        handler: async (rawArgs, ctx) => {
+            const { name, version, ...patch } = parse(UpdateSchema, "update_service arguments", rawArgs);
+            const row = await findEntry(ctx, { name, version });
+            if (row.builtin)
+                throw refuseBuiltin({ name, version });
+            const changes = Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== undefined));
+            const next = parse(CodingServiceDefinitionSchema, "coding service", { ...catalogEntryFromRow(row), ...changes });
+            const { name: _name, version: _version, kind: _kind, ...fields } = next;
+            const updated = await ctx.db.codingService.update({ where: { name_version: { name, version } }, data: fields });
+            audit(ctx, "update", next);
+            return textResult(view(updated));
+        },
+    });
+    mcp.registerTool({
+        name: "delete_service",
+        scope: "services:manage",
+        description: "Service managers (services:manage): remove a non-built-in catalog entry. Repositories still declaring it are refused at their next run (service_unknown).",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["name", "version"],
+            properties: keyJsonSchema,
+        },
+        handler: async (rawArgs, ctx) => {
+            const key = parse(KeySchema, "delete_service arguments", rawArgs);
+            const row = await findEntry(ctx, key);
+            if (row.builtin)
+                throw refuseBuiltin(key);
+            await ctx.db.codingService.delete({ where: { name_version: key } });
+            audit(ctx, "delete", key);
+            return textResult({ deleted: key });
+        },
+    });
+}