corsair 0.1.20 → 0.1.22

package/dist/core/client/index.d.ts

@@ -87,13 +87,13 @@ type InferAllIntegrationKeys<Plugins extends readonly CorsairPlugin[]> = UnionTo
 type InferPluginNamespaces<Plugins extends readonly CorsairPlugin[]> = UnionToIntersection<InferPluginNamespace<Plugins[number]>>;
 /**
  * The main Corsair client type that provides access to all plugin APIs, entities, webhooks, and keys.
- * Also includes get_methods() and get_schema() for agent-facing endpoint discovery.
+ * Also includes list_operations() and get_schema() for agent-facing endpoint discovery.
  */
 export type CorsairClient<Plugins extends readonly CorsairPlugin[]> = InferPluginNamespaces<Plugins> & CorsairInspectMethods;
 /**
  * Multi-tenant wrapper that provides a `withTenant` method to scope operations to a specific tenant.
  * Also includes integration-level `keys` for managing shared secrets (OAuth2 client credentials, etc.)
- * Inspect methods (get_methods / get_schema) are available at the root — no need to call withTenant().
+ * Inspect methods (list_operations / get_schema) are available at the root — no need to call withTenant().
  */
 export type CorsairTenantWrapper<Plugins extends readonly CorsairPlugin[]> = {
     withTenant: (tenantId: string) => CorsairClient<Plugins>;

package/dist/core/index.d.ts

@@ -38,7 +38,7 @@ export type { AllProviders, AuthTypes, BaseProviders } from './constants';
 export type { BindEndpoints, BoundEndpointFn, BoundEndpointTree, CorsairContext, CorsairEndpoint, EndpointPathsOf, EndpointTree, } from './endpoints';
 export type { CorsairErrorHandler, ErrorContext, ErrorHandler, ErrorHandlerAndMatchFunction, ErrorMatcher, RetryStrategies, RetryStrategy, } from './errors';
 export type { CorsairInspectMethods, EndpointSchemaResult } from './inspect';
-export type { EnforcePermissionOptions, EnforcePermissionResult } from './permissions';
+export type { EnforcePermissionOptions, EnforcePermissionResult, } from './permissions';
 export type { BeforeHookResult, CorsairIntegration, CorsairKeyBuilder, CorsairKeyBuilderBase, CorsairPlugin, CorsairPluginContext, EndpointHooks, EndpointMetaEntry, EndpointRiskLevel, KeyBuilderContext, PermissionMode, PermissionPolicy, PluginEndpointMeta, PluginPermissionsConfig, RequiredPluginEndpointMeta, RequiredPluginEndpointSchemas, RequiredPluginWebhookSchemas, WebhookHooks, } from './plugins';
 export type { Bivariant, UnionToIntersection } from './utils';
 export type { BindWebhooks, BoundWebhook, BoundWebhookTree, CorsairWebhook, CorsairWebhookHandler, CorsairWebhookMatcher, RawWebhookRequest, WebhookPathsOf, WebhookRequest, WebhookResponse, WebhookTree, } from './webhooks';

package/dist/core/index.d.ts.map

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

package/dist/core/inspect/index.d.ts

@@ -1,4 +1,5 @@
 import type { CorsairPlugin } from '../plugins';
+type DbFieldType = 'string' | 'number' | 'boolean' | 'date';
 export type EndpointSchemaResult = {
     /** Human-readable description of what this endpoint does. */
     description?: string;
@@ -34,102 +35,114 @@ export type WebhookSchemaResult = {
      */
     availableWebhooks?: Record<string, string[]>;
 };
-export type CorsairInspectMethods = {
+export type DbSearchSchemaResult = {
     /**
-     * Returns all available endpoint paths for every registered plugin.
-     * Keys are plugin IDs, values are arrays of full-form paths (plugin.api.group.method), all lowercase.
-     *
-     * @example
-     * corsair.get_methods()
-     * // { slack: ['slack.api.channels.list', 'slack.api.messages.post', ...], github: ['github.api.issues.list', ...] }
+     * What this entity type represents and how to search it.
+     * Pass `limit` and `offset` as numbers for pagination.
      */
-    get_methods(): Record<string, string[]>;
+    description: string;
     /**
-     * Returns all available endpoint paths for a specific plugin.
-     * Paths are full-form (plugin.api.group.method), all lowercase, and can be passed directly to get_schema().
+     * Filterable fields for the search() call.
+     * All active filters are AND-combined. Omit a field to skip filtering on it.
      *
-     * @example
-     * corsair.get_methods('slack')
-     * // ['slack.api.channels.list', 'slack.api.channels.get', 'slack.api.messages.post', ...]
+     * Each operator shorthand: passing a raw value (string/number/boolean/Date) is
+     * equivalent to `{ equals: value }`.
      */
-    get_methods(plugin: string): string[];
+    filters: {
+        /** Filter by the entity's external platform ID (e.g. a Slack channel ID). */
+        entity_id: {
+            type: 'string';
+            operators: string[];
+        };
+        /**
+         * Filter by fields inside the entity's data payload.
+         * Only flat primitive fields are listed — nested objects are not filterable.
+         */
+        data: Record<string, {
+            type: DbFieldType;
+            operators: string[];
+        }>;
+    };
+};
+export type ListOperationsOptions = {
     /**
-     * Returns schema and metadata for a specific endpoint.
-     * Pass the full dot-path including the plugin ID and 'api' segment: 'slack.api.channels.list'.
-     * Casing is ignored — the method string is lowercased before lookup.
-     * If the method is not found, returns an empty result with `availableMethods` listing all valid paths.
-     *
-     * @example
-     * corsair.get_schema('slack.api.channels.list')
-     * // { description: '...', riskLevel: 'read', input: { type: 'object', ... }, output: { ... } }
-     *
-     * corsair.get_schema('slack.api.channels.getHistory') // casing normalised automatically
-     * // { description: '...', riskLevel: 'read', input: { type: 'object', ... }, output: { ... } }
-     *
-     * corsair.get_schema('slack.api.invalid')
-     * // { availableMethods: { slack: ['slack.api.channels.list', ...], ... } }
+     * Filter to a specific plugin by its ID (e.g. 'slack', 'github').
+     * - If the plugin is known but not added to the Corsair instance, a plain string message is returned.
+     * - If the string is completely unrecognised, returns all API endpoints as a fallback.
      */
-    get_schema(method: string): EndpointSchemaResult;
+    plugin?: string;
     /**
-     * Returns all available webhook paths for every registered plugin.
-     * Keys are plugin IDs, values are arrays of full dot-paths (pluginId.group.event).
-     * Pass a path directly to get_webhook_schema() to get its usage example and type info.
-     *
-     * @example
-     * corsair.get_webhooks()
-     * // {
-     * //   slack: ['slack.messages.message', 'slack.channels.created', ...],
-     * //   googlecalendar: ['googlecalendar.onEventChanged', 'googlecalendar.onEventCreated', ...],
-     * // }
+     * Whether to list API endpoints, webhooks, or database entities.
+     * - 'api' (default) — lists callable API endpoint paths
+     * - 'webhooks' — lists receivable webhook event paths
+     * - 'db' — lists searchable database entity paths (one .search per entity type)
      */
-    get_webhooks(): Record<string, string[]>;
+    type?: 'api' | 'webhooks' | 'db';
+};
+export type CorsairInspectMethods = {
     /**
-     * Returns all available webhook paths for a specific plugin.
+     * Lists available operations (API endpoints, webhooks, or database entities) for the configured plugins.
+     *
+     * - No options → all API endpoint paths across every plugin, keyed by plugin ID
+     * - `{ type: 'webhooks' }` → all webhook paths across every plugin, keyed by plugin ID
+     * - `{ type: 'db' }` → all searchable DB entity paths across every plugin, keyed by plugin ID
+     * - `{ plugin: 'slack' }` → Slack API endpoint paths as a flat array
+     * - `{ plugin: 'slack', type: 'webhooks' }` → Slack webhook paths as a flat array
+     * - `{ plugin: 'slack', type: 'db' }` → Slack DB entity search paths as a flat array
+     * - If the plugin is known but not configured, returns a plain string message.
+     * - If the plugin string is completely unrecognised, returns all API endpoints (same as no options).
+     *
+     * API paths use the format `plugin.api.group.method` (e.g. `slack.api.messages.post`).
+     * Webhook paths use the format `plugin.webhooks.group.event` (e.g. `slack.webhooks.messages.message`).
+     * DB paths use the format `plugin.db.entityType.search` (e.g. `slack.db.messages.search`).
+     * All paths can be passed directly to `get_schema()`.
      *
      * @example
-     * corsair.get_webhooks('slack')
-     * // ['slack.messages.message', 'slack.channels.created', ...]
+     * corsair.list_operations()
+     * // { slack: ['slack.api.channels.list', 'slack.api.messages.post', ...], ... }
+     *
+     * corsair.list_operations({ plugin: 'slack' })
+     * // ['slack.api.channels.list', 'slack.api.messages.post', ...]
+     *
+     * corsair.list_operations({ plugin: 'slack', type: 'webhooks' })
+     * // ['slack.webhooks.messages.message', 'slack.webhooks.channels.created', ...]
+     *
+     * corsair.list_operations({ plugin: 'slack', type: 'db' })
+     * // ['slack.db.messages.search', 'slack.db.channels.search', 'slack.db.users.search', ...]
+     *
+     * corsair.list_operations({ plugin: 'unknown' })
+     * // "unknown isn't configured in the Corsair instance."
      */
-    get_webhooks(plugin: string): string[];
+    list_operations(options?: ListOperationsOptions): Record<string, string[]> | string[] | string;
     /**
-     * Returns a ready-to-copy usage example plus type information for a specific webhook.
-     * Pass the dot-path from get_webhooks(): 'slack.messages.message'.
+     * Returns schema and metadata for a specific API endpoint, webhook, or database entity search.
+     * The path format determines which kind of schema is returned:
+     * - API path (`plugin.api.group.method`) → `EndpointSchemaResult`
+     * - Webhook path (`plugin.webhooks.group.event`) → `WebhookSchemaResult`
+     * - DB path (`plugin.db.entityType.search`) → `DbSearchSchemaResult`
+     *
      * Casing is ignored — the path is lowercased before lookup.
+     * If the path is not found, returns an object with available paths for self-correction.
+     *
+     * @example
+     * corsair.get_schema('slack.api.channels.list')
+     * // { description: '...', riskLevel: 'read', input: { type: 'object', ... }, output: { ... } }
      *
-     * The `usage` field is a complete code snippet showing how to configure this webhook
-     * inside the plugin options, with the response.data type embedded as an inline comment.
+     * corsair.get_schema('slack.webhooks.messages.message')
+     * // { description: '...', usage: '...', payload: { ... }, response: { ... } }
      *
-     * If the webhook path is not found, returns `availableWebhooks` for self-correction.
+     * corsair.get_schema('slack.db.messages.search')
+     * // { description: '...', filters: { entity_id: { ... }, data: { text: { type: 'string', operators: [...] }, ... } } }
      *
-     * @example
-     * corsair.get_webhook_schema('slack.messages.message')
-     * // {
-     * //   description: 'Fires when a message is posted',
-     * //   usage: `
-     * //     slack({
-     * //         webhookHooks: {
-     * //             messages: {
-     * //                 message: {
-     * //                     before(ctx, args) {
-     * //                         return { ctx, args };
-     * //                     },
-     * //                     after(ctx, response) {
-     * //                         // response.data:
-     * //                         // { "type": "object", ... }
-     * //                     },
-     * //                 },
-     * //             },
-     * //         },
-     * //     })`,
-     * //   payload: { ... },
-     * //   response: { ... },
-     * // }
+     * corsair.get_schema('slack.api.invalid')
+     * // { availableMethods: { slack: ['slack.api.channels.list', ...], ... } }
      */
-    get_webhook_schema(webhook: string): WebhookSchemaResult;
+    get_schema(path: string): EndpointSchemaResult | WebhookSchemaResult | DbSearchSchemaResult;
 };
 /**
- * Creates the get_methods / get_schema / get_webhooks / get_webhook_schema functions
- * bound to a specific plugin list. Used by both single-tenant and multi-tenant client builders.
+ * Creates the list_operations / get_schema functions bound to a specific plugin list.
+ * Used by both single-tenant and multi-tenant client builders.
  */
 export declare function buildInspectMethods(plugins: readonly CorsairPlugin[]): CorsairInspectMethods;
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/core/inspect/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../core/inspect/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAqB,MAAM,YAAY,CAAC;AAqFnE,MAAM,MAAM,oBAAoB,GAAG;IAClC,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;IAC7C,4CAA4C;IAC5C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IACjC,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iGAAiG;IACjG,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IACnC;;;;;;;OAOG;IACH,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACxC;;;;;;;OAOG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACtC;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,CAAC;IACjD;;;;;;;;;;;OAWG;IACH,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACzC;;;;;;OAMG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,CAAC;CACzD,CAAC;AAkUF;;;GAGG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,SAAS,aAAa,EAAE,GAC/B,qBAAqB,CAgBvB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../core/inspect/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAqB,MAAM,YAAY,CAAC;AA2FnE,KAAK,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAyF5D,MAAM,MAAM,oBAAoB,GAAG;IAClC,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;IAC7C,4CAA4C;IAC5C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IACjC,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iGAAiG;IACjG,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IAClC;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,OAAO,EAAE;QACR,6EAA6E;QAC7E,SAAS,EAAE;YAAE,IAAI,EAAE,QAAQ,CAAC;YAAC,SAAS,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC;QACnD;;;WAGG;QACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE,WAAW,CAAC;YAAC,SAAS,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC,CAAC;KACjE,CAAC;CACF,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IACnC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,KAAK,GAAG,UAAU,GAAG,IAAI,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IACnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,eAAe,CACd,OAAO,CAAC,EAAE,qBAAqB,GAC7B,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC;IAChD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,UAAU,CACT,IAAI,EAAE,MAAM,GACV,oBAAoB,GAAG,mBAAmB,GAAG,oBAAoB,CAAC;CACrE,CAAC;AAmYF;;;GAGG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,SAAS,aAAa,EAAE,GAC/B,qBAAqB,CASvB"}

package/dist/core/inspect/index.js

@@ -1,3 +1,4 @@
+import { BaseProviders } from '../constants';
 // ─────────────────────────────────────────────────────────────────────────────
 // Zod → JSON Schema Converter
 // ─────────────────────────────────────────────────────────────────────────────
@@ -74,6 +75,89 @@ function zodToJsonSchema(schema) {
     }
 }
 // ─────────────────────────────────────────────────────────────────────────────
+// DB Entity Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+const STRING_OPERATORS = ['equals', 'contains', 'startsWith', 'endsWith', 'in'];
+const NUMBER_OPERATORS = ['equals', 'gt', 'gte', 'lt', 'lte', 'in'];
+const BOOLEAN_OPERATORS = ['equals'];
+const DATE_OPERATORS = ['equals', 'before', 'after', 'between'];
+/**
+ * Unwraps Optional/Nullable/Default/Effects wrappers to find the primitive leaf type.
+ * Returns null for complex types (objects, arrays, unions) that are not directly filterable.
+ */
+function getSchemaLeafType(schema) {
+    const def = schema._def;
+    const typeName = def.typeName;
+    switch (typeName) {
+        case 'ZodOptional':
+        case 'ZodNullable':
+        case 'ZodDefault':
+            return getSchemaLeafType(def.innerType);
+        case 'ZodEffects':
+            // Covers z.coerce.date() and other transforms
+            return getSchemaLeafType(def.schema);
+        case 'ZodString':
+            return 'string';
+        case 'ZodNumber':
+            return 'number';
+        case 'ZodBoolean':
+            return 'boolean';
+        case 'ZodDate':
+            return 'date';
+        default:
+            return null;
+    }
+}
+/**
+ * Derives the filterable fields from a Zod object schema.
+ * Only flat primitive fields (string, number, boolean, date) are included.
+ * Nested objects and arrays are skipped — the ORM does not support filtering into them.
+ */
+function buildFilterableFields(schema) {
+    const def = schema._def;
+    const typeName = def.typeName;
+    if (typeName === 'ZodOptional' ||
+        typeName === 'ZodNullable' ||
+        typeName === 'ZodDefault') {
+        return buildFilterableFields(def.innerType);
+    }
+    if (typeName === 'ZodEffects') {
+        return buildFilterableFields(def.schema);
+    }
+    if (typeName !== 'ZodObject')
+        return {};
+    const shape = def.shape();
+    const result = {};
+    for (const [key, fieldSchema] of Object.entries(shape)) {
+        const leafType = getSchemaLeafType(fieldSchema);
+        if (leafType === 'string') {
+            result[key] = { type: 'string', operators: STRING_OPERATORS };
+        }
+        else if (leafType === 'number') {
+            result[key] = { type: 'number', operators: NUMBER_OPERATORS };
+        }
+        else if (leafType === 'boolean') {
+            result[key] = { type: 'boolean', operators: BOOLEAN_OPERATORS };
+        }
+        else if (leafType === 'date') {
+            result[key] = { type: 'date', operators: DATE_OPERATORS };
+        }
+        // Nested objects, arrays, unions — not filterable via ORM, omit them
+    }
+    return result;
+}
+/**
+ * Case-insensitive lookup for an entity name in a schema's entities map.
+ * Entity names are camelCase (e.g. 'userGroups') but agent paths are lowercased.
+ */
+function findEntityCaseInsensitive(entities, lowercasedName) {
+    for (const [key, schema] of Object.entries(entities)) {
+        if (key.toLowerCase() === lowercasedName)
+            return [key, schema];
+    }
+    return undefined;
+}
+// ─────────────────────────────────────────────────────────────────────────────
 // Endpoint Tree Walker
 // ─────────────────────────────────────────────────────────────────────────────
 function walkEndpointTree(tree, pathParts, result) {
@@ -190,43 +274,75 @@ function buildWebhookUsageExample(pluginId, pathParts, responseSchema) {
     return lines.join('\n');
 }
 // ─────────────────────────────────────────────────────────────────────────────
+// Known Plugin Registry
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Set of all plugin IDs that ship with the corsair package.
+ * Derived from BaseProviders (core/constants.ts) — the single source of truth.
+ * Used to distinguish "valid but not configured" from "completely unknown" plugin strings.
+ */
+const KNOWN_PLUGIN_IDS = new Set(BaseProviders);
+// ─────────────────────────────────────────────────────────────────────────────
 // Core Functions
 // ─────────────────────────────────────────────────────────────────────────────
-function getMethods(plugins, plugin) {
-    if (plugin !== undefined) {
-        const found = plugins.find((p) => p.id === plugin);
-        if (!found?.endpoints)
+function listOperations(plugins, options) {
+    const type = options?.type ?? 'api';
+    const pluginId = options?.plugin;
+    if (pluginId !== undefined) {
+        const found = plugins.find((p) => p.id === pluginId);
+        if (!found) {
+            // Known plugin (exists in the package) but not added to this instance
+            if (KNOWN_PLUGIN_IDS.has(pluginId)) {
+                return `This plugin (${pluginId}) is not configured. Please add it to the Corsair instance to see its associated methods.`;
+            }
+            // Completely unknown string — fall through to return all API endpoints
+            return listOperations(plugins);
+        }
+        if (type === 'webhooks') {
+            if (!found.webhooks)
+                return [];
+            const paths = [];
+            walkWebhookTree(found.webhooks, [], paths);
+            return paths.map((path) => `${found.id}.webhooks.${path}`);
+        }
+        if (type === 'db') {
+            const entities = found.schema?.entities;
+            if (!entities)
+                return [];
+            return Object.keys(entities).map((entityName) => `${found.id}.db.${entityName}.search`);
+        }
+        if (!found.endpoints)
             return [];
         const paths = [];
         walkEndpointTree(found.endpoints, [], paths);
         return paths.map((path) => `${found.id}.api.${path.toLowerCase()}`);
     }
     const result = {};
-    for (const p of plugins) {
-        if (!p.endpoints)
-            continue;
-        const paths = [];
-        walkEndpointTree(p.endpoints, [], paths);
-        result[p.id] = paths.map((path) => `${p.id}.api.${path.toLowerCase()}`);
+    if (type === 'webhooks') {
+        for (const p of plugins) {
+            if (!p.webhooks)
+                continue;
+            const paths = [];
+            walkWebhookTree(p.webhooks, [], paths);
+            result[p.id] = paths.map((path) => `${p.id}.webhooks.${path}`);
+        }
     }
-    return result;
-}
-function getWebhooks(plugins, plugin) {
-    if (plugin !== undefined) {
-        const found = plugins.find((p) => p.id === plugin);
-        if (!found?.webhooks)
-            return [];
-        const paths = [];
-        walkWebhookTree(found.webhooks, [], paths);
-        return paths.map((path) => `${found.id}.${path}`);
+    else if (type === 'db') {
+        for (const p of plugins) {
+            const entities = p.schema?.entities;
+            if (!entities)
+                continue;
+            result[p.id] = Object.keys(entities).map((entityName) => `${p.id}.db.${entityName}.search`);
+        }
     }
-    const result = {};
-    for (const p of plugins) {
-        if (!p.webhooks)
-            continue;
-        const paths = [];
-        walkWebhookTree(p.webhooks, [], paths);
-        result[p.id] = paths.map((path) => `${p.id}.${path}`);
+    else {
+        for (const p of plugins) {
+            if (!p.endpoints)
+                continue;
+            const paths = [];
+            walkEndpointTree(p.endpoints, [], paths);
+            result[p.id] = paths.map((path) => `${p.id}.api.${path.toLowerCase()}`);
+        }
     }
     return result;
 }
@@ -244,22 +360,82 @@ function findEndpointCaseInsensitive(record, lowercasedPath) {
     }
     return undefined;
 }
-function getSchema(plugins, method) {
+function getSchema(plugins, path) {
     // Normalise casing so the agent can call with any capitalisation
-    const normalised = method.toLowerCase();
+    const normalised = path.toLowerCase();
     const dotIndex = normalised.indexOf('.');
     if (dotIndex !== -1) {
         const pluginId = normalised.slice(0, dotIndex);
-        let remainder = normalised.slice(dotIndex + 1);
-        // Strip the optional 'api.' segment (present in the new full-form paths)
-        if (remainder.startsWith('api.')) {
-            remainder = remainder.slice(4);
-        }
+        const remainder = normalised.slice(dotIndex + 1);
         const plugin = plugins.find((p) => p.id === pluginId);
         if (plugin) {
-            const meta = findEndpointCaseInsensitive(plugin.endpointMeta, remainder);
-            const schemas = findEndpointCaseInsensitive(plugin.endpointSchemas, remainder);
-            // Valid entry — meta or schemas found
+            // ── DB search path: plugin.db.entityType.search ────────────────────────
+            if (remainder.startsWith('db.')) {
+                const dbPath = remainder.slice(3); // strip 'db.'
+                const lastDot = dbPath.lastIndexOf('.');
+                if (lastDot !== -1) {
+                    const entityNameLower = dbPath.slice(0, lastDot);
+                    const method = dbPath.slice(lastDot + 1);
+                    const entities = plugin.schema?.entities;
+                    if (method === 'search' && entities) {
+                        const entry = findEntityCaseInsensitive(entities, entityNameLower);
+                        if (entry) {
+                            const [entityName, entitySchema] = entry;
+                            return {
+                                description: `Search ${pluginId} ${entityName} stored in the local database. Returns an array of matching records. Pass limit and offset (numbers) for pagination.`,
+                                filters: {
+                                    entity_id: {
+                                        type: 'string',
+                                        operators: STRING_OPERATORS,
+                                    },
+                                    data: buildFilterableFields(entitySchema),
+                                },
+                            };
+                        }
+                    }
+                }
+                // Invalid db path — return available db operations for self-correction
+                return {
+                    availableMethods: listOperations(plugins, {
+                        type: 'db',
+                    }),
+                };
+            }
+            // ── Webhook path: plugin.webhooks.group.event ──────────────────────────
+            if (remainder.startsWith('webhooks.')) {
+                const webhookPathNormalised = remainder.slice(9); // strip 'webhooks.'
+                if (plugin.webhooks) {
+                    const originalPathParts = resolveWebhookPathOriginalCase(plugin.webhooks, webhookPathNormalised.split('.'));
+                    if (originalPathParts !== null) {
+                        const originalPath = originalPathParts.join('.');
+                        const schemas = findEndpointCaseInsensitive(plugin.webhookSchemas, originalPath.toLowerCase());
+                        const responseSchema = schemas?.response
+                            ? zodToJsonSchema(schemas.response)
+                            : null;
+                        return {
+                            description: schemas?.description,
+                            payload: schemas?.payload
+                                ? zodToJsonSchema(schemas.payload)
+                                : undefined,
+                            response: responseSchema ?? undefined,
+                            usage: buildWebhookUsageExample(pluginId, originalPathParts, responseSchema),
+                        };
+                    }
+                }
+                // Invalid webhook path — return available webhooks for self-correction
+                return {
+                    availableWebhooks: listOperations(plugins, {
+                        type: 'webhooks',
+                    }),
+                };
+            }
+            // ── API endpoint path: plugin.api.group.method ─────────────────────────
+            let endpointPath = remainder;
+            if (endpointPath.startsWith('api.')) {
+                endpointPath = endpointPath.slice(4);
+            }
+            const meta = findEndpointCaseInsensitive(plugin.endpointMeta, endpointPath);
+            const schemas = findEndpointCaseInsensitive(plugin.endpointSchemas, endpointPath);
             if (meta || schemas) {
                 return {
                     description: meta?.description,
@@ -271,63 +447,25 @@ function getSchema(plugins, method) {
             }
         }
     }
-    // Invalid or unknown method — return all available methods so the caller can self-correct
-    return { availableMethods: getMethods(plugins) };
-}
-function getWebhookSchema(plugins, webhook) {
-    // Normalise casing so the agent can call with any capitalisation
-    const normalised = webhook.toLowerCase();
-    const dotIndex = normalised.indexOf('.');
-    if (dotIndex !== -1) {
-        const pluginId = normalised.slice(0, dotIndex);
-        const webhookPathNormalised = normalised.slice(dotIndex + 1);
-        const plugin = plugins.find((p) => p.id === pluginId);
-        if (plugin?.webhooks) {
-            // Resolve original-cased key segments from the webhook tree
-            const originalPathParts = resolveWebhookPathOriginalCase(plugin.webhooks, webhookPathNormalised.split('.'));
-            if (originalPathParts !== null) {
-                // Look up optional schemas using original-cased path (case-insensitive fallback)
-                const originalPath = originalPathParts.join('.');
-                const schemas = findEndpointCaseInsensitive(plugin.webhookSchemas, originalPath.toLowerCase());
-                const responseSchema = schemas?.response
-                    ? zodToJsonSchema(schemas.response)
-                    : null;
-                return {
-                    description: schemas?.description,
-                    payload: schemas?.payload
-                        ? zodToJsonSchema(schemas.payload)
-                        : undefined,
-                    response: responseSchema ?? undefined,
-                    usage: buildWebhookUsageExample(pluginId, originalPathParts, responseSchema),
-                };
-            }
-        }
-    }
-    // Invalid or unknown webhook — return all available webhooks so the caller can self-correct
+    // Invalid or unknown path — return all available API methods for self-correction
     return {
-        availableWebhooks: getWebhooks(plugins),
+        availableMethods: listOperations(plugins),
     };
 }
 // ─────────────────────────────────────────────────────────────────────────────
 // Factory — binds inspect methods to a fixed plugin list
 // ─────────────────────────────────────────────────────────────────────────────
 /**
- * Creates the get_methods / get_schema / get_webhooks / get_webhook_schema functions
- * bound to a specific plugin list. Used by both single-tenant and multi-tenant client builders.
+ * Creates the list_operations / get_schema functions bound to a specific plugin list.
+ * Used by both single-tenant and multi-tenant client builders.
  */
 export function buildInspectMethods(plugins) {
     return {
-        get_methods(plugin) {
-            return getMethods(plugins, plugin);
-        },
-        get_schema(method) {
-            return getSchema(plugins, method);
-        },
-        get_webhooks(plugin) {
-            return getWebhooks(plugins, plugin);
+        list_operations(options) {
+            return listOperations(plugins, options);
         },
-        get_webhook_schema(webhook) {
-            return getWebhookSchema(plugins, webhook);
+        get_schema(path) {
+            return getSchema(plugins, path);
         },
     };
 }

package/dist/core/plugins/index.d.ts

@@ -330,7 +330,7 @@ export type CorsairPlugin<Id extends AllProviders = AllProviders, Schema extends
     /**
      * Risk metadata for each endpoint in this plugin. Drives the permission system:
      * riskLevel against the active mode determines the policy (allow / deny / require_approval).
-     * Also used by get_schema() to surface descriptions to the agent.
+     * Also used by list_operations() and get_schema() to surface descriptions to the agent.
      *
      * Keys are dot-notation paths derived from `Endpoints` — only valid paths compile.
      *
@@ -346,7 +346,7 @@ export type CorsairPlugin<Id extends AllProviders = AllProviders, Schema extends
     endpointMeta?: Endpoints extends EndpointTree ? PluginEndpointMeta<Endpoints> : never;
     /**
      * Zod input and output schemas for each endpoint, keyed by dot-notation path.
-     * Used by get_schema() to expose structured type information to the agent.
+     * Used by get_schema() to expose structured endpoint type information to the agent.
      * Keys must match the endpoint dot-paths used in endpointMeta.
      *
      * @example
@@ -363,7 +363,7 @@ export type CorsairPlugin<Id extends AllProviders = AllProviders, Schema extends
     }>;
     /**
      * Zod schemas for each webhook, keyed by dot-notation path.
-     * Used by get_webhook_schema() to expose structured type information to the agent.
+     * Used by get_schema() to expose structured webhook type information to the agent.
      * Keys must match the dot-paths of the webhook tree (e.g. 'messages.message').
      *
      * - `payload` — the type of `request.payload` in the before hook