@pikku/core 0.12.8 → 0.12.10

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

@@ -4,6 +4,7 @@ import { getDurationInMilliseconds } from '../../time-utils.js';
 import { continueGraph, executeGraphStep, runWorkflowGraph, runFromMeta, } from './graph/graph-runner.js';
 import { PikkuError, addError } from '../../errors/error-handler.js';
 import { RPCNotFoundError } from '../rpc/rpc-runner.js';
+import { ChildWorkflowStartedException } from './graph/graph-runner.js';
 /**
  * Exception thrown when workflow needs to pause for async step
  */
@@ -84,6 +85,9 @@ const WORKFLOW_END_STATES = new Set([
  */
 export class PikkuWorkflowService {
     inlineRuns = new Set();
+    get logger() {
+        return getSingletonServices()?.logger;
+    }
     constructor() { }
     /**
      * Check if a run is executing inline (without queues)
@@ -124,12 +128,12 @@ export class PikkuWorkflowService {
     }
     async queueStepWorker(runId, stepName, rpcName, data) {
         const queueService = this.verifyQueueService();
-        await queueService.add(this.getConfig().stepWorkerQueueName, {
+        await queueService.add(this.getConfig().stepWorkerQueueName, JSON.parse(JSON.stringify({
             runId,
             stepName,
             rpcName,
             data,
-        });
+        })));
     }
     /**
      * Execute a workflow sleep step completion
@@ -163,7 +167,9 @@ export class PikkuWorkflowService {
             throw new WorkflowNotFoundError(name);
         }
         if (workflowMeta.source === 'graph' || workflowMeta.source === 'ai-agent') {
-            const shouldInline = options?.inline || !getSingletonServices()?.queueService;
+            const shouldInline = options?.inline ||
+                workflowMeta.inline ||
+                !getSingletonServices()?.queueService;
             return runWorkflowGraph(this, name, input, rpcService, shouldInline, options?.startNode, wire);
         }
         // DSL workflow - check registration exists
@@ -175,17 +181,25 @@ export class PikkuWorkflowService {
         if (!workflowMeta.graphHash) {
             throw new Error(`Missing workflow graphHash for '${name}'`);
         }
-        const shouldInline = options?.inline || !getSingletonServices()?.queueService;
+        const shouldInline = options?.inline ||
+            workflowMeta.inline ||
+            !getSingletonServices()?.queueService;
         const runId = await this.createRun(name, input, shouldInline, workflowMeta.graphHash, wire);
         if (shouldInline) {
             this.inlineRuns.add(runId);
-            this.runWorkflowJob(runId, rpcService)
-                .catch((err) => {
-                getSingletonServices().logger.error(`Workflow ${name} (run ${runId}) failed:`, err);
-            })
-                .finally(() => {
+            try {
+                await this.runWorkflowJob(runId, rpcService);
+            }
+            catch (error) {
+                if (error.name !== 'WorkflowAsyncException' &&
+                    error.name !== 'WorkflowCancelledException' &&
+                    error.name !== 'WorkflowSuspendedException') {
+                    getSingletonServices().logger.error(`Workflow ${name} (run ${runId}) failed:`, error);
+                }
+            }
+            finally {
                 this.inlineRuns.delete(runId);
-            });
+            }
         }
         else {
             await this.resumeWorkflow(runId);
@@ -227,6 +241,14 @@ export class PikkuWorkflowService {
         }
         if (workflowMeta?.source === 'graph') {
             await continueGraph(this, runId, run.workflow);
+            const updatedRun = await this.getRun(runId);
+            if (updatedRun?.status === 'completed') {
+                await this.onChildWorkflowCompleted(updatedRun, updatedRun.output);
+            }
+            else if (updatedRun?.status === 'failed' ||
+                updatedRun?.status === 'cancelled') {
+                await this.onChildWorkflowFailed(updatedRun, new Error(updatedRun.error?.message || 'Child workflow failed'));
+            }
             return;
         }
         const registrations = pikkuState(null, 'workflows', 'registrations');
@@ -249,6 +271,7 @@ export class PikkuWorkflowService {
                     data: () => run.input,
                 });
                 await this.updateRunStatus(runId, 'completed', result);
+                await this.onChildWorkflowCompleted(run, result);
             }
             catch (error) {
                 if (error instanceof WorkflowAsyncException) {
@@ -260,6 +283,7 @@ export class PikkuWorkflowService {
                         stack: '',
                         code: 'WORKFLOW_CANCELLED',
                     });
+                    await this.onChildWorkflowFailed(run, error);
                     throw error;
                 }
                 if (error instanceof WorkflowSuspendedException) {
@@ -275,10 +299,27 @@ export class PikkuWorkflowService {
                     stack: error.stack,
                     code: error.code,
                 });
+                await this.onChildWorkflowFailed(run, error);
                 throw error;
             }
         });
     }
+    async onChildWorkflowCompleted(childRun, result) {
+        const { parentRunId, parentStepId } = childRun.wire ?? {};
+        if (!parentRunId || !parentStepId)
+            return;
+        this.logger?.debug(`Child workflow ${childRun.id} completed, updating parent step ${parentStepId}`);
+        await this.setStepResult(parentStepId, result);
+        await this.resumeWorkflow(parentRunId);
+    }
+    async onChildWorkflowFailed(childRun, error) {
+        const { parentRunId, parentStepId } = childRun.wire ?? {};
+        if (!parentRunId || !parentStepId)
+            return;
+        this.logger?.debug(`Child workflow ${childRun.id} failed, updating parent step ${parentStepId}`);
+        await this.setStepError(parentStepId, error);
+        await this.resumeWorkflow(parentRunId);
+    }
     async runVersionMismatchFallback(run, currentMeta, rpcService) {
         const source = currentMeta.source;
         if (source === 'complex') {
@@ -309,9 +350,8 @@ export class PikkuWorkflowService {
         await this.withStepLock(runId, stepName, async () => {
             // Get step state
             let stepState = await this.getStepState(runId, stepName);
-            // Idempotency - if already succeeded, resume orchestrator and return
+            // Idempotency - if already succeeded, nothing to do
             if (stepState.status === 'succeeded') {
-                await this.resumeWorkflow(runId);
                 return;
             }
             // Log warning if already running (race condition)
@@ -322,8 +362,7 @@ export class PikkuWorkflowService {
             if (stepState.status === 'failed') {
                 stepState = await this.createRetryAttempt(stepState.stepId, 'running');
             }
-            if (stepState.status === 'pending') {
-                // Mark pending step as running before execution
+            if (stepState.status === 'pending' || stepState.status === 'scheduled') {
                 await this.setStepRunning(stepState.stepId);
             }
             try {
@@ -334,17 +373,49 @@ export class PikkuWorkflowService {
                 }
                 const meta = pikkuState(null, 'workflows', 'meta');
                 const workflowMeta = meta[run.workflow];
-                if (workflowMeta?.nodes && stepName in workflowMeta.nodes) {
+                const isGraphWorkflow = workflowMeta?.source === 'graph' ||
+                    workflowMeta?.source === 'ai-agent';
+                if (isGraphWorkflow &&
+                    workflowMeta?.nodes &&
+                    stepName in workflowMeta.nodes) {
                     result = await executeGraphStep(this, rpcService, runId, stepState.stepId, stepName, rpcName, data, run.workflow);
                 }
                 else {
-                    result = await rpcService.rpcWithWire(rpcName, data, {
-                        workflowStep: {
-                            runId,
-                            stepId: stepState.stepId,
-                            attemptCount: stepState.attemptCount,
-                        },
-                    });
+                    // Check if rpcName refers to a sub-workflow
+                    const subWorkflowMeta = meta[rpcName];
+                    if (subWorkflowMeta) {
+                        const childWire = {
+                            type: 'workflow',
+                            id: rpcName,
+                            parentRunId: runId,
+                            parentStepId: stepState.stepId,
+                        };
+                        const shouldInline = subWorkflowMeta.inline || !getSingletonServices()?.queueService;
+                        const { runId: childRunId } = await this.startWorkflow(rpcName, data, childWire, rpcService, { inline: shouldInline });
+                        await this.setStepChildRunId(stepState.stepId, childRunId);
+                        if (shouldInline) {
+                            const childRun = await this.getRun(childRunId);
+                            if (childRun?.status === 'failed') {
+                                throw new Error(childRun.error?.message || 'Sub-workflow failed');
+                            }
+                            if (childRun?.status === 'cancelled') {
+                                throw new Error('Sub-workflow was cancelled');
+                            }
+                            result = childRun?.output;
+                        }
+                        else {
+                            throw new ChildWorkflowStartedException(runId, stepState.stepId, childRunId);
+                        }
+                    }
+                    else {
+                        result = await rpcService.rpcWithWire(rpcName, data, {
+                            workflowStep: {
+                                runId,
+                                stepId: stepState.stepId,
+                                attemptCount: stepState.attemptCount,
+                            },
+                        });
+                    }
                 }
                 // Store result and mark succeeded
                 await this.setStepResult(stepState.stepId, result);
@@ -352,6 +423,10 @@ export class PikkuWorkflowService {
                 await this.resumeWorkflow(runId);
             }
             catch (error) {
+                if (error instanceof ChildWorkflowStartedException) {
+                    this.logger?.debug(`Workflow step '${stepName}': child workflow ${error.childRunId} started, waiting for completion`);
+                    return;
+                }
                 if (error instanceof RPCNotFoundError) {
                     await this.setStepError(stepState.stepId, error);
                     await this.updateRunStatus(runId, 'suspended', undefined, {
@@ -437,12 +512,12 @@ export class PikkuWorkflowService {
             // Map step retry options to queue job options
             const retries = stepOptions?.retries ?? 0;
             const retryDelay = stepOptions?.retryDelay;
-            await getSingletonServices().queueService.add(this.getConfig().stepWorkerQueueName, {
+            await getSingletonServices().queueService.add(this.getConfig().stepWorkerQueueName, JSON.parse(JSON.stringify({
                 runId,
                 stepName,
                 rpcName,
                 data,
-            }, {
+            })), {
                 // attempts includes initial attempt, retries doesn't
                 attempts: retries + 1,
                 // Map retry delay to backoff

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

@@ -7,6 +7,7 @@ export interface WorkflowRunWire {
     type: string;
     id?: string;
     parentRunId?: string;
+    parentStepId?: string;
 }
 export interface WorkflowServiceConfig {
     retries: number;
@@ -166,6 +167,7 @@ export type WorkflowsMeta = Record<string, CommonWireMeta & {
     steps: WorkflowStepMeta[];
     context?: WorkflowContext;
     dsl?: boolean;
+    inline?: boolean;
 }>;
 /**
  * Unified workflow runtime meta (used by runtime to execute workflows)
@@ -183,6 +185,8 @@ export interface WorkflowRuntimeMeta {
     description?: string;
     /** Tags for organization */
     tags?: string[];
+    /** If true, workflow always executes inline without queues */
+    inline?: boolean;
     /** Serialized nodes */
     nodes?: Record<string, any>;
     /** Entry node IDs for graph workflows (computed at build time) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.8",
+  "version": "0.12.10",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -35,6 +35,7 @@
     "./cli": "./dist/wirings/cli/index.js",
     "./cli/channel": "./dist/wirings/cli/channel/index.js",
     "./node": "./dist/wirings/node/index.js",
+    "./credential": "./dist/wirings/credential/index.js",
     "./secret": "./dist/wirings/secret/index.js",
     "./variable": "./dist/wirings/variable/index.js",
     "./oauth2": "./dist/wirings/oauth2/index.js",

package/src/env.ts

@@ -0,0 +1 @@
+export const isProduction = () => process.env.NODE_ENV === 'production'

package/src/errors/errors.ts

@@ -372,3 +372,38 @@ addError(MissingSchemaError, {
   message:
     'A required schema was not found. Ensure schema generation has been run.',
 })
+
+/**
+ * An AI provider has not been configured. Set up an AI provider (e.g. OpenAI, Anthropic) to use agent features.
+ * @group Error
+ */
+export class AIProviderNotConfiguredError extends PikkuError {
+  constructor() {
+    super(
+      'No AI provider configured. Please set up an AI provider (e.g. OpenAI, Anthropic) and provide a valid API key to use this agent.'
+    )
+  }
+}
+addError(AIProviderNotConfiguredError, {
+  status: 503,
+  message:
+    'No AI provider configured. Please set up an AI provider (e.g. OpenAI, Anthropic) and provide a valid API key to use this agent.',
+})
+
+/**
+ * The AI provider API key is missing or invalid.
+ * @group Error
+ */
+export class AIProviderAuthError extends PikkuError {
+  constructor(message?: string) {
+    super(
+      message ||
+        'AI provider API key is missing or invalid. Please check your API key configuration.'
+    )
+  }
+}
+addError(AIProviderAuthError, {
+  status: 401,
+  message:
+    'AI provider API key is missing or invalid. Please check your API key configuration.',
+})

package/src/function/function-runner.ts

@@ -28,6 +28,8 @@ import { parseVersionedId } from '../version.js'
 import type { SessionService } from '../services/user-session-service.js'
 import { createFunctionSessionWireProps } from '../services/user-session-service.js'
 import { ForbiddenError, ReadonlySessionError } from '../errors/errors.js'
+import type { PikkuCredentialWireService } from '../services/credential-wire-service.js'
+import { createWireServicesCredentialWireProps } from '../services/credential-wire-service.js'
 import { rpcService } from '../wirings/rpc/rpc-runner.js'
 import { closeWireServices } from '../utils.js'
 
@@ -146,6 +148,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
     tags = [],
     wire,
     sessionService,
+    credentialWireService,
     packageName = null,
   }: {
     singletonServices: CoreSingletonServices
@@ -162,6 +165,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
     tags?: string[]
     wire: PikkuWire
     sessionService?: SessionService<CoreUserSession>
+    credentialWireService?: PikkuCredentialWireService
     packageName?: string | null
   }
 ): Promise<Out> => {
@@ -312,6 +316,13 @@ export const runPikkuFunc = async <In = any, Out = any>(
       })
     }
 
+    if (credentialWireService) {
+      Object.assign(
+        resolvedWire,
+        createWireServicesCredentialWireProps(credentialWireService)
+      )
+    }
+
     const wireServices = await resolvedCreateWireServices?.(
       resolvedSingletonServices,
       resolvedWire

package/src/handle-error.ts

@@ -1,3 +1,4 @@
+import { isProduction } from './env.js'
 import { getErrorResponse } from './errors/error-handler.js'
 import { NotFoundError } from './errors/errors.js'
 import type { Logger } from './services/logger.js'
@@ -55,7 +56,7 @@ export const handleHTTPError = (
     if (trackerId) {
       logger.warn(`Error id: ${trackerId}`)
       const errorBody: Record<string, unknown> = { errorId: trackerId }
-      if (exposeErrors && e instanceof Error) {
+      if (exposeErrors && !isProduction() && e instanceof Error) {
         errorBody.message = e.message
         errorBody.stack = e.stack
       }

package/src/middleware/auth-bearer.ts

@@ -2,6 +2,15 @@ import { InvalidSessionError } from '../errors/errors.js'
 import type { CoreUserSession } from '../types/core.types.js'
 import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
 
+const constantTimeEqual = (a: string, b: string): boolean => {
+  if (a.length !== b.length) return false
+  let result = 0
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i)
+  }
+  return result === 0
+}
+
 /**
  * Bearer token middleware that extracts and validates tokens from the Authorization header.
  *
@@ -55,7 +64,7 @@ export const authBearer = pikkuMiddlewareFactory<{
 
         let userSession: CoreUserSession | null = null
 
-        if (token && bearerToken === token.value) {
+        if (token && constantTimeEqual(bearerToken, token.value)) {
           userSession = token.userSession
         } else if (jwtService && !token) {
           userSession = await jwtService.decode(bearerToken)

package/src/middleware/auth-cookie.ts

@@ -35,8 +35,15 @@ export const authCookie = pikkuMiddlewareFactory<{
   name: string
   options: SerializeOptions
   expiresIn: RelativeTimeInput
-}>(({ name, options, expiresIn }) =>
-  pikkuMiddleware(
+}>(({ name, options, expiresIn }) => {
+  const mergedOptions: SerializeOptions = {
+    httpOnly: true,
+    secure: true,
+    sameSite: 'lax',
+    path: '/',
+    ...options,
+  }
+  return pikkuMiddleware(
     async (
       { jwt: jwtService, logger },
       { http, setSession, getSession, session, hasSessionChanged },
@@ -67,7 +74,7 @@ export const authCookie = pikkuMiddlewareFactory<{
             name,
             await jwtService.encode(expiresIn, currentSession),
             {
-              ...options,
+              ...mergedOptions,
               expires: getRelativeTimeOffsetFromNow(expiresIn),
             }
           )
@@ -77,4 +84,4 @@ export const authCookie = pikkuMiddlewareFactory<{
       }
     }
   )
-)
+})

package/src/middleware/timeout.ts

@@ -4,12 +4,19 @@ import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
 export const timeout = () =>
   pikkuMiddlewareFactory<{ timeout: number }>(({ timeout }) =>
     pikkuMiddleware(async (_services, _wire, next) => {
-      const timeoutId = setTimeout(() => {
-        throw new RequestTimeoutError()
-      }, timeout)
-
-      await next()
-
-      clearTimeout(timeoutId)
+      let timeoutId: ReturnType<typeof setTimeout> | undefined
+      await Promise.race([
+        next(),
+        new Promise<never>((_resolve, reject) => {
+          timeoutId = setTimeout(
+            () => reject(new RequestTimeoutError()),
+            timeout
+          )
+        }),
+      ]).finally(() => {
+        if (timeoutId !== undefined) {
+          clearTimeout(timeoutId)
+        }
+      })
     })
   )

package/src/pikku-state.ts

@@ -14,7 +14,7 @@ import type { GatewaysMeta } from './wirings/gateway/gateway.types.js'
 import type { ScheduledTasksMeta } from './wirings/scheduler/scheduler.types.js'
 import type { TriggerMeta } from './wirings/trigger/trigger.types.js'
 
-const PIKKU_STATE_KEY = Symbol.for('@pikku/core/state')
+const PIKKU_STATE_KEY = Symbol('@pikku/core/state')
 
 export const getAllPackageStates = (): Map<string, PikkuPackageState> => {
   if (!(globalThis as any)[PIKKU_STATE_KEY]) {

package/src/services/credential-service.ts

@@ -0,0 +1,44 @@
+/**
+ * Interface for managing dynamic/managed credentials.
+ * Used for OAuth tokens, per-user API keys, and other credentials
+ * that change at runtime (as opposed to SecretService which is for
+ * static, developer-configured values).
+ */
+export interface CredentialService {
+  /**
+   * Retrieves a credential by name and optional user ID.
+   * @param name - The credential name (e.g. 'stripe', 'google-sheets').
+   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
+   * @returns The credential value, or null if not found.
+   */
+  get<T = unknown>(name: string, userId?: string): Promise<T | null>
+
+  /**
+   * Stores a credential.
+   * @param name - The credential name.
+   * @param value - The credential value to store.
+   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
+   */
+  set(name: string, value: unknown, userId?: string): Promise<void>
+
+  /**
+   * Deletes a credential.
+   * @param name - The credential name.
+   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
+   */
+  delete(name: string, userId?: string): Promise<void>
+
+  /**
+   * Checks if a credential exists.
+   * @param name - The credential name.
+   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
+   */
+  has(name: string, userId?: string): Promise<boolean>
+
+  /**
+   * Retrieves all credentials for a user.
+   * @param userId - The user ID.
+   * @returns A record of credential name to value.
+   */
+  getAll(userId: string): Promise<Record<string, unknown>>
+}

package/src/services/credential-wire-service.ts

@@ -0,0 +1,44 @@
+export class PikkuCredentialWireService {
+  private credentials: Record<string, unknown> = {}
+
+  set(name: string, value: unknown): void {
+    this.credentials[name] = value
+  }
+
+  getAll(): Record<string, unknown> {
+    return this.credentials
+  }
+
+  getScoped(allowedNames: string[]): Record<string, unknown> {
+    const scoped: Record<string, unknown> = {}
+    for (const name of allowedNames) {
+      if (name in this.credentials) {
+        scoped[name] = this.credentials[name]
+      }
+    }
+    return scoped
+  }
+}
+
+export function createMiddlewareCredentialWireProps(
+  credentialWire: PikkuCredentialWireService
+) {
+  return {
+    setCredential: (name: string, value: unknown) =>
+      credentialWire.set(name, value),
+  }
+}
+
+export function createWireServicesCredentialWireProps(
+  credentialWire: PikkuCredentialWireService,
+  allowedNames?: string[]
+) {
+  return {
+    setCredential: (name: string, value: unknown) =>
+      credentialWire.set(name, value),
+    getCredentials: () =>
+      allowedNames
+        ? credentialWire.getScoped(allowedNames)
+        : credentialWire.getAll(),
+  }
+}

package/src/services/index.ts

@@ -10,8 +10,14 @@ export {
   createFunctionSessionWireProps,
 } from './user-session-service.js'
 export { TypedSecretService } from './typed-secret-service.js'
+export {
+  PikkuCredentialWireService,
+  createMiddlewareCredentialWireProps,
+  createWireServicesCredentialWireProps,
+} from './credential-wire-service.js'
 export { TypedVariablesService } from './typed-variables-service.js'
 export { LocalSecretService } from './local-secrets.js'
+export { LocalCredentialService } from './local-credential-service.js'
 export { LocalVariablesService } from './local-variables.js'
 export { ConsoleLogger } from './logger-console.js'
 export { InMemoryWorkflowService } from './in-memory-workflow-service.js'
@@ -53,4 +59,10 @@ export type {
   CredentialStatus,
   CredentialMeta,
 } from './typed-secret-service.js'
+export type { CredentialService } from './credential-service.js'
+export { TypedCredentialService } from './typed-credential-service.js'
+export type {
+  CredentialStatusInfo,
+  CredentialMetaInfo,
+} from './typed-credential-service.js'
 export type { VariableStatus, VariableMeta } from './typed-variables-service.js'