@orthacms/tools-server 0.0.0-reserve.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ortha CMS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @orthacms/tools-server
+
+Part of [Ortha CMS](https://github.com/ortha-source/ortha-cms).
+
+```sh
+npm install @orthacms/tools-server
+```

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Public API of `@orthacms/tools-server` — the shared, transport-neutral
+ * catalogue of everything an agent can do to this CMS, and the single place a
+ * tool call is authorized.
+ *
+ * It lives in its own package rather than inside `mcp/server` (where
+ * [ADR-0006](../../../docs/adr/0006-cms-as-an-mcp-server.md) §2 first put it)
+ * because MCP turned out to be one consumer of two, not the owner: the
+ * copilot's in-process tool loop injects the same registry. Importing it from
+ * the MCP package would have made a deployment that wants only the copilot pull
+ * `@modelcontextprotocol/sdk` through that package's barrel — a dependency on a
+ * protocol it does not speak.
+ */
+export { ToolRegistry } from './lib/tool-registry';
+export { ToolsModule } from './lib/tools.module';
+export type { ToolProvider } from './lib/tool-provider';
+export type { JsonSchema, ResourceContents, ResourceDefinition, ToolActor, ToolActorKind, ToolContext, ToolDefinition, ToolEffect, ToolOutput, ToolSurface } from './lib/tool';
+export { createToolContext } from './lib/tool-context';
+export { toToolError } from './lib/tool-error';
+export type { ToolError } from './lib/tool-error';
+export { validateToolInput } from './lib/validate-tool-input';
+export type { ToolInputValidation } from './lib/validate-tool-input';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EACR,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,SAAS,EACT,aAAa,EACb,WAAW,EACX,cAAc,EACd,UAAU,EACV,UAAU,EACV,WAAW,EACd,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAMlD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,YAAY,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Public API of `@orthacms/tools-server` — the shared, transport-neutral
+ * catalogue of everything an agent can do to this CMS, and the single place a
+ * tool call is authorized.
+ *
+ * It lives in its own package rather than inside `mcp/server` (where
+ * [ADR-0006](../../../docs/adr/0006-cms-as-an-mcp-server.md) §2 first put it)
+ * because MCP turned out to be one consumer of two, not the owner: the
+ * copilot's in-process tool loop injects the same registry. Importing it from
+ * the MCP package would have made a deployment that wants only the copilot pull
+ * `@modelcontextprotocol/sdk` through that package's barrel — a dependency on a
+ * protocol it does not speak.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateToolInput = exports.toToolError = exports.createToolContext = exports.ToolsModule = exports.ToolRegistry = void 0;
+var tool_registry_1 = require("./lib/tool-registry");
+Object.defineProperty(exports, "ToolRegistry", { enumerable: true, get: function () { return tool_registry_1.ToolRegistry; } });
+// The module that provides it. Imported by each consumer (MCP, copilot) rather
+// than provided by either — see its JSDoc.
+var tools_module_1 = require("./lib/tools.module");
+Object.defineProperty(exports, "ToolsModule", { enumerable: true, get: function () { return tools_module_1.ToolsModule; } });
+// Building a context is exported because neither consumer owns it: the MCP
+// endpoint builds one for a bearer token, the copilot for the signed-in user.
+var tool_context_1 = require("./lib/tool-context");
+Object.defineProperty(exports, "createToolContext", { enumerable: true, get: function () { return tool_context_1.createToolContext; } });
+var tool_error_1 = require("./lib/tool-error");
+Object.defineProperty(exports, "toToolError", { enumerable: true, get: function () { return tool_error_1.toToolError; } });
+// The argument check `ToolRegistry.call` applies before dispatch. Exported
+// because a consumer may want to reject a malformed call earlier than the
+// registry does — the copilot's run engine validates at the point it decides
+// what to tell the model, so the run continues instead of throwing.
+var validate_tool_input_1 = require("./lib/validate-tool-input");
+Object.defineProperty(exports, "validateToolInput", { enumerable: true, get: function () { return validate_tool_input_1.validateToolInput; } });

package/dist/lib/tool-context.d.ts

@@ -0,0 +1,16 @@
+import type { ToolActor, ToolContext } from './tool';
+/**
+ * Build a {@link ToolContext} from an already-resolved actor and workspace.
+ *
+ * Exported because the MCP endpoint is not the only thing that builds one: the
+ * copilot's tool loop runs as the **signed-in user**, resolves that user's role
+ * grants through identity's RBAC service, and calls the same registry. Sharing
+ * the constructor keeps `can()` meaning one thing.
+ *
+ * Note what this function does **not** do: it never derives permissions. The
+ * caller resolves them (a token's scope via `scopePermissions`, a user's via
+ * their role) and hands them over. Authorization inputs are decided once, at
+ * the edge, by the code that authenticated the caller.
+ */
+export declare function createToolContext(actor: ToolActor, workspaceId: string): ToolContext;
+//# sourceMappingURL=tool-context.d.ts.map

package/dist/lib/tool-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-context.d.ts","sourceRoot":"","sources":["../../src/lib/tool-context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC7B,KAAK,EAAE,SAAS,EAChB,WAAW,EAAE,MAAM,GACpB,WAAW,CAOb"}

package/dist/lib/tool-context.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createToolContext = createToolContext;
+/**
+ * Build a {@link ToolContext} from an already-resolved actor and workspace.
+ *
+ * Exported because the MCP endpoint is not the only thing that builds one: the
+ * copilot's tool loop runs as the **signed-in user**, resolves that user's role
+ * grants through identity's RBAC service, and calls the same registry. Sharing
+ * the constructor keeps `can()` meaning one thing.
+ *
+ * Note what this function does **not** do: it never derives permissions. The
+ * caller resolves them (a token's scope via `scopePermissions`, a user's via
+ * their role) and hands them over. Authorization inputs are decided once, at
+ * the edge, by the code that authenticated the caller.
+ */
+function createToolContext(actor, workspaceId) {
+    return {
+        actor,
+        workspaceId,
+        can: (permission) => actor.grantedPermissions.has(permission)
+    };
+}

package/dist/lib/tool-error.d.ts

@@ -0,0 +1,28 @@
+/** A tool failure, flattened into something a model can read and act on. */
+export interface ToolError {
+    /** HTTP-ish status the underlying operation failed with. */
+    status: number;
+    /** A short machine label, e.g. `not_found`, `validation_failed`. */
+    code: string;
+    /** Human/model-readable explanation. */
+    message: string;
+    /** Per-field issues, when the failure was a validation one. */
+    issues?: unknown;
+}
+/**
+ * Turn whatever a tool handler threw into a {@link ToolError}.
+ *
+ * Tool handlers delegate to the very same services the HTTP controllers call,
+ * so they throw Nest `HttpException`s — a 404 for an unknown entry, a 422
+ * carrying per-field validation issues. Those are **the most useful thing a
+ * model can be told**: "title must be at most 200 characters" is a failure it
+ * can fix on the next call, so the issues are carried through verbatim rather
+ * than flattened to "bad request".
+ *
+ * Anything that is *not* an `HttpException` is a bug, not a caller error. It is
+ * logged with its stack for the operator and reported as a bare 500 — the
+ * message could name a table, a column, or a connection string, and a tool
+ * result is read by a third-party model.
+ */
+export declare function toToolError(error: unknown): ToolError;
+//# sourceMappingURL=tool-error.d.ts.map

package/dist/lib/tool-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-error.d.ts","sourceRoot":"","sources":["../../src/lib/tool-error.ts"],"names":[],"mappings":"AAEA,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACtB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB;AAcD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAoCrD"}

package/dist/lib/tool-error.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toToolError = toToolError;
+const common_1 = require("@nestjs/common");
+/** Status → the short code a model sees. */
+const CODES = {
+    [common_1.HttpStatus.BAD_REQUEST]: 'bad_request',
+    [common_1.HttpStatus.UNAUTHORIZED]: 'unauthorized',
+    [common_1.HttpStatus.FORBIDDEN]: 'forbidden',
+    [common_1.HttpStatus.NOT_FOUND]: 'not_found',
+    [common_1.HttpStatus.CONFLICT]: 'conflict',
+    [common_1.HttpStatus.UNPROCESSABLE_ENTITY]: 'validation_failed'
+};
+const logger = new common_1.Logger('McpTools');
+/**
+ * Turn whatever a tool handler threw into a {@link ToolError}.
+ *
+ * Tool handlers delegate to the very same services the HTTP controllers call,
+ * so they throw Nest `HttpException`s — a 404 for an unknown entry, a 422
+ * carrying per-field validation issues. Those are **the most useful thing a
+ * model can be told**: "title must be at most 200 characters" is a failure it
+ * can fix on the next call, so the issues are carried through verbatim rather
+ * than flattened to "bad request".
+ *
+ * Anything that is *not* an `HttpException` is a bug, not a caller error. It is
+ * logged with its stack for the operator and reported as a bare 500 — the
+ * message could name a table, a column, or a connection string, and a tool
+ * result is read by a third-party model.
+ */
+function toToolError(error) {
+    if (error instanceof common_1.HttpException) {
+        const status = error.getStatus();
+        const response = error.getResponse();
+        const body = typeof response === 'object' && response !== null
+            ? response
+            : {};
+        const message = typeof body['message'] === 'string'
+            ? body['message']
+            : Array.isArray(body['message'])
+                ? body['message'].join('; ')
+                : error.message;
+        // `issues` is what the content plugin's 422 carries per field; keeping
+        // the key intact is what makes a validation failure self-correcting.
+        const issues = body['issues'];
+        return {
+            status,
+            code: CODES[status] ?? 'error',
+            message,
+            ...(issues === undefined ? {} : { issues })
+        };
+    }
+    logger.error(`Unhandled error in a tool handler: ${error instanceof Error ? error.message : String(error)}`, error instanceof Error ? error.stack : undefined);
+    return {
+        status: common_1.HttpStatus.INTERNAL_SERVER_ERROR,
+        code: 'internal_error',
+        message: 'The tool failed unexpectedly. See the server logs.'
+    };
+}

package/dist/lib/tool-provider.d.ts

@@ -0,0 +1,40 @@
+import type { ResourceContents, ResourceDefinition, ToolContext, ToolDefinition } from './tool';
+/**
+ * A plugin's contribution of tools (and optionally resources) to the shared
+ * {@link ToolRegistry}.
+ *
+ * The **inversion** that keeps the package graph acyclic and this package free
+ * of domain knowledge: `mcp/server` owns the protocol and knows nothing about
+ * content, media, or users; each capability plugin implements this and
+ * registers itself. `content/server` binds the first one. A plugin's tools can
+ * therefore reach straight into its own internals — `PublicEntriesQuery`,
+ * `PublicEntryWritesService` — instead of those having to be re-exported for an
+ * outside package to drive, which is precisely how a second, drifting copy of
+ * the visibility rules would get written.
+ *
+ * Registration is a **call**, not a DI multi-binding, because Nest has no
+ * multi-provider token: a contributor injects the registry `@Optional()` and
+ * registers itself in `onModuleInit`. Optional because MCP is a plugin — a
+ * deployment that leaves it out must still boot, with its capability plugins
+ * simply contributing nothing.
+ */
+export interface ToolProvider {
+    /**
+     * The tools this plugin contributes. Called once per `tools/list`, so it
+     * may vary with runtime state (the content registry's types), but must not
+     * be expensive or do I/O — permission filtering happens after it returns.
+     */
+    tools(): readonly ToolDefinition[];
+    /**
+     * Resources this plugin exposes to the calling actor, if any. Async and
+     * context-taking because visibility is per-workspace: a content type the
+     * workspace was not granted must not be listed.
+     */
+    resources?(context: ToolContext): Promise<readonly ResourceDefinition[]>;
+    /**
+     * Read one of this plugin's resources. Return `undefined` for a URI this
+     * provider does not own, so the registry can try the next one.
+     */
+    readResource?(uri: string, context: ToolContext): Promise<ResourceContents | undefined>;
+}
+//# sourceMappingURL=tool-provider.d.ts.map

package/dist/lib/tool-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-provider.d.ts","sourceRoot":"","sources":["../../src/lib/tool-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,cAAc,EACjB,MAAM,QAAQ,CAAC;AAEhB;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,YAAY;IACzB;;;;OAIG;IACH,KAAK,IAAI,SAAS,cAAc,EAAE,CAAC;IAEnC;;;;OAIG;IACH,SAAS,CAAC,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,kBAAkB,EAAE,CAAC,CAAC;IAEzE;;;OAGG;IACH,YAAY,CAAC,CACT,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,WAAW,GACrB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC;CAC5C"}

package/dist/lib/tool-provider.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/tool-registry.d.ts

@@ -0,0 +1,137 @@
+import { type OnApplicationBootstrap } from '@nestjs/common';
+import type { ResourceContents, ResourceDefinition, ToolContext, ToolDefinition, ToolOutput, ToolSurface } from './tool';
+import type { ToolProvider } from './tool-provider';
+/**
+ * The shared, transport-neutral catalogue of everything an agent can do to this
+ * CMS — and the **single place** a tool call is authorized.
+ *
+ * Two consumers, one registry: the MCP endpoint exposes it to external clients
+ * (Claude Desktop, Cursor, an agent framework), and the copilot's in-process
+ * tool loop will inject the very same instance. That is the whole reason
+ * nothing on {@link ToolDefinition} or {@link ToolContext} mentions HTTP or
+ * JSON-RPC — a tool added for one consumer is automatically available to the
+ * other, and neither can end up with a private set of rules.
+ *
+ * **The authorization invariant.** `call()` checks `requires` before dispatch,
+ * and `visibleTo()` merely *hides* what the actor could not call anyway.
+ * Filtering a list is a usability nicety; the check in `call()` is the security
+ * boundary, and it must stay that way — an MCP client is free to invoke a tool
+ * name it was never shown, and the copilot may hallucinate one outright.
+ */
+export declare class ToolRegistry implements OnApplicationBootstrap {
+    private readonly providers;
+    /**
+     * Add a provider's contributions. Called by each capability plugin from
+     * `onModuleInit`; see {@link ToolProvider} for why this is a call rather
+     * than a DI multi-binding.
+     *
+     * **Idempotent per provider instance.** Registration is a call, so nothing
+     * stops a plugin making it twice — an `onModuleInit` that also runs on a
+     * re-created testing module, a provider bound in two modules. Pushing the
+     * same instance twice would make every one of its tools collide with
+     * itself and take the *whole* catalogue down, on both surfaces, for a
+     * mistake that changes nothing. Registering the same provider again is
+     * therefore a no-op; two *different* providers claiming one name is still
+     * the wiring bug {@link onApplicationBootstrap} refuses to boot with.
+     */
+    register(provider: ToolProvider): void;
+    /**
+     * Validate the assembled catalogue **once, at boot**.
+     *
+     * Every problem below used to surface at the first `tools/list` or
+     * `tools/call` instead — a duplicate name took both surfaces down at
+     * runtime while boot reported success, and a tool whose `requires` names a
+     * permission no role grants (a raw string literal gone stale, a stray
+     * space) simply became invisible and uncallable with nothing said. Both are
+     * wiring bugs, and a wiring bug belongs to the deploy, not to the first
+     * caller unlucky enough to hit it.
+     *
+     * `OnApplicationBootstrap` rather than `register()` because every
+     * capability plugin registers from `onModuleInit`, and a provider's
+     * `tools()` may depend on state (the content-type registry) that is only
+     * complete once every module has initialized. Throwing here aborts
+     * `app.init()`, so the process never starts serving.
+     */
+    onApplicationBootstrap(): void;
+    /**
+     * Every registered tool, in registration order.
+     *
+     * A duplicate name is a **wiring bug** — two plugins claiming one tool name
+     * would make which implementation runs depend on registration order — so it
+     * fails loudly here rather than resolving silently. This is the backstop:
+     * {@link onApplicationBootstrap} refuses to boot with one, so the only way
+     * to reach this throw is a provider whose `tools()` starts colliding after
+     * boot.
+     */
+    all(): readonly ToolDefinition[];
+    /**
+     * Every tool offered to one **surface** — the MCP endpoint or the copilot.
+     *
+     * A tool that names no surfaces is offered to both, so this narrows only
+     * the ones that declared a reason to be narrowed (see {@link ToolSurface}).
+     */
+    forSurface(surface: ToolSurface): readonly ToolDefinition[];
+    /**
+     * The tools `context`'s actor holds the permissions for, on one surface.
+     * What a client is shown — a read-only token never learns that
+     * `content_create` exists, which is a far better experience than
+     * discovering it via a refusal, and keeps a model from burning turns on
+     * calls that cannot succeed.
+     */
+    visibleTo(context: ToolContext, surface: ToolSurface): readonly ToolDefinition[];
+    /**
+     * Authorize, validate and run one tool.
+     *
+     * An unknown name and a name the actor may not call are deliberately
+     * **different** answers: the tool set is not secret (it is the same for
+     * every actor of a given scope, and documented), so conflating them would
+     * only make a legitimate permission problem undiagnosable. What is never
+     * revealed is *data* — that distinction lives in the handlers, where an
+     * ungranted content type 404s exactly like an unknown one.
+     *
+     * Arguments are checked against the tool's own `inputSchema` before
+     * dispatch (see {@link validateToolInput} for the subset that covers, and
+     * the keywords it deliberately ignores). It is not a security boundary —
+     * `requires` is — but it is what keeps a caller's malformed arguments from
+     * reaching a handler and coming back as an opaque 500 instead of a
+     * `validation_failed` naming the field.
+     */
+    call(name: string, input: Record<string, unknown> | undefined, context: ToolContext, surface: ToolSurface): Promise<ToolOutput>;
+    /**
+     * Every resource visible to the actor, across providers — permission
+     * filtered, exactly as {@link visibleTo} filters tools.
+     */
+    resources(context: ToolContext): Promise<readonly ResourceDefinition[]>;
+    /**
+     * Read one resource. Providers are asked in registration order and the
+     * first that claims the URI wins; nobody claiming it is a 404.
+     *
+     * A declared resource's `requires` is checked **here, before any provider
+     * is asked for the bytes** — the same rule as {@link call}, for the same
+     * reason: `resources()` hiding a resource is a listing nicety, and a client
+     * is free to read a URI it was never shown. The extra enumeration is the
+     * price of the gate; `resources/read` is not a hot path, and a provider
+     * that declares no resources costs nothing.
+     */
+    readResource(uri: string, context: ToolContext): Promise<ResourceContents>;
+    /** Every resource every provider declares, before permission filtering. */
+    private declaredResources;
+    /** Whether the actor holds every permission the tool requires. */
+    private permits;
+    /**
+     * Whether the actor holds every permission the resource requires. A
+     * resource that declares none is readable by anyone who reached the
+     * endpoint, which is what every shipped resource means today.
+     */
+    private permitsResource;
+    /**
+     * Everything wrong with the registered catalogue, as human sentences.
+     *
+     * Reported all at once rather than throwing on the first, so a deploy that
+     * broke two things learns about both.
+     */
+    private catalogueProblems;
+    /** Everything wrong with one tool definition. */
+    private toolProblems;
+}
+//# sourceMappingURL=tool-registry.d.ts.map

package/dist/lib/tool-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../src/lib/tool-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAKH,KAAK,sBAAsB,EAC9B,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EACR,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,cAAc,EACd,UAAU,EACV,WAAW,EACd,MAAM,QAAQ,CAAC;AAChB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAgCpD;;;;;;;;;;;;;;;;GAgBG;AACH,qBACa,YAAa,YAAW,sBAAsB;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAEhD;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;IAOtC;;;;;;;;;;;;;;;;OAgBG;IACH,sBAAsB,IAAI,IAAI;IAW9B;;;;;;;;;OASG;IACH,GAAG,IAAI,SAAS,cAAc,EAAE;IAiBhC;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,cAAc,EAAE;IAM3D;;;;;;OAMG;IACH,SAAS,CACL,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,WAAW,GACrB,SAAS,cAAc,EAAE;IAM5B;;;;;;;;;;;;;;;;OAgBG;IACG,IAAI,CACN,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC1C,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,WAAW,GACrB,OAAO,CAAC,UAAU,CAAC;IA0CtB;;;OAGG;IACG,SAAS,CACX,OAAO,EAAE,WAAW,GACrB,OAAO,CAAC,SAAS,kBAAkB,EAAE,CAAC;IAMzC;;;;;;;;;;OAUG;IACG,YAAY,CACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,WAAW,GACrB,OAAO,CAAC,gBAAgB,CAAC;IAsB5B,2EAA2E;YAC7D,iBAAiB;IAW/B,kEAAkE;IAClE,OAAO,CAAC,OAAO;IAIf;;;;OAIG;IACH,OAAO,CAAC,eAAe;IASvB;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAiBzB,iDAAiD;IACjD,OAAO,CAAC,YAAY;CAyCvB"}

package/dist/lib/tool-registry.js

@@ -0,0 +1,290 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolRegistry = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const identity_server_1 = require("@orthacms/identity-server");
+const validate_tool_input_1 = require("./validate-tool-input");
+/**
+ * The shape a tool name must have — `snake_case`, lowercase, no leading,
+ * trailing or doubled underscores. Checked at boot rather than trusted, because
+ * every deviation is silent: a padded name registers and is callable only by
+ * sending the padding back, and `Content_List` next to `content_list` is two
+ * live tools one letter apart.
+ */
+const TOOL_NAME_PATTERN = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
+/** The permission keys this deployment actually defines. */
+const KNOWN_PERMISSIONS = new Set(identity_server_1.PERMISSION_KEYS);
+/** A non-null, non-array object. */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Split one `path: message` validation error into the per-field shape the rest
+ * of the API's 422s carry, so a model reads a registry refusal exactly as it
+ * reads a content plugin's.
+ */
+function toIssue(error) {
+    const at = error.indexOf(': ');
+    return at === -1
+        ? { field: 'input', message: error }
+        : { field: error.slice(0, at), message: error.slice(at + 2) };
+}
+/**
+ * The shared, transport-neutral catalogue of everything an agent can do to this
+ * CMS — and the **single place** a tool call is authorized.
+ *
+ * Two consumers, one registry: the MCP endpoint exposes it to external clients
+ * (Claude Desktop, Cursor, an agent framework), and the copilot's in-process
+ * tool loop will inject the very same instance. That is the whole reason
+ * nothing on {@link ToolDefinition} or {@link ToolContext} mentions HTTP or
+ * JSON-RPC — a tool added for one consumer is automatically available to the
+ * other, and neither can end up with a private set of rules.
+ *
+ * **The authorization invariant.** `call()` checks `requires` before dispatch,
+ * and `visibleTo()` merely *hides* what the actor could not call anyway.
+ * Filtering a list is a usability nicety; the check in `call()` is the security
+ * boundary, and it must stay that way — an MCP client is free to invoke a tool
+ * name it was never shown, and the copilot may hallucinate one outright.
+ */
+let ToolRegistry = class ToolRegistry {
+    providers = [];
+    /**
+     * Add a provider's contributions. Called by each capability plugin from
+     * `onModuleInit`; see {@link ToolProvider} for why this is a call rather
+     * than a DI multi-binding.
+     *
+     * **Idempotent per provider instance.** Registration is a call, so nothing
+     * stops a plugin making it twice — an `onModuleInit` that also runs on a
+     * re-created testing module, a provider bound in two modules. Pushing the
+     * same instance twice would make every one of its tools collide with
+     * itself and take the *whole* catalogue down, on both surfaces, for a
+     * mistake that changes nothing. Registering the same provider again is
+     * therefore a no-op; two *different* providers claiming one name is still
+     * the wiring bug {@link onApplicationBootstrap} refuses to boot with.
+     */
+    register(provider) {
+        if (this.providers.includes(provider)) {
+            return;
+        }
+        this.providers.push(provider);
+    }
+    /**
+     * Validate the assembled catalogue **once, at boot**.
+     *
+     * Every problem below used to surface at the first `tools/list` or
+     * `tools/call` instead — a duplicate name took both surfaces down at
+     * runtime while boot reported success, and a tool whose `requires` names a
+     * permission no role grants (a raw string literal gone stale, a stray
+     * space) simply became invisible and uncallable with nothing said. Both are
+     * wiring bugs, and a wiring bug belongs to the deploy, not to the first
+     * caller unlucky enough to hit it.
+     *
+     * `OnApplicationBootstrap` rather than `register()` because every
+     * capability plugin registers from `onModuleInit`, and a provider's
+     * `tools()` may depend on state (the content-type registry) that is only
+     * complete once every module has initialized. Throwing here aborts
+     * `app.init()`, so the process never starts serving.
+     */
+    onApplicationBootstrap() {
+        const problems = this.catalogueProblems();
+        if (problems.length > 0) {
+            throw new Error(`The agent tool catalogue is invalid:\n- ${problems.join('\n- ')}`);
+        }
+    }
+    /**
+     * Every registered tool, in registration order.
+     *
+     * A duplicate name is a **wiring bug** — two plugins claiming one tool name
+     * would make which implementation runs depend on registration order — so it
+     * fails loudly here rather than resolving silently. This is the backstop:
+     * {@link onApplicationBootstrap} refuses to boot with one, so the only way
+     * to reach this throw is a provider whose `tools()` starts colliding after
+     * boot.
+     */
+    all() {
+        const tools = [];
+        const seen = new Set();
+        for (const provider of this.providers) {
+            for (const tool of provider.tools()) {
+                if (seen.has(tool.name)) {
+                    throw new Error(`Duplicate tool name "${tool.name}" — two providers registered it. Tool names must be unique across plugins.`);
+                }
+                seen.add(tool.name);
+                tools.push(tool);
+            }
+        }
+        return tools;
+    }
+    /**
+     * Every tool offered to one **surface** — the MCP endpoint or the copilot.
+     *
+     * A tool that names no surfaces is offered to both, so this narrows only
+     * the ones that declared a reason to be narrowed (see {@link ToolSurface}).
+     */
+    forSurface(surface) {
+        return this.all().filter((tool) => !tool.surfaces || tool.surfaces.includes(surface));
+    }
+    /**
+     * The tools `context`'s actor holds the permissions for, on one surface.
+     * What a client is shown — a read-only token never learns that
+     * `content_create` exists, which is a far better experience than
+     * discovering it via a refusal, and keeps a model from burning turns on
+     * calls that cannot succeed.
+     */
+    visibleTo(context, surface) {
+        return this.forSurface(surface).filter((tool) => this.permits(tool, context));
+    }
+    /**
+     * Authorize, validate and run one tool.
+     *
+     * An unknown name and a name the actor may not call are deliberately
+     * **different** answers: the tool set is not secret (it is the same for
+     * every actor of a given scope, and documented), so conflating them would
+     * only make a legitimate permission problem undiagnosable. What is never
+     * revealed is *data* — that distinction lives in the handlers, where an
+     * ungranted content type 404s exactly like an unknown one.
+     *
+     * Arguments are checked against the tool's own `inputSchema` before
+     * dispatch (see {@link validateToolInput} for the subset that covers, and
+     * the keywords it deliberately ignores). It is not a security boundary —
+     * `requires` is — but it is what keeps a caller's malformed arguments from
+     * reaching a handler and coming back as an opaque 500 instead of a
+     * `validation_failed` naming the field.
+     */
+    async call(name, input, context, surface) {
+        // Scoped to the surface, so a caller cannot invoke a tool the *other*
+        // consumer's rules were written for — an MCP client naming
+        // `content_propose_edit` gets "unknown tool", not a proposal it has no
+        // way to accept.
+        const tool = this.forSurface(surface).find((candidate) => candidate.name === name);
+        if (!tool) {
+            throw new common_1.NotFoundException(`Unknown tool "${name}".`);
+        }
+        if (!this.permits(tool, context)) {
+            throw new common_1.ForbiddenException(`"${name}" requires ${tool.requires.join(', ')}, which this ${context.actor.kind === 'token' ? 'token' : 'user'} does not hold.`);
+        }
+        // Defaulted here rather than at each edge. Both shipped consumers
+        // already compensate for a missing arguments object (`args ?? {}` in
+        // the MCP adapter, `call.input ?? {}` in the run engine) — for a
+        // parameter this signature types as an object, that is a defence the
+        // registry owes them, not one each has to remember.
+        const args = input ?? {};
+        // Authorization first, validation second: a caller who may not run the
+        // tool learns nothing about its arguments, and the answer to an
+        // unauthorized call is the same whatever it sent.
+        const validation = (0, validate_tool_input_1.validateToolInput)(args, tool.inputSchema);
+        if (!validation.valid) {
+            throw new common_1.UnprocessableEntityException({
+                message: `Invalid arguments for "${name}".`,
+                issues: validation.errors.map(toIssue)
+            });
+        }
+        // Stamped here rather than at the edge that built the context, so the
+        // surface a handler sees is by construction the one its `surfaces` was
+        // narrowed against — a tool cannot be authorized as one consumer and
+        // rendered for the other. See `ToolContext.surface` for what a handler
+        // may and may not do with it.
+        return tool.handler(args, { ...context, surface });
+    }
+    /**
+     * Every resource visible to the actor, across providers — permission
+     * filtered, exactly as {@link visibleTo} filters tools.
+     */
+    async resources(context) {
+        return (await this.declaredResources(context)).filter((resource) => this.permitsResource(resource, context));
+    }
+    /**
+     * Read one resource. Providers are asked in registration order and the
+     * first that claims the URI wins; nobody claiming it is a 404.
+     *
+     * A declared resource's `requires` is checked **here, before any provider
+     * is asked for the bytes** — the same rule as {@link call}, for the same
+     * reason: `resources()` hiding a resource is a listing nicety, and a client
+     * is free to read a URI it was never shown. The extra enumeration is the
+     * price of the gate; `resources/read` is not a hot path, and a provider
+     * that declares no resources costs nothing.
+     */
+    async readResource(uri, context) {
+        const declared = (await this.declaredResources(context)).find((resource) => resource.uri === uri);
+        if (declared && !this.permitsResource(declared, context)) {
+            throw new common_1.ForbiddenException(`"${uri}" requires ${(declared.requires ?? []).join(', ')}, which this ${context.actor.kind === 'token' ? 'token' : 'user'} does not hold.`);
+        }
+        for (const provider of this.providers) {
+            const contents = await provider.readResource?.(uri, context);
+            if (contents) {
+                return contents;
+            }
+        }
+        throw new common_1.NotFoundException(`Unknown resource "${uri}".`);
+    }
+    /** Every resource every provider declares, before permission filtering. */
+    async declaredResources(context) {
+        const perProvider = await Promise.all(this.providers.map((provider) => provider.resources?.(context) ?? []));
+        return perProvider.flat();
+    }
+    /** Whether the actor holds every permission the tool requires. */
+    permits(tool, context) {
+        return tool.requires.every((permission) => context.can(permission));
+    }
+    /**
+     * Whether the actor holds every permission the resource requires. A
+     * resource that declares none is readable by anyone who reached the
+     * endpoint, which is what every shipped resource means today.
+     */
+    permitsResource(resource, context) {
+        return (resource.requires ?? []).every((permission) => context.can(permission));
+    }
+    /**
+     * Everything wrong with the registered catalogue, as human sentences.
+     *
+     * Reported all at once rather than throwing on the first, so a deploy that
+     * broke two things learns about both.
+     */
+    catalogueProblems() {
+        const problems = [];
+        const seen = new Set();
+        for (const provider of this.providers) {
+            for (const tool of provider.tools()) {
+                if (seen.has(tool.name)) {
+                    problems.push(`duplicate tool name "${tool.name}" — two providers registered it. Tool names must be unique across plugins.`);
+                }
+                seen.add(tool.name);
+                problems.push(...this.toolProblems(tool));
+            }
+        }
+        return problems;
+    }
+    /** Everything wrong with one tool definition. */
+    toolProblems(tool) {
+        const problems = [];
+        if (!TOOL_NAME_PATTERN.test(tool.name)) {
+            problems.push(`"${tool.name}" is not a valid tool name — names are snake_case (${TOOL_NAME_PATTERN.source}).`);
+        }
+        if (tool.surfaces && tool.surfaces.length === 0) {
+            problems.push(`"${tool.name}" declares an empty \`surfaces\` array, so it is offered to neither consumer and callable by none. Omit the field to share it.`);
+        }
+        if (!Array.isArray(tool.requires)) {
+            problems.push(`"${tool.name}" has no \`requires\` array — a tool declares its permissions even when the answer is \`[]\`.`);
+        }
+        else {
+            for (const permission of tool.requires) {
+                if (!KNOWN_PERMISSIONS.has(permission)) {
+                    problems.push(`"${tool.name}" requires "${permission}", which is not a permission this deployment defines. Use a PERMISSIONS.* constant — a raw literal goes stale silently and leaves the tool uncallable by everyone.`);
+                }
+            }
+        }
+        if (!isPlainObject(tool.inputSchema)) {
+            problems.push(`"${tool.name}" has no \`inputSchema\` object. Declare \`{ type: 'object', properties: {} }\` for a tool that takes no arguments.`);
+        }
+        else if (tool.inputSchema['type'] !== undefined &&
+            tool.inputSchema['type'] !== 'object') {
+            problems.push(`"${tool.name}" declares an \`inputSchema\` of type "${String(tool.inputSchema['type'])}" — tool arguments are always an object.`);
+        }
+        return problems;
+    }
+};
+exports.ToolRegistry = ToolRegistry;
+exports.ToolRegistry = ToolRegistry = tslib_1.__decorate([
+    (0, common_1.Injectable)()
+], ToolRegistry);

package/dist/lib/tool.d.ts

@@ -0,0 +1,222 @@
+import type { PermissionKey } from '@orthacms/identity-server';
+/**
+ * A JSON Schema fragment. Tools declare their input shape as **plain JSON
+ * Schema** rather than a validator's object model, because most of this CMS's
+ * schema is runtime data — content types are defined in code and held in a
+ * registry, so their shapes are computed at boot, not declared as classes.
+ * `content/server`'s `docs/field-schema.ts` already produces exactly this for
+ * the OpenAPI document; the MCP tool schemas reuse it.
+ */
+export type JsonSchema = Record<string, unknown>;
+/** Who a tool call acts as. */
+export type ToolActorKind = 'token' | 'user';
+/**
+ * The identity a tool call runs under — the transport-neutral half of "who is
+ * asking". A bearer API token from the public API and a signed-in admin user
+ * driving the copilot are the same shape here, which is what lets one tool
+ * implementation serve both callers.
+ *
+ * `grantedPermissions` is resolved by whoever built the context (the MCP
+ * endpoint's bearer auth, or the copilot's RBAC lookup) and is the **only**
+ * input to the authorization decision — a tool never re-derives rights from
+ * `id` or `userId`.
+ */
+export interface ToolActor {
+    /** Whether this is a bearer token acting as itself, or a signed-in user. */
+    kind: ToolActorKind;
+    /**
+     * The actor's own id — a token id or a user id. What a log line keys on.
+     * For a token this is deliberately **not** the minting user: a token acts
+     * as itself, so revoking it revokes its access whoever created it.
+     */
+    id: string;
+    /** Display name, for diagnostics and audit lines. */
+    displayName: string;
+    /** The `resource:action` keys this actor holds. */
+    grantedPermissions: ReadonlySet<string>;
+    /**
+     * The accountable human, when there is one — the user themselves, or the
+     * user who minted a token. **Attribution only, never authorization.**
+     */
+    userId: string | null;
+}
+/**
+ * Everything a tool handler is told about the call, beyond its own arguments.
+ * Framework-free by design: no request, no response, nothing HTTP. A tool
+ * written against this runs identically behind the MCP endpoint and inside the
+ * copilot's in-process tool loop.
+ */
+export interface ToolContext {
+    /** Who is calling. */
+    actor: ToolActor;
+    /** The workspace this call acts in — always resolved before dispatch. */
+    workspaceId: string;
+    /**
+     * Aborted when the caller goes away, so a tool doing real I/O can give up
+     * instead of finishing work nobody will read.
+     *
+     * Optional because only one consumer has one: the copilot's run is a live
+     * SSE stream that ends when the browser disconnects, while an MCP call is a
+     * request/response and finishes either way. A tool that ignores it is
+     * correct — this is a courtesy, never a correctness boundary.
+     */
+    signal?: AbortSignal;
+    /**
+     * Which consumer dispatched this call — stamped by
+     * {@link ToolRegistry.call}, so it is always the surface the call was
+     * authorized against and never something the caller can assert.
+     *
+     * **For presentation only, never for authorization.** A tool offered to
+     * both surfaces may need to render the same fact differently for each — a
+     * download link is the session-gated admin route for the copilot and the
+     * bearer-fetchable `/v1` one for MCP, because the two callers hold
+     * different credentials. What a tool must *not* do is widen what it returns
+     * or skip a check on one surface: that is a difference in authority, and
+     * authority is `requires` plus {@link can}, which mean one thing for
+     * everybody. A tool that finds itself wanting `if (surface === 'copilot')`
+     * around a rule is two tools.
+     *
+     * Optional so a handler can be unit-tested with a hand-built context;
+     * absent, treat it as the copilot's admin-facing rendering.
+     */
+    surface?: ToolSurface;
+    /**
+     * Whether the actor holds a permission. Handlers use this for decisions
+     * **finer** than the tool's own `requires` gate — e.g. content reads let a
+     * writer see drafts, which is a widening inside one tool rather than a
+     * separate tool.
+     */
+    can(permission: PermissionKey): boolean;
+}
+/**
+ * What running a tool does to the system — the **authority** vocabulary, as
+ * distinct from the `readOnly`/`destructive` MCP *hints* below.
+ *
+ * `read` runs freely. `propose` produces a reviewable change a human accepts
+ * ([ADR-0005](../../../../docs/adr/0005-copilot-authority-model.md) §5) — its
+ * handler writes nothing, returning the change for its consumer to record.
+ * `apply` writes directly, gated only by the caller's own permissions
+ * ([ADR-0009](../../../../docs/adr/0009-copilot-applies-directly.md) §5 — it is
+ * offered exactly when a `read` tool with the same `requires` would be). It
+ * used to be off behind a workspace policy; ADR-0009 §4 deleted that policy,
+ * and an `apply` tool is now something a run performs, not something an
+ * operator opts into.
+ *
+ * Two vocabularies rather than one because they answer different questions.
+ * `readOnly` tells an MCP client what is safe to auto-approve; `effect` tells
+ * the *server* whether a handler's return value is a change or a result. A
+ * `propose` tool is not read-only in the MCP sense (it is part of a write
+ * flow), and a direct-write tool is not `propose` however destructive it is.
+ */
+export type ToolEffect = 'read' | 'propose' | 'apply';
+/**
+ * Which consumer of the registry a tool is offered to.
+ *
+ * Sharing the registry does **not** mean every tool suits every caller. The
+ * MCP content tools read through the public API's published-only services and
+ * attribute writes to a token; the copilot's read the admin's services (a
+ * viewer must see drafts) and write through propose-then-apply with the human
+ * as actor. Both are correct for their caller and wrong for the other, so the
+ * tool declares who it is for rather than a filter elsewhere guessing.
+ *
+ * Omitted means **both** — the honest default for a tool with no such tension
+ * (locales, media search), and the one that makes adding a genuinely shared
+ * tool the path of least resistance.
+ */
+export type ToolSurface = 'mcp' | 'copilot';
+/**
+ * What a tool returns. A plain JSON-serializable value — the transport decides
+ * how to present it (MCP wraps it as `structuredContent` plus a text rendering;
+ * the copilot's loop will feed it back to the model as a tool result).
+ */
+export type ToolOutput = unknown;
+/**
+ * One callable tool. The unit every consumer of the registry sees.
+ *
+ * `requires` is the authorization contract and is enforced **centrally** by
+ * {@link ToolRegistry.call}, exactly as `@RequirePermissions(...)` is enforced
+ * by a guard on the HTTP routes — a handler never checks its own gate, so a new
+ * tool cannot forget to. It is the direct analogue of the decorator, and the
+ * reason a `read`-scoped token gets a refusal on every write tool without a
+ * line of code here saying so.
+ */
+export interface ToolDefinition {
+    /**
+     * Machine name, `snake_case`, unique across every provider. Namespaced by
+     * subject (`content_list`, `content_create`) so a second contributing
+     * plugin's tools cannot read as the first's.
+     */
+    name: string;
+    /** Short human title, shown by MCP clients in tool pickers. */
+    title: string;
+    /**
+     * What the tool does, written **for a model**. This is the only
+     * documentation the caller gets, so it carries the workflow rules the HTTP
+     * API states in prose: that a create yields a draft, that publish is a
+     * separate call, that an update merges.
+     */
+    description: string;
+    /** JSON Schema for the arguments object. */
+    inputSchema: JsonSchema;
+    /**
+     * Permissions the actor must hold — **all** of them. Checked before the
+     * handler runs, and used to hide the tool from actors who cannot call it.
+     */
+    requires: readonly PermissionKey[];
+    /**
+     * True when the tool cannot modify anything. Surfaces as MCP's
+     * `readOnlyHint`, which clients use to decide what to auto-approve.
+     */
+    readOnly: boolean;
+    /**
+     * What running this does to the system. Defaults to `read` when omitted,
+     * which is what every tool written before the copilot joined the registry
+     * meant — but say it explicitly on anything that writes.
+     */
+    effect?: ToolEffect;
+    /**
+     * Which consumers may be offered this tool. Omitted means both; see
+     * {@link ToolSurface} for why a tool would ever narrow it.
+     */
+    surfaces?: readonly ToolSurface[];
+    /**
+     * True when the tool can destroy data an actor would not get back.
+     * Surfaces as MCP's `destructiveHint`.
+     */
+    destructive?: boolean;
+    /** Runs the tool. Throws to signal failure; see `toToolError`. */
+    handler(input: Record<string, unknown>, context: ToolContext): Promise<ToolOutput>;
+}
+/** One readable resource — a document a client can pull in without a call. */
+export interface ResourceDefinition {
+    /** Stable URI, e.g. `ortha://content-type/article`. */
+    uri: string;
+    /** Short human name. */
+    name: string;
+    /** What the resource holds. */
+    description: string;
+    /** MIME type of the contents, e.g. `application/json`. */
+    mimeType: string;
+    /**
+     * Permissions the actor must hold to list **or read** this resource — all
+     * of them, exactly as {@link ToolDefinition.requires}. Enforced centrally by
+     * {@link ToolRegistry}, so a resource cannot forget its own gate.
+     *
+     * Omitted means "no gate beyond reaching the endpoint", which is what every
+     * resource shipped today means: the content-type schemas are already
+     * narrowed to the workspace's own grants by the provider that builds them,
+     * and a resource that needs more than the workspace scope says so here
+     * rather than re-implementing the check.
+     */
+    requires?: readonly PermissionKey[];
+}
+/** The body of a resource read. */
+export interface ResourceContents {
+    /** Echoes the requested URI. */
+    uri: string;
+    /** MIME type of {@link text}. */
+    mimeType: string;
+    /** The resource body. */
+    text: string;
+}
+//# sourceMappingURL=tool.d.ts.map

package/dist/lib/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/lib/tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,+BAA+B;AAC/B,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,SAAS;IACtB,4EAA4E;IAC5E,IAAI,EAAE,aAAa,CAAC;IACpB;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACxC;;;OAGG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IACxB,sBAAsB;IACtB,KAAK,EAAE,SAAS,CAAC;IACjB,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;;;OAKG;IACH,GAAG,CAAC,UAAU,EAAE,aAAa,GAAG,OAAO,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAEtD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,SAAS,CAAC;AAE5C;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC;AAEjC;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC3B;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,WAAW,EAAE,UAAU,CAAC;IACxB;;;OAGG;IACH,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IACnC;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAClC;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kEAAkE;IAClE,OAAO,CACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,WAAW,GACrB,OAAO,CAAC,UAAU,CAAC,CAAC;CAC1B;AAED,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IAC/B,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACvC;AAED,mCAAmC;AACnC,MAAM,WAAW,gBAAgB;IAC7B,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;CAChB"}

package/dist/lib/tool.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/tools.module.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Provides the shared {@link ToolRegistry} — one instance for the whole
+ * application.
+ *
+ * **Global, and imported rather than provided by either consumer.** The
+ * registry has two of them (the MCP endpoint and the copilot's run loop) and
+ * belongs to neither: if `McpModule` provided it, a deployment running the
+ * copilot without MCP would have no registry and no tools; if each provided its
+ * own, the two would hold different catalogues and a tool registered by a
+ * capability plugin would reach whichever happened to win.
+ *
+ * Nest caches a static module by class, so importing this from both yields the
+ * same instance — which is exactly the invariant the whole seam rests on.
+ *
+ * A capability plugin does **not** import this: it injects `ToolRegistry`
+ * `@Optional()`, because a deployment may run neither consumer and its tools
+ * then simply go unregistered.
+ */
+export declare class ToolsModule {
+}
+//# sourceMappingURL=tools.module.d.ts.map

package/dist/lib/tools.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.module.d.ts","sourceRoot":"","sources":["../../src/lib/tools.module.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAKa,WAAW;CAAG"}

package/dist/lib/tools.module.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolsModule = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const tool_registry_1 = require("./tool-registry");
+/**
+ * Provides the shared {@link ToolRegistry} — one instance for the whole
+ * application.
+ *
+ * **Global, and imported rather than provided by either consumer.** The
+ * registry has two of them (the MCP endpoint and the copilot's run loop) and
+ * belongs to neither: if `McpModule` provided it, a deployment running the
+ * copilot without MCP would have no registry and no tools; if each provided its
+ * own, the two would hold different catalogues and a tool registered by a
+ * capability plugin would reach whichever happened to win.
+ *
+ * Nest caches a static module by class, so importing this from both yields the
+ * same instance — which is exactly the invariant the whole seam rests on.
+ *
+ * A capability plugin does **not** import this: it injects `ToolRegistry`
+ * `@Optional()`, because a deployment may run neither consumer and its tools
+ * then simply go unregistered.
+ */
+let ToolsModule = class ToolsModule {
+};
+exports.ToolsModule = ToolsModule;
+exports.ToolsModule = ToolsModule = tslib_1.__decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({
+        providers: [tool_registry_1.ToolRegistry],
+        exports: [tool_registry_1.ToolRegistry]
+    })
+], ToolsModule);

package/dist/lib/validate-tool-input.d.ts

@@ -0,0 +1,36 @@
+import type { JsonSchema } from './tool';
+/** The outcome of checking one tool's arguments against its schema. */
+export interface ToolInputValidation {
+    /** Whether the arguments satisfy the schema. */
+    valid: boolean;
+    /** Every problem found, as `path: message`. Empty when {@link valid}. */
+    errors: string[];
+}
+/**
+ * Validates a caller's tool arguments against the tool's declared JSON Schema.
+ *
+ * It lives beside {@link ToolDefinition} because that is the type whose
+ * `inputSchema` it interprets. It used to sit in the copilot's framework-free
+ * core, where only the copilot's run loop reached it — which is exactly why the
+ * MCP endpoint spent its whole life dispatching unvalidated arguments while the
+ * copilot refused them. Owned here, {@link ToolRegistry.call} applies it to
+ * **every** consumer, and a third one gets it without remembering to ask.
+ *
+ * **A deliberate subset, not a JSON Schema implementation.** It covers exactly
+ * what the generated tool schemas use — `type`, `properties`, `required`,
+ * `enum`, `items`, `additionalProperties`, and the numeric/length bounds — and
+ * *ignores* keywords it doesn't know (`anyOf`, `oneOf`, `$ref`, `format`,
+ * `pattern`) rather than guessing at them. A rule nested inside an `anyOf` is
+ * therefore **not** checked at all, which is the one thing a tool author must
+ * not read this as promising.
+ *
+ * That is tolerable because it is a **defence-in-depth** check, not a security
+ * boundary: `requires` is what decides whether a tool may run at all, and a
+ * handler still owns every rule about its own values. What this stops is a
+ * malformed call reaching a handler and turning a caller's mistake into an
+ * opaque 500. Every error it produces goes back to the caller as a
+ * `validation_failed` tool error naming the field, so a model can fix it and
+ * retry.
+ */
+export declare function validateToolInput(input: unknown, schema: JsonSchema): ToolInputValidation;
+//# sourceMappingURL=validate-tool-input.d.ts.map

package/dist/lib/validate-tool-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-tool-input.d.ts","sourceRoot":"","sources":["../../src/lib/validate-tool-input.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC,uEAAuE;AACvE,MAAM,WAAW,mBAAmB;IAChC,gDAAgD;IAChD,KAAK,EAAE,OAAO,CAAC;IACf,yEAAyE;IACzE,MAAM,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAC7B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,UAAU,GACnB,mBAAmB,CAIrB"}

package/dist/lib/validate-tool-input.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateToolInput = validateToolInput;
+/**
+ * Validates a caller's tool arguments against the tool's declared JSON Schema.
+ *
+ * It lives beside {@link ToolDefinition} because that is the type whose
+ * `inputSchema` it interprets. It used to sit in the copilot's framework-free
+ * core, where only the copilot's run loop reached it — which is exactly why the
+ * MCP endpoint spent its whole life dispatching unvalidated arguments while the
+ * copilot refused them. Owned here, {@link ToolRegistry.call} applies it to
+ * **every** consumer, and a third one gets it without remembering to ask.
+ *
+ * **A deliberate subset, not a JSON Schema implementation.** It covers exactly
+ * what the generated tool schemas use — `type`, `properties`, `required`,
+ * `enum`, `items`, `additionalProperties`, and the numeric/length bounds — and
+ * *ignores* keywords it doesn't know (`anyOf`, `oneOf`, `$ref`, `format`,
+ * `pattern`) rather than guessing at them. A rule nested inside an `anyOf` is
+ * therefore **not** checked at all, which is the one thing a tool author must
+ * not read this as promising.
+ *
+ * That is tolerable because it is a **defence-in-depth** check, not a security
+ * boundary: `requires` is what decides whether a tool may run at all, and a
+ * handler still owns every rule about its own values. What this stops is a
+ * malformed call reaching a handler and turning a caller's mistake into an
+ * opaque 500. Every error it produces goes back to the caller as a
+ * `validation_failed` tool error naming the field, so a model can fix it and
+ * retry.
+ */
+function validateToolInput(input, schema) {
+    const errors = [];
+    check(input, schema, '', errors);
+    return { valid: errors.length === 0, errors };
+}
+/** Recursively checks one value against one (sub)schema. */
+function check(value, schema, path, errors) {
+    const where = path || 'input';
+    const type = schema['type'];
+    if (typeof type === 'string' && !matchesType(value, type)) {
+        errors.push(`${where}: expected ${type}`);
+        // Bail out on this branch: every keyword below assumes the type held,
+        // and reporting "minLength failed" about a number is noise.
+        return;
+    }
+    const enumValues = schema['enum'];
+    if (Array.isArray(enumValues) && !enumValues.includes(value)) {
+        errors.push(`${where}: must be one of ${enumValues.join(', ')}`);
+    }
+    if (type === 'object' || isPlainObject(value)) {
+        checkObject(value, schema, path, errors);
+    }
+    if (Array.isArray(value)) {
+        checkArray(value, schema, path, errors);
+    }
+    if (typeof value === 'string') {
+        checkString(value, schema, where, errors);
+    }
+    if (typeof value === 'number') {
+        checkNumber(value, schema, where, errors);
+    }
+}
+/** `required`, `properties`, and `additionalProperties: false`. */
+function checkObject(value, schema, path, errors) {
+    if (!isPlainObject(value)) {
+        return;
+    }
+    const required = schema['required'];
+    if (Array.isArray(required)) {
+        for (const key of required) {
+            if (typeof key === 'string' && !(key in value)) {
+                errors.push(`${path ? `${path}.` : ''}${key}: required`);
+            }
+        }
+    }
+    const properties = isPlainObject(schema['properties'])
+        ? schema['properties']
+        : {};
+    for (const [key, raw] of Object.entries(value)) {
+        const propertySchema = properties[key];
+        if (isPlainObject(propertySchema)) {
+            check(raw, propertySchema, path ? `${path}.${key}` : key, errors);
+            continue;
+        }
+        // Only complain about an unknown key when the schema actually closed
+        // the object. A schema that stays open is choosing to accept extras.
+        if (schema['additionalProperties'] === false) {
+            errors.push(`${path ? `${path}.` : ''}${key}: unexpected property`);
+        }
+    }
+}
+/** `items`, `minItems`, `maxItems`. */
+function checkArray(value, schema, path, errors) {
+    const where = path || 'input';
+    const minItems = schema['minItems'];
+    if (typeof minItems === 'number' && value.length < minItems) {
+        errors.push(`${where}: expected at least ${minItems} items`);
+    }
+    const maxItems = schema['maxItems'];
+    if (typeof maxItems === 'number' && value.length > maxItems) {
+        errors.push(`${where}: expected at most ${maxItems} items`);
+    }
+    const items = schema['items'];
+    if (isPlainObject(items)) {
+        value.forEach((entry, index) => check(entry, items, `${path}[${index}]`, errors));
+    }
+}
+/** `minLength`, `maxLength`. */
+function checkString(value, schema, where, errors) {
+    const minLength = schema['minLength'];
+    if (typeof minLength === 'number' && value.length < minLength) {
+        errors.push(`${where}: expected at least ${minLength} characters`);
+    }
+    const maxLength = schema['maxLength'];
+    if (typeof maxLength === 'number' && value.length > maxLength) {
+        errors.push(`${where}: expected at most ${maxLength} characters`);
+    }
+}
+/** `minimum`, `maximum`. */
+function checkNumber(value, schema, where, errors) {
+    const minimum = schema['minimum'];
+    if (typeof minimum === 'number' && value < minimum) {
+        errors.push(`${where}: expected >= ${minimum}`);
+    }
+    const maximum = schema['maximum'];
+    if (typeof maximum === 'number' && value > maximum) {
+        errors.push(`${where}: expected <= ${maximum}`);
+    }
+}
+/** JSON Schema's type names, mapped onto JavaScript's. */
+function matchesType(value, type) {
+    switch (type) {
+        case 'object':
+            return isPlainObject(value);
+        case 'array':
+            return Array.isArray(value);
+        case 'string':
+            return typeof value === 'string';
+        case 'integer':
+            return typeof value === 'number' && Number.isInteger(value);
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'null':
+            return value === null;
+        default:
+            // An unknown type name is not a failure to report against the
+            // value — it's a schema we don't understand. Accept and move on.
+            return true;
+    }
+}
+/** A non-null, non-array object — what JSON Schema calls `object`. */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "@orthacms/tools-server",
+    "version": "0.0.0-reserve.0",
+    "description": "@orthacms/tools-server — part of Ortha CMS.",
+    "license": "MIT",
+    "homepage": "https://github.com/ortha-source/ortha-cms/tree/main/packages/tools/server",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ortha-source/ortha-cms.git",
+        "directory": "packages/tools/server"
+    },
+    "bugs": {
+        "url": "https://github.com/ortha-source/ortha-cms/issues"
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist"
+    ],
+    "dependencies": {
+        "@nestjs/common": "^11.0.0",
+        "@orthacms/identity-server": "^0.0.1",
+        "tslib": "^2.3.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}