@pikku/core 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
+## 0.12.0
+
+### New Features
+
+- AI agents with `pikkuAIAgent()` — define agents with tools, sub-agents, memory, structured output, and streaming via SSE
+- AI middleware hooks (`pikkuAIMiddleware`) for input, stream, and output transformation
+- Tool approval flow — suspend agent execution pending human approval
+- Channel middleware (`pikkuChannelMiddleware`) for intercepting and transforming channel events
+- Remote RPC — call functions across servers with `rpc.remote()` and `DeploymentService`
+- HTTP route groups with `wireHTTPRoutes` for shared basePath, tags, and auth
+- Workflow graph engine with `createGraph()` type-safe builder
+- Workflow HTTP helpers: `workflow()`, `workflowStart()`, `workflowStatus()`, `graphStart()`
+- Workflow DSL with rich step types (branch, parallel, fanout, switch, filter)
+- Trigger system with `wireTrigger()` and `wireTriggerSource()`
+- OAuth2 support with `wireOAuth2Credential` and `OAuth2Client`
+- Secret and variable declarations with `wireSecret()` and `wireVariable()`
+- `TypedSecretService` and `TypedVariablesService` for compile-time validated access
+- `defineCLICommands` and `defineChannelRoutes` for external composition
+- Built-in CORS middleware
+- `disabled: true` support on all wirings and functions
+- `createWireServices` and `createConfig` are now optional
+- `InMemoryWorkflowService` and `InMemoryTriggerService` for testing
+
+### Breaking Changes
+
+- `PikkuInteraction` → `PikkuWire`, `CreateSessionServices` → `CreateWireServices`
+- `wireForgeCredential` → `wireCredential`
+- `startWorkflowByWire` → `startWorkflowByHTTPWire`
+- Renamed all `forge` → `node` naming
+- Renamed `credential` → `secret` across core types
+- `WorkflowService.createRun` signature changed (new `inline`, `graphHash` params)
+- Auth enforced by default for `pikkuFunc`
+
 ## 0.11.0
 
+## 0.11.2
+
+### Patch Changes
+
+- db9c7bf: Add workflow graph system with type-safe builder
+
+### Features
+
+- f35e89da: Add workflow graph system with type-safe builder
+  - `createGraph<RPCMap>()` for building workflow graphs with full type safety
+  - `wireWorkflowGraph()` for registering workflow graphs
+  - `graphNode()` helper for type-safe node creation
+  - Graph scheduler for execution (continueGraph, startWorkflowGraph)
+  - TypedRef for type-safe input refs in workflow graphs
+  - `setBranchTaken` added to WorkflowService interface
+  - Trigger runner for workflow triggers
+
+### Breaking Changes
+
+- Rename `pikkuWorkflowFunc` to `pikkuWorkflowComplexFunc`
+- Rename `pikkuWorkflowDSTFunc` to `pikkuWorkflowFunc`
+
 ## 0.11.1
 
 ### Patch Changes

package/dist/crypto-utils.d.ts

@@ -0,0 +1,2 @@
+export declare const encryptJSON: (secret: string, value: unknown) => Promise<string>;
+export declare const decryptJSON: <T>(secret: string, token: string) => Promise<T>;

package/dist/crypto-utils.js

@@ -0,0 +1,78 @@
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const getSubtle = () => {
+    const crypto = globalThis.crypto;
+    if (!crypto?.subtle) {
+        throw new Error('WebCrypto not available');
+    }
+    return crypto.subtle;
+};
+const base64Encode = (bytes) => {
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(bytes).toString('base64');
+    }
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+};
+const base64Decode = (input) => {
+    if (typeof Buffer !== 'undefined') {
+        return new Uint8Array(Buffer.from(input, 'base64'));
+    }
+    const binary = atob(input);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+};
+const toBase64Url = (bytes) => {
+    return base64Encode(bytes)
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/g, '');
+};
+const fromBase64Url = (input) => {
+    let base64 = input.replace(/-/g, '+').replace(/_/g, '/');
+    while (base64.length % 4 !== 0)
+        base64 += '=';
+    return base64Decode(base64);
+};
+const deriveKey = async (secret) => {
+    const subtle = getSubtle();
+    const hash = await subtle.digest('SHA-256', encoder.encode(secret));
+    return subtle.importKey('raw', hash, { name: 'AES-GCM' }, false, [
+        'encrypt',
+        'decrypt',
+    ]);
+};
+export const encryptJSON = async (secret, value) => {
+    const crypto = globalThis.crypto;
+    if (!crypto?.getRandomValues) {
+        throw new Error('WebCrypto not available');
+    }
+    const subtle = getSubtle();
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const key = await deriveKey(secret);
+    const plaintext = encoder.encode(JSON.stringify(value));
+    const encrypted = await subtle.encrypt({ name: 'AES-GCM', iv }, key, plaintext);
+    const cipherBytes = new Uint8Array(encrypted);
+    const out = new Uint8Array(iv.length + cipherBytes.length);
+    out.set(iv, 0);
+    out.set(cipherBytes, iv.length);
+    return toBase64Url(out);
+};
+export const decryptJSON = async (secret, token) => {
+    const subtle = getSubtle();
+    const data = fromBase64Url(token);
+    if (data.length < 13) {
+        throw new Error('Invalid encrypted payload');
+    }
+    const iv = data.slice(0, 12);
+    const ciphertext = data.slice(12);
+    const key = await deriveKey(secret);
+    const decrypted = await subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext);
+    return JSON.parse(decoder.decode(new Uint8Array(decrypted)));
+};

package/dist/errors/error-handler.js

@@ -19,7 +19,7 @@ export class PikkuError extends Error {
  * @param details - The details of the error.
  */
 export const addError = (error, { status, message }) => {
-    pikkuState('misc', 'errors').set(error, { status, message });
+    pikkuState(null, 'misc', 'errors').set(error, { status, message });
 };
 /**
  * Adds multiple errors to the API errors map.
@@ -36,10 +36,10 @@ export const addErrors = (errors) => {
  * @returns An object containing the status and message, or undefined if the error is not found.
  */
 export const getErrorResponse = (error) => {
-    const errors = Array.from(pikkuState('misc', 'errors').entries());
+    const errors = Array.from(pikkuState(null, 'misc', 'errors').entries());
     const foundError = errors.find(([e]) => e.name === error.constructor.name);
     if (foundError) {
         return foundError[1];
     }
-    return pikkuState('misc', 'errors').get(error);
+    return pikkuState(null, 'misc', 'errors').get(error);
 };

package/dist/errors/errors.d.ts

@@ -4,6 +4,8 @@
 import { PikkuError } from './error-handler.js';
 export declare class InvalidMiddlewareWireError extends PikkuError {
 }
+export declare class PikkuMissingMetaError extends PikkuError {
+}
 /**
  * The server cannot or will not process the request due to client error (e.g., malformed request syntax).
  * @group Error
@@ -190,3 +192,9 @@ export declare class HTTPVersionNotSupportedError extends PikkuError {
  */
 export declare class MaxComputeTimeReachedError extends PikkuError {
 }
+/**
+ * A required schema was not found during validation.
+ * @group Error
+ */
+export declare class MissingSchemaError extends PikkuError {
+}

package/dist/errors/errors.js

@@ -8,6 +8,12 @@ addError(InvalidMiddlewareWireError, {
     status: 500,
     message: 'The middleware wire is invalid for the current wiring type.',
 });
+export class PikkuMissingMetaError extends PikkuError {
+}
+addError(PikkuMissingMetaError, {
+    status: 500,
+    message: 'Required metadata is missing',
+});
 /**
  * The server cannot or will not process the request due to client error (e.g., malformed request syntax).
  * @group Error
@@ -321,3 +327,13 @@ addError(MaxComputeTimeReachedError, {
     status: 524,
     message: 'The server took too long to complete the request, reaching the maximum compute time allowed.',
 });
+/**
+ * A required schema was not found during validation.
+ * @group Error
+ */
+export class MissingSchemaError extends PikkuError {
+}
+addError(MissingSchemaError, {
+    status: 500,
+    message: 'A required schema was not found. Ensure schema generation has been run.',
+});

package/dist/errors/index.d.ts

@@ -1,2 +1 @@
-export * from './error-handler.js';
 export * from './errors.js';

package/dist/errors/index.js

@@ -1,2 +1 @@
-export * from './error-handler.js';
 export * from './errors.js';

package/dist/function/function-runner.d.ts

@@ -1,18 +1,25 @@
 import { CoreServices, CoreUserSession, CorePikkuMiddleware, PikkuWiringTypes, PikkuWire, MiddlewareMetadata, PermissionMetadata, CoreSingletonServices, CreateWireServices } from '../types/core.types.js';
+import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js';
 import { CorePermissionGroup, CorePikkuFunctionConfig, CorePikkuPermission } from './functions.types.js';
 import { SessionService } from '../services/user-session-service.js';
-export declare const addFunction: (funcName: string, funcConfig: CorePikkuFunctionConfig<any, any>) => void;
-export declare const runPikkuFuncDirectly: <In, Out>(funcName: string, allServices: CoreServices, wire: PikkuWire, data: In, userSession?: SessionService<CoreUserSession>) => Promise<Out>;
-export declare const runPikkuFunc: <In = any, Out = any>(wireType: PikkuWiringTypes, wireId: string, funcName: string, { singletonServices, createWireServices, data, auth: wiringAuth, inheritedMiddleware, wireMiddleware, inheritedPermissions, wirePermissions, coerceDataFromSchema, tags, wire, }: {
+export declare const addFunction: (funcName: string, funcConfig: CorePikkuFunctionConfig<any, any>, packageName?: string | null) => void;
+export declare const getFunctionNames: (packageName?: string | null) => string[];
+export declare const getAllFunctionNames: () => string[];
+export declare const runPikkuFuncDirectly: <In, Out>(funcName: string, allServices: CoreServices, wire: PikkuWire, data: In, userSession?: SessionService<CoreUserSession>, packageName?: string | null) => Promise<Out>;
+export declare const runPikkuFunc: <In = any, Out = any>(wireType: PikkuWiringTypes, wireId: string, funcName: string, { singletonServices, createWireServices, data, auth: wiringAuth, inheritedMiddleware, wireMiddleware, inheritedChannelMiddleware, wireChannelMiddleware, inheritedPermissions, wirePermissions, coerceDataFromSchema, tags, wire, sessionService, packageName, }: {
     singletonServices: CoreSingletonServices;
     createWireServices?: CreateWireServices;
     data: () => Promise<In> | In;
     auth?: boolean;
     inheritedMiddleware?: MiddlewareMetadata[];
     wireMiddleware?: CorePikkuMiddleware[];
+    inheritedChannelMiddleware?: MiddlewareMetadata[];
+    wireChannelMiddleware?: CorePikkuChannelMiddleware[];
     inheritedPermissions?: PermissionMetadata[];
     wirePermissions?: CorePermissionGroup | CorePikkuPermission[];
     coerceDataFromSchema?: boolean;
     tags?: string[];
     wire: PikkuWire;
+    sessionService?: SessionService<CoreUserSession>;
+    packageName?: string | null;
 }) => Promise<Out>;

package/dist/function/function-runner.js

@@ -1,34 +1,121 @@
 import { runMiddleware, combineMiddleware } from '../middleware-runner.js';
+import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../wirings/channel/channel-middleware-runner.js';
 import { runPermissions } from '../permissions.js';
 import { pikkuState } from '../pikku-state.js';
 import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js';
+import { parseVersionedId } from '../version.js';
+import { createFunctionSessionWireProps, } from '../services/user-session-service.js';
 import { ForbiddenError } from '../errors/errors.js';
 import { rpcService } from '../wirings/rpc/rpc-runner.js';
 import { closeWireServices } from '../utils.js';
-export const addFunction = (funcName, funcConfig) => {
-    pikkuState('function', 'functions').set(funcName, funcConfig);
+/**
+ * Get or create singleton services for an external package.
+ * Services are cached in pikkuState to avoid recreation on each call.
+ *
+ * @param packageName - The external package name
+ * @param parentServices - The parent/caller's singleton services (used as base)
+ * @returns The package's singleton services
+ */
+const getOrCreatePackageSingletonServices = async (packageName, parentServices) => {
+    // Check if we already have cached singleton services for this package
+    const cachedServices = pikkuState(packageName, 'package', 'singletonServices');
+    if (cachedServices) {
+        return cachedServices;
+    }
+    // Get the package's service factories
+    const factories = pikkuState(packageName, 'package', 'factories');
+    if (!factories || !factories.createSingletonServices) {
+        // No factories registered, use parent services
+        return parentServices;
+    }
+    // Create config for the package (use parent config if no factory)
+    let config = parentServices.config;
+    if (factories.createConfig) {
+        config = await factories.createConfig(parentServices.variables);
+    }
+    // Create singleton services for the package, passing parent services as existing
+    const packageServices = await factories.createSingletonServices(config, parentServices);
+    // Cache the services
+    pikkuState(packageName, 'package', 'singletonServices', packageServices);
+    return packageServices;
+};
+export const addFunction = (funcName, funcConfig, packageName = null) => {
+    pikkuState(packageName, 'function', 'functions').set(funcName, funcConfig);
+};
+export const getFunctionNames = (packageName = null) => {
+    const functionsMeta = pikkuState(packageName, 'function', 'meta');
+    return Object.keys(functionsMeta);
 };
-export const runPikkuFuncDirectly = async (funcName, allServices, wire, data, userSession) => {
-    const funcConfig = pikkuState('function', 'functions').get(funcName);
+export const getAllFunctionNames = () => {
+    const functions = [];
+    const mainFunctionsMeta = pikkuState(null, 'function', 'meta');
+    functions.push(...Object.keys(mainFunctionsMeta));
+    const externalPackages = pikkuState(null, 'rpc', 'externalPackages');
+    for (const [namespace, config] of externalPackages) {
+        const packageFunctionsMeta = pikkuState(config.package, 'function', 'meta');
+        for (const funcName of Object.keys(packageFunctionsMeta)) {
+            functions.push(`${namespace}:${funcName}`);
+        }
+    }
+    return functions;
+};
+export const runPikkuFuncDirectly = async (funcName, allServices, wire, data, userSession, packageName = null) => {
+    const funcConfig = pikkuState(packageName, 'function', 'functions').get(funcName);
     if (!funcConfig) {
         throw new Error(`Function not found: ${funcName}`);
     }
-    // Inject session into wire
     const wireWithSession = {
         ...wire,
-        session: userSession,
+        ...(userSession && createFunctionSessionWireProps(userSession)),
     };
     return (await funcConfig.func(allServices, data, wireWithSession));
 };
-export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServices, createWireServices, data, auth: wiringAuth, inheritedMiddleware, wireMiddleware, inheritedPermissions, wirePermissions, coerceDataFromSchema, tags = [], wire, }) => {
-    const funcConfig = pikkuState('function', 'functions').get(funcName);
+export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServices, createWireServices, data, auth: wiringAuth, inheritedMiddleware, wireMiddleware, inheritedChannelMiddleware, wireChannelMiddleware, inheritedPermissions, wirePermissions, coerceDataFromSchema, tags = [], wire, sessionService, packageName = null, }) => {
+    wire = {
+        ...wire,
+        wireType: wire.wireType ?? wireType,
+        wireId: wire.wireId ?? wireId,
+    };
+    const funcMap = pikkuState(packageName, 'function', 'functions');
+    let funcConfig = funcMap.get(funcName);
+    const allMeta = pikkuState(packageName, 'function', 'meta');
+    let funcMeta = allMeta[funcName];
+    if (!funcConfig || !funcMeta) {
+        const { baseName, version } = parseVersionedId(funcName);
+        if (version !== null) {
+            funcConfig = funcConfig || funcMap.get(baseName);
+            funcMeta = funcMeta || allMeta[baseName];
+            if (funcConfig && funcMeta) {
+                singletonServices.logger.warn(`Version '${funcName}' not registered, resolved to '${baseName}'`);
+            }
+        }
+    }
     if (!funcConfig) {
         throw new Error(`Function not found: ${funcName}`);
     }
-    const funcMeta = pikkuState('function', 'meta')[funcName];
     if (!funcMeta) {
         throw new Error(`Function meta not found: ${funcName}`);
     }
+    // For external packages, get or create their singleton services
+    const resolvedSingletonServices = packageName
+        ? await getOrCreatePackageSingletonServices(packageName, singletonServices)
+        : singletonServices;
+    // Get the package's createWireServices if available
+    let resolvedCreateWireServices = createWireServices;
+    if (packageName) {
+        const factories = pikkuState(packageName, 'package', 'factories');
+        if (factories?.createWireServices) {
+            resolvedCreateWireServices = factories.createWireServices;
+        }
+    }
+    const allChannelMiddleware = combineChannelMiddleware(wireType, wireId, {
+        wireInheritedChannelMiddleware: inheritedChannelMiddleware,
+        wireChannelMiddleware,
+        packageName,
+    });
+    const resolvedWire = allChannelMiddleware.length > 0 && wire.channel
+        ? wrapChannelWithMiddleware(wire, resolvedSingletonServices, allChannelMiddleware)
+        : wire;
     // Convert tags to PermissionMetadata and merge with inheritedPermissions
     const mergedInheritedPermissions = [
         ...(inheritedPermissions || []),
@@ -36,22 +123,36 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
     ];
     // Helper function to run permissions and execute the function
     const executeFunction = async () => {
-        const initialSession = wire.session?.freezeInitial();
-        const wireWithInitialSession = {
-            ...wire,
-            initialSession,
+        const functionWireProps = sessionService
+            ? createFunctionSessionWireProps(sessionService)
+            : undefined;
+        const wireWithSession = {
+            ...resolvedWire,
+            ...functionWireProps,
         };
-        if (wiringAuth === true || funcConfig.auth === true) {
-            // This means it was explicitly enabled in either wiring or function and has to be respected
-            if (!initialSession) {
+        const session = wireWithSession.session;
+        if (funcMeta.sessionless) {
+            if (wiringAuth === true || funcConfig.auth === true) {
+                if (!session) {
+                    throw new ForbiddenError('Authentication required');
+                }
+            }
+        }
+        else if (funcMeta.sessionless === false) {
+            if (wiringAuth === false || funcConfig.auth === false) {
+                resolvedSingletonServices.logger.warn(`Function '${funcName}' requires a session but auth was explicitly disabled — use pikkuSessionlessFunc instead.`);
+            }
+            else if (!session) {
                 throw new ForbiddenError('Authentication required');
             }
         }
-        if (wiringAuth === undefined && funcConfig.auth === undefined) {
-            // We always default to requiring auth unless explicitly disabled
-            if (!initialSession) {
-                // TODO: Critical, we need to figure out how to make this work with different wirings
-                // throw new ForbiddenError('Authentication required')
+        else {
+            // TODO: Remove after a couple of releases — backward compat for
+            // generated metadata that doesn't include the `sessionless` field yet.
+            if (wiringAuth === true || funcConfig.auth === true) {
+                if (!session) {
+                    throw new ForbiddenError('Authentication required');
+                }
             }
         }
         // Evaluate the data from the lazy function
@@ -60,10 +161,10 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         const inputSchemaName = funcMeta.inputSchemaName;
         if (inputSchemaName) {
             // Validate request data against the defined schema, if any
-            await validateSchema(singletonServices.logger, singletonServices.schema, inputSchemaName, actualData);
+            await validateSchema(resolvedSingletonServices.logger, resolvedSingletonServices.schema, inputSchemaName, actualData, packageName);
             // Coerce (top level) query string parameters or date objects if specified by the schema
             if (coerceDataFromSchema) {
-                coerceTopLevelDataFromSchema(inputSchemaName, actualData);
+                coerceTopLevelDataFromSchema(inputSchemaName, actualData, packageName);
             }
         }
         await runPermissions(wireType, wireId, {
@@ -71,22 +172,25 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
             wirePermissions: wirePermissions,
             funcInheritedPermissions: funcMeta.permissions,
             funcPermissions: funcConfig.permissions,
-            services: singletonServices,
-            wire: { ...wireWithInitialSession, rpc: undefined },
+            services: resolvedSingletonServices,
+            wire: { ...wireWithSession, rpc: undefined },
             data: actualData,
+            packageName,
         });
-        const wireServices = await createWireServices?.(singletonServices, wireWithInitialSession);
+        const wireServices = await resolvedCreateWireServices?.(resolvedSingletonServices, wireWithSession);
         try {
-            const services = { ...singletonServices, ...wireServices };
-            const rpc = rpcService.getContextRPCService(services, wireWithInitialSession);
+            const services = { ...resolvedSingletonServices, ...wireServices };
+            const rpc = rpcService.getContextRPCService(services, wireWithSession, {
+                sessionService,
+            });
             return await funcConfig.func(services, actualData, {
-                ...wireWithInitialSession,
+                ...wireWithSession,
                 rpc,
             });
         }
         finally {
             if (wireServices) {
-                await closeWireServices(singletonServices.logger, wireServices);
+                await closeWireServices(resolvedSingletonServices.logger, wireServices);
             }
         }
     };
@@ -95,9 +199,10 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         wireMiddleware,
         funcInheritedMiddleware: funcMeta.middleware,
         funcMiddleware: funcConfig.middleware,
+        packageName,
     });
     if (allMiddleware.length > 0) {
-        return (await runMiddleware(singletonServices, wire, allMiddleware, executeFunction));
+        return (await runMiddleware(resolvedSingletonServices, resolvedWire, allMiddleware, executeFunction));
     }
     return (await executeFunction());
 };

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

@@ -1,5 +1,11 @@
 import type { CoreServices, CoreSingletonServices, CoreUserSession, CorePikkuMiddleware, PikkuWire, PickRequired } from '../types/core.types.js';
-import { Session } from 'inspector';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { CoreNodeConfig } from '../wirings/node/node.types.js';
+/**
+ * @deprecated Use StandardSchemaV1 from @standard-schema/spec instead.
+ * This alias exists only for backward compatibility with generated code.
+ */
+export type ZodLike<T = any> = StandardSchemaV1<T, T>;
 /**
  * Represents a core API function that performs an operation using core services and a user session.
  *
@@ -8,7 +14,7 @@ import { Session } from 'inspector';
  * @template Services - The services type, defaults to `CoreServices`.
  * @template Wire - The wire type, defaults to `PikkuWire<In, Out>`.
  */
-export type CorePikkuFunction<In, Out, Services extends CoreSingletonServices = CoreServices, Wire extends PikkuWire<In, Out> = PikkuWire<In, Out, true, Session>> = (services: Services, data: In, wire: Wire) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>;
+export type CorePikkuFunction<In, Out, Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession, Wire extends PikkuWire<In, Out> = PikkuWire<In, Out, true, Session>> = (services: Services, data: In, wire: Wire) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>;
 /**
  * Represents a core API function that can be used without a session.
  *
@@ -17,7 +23,7 @@ export type CorePikkuFunction<In, Out, Services extends CoreSingletonServices =
  * @template Services - The services type, defaults to `CoreServices`.
  * @template Wire - The wire type, defaults to `PikkuWire<In, Out>`.
  */
-export type CorePikkuFunctionSessionless<In, Out, Services extends CoreSingletonServices = CoreServices, Wire extends PikkuWire<In, Out, false, CoreUserSession, any, any, any> = PikkuWire<In, Out, false, CoreUserSession, any, any, any>> = (services: Services, data: In, wire: Wire) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>;
+export type CorePikkuFunctionSessionless<In, Out, Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession, Wire extends PikkuWire<In, Out, false, Session, any, any, any> = PikkuWire<In, Out, false, Session, any, any, any>> = (services: Services, data: In, wire: Wire) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>;
 /**
  * Represents a function that checks permissions for a given operation.
  *
@@ -49,8 +55,8 @@ export type CorePikkuPermissionConfig<In = any, Services extends CoreSingletonSe
  * ```typescript
  * // Direct function syntax
  * export const adminPermission = pikkuPermission(
- *   async ({ logger }, _data, { session }) => {
- *     const currentSession = await session.get()
+ *   async ({ logger }, _data, { getSession }) => {
+ *     const currentSession = await getSession()
  *     return currentSession?.role === 'admin'
  *   }
  * )
@@ -59,8 +65,8 @@ export type CorePikkuPermissionConfig<In = any, Services extends CoreSingletonSe
  * export const adminPermission = pikkuPermission({
  *   name: 'Admin Permission',
  *   description: 'Checks if user has admin role',
- *   func: async ({ logger }, _data, { session }) => {
- *     const currentSession = await session.get()
+ *   func: async ({ logger }, _data, { getSession }) => {
+ *     const currentSession = await getSession()
  *     return currentSession?.role === 'admin'
  *   }
  * })
@@ -85,8 +91,8 @@ export type CorePikkuPermissionFactory<In = any, Services extends CoreSingletonS
  * export const requireRole = pikkuPermissionFactory<{ role: string }>(({
  *   role
  * }) => {
- *   return pikkuPermission(async ({ logger }, data, { session }) => {
- *      const currentSession = await session.get()
+ *   return pikkuPermission(async ({ logger }, data, { getSession }) => {
+ *      const currentSession = await getSession()
  *     if (!currentSession || currentSession.role !== role) {
  *       logger.warn(`Permission denied: required role '${role}'`)
  *       return false
@@ -97,14 +103,31 @@ export type CorePikkuPermissionFactory<In = any, Services extends CoreSingletonS
  * ```
  */
 export declare const pikkuPermissionFactory: <In = any>(factory: CorePikkuPermissionFactory<In>) => CorePikkuPermissionFactory<In>;
-export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> = Record<string, PikkuPermission | PikkuPermission[]> | undefined;
-export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = {
+export type CorePikkuAuth<Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession> = (services: Services, session: Session) => Promise<boolean> | boolean;
+export type CorePikkuAuthConfig<Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession> = {
+    func: CorePikkuAuth<Services, Session>;
     name?: string;
+    description?: string;
+};
+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 */
+    title?: string;
+    /** Optional description of what the function does */
+    description?: string;
+    override?: string;
+    version?: number;
     tags?: string[];
     expose?: boolean;
-    internal?: boolean;
+    remote?: boolean;
+    mcp?: boolean;
+    requiresApproval?: boolean;
     func: PikkuFunction;
     auth?: boolean;
     permissions?: CorePermissionGroup<PikkuPermission>;
     middleware?: PikkuMiddleware[];
+    input?: InputSchema;
+    output?: OutputSchema;
+    node?: CoreNodeConfig;
 };

package/dist/function/functions.types.js

@@ -6,8 +6,8 @@
  * ```typescript
  * // Direct function syntax
  * export const adminPermission = pikkuPermission(
- *   async ({ logger }, _data, { session }) => {
- *     const currentSession = await session.get()
+ *   async ({ logger }, _data, { getSession }) => {
+ *     const currentSession = await getSession()
  *     return currentSession?.role === 'admin'
  *   }
  * )
@@ -16,8 +16,8 @@
  * export const adminPermission = pikkuPermission({
  *   name: 'Admin Permission',
  *   description: 'Checks if user has admin role',
- *   func: async ({ logger }, _data, { session }) => {
- *     const currentSession = await session.get()
+ *   func: async ({ logger }, _data, { getSession }) => {
+ *     const currentSession = await getSession()
  *     return currentSession?.role === 'admin'
  *   }
  * })
@@ -35,8 +35,8 @@ export const pikkuPermission = (permission) => {
  * export const requireRole = pikkuPermissionFactory<{ role: string }>(({
  *   role
  * }) => {
- *   return pikkuPermission(async ({ logger }, data, { session }) => {
- *      const currentSession = await session.get()
+ *   return pikkuPermission(async ({ logger }, data, { getSession }) => {
+ *      const currentSession = await getSession()
  *     if (!currentSession || currentSession.role !== role) {
  *       logger.warn(`Permission denied: required role '${role}'`)
  *       return false
@@ -49,3 +49,13 @@ export const pikkuPermission = (permission) => {
 export const pikkuPermissionFactory = (factory) => {
     return factory;
 };
+export const pikkuAuth = (auth) => {
+    const fn = typeof auth === 'function' ? auth : auth.func;
+    const wrapper = async (services, _data, wire) => {
+        const session = wire.session;
+        if (!session)
+            return false;
+        return fn(services, session);
+    };
+    return wrapper;
+};

package/dist/function/index.d.ts

@@ -1,2 +1,2 @@
-export * from './function-runner.js';
-export * from './functions.types.js';
+export { addFunction, getAllFunctionNames } from './function-runner.js';
+export type { CorePikkuFunction, CorePikkuFunctionSessionless, } from './functions.types.js';

package/dist/function/index.js

@@ -1,2 +1 @@
-export * from './function-runner.js';
-export * from './functions.types.js';
+export { addFunction, getAllFunctionNames } from './function-runner.js';