@thinger-io/cli-core 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.3.0] - 2026-10-14
+
+### Added
+
+- `runCli({ resourceTypes, resourceActions })`: a CLI adds its platform's
+  own resource types (functions instead of a REST path) and actions on the
+  server's types, served by the same `resource_*` tools: listed in
+  `resource_describe`, searched and paged by `resource_list`, their parent
+  and id checked like the server's. Clashes with the catalog fail at
+  startup. ThinRemote serves its files, scripts, metrics, log sources and
+  playbooks this way.
+- `alarm_instance` action `stats`: how many instances there are in each
+  state.
+
+### Fixed
+
+- `resource_list` pages lists answered whole from any `index`, not only
+  when they are longer than a page.
+- `resource_describe` says which server actions take no id.
+
 ## [0.2.1] - 2026-10-12
 
 ### Changed

package/README.md

@@ -70,6 +70,18 @@ servers.
   the same name.
 - `resourceHooks` — the CLI's hooks on catalog types (`{ product: {
 afterDelete } }`), run after the core's: see `mcp/resource-hooks.js`.
+- `resourceTypes` — resource types of the CLI's own platform, served by the
+  same `resource_*` tools as the server's: instead of a REST path each has
+  functions for the verbs it supports (`list`, `get`, `create`, `update`,
+  `delete`), its `parent` and `id`, a `schema` and `notes` for
+  `resource_describe`, and `actions` for `resource_call` (`on: 'item'`,
+  `'collection'` or `'either'`). The core checks the parent and id, and
+  searches and pages what `list` returns. See `LocalType` in
+  `mcp/tools-resource.js`.
+- `resourceActions` — actions the CLI adds to the server's types
+  (`{ device: { reboot: { description, run } } }`), run with
+  `resource_call` like the server's. A type or action that clashes with the
+  catalog fails at startup.
 - `mcpInstructions` — server-level guidance sent to MCP clients.
 
 ## MCP tools

package/lib/cli.js

@@ -23,13 +23,17 @@ import { registerBucketCommands } from './commands/bucket.js';
  *   mcpTools?: Array<object>,
  *   mcpInstructions?: string,
  *   resourceHooks?: Record<string, import('./mcp/resource-hooks.js').ResourceHooks>,
+ *   resourceTypes?: Record<string, import('./mcp/tools-resource.js').LocalType>,
+ *   resourceActions?: Record<string, Record<string, import('./mcp/tools-resource.js').LocalAction>>,
  *   docs?: Parameters<typeof import('./docs.js').defineCliDocs>[0],
  * }} opts
  *   `register` adds the CLI's own commands, at the top level or inside the
  *   generic groups. `onNoCommand` runs when the CLI is called without
  *   arguments (default: print the help). `mcpTools` are the CLI's own MCP
  *   tools (see buildTools), and `resourceHooks` its hooks on the
- *   catalog types the generic `resource_*` tools serve. `docs` are guides
+ *   catalog types the generic `resource_*` tools serve; `resourceTypes` and
+ *   `resourceActions` are types and actions it adds to that catalog (its
+ *   platform's own things, served by the same tools). `docs` are guides
  *   the CLI ships, served by `doc_read` and as MCP resources next to the
  *   server's documentation.
  */
@@ -41,6 +45,8 @@ export async function runCli({
     mcpTools = [],
     mcpInstructions,
     resourceHooks,
+    resourceTypes,
+    resourceActions,
     docs,
 }) {
     const id = identity();
@@ -91,6 +97,8 @@ export async function runCli({
                     tools: mcpTools,
                     instructions: mcpInstructions,
                     resourceHooks,
+                    resourceTypes,
+                    resourceActions,
                     docs,
                 });
             } catch (error) {

package/lib/mcp/catalog.js

@@ -339,6 +339,16 @@ export const CATALOG = {
             delete: 'Alarm_DeleteInstance',
             projects: 'Alarm_UpdateInstanceProjects',
         },
+        actions: {
+            stats: {
+                op: 'Alarm_ReadInstanceStats',
+                method: 'get',
+                path: 'stats',
+                on: 'collection',
+                description:
+                    'How many instances there are in each state: the health of the account at a glance, without listing them.',
+            },
+        },
         notes: 'States: 0 none, 1 active, 2 acknowledged, 3 latched, 4 shelved, 5 cleared; severities: 0 none, 1 low, 2 medium, 3 high, 4 critical. Acknowledge with update {state: 2, annotation?}; shelve with {state: 4, reactivation: {type: "timespan", timespan: {value, magnitude: "minute"|"hour"|"day"…}}}; clear with {state: 5} (a cleared alarm cannot be reactivated). Prefer clearing to deleting: delete removes the history. List filters: state and severity (arrays allowed), name, sort, order, and exact values of nested fields with dots: {"alarm.rule": "<rule id>"}, {"origin.id": "<device>"}, or both (servers before this filter ignore it and list every instance: check the records). `search` matches the instance id and the rule\'s name, not the rule id. A record: {instance, name, description, state, severity, alarm: {rule: <rule id>, group, type}, origin: {source: "device", id: <device>, name}, asset_type, asset_group, activation: {initiated, completed, detections}, normalization: {…}, evaluation: {last_values: {<source>: {<field>: value}}, last_completed}, notification: {last_type, total_completed, total_failed}, project}; times in unix ms.',
     },
     claim: {

package/lib/mcp/registry.js

@@ -15,6 +15,10 @@ import { expandToolRefs, toolName } from './naming.js';
  * @typedef {object} ToolOptions
  * @property {Record<string, import('./resource-hooks.js').ResourceHooks>} [hooks]
  *   The CLI's own hooks on catalog types (see resource-hooks.js).
+ * @property {Record<string, import('./tools-resource.js').LocalType>} [types]
+ *   Resource types the CLI adds, served by the same `resource_*` tools.
+ * @property {Record<string, Record<string, import('./tools-resource.js').LocalAction>>} [actions]
+ *   Actions the CLI adds to resource types (the server's or its own).
  */
 
 /**

package/lib/mcp/server.js

@@ -25,13 +25,16 @@ import { defineCliDocs } from '../docs.js';
  *   tools?: Array<object>,
  *   instructions?: string,
  *   resourceHooks?: Record<string, import('./resource-hooks.js').ResourceHooks>,
+ *   resourceTypes?: Record<string, import('./tools-resource.js').LocalType>,
+ *   resourceActions?: Record<string, Record<string, import('./tools-resource.js').LocalAction>>,
  *   docs?: Parameters<typeof import('../docs.js').defineCliDocs>[0],
  * }} [opts]
  *   `version` is echoed in the `initialize` response's `serverInfo.version`;
  *   callers pass their `package.json#version` so the two never drift.
  *   `tools` are CLI-specific tools added to the generic set.
  *   `instructions` is the server-level guidance sent to the client.
- *   `resourceHooks` are the CLI's hooks on catalog types.
+ *   `resourceHooks` are the CLI's hooks on catalog types; `resourceTypes`
+ *   and `resourceActions` the types and actions it adds to the catalog.
  *   `docs` are the guides the CLI ships (see docs.js).
  */
 export async function startMCPServer({
@@ -39,11 +42,17 @@ export async function startMCPServer({
     tools: extra = [],
     instructions,
     resourceHooks,
+    resourceTypes,
+    resourceActions,
     docs,
 } = {}) {
     const { mcp } = identity();
     defineCliDocs(docs);
-    const tools = buildTools(extra, { hooks: resourceHooks });
+    const tools = buildTools(extra, {
+        hooks: resourceHooks,
+        types: resourceTypes,
+        actions: resourceActions,
+    });
 
     const server = new Server(
         {

package/lib/mcp/tools-resource.js

@@ -28,6 +28,131 @@ import { mergeHooks } from './resource-hooks.js';
  * document when the model needs it.
  */
 
+/**
+ * Types and actions a CLI adds to the catalog (`runCli({ resourceTypes,
+ * resourceActions })`): its platform's own things, served by the same
+ * tools. A CLI type has no REST path: its functions answer each verb.
+ *
+ * What reaches those functions comes from the model: `parent` and `id` are
+ * checked for their number of segments (and `..`, empty or control
+ * characters), but `id`, `filter`, `query` and the body are still untrusted
+ * input, to be validated before use.
+ *
+ * @typedef {object} LocalContext
+ * @property {string} type
+ * @property {string} [parent]
+ * @property {string} [id]
+ * @property {string | null} [user]
+ * @property {Record<string, any>} [filter]  resource_list's filter.
+ * @property {Record<string, any>} [query]   resource_call's query.
+ * @property {boolean} [full]
+ * @property {Record<string, any>} state
+ *
+ * @typedef {object} LocalAction
+ * @property {string} description
+ * @property {'item' | 'collection' | 'either'} [on]  Whether it takes an id: item (default)
+ *   needs one, collection takes none, either takes it or not.
+ * @property {object} [body]  JSON schema of its body, shown by resource_describe.
+ * @property {(body: any, ctx: LocalContext) => any} run  Returns the answer: text,
+ *   anything JSON, or a whole tool result ({content: [{type, text}], isError}) to flag a
+ *   failure (only actions can; the verbs answer text or JSON).
+ *
+ * @typedef {object} LocalType
+ * @property {string} description  One line, shown in the catalog summary.
+ * @property {string} [parent]  Type this one hangs off (the server's or another CLI
+ *   type with an id): its location is the `parent`.
+ * @property {string} [id]      Name of the item id; without one, a single resource of its parent.
+ * @property {string} [notes]   Longer guidance returned by resource_describe.
+ * @property {object} [schema]  JSON schema of a record, the body of create and update.
+ * @property {() => Record<string, any> | Promise<Record<string, any>>} [describe]  More
+ *   for resource_describe to show (a reference the type's records follow, say).
+ * @property {(ctx: LocalContext) => any[] | Promise<any[]>} [list]  The whole list:
+ *   search and paging are done by the tool.
+ * @property {(ctx: LocalContext) => any} [get]
+ * @property {(body: any, ctx: LocalContext) => any} [create]  Returns a result or a note.
+ * @property {(body: any, ctx: LocalContext) => any} [update]
+ * @property {(ctx: LocalContext) => any} [delete]
+ * @property {Record<string, LocalAction>} [actions]
+ */
+
+const LOCAL_VERBS = /** @type {const} */ (['list', 'get', 'create', 'update', 'delete']);
+const ACTION_ON = new Set(['item', 'collection', 'either']);
+// eslint-disable-next-line no-control-regex -- control characters are what it looks for
+const CONTROL = /[\x00-\x1f]/;
+
+/** An own key of a plain map: never `constructor` or another inherited one. */
+const own = (map, key) =>
+    map && typeof key === 'string' && Object.hasOwn(map, key) ? map[key] : undefined;
+
+/** A whole MCP tool result, as an action may answer to flag a failure. */
+const isToolResult = (v) =>
+    !!v &&
+    typeof v === 'object' &&
+    Array.isArray(v.content) &&
+    v.content.every((c) => c && typeof c === 'object' && typeof c.type === 'string') &&
+    Object.keys(v).every((k) => k === 'content' || k === 'isError' || k === '_meta');
+
+/**
+ * Longest answer a CLI type or action gives (characters of the text sent):
+ * a file it reads can be huge. Server types are never cut: a record read to
+ * be edited and written back must be whole.
+ */
+export const MAX_TEXT = 100_000;
+
+/** `text` cut at MAX_TEXT, saying so. */
+function capped(t) {
+    t = String(t ?? '');
+    if (t.length <= MAX_TEXT) return t;
+    return `${t.slice(0, MAX_TEXT)}\n… (cut: ${t.length} characters in total, showing the first ${MAX_TEXT})`;
+}
+
+/**
+ * Check what a CLI adds against the catalog: a type or an action that
+ * clashes with the server's is a mistake, found when the server starts.
+ *
+ * @param {Record<string, LocalType>} types
+ * @param {Record<string, Record<string, LocalAction>>} actions
+ */
+export function checkLocal(types, actions) {
+    for (const [name, t] of Object.entries(types)) {
+        if (CATALOG[name]) throw new Error(`Resource type "${name}" is already a server type`);
+        if (!t.description) throw new Error(`Resource type "${name}" needs a description`);
+        if (t.parent && !CATALOG[t.parent] && !own(types, t.parent)) {
+            throw new Error(`Resource type "${name}": unknown parent "${t.parent}"`);
+        }
+        const seen = new Set([name]);
+        for (let p = t.parent; p && own(types, p); p = types[p].parent) {
+            if (seen.has(p)) throw new Error(`Resource type "${name}": its parents loop`);
+            if (!types[p].id) throw new Error(`Resource type "${name}": parent "${p}" has no id`);
+            seen.add(p);
+        }
+        if (!LOCAL_VERBS.some((v) => typeof t[v] === 'function') && !t.actions) {
+            throw new Error(`Resource type "${name}" has no operations`);
+        }
+        for (const [a, spec] of Object.entries(t.actions || {})) checkAction(name, a, spec);
+    }
+    for (const [type, list] of Object.entries(actions)) {
+        if (!CATALOG[type] && !types[type]) {
+            throw new Error(`Actions for unknown resource type "${type}"`);
+        }
+        for (const [a, spec] of Object.entries(list)) {
+            if (CATALOG[type]?.actions?.[a] || types[type]?.actions?.[a]) {
+                throw new Error(`Resource type "${type}" already has an action "${a}"`);
+            }
+            checkAction(type, a, spec);
+        }
+    }
+}
+
+function checkAction(type, name, spec) {
+    if (typeof spec?.run !== 'function' || !spec.description) {
+        throw new Error(`Action "${name}" of "${type}" needs a description and run()`);
+    }
+    if (spec.on !== undefined && !ACTION_ON.has(spec.on)) {
+        throw new Error(`Action "${name}" of "${type}": on must be item, collection or either`);
+    }
+}
+
 /** `{tool:x}` in catalog notes → full tool names (tests check they exist). */
 const expandNotes = (notes) => notes.replace(/\{tool:([a-z0-9_]+)\}/g, (_, base) => toolName(base));
 
@@ -209,7 +334,7 @@ function responseExample(operation) {
 }
 
 /** Which tool runs each verb of a type. */
-function operationsOf(type) {
+function operationsOf(ops) {
     const tools = {
         list: toolName('resource_list'),
         get: toolName('resource_get'),
@@ -220,30 +345,115 @@ function operationsOf(type) {
         clone: toolName('resource_clone'),
         projects: `${toolName('resource_update')} with {projects: [...]}`,
     };
-    return Object.fromEntries(Object.keys(type.ops).map((verb) => [verb, tools[verb]]));
-}
-
-function catalogSummary(names) {
-    const lines = names.map((name) => {
-        const t = CATALOG[name];
-        const parent = t.parent ? ` (parent ${parentHint(name)})` : '';
-        const id = idNames(t).length ? '' : ' (single, no id)';
-        const actions = Object.keys(t.actions || {});
-        const ops =
-            Object.keys(t.ops).join(' ') + (actions.length ? ` | ${actions.join(' ')}` : '');
-        return `${name}${parent}${id}: ${expandNotes(t.description)} [${ops}]`;
-    });
-    return `Resource types, with their operations and, after |, their actions (run with ${toolName('resource_call')}). ${toolName('resource_describe')} with a type gives its schemas and examples.\n\n${lines.join('\n')}`;
+    return Object.fromEntries(Object.keys(ops).map((verb) => [verb, tools[verb]]));
 }
 
 /**
- * The tools, for the types this server mode exposes.
+ * The tools, over the catalog and what the CLI adds to it.
  *
- * @param {{ hooks?: Record<string, import('./resource-hooks.js').ResourceHooks> }} [opts]
+ * @param {{
+ *   hooks?: Record<string, import('./resource-hooks.js').ResourceHooks>,
+ *   types?: Record<string, LocalType>,
+ *   actions?: Record<string, Record<string, LocalAction>>,
+ * }} [opts]
  */
-export function resourceTools({ hooks: extraHooks } = {}) {
+export function resourceTools({ hooks: extraHooks, types: local = {}, actions: extra = {} } = {}) {
+    checkLocal(local, extra);
     const hooks = mergeHooks(extraHooks);
-    const served = new Set(typeNames());
+    const served = new Set([...typeNames(), ...Object.keys(local)]);
+
+    /** Verbs of a type: the catalog's, or the functions a CLI type has. */
+    const opsOf = (name) =>
+        own(local, name)
+            ? Object.fromEntries(
+                  LOCAL_VERBS.filter((v) => typeof local[name][v] === 'function').map((v) => [
+                      v,
+                      'cli',
+                  ]),
+              )
+            : CATALOG[name].ops;
+    /** Actions a CLI adds, to its own types or to the server's. */
+    const localActionsOf = (name) => ({
+        ...(own(local, name)?.actions || {}),
+        ...(own(extra, name) || {}),
+    });
+    const actionNames = (name) => [
+        ...Object.keys(CATALOG[name]?.actions || {}),
+        ...Object.keys(localActionsOf(name)),
+    ];
+    const namesWith = (verb) => [...served].filter((n) => verb in opsOf(n));
+    /** How the parent of a type is written: `<device>`, `<device>/<bucket>`. */
+    const parentOf = (name) => {
+        if (!own(local, name)) return parentHint(name);
+        const p = local[name].parent;
+        return p ? [parentOf(p), idOf(p)].filter(Boolean).join('/') : '';
+    };
+    function idOf(name) {
+        if (!own(local, name)) return idHint(name);
+        return local[name].id ? `<${local[name].id}>` : '';
+    }
+
+    /**
+     * `parent` (and `id`, when needed) as many segments as the type's
+     * location has, none empty, `.`, `..` or with control characters. The
+     * id of a CLI type is one value, which may hold "/" (a path).
+     */
+    function checkLocation(args, { needsId }) {
+        const bad = (part) => !part || part === '.' || part === '..' || CONTROL.test(part);
+        const segments = (value, hint, what) => {
+            if (!hint) return;
+            const parts = value === undefined || value === null ? [] : String(value).split('/');
+            if (parts.length !== hint.split('/').length || parts.some(bad)) {
+                throw inputError(`${what} (${hint}) is required`);
+            }
+        };
+        segments(args.parent, parentOf(args.type), 'parent');
+        if (!needsId || !idOf(args.type)) return;
+        if (own(local, args.type)) {
+            const id = args.id === undefined || args.id === null ? '' : String(args.id);
+            if (!id || CONTROL.test(id))
+                throw inputError(`id (${idOf(args.type)}) is required`);
+        } else {
+            segments(args.id, idOf(args.type), 'id');
+        }
+    }
+
+    function catalogSummary(names) {
+        const lines = names.map((name) => {
+            const t = local[name] || CATALOG[name];
+            const parent = t.parent ? ` (parent ${parentOf(name)})` : '';
+            const id = idOf(name) ? '' : ' (single, no id)';
+            const actions = actionNames(name);
+            const ops =
+                Object.keys(opsOf(name)).join(' ') +
+                (actions.length ? ` | ${actions.join(' ')}` : '');
+            return `${name}${parent}${id}: ${expandNotes(t.description)} [${ops}]`;
+        });
+        return `Resource types, with their operations and, after |, their actions (run with ${toolName('resource_call')}). ${toolName('resource_describe')} with a type gives its schemas and examples.\n\n${lines.join('\n')}`;
+    }
+
+    /** Context of a call on a CLI type or action, with its parent and id checked. */
+    function localContext(args, { needsId = true, state = {} } = {}) {
+        checkLocation(args, { needsId });
+        return {
+            type: args.type,
+            parent: args.parent,
+            id: args.id,
+            user: args.user,
+            filter: args.filter,
+            query: args.query,
+            full: args.full === true,
+            state,
+        };
+    }
+
+    /** What a CLI function answered, as tool text. */
+    const answer = (value) =>
+        value === undefined || value === null || value === ''
+            ? undefined
+            : typeof value === 'string'
+              ? value
+              : JSON.stringify(value, null, 2);
 
     /**
      * Validate the type for a verb and build the hook context.
@@ -258,10 +468,16 @@ export function resourceTools({ hooks: extraHooks } = {}) {
                 `Unknown type "${type ?? ''}". ${toolName('resource_describe')} lists them.`,
             );
         }
-        if (!(verb in CATALOG[type].ops)) {
-            const allowed = Object.keys(CATALOG[type].ops).join(', ');
+        if (!(verb in opsOf(type))) {
+            const allowed = Object.keys(opsOf(type)).join(', ');
             throw inputError(`Type "${type}" does not support ${verb} (it supports: ${allowed})`);
         }
+        // CLI types: located before any hook runs; the id of a create may
+        // still come from the body.
+        if (own(local, type)) {
+            if (args.merge) throw inputError(`${type} takes no merge: send the fields to change`);
+            checkLocation(args, { needsId: verb !== 'list' && verb !== 'create' });
+        }
         const ctx = {
             type,
             parent: args.parent,
@@ -284,6 +500,52 @@ export function resourceTools({ hooks: extraHooks } = {}) {
         return body;
     }
 
+    /** Actions as resource_describe shows them: how to run, what they do, their body. */
+    function describeActions(actions) {
+        return Object.fromEntries(
+            Object.entries(actions).map(([a, spec]) => {
+                const entry = {
+                    run: `${toolName('resource_call')} action "${a}"`,
+                    does: expandNotes(spec.description),
+                };
+                if (typeof spec.run === 'function') {
+                    const on = spec.on || 'item';
+                    if (on !== 'item') entry.id = on === 'collection' ? 'none' : 'optional';
+                    if (spec.body) entry.body = { schema: spec.body };
+                } else if (spec.on === 'collection') {
+                    entry.id = 'none';
+                }
+                return [a, entry];
+            }),
+        );
+    }
+
+    /** resource_describe of a CLI type: everything it says comes from its definition. */
+    async function describeLocal(name) {
+        const t = local[name];
+        const out = { type: name, description: expandNotes(t.description) };
+        if (t.parent) out.parent = `${t.parent} (write it as "${parentOf(name)}")`;
+        out.id = t.id ? idOf(name) : 'none: a single resource of its parent';
+        out.operations = operationsOf(opsOf(name));
+        if (t.schema) out.fields = t.schema;
+        const actions = localActionsOf(name);
+        if (Object.keys(actions).length) out.actions = describeActions(actions);
+        if (t.notes) out.notes = expandNotes(t.notes);
+        if (t.describe) {
+            try {
+                Object.assign(out, await t.describe());
+            } catch (e) {
+                out.reference = `unavailable: ${e instanceof Error ? e.message : String(e)}`;
+            }
+        }
+        return Object.entries(out)
+            .map(
+                ([key, value]) =>
+                    `${key}: ${typeof value === 'string' ? value : JSON.stringify(value)}`,
+            )
+            .join('\n');
+    }
+
     async function toolDescribe(args) {
         if (!args.type) {
             // The overview call: the types, plus the server's guide to its
@@ -302,23 +564,15 @@ export function resourceTools({ hooks: extraHooks } = {}) {
             throw inputError(`Unknown type "${args.type}".\n\n${catalogSummary([...served])}`);
         }
         const name = args.type;
+        if (own(local, name)) return text(capped(await describeLocal(name)));
         const type = CATALOG[name];
         const out = { type: name, description: expandNotes(type.description) };
         const chain = ancestry(name);
         if (chain.length) out.parent = `${chain.join(' > ')} (write it as "${parentHint(name)}")`;
         out.id = idNames(type).length ? idHint(name) : 'none: a single resource of its parent';
-        out.operations = operationsOf(type);
-        if (type.actions) {
-            out.actions = Object.fromEntries(
-                Object.entries(type.actions).map(([a, spec]) => [
-                    a,
-                    {
-                        run: `${toolName('resource_call')} action "${a}"`,
-                        does: expandNotes(spec.description),
-                    },
-                ]),
-            );
-        }
+        out.operations = operationsOf(type.ops);
+        const allActions = { ...(type.actions || {}), ...localActionsOf(name) };
+        if (Object.keys(allActions).length) out.actions = describeActions(allActions);
         if (type.notes) out.notes = expandNotes(type.notes);
         if (type.sdk) {
             out.sdk = await readDoc('dashboard-sdk').then(
@@ -381,7 +635,12 @@ export function resourceTools({ hooks: extraHooks } = {}) {
     }
 
     async function toolList(args) {
-        const { type } = prepare(args, 'list');
+        const { type, ctx } = prepare(args, 'list');
+        if (own(local, type)) {
+            const lctx = localContext(args, { needsId: false, state: ctx.state });
+            const data = (await local[type].list?.(lctx)) ?? [];
+            return text(capped(pageOf(type, data, args, true)));
+        }
         const params = { ...(CATALOG[type].listQuery || {}), ...(args.filter || {}) };
         // Search: the server matches `name` against ids and names (partial,
         // case-insensitive, as a regular expression: escape it). Lists the
@@ -395,6 +654,14 @@ export function resourceTools({ hooks: extraHooks } = {}) {
         let data = await sendList(type, args, params);
         const fields = CATALOG[type].listFields;
         if (fields && Array.isArray(data)) data = data.map((record) => pick(record, fields));
+        return text(pageOf(type, data, args, whole));
+    }
+
+    /**
+     * A list as resource_list answers it: searched here when the source
+     * answers it whole, and paged here when it ignores count/index.
+     */
+    function pageOf(type, data, args, whole) {
         // Lists answered whole: every word must appear in what a record shows.
         if (args.search && whole && Array.isArray(data)) {
             const words = String(args.search).toLowerCase().split(/\s+/).filter(Boolean);
@@ -406,29 +673,32 @@ export function resourceTools({ hooks: extraHooks } = {}) {
         // Some collections ignore count/index and answer everything: page
         // them here so one call cannot flood the conversation.
         const pageSize = args.count ?? 50;
-        if (Array.isArray(data) && data.length > pageSize) {
-            const from = args.index ?? 0;
+        const from = args.index ?? 0;
+        if (Array.isArray(data) && (data.length > pageSize || (whole && from > 0))) {
             const page = data.slice(from, from + pageSize);
             const next =
                 from + page.length < data.length
                     ? `; pass index: ${from + page.length} for more, or narrow it with filter`
                     : '';
-            return text(
-                `${formatList(type, page, Infinity)}\n(${data.length} in total, showing ${from}–${from + page.length - 1}${next})`,
-            );
+            return `${formatList(type, page, Infinity)}\n(${data.length} in total, showing ${from}–${from + page.length - 1}${next})`;
         }
-        return text(formatList(type, data, whole ? Infinity : pageSize));
+        return formatList(type, data, whole ? Infinity : pageSize);
     }
 
     async function toolGet(args) {
         const { type, ctx, hook } = prepare(args, 'get');
-        let record = await send(type, 'get', args);
+        const mine = own(local, type);
+        let record = mine
+            ? await mine.get?.(localContext(args, { state: ctx.state }))
+            : await send(type, 'get', args);
         if (hook.afterGet) record = await hook.afterGet(record, ctx);
-        return text(JSON.stringify(record, null, 2));
+        if (!mine) return text(JSON.stringify(record, null, 2));
+        return text(capped(answer(record) ?? `No ${label(type, args)}.`));
     }
 
     async function toolCreate(args) {
         const { type, ctx, hook } = prepare(args, 'create');
+        if (own(local, type)) return createLocal(args, ctx, hook);
         const t = CATALOG[type];
         let body = bodyArg(args, 'create');
         // `projects` is not a field the server takes on create: set it right
@@ -472,9 +742,46 @@ export function resourceTools({ hooks: extraHooks } = {}) {
         return text(lines.join('\n'));
     }
 
+    async function createLocal(args, ctx, hook) {
+        const t = local[args.type];
+        let body = bodyArg(args, 'create');
+        if (Array.isArray(body)) throw inputError('body must be a JSON object');
+        if (t.id && args.id !== undefined && body[t.id] === undefined)
+            body = { [t.id]: args.id, ...body };
+        // The hook may set or normalise the id: read it after.
+        if (hook.beforeCreate) body = await hook.beforeCreate(body, ctx);
+        const id = args.id ?? (t.id ? body?.[t.id] : undefined);
+        if (t.id && (id === undefined || id === null || id === '')) {
+            throw inputError(`give the ${args.type} id: \`id\`, or the body field "${t.id}"`);
+        }
+        ctx.id = id;
+        const lctx = localContext({ ...args, id }, { state: ctx.state });
+        const result = await t.create?.(body, lctx);
+        const lines = [`Created ${label(args.type, { parent: args.parent, id })}.`];
+        const said = answer(result);
+        if (said) lines.push(said);
+        const note = hook.afterCreate && (await hook.afterCreate(result, ctx));
+        if (note) lines.push('', note);
+        return text(lines.join('\n'));
+    }
+
     async function toolUpdate(args) {
         /** @type {import('./catalog.js').Verb} */
         const verb = args.merge ? 'patch' : 'update';
+        if (own(local, args.type)) {
+            const { type, ctx, hook } = prepare(args, 'update');
+            let body = bodyArg(args, 'update');
+            if (Array.isArray(body)) throw inputError('body must be a JSON object');
+            if (hook.beforeUpdate) body = await hook.beforeUpdate(body, ctx);
+            const result = await local[type].update?.(
+                body,
+                localContext(args, { state: ctx.state }),
+            );
+            const said = answer(result);
+            return text(
+                `Updated ${label(type, args)}: ${Object.keys(body).join(', ')}.${said ? `\n${said}` : ''}`,
+            );
+        }
         const { projects, ...fields } = bodyArg(args, 'update');
         const { type, ctx, hook } = prepare(args, projects !== undefined ? 'projects' : verb);
         const done = [];
@@ -506,8 +813,13 @@ export function resourceTools({ hooks: extraHooks } = {}) {
 
     async function toolDelete(args) {
         const { type, ctx, hook } = prepare(args, 'delete');
-        await send(type, 'delete', args);
+        const mine = own(local, type);
+        const result = mine
+            ? await mine.delete?.(localContext(args, { state: ctx.state }))
+            : await send(type, 'delete', args);
         const lines = [`Deleted ${label(type, args)}.`];
+        const said = mine && answer(result);
+        if (said) lines.push(said);
         const note = hook.afterDelete && (await hook.afterDelete(ctx));
         if (note) lines.push(note);
         return text(lines.join('\n'));
@@ -543,11 +855,36 @@ export function resourceTools({ hooks: extraHooks } = {}) {
 
     async function toolCall(args) {
         const type = args.type;
-        if (!type || !served.has(type) || !CATALOG[type].actions) {
+        const known = typeof type === 'string' && served.has(type);
+        const mine = known ? own(localActionsOf(type), args.action) : undefined;
+        if (mine) {
+            const on = mine.on || 'item';
+            if (on === 'collection' && args.id !== undefined) {
+                throw inputError(`${args.action} takes no id`);
+            }
+            const ctx = localContext(args, { needsId: on === 'item' });
+            const result = await mine.run(args.body, ctx);
+            if (isToolResult(result)) {
+                return {
+                    ...result,
+                    content: result.content.map((c) =>
+                        c.type === 'text' ? { ...c, text: capped(c.text) } : c,
+                    ),
+                };
+            }
+            const said = answer(result);
+            return text(capped(said ?? `Ran ${args.action} on ${label(type, args)}.`));
+        }
+        if (!known || !actionNames(type).length) {
             throw inputError(
                 `Type "${type ?? ''}" has no actions. ${toolName('resource_describe')} lists them after |.`,
             );
         }
+        if (!own(CATALOG[type]?.actions, args.action)) {
+            throw inputError(
+                `Type "${type}" has no action "${args.action}" (it has: ${actionNames(type).join(', ')})`,
+            );
+        }
         const { method, url, query } = actionRequest(type, args.action, args);
         const spec = CATALOG[type].actions?.[args.action];
         const started = Date.now();
@@ -585,7 +922,7 @@ export function resourceTools({ hooks: extraHooks } = {}) {
 
     const typeParam = (verb) => ({
         type: 'string',
-        enum: typeNames({ verb }),
+        enum: verb ? namesWith(verb) : [...served],
         description: 'Resource type (see {tool:resource_describe}).',
     });
     const common = {
@@ -609,7 +946,7 @@ export function resourceTools({ hooks: extraHooks } = {}) {
                 "Describe a resource type: its parent and id, the operations it supports and, from this server's API, the request schemas and examples for create, update and clone. Call it before writing a type for the first time. Without `type`: all types and a guide to the platform's concepts (start here).",
             inputSchema: {
                 type: 'object',
-                properties: { type: { ...typeParam(), enum: [...served] } },
+                properties: { type: typeParam() },
                 required: [],
             },
             handler: toolDescribe,
@@ -650,7 +987,7 @@ export function resourceTools({ hooks: extraHooks } = {}) {
                     full: {
                         type: 'boolean',
                         description:
-                            'Plugin catalog manifests only: also include the product code and the console dashboard (large).',
+                            'Plugin catalog manifests: also include the product code and the console dashboard (large). Types that take it say so in their notes.',
                     },
                     user: common.user,
                 },
@@ -742,7 +1079,7 @@ export function resourceTools({ hooks: extraHooks } = {}) {
                 properties: {
                     type: {
                         type: 'string',
-                        enum: Object.keys(CATALOG).filter((n) => CATALOG[n].actions),
+                        enum: [...served].filter((n) => actionNames(n).length),
                         description: 'Resource type.',
                     },
                     action: { type: 'string', description: 'Action name, e.g. "verify".' },

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@thinger-io/cli-core",
-    "version": "0.2.1",
+    "version": "0.3.0",
     "description": "Shared core of the Thinger.io CLIs and their MCP servers: API client, auth, profiles, generic commands and MCP tools",
     "type": "module",
     "exports": {