@pikku/core 0.12.64 → 0.12.67

package/dist/wirings/gateway/gateway-runner.js

@@ -1,6 +1,6 @@
 import { pikkuState } from '../../pikku-state.js';
 import { NotFoundError, UnauthorizedError } from '../../errors/errors.js';
-import { addFunction } from '../../function/function-runner.js';
+import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
 import { runMiddleware } from '../../middleware-runner.js';
 import { httpRouter } from '../http/routers/http-router.js';
 /**
@@ -9,6 +9,52 @@ import { httpRouter } from '../http/routers/http-router.js';
  * requests share one construction).
  */
 const resolvedAdapters = new WeakMap();
+/**
+ * The generated function id a gateway's handler is registered under.
+ */
+const gatewayHandlerFuncId = (name) => `gateway__${name}__handler`;
+/**
+ * Bridges a session established by gateway middleware onto the wire so the
+ * handler's gate can see it.
+ *
+ * Gateway middleware is the only place a webhook can acquire a session (e.g.
+ * mapping a verified platform sender to a user). Middleware that assigns
+ * `wire.session` needs nothing, but middleware using the idiomatic
+ * `wire.setSession()` writes to the enclosing wiring's session service, which
+ * the handler's own invocation does not read — without this the session would
+ * be silently invisible to `auth` and `scopes`.
+ */
+const bridgeMiddlewareSession = async (wire) => {
+    if (wire.session || !wire.getSession)
+        return;
+    const session = await wire.getSession();
+    if (session) {
+        wire.session = session;
+    }
+};
+/**
+ * Registers a gateway's handler as a real pikku function so that invoking it
+ * goes through the function runner's gate. Without this the handler is called
+ * directly and its own `auth`, `scopes` and `permissions` are never evaluated.
+ *
+ * The handler is registered as sessionless: a gateway's inbound traffic is
+ * platform-authenticated (adapter signature verification), not session-bearing,
+ * so requiring a session by default would break every webhook. A handler that
+ * does need one declares `auth: true`, exactly like `pikkuSessionlessFunc`.
+ * `scopes` and `permissions` are always enforced when declared.
+ */
+const registerGatewayHandler = (config) => {
+    const funcId = gatewayHandlerFuncId(config.name);
+    const funcMeta = pikkuState(null, 'function', 'meta');
+    funcMeta[funcId] = {
+        pikkuFuncId: funcId,
+        inputSchemaName: null,
+        outputSchemaName: null,
+        sessionless: true,
+    };
+    addFunction(funcId, config.func);
+    return funcId;
+};
 export const resolveGatewayAdapter = (config, services) => {
     let resolved = resolvedAdapters.get(config);
     if (!resolved) {
@@ -107,12 +153,13 @@ const wireWebhookGateway = (config) => {
  *  2. Parse body via adapter → GatewayInboundMessage (or null to ignore)
  *  3. Populate `wire.gateway`
  *  4. Run user middleware (which can read `wire.gateway` for auth)
- *  5. Call user func with parsed message
+ *  5. Invoke the handler through the function runner, which enforces its
+ *     `auth`/`scopes`/`permissions` before running it
  *  6. Auto-send response via adapter if func returns outbound content
  */
 const createWebhookPostHandler = (config) => {
-    const { name, func: userFunc, middleware: userMiddleware } = config;
-    const userFuncConfig = userFunc;
+    const { name, middleware: userMiddleware } = config;
+    const handlerFuncId = registerGatewayHandler(config);
     return async (services, data, wire) => {
         const adapter = await resolveGatewayAdapter(config, services);
         // Check for POST-based webhook verification (e.g. Slack url_verification)
@@ -136,23 +183,28 @@ const createWebhookPostHandler = (config) => {
             send: (msg) => adapter.send(parsed.senderId, msg),
         };
         wire.gateway = gateway;
-        // Build combined middleware chain: gateway-level + func-level
-        const allMiddleware = [
-            ...(userMiddleware || []),
-            ...(userFuncConfig.middleware || []),
-        ];
-        const exec = async () => {
-            const result = await userFuncConfig.func(services, parsed, wire);
-            // Auto-send response if the func returns outbound content
-            if (result && (result.text || result.richContent || result.attachments)) {
-                await adapter.send(parsed.senderId, result);
-            }
-            return { ok: true };
+        // Gateway middleware runs first and outside the gate, so it can establish
+        // the session the gate then checks. The handler is invoked through the
+        // function runner, which enforces its auth, scopes and permissions and
+        // applies the handler's own middleware.
+        const invoke = async () => {
+            await bridgeMiddlewareSession(wire);
+            return await runPikkuFunc('gateway', name, handlerFuncId, {
+                singletonServices: services,
+                data: () => parsed,
+                auth: config.auth,
+                wire: wire,
+            });
         };
-        if (allMiddleware.length > 0) {
-            return await runMiddleware(services, wire, allMiddleware, exec);
+        const gatewayMiddleware = userMiddleware;
+        const result = gatewayMiddleware?.length
+            ? await runMiddleware(services, wire, gatewayMiddleware, invoke)
+            : await invoke();
+        // Auto-send response if the func returns outbound content
+        if (result && (result.text || result.richContent || result.attachments)) {
+            await adapter.send(parsed.senderId, result);
         }
-        return await exec();
+        return { ok: true };
     };
 };
 /**
@@ -215,8 +267,8 @@ const wireWebsocketGateway = (config) => {
         connect: { pikkuFuncId: connectFuncId },
         message: { pikkuFuncId: messageFuncId },
     };
-    const userFuncConfig = config.func;
     const userMiddleware = config.middleware;
+    const handlerFuncId = registerGatewayHandler(config);
     // Register onConnect
     addFunction(connectFuncId, {
         auth: false,
@@ -249,22 +301,21 @@ const wireWebsocketGateway = (config) => {
                 },
             };
             wire.gateway = gateway;
-            const allMiddleware = [
-                ...(userMiddleware || []),
-                ...(userFuncConfig.middleware || []),
-            ];
-            const exec = async () => {
-                const result = await userFuncConfig.func(services, parsed, wire);
-                if (result &&
-                    (result.text || result.richContent || result.attachments)) {
-                    wire.channel?.send(result);
-                }
+            const invoke = async () => {
+                await bridgeMiddlewareSession(wire);
+                return await runPikkuFunc('gateway', name, handlerFuncId, {
+                    singletonServices: services,
+                    data: () => parsed,
+                    auth: config.auth,
+                    wire: wire,
+                });
             };
-            if (allMiddleware.length > 0) {
-                await runMiddleware(services, wire, allMiddleware, exec);
-            }
-            else {
-                await exec();
+            const gatewayMiddleware = userMiddleware;
+            const result = gatewayMiddleware?.length
+                ? await runMiddleware(services, wire, gatewayMiddleware, invoke)
+                : await invoke();
+            if (result && (result.text || result.richContent || result.attachments)) {
+                wire.channel?.send(result);
             }
         },
     });
@@ -300,8 +351,8 @@ const wireListenerGateway = (config) => {
  * @param singletonServices - Singleton services to pass to handler/middleware
  */
 export const createListenerMessageHandler = (name, config, singletonServices) => {
-    const userFuncConfig = config.func;
     const userMiddleware = config.middleware;
+    const handlerFuncId = registerGatewayHandler(config);
     return async (rawData) => {
         const adapter = await resolveGatewayAdapter(config, singletonServices);
         const parsed = adapter.parse(rawData);
@@ -315,21 +366,20 @@ export const createListenerMessageHandler = (name, config, singletonServices) =>
             send: (msg) => adapter.send(parsed.senderId, msg),
         };
         wire.gateway = gateway;
-        const allMiddleware = [
-            ...(userMiddleware || []),
-            ...(userFuncConfig.middleware || []),
-        ];
-        const exec = async () => {
-            const result = await userFuncConfig.func(singletonServices, parsed, wire);
-            if (result && (result.text || result.richContent || result.attachments)) {
-                await adapter.send(parsed.senderId, result);
-            }
+        const invoke = async () => {
+            await bridgeMiddlewareSession(wire);
+            return await runPikkuFunc('gateway', name, handlerFuncId, {
+                singletonServices,
+                data: () => parsed,
+                auth: config.auth,
+                wire,
+            });
         };
-        if (allMiddleware.length > 0) {
-            await runMiddleware(singletonServices, wire, allMiddleware, exec);
-        }
-        else {
-            await exec();
+        const result = userMiddleware?.length
+            ? await runMiddleware(singletonServices, wire, userMiddleware, invoke)
+            : await invoke();
+        if (result && (result.text || result.richContent || result.attachments)) {
+            await adapter.send(parsed.senderId, result);
         }
     };
 };

package/dist/wirings/gateway/gateway.types.d.ts

@@ -1,5 +1,5 @@
 import type { CommonWireMeta, CorePikkuMiddleware, CorePikkuMiddlewareGroup, CoreSingletonServices } from '../../types/core.types.js';
-import type { CorePikkuFunctionConfig, CorePermissionGroup, CorePikkuPermission } from '../../function/functions.types.js';
+import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 import type { PikkuHTTPRequest } from '../http/http.types.js';
 /**
  * Attachment in gateway messages (images, files, etc.)
@@ -102,7 +102,7 @@ export type GatewayTransportType = 'webhook' | 'websocket' | 'listener';
 /**
  * Core gateway configuration for wireGateway()
  */
-export type CoreGateway<PikkuFunctionConfig = CorePikkuFunctionConfig<any, any>, PikkuPermission extends CorePikkuPermission = CorePikkuPermission, PikkuMiddleware extends CorePikkuMiddleware = CorePikkuMiddleware> = Partial<Pick<CommonWireMeta, 'title' | 'summary' | 'description' | 'errors'>> & {
+export type CoreGateway<PikkuFunctionConfig = CorePikkuFunctionConfig<any, any>, PikkuMiddleware extends CorePikkuMiddleware = CorePikkuMiddleware> = Partial<Pick<CommonWireMeta, 'title' | 'summary' | 'description' | 'errors'>> & {
     /** Unique name for this gateway */
     name: string;
     /** Transport type */
@@ -117,11 +117,14 @@ export type CoreGateway<PikkuFunctionConfig = CorePikkuFunctionConfig<any, any>,
     func: PikkuFunctionConfig;
     /** Optional middleware chain (e.g., auth) */
     middleware?: CorePikkuMiddlewareGroup<any, any>;
-    /** Optional permissions */
-    permissions?: CorePermissionGroup | PikkuPermission[];
     /** Optional tags for categorization */
     tags?: string[];
-    /** Whether authentication is required (default: true) */
+    /**
+     * Whether the handler requires a session. Left unset, the handler's own
+     * `auth` governs, and a gateway handler is sessionless by default — inbound
+     * gateway traffic is platform-authenticated by the adapter, not
+     * session-bearing. Set `true` to require a session for every message.
+     */
     auth?: boolean;
 };
 /**

package/dist/wirings/http/http.types.d.ts

@@ -71,7 +71,7 @@ export type PikkuQuery<T = Record<string, string | undefined>> = Record<string,
  * @template PikkuFunctionSessionless - The sessionless API function type, defaults to `CorePikkuFunctionSessionless`.
  * @template PikkuPermission - The permission function type, defaults to `CorePikkuPermission`.
  */
-export type CoreHTTPFunctionWiring<In, Out, R extends string, PikkuFunction extends CorePikkuFunction<In, Out, any, any, any> = CorePikkuFunction<In, Out>, PikkuFunctionSessionless extends CorePikkuFunctionSessionless<In, Out, any, any, any> = CorePikkuFunctionSessionless<In, Out>, PikkuPermission extends CorePikkuPermission<In, any, any> = CorePikkuPermission<In, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any>> = (CoreHTTPFunction & {
+export type CoreHTTPFunctionWiring<In, Out, R extends string, PikkuFunction extends CorePikkuFunction<In, Out, any, any, any> = CorePikkuFunction<In, Out>, PikkuFunctionSessionless extends CorePikkuFunctionSessionless<In, Out, any, any, any> = CorePikkuFunctionSessionless<In, Out>, PikkuPermission extends CorePikkuPermission<In, any, any> = CorePikkuPermission<In, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = (CoreHTTPFunction & {
     route: R;
     method: HTTPMethod;
     func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>;
@@ -177,7 +177,7 @@ export interface PikkuHTTPResponse<Out = unknown> {
 /**
  * Single route configuration - supports all wireHTTP options
  */
-export type HTTPRouteConfig<PikkuFunction extends CorePikkuFunction<any, any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any, any> = CorePikkuFunction<any, any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = HTTPRouteBaseConfig & {
+export type HTTPRouteConfig<PikkuFunction extends CorePikkuFunction<any, any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any, any> = CorePikkuFunction<any, any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = HTTPRouteBaseConfig & {
     method: HTTPMethod;
     route: string;
     func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>;
@@ -188,7 +188,7 @@ export type HTTPRouteConfig<PikkuFunction extends CorePikkuFunction<any, any, an
 /**
  * Group-level configuration applied to all routes
  */
-export type HTTPRoutesGroupConfig<PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = {
+export type HTTPRoutesGroupConfig<PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = {
     basePath?: string;
     tags?: string[];
     auth?: boolean;

package/dist/wirings/scope/validate-scope-definitions.d.ts

@@ -3,6 +3,14 @@ import type { FlatScope, ScopeDefinitions, ScopeDefinitionsMeta } from './scope.
  * Flattens declared scope trees into the full list of grantable scope ids,
  * depth-first. Every node is emitted, including intermediate ones.
  *
+ * Ids are unique. A root may legitimately be declared more than once — an addon
+ * and its host app both contributing the same `admin` tree, say — and
+ * {@link validateAndBuildScopeDefinitionsMeta} already guarantees those
+ * declarations are identical, so the second one is redundant rather than
+ * conflicting. Collapsing it here keeps every consumer honest: codegen emits an
+ * object literal keyed by id (duplicates are a TypeScript error), and a
+ * ScopeService syncs one row per scope instead of re-writing the same one.
+ *
  * Used by codegen to build the `ScopeId` union, and by a ScopeService to sync
  * the declared set into its store.
  */

package/dist/wirings/scope/validate-scope-definitions.js

@@ -30,6 +30,14 @@ const flattenNodes = (nodes, prefix, out) => {
  * Flattens declared scope trees into the full list of grantable scope ids,
  * depth-first. Every node is emitted, including intermediate ones.
  *
+ * Ids are unique. A root may legitimately be declared more than once — an addon
+ * and its host app both contributing the same `admin` tree, say — and
+ * {@link validateAndBuildScopeDefinitionsMeta} already guarantees those
+ * declarations are identical, so the second one is redundant rather than
+ * conflicting. Collapsing it here keeps every consumer honest: codegen emits an
+ * object literal keyed by id (duplicates are a TypeScript error), and a
+ * ScopeService syncs one row per scope instead of re-writing the same one.
+ *
  * Used by codegen to build the `ScopeId` union, and by a ScopeService to sync
  * the declared set into its store.
  */
@@ -39,7 +47,14 @@ export const flattenScopeDefinitions = (definitions) => {
         out.push({ id: def.name, description: def.description });
         flattenNodes(def.scopes, def.name, out);
     }
-    return out;
+    const seen = new Set();
+    return out.filter((scope) => {
+        if (seen.has(scope.id)) {
+            return false;
+        }
+        seen.add(scope.id);
+        return true;
+    });
 };
 /**
  * Validates declared scopes and keys them by name.

package/dist/wirings/secret/secret.types.d.ts

@@ -4,6 +4,13 @@ export type CoreSecret<T = unknown> = {
     description?: string;
     secretId: string;
     schema: T;
+    /**
+     * Link to documentation explaining how to obtain this value — a provider's
+     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+     * deploy UIs so a user facing a missing value has somewhere to go instead of
+     * an opaque identifier.
+     */
+    docsUrl?: string;
     /**
      * Optional rotation cadence for this secret, e.g. '1d', '30day', '1w'.
      * Stored in the generated secrets metadata so consumers can tell when a
@@ -25,6 +32,13 @@ export type SecretDefinitionMeta = {
     description?: string;
     secretId: string;
     schema?: Record<string, unknown> | string;
+    /**
+     * Link to documentation explaining how to obtain this value — a provider's
+     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+     * deploy UIs so a user facing a missing value has somewhere to go instead of
+     * an opaque identifier.
+     */
+    docsUrl?: string;
     oauth2?: OAuth2CredentialConfig;
     rotationPeriod?: string;
     sourceFile?: string;

package/dist/wirings/secret/validate-secret-definitions.js

@@ -34,6 +34,7 @@ export function validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup)
                     schema: def.schema,
                     oauth2: def.oauth2,
                     rotationPeriod: def.rotationPeriod,
+                    docsUrl: def.docsUrl,
                     sourceFile: def.sourceFile,
                 };
             }
@@ -49,6 +50,7 @@ export function validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup)
                 schema: def.schema,
                 oauth2: def.oauth2,
                 rotationPeriod: def.rotationPeriod,
+                docsUrl: def.docsUrl,
                 sourceFile: def.sourceFile,
             };
         }

package/dist/wirings/variable/validate-variable-definitions.js

@@ -24,6 +24,7 @@ export function validateAndBuildVariableDefinitionsMeta(definitions, schemaLooku
                     description: def.description,
                     variableId: def.variableId,
                     schema: def.schema,
+                    docsUrl: def.docsUrl,
                     sourceFile: def.sourceFile,
                 };
             }
@@ -37,6 +38,7 @@ export function validateAndBuildVariableDefinitionsMeta(definitions, schemaLooku
                 description: def.description,
                 variableId: def.variableId,
                 schema: def.schema,
+                docsUrl: def.docsUrl,
                 sourceFile: def.sourceFile,
             };
         }

package/dist/wirings/variable/variable.types.d.ts

@@ -4,6 +4,13 @@ export type CoreVariable<T = unknown> = {
     description?: string;
     variableId: string;
     schema: T;
+    /**
+     * Link to documentation explaining how to obtain this value — a provider's
+     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+     * deploy UIs so a user facing a missing value has somewhere to go instead of
+     * an opaque identifier.
+     */
+    docsUrl?: string;
 };
 export type VariableDefinitionMeta = {
     name: string;
@@ -11,6 +18,13 @@ export type VariableDefinitionMeta = {
     description?: string;
     variableId: string;
     schema?: Record<string, unknown> | string;
+    /**
+     * Link to documentation explaining how to obtain this value — a provider's
+     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+     * deploy UIs so a user facing a missing value has somewhere to go instead of
+     * an opaque identifier.
+     */
+    docsUrl?: string;
     sourceFile?: string;
 };
 export type VariableDefinitionsMeta = Record<string, VariableDefinitionMeta>;

package/dist/wirings/workflow/dsl/workflow-dsl.types.d.ts

@@ -15,6 +15,13 @@ export interface WorkflowStepOptions {
     retries?: number;
     /** Delay between retry attempts (e.g., '1s', '2s', '2min') */
     retryDelay?: string | number;
+    /**
+     * RPC to invoke for compensation when this step fails after exhausting its
+     * retries. Mirrors a graph node's `onError`: the handler receives
+     * `{ error: { message } }` and the original error is still thrown, so the
+     * workflow fails — this is compensation, not recovery.
+     */
+    onError?: string;
     /**
      * Run this step as an actor (scenarios). The RPC is sent through the
      * actor's authenticated client over the REAL transport — never dispatched
@@ -214,16 +221,20 @@ export interface ParallelGroupStepMeta {
  */
 export interface FanoutStepMeta {
     type: 'fanout';
-    /** Step name for this fanout */
-    stepName: string;
+    /**
+     * Step name for this fanout. Optional: a fanout is not itself a cached step,
+     * and node ids are step names — borrowing a body step's name would give the
+     * loop and that step the same id, collapsing one onto the other.
+     */
+    stepName?: string;
     /** Source array variable name */
     sourceVar: string;
     /** Iterator variable name */
     itemVar: string;
     /** Execution mode */
     mode: 'parallel' | 'sequential';
-    /** Child step to execute per iteration */
-    child: RpcStepMeta;
+    /** Steps to execute inline per iteration, in order */
+    body: Array<RpcStepMeta | SleepStepMeta | SuspendStepMeta>;
     /** Time between iterations (sequential mode only) */
     timeBetween?: string;
 }
@@ -234,6 +245,12 @@ export interface ReturnStepMeta {
     type: 'return';
     /** Output bindings */
     outputs: Record<string, OutputBinding>;
+    /**
+     * Variables spread into the returned object (`return { ...r }`), or the sole
+     * returned variable (`return r`). Their fields are not enumerable statically,
+     * so they are recorded by name rather than expanded into `outputs`.
+     */
+    spread?: string[];
 }
 /**
  * Inline step metadata (legacy support)
@@ -258,6 +275,13 @@ export interface SleepStepMeta {
     stepName: string;
     /** Sleep duration */
     duration: string | number;
+    /**
+     * Source text of a duration only known at runtime (e.g. a loop variable).
+     * The closure evaluates it, so it is legal DSL; it is kept separate from
+     * `duration` so regenerated code emits it raw rather than as a string
+     * literal, exactly as `expression` does on a set step.
+     */
+    expression?: string;
 }
 /**
  * Cancel step metadata
@@ -276,8 +300,14 @@ export interface SetStepMeta {
     type: 'set';
     /** Variable name to set (must be in context) */
     variable: string;
-    /** Value to assign (literal or expression) */
-    value: unknown;
+    /** Literal value to assign. Mutually exclusive with `expression`. */
+    value?: unknown;
+    /**
+     * Source text of a non-literal assignment (e.g. `count + 1`). Kept separate
+     * from `value` so regenerated code can emit it raw — a string `value` is a
+     * string literal, an `expression` is code.
+     */
+    expression?: string;
 }
 /**
  * Switch case metadata

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -443,6 +443,14 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * loop exits immediately without recording a step error or retrying.
      */
     private runInlineRetryLoop;
+    /**
+     * Run a failed step's compensation handler as a durable step of its own.
+     *
+     * Durable rather than a bare invoke so a replay does not compensate twice —
+     * a handler is typically a refund or a rollback. `onError` is deliberately
+     * not forwarded: a compensation handler cannot itself compensate.
+     */
+    private runStepCompensation;
     private rpcStep;
     private inlineStep;
     private sleepStep;

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -1156,6 +1156,16 @@ export class PikkuWorkflowService {
             }
         }
     }
+    /**
+     * Run a failed step's compensation handler as a durable step of its own.
+     *
+     * Durable rather than a bare invoke so a replay does not compensate twice —
+     * a handler is typically a refund or a rollback. `onError` is deliberately
+     * not forwarded: a compensation handler cannot itself compensate.
+     */
+    async runStepCompensation(runId, stepName, onErrorRpcName, rpcService, error) {
+        await this.rpcStep(runId, `${stepName}:onError`, onErrorRpcName, { error: { message: error.message } }, rpcService, { retries: 0 });
+    }
     async rpcStep(runId, logicalStepName, rpcName, data, rpcService, stepOptions) {
         // Capture the predecessor before nextStepKey advances the lineage to us.
         const fromStepName = this.lastStepName(runId);
@@ -1168,6 +1178,7 @@ export class PikkuWorkflowService {
             retries: stepOptions?.retries ?? DEFAULT_STEP_RETRIES,
             retryDelay: stepOptions?.retryDelay,
             actor: stepOptions?.actor,
+            onError: stepOptions?.onError,
         };
         // Check if step already exists
         let stepState;
@@ -1186,6 +1197,11 @@ export class PikkuWorkflowService {
             // Step failed with retries exhausted - throw error to fail the workflow
             const error = new Error(stepState.error?.message ||
                 `Step '${stepName}' failed after exhausting all retries`);
+            // Compensation, mirroring a graph node's onError: run the handler, then
+            // still throw — the workflow fails either way.
+            if (resolvedStepOptions.onError) {
+                await this.runStepCompensation(runId, stepName, resolvedStepOptions.onError, rpcService, error);
+            }
             // Preserve original error properties if available
             if (stepState.error) {
                 Object.assign(error, stepState.error);

package/dist/wirings/workflow/workflow.types.d.ts

@@ -194,8 +194,6 @@ export type CoreWorkflow<PikkuFunctionConfig extends CorePikkuFunctionConfig<any
     func: PikkuFunctionConfig;
     /** Middleware chain for this workflow */
     middleware?: PikkuFunctionConfig['middleware'];
-    /** Permission requirements */
-    permissions?: PikkuFunctionConfig['permissions'];
     /** Tags for organization and filtering */
     tags?: string[];
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.64",
+  "version": "0.12.67",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -33,6 +33,7 @@
     "./scheduler": "./dist/wirings/scheduler/index.js",
     "./trigger": "./dist/wirings/trigger/index.js",
     "./rpc": "./dist/wirings/rpc/index.js",
+    "./safe-fetch": "./dist/utils/safe-fetch.js",
     "./mcp": "./dist/wirings/mcp/index.js",
     "./ai-agent": "./dist/wirings/ai-agent/index.js",
     "./gateway": "./dist/wirings/gateway/index.js",

package/src/index.ts

@@ -2,6 +2,7 @@
  * @module @pikku/core
  */
 export type {
+  AuthInstance,
   CommonWireMeta,
   CoreConfig,
   CorePikkuMiddleware,
@@ -197,7 +198,7 @@ export {
   addGlobalMiddleware,
 } from './middleware-runner.js'
 export { addGlobalPermission, checkAuthPermissions } from './permissions.js'
-export { verifyScopes } from './scopes.js'
+export { hasScopes, verifyScopes } from './scopes.js'
 export {
   isSerializable,
   stopSingletonServices,

package/src/permissions.test.ts

@@ -6,7 +6,7 @@ import {
   clearPermissionsCache,
   checkAuthPermissions,
 } from './permissions.js'
-import { pikkuState, resetPikkuState } from './pikku-state.js'
+import { resetPikkuState } from './pikku-state.js'
 import { pikkuAuth } from './function/functions.types.js'
 import type { CoreServices, CoreUserSession } from './types/core.types.js'
 import type { CorePermissionGroup } from './function/functions.types.js'
@@ -190,25 +190,31 @@ describe('checkAuthPermissions', () => {
     )
   })
 
-  test('resolves a function-referenced (wire) auth predicate by name', async () => {
-    const store = pikkuState(null, 'misc', 'permissions')
-    store['isAdmin'] = [pikkuAuth(async () => false)] as any
+  test('evaluates a live pikkuAuth predicate from the config group', async () => {
     assert.equal(
       await checkAuthPermissions(
-        [{ type: 'wire', name: 'isAdmin' }],
+        { admin: pikkuAuth(async () => false) as any },
         mockSession,
         mockServices
       ),
       false
     )
+    assert.equal(
+      await checkAuthPermissions(
+        { admin: pikkuAuth(async () => true) as any },
+        mockSession,
+        mockServices
+      ),
+      true
+    )
   })
 
   test('ignores data-dependent permissions (no auth marker)', async () => {
-    const store = pikkuState(null, 'misc', 'permissions')
-    store['ownsRow'] = [async () => false] as any
+    // A bare pikkuPermission carries no __pikkuAuth brand, so it cannot be
+    // evaluated at filter time and must not gate the tool list.
     assert.equal(
       await checkAuthPermissions(
-        [{ type: 'wire', name: 'ownsRow' }],
+        { ownsRow: (async () => false) as any },
         mockSession,
         mockServices
       ),