@objectstack/runtime 10.3.0 → 11.1.0

package/dist/index.d.cts

@@ -918,12 +918,16 @@ interface HttpDispatcherOptions {
     scopeManager?: EnvironmentScopeManager;
 }
 /**
- * @deprecated Use `createDispatcherPlugin()` from `@objectstack/runtime` instead.
- * This class will be removed in v2. Prefer the plugin-based approach:
- * ```ts
- * import { createDispatcherPlugin } from '@objectstack/runtime';
- * kernel.use(createDispatcherPlugin({ prefix: '/api/v1' }));
- * ```
+ * The HTTP dispatch engine — translates an inbound (method, path, body, ctx)
+ * request into a kernel response. Used directly by the framework's HTTP adapters
+ * (express / fastify / nextjs / nestjs / nuxt / sveltekit / hono) and plugin-msw,
+ * which need a *callable* dispatcher.
+ *
+ * NOTE: `createDispatcherPlugin()` is a different thing — a kernel plugin that
+ * registers routes on a kernel-hosted HTTP server. It is NOT a drop-in for
+ * adapters. Retiring this public class behind a `createHttpDispatcher()` factory
+ * is tracked in #2380 (a deliberate adapter-API change, not yet done) — so this
+ * is intentionally NOT marked `@deprecated` while no working replacement exists.
  */
 declare class HttpDispatcher {
     private kernel;
@@ -1014,6 +1018,49 @@ declare class HttpDispatcher {
      * engine access.
      */
     private buildMcpBridge;
+    /**
+     * [ADR-0066 D4] Shared capability gate for an action invocation. Returns a
+     * human-readable error string when the caller's `systemPermissions` don't
+     * cover the action's declared `requiredPermissions`, or `null` when allowed.
+     * System/engine self-invocation (`isSystem`) bypasses; an action without
+     * `requiredPermissions` is ungated. Single-sourced so the REST `/actions/...`
+     * route and the MCP `run_action` bridge enforce the SAME declaration.
+     */
+    private actionPermissionError;
+    /**
+     * Whether an action has a headless invocation path (so MCP can run it).
+     * Mirrors the supported-type set of the (now cloud-side) action-tools
+     * bridge: `script` needs a handler binding (`target`) or an inline `body`;
+     * `flow` needs a `target` and an automation service. UI-only types
+     * (`url`, `modal`, `form`) and `api` have no server dispatch here.
+     */
+    private isHeadlessInvokableAction;
+    /** True when an action is destructive by author signal/heuristic (HITL hint). */
+    private actionLooksDestructive;
+    /** Project an action's declarative metadata into a lean MCP summary. */
+    private summarizeAction;
+    /** Map an ObjectStack field type to a JSON-Schema primitive (conservative). */
+    private jsonTypeOf;
+    /** Resolve an action's params into LLM-facing summaries (field-backed types resolved). */
+    private summarizeActionParams;
+    /** Slim engine facade matching the ActionContext.engine shape handlers expect. */
+    private buildActionEngineFacade;
+    /**
+     * Resolve + invoke a business action by its declarative name for the MCP
+     * `run_action` tool. Enforces the ADR-0066 D4 capability gate and RLS as the
+     * caller, loads the subject record under RLS for row-context actions, and
+     * dispatches through the framework's `engine.executeAction` (script/body) or
+     * automation flow runner (flow). Throws on denial / not-found / handler
+     * failure so the tool surfaces a clean tool-error. No service-ai dependency.
+     */
+    private invokeBusinessAction;
+    /**
+     * Find an action's declarative definition by name across object metadata,
+     * optionally scoped to a single object. Returns the action plus its owning
+     * object name, or `null`. Throws when the name is ambiguous across objects
+     * and no `objectName` was supplied (so `run_action` can ask for one).
+     */
+    private resolveActionByName;
     /**
      * Generate a `sys_api_key` and return the raw secret EXACTLY ONCE
      * (`POST /keys`). This is the only mint path — the raw key is never stored
@@ -1077,6 +1124,13 @@ declare class HttpDispatcher {
      * response object that callers should surface directly — no further
      * dispatch happens.
      */
+    /**
+     * ADR-0069 — returns a 403 response when the resolved session is blocked by
+     * an auth-policy gate (expired password / required MFA) on a non-allow-listed
+     * path, else null. Mirrors the REST `enforceAuth` seam so REST + dispatcher
+     * (MCP, GraphQL) enforce consistently. Fails open on any lookup error.
+     */
+    private enforceAuthGate;
     private enforceProjectMembership;
     /**
      * Generates the discovery JSON response for the API root.

package/dist/index.d.ts

@@ -918,12 +918,16 @@ interface HttpDispatcherOptions {
     scopeManager?: EnvironmentScopeManager;
 }
 /**
- * @deprecated Use `createDispatcherPlugin()` from `@objectstack/runtime` instead.
- * This class will be removed in v2. Prefer the plugin-based approach:
- * ```ts
- * import { createDispatcherPlugin } from '@objectstack/runtime';
- * kernel.use(createDispatcherPlugin({ prefix: '/api/v1' }));
- * ```
+ * The HTTP dispatch engine — translates an inbound (method, path, body, ctx)
+ * request into a kernel response. Used directly by the framework's HTTP adapters
+ * (express / fastify / nextjs / nestjs / nuxt / sveltekit / hono) and plugin-msw,
+ * which need a *callable* dispatcher.
+ *
+ * NOTE: `createDispatcherPlugin()` is a different thing — a kernel plugin that
+ * registers routes on a kernel-hosted HTTP server. It is NOT a drop-in for
+ * adapters. Retiring this public class behind a `createHttpDispatcher()` factory
+ * is tracked in #2380 (a deliberate adapter-API change, not yet done) — so this
+ * is intentionally NOT marked `@deprecated` while no working replacement exists.
  */
 declare class HttpDispatcher {
     private kernel;
@@ -1014,6 +1018,49 @@ declare class HttpDispatcher {
      * engine access.
      */
     private buildMcpBridge;
+    /**
+     * [ADR-0066 D4] Shared capability gate for an action invocation. Returns a
+     * human-readable error string when the caller's `systemPermissions` don't
+     * cover the action's declared `requiredPermissions`, or `null` when allowed.
+     * System/engine self-invocation (`isSystem`) bypasses; an action without
+     * `requiredPermissions` is ungated. Single-sourced so the REST `/actions/...`
+     * route and the MCP `run_action` bridge enforce the SAME declaration.
+     */
+    private actionPermissionError;
+    /**
+     * Whether an action has a headless invocation path (so MCP can run it).
+     * Mirrors the supported-type set of the (now cloud-side) action-tools
+     * bridge: `script` needs a handler binding (`target`) or an inline `body`;
+     * `flow` needs a `target` and an automation service. UI-only types
+     * (`url`, `modal`, `form`) and `api` have no server dispatch here.
+     */
+    private isHeadlessInvokableAction;
+    /** True when an action is destructive by author signal/heuristic (HITL hint). */
+    private actionLooksDestructive;
+    /** Project an action's declarative metadata into a lean MCP summary. */
+    private summarizeAction;
+    /** Map an ObjectStack field type to a JSON-Schema primitive (conservative). */
+    private jsonTypeOf;
+    /** Resolve an action's params into LLM-facing summaries (field-backed types resolved). */
+    private summarizeActionParams;
+    /** Slim engine facade matching the ActionContext.engine shape handlers expect. */
+    private buildActionEngineFacade;
+    /**
+     * Resolve + invoke a business action by its declarative name for the MCP
+     * `run_action` tool. Enforces the ADR-0066 D4 capability gate and RLS as the
+     * caller, loads the subject record under RLS for row-context actions, and
+     * dispatches through the framework's `engine.executeAction` (script/body) or
+     * automation flow runner (flow). Throws on denial / not-found / handler
+     * failure so the tool surfaces a clean tool-error. No service-ai dependency.
+     */
+    private invokeBusinessAction;
+    /**
+     * Find an action's declarative definition by name across object metadata,
+     * optionally scoped to a single object. Returns the action plus its owning
+     * object name, or `null`. Throws when the name is ambiguous across objects
+     * and no `objectName` was supplied (so `run_action` can ask for one).
+     */
+    private resolveActionByName;
     /**
      * Generate a `sys_api_key` and return the raw secret EXACTLY ONCE
      * (`POST /keys`). This is the only mint path — the raw key is never stored
@@ -1077,6 +1124,13 @@ declare class HttpDispatcher {
      * response object that callers should surface directly — no further
      * dispatch happens.
      */
+    /**
+     * ADR-0069 — returns a 403 response when the resolved session is blocked by
+     * an auth-policy gate (expired password / required MFA) on a non-allow-listed
+     * path, else null. Mirrors the REST `enforceAuth` seam so REST + dispatcher
+     * (MCP, GraphQL) enforce consistently. Fails open on any lookup error.
+     */
+    private enforceAuthGate;
     private enforceProjectMembership;
     /**
      * Generates the discovery JSON response for the API root.