@pikku/core 0.12.26 → 0.12.28

package/src/function/function-runner.ts

@@ -7,7 +7,6 @@ import { runPermissions } from '../permissions.js'
 import { pikkuState } from '../pikku-state.js'
 import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js'
 import type {
-  CoreServices,
   CoreUserSession,
   CorePikkuMiddleware,
   PikkuWiringTypes,
@@ -26,10 +25,7 @@ import type {
 } from './functions.types.js'
 import { parseVersionedId } from '../version.js'
 import type { SessionService } from '../services/user-session-service.js'
-import {
-  PikkuSessionService,
-  createFunctionSessionWireProps,
-} from '../services/user-session-service.js'
+import { PikkuSessionService } from '../services/user-session-service.js'
 import { ForbiddenError, ReadonlySessionError } from '../errors/errors.js'
 import {
   PikkuCredentialWireService,
@@ -200,27 +196,6 @@ export const getAllFunctionNames = (): string[] => {
   return functions
 }
 
-export const runPikkuFuncDirectly = async <In, Out>(
-  funcName: string,
-  allServices: CoreServices,
-  wire: PikkuWire,
-  data: In,
-  userSession?: SessionService<CoreUserSession>,
-  packageName: string | null = null
-) => {
-  const funcConfig = pikkuState(packageName, 'function', 'functions').get(
-    funcName
-  )
-  if (!funcConfig) {
-    throw new Error(`Function not found: ${funcName}`)
-  }
-  const wireWithSession = {
-    ...wire,
-    ...(userSession && createFunctionSessionWireProps(userSession)),
-  }
-  return (await funcConfig.func(allServices, data, wireWithSession)) as Out
-}
-
 export const runPikkuFunc = async <In = any, Out = any>(
   wireType: PikkuWiringTypes,
   wireId: string,
@@ -381,7 +356,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
           throw new ForbiddenError('Authentication required')
         }
       }
-    } else if (funcMeta.sessionless === false) {
+    } else {
       if (wiringAuth === false || funcConfig.auth === false) {
         resolvedSingletonServices.logger.warn(
           `Function '${funcName}' requires a session but auth was explicitly disabled — use pikkuSessionlessFunc instead.`
@@ -390,14 +365,6 @@ export const runPikkuFunc = async <In = any, Out = any>(
       if (!session) {
         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')
-        }
-      }
     }
 
     if ((session as any)?.readonly && !funcMeta.readonly) {

package/src/function/functions.types.ts

@@ -295,6 +295,8 @@ export type CorePikkuFunctionConfig<
   readonly?: boolean
   deploy?: 'serverless' | 'server' | 'auto'
   approvalRequired?: boolean
+  /** When false, workflow steps calling this function are dispatched via the queue instead of running inline. Defaults to true (inline). */
+  inline?: boolean
   audit?:
     | boolean
     | {

package/src/handle-error.test.ts

@@ -89,6 +89,7 @@ describe('handleHTTPError', () => {
 
     assert.strictEqual(http._state.statusCode, 404)
     assert.deepStrictEqual(http._state.jsonBody, {
+      name: 'NotFoundError',
       message: 'The server cannot find the requested resource.',
       payload: undefined,
       errorId: 'tracker-1',

package/src/handle-error.ts

@@ -36,6 +36,7 @@ export const handleHTTPError = (
     // Set status and response body
     http?.response?.status(errorResponse.status)
     http?.response?.json({
+      name: e instanceof Error ? e.name : undefined,
       message:
         e instanceof Error && e.message && e.message !== 'An error occurred'
           ? e.message

package/src/index.ts

@@ -171,7 +171,12 @@ export {
   checkAuthPermissions,
 } from './permissions.js'
 export { isSerializable, stopSingletonServices } from './utils.js'
-export { getSingletonServices, getCreateWireServices } from './pikku-state.js'
+export {
+  getSingletonServices,
+  getCreateWireServices,
+  setSingletonServices,
+} from './pikku-state.js'
+export { clearPikkuRuntimeState } from './test-utils.js'
 export {
   type ScheduledTaskInfo,
   type ScheduledTaskSummary,
@@ -180,6 +185,7 @@ export { SchedulerService } from './services/scheduler-service.js'
 
 export type {
   Private,
+  Pii,
   Secret,
   Classification,
   AnonymizeStrategy,

package/src/pikku-state.ts

@@ -193,6 +193,10 @@ export const getSingletonServices = (): CoreSingletonServices => {
   return services
 }
 
+export const setSingletonServices = (services: CoreSingletonServices): void => {
+  pikkuState(null, 'package', 'singletonServices', services)
+}
+
 export const getCreateWireServices = (): CreateWireServices | undefined => {
   return pikkuState(null, 'package', 'factories')?.createWireServices
 }

package/src/services/gopass-secrets.ts

@@ -63,4 +63,14 @@ export class GopassSecretService implements SecretService {
       // Ignore errors if secret doesn't exist
     }
   }
+
+  public async getSecrets(keys: string[]): Promise<Record<string, unknown>> {
+    const results = await Promise.allSettled(keys.map((k) => this.getSecret(k)))
+    const out: Record<string, unknown> = {}
+    keys.forEach((key, i) => {
+      if (results[i].status === 'fulfilled')
+        out[key] = (results[i] as PromiseFulfilledResult<unknown>).value
+    })
+    return out
+  }
 }

package/src/services/local-secrets.ts

@@ -52,4 +52,14 @@ export class LocalSecretService implements SecretService {
   public async deleteSecret(key: string): Promise<void> {
     this.localSecrets.delete(key)
   }
+
+  public async getSecrets(keys: string[]): Promise<Record<string, unknown>> {
+    const results = await Promise.allSettled(keys.map((k) => this.getSecret(k)))
+    const out: Record<string, unknown> = {}
+    keys.forEach((key, i) => {
+      if (results[i].status === 'fulfilled')
+        out[key] = (results[i] as PromiseFulfilledResult<unknown>).value
+    })
+    return out
+  }
 }

package/src/services/meta-service.ts

@@ -533,7 +533,17 @@ export class LocalMetaService implements MetaService {
       )
     }
 
+    // emailsMeta.src is an absolute path resolved by the CLI at generation time.
+    // Read directly rather than through readProjectFile (which prepends the project
+    // root and produces a wrong compound path when baseDir is absolute).
     const baseDir = emailsMeta.src
+    const readEmailFile = async (rel: string): Promise<string | null> => {
+      try {
+        return await readFile(join(baseDir, rel), 'utf-8')
+      } catch {
+        return null
+      }
+    }
     const [
       themeRaw,
       localeRaw,
@@ -543,13 +553,13 @@ export class LocalMetaService implements MetaService {
       templateSubject,
       templateText,
     ] = await Promise.all([
-      this.readProjectFile(`${baseDir}/theme.json`),
-      this.readProjectFile(`${baseDir}/locales/${locale}.json`),
-      this.readProjectFile(`${baseDir}/partials/layout.html`),
-      this.readProjectFile(`${baseDir}/partials/footer.html`),
-      this.readProjectFile(`${baseDir}/templates/${templateName}.html`),
-      this.readProjectFile(`${baseDir}/templates/${templateName}.subject.txt`),
-      this.readProjectFile(`${baseDir}/templates/${templateName}.text.txt`),
+      readEmailFile('theme.json'),
+      readEmailFile(`locales/${locale}.json`),
+      readEmailFile('partials/layout.html'),
+      readEmailFile('partials/footer.html'),
+      readEmailFile(`templates/${templateName}.html`),
+      readEmailFile(`templates/${templateName}.subject.txt`),
+      readEmailFile(`templates/${templateName}.text.txt`),
     ])
 
     return {

package/src/services/scoped-secret-service.ts

@@ -33,4 +33,9 @@ export class ScopedSecretService implements SecretService {
   async deleteSecret(_key: string): Promise<void> {
     throw new Error('deleteSecret is not allowed in scoped secret service')
   }
+
+  async getSecrets(keys: string[]): Promise<Record<string, unknown>> {
+    const allowed = keys.filter((k) => this.allowedKeys.has(k))
+    return this.secrets.getSecrets(allowed)
+  }
 }

package/src/services/secret-service.ts

@@ -28,4 +28,11 @@ export interface SecretService {
    * @returns A promise that resolves when the secret is deleted.
    */
   deleteSecret(key: string): Promise<void>
+  /**
+   * Retrieves multiple secrets in a single batch operation.
+   * Returns a map of key → value for successfully fetched secrets; missing
+   * keys are omitted rather than throwing.
+   * @param keys - The keys of the secrets to retrieve.
+   */
+  getSecrets(keys: string[]): Promise<Record<string, unknown>>
 }

package/src/services/typed-secret-service.ts

@@ -43,6 +43,10 @@ export class TypedSecretService<
     return this.secrets.deleteSecret(key)
   }
 
+  async getSecrets(keys: string[]): Promise<Record<string, unknown>> {
+    return this.secrets.getSecrets(keys)
+  }
+
   async getAllStatus(): Promise<CredentialStatus[]> {
     const results: CredentialStatus[] = []
 

package/src/test-utils.ts

@@ -0,0 +1,38 @@
+import { getAllPackageStates } from './pikku-state.js'
+import { clearMiddlewareCache } from './middleware-runner.js'
+import { clearPermissionsCache } from './permissions.js'
+import { clearChannelMiddlewareCache } from './wirings/channel/channel-middleware-runner.js'
+
+/**
+ * Clears all runtime caches between test scenarios without touching registered
+ * routes, functions, or middleware groups (which are set at module load time
+ * and must persist for the whole test run).
+ *
+ * Call this alongside your DB snapshot restore in your Before hook:
+ *
+ * ```typescript
+ * Before(async function() {
+ *   await restoreSnapshot()
+ *   clearPikkuRuntimeState()
+ *   setSingletonServices(bundle.services)
+ * })
+ * ```
+ *
+ * Only works when NODE_ENV === 'test'. Logs an error and returns otherwise.
+ */
+export const clearPikkuRuntimeState = (): void => {
+  if (process.env.NODE_ENV !== 'test') {
+    console.error(
+      '[pikku] clearPikkuRuntimeState() must only be called in test environments. Ignoring.'
+    )
+    return
+  }
+
+  clearMiddlewareCache()
+  clearPermissionsCache()
+  clearChannelMiddlewareCache()
+
+  for (const packageState of getAllPackageStates().values()) {
+    packageState.package.singletonServices = null
+  }
+}

package/src/types/core.types.ts

@@ -118,6 +118,8 @@ export type FunctionRuntimeMeta = {
   readonly?: boolean
   deploy?: 'serverless' | 'server' | 'auto'
   sessionless?: boolean
+  /** When false, workflow steps calling this function are dispatched via the queue. Defaults to true (inline). */
+  inline?: boolean
   version?: number
   approvalRequired?: boolean
   approvalDescription?: string

package/src/wirings/ai-agent/ai-agent-prepare.test.ts

@@ -178,6 +178,7 @@ describe('ai-agent-prepare', () => {
       description: 'Deploy the service',
       approvalRequired: true,
       inputSchemaName: 'DeployInput',
+      sessionless: true,
     }
     pikkuState(null, 'misc', 'schemas').set('DeployInput', {
       type: 'object',
@@ -254,6 +255,7 @@ describe('ai-agent-prepare', () => {
       description: 'Secret tool',
       permissions: ['admin'],
       inputSchemaName: 'SecretInput',
+      sessionless: true,
     }
     pikkuState(null, 'misc', 'schemas').set('SecretInput', {
       type: 'object',

package/src/wirings/ai-agent/ai-agent-runner.test.ts

@@ -560,6 +560,7 @@ describe('runAIAgent', () => {
       description: 'Deploy',
       approvalRequired: true,
       inputSchemaName: 'DeployInput',
+      sessionless: true,
     }
     pikkuState(null, 'misc', 'schemas').set('DeployInput', {
       type: 'object',
@@ -716,6 +717,7 @@ describe('resumeAIAgentSync', () => {
     pikkuState(null, 'function', 'meta').deploy = {
       description: 'Deploy',
       inputSchemaName: 'DeployInput',
+      sessionless: true,
     }
     pikkuState(null, 'misc', 'schemas').set('DeployInput', {
       type: 'object',
@@ -901,6 +903,7 @@ describe('resumeAIAgentSync', () => {
     pikkuState(null, 'function', 'meta').deploy = {
       description: 'Deploy',
       inputSchemaName: 'DeployInput',
+      sessionless: true,
     }
     pikkuState(null, 'misc', 'schemas').set('DeployInput', {
       type: 'object',
@@ -986,7 +989,12 @@ describe('getCredential API key override', () => {
     }
 
     const mockServices = {
-      logger: { info: () => {}, warn: () => {}, error: () => {}, debug: () => {} },
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      },
       aiAgentRunner: {
         run: async (): Promise<AIAgentStepResult> => {
           originalRunCalls.push('original')
@@ -1019,13 +1027,24 @@ describe('getCredential API key override', () => {
     const originalRunCalls: string[] = []
 
     const mockServices = {
-      logger: { info: () => {}, warn: () => {}, error: () => {}, debug: () => {} },
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      },
       aiAgentRunner: {
         run: async (): Promise<AIAgentStepResult> => {
           originalRunCalls.push('original')
           return makeStepResult({ text: 'from-original', finishReason: 'stop' })
         },
-        withApiKey: (_key: string) => ({ run: async () => makeStepResult({ text: 'should-not-be-called', finishReason: 'stop' }) }),
+        withApiKey: (_key: string) => ({
+          run: async () =>
+            makeStepResult({
+              text: 'should-not-be-called',
+              finishReason: 'stop',
+            }),
+        }),
       },
       aiRunState: {
         createRun: async () => 'run-no-cred',
@@ -1051,7 +1070,12 @@ describe('getCredential API key override', () => {
     const originalRunCalls: string[] = []
 
     const mockServices = {
-      logger: { info: () => {}, warn: () => {}, error: () => {}, debug: () => {} },
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      },
       aiAgentRunner: {
         run: async (): Promise<AIAgentStepResult> => {
           originalRunCalls.push('original')

package/src/wirings/ai-agent/ai-agent-stream.test.ts

@@ -327,6 +327,7 @@ describe('streamAIAgent', () => {
       description: 'Add a todo',
       approvalRequired: true,
       inputSchemaName: 'AddTodoInput',
+      sessionless: true,
     }
     pikkuState(null, 'misc', 'schemas').set('AddTodoInput', {
       type: 'object',
@@ -428,6 +429,7 @@ describe('streamAIAgent', () => {
       description: 'Add a todo',
       approvalRequired: true,
       inputSchemaName: 'AddTodoInput',
+      sessionless: true,
     }
     pikkuState('@test/addon-todos', 'misc', 'schemas').set('AddTodoInput', {
       type: 'object',
@@ -1287,6 +1289,7 @@ describe('resumeAIAgent', () => {
     pikkuState(null, 'function', 'meta').deploy = {
       description: 'Deploy',
       inputSchemaName: 'DeployInput',
+      sessionless: true,
     }
     pikkuState(null, 'misc', 'schemas').set('DeployInput', {
       type: 'object',

package/src/wirings/channel/channel-common.ts

@@ -6,7 +6,7 @@ import type {
 } from '../../types/core.types.js'
 import type { CoreChannel, ChannelMessageMeta } from './channel.types.js'
 import { combineMiddleware, runMiddleware } from '../../middleware-runner.js'
-import { runPikkuFuncDirectly } from '../../function/function-runner.js'
+import { runPikkuFunc } from '../../function/function-runner.js'
 import {
   combineChannelMiddleware,
   wrapChannelWithMiddleware,
@@ -79,7 +79,14 @@ export const runChannelLifecycleWithMiddleware = async ({
   }
 
   const runLifecycle = async () => {
-    return await runPikkuFuncDirectly(meta.pikkuFuncId, services, wire, data)
+    return await runPikkuFunc('channel', channelConfig.name, meta.pikkuFuncId, {
+      singletonServices: services,
+      data: () => data as any,
+      wire,
+      tags: meta.tags ?? [],
+      inheritedPermissions: meta.permissions,
+      packageName: meta.packageName ?? null,
+    })
   }
 
   if (allMiddleware.length > 0) {

package/src/wirings/channel/local/local-channel-handler.ts

@@ -1,3 +1,4 @@
+import type { Logger } from '../../../services/logger.js'
 import type { BinaryData } from '../channel.types.js'
 import { PikkuAbstractChannelHandler } from '../pikku-abstract-channel-handler.js'
 
@@ -7,19 +8,30 @@ export class PikkuLocalChannelHandler<
 > extends PikkuAbstractChannelHandler<OpeningData, Out> {
   private onMessageCallback?: (message: unknown) => void
   private onBinaryMessageCallback?: (data: BinaryData) => void
-  private openCallBack?: () => void
-  private closeCallbacks: (() => void)[] = []
+  private openCallBack?: () => Promise<void> | void
+  private closeCallbacks: (() => Promise<void> | void)[] = []
   private sendCallback?: (message: Out, isBinary?: boolean) => void
   private sendBinaryCallback?: (data: BinaryData) => void
+  private logger?: Logger
 
-  public registerOnOpen(callback: () => void): void {
+  constructor(
+    channelId: string,
+    channelName: string,
+    openingData: OpeningData,
+    logger?: Logger
+  ) {
+    super(channelId, channelName, openingData)
+    this.logger = logger
+  }
+
+  public registerOnOpen(callback: () => Promise<void> | void): void {
     this.openCallBack = callback
   }
 
-  public open() {
+  public async open(): Promise<void> {
     this.getChannel().state = 'open'
     if (this.openCallBack) {
-      this.openCallBack()
+      await this.openCallBack()
     }
   }
 
@@ -43,17 +55,20 @@ export class PikkuLocalChannelHandler<
     return this.onBinaryMessageCallback?.(data)
   }
 
-  public registerOnClose(callback: () => void): void {
+  public registerOnClose(callback: () => Promise<void> | void): void {
     this.closeCallbacks.push(callback)
   }
 
-  public close() {
+  public async close(): Promise<void> {
     if (this.getChannel().state === 'closed') {
       return
     }
     super.close()
-    for (const cb of this.closeCallbacks) {
-      cb()
+    const results = await Promise.allSettled(this.closeCallbacks.map((cb) => cb()))
+    for (const result of results) {
+      if (result.status === 'rejected') {
+        this.logger?.error('Error in channel close callback:', result.reason)
+      }
     }
   }
 

package/src/wirings/channel/local/local-channel-runner.ts

@@ -119,7 +119,8 @@ export const runLocalChannel = async ({
       channelHandler = new PikkuLocalChannelHandler(
         channelId,
         channelConfig.name,
-        openingData
+        openingData,
+        singletonServices.logger
       )
       const channel = channelHandler.getChannel()
       const wire: PikkuWire = {

package/src/wirings/cli/cli-runner.test.ts

@@ -128,6 +128,7 @@ describe('CLI Runner', () => {
           pikkuFuncId: 'greetFunc',
           inputSchemaName: null,
           outputSchemaName: null,
+          sessionless: true,
         },
       })
 
@@ -192,6 +193,7 @@ describe('CLI Runner', () => {
           pikkuFuncId: 'testFunc',
           inputSchemaName: null,
           outputSchemaName: null,
+          sessionless: true,
         },
       })
 
@@ -252,6 +254,7 @@ describe('CLI Runner', () => {
           pikkuFuncId: 'greetFunc',
           inputSchemaName: null,
           outputSchemaName: null,
+          sessionless: true,
         },
       })
 
@@ -296,6 +299,7 @@ describe('CLI Runner', () => {
           pikkuFuncId: 'secureFunc',
           inputSchemaName: null,
           outputSchemaName: null,
+          sessionless: true,
         },
       })
 

package/src/wirings/http/http-runner.test.ts

@@ -129,6 +129,7 @@ const setRouteMeta = (
     inputSchemaName: null,
     outputSchemaName: null,
     sessionless: true,
+    sessionless: true,
     permissions: undefined,
     middleware: undefined,
   } as any

package/src/wirings/queue/queue-runner.test.ts

@@ -43,6 +43,7 @@ const addTestQueueFunction = (pikkuFuncId: string) => {
     pikkuFuncId,
     inputSchemaName: null,
     outputSchemaName: null,
+    sessionless: true,
     middleware: undefined,
     permissions: undefined,
   }

package/src/wirings/scheduler/scheduler-runner.test.ts

@@ -157,6 +157,7 @@ describe('runScheduledTask', () => {
       pikkuFuncId: 'scheduler_simple-task',
       inputSchemaName: null,
       outputSchemaName: null,
+      sessionless: true,
     }
     wireScheduler(mockTask)
 
@@ -199,6 +200,7 @@ describe('runScheduledTask', () => {
       pikkuFuncId: 'scheduler_task-with-session',
       inputSchemaName: null,
       outputSchemaName: null,
+      sessionless: true,
     }
     wireScheduler(mockTask)
 
@@ -287,6 +289,7 @@ describe('runScheduledTask', () => {
       pikkuFuncId: 'scheduler_skipped-task',
       inputSchemaName: null,
       outputSchemaName: null,
+      sessionless: true,
     }
     wireScheduler(mockTask)
 
@@ -332,6 +335,7 @@ describe('runScheduledTask', () => {
       pikkuFuncId: 'scheduler_skipped-task-no-reason',
       inputSchemaName: null,
       outputSchemaName: null,
+      sessionless: true,
     }
     wireScheduler(mockTask)
 
@@ -380,6 +384,7 @@ describe('runScheduledTask', () => {
       pikkuFuncId: 'scheduler_wire-task',
       inputSchemaName: null,
       outputSchemaName: null,
+      sessionless: true,
     }
     wireScheduler(mockTask)
 
@@ -420,6 +425,7 @@ describe('runScheduledTask', () => {
       pikkuFuncId: 'scheduler_session-services-task',
       inputSchemaName: null,
       outputSchemaName: null,
+      sessionless: true,
     }
     wireScheduler(mockTask)
 
@@ -469,6 +475,7 @@ describe('runScheduledTask', () => {
       pikkuFuncId: 'scheduler_cleanup-task',
       inputSchemaName: null,
       outputSchemaName: null,
+      sessionless: true,
     }
     wireScheduler(mockTask)
 
@@ -517,6 +524,7 @@ describe('runScheduledTask', () => {
       pikkuFuncId: 'scheduler_error-cleanup-task',
       inputSchemaName: null,
       outputSchemaName: null,
+      sessionless: true,
     }
     wireScheduler(mockTask)
 
@@ -558,6 +566,7 @@ describe('runScheduledTask', () => {
       pikkuFuncId: 'scheduler_error-task',
       inputSchemaName: null,
       outputSchemaName: null,
+      sessionless: true,
     }
     wireScheduler(mockTask)
 
@@ -607,6 +616,7 @@ describe('runScheduledTask', () => {
       pikkuFuncId: 'scheduler_middleware-task',
       inputSchemaName: null,
       outputSchemaName: null,
+      sessionless: true,
     }
     wireScheduler(mockTask)
 

package/src/wirings/workflow/pikku-workflow-service.ts

@@ -879,7 +879,16 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     data: unknown,
     stepOptions?: WorkflowStepOptions
   ): Promise<boolean> {
-    if (this.isInline(runId) || !getSingletonServices()?.queueService) {
+    if (!getSingletonServices()?.queueService) {
+      return false
+    }
+    // Functions default to inline execution. Only dispatch via queue when the
+    // function explicitly sets inline: false.
+    const functionsMeta = pikkuState(null, 'function', 'meta')
+    const rpcFuncId = pikkuState(null, 'rpc', 'meta')[rpcName]
+    const rpcMeta = typeof rpcFuncId === 'string' ? functionsMeta[rpcFuncId] : undefined
+    const forceQueue = rpcMeta?.inline === false
+    if (!forceQueue && this.isInline(runId)) {
       return false
     }
     const retries = stepOptions?.retries ?? 0