@pikku/core 0.12.19 → 0.12.21

package/CHANGELOG.md

@@ -1,3 +1,80 @@
+## 0.12.21
+
+### Patch Changes
+
+- 9060165: Agents now declare their model directly as `<provider>/<model>` (e.g. `openai/gpt-4o`). The `models`, `agentDefaults`, and `agentOverrides` config blocks have been removed.
+
+  **Migration:** replace any bare `model: 'alias'` values with the full provider-qualified form and remove those blocks from `pikku.config.json`.
+
+- 9060165: WebSocket channels now expose `setState`, `getState`, and `clearState` — channel state and session lifecycle are managed independently.
+- 9060165: Workflow steps now support per-step `retries` and `retryDelay` configuration. Cloudflare deployments gain Workflow Durable Object bindings for graph-DSL workflows on Workers-for-Platforms, and the deploy bundle now boots cleanly on the Cloudflare Workers runtime.
+
+## 0.12.20
+
+### Patch Changes
+
+- 18acebe: feat(core): scope bare `rpc.invoke()` calls to the caller's addon package
+
+  Addon functions calling `rpc.invoke('foo')` (bare, no colon) previously only
+  resolved against root RPC meta and threw `RPCNotFoundError` for the addon's
+  own functions, forcing authors to prefix every call with their consumer-facing
+  namespace (`'cli:foo'`) — which couples the addon to its caller's `wireAddon({ name })`.
+
+  `ContextAwareRPCService` now carries an optional `packageName` passed through
+  from `runPikkuFunc` via `getContextRPCService`. For bare names from inside an
+  addon, resolution first checks the caller's package function meta, then falls
+  back to root. Applies to both `rpc.invoke()` and `rpc.rpcWithWire()`. Explicit
+  namespaced calls (`'stripe:createCharge'`) and root-namespace calls are unchanged.
+
+- 66d1b4f: feat(content)!: bucket-aware ContentService with typed object args
+
+  BREAKING CHANGE: All `ContentService` methods now take object args with a
+  required `bucket` field. The interface is generic over `TBucket extends string`
+  so callers can constrain bucket names to a typed union.
+
+  Migration:
+
+  ```ts
+  // Before
+  content.getUploadURL(fileKey, contentType)
+  content.signContentKey(key, expiresAt)
+  content.writeFile(assetKey, stream)
+  content.readFile(assetKey)
+  content.deleteFile(assetKey)
+
+  // After
+  content.getUploadURL({ bucket, fileKey, contentType })
+  content.signContentKey({ bucket, contentKey, dateLessThan: expiresAt })
+  content.writeFile({ bucket, key, stream })
+  content.readFile({ bucket, key })
+  content.deleteFile({ bucket, key })
+  ```
+
+  - New exported types: `SignContentKeyArgs`, `SignURLArgs`, `GetUploadURLArgs`,
+    `UploadURLResult`, `BucketKeyArgs`, `WriteFileArgs`, `CopyFileArgs`.
+  - `LocalContent` stores objects under `<base>/<bucket>/<key>`.
+  - `S3Content` and `B2Content` treat the logical bucket as a key prefix within
+    the configured underlying storage bucket.
+  - `workflow-screenshot` addon takes `bucket?` / `key?` input; default bucket
+    resolved from `PIKKU_WORKFLOW_SCREENSHOT_BUCKET` variable, no hardcoded
+    fallback.
+
+- 3e35b99: feat(core): scope bare workflow names to the caller's addon package
+
+  Parallel to the RPC scoping fix for addon functions. Addon code calling
+  `services.workflowService.runToCompletion('myWorkflow', ...)` (bare name,
+  no colon) previously missed workflows registered under the addon's package
+  scope and threw `WorkflowNotFoundError`, forcing authors to hard-code
+  the consumer-facing namespace (`'cli:myWorkflow'`) — which couples the
+  addon to its caller's `wireAddon({ name })`.
+
+  `getOrCreatePackageSingletonServices` in the function-runner now wraps
+  the package's `workflowService` with a Proxy that auto-prefixes bare
+  workflow names on `startWorkflow` / `runToCompletion` with the addon's
+  consumer-defined namespace (looked up from `pikkuState(null, 'addons',
+'packages')`). Explicit `'ns:name'` calls and root-namespace workflows
+  are unchanged.
+
 ## 0.12.19
 
 ### Patch Changes

package/dist/dev/hot-reload.js

@@ -1,6 +1,8 @@
 import { watch } from 'node:fs';
 import { stat, readFile } from 'node:fs/promises';
 import { join, resolve, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { register } from 'tsx/esm/api';
 import { pikkuState } from '../pikku-state.js';
 import { addFunction } from '../function/function-runner.js';
 import { clearMiddlewareCache } from '../middleware-runner.js';
@@ -35,8 +37,19 @@ const findCompiledFile = async (tsFile, srcDir, pikkuDir) => {
 // Use data: URLs to import modules. This bypasses TypeScript loaders
 // (e.g. tsx) that intercept file:// imports and break dynamic ESM loading.
 // Each import gets unique content so there's no module cache to worry about.
-const reimportModule = async (filePath) => {
+let tsxRegistered = false;
+const ensureTsxRegistered = () => {
+    if (tsxRegistered)
+        return;
+    register();
+    tsxRegistered = true;
+};
+const reimportModule = async (filePath, useTsx = false) => {
     try {
+        if (useTsx) {
+            ensureTsxRegistered();
+            return await import(`${pathToFileURL(resolve(filePath)).href}?t=${Date.now()}`);
+        }
         const content = await readFile(resolve(filePath), 'utf-8');
         const dataUrl = 'data:text/javascript;base64,' + Buffer.from(content).toString('base64');
         return await import(dataUrl);
@@ -64,13 +77,14 @@ export async function pikkuDevReloader(options) {
         if (!srcDir)
             return;
         const compiledFile = await findCompiledFile(changedTsFile, srcDir, absPikkuDir);
-        if (!compiledFile) {
-            logger.warn(`Could not find compiled JS for: ${relative(process.cwd(), changedTsFile)}`);
-            return;
+        const importPath = compiledFile ?? changedTsFile;
+        const usedTsxFallback = !compiledFile;
+        if (usedTsxFallback) {
+            logger.debug(`Hot-reload using tsx fallback for: ${relative(process.cwd(), changedTsFile)}`);
         }
-        const mod = await reimportModule(compiledFile);
+        const mod = await reimportModule(importPath, usedTsxFallback);
         if (!mod) {
-            logger.error(`Failed to import: ${relative(process.cwd(), compiledFile)} (keeping old code)`);
+            logger.error(`Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)`);
             return;
         }
         let schemasChanged = false;

package/dist/errors/error-handler.d.ts

@@ -22,7 +22,7 @@ export interface ErrorDetails {
  * @param error - The error to add.
  * @param details - The details of the error.
  */
-export declare const addError: (error: any, { status, message }: ErrorDetails) => void;
+export declare const addError: (error: any, { status, message, mcpCode }: ErrorDetails) => void;
 /**
  * Adds multiple errors to the API errors map.
  * @param errors - An array of errors and their details.

package/dist/errors/error-handler.js

@@ -18,8 +18,8 @@ export class PikkuError extends Error {
  * @param error - The error to add.
  * @param details - The details of the error.
  */
-export const addError = (error, { status, message }) => {
-    pikkuState(null, 'misc', 'errors').set(error, { status, message });
+export const addError = (error, { status, message, mcpCode }) => {
+    pikkuState(null, 'misc', 'errors').set(error, mcpCode === undefined ? { status, message } : { status, message, mcpCode });
 };
 /**
  * Adds multiple errors to the API errors map.

package/dist/function/function-runner.js

@@ -37,6 +37,51 @@ async function resolveSession(wire, singletonServices, sessionService) {
  * @param parentServices - The parent/caller's singleton services (used as base)
  * @returns The package's singleton services
  */
+/**
+ * Find the consumer-defined namespace (from wireAddon) for a given addon package.
+ * Returns null if the package isn't registered as an addon.
+ */
+const findAddonNamespaceForPackage = (packageName) => {
+    const addons = pikkuState(null, 'addons', 'packages');
+    if (!addons)
+        return null;
+    for (const [namespace, cfg] of addons.entries()) {
+        if (cfg?.package === packageName)
+            return namespace;
+    }
+    return null;
+};
+/**
+ * Wrap a workflow service so that bare workflow names passed from inside an
+ * addon function are auto-prefixed with the addon's consumer-facing namespace.
+ * Without this, `runToCompletion('myWorkflow')` from inside an addon misses
+ * the workflow registered under the addon's package scope and throws
+ * WorkflowNotFoundError — forcing addons to hardcode their consumer-defined
+ * namespace, which couples the addon to its caller.
+ *
+ * Explicit `'ns:name'` and bare names that already exist in root meta are
+ * unaffected; only bare names that would otherwise miss resolution get
+ * prefixed.
+ */
+const wrapWorkflowServiceForPackage = (service, packageName) => {
+    return new Proxy(service, {
+        get(target, prop, receiver) {
+            if (prop === 'startWorkflow' || prop === 'runToCompletion') {
+                const original = Reflect.get(target, prop, receiver);
+                return function (name, ...rest) {
+                    if (typeof name === 'string' && !name.includes(':')) {
+                        const namespace = findAddonNamespaceForPackage(packageName);
+                        if (namespace) {
+                            name = `${namespace}:${name}`;
+                        }
+                    }
+                    return original.call(this, name, ...rest);
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+};
 const getOrCreatePackageSingletonServices = async (packageName, parentServices) => {
     // Check if we already have cached singleton services for this package
     const cachedServices = pikkuState(packageName, 'package', 'singletonServices');
@@ -56,6 +101,12 @@ const getOrCreatePackageSingletonServices = async (packageName, parentServices)
     }
     // Create singleton services for the package, passing parent services as existing
     const packageServices = await factories.createSingletonServices(config, parentServices);
+    // Wrap workflowService so that bare names used inside the addon's functions
+    // resolve to workflows registered under the addon's package scope.
+    if (packageServices.workflowService &&
+        typeof packageServices.workflowService === 'object') {
+        packageServices.workflowService = wrapWorkflowServiceForPackage(packageServices.workflowService, packageName);
+    }
     // Cache the services
     pikkuState(packageName, 'package', 'singletonServices', packageServices);
     return packageServices;
@@ -223,11 +274,10 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
             const services = wireServices && Object.keys(wireServices).length > 0
                 ? { ...resolvedSingletonServices, ...wireServices }
                 : resolvedSingletonServices;
+            const callerPackageName = packageName;
             Object.defineProperty(resolvedWire, 'rpc', {
                 get() {
-                    const rpc = rpcService.getContextRPCService(services, resolvedWire, {
-                        sessionService,
-                    });
+                    const rpc = rpcService.getContextRPCService(services, resolvedWire, { sessionService }, 0, callerPackageName);
                     Object.defineProperty(resolvedWire, 'rpc', {
                         value: rpc,
                         writable: true,

package/dist/function/functions.types.d.ts

@@ -135,10 +135,11 @@ export type CorePikkuAuthConfig<Services extends CoreSingletonServices = CoreSer
 export declare const pikkuAuth: <Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession>(auth: CorePikkuAuth<Services, Session> | CorePikkuAuthConfig<Services, Session>) => CorePikkuPermission<any, Services, any>;
 export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> = Record<string, PikkuPermission | PikkuPermission[]> | undefined;
 export type CorePikkuFunctionConfig<PikkuFunction extends 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>, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined> = {
-    /** Optional human-readable title for the function */
+    /** Short human-readable name (e.g. "Create Todo") */
     title?: string;
-    /** Optional description of what the function does */
+    /** Longer-form description of what the function does */
     description?: string;
+    /** Explicit logical name override; lets multiple exports share a versioned base */
     override?: string;
     version?: number;
     tags?: string[];

package/dist/index.d.ts

@@ -24,7 +24,7 @@ export type { QueueService } from './wirings/queue/queue.types.js';
 export type { JWTService } from './services/jwt-service.js';
 export type { SecretService } from './services/secret-service.js';
 export type { VariablesService } from './services/variables-service.js';
-export type { ContentService } from './services/content-service.js';
+export type { ContentService, SignContentKeyArgs, SignURLArgs, GetUploadURLArgs, UploadURLResult, BucketKeyArgs, WriteFileArgs, CopyFileArgs, } from './services/content-service.js';
 export type { DeploymentService } from './services/deployment-service.js';
 export type { WorkflowService } from './services/workflow-service.js';
 export type { GatewayService } from './services/gateway-service.js';
@@ -40,8 +40,8 @@ export { createGraph } from './wirings/workflow/graph/graph-node.js';
 export { wireAddon } from './wirings/rpc/wire-addon.js';
 export type { WireAddonConfig } from './wirings/rpc/wire-addon.js';
 export type { PikkuPackageState } from './types/state.types.js';
-export { runMiddleware, addMiddleware } from './middleware-runner.js';
-export { addPermission, checkAuthPermissions } from './permissions.js';
+export { runMiddleware, addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, } from './middleware-runner.js';
+export { addTagPermission, addTagPermission as addPermission, addGlobalPermission, checkAuthPermissions, } from './permissions.js';
 export { isSerializable, stopSingletonServices } from './utils.js';
 export { getSingletonServices, getCreateWireServices } from './pikku-state.js';
 export { type ScheduledTaskInfo, type ScheduledTaskSummary, } from './services/scheduler-service.js';

package/dist/index.js

@@ -13,8 +13,8 @@ export { runScheduledTask } from './wirings/scheduler/scheduler-runner.js';
 export { NotFoundError } from './errors/errors.js';
 export { createGraph } from './wirings/workflow/graph/graph-node.js';
 export { wireAddon } from './wirings/rpc/wire-addon.js';
-export { runMiddleware, addMiddleware } from './middleware-runner.js';
-export { addPermission, checkAuthPermissions } from './permissions.js';
+export { runMiddleware, addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, } from './middleware-runner.js';
+export { addTagPermission, addTagPermission as addPermission, addGlobalPermission, checkAuthPermissions, } from './permissions.js';
 export { isSerializable, stopSingletonServices } from './utils.js';
 export { getSingletonServices, getCreateWireServices } from './pikku-state.js';
 export { SchedulerService } from './services/scheduler-service.js';

package/dist/middleware/index.d.ts

@@ -4,5 +4,5 @@ export { authBearer } from './auth-bearer.js';
 export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
 export { cors } from './cors.js';
 export { telemetryOuter, telemetryInner } from './telemetry.js';
-export { addMiddleware, runMiddleware } from '../middleware-runner.js';
-export { addPermission } from '../permissions.js';
+export { addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, runMiddleware, } from '../middleware-runner.js';
+export { addTagPermission, addTagPermission as addPermission, addGlobalPermission, } from '../permissions.js';

package/dist/middleware/index.js

@@ -4,5 +4,5 @@ export { authBearer } from './auth-bearer.js';
 export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
 export { cors } from './cors.js';
 export { telemetryOuter, telemetryInner } from './telemetry.js';
-export { addMiddleware, runMiddleware } from '../middleware-runner.js';
-export { addPermission } from '../permissions.js';
+export { addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, runMiddleware, } from '../middleware-runner.js';
+export { addTagPermission, addTagPermission as addPermission, addGlobalPermission, } from '../permissions.js';

package/dist/middleware/telemetry.d.ts

@@ -11,7 +11,7 @@
  * @example
  * ```typescript
  * import { telemetryOuter } from '@pikku/core/middleware'
- * addMiddleware('myTag', [telemetryOuter()])
+ * addTagMiddleware('myTag', [telemetryOuter()])
  * ```
  */
 export declare const telemetryOuter: import("../types/core.types.js").CorePikkuMiddlewareFactory<void | {
@@ -34,7 +34,7 @@ export declare const telemetryOuter: import("../types/core.types.js").CorePikkuM
  * @example
  * ```typescript
  * import { telemetryInner } from '@pikku/core/middleware'
- * addMiddleware('myTag', [telemetryInner()])
+ * addTagMiddleware('myTag', [telemetryInner()])
  * ```
  */
 export declare const telemetryInner: import("../types/core.types.js").CorePikkuMiddlewareFactory<void | {

package/dist/middleware/telemetry.js

@@ -12,7 +12,7 @@ import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
  * @example
  * ```typescript
  * import { telemetryOuter } from '@pikku/core/middleware'
- * addMiddleware('myTag', [telemetryOuter()])
+ * addTagMiddleware('myTag', [telemetryOuter()])
  * ```
  */
 export const telemetryOuter = pikkuMiddlewareFactory(({ environmentId, orgId } = {}) => {
@@ -67,7 +67,7 @@ export const telemetryOuter = pikkuMiddlewareFactory(({ environmentId, orgId } =
  * @example
  * ```typescript
  * import { telemetryInner } from '@pikku/core/middleware'
- * addMiddleware('myTag', [telemetryInner()])
+ * addTagMiddleware('myTag', [telemetryInner()])
  * ```
  */
 export const telemetryInner = pikkuMiddlewareFactory(({ environmentId, orgId } = {}) => {

package/dist/middleware-runner.d.ts

@@ -18,39 +18,27 @@ import type { CoreSingletonServices, PikkuWire, CorePikkuMiddleware, CorePikkuMi
  */
 export declare const runMiddleware: <Middleware extends CorePikkuMiddleware>(services: CoreSingletonServices, wire: PikkuWire, middlewares: readonly Middleware[], main?: () => Promise<unknown>) => Promise<unknown>;
 /**
- * Registers global middleware for a specific tag.
+ * Registers tag-scoped middleware. Applies to any wiring (HTTP, Channel,
+ * Queue, Scheduler, MCP, CLI, Workflow, Agent) that carries the matching tag.
  *
- * This function registers middleware at runtime that will be applied to
- * any wiring (HTTP, Channel, Queue, Scheduler, MCP, CLI) that includes the matching tag.
+ * For tree-shaking, wrap in a factory:
+ * `export const x = () => addTagMiddleware('tag', [...])`
  *
- * For tree-shaking benefits, wrap in a factory function:
- * `export const x = () => addMiddleware('tag', [...])`
- *
- * Accepts an array that can contain:
- * - Direct middleware functions (CorePikkuMiddleware)
- * - Factory middleware functions (CorePikkuMiddlewareFactory)
- *
- * @template PikkuMiddleware The middleware type.
- * @param {string} tag - The tag that the middleware should apply to.
- * @param {CorePikkuMiddlewareGroup} middleware - Array of middleware for this tag.
+ * @example
+ * export const adminMiddleware = () => addTagMiddleware('admin', [authMiddleware])
+ */
+export declare const addTagMiddleware: <PikkuMiddleware extends CorePikkuMiddleware>(tag: string, middleware: CorePikkuMiddlewareGroup, packageName?: string | null) => CorePikkuMiddlewareGroup;
+/**
+ * Registers wire-agnostic global middleware. Runs at the top of every
+ * wiring's middleware chain — before wire-, tag-, and function-level
+ * entries — across HTTP, Channel, Queue, Scheduler, MCP, CLI, Workflow, Agent.
  *
- * @returns {CorePikkuMiddlewareGroup} The middleware array (for chaining/wrapping).
+ * Resolution order: global → wire → tag → function.
  *
  * @example
- * ```typescript
- * // Recommended: tree-shakeable
- * export const adminMiddleware = () => addMiddleware('admin', [
- *   authMiddleware,
- *   loggingMiddleware({ level: 'info' })
- * ])
- *
- * // Also works: no tree-shaking
- * export const apiMiddleware = addMiddleware('api', [
- *   rateLimitMiddleware
- * ])
- * ```
+ * addGlobalMiddleware([telemetryMiddleware])
  */
-export declare const addMiddleware: <PikkuMiddleware extends CorePikkuMiddleware>(tag: string, middleware: CorePikkuMiddlewareGroup, packageName?: string | null) => CorePikkuMiddlewareGroup;
+export declare const addGlobalMiddleware: <PikkuMiddleware extends CorePikkuMiddleware>(middleware: CorePikkuMiddlewareGroup, packageName?: string | null) => CorePikkuMiddlewareGroup;
 export declare const clearMiddlewareCache: () => void;
 /**
  * Combines wiring-specific middleware with function-level middleware.

package/dist/middleware-runner.js

@@ -58,43 +58,35 @@ const isSortedByPriority = (middlewares) => {
     return true;
 };
 /**
- * Registers global middleware for a specific tag.
+ * Registers tag-scoped middleware. Applies to any wiring (HTTP, Channel,
+ * Queue, Scheduler, MCP, CLI, Workflow, Agent) that carries the matching tag.
  *
- * This function registers middleware at runtime that will be applied to
- * any wiring (HTTP, Channel, Queue, Scheduler, MCP, CLI) that includes the matching tag.
- *
- * For tree-shaking benefits, wrap in a factory function:
- * `export const x = () => addMiddleware('tag', [...])`
- *
- * Accepts an array that can contain:
- * - Direct middleware functions (CorePikkuMiddleware)
- * - Factory middleware functions (CorePikkuMiddlewareFactory)
- *
- * @template PikkuMiddleware The middleware type.
- * @param {string} tag - The tag that the middleware should apply to.
- * @param {CorePikkuMiddlewareGroup} middleware - Array of middleware for this tag.
- *
- * @returns {CorePikkuMiddlewareGroup} The middleware array (for chaining/wrapping).
+ * For tree-shaking, wrap in a factory:
+ * `export const x = () => addTagMiddleware('tag', [...])`
  *
  * @example
- * ```typescript
- * // Recommended: tree-shakeable
- * export const adminMiddleware = () => addMiddleware('admin', [
- *   authMiddleware,
- *   loggingMiddleware({ level: 'info' })
- * ])
- *
- * // Also works: no tree-shaking
- * export const apiMiddleware = addMiddleware('api', [
- *   rateLimitMiddleware
- * ])
- * ```
+ * export const adminMiddleware = () => addTagMiddleware('admin', [authMiddleware])
  */
-export const addMiddleware = (tag, middleware, packageName = null) => {
+export const addTagMiddleware = (tag, middleware, packageName = null) => {
     const tagGroups = pikkuState(packageName, 'middleware', 'tagGroup');
     tagGroups[tag] = middleware;
     return middleware;
 };
+/**
+ * Registers wire-agnostic global middleware. Runs at the top of every
+ * wiring's middleware chain — before wire-, tag-, and function-level
+ * entries — across HTTP, Channel, Queue, Scheduler, MCP, CLI, Workflow, Agent.
+ *
+ * Resolution order: global → wire → tag → function.
+ *
+ * @example
+ * addGlobalMiddleware([telemetryMiddleware])
+ */
+export const addGlobalMiddleware = (middleware, packageName = null) => {
+    const state = pikkuState(packageName, 'middleware', 'global');
+    state.push(...middleware);
+    return middleware;
+};
 /**
  * Retrieves a registered middleware function by its name.
  *
@@ -156,7 +148,10 @@ export const combineMiddleware = (wireType, uid, { wireInheritedMiddleware, wire
         return middlewareCache[wireType][uid];
     }
     const resolved = [];
-    // 1. Resolve wire inherited middleware (HTTP + tag groups + individual wire middleware)
+    const globals = pikkuState(packageName, 'middleware', 'global');
+    if (globals && globals.length > 0) {
+        resolved.push(...globals);
+    }
     if (wireInheritedMiddleware) {
         for (const meta of wireInheritedMiddleware) {
             if (meta.type === 'http') {

package/dist/permissions.d.ts

@@ -1,34 +1,27 @@
 import type { CoreServices, CoreUserSession, PikkuWiringTypes, PermissionMetadata, PikkuWire } from './types/core.types.js';
 import type { CorePermissionGroup, CorePikkuPermission } from './function/functions.types.js';
 /**
- * Adds global permissions for a specific tag.
+ * Registers tag-scoped permissions. Applies to any wiring that carries the
+ * matching tag.
  *
- * This function allows you to register permissions that will be applied to
- * any wiring (HTTP, Channel, Queue, Scheduler, MCP) that includes the matching tag.
+ * For tree-shaking, wrap in a factory:
+ * `export const x = () => addTagPermission('tag', [...])`
  *
- * For tree-shaking benefits, wrap in a factory function:
- * `export const x = () => addPermission('tag', [...])`
- *
- * @param {string} tag - The tag that the permissions should apply to.
- * @param {any[]} permissions - The permissions array to apply for the specified tag.
+ * @example
+ * export const adminPermissions = () => addTagPermission('admin', [adminPermission])
+ */
+export declare const addTagPermission: (tag: string, permissions: CorePermissionGroup | CorePikkuPermission[], packageName?: string | null) => CorePermissionGroup | CorePikkuPermission[];
+/**
+ * Registers wire-agnostic global permissions. Runs at the top of every
+ * wiring's permission resolution — before wire-, tag-, and function-level
+ * entries — across all wire types.
  *
- * @returns {CorePermissionGroup | CorePikkuPermission[]} The permissions (for chaining/wrapping).
+ * Resolution order: global → wire → tag → function.
  *
  * @example
- * ```typescript
- * // Recommended: tree-shakeable
- * export const adminPermissions = () => addPermission('admin', [
- *   adminPermission,
- *   rolePermission({ role: 'admin' })
- * ])
- *
- * // Also works: no tree-shaking
- * export const apiPermissions = addPermission('api', [
- *   readPermission
- * ])
- * ```
+ * addGlobalPermission([signedInUser])
  */
-export declare const addPermission: (tag: string, permissions: CorePermissionGroup | CorePikkuPermission[], packageName?: string | null) => CorePermissionGroup | CorePikkuPermission[];
+export declare const addGlobalPermission: (permissions: CorePermissionGroup | CorePikkuPermission[], packageName?: string | null) => CorePermissionGroup | CorePikkuPermission[];
 export declare const clearPermissionsCache: () => void;
 /**
  * Runs permission checks using combined permissions from all sources.

package/dist/permissions.js

@@ -53,34 +53,16 @@ const getPermissionByName = (name) => {
     return undefined;
 };
 /**
- * Adds global permissions for a specific tag.
+ * Registers tag-scoped permissions. Applies to any wiring that carries the
+ * matching tag.
  *
- * This function allows you to register permissions that will be applied to
- * any wiring (HTTP, Channel, Queue, Scheduler, MCP) that includes the matching tag.
- *
- * For tree-shaking benefits, wrap in a factory function:
- * `export const x = () => addPermission('tag', [...])`
- *
- * @param {string} tag - The tag that the permissions should apply to.
- * @param {any[]} permissions - The permissions array to apply for the specified tag.
- *
- * @returns {CorePermissionGroup | CorePikkuPermission[]} The permissions (for chaining/wrapping).
+ * For tree-shaking, wrap in a factory:
+ * `export const x = () => addTagPermission('tag', [...])`
  *
  * @example
- * ```typescript
- * // Recommended: tree-shakeable
- * export const adminPermissions = () => addPermission('admin', [
- *   adminPermission,
- *   rolePermission({ role: 'admin' })
- * ])
- *
- * // Also works: no tree-shaking
- * export const apiPermissions = addPermission('api', [
- *   readPermission
- * ])
- * ```
+ * export const adminPermissions = () => addTagPermission('admin', [adminPermission])
  */
-export const addPermission = (tag, permissions, packageName = null) => {
+export const addTagPermission = (tag, permissions, packageName = null) => {
     const tagGroups = pikkuState(packageName, 'permissions', 'tagGroup');
     if (tagGroups[tag]) {
         throw new Error(`Permissions for tag '${tag}' already exist. Use a different tag or remove the existing permissions first.`);
@@ -88,6 +70,26 @@ export const addPermission = (tag, permissions, packageName = null) => {
     tagGroups[tag] = permissions;
     return permissions;
 };
+/**
+ * Registers wire-agnostic global permissions. Runs at the top of every
+ * wiring's permission resolution — before wire-, tag-, and function-level
+ * entries — across all wire types.
+ *
+ * Resolution order: global → wire → tag → function.
+ *
+ * @example
+ * addGlobalPermission([signedInUser])
+ */
+export const addGlobalPermission = (permissions, packageName = null) => {
+    const state = pikkuState(packageName, 'permissions', 'global');
+    if (Array.isArray(permissions)) {
+        state.push(...permissions);
+    }
+    else {
+        state.push(permissions);
+    }
+    return permissions;
+};
 const combinedPermissionsCache = {
     http: {},
     rpc: {},
@@ -135,7 +137,10 @@ const combinePermissions = (wireType, uid, { wireInheritedPermissions, wirePermi
         return combinedPermissionsCache[wireType][uid];
     }
     const resolved = [];
-    // 1. Resolve wire inherited permissions (HTTP + tag groups + individual wire permissions)
+    const globals = pikkuState(packageName, 'permissions', 'global');
+    if (globals && globals.length > 0) {
+        resolved.push(...globals);
+    }
     if (wireInheritedPermissions) {
         for (const meta of wireInheritedPermissions) {
             if (meta.type === 'http') {

package/dist/pikku-request.js

@@ -13,7 +13,7 @@ export class PikkuRequest {
      * @returns A promise that resolves to an object containing the combined data.
      */
     async data() {
-        if (!this.#data) {
+        if (this.#data === undefined) {
             throw new Error('Data not found');
         }
         return this.#data;

package/dist/pikku-state.js

@@ -105,6 +105,7 @@ const createEmptyPackageState = () => ({
     middleware: {
         tagGroup: {},
         httpGroup: {},
+        global: [],
     },
     channelMiddleware: {
         tagGroup: {},
@@ -112,6 +113,7 @@ const createEmptyPackageState = () => ({
     permissions: {
         tagGroup: {},
         httpGroup: {},
+        global: [],
     },
     misc: {
         errors: new Map(),
@@ -120,9 +122,6 @@ const createEmptyPackageState = () => ({
         channelMiddleware: {},
         permissions: {},
     },
-    models: {
-        config: null,
-    },
     package: {
         factories: null,
         singletonServices: null,

package/dist/services/ai-agent-runner-service.d.ts

@@ -36,6 +36,7 @@ export type AIAgentStepResult = {
         outputTokens: number;
     };
     finishReason: 'stop' | 'tool-calls' | 'length' | 'error' | 'unknown';
+    reasoningContent?: string;
 };
 export interface AIAgentRunnerService {
     stream(params: AIAgentRunnerParams, channel: AIStreamChannel): Promise<AIAgentStepResult>;