src/tools/namespaces.ts

Functions

Imports

It imports src/agents-schema.ts, src/github.ts, src/limits.ts, src/namespace-delete.ts, src/scope.ts, src/store-guards.ts, src/tools/docs.ts, src/tools/surface.ts. Imported by src/tools/docs.ts.

Source

1import { McpServer } from "@modelcontextprotocol/server";
2import { z } from "zod";
3import { IMPROVE_OVERRIDE_FLAGS } from "../scope";
4import { surfaceOf } from "./surface";
5import { NAMESPACE_DELETE_MAX_DOCUMENTS, performNamespaceDelete, previewNamespaceDelete } from "../namespace-delete";
6import { parseReposList, REPO_SHAPE, requireSinglePrimary } from "../github";
7import { auditStatement } from "../store-guards";
8import { driverMintInstruction } from "../agents-schema";
9import { bounded, MAX_CONFIRM_TOKEN, MAX_REPO_SELECTOR, MAX_REPOS_JSON, nsName } from "../limits";
10import { ok, fail, type ToolCtx } from "./docs";
11
12// The namespace operations: namespaces (capsid_find_docs action namespaces), and
13// register_namespace, update_namespace and delete_namespace (capsid_admin_manage_namespaces
14// actions register, update, delete_preview and delete_perform).
15// defineDocOperations in ./docs registers them after the document tools.
16
17export function defineNamespaceOperations(server: McpServer, ctx: ToolCtx): void {
18  const { env, db, actor } = ctx;
19
20  ctx.ops.define(
21    "namespaces",
22    {
23      description:
24        "List the namespaces this caller is scoped to and the repos each maps to. A scoped agent sees only its own namespaces.",
25      inputSchema: {},
26    },
27    async () => {
28      // unconsolidated = episodic and source docs not yet archived by the lint loop,
29      // surfaced so every session sees which namespaces need a run. Not filtered on
30      // status: the archive/ prefix is the only thing that takes a doc out of the loop.
31      const { results } = await db
32        .prepare(
33          `SELECT n.namespace, n.repos, n.created_at,
34                  (SELECT COUNT(*) FROM documents d
35                   WHERE d.namespace = n.namespace AND d.type IN ('episodic', 'source')
36                     AND d.path NOT LIKE 'archive/%') AS unconsolidated
37           FROM namespaces n ORDER BY n.namespace`
38        )
39        .all();
40      // Filtered to the caller's own namespaces. This tool takes no arguments, so
41      // namespaceRefusal at the registrar has nothing to fire on. The mapping is what
42      // scripts/mint-agents.ts uses to set the repos axis and what resolveRepo
43      // resolves through, so handing it to a narrowed caller hands it the shape of the
44      // boundary it sits behind.
45      const scoped = ctx.agent.scopes.namespaces;
46      const visible = scoped === "*" ? results : results.filter((row) => scoped.includes(String((row as { namespace: string }).namespace)));
47      return ok(visible);
48    }
49  );
50
51  // Register a namespace: the one row in the namespaces table that repo tools and the
52  // namespaces list read. Writing documents to a new namespace label does not create
53  // it. Create-only: it will not overwrite an existing mapping. Admin only (TOOL_GRANTS in src/scope.ts): an OAuth
54  // session qualifies, a minted agent holding the write grant does not.
55  ctx.ops.define(
56    "register_namespace",
57    {
58      description:
59        "Register a namespace in the namespaces table. Give repo as 'owner/name' (label defaults to 'primary'), or pass a repos JSON array like [{\"repo\":\"owner/name\",\"label\":\"primary\"}] for a multi-repo namespace. Refused if the namespace exists. Admin only: an OAuth session qualifies, a minted agent holding the write grant does not.",
60      inputSchema: {
61        namespace: nsName,
62        repo: bounded(MAX_REPO_SELECTOR).optional(),
63        label: bounded(MAX_REPO_SELECTOR).optional(),
64        repos: bounded(MAX_REPOS_JSON).optional(),
65      },
66    },
67    async ({ namespace, repo, label, repos }) => {
68      const ns = namespace.trim();
69      if (!ns) return fail("namespace is required");
70      let list: Array<{ repo: string; label: string }>;
71      if (repos) {
72        const parsed = parseReposList(repos);
73        if ("error" in parsed) return fail(parsed.error);
74        list = parsed.list;
75      } else {
76        if (!repo || !REPO_SHAPE.test(repo)) {
77          return fail('provide repo as "owner/name", or pass a repos JSON array');
78        }
79        list = [{ repo, label: (label ?? "primary").trim() || "primary" }];
80      }
81      // The same single-primary requirement as update_namespace. Two primaries or none
82      // would make every repo tool resolve by accident, and update would refuse to fix
83      // it in place.
84      const primaryError = requireSinglePrimary(list);
85      if (primaryError) return fail(primaryError);
86      const existing = await db.prepare("SELECT namespace FROM namespaces WHERE namespace = ?1").bind(ns).first();
87      if (existing) {
88        return fail(`namespace already registered: ${ns}. Use capsid_admin_manage_namespaces action update to change its repo mapping; it snapshots the prior mapping to the audit log.`);
89      }
90      const reposJson = JSON.stringify(list);
91      await db.batch([
92        db.prepare("INSERT INTO namespaces (namespace, repos) VALUES (?1, ?2)").bind(ns, reposJson),
93        auditStatement(db, actor, "register_namespace", ns, null, list),
94      ]);
95      return ok({
96        namespace: ns,
97        repos: list,
98        action: "registered",
99        driver_agent: null,
100        next: driverMintInstruction(ns),
101      });
102    }
103  );
104
105  // Remap an existing namespace's repos; register_namespace is the create path.
106  // Snapshots the prior mapping to the audit log. It does not rename the namespace: a
107  // rename touches document keys, versions and audit history.
108  ctx.ops.define(
109    "update_namespace",
110    {
111      description:
112        "Remap an existing namespace's repos. Pass repos as a JSON array like [{\"repo\":\"owner/name\",\"label\":\"primary\"},{\"repo\":\"owner/legacy\",\"label\":\"legacy\"}], with exactly one entry labeled \"primary\". The namespace must exist. Records the prior mapping in the audit log. Does not rename the namespace or move its documents. Admin only: an OAuth session qualifies, a minted agent holding the write grant does not.",
113      inputSchema: { namespace: nsName, repos: bounded(MAX_REPOS_JSON) },
114    },
115    async ({ namespace, repos }) => {
116      const ns = namespace.trim();
117      if (!ns) return fail("namespace is required");
118      const parsed = parseReposList(repos);
119      if ("error" in parsed) return fail(parsed.error);
120      const list = parsed.list;
121      const primaryError = requireSinglePrimary(list);
122      if (primaryError) return fail(primaryError);
123      const existing = await db
124        .prepare("SELECT repos FROM namespaces WHERE namespace = ?1")
125        .bind(ns)
126        .first<{ repos: string }>();
127      if (!existing) return fail(`namespace not found: ${ns}. Use capsid_admin_manage_namespaces action register to create it.`);
128      const reposJson = JSON.stringify(list);
129      await db.batch([
130        db.prepare("UPDATE namespaces SET repos = ?2 WHERE namespace = ?1").bind(ns, reposJson),
131        auditStatement(db, actor, "update_namespace", ns, null, { old: existing.repos, new: reposJson }),
132      ]);
133      return ok({ namespace: ns, repos: list, action: "updated", previous: existing.repos });
134    }
135  );
136  // Delete a namespace: a preview that counts everything naming it and signs a token,
137  // then a perform that re-plans, requires the token to match and commits one guarded
138  // batch. The rules and what is kept are in src/namespace-delete.ts. Admin only
139  // (TOOL_GRANTS in src/scope.ts), like the other two tools that edit the mapping.
140  ctx.ops.define(
141    "delete_namespace",
142    {
143      description:
144        `Delete a registered namespace. Two calls. action 'delete_preview' writes nothing: it counts every live and archived document, snapshot, edge, job by status, agent naming the namespace, and the ops_sites row, and returns a verdict. It is refused while any job in the namespace is open (queued, claimed or blocked) or any live agent names it in its scopes (cascade never reaches jobs or agents; end them with capsid_work_jobs or capsid_admin_manage_agents), while it is on the roster, while live documents exist and cascade is not true, while it holds signed policy documents (policy/) and allow_improve_paths is not true, and while it holds more live documents than one batch deletes (${NAMESPACE_DELETE_MAX_DOCUMENTS}; delete some with capsid_delete_doc or move them with capsid_write_doc action move first). An allowed preview returns a token bound to the namespace, cascade, allow_improve_paths, the counts and this caller, valid five minutes. action 'delete_perform' takes the same arguments and that token, re-reads the plan and refuses if anything counted changed, then in one batch snapshots every live document to document_versions and deletes it with the edges touching it, deletes the ops_sites row and the namespaces row, and writes one audit row 'namespace-delete' holding the edges and both rows whole. Archived documents, versions, the audit log, finished jobs and their records are kept. Admin only: an OAuth session qualifies, a minted agent holding the write grant does not.`,
145      inputSchema: {
146        namespace: nsName,
147        action: z.enum(["preview", "perform"]),
148        cascade: z.boolean().optional(),
149        allow_improve_paths: z.boolean().optional(),
150        token: bounded(MAX_CONFIRM_TOKEN).optional(),
151      },
152    },
153    async ({ namespace, action, cascade, allow_improve_paths, token }) => {
154      const ns = namespace.trim();
155      if (!ns) return fail("namespace is required");
156      const opts = { cascade: cascade === true, allowImprovePaths: allow_improve_paths === true };
157      // The policy override is scoped as it is on a document delete: the flag is the
158      // permission, the argument only the caller's intent.
159      if (opts.allowImprovePaths) {
160        const overrideRefusal = ctx.scope({ ...surfaceOf("delete_namespace", "perform"), namespace: ns, flags: IMPROVE_OVERRIDE_FLAGS });
161        if (overrideRefusal) return fail(overrideRefusal);
162      }
163      const now = new Date();
164      const answer =
165        action === "preview"
166          ? await previewNamespaceDelete(env, actor, ns, opts, now)
167          : await performNamespaceDelete(env, actor, ns, opts, token, now);
168      return answer.ok ? ok(answer.data) : fail(answer.refusal);
169    }
170  );
171}