@shardworks/tools-apparatus 0.1.101

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Sean Boots
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+# `@shardworks/tools-apparatus`
+
+The Instrumentarium — the guild's tool registry. This apparatus scans installed tools from kit contributions and apparatus supportKits at startup, resolves permission-gated tool sets on demand, and serves as the single source of truth for "what tools exist and who can use them."
+
+Both the CLI and the session layer (The Animator, via MCP) depend on The Instrumentarium to discover available tools. It sits low in the dependency graph — no dependencies on other apparatus.
+
+```
+@shardworks/tools-apparatus       — tool() factory, ToolDefinition type, tool registry, InstrumentariumApi
+@shardworks/nexus (cli)           — queries InstrumentariumApi for CLI-callable tools
+kits / apparatus supportKits      — contribute ToolDefinition[] via `tools` field
+```
+
+---
+
+## Installation
+
+```json
+{
+  "dependencies": {
+    "@shardworks/tools-apparatus": "workspace:*"
+  }
+}
+```
+
+Plugin id: `tools`
+
+---
+
+## API
+
+The Instrumentarium exposes `InstrumentariumApi` via `provides`, accessed by other plugins as:
+
+```typescript
+import { guild } from '@shardworks/nexus-core';
+import type { InstrumentariumApi } from '@shardworks/tools-apparatus';
+
+const instrumentarium = guild().apparatus<InstrumentariumApi>('tools');
+```
+
+### `InstrumentariumApi`
+
+```typescript
+interface InstrumentariumApi {
+  /**
+   * Resolve the tool set for a given set of permissions.
+   *
+   * Evaluates each registered tool against the permission grants:
+   * - Tools with a `permission` field: included if any grant matches
+   * - Permissionless tools: always included (default) or gated by `strict`
+   * - Channel filtering applied last
+   */
+  resolve(options: ResolveOptions): ResolvedTool[];
+
+  /**
+   * Find a single tool by name. Returns null if not installed.
+   */
+  find(name: string): ResolvedTool | null;
+
+  /**
+   * List all installed tools, regardless of permissions.
+   */
+  list(): ResolvedTool[];
+}
+```
+
+### `ResolvedTool`
+
+A tool with provenance metadata:
+
+```typescript
+interface ResolvedTool {
+  /** The tool definition (name, description, params schema, handler). */
+  definition: ToolDefinition;
+  /** Plugin id of the kit or apparatus that contributed this tool. */
+  pluginId: string;
+}
+```
+
+### `ResolveOptions`
+
+```typescript
+interface ResolveOptions {
+  /**
+   * Permission grants in `plugin:level` format.
+   * Supports wildcards: `plugin:*`, `*:level`, `*:*`.
+   */
+  permissions: string[];
+  /**
+   * When true, permissionless tools are excluded unless the role grants
+   * `plugin:*` or `*:*` for the tool's plugin. When false (default),
+   * permissionless tools are included unconditionally.
+   */
+  strict?: boolean;
+  /** Filter by caller type. Tools with no callableBy restriction pass all callers. */
+  caller?: ToolCaller;
+}
+```
+
+### Usage Examples
+
+**Resolve tools for a session (The Loom's use case):**
+
+```typescript
+// The Loom resolves role → permissions, then asks the Instrumentarium
+const tools = instrumentarium.resolve({
+  permissions: ['stdlib:read', 'stdlib:write', 'animator:read'],
+  caller: 'anima',
+});
+// → ResolvedTool[] — all anima-callable tools matching those permission grants
+```
+
+**Resolve with strict mode (lock down permissionless tools):**
+
+```typescript
+const tools = instrumentarium.resolve({
+  permissions: ['stdlib:*'],
+  strict: true,
+});
+// → Only tools from the stdlib plugin (both permissioned and permissionless)
+```
+
+**Find a specific tool:**
+
+```typescript
+const tool = instrumentarium.find('commission-show');
+if (tool) {
+  const result = await tool.definition.handler({ id: 'writ-123' });
+}
+```
+
+**List everything installed (the CLI's use case):**
+
+```typescript
+const cliTools = instrumentarium.list()
+  .filter(r => !r.definition.callableBy || r.definition.callableBy.includes('cli'))
+  .map(r => r.definition);
+```
+
+---
+
+## Permission Model
+
+The Instrumentarium is **role-agnostic** — it receives an already-resolved permissions array and returns matching tools. Role definitions and permission grants are owned by the Loom.
+
+### How permissions work
+
+Each tool may declare a `permission` level (e.g. `'read'`, `'write'`, `'admin'`). Callers provide permission grants in `plugin:level` format:
+
+| Grant format | Meaning |
+|---|---|
+| `stdlib:read` | Exact match — grants `read` tools from the `stdlib` plugin |
+| `stdlib:*` | Plugin wildcard — grants all tools from `stdlib` |
+| `*:read` | Level wildcard — grants `read` tools from any plugin |
+| `*:*` | Superuser — grants all tools from all plugins |
+
+There is **no permission hierarchy** — `write` does not imply `read`. Each level must be granted explicitly, or use wildcards.
+
+### Permissionless tools
+
+Tools without a `permission` field are **permissionless**. In default mode, they are always included in resolution results. In `strict` mode, they are excluded unless the caller has `plugin:*` or `*:*` for the tool's plugin.
+
+---
+
+## Kit Interface
+
+Kits contribute tools via a `tools` field in their kit export:
+
+```typescript
+import { tool } from '@shardworks/tools-apparatus';
+import { z } from 'zod';
+
+const showTool = tool({
+  name: 'commission-show',
+  description: 'Show details of a commission',
+  permission: 'read',
+  params: {
+    id: z.string().describe('Commission id'),
+  },
+  handler: async ({ id }) => {
+    const stacks = guild().apparatus<StacksApi>('stacks');
+    const writs = stacks.readBook<Writ>('clerk', 'writs');
+    return await writs.get(id);
+  },
+});
+
+export default {
+  kit: {
+    requires: ['tools'],
+    tools: [showTool],
+  },
+} satisfies Plugin;
+```
+
+Each entry in the `tools` array is a `ToolDefinition` produced by the `tool()` factory. The Instrumentarium scans these contributions at startup via the `plugin:initialized` lifecycle event.
+
+---
+
+## Exports
+
+```typescript
+// Tool authoring API (canonical home)
+import { tool, type ToolDefinition, type ToolCaller } from '@shardworks/tools-apparatus';
+
+// Instrumentarium API
+import {
+  type InstrumentariumApi,
+  type ResolvedTool,
+  type ResolveOptions,
+  createInstrumentarium,
+} from '@shardworks/tools-apparatus';
+```
+
+The default export is the apparatus plugin instance, ready for use in `guild.json`:
+
+```typescript
+import instrumentarium from '@shardworks/tools-apparatus';
+// → Plugin with apparatus.provides = InstrumentariumApi
+```

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @shardworks/tools-apparatus — The Instrumentarium.
+ *
+ * Guild tool registry: scans kit contributions, resolves permission-gated
+ * tool sets, and provides the InstrumentariumApi for tool lookup and resolution.
+ *
+ * The tool() factory and ToolDefinition type live here canonically.
+ *
+ * See: docs/specification.md (instrumentarium)
+ */
+export { type ToolCaller, type ToolDefinition, tool, isToolDefinition, } from './tool.ts';
+export { type InstrumentariumApi, type ResolvedTool, type ResolveOptions, } from './instrumentarium.ts';
+declare const _default: import("@shardworks/nexus-core").Plugin;
+export default _default;
+//# 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;;;;;;;;;GASG;AAMH,OAAO,EACL,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,IAAI,EACJ,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAInB,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,cAAc,GACpB,MAAM,sBAAsB,CAAC;;AAI9B,wBAAuC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * @shardworks/tools-apparatus — The Instrumentarium.
+ *
+ * Guild tool registry: scans kit contributions, resolves permission-gated
+ * tool sets, and provides the InstrumentariumApi for tool lookup and resolution.
+ *
+ * The tool() factory and ToolDefinition type live here canonically.
+ *
+ * See: docs/specification.md (instrumentarium)
+ */
+import { createInstrumentarium } from "./instrumentarium.js";
+// ── Tool authoring API ───────────────────────────────────────────────
+export { tool, isToolDefinition, } from "./tool.js";
+// ── Instrumentarium API ───────────────────────────────────────────────
+export {} from "./instrumentarium.js";
+// ── Default export: the apparatus plugin ──────────────────────────────
+export default createInstrumentarium();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,wEAAwE;AAExE,OAAO,EAGL,IAAI,EACJ,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAEnB,yEAAyE;AAEzE,OAAO,EAIN,MAAM,sBAAsB,CAAC;AAE9B,yEAAyE;AAEzE,eAAe,qBAAqB,EAAE,CAAC"}

package/dist/instrumentarium.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The Instrumentarium — guild tool registry apparatus.
+ *
+ * Scans installed tools from kit contributions and apparatus supportKits,
+ * resolves permission-gated tool sets on demand, and serves as the single
+ * source of truth for "what tools exist and who can use them."
+ *
+ * The Instrumentarium is role-agnostic — it receives an already-resolved
+ * permissions array from the Loom and returns the matching tool set.
+ * Role definitions and permission grants are owned by the Loom.
+ */
+import type { Plugin } from '@shardworks/nexus-core';
+import type { ToolDefinition, ToolCaller } from './tool.ts';
+/** A resolved tool with provenance metadata. */
+export interface ResolvedTool {
+    /** The tool definition (name, description, params schema, handler). */
+    definition: ToolDefinition;
+    /** Plugin id of the kit or apparatus that contributed this tool. */
+    pluginId: string;
+}
+/** Options for resolving a permission-gated tool set. */
+export interface ResolveOptions {
+    /**
+     * Permission grants in `plugin:level` format.
+     * Supports wildcards: `plugin:*`, `*:level`, `*:*`.
+     */
+    permissions: string[];
+    /**
+     * When true, permissionless tools are excluded unless the role grants
+     * `plugin:*` or `*:*` for the tool's plugin. When false (default),
+     * permissionless tools are included unconditionally.
+     */
+    strict?: boolean;
+    /** Filter by invocation caller. Tools with no callableBy pass all callers. */
+    caller?: ToolCaller;
+}
+/** The Instrumentarium's public API, exposed via `provides`. */
+export interface InstrumentariumApi {
+    /**
+     * Resolve the tool set for a given set of permissions.
+     *
+     * Evaluates each registered tool against the permission grants:
+     * - Tools with a `permission` field: included if any grant matches
+     * - Permissionless tools: always included (default) or gated by `strict`
+     * - Caller filtering applied last
+     */
+    resolve(options: ResolveOptions): ResolvedTool[];
+    /**
+     * Find a single tool by name. Returns null if not installed.
+     */
+    find(name: string): ResolvedTool | null;
+    /**
+     * List all installed tools, regardless of permissions.
+     */
+    list(): ResolvedTool[];
+}
+/**
+ * Create the Instrumentarium apparatus plugin.
+ *
+ * Returns a Plugin with:
+ * - `consumes: ['tools']` — scans kit/supportKit contributions
+ * - `provides: InstrumentariumApi` — the tool registry API
+ */
+export declare function createInstrumentarium(): Plugin;
+//# sourceMappingURL=instrumentarium.d.ts.map

package/dist/instrumentarium.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentarium.d.ts","sourceRoot":"","sources":["../src/instrumentarium.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAKV,MAAM,EACP,MAAM,wBAAwB,CAAC;AAOhC,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAO5D,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,UAAU,EAAE,cAAc,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,gEAAgE;AAChE,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,YAAY,EAAE,CAAC;IAEjD;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAAC;IAExC;;OAEG;IACH,IAAI,IAAI,YAAY,EAAE,CAAC;CACxB;AAkND;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CA8D9C"}

package/dist/instrumentarium.js

@@ -0,0 +1,248 @@
+/**
+ * The Instrumentarium — guild tool registry apparatus.
+ *
+ * Scans installed tools from kit contributions and apparatus supportKits,
+ * resolves permission-gated tool sets on demand, and serves as the single
+ * source of truth for "what tools exist and who can use them."
+ *
+ * The Instrumentarium is role-agnostic — it receives an already-resolved
+ * permissions array from the Loom and returns the matching tool set.
+ * Role definitions and permission grants are owned by the Loom.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { guild, isLoadedKit, isLoadedApparatus, } from '@shardworks/nexus-core';
+import { isToolDefinition } from "./tool.js";
+import { createToolsList } from "./tools/tools-list.js";
+import { createToolsShow } from "./tools/tools-show.js";
+/** Parse a grant string like "plugin:level" into its components. */
+function parseGrant(grant) {
+    const colonIdx = grant.indexOf(':');
+    if (colonIdx === -1)
+        return null;
+    return {
+        plugin: grant.slice(0, colonIdx),
+        level: grant.slice(colonIdx + 1),
+    };
+}
+/**
+ * Check if a tool with the given permission level from the given plugin
+ * is matched by any of the parsed grants.
+ */
+function matchesPermission(pluginId, permission, grants) {
+    for (const grant of grants) {
+        // Exact match: plugin:level
+        if (grant.plugin === pluginId && grant.level === permission)
+            return true;
+        // Plugin wildcard: plugin:*
+        if (grant.plugin === pluginId && grant.level === '*')
+            return true;
+        // Level wildcard: *:level
+        if (grant.plugin === '*' && grant.level === permission)
+            return true;
+        // Superuser: *:*
+        if (grant.plugin === '*' && grant.level === '*')
+            return true;
+    }
+    return false;
+}
+/**
+ * Check if a permissionless tool from the given plugin should be included
+ * in strict mode. Only `plugin:*` or `*:*` opts in permissionless tools.
+ */
+function strictAllowsPermissionless(pluginId, grants) {
+    for (const grant of grants) {
+        if (grant.plugin === pluginId && grant.level === '*')
+            return true;
+        if (grant.plugin === '*' && grant.level === '*')
+            return true;
+    }
+    return false;
+}
+// ── Implementation ────────────────────────────────────────────────────
+/**
+ * The tool registry — accumulates tools from plugin contributions
+ * and resolves permission-gated tool sets.
+ */
+class ToolRegistry {
+    /** Map from tool name → ResolvedTool. Last-write-wins for duplicates. */
+    tools = new Map();
+    /** Guild root path — set at startup, used for instructionsFile resolution. */
+    guildHome = '';
+    /** Set the guild root path for instructionsFile resolution. */
+    setHome(home) {
+        this.guildHome = home;
+    }
+    /** Register all tools from a loaded plugin. */
+    register(plugin) {
+        const pluginId = plugin.id;
+        const packageName = plugin.packageName;
+        if (isLoadedKit(plugin)) {
+            this.registerToolsFromKit(pluginId, packageName, plugin.kit);
+        }
+        else if (isLoadedApparatus(plugin)) {
+            if (plugin.apparatus.supportKit) {
+                this.registerToolsFromKit(pluginId, packageName, plugin.apparatus.supportKit);
+            }
+        }
+    }
+    /** Extract and register tools from a kit (or supportKit) contribution. */
+    registerToolsFromKit(pluginId, packageName, kit) {
+        const rawTools = kit.tools;
+        if (!Array.isArray(rawTools))
+            return;
+        for (const t of rawTools) {
+            if (isToolDefinition(t)) {
+                const definition = this.preloadInstructions(t, packageName);
+                this.tools.set(definition.name, { definition, pluginId });
+            }
+        }
+    }
+    /**
+     * Pre-load instructionsFile into instructions text.
+     *
+     * If the tool has an `instructionsFile`, resolve it relative to the
+     * package root in node_modules, read the file, and return a copy with
+     * `instructions` set to the file content and `instructionsFile` cleared.
+     *
+     * Tools with inline `instructions` or neither field are returned as-is.
+     */
+    preloadInstructions(tool, packageName) {
+        if (!tool.instructionsFile)
+            return tool;
+        const packageDir = path.join(this.guildHome, 'node_modules', packageName);
+        const filePath = path.join(packageDir, tool.instructionsFile);
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            // Return a mutated copy — instructionsFile consumed, instructions set
+            const { instructionsFile: _, ...rest } = tool;
+            return { ...rest, instructions: content };
+        }
+        catch {
+            console.warn(`[instrumentarium] Could not read instructions file for tool "${tool.name}": ${filePath}`);
+            // Return tool without instructions — don't block registration
+            const { instructionsFile: _, ...rest } = tool;
+            return rest;
+        }
+    }
+    /** Register a single tool definition directly (for self-contributed tools). */
+    registerTool(definition, pluginId) {
+        this.tools.set(definition.name, { definition, pluginId });
+    }
+    /** Find a tool by name. */
+    find(name) {
+        return this.tools.get(name) ?? null;
+    }
+    /** List all installed tools. */
+    list() {
+        return [...this.tools.values()];
+    }
+    /**
+     * Resolve a permission-gated tool set.
+     *
+     * 1. Parse each grant into (plugin, level) pairs
+     * 2. For each registered tool:
+     *    a. If tool has no permission:
+     *       - If NOT strict → include
+     *       - If strict → include only if grants contain <tool's plugin>:* or *:*
+     *    b. If tool has a permission:
+     *       - Match against grants: exact, plugin wildcard, level wildcard, or superuser
+     *       - Include if any grant matches
+     * 3. Filter by caller (callableBy)
+     */
+    resolve(options) {
+        const grants = options.permissions
+            .map(parseGrant)
+            .filter((g) => g !== null);
+        const strict = options.strict ?? false;
+        const result = [];
+        for (const resolved of this.tools.values()) {
+            const { definition, pluginId } = resolved;
+            const permission = definition.permission;
+            // Permission check
+            if (permission === undefined) {
+                // Permissionless tool
+                if (strict && !strictAllowsPermissionless(pluginId, grants)) {
+                    continue;
+                }
+                // In default mode, permissionless tools are always included
+            }
+            else {
+                // Tool has a permission — must match against grants
+                if (!matchesPermission(pluginId, permission, grants)) {
+                    continue;
+                }
+            }
+            // Caller filter
+            if (options.caller &&
+                definition.callableBy &&
+                !definition.callableBy.includes(options.caller)) {
+                continue;
+            }
+            result.push(resolved);
+        }
+        return result;
+    }
+}
+// ── Apparatus factory ─────────────────────────────────────────────────
+/**
+ * Create the Instrumentarium apparatus plugin.
+ *
+ * Returns a Plugin with:
+ * - `consumes: ['tools']` — scans kit/supportKit contributions
+ * - `provides: InstrumentariumApi` — the tool registry API
+ */
+export function createInstrumentarium() {
+    const registry = new ToolRegistry();
+    const api = {
+        resolve(options) {
+            return registry.resolve(options);
+        },
+        find(name) {
+            return registry.find(name);
+        },
+        list() {
+            return registry.list();
+        },
+    };
+    // Introspection tools use a lazy getter so they can query the registry
+    // after all plugins have registered their tools at startup.
+    const getApi = () => api;
+    const toolsList = createToolsList(getApi);
+    const toolsShow = createToolsShow(getApi);
+    return {
+        apparatus: {
+            requires: [],
+            consumes: ['tools'],
+            provides: api,
+            supportKit: {
+                tools: [toolsList, toolsShow],
+            },
+            start(ctx) {
+                const g = guild();
+                registry.setHome(g.home);
+                // Register our own supportKit tools (tools-list, tools-show).
+                // These live on this apparatus and aren't discovered through the
+                // normal kit scanning path.
+                for (const t of [toolsList, toolsShow]) {
+                    registry.registerTool(t, 'tools');
+                }
+                // Scan all already-loaded kits. These fired plugin:initialized before
+                // any apparatus started, so we can't catch them via events.
+                for (const kit of g.kits()) {
+                    registry.register(kit);
+                }
+                // Subscribe to plugin:initialized for apparatus supportKits that
+                // fire after us in the startup sequence.
+                ctx.on('plugin:initialized', (plugin) => {
+                    const loaded = plugin;
+                    // Skip kits — we already scanned them above.
+                    if (isLoadedApparatus(loaded)) {
+                        registry.register(loaded);
+                    }
+                });
+            },
+        },
+    };
+}
+//# sourceMappingURL=instrumentarium.js.map

package/dist/instrumentarium.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentarium.js","sourceRoot":"","sources":["../src/instrumentarium.ts"],"names":[],"mappings":"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"}

package/dist/tool.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Tool SDK — the primary authoring interface for module-based tools.
+ *
+ * Use `tool()` to define a typed tool with Zod parameter schemas.
+ * The returned definition is what the MCP engine imports and registers as a tool,
+ * what the CLI uses to auto-generate subcommands, and what engines import directly.
+ *
+ * A package can export a single tool or an array of tools:
+ *
+ * @example Single tool
+ * ```typescript
+ * import { tool } from '@shardworks/tools-apparatus';
+ * import { z } from 'zod';
+ *
+ * export default tool({
+ *   name: 'lookup',
+ *   description: 'Look up an anima by name',
+ *   instructionsFile: './instructions.md',
+ *   params: {
+ *     name: z.string().describe('Anima name'),
+ *   },
+ *   handler: async ({ name }) => {
+ *     const { home } = guild();
+ *     return { found: true, status: 'active' };
+ *   },
+ * });
+ * ```
+ *
+ * @example Tool collection
+ * ```typescript
+ * export default [
+ *   tool({ name: 'commission', description: '...', params: {...}, handler: ... }),
+ *   tool({ name: 'signal', description: '...', params: {...}, handler: ... }),
+ * ];
+ * ```
+ */
+import { z } from 'zod';
+type ZodShape = Record<string, z.ZodType>;
+/**
+ * The caller types a tool can be invoked by.
+ * - `'cli'` — accessible via `nsg` commands (human-facing)
+ * - `'anima'` — accessible via MCP server (anima-facing, in sessions)
+ * - `'library'` — accessible programmatically via direct import
+ *
+ * Defaults to all caller types if `callableBy` is unspecified.
+ */
+export type ToolCaller = 'cli' | 'anima' | 'library';
+/**
+ * A fully-defined tool — the return type of `tool()`.
+ *
+ * The MCP engine uses `.params.shape` to register the tool's input schema,
+ * `.description` for the tool description, and `.handler` to execute calls.
+ * The CLI uses `.params` to auto-generate Commander options.
+ * Engines call `.handler` directly.
+ */
+export interface ToolDefinition<TShape extends ZodShape = ZodShape> {
+    /** Tool name — used for resolution when a package exports multiple tools. */
+    readonly name: string;
+    readonly description: string;
+    /** Per-tool instructions injected into the anima's session context (inline text). */
+    readonly instructions?: string;
+    /**
+     * Path to an instructions file, relative to the package root.
+     * Resolved by the manifest engine at session time.
+     * Mutually exclusive with `instructions`.
+     */
+    readonly instructionsFile?: string;
+    /**
+     * Caller types this tool is available to.
+     * Always a normalized array. Absent means available to all callers.
+     */
+    readonly callableBy?: ToolCaller[];
+    /**
+     * Permission level required to invoke this tool. Matched against role grants.
+     *
+     * Format: a freeform string chosen by the tool author. Conventional names:
+     * - `'read'` — query/inspect operations
+     * - `'write'` — create/update operations
+     * - `'delete'` — destructive operations
+     * - `'admin'` — configuration and lifecycle operations
+     *
+     * Plugins are free to define their own levels.
+     * If omitted, the tool is permissionless — included by default in non-strict
+     * mode, excluded in strict mode unless the role grants `plugin:*` or `*:*`.
+     */
+    readonly permission?: string;
+    readonly params: z.ZodObject<TShape>;
+    readonly handler: (params: z.infer<z.ZodObject<TShape>>) => unknown | Promise<unknown>;
+}
+/** Input to `tool()` — instructions are either inline text or a file path, not both. */
+type ToolInput<TShape extends ZodShape> = {
+    name: string;
+    description: string;
+    params: TShape;
+    handler: (params: z.infer<z.ZodObject<TShape>>) => unknown | Promise<unknown>;
+    /**
+     * Caller types this tool is available to.
+     * Accepts a single caller or an array. Normalized to an array in the returned definition.
+     */
+    callableBy?: ToolCaller | ToolCaller[];
+    /**
+     * Permission level required to invoke this tool.
+     * See ToolDefinition.permission for details.
+     */
+    permission?: string;
+} & ({
+    instructions?: string;
+    instructionsFile?: never;
+} | {
+    instructions?: never;
+    instructionsFile?: string;
+});
+/**
+ * Define a Nexus tool.
+ *
+ * This is the primary SDK entry point for module-based tools. Pass a
+ * name, description, a params object of Zod schemas, and a handler function.
+ * The framework handles the rest — MCP registration, CLI generation, validation.
+ *
+ * The handler receives one argument:
+ * - `params` — the validated input, typed from your Zod schemas
+ *
+ * To access guild infrastructure (apparatus, config, home path), import
+ * `guild` from `@shardworks/nexus-core` and call `guild()` inside the handler.
+ *
+ * Return any JSON-serializable value. The MCP engine wraps it as tool output;
+ * the CLI prints it; engines use it directly.
+ *
+ * Instructions can be provided inline or as a file path:
+ * - `instructions: 'Use this tool when...'` — inline text
+ * - `instructionsFile: './instructions.md'` — resolved at manifest time
+ */
+export declare function tool<TShape extends ZodShape>(def: ToolInput<TShape>): ToolDefinition<TShape>;
+/** Type guard: is this value a ToolDefinition? */
+export declare function isToolDefinition(obj: unknown): obj is ToolDefinition;
+export {};
+//# sourceMappingURL=tool.d.ts.map

package/dist/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;AAE1C;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,OAAO,GAAG,SAAS,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc,CAAC,MAAM,SAAS,QAAQ,GAAG,QAAQ;IAChE,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC;IACnC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,CAChB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,KACjC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC;AAED,wFAAwF;AACxF,KAAK,SAAS,CAAC,MAAM,SAAS,QAAQ,IAAI;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,CACP,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,KACjC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,GAAG,UAAU,EAAE,CAAC;IACvC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,CACA;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,KAAK,CAAA;CAAE,GACnD;IAAE,YAAY,CAAC,EAAE,KAAK,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,CACtD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,IAAI,CAAC,MAAM,SAAS,QAAQ,EAAE,GAAG,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,cAAc,CAAC,MAAM,CAAC,CAa5F;AAED,kDAAkD;AAClD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc,CAYpE"}

package/dist/tool.js

@@ -0,0 +1,84 @@
+/**
+ * Tool SDK — the primary authoring interface for module-based tools.
+ *
+ * Use `tool()` to define a typed tool with Zod parameter schemas.
+ * The returned definition is what the MCP engine imports and registers as a tool,
+ * what the CLI uses to auto-generate subcommands, and what engines import directly.
+ *
+ * A package can export a single tool or an array of tools:
+ *
+ * @example Single tool
+ * ```typescript
+ * import { tool } from '@shardworks/tools-apparatus';
+ * import { z } from 'zod';
+ *
+ * export default tool({
+ *   name: 'lookup',
+ *   description: 'Look up an anima by name',
+ *   instructionsFile: './instructions.md',
+ *   params: {
+ *     name: z.string().describe('Anima name'),
+ *   },
+ *   handler: async ({ name }) => {
+ *     const { home } = guild();
+ *     return { found: true, status: 'active' };
+ *   },
+ * });
+ * ```
+ *
+ * @example Tool collection
+ * ```typescript
+ * export default [
+ *   tool({ name: 'commission', description: '...', params: {...}, handler: ... }),
+ *   tool({ name: 'signal', description: '...', params: {...}, handler: ... }),
+ * ];
+ * ```
+ */
+import { z } from 'zod';
+/**
+ * Define a Nexus tool.
+ *
+ * This is the primary SDK entry point for module-based tools. Pass a
+ * name, description, a params object of Zod schemas, and a handler function.
+ * The framework handles the rest — MCP registration, CLI generation, validation.
+ *
+ * The handler receives one argument:
+ * - `params` — the validated input, typed from your Zod schemas
+ *
+ * To access guild infrastructure (apparatus, config, home path), import
+ * `guild` from `@shardworks/nexus-core` and call `guild()` inside the handler.
+ *
+ * Return any JSON-serializable value. The MCP engine wraps it as tool output;
+ * the CLI prints it; engines use it directly.
+ *
+ * Instructions can be provided inline or as a file path:
+ * - `instructions: 'Use this tool when...'` — inline text
+ * - `instructionsFile: './instructions.md'` — resolved at manifest time
+ */
+export function tool(def) {
+    return {
+        name: def.name,
+        description: def.description,
+        ...(def.instructions ? { instructions: def.instructions } : {}),
+        ...(def.instructionsFile ? { instructionsFile: def.instructionsFile } : {}),
+        ...(def.callableBy !== undefined
+            ? { callableBy: Array.isArray(def.callableBy) ? def.callableBy : [def.callableBy] }
+            : {}),
+        ...(def.permission !== undefined ? { permission: def.permission } : {}),
+        params: z.object(def.params),
+        handler: def.handler,
+    };
+}
+/** Type guard: is this value a ToolDefinition? */
+export function isToolDefinition(obj) {
+    return (typeof obj === 'object' &&
+        obj !== null &&
+        'name' in obj &&
+        'description' in obj &&
+        'params' in obj &&
+        'handler' in obj &&
+        typeof obj.name === 'string' &&
+        typeof obj.description === 'string' &&
+        typeof obj.handler === 'function');
+}
+//# sourceMappingURL=tool.js.map

package/dist/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAoFxB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,IAAI,CAA0B,GAAsB;IAClE,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,GAAG,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3E,GAAG,CAAC,GAAG,CAAC,UAAU,KAAK,SAAS;YAC9B,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE;YACnF,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;QAC5B,OAAO,EAAE,GAAG,CAAC,OAAO;KACrB,CAAC;AACJ,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,MAAM,IAAI,GAAG;QACb,aAAa,IAAI,GAAG;QACpB,QAAQ,IAAI,GAAG;QACf,SAAS,IAAI,GAAG;QAChB,OAAQ,GAAsB,CAAC,IAAI,KAAK,QAAQ;QAChD,OAAQ,GAAsB,CAAC,WAAW,KAAK,QAAQ;QACvD,OAAQ,GAAsB,CAAC,OAAO,KAAK,UAAU,CACtD,CAAC;AACJ,CAAC"}

package/dist/tools/tools-list.d.ts

@@ -0,0 +1,29 @@
+/**
+ * tools-list — administrative view of all tools installed in the guild.
+ *
+ * Lists the full registry with optional filters for caller type, permission
+ * level, and contributing plugin. This is an inventory tool, not a
+ * permission-resolved view — use MCP native tool listing for that.
+ *
+ * Requires `tools:read` permission.
+ */
+import { z } from 'zod';
+import type { InstrumentariumApi } from '../instrumentarium.ts';
+/** Summary returned for each tool in the list. */
+export interface ToolSummary {
+    name: string;
+    description: string;
+    pluginId: string;
+    permission: string | null;
+    callableBy: string[] | null;
+}
+export declare function createToolsList(getApi: () => InstrumentariumApi): import("../tool.ts").ToolDefinition<{
+    caller: z.ZodOptional<z.ZodEnum<{
+        cli: "cli";
+        anima: "anima";
+        library: "library";
+    }>>;
+    permission: z.ZodOptional<z.ZodString>;
+    plugin: z.ZodOptional<z.ZodString>;
+}>;
+//# sourceMappingURL=tools-list.d.ts.map

package/dist/tools/tools-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-list.d.ts","sourceRoot":"","sources":["../../src/tools/tools-list.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAC7B;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,kBAAkB;;;;;;;;GA0D/D"}

package/dist/tools/tools-list.js

@@ -0,0 +1,57 @@
+/**
+ * tools-list — administrative view of all tools installed in the guild.
+ *
+ * Lists the full registry with optional filters for caller type, permission
+ * level, and contributing plugin. This is an inventory tool, not a
+ * permission-resolved view — use MCP native tool listing for that.
+ *
+ * Requires `tools:read` permission.
+ */
+import { z } from 'zod';
+import { tool } from "../tool.js";
+export function createToolsList(getApi) {
+    return tool({
+        name: 'tools-list',
+        description: 'List all tools installed in the guild. Administrative view — shows the full registry, not a permission-resolved set.',
+        permission: 'read',
+        params: {
+            caller: z
+                .enum(['cli', 'anima', 'library'])
+                .optional()
+                .describe('Filter to tools callable by this caller type.'),
+            permission: z
+                .string()
+                .optional()
+                .describe('Filter to tools requiring this permission level (e.g. "read", "write").'),
+            plugin: z
+                .string()
+                .optional()
+                .describe('Filter to tools contributed by this plugin id.'),
+        },
+        handler: async ({ caller, permission, plugin }) => {
+            const api = getApi();
+            let tools = api.list();
+            // Filter by contributing plugin
+            if (plugin) {
+                tools = tools.filter((t) => t.pluginId === plugin);
+            }
+            // Filter by permission level
+            if (permission) {
+                tools = tools.filter((t) => t.definition.permission === permission);
+            }
+            // Filter by caller type (callableBy gate)
+            if (caller) {
+                tools = tools.filter((t) => !t.definition.callableBy ||
+                    t.definition.callableBy.includes(caller));
+            }
+            return tools.map((t) => ({
+                name: t.definition.name,
+                description: t.definition.description,
+                pluginId: t.pluginId,
+                permission: t.definition.permission ?? null,
+                callableBy: t.definition.callableBy ?? null,
+            }));
+        },
+    });
+}
+//# sourceMappingURL=tools-list.js.map

package/dist/tools/tools-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-list.js","sourceRoot":"","sources":["../../src/tools/tools-list.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAYlC,MAAM,UAAU,eAAe,CAAC,MAAgC;IAC9D,OAAO,IAAI,CAAC;QACV,IAAI,EAAE,YAAY;QAClB,WAAW,EACT,sHAAsH;QACxH,UAAU,EAAE,MAAM;QAClB,MAAM,EAAE;YACN,MAAM,EAAE,CAAC;iBACN,IAAI,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;iBACjC,QAAQ,EAAE;iBACV,QAAQ,CAAC,+CAA+C,CAAC;YAC5D,UAAU,EAAE,CAAC;iBACV,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,yEAAyE,CAC1E;YACH,MAAM,EAAE,CAAC;iBACN,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,gDAAgD,CAAC;SAC9D;QACD,OAAO,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE;YAChD,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;YACrB,IAAI,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;YAEvB,gCAAgC;YAChC,IAAI,MAAM,EAAE,CAAC;gBACX,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,MAAM,CAAC,CAAC;YACrD,CAAC;YAED,6BAA6B;YAC7B,IAAI,UAAU,EAAE,CAAC;gBACf,KAAK,GAAG,KAAK,CAAC,MAAM,CAClB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,UAAU,KAAK,UAAU,CAC9C,CAAC;YACJ,CAAC;YAED,0CAA0C;YAC1C,IAAI,MAAM,EAAE,CAAC;gBACX,KAAK,GAAG,KAAK,CAAC,MAAM,CAClB,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,CAAC,UAAU,CAAC,UAAU;oBACxB,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,CAC3C,CAAC;YACJ,CAAC;YAED,OAAO,KAAK,CAAC,GAAG,CACd,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC;gBACnB,IAAI,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI;gBACvB,WAAW,EAAE,CAAC,CAAC,UAAU,CAAC,WAAW;gBACrC,QAAQ,EAAE,CAAC,CAAC,QAAQ;gBACpB,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,UAAU,IAAI,IAAI;gBAC3C,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,UAAU,IAAI,IAAI;aAC5C,CAAC,CACH,CAAC;QACJ,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/tools-show.d.ts

@@ -0,0 +1,30 @@
+/**
+ * tools-show — show full details for a single tool.
+ *
+ * Returns name, description, plugin, permission, callableBy, parameter
+ * schema, and instructions for the named tool. Returns null if not found.
+ *
+ * Requires `tools:read` permission.
+ */
+import { z } from 'zod';
+import type { InstrumentariumApi } from '../instrumentarium.ts';
+/** Parameter info derived from the Zod schema. */
+export interface ParamInfo {
+    type: string;
+    description: string | null;
+    optional: boolean;
+}
+/** Full detail returned for a single tool. */
+export interface ToolDetail {
+    name: string;
+    description: string;
+    pluginId: string;
+    permission: string | null;
+    callableBy: string[] | null;
+    params: Record<string, ParamInfo>;
+    instructions: string | null;
+}
+export declare function createToolsShow(getApi: () => InstrumentariumApi): import("../tool.ts").ToolDefinition<{
+    name: z.ZodString;
+}>;
+//# sourceMappingURL=tools-show.d.ts.map

package/dist/tools/tools-show.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-show.d.ts","sourceRoot":"","sources":["../../src/tools/tools-show.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,kDAAkD;AAClD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAClC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAyDD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,kBAAkB;;GA8B/D"}

package/dist/tools/tools-show.js

@@ -0,0 +1,94 @@
+/**
+ * tools-show — show full details for a single tool.
+ *
+ * Returns name, description, plugin, permission, callableBy, parameter
+ * schema, and instructions for the named tool. Returns null if not found.
+ *
+ * Requires `tools:read` permission.
+ */
+import { z } from 'zod';
+import { tool } from "../tool.js";
+/**
+ * Extract parameter info from a Zod object schema.
+ *
+ * Walks the shape, unwraps ZodOptional/ZodDefault wrappers, and
+ * derives the JSON Schema type name from the inner Zod type.
+ */
+function extractParams(schema) {
+    const shape = schema.shape;
+    const result = {};
+    for (const [key, zodType] of Object.entries(shape)) {
+        result[key] = extractSingleParam(zodType);
+    }
+    return result;
+}
+/** Extract info for a single Zod parameter. */
+function extractSingleParam(zodType) {
+    let isOptional = false;
+    let inner = zodType;
+    // Unwrap ZodOptional
+    if (inner instanceof z.ZodOptional) {
+        isOptional = true;
+        inner = inner.unwrap();
+    }
+    // Unwrap ZodDefault
+    if (inner instanceof z.ZodDefault) {
+        isOptional = true;
+        inner = inner.unwrap();
+    }
+    return {
+        type: zodTypeToJsonType(inner),
+        description: inner.description ?? null,
+        optional: isOptional,
+    };
+}
+/** Map a Zod type to a JSON Schema type string. */
+function zodTypeToJsonType(zodType) {
+    if (zodType instanceof z.ZodString)
+        return 'string';
+    if (zodType instanceof z.ZodNumber)
+        return 'number';
+    if (zodType instanceof z.ZodBoolean)
+        return 'boolean';
+    if (zodType instanceof z.ZodArray)
+        return 'array';
+    if (zodType instanceof z.ZodObject)
+        return 'object';
+    if (zodType instanceof z.ZodEnum)
+        return 'string';
+    if (zodType instanceof z.ZodLiteral)
+        return typeof zodType._def.values[0];
+    if (zodType instanceof z.ZodUnion)
+        return 'union';
+    if (zodType instanceof z.ZodNullable)
+        return zodTypeToJsonType(zodType.unwrap());
+    return 'unknown';
+}
+export function createToolsShow(getApi) {
+    return tool({
+        name: 'tools-show',
+        description: 'Show details for a tool by name, including parameter schema and instructions.',
+        permission: 'read',
+        params: {
+            name: z.string().describe('Tool name to look up.'),
+        },
+        handler: async ({ name }) => {
+            const api = getApi();
+            const resolved = api.find(name);
+            if (!resolved)
+                return null;
+            const { definition, pluginId } = resolved;
+            const detail = {
+                name: definition.name,
+                description: definition.description,
+                pluginId,
+                permission: definition.permission ?? null,
+                callableBy: definition.callableBy ?? null,
+                params: extractParams(definition.params),
+                instructions: definition.instructions ?? null,
+            };
+            return detail;
+        },
+    });
+}
+//# sourceMappingURL=tools-show.js.map

package/dist/tools/tools-show.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-show.js","sourceRoot":"","sources":["../../src/tools/tools-show.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@shardworks/tools-apparatus",
+  "version": "0.1.101",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shardworks/nexus",
+    "directory": "packages/plugins/tools"
+  },
+  "description": "The Instrumentarium — guild tool registry apparatus",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "4.3.6",
+    "@shardworks/nexus-core": "0.1.101"
+  },
+  "devDependencies": {
+    "@types/node": "25.5.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --disable-warning=ExperimentalWarning --experimental-transform-types --test 'src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  }
+}