@pikku/core 0.11.1 → 0.12.0

package/src/services/secret-service.ts

@@ -1,17 +1,38 @@
 /**
- * Interface for retrieving secrets.
+ * Interface for retrieving and managing secrets.
  */
 export interface SecretService {
   /**
-   * Retrieves a secret by key.
+   * Retrieves a secret by key and parses it as JSON.
    * @param key - The key of the secret to retrieve.
-   * @returns A promise that resolves to the secret value.
+   * @returns A promise that resolves to the parsed secret value.
+   * @throws If the secret is not found.
    */
   getSecretJSON<Return = {}>(key: string): Promise<Return>
   /**
-   * Retrieves a secret by key.
+   * Retrieves a secret by key as a string.
    * @param key - The key of the secret to retrieve.
    * @returns A promise that resolves to the secret value.
+   * @throws If the secret is not found.
    */
   getSecret(key: string): Promise<string>
+  /**
+   * Checks if a secret exists without throwing.
+   * @param key - The key of the secret to check.
+   * @returns A promise that resolves to true if the secret exists, false otherwise.
+   */
+  hasSecret(key: string): Promise<boolean>
+  /**
+   * Stores a JSON value as a secret.
+   * @param key - The key to store the secret under.
+   * @param value - The JSON value to store.
+   * @returns A promise that resolves when the secret is stored.
+   */
+  setSecretJSON(key: string, value: unknown): Promise<void>
+  /**
+   * Deletes a secret by key.
+   * @param key - The key of the secret to delete.
+   * @returns A promise that resolves when the secret is deleted.
+   */
+  deleteSecret(key: string): Promise<void>
 }

package/src/services/trigger-service.ts

@@ -0,0 +1,38 @@
+import {
+  CoreSingletonServices,
+  CreateWireServices,
+  CoreServices,
+  CoreUserSession,
+} from '../types/core.types.js'
+
+/**
+ * Abstract TriggerService interface.
+ *
+ * Implementations manage trigger subscriptions — listening to external events
+ * and dispatching to RPC targets or workflow starts.
+ */
+export interface TriggerService {
+  /**
+   * Set services needed for processing triggers.
+   * Called after construction since the trigger service is created before
+   * singletonServices are fully assembled.
+   */
+  setServices(
+    _singletonServices: CoreSingletonServices,
+    _createWireServices?: CreateWireServices<
+      CoreSingletonServices,
+      CoreServices,
+      CoreUserSession
+    >
+  ): void
+
+  /**
+   * Start all triggers
+   */
+  start(): Promise<void>
+
+  /**
+   * Stop all triggers
+   */
+  stop(): Promise<void>
+}

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

@@ -0,0 +1,70 @@
+import type { SecretService } from './secret-service.js'
+
+export interface CredentialStatus {
+  secretId: string
+  name: string
+  displayName: string
+  isConfigured: boolean
+  oauth2?: { tokenSecretId: string }
+}
+
+export type CredentialMeta = {
+  name: string
+  displayName: string
+  oauth2?: { tokenSecretId: string }
+}
+
+export class TypedSecretService<TMap = Record<string, unknown>>
+  implements SecretService
+{
+  constructor(
+    private secrets: SecretService,
+    private credentialsMeta: Record<string, CredentialMeta>
+  ) {}
+
+  async getSecretJSON<K extends keyof TMap & string>(key: K): Promise<TMap[K]>
+  async getSecretJSON<T = unknown>(key: string): Promise<T>
+  async getSecretJSON(key: string): Promise<unknown> {
+    return this.secrets.getSecretJSON(key)
+  }
+
+  async getSecret(key: string): Promise<string> {
+    return this.secrets.getSecret(key)
+  }
+
+  async hasSecret(key: string): Promise<boolean> {
+    return this.secrets.hasSecret(key)
+  }
+
+  async setSecretJSON<K extends string>(
+    key: K,
+    value: K extends keyof TMap ? TMap[K] : unknown
+  ): Promise<void> {
+    return this.secrets.setSecretJSON(key, value)
+  }
+
+  async deleteSecret(key: string): Promise<void> {
+    return this.secrets.deleteSecret(key)
+  }
+
+  async getAllStatus(): Promise<CredentialStatus[]> {
+    const results: CredentialStatus[] = []
+
+    for (const [secretId, meta] of Object.entries(this.credentialsMeta)) {
+      results.push({
+        secretId,
+        name: meta.name,
+        displayName: meta.displayName,
+        isConfigured: await this.secrets.hasSecret(secretId),
+        oauth2: meta.oauth2,
+      })
+    }
+
+    return results
+  }
+
+  async getMissing(): Promise<CredentialStatus[]> {
+    const all = await this.getAllStatus()
+    return all.filter((c) => !c.isConfigured)
+  }
+}

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

@@ -0,0 +1,81 @@
+import type { VariablesService } from './variables-service.js'
+
+export interface VariableStatus {
+  variableId: string
+  name: string
+  displayName: string
+  isConfigured: boolean
+}
+
+export type VariableMeta = {
+  name: string
+  displayName: string
+}
+
+export class TypedVariablesService<TMap = Record<string, unknown>>
+  implements VariablesService
+{
+  constructor(
+    private variables: VariablesService,
+    private variablesMeta: Record<string, VariableMeta>
+  ) {}
+
+  get(
+    name: keyof TMap & string
+  ): Promise<string | undefined> | string | undefined
+  get(name: string): Promise<string | undefined> | string | undefined
+  get(name: string): Promise<string | undefined> | string | undefined {
+    return this.variables.get(name)
+  }
+
+  getJSON<K extends keyof TMap & string>(
+    name: K
+  ): Promise<TMap[K] | undefined> | TMap[K] | undefined
+  getJSON<T = unknown>(name: string): Promise<T | undefined> | T | undefined
+  getJSON(name: string): Promise<unknown> | unknown {
+    return this.variables.getJSON(name)
+  }
+
+  getAll():
+    | Promise<Record<string, string | undefined>>
+    | Record<string, string | undefined> {
+    return this.variables.getAll()
+  }
+
+  set(name: string, value: string): Promise<void> | void {
+    return this.variables.set(name, value)
+  }
+
+  setJSON(name: string, value: unknown): Promise<void> | void {
+    return this.variables.setJSON(name, value)
+  }
+
+  has(name: string): Promise<boolean> | boolean {
+    return this.variables.has(name)
+  }
+
+  delete(name: string): Promise<void> | void {
+    return this.variables.delete(name)
+  }
+
+  async getAllStatus(): Promise<VariableStatus[]> {
+    const results: VariableStatus[] = []
+    const all = await this.variables.getAll()
+
+    for (const [variableId, meta] of Object.entries(this.variablesMeta)) {
+      results.push({
+        variableId,
+        name: meta.name,
+        displayName: meta.displayName,
+        isConfigured: all[variableId] !== undefined,
+      })
+    }
+
+    return results
+  }
+
+  async getMissing(): Promise<VariableStatus[]> {
+    const all = await this.getAllStatus()
+    return all.filter((v) => !v.isConfigured)
+  }
+}

package/src/services/user-session-service.ts

@@ -61,3 +61,26 @@ export class PikkuSessionService<UserSession extends CoreUserSession>
     return this.session
   }
 }
+
+export function createMiddlewareSessionWireProps<
+  UserSession extends CoreUserSession,
+>(session: SessionService<UserSession>) {
+  return {
+    session: session.get(),
+    setSession: (s: UserSession) => session.setInitial(s),
+    getSession: () => session.get(),
+    hasSessionChanged: () => session.sessionChanged,
+  }
+}
+
+export function createFunctionSessionWireProps<
+  UserSession extends CoreUserSession,
+>(session: SessionService<UserSession>) {
+  return {
+    session: session.freezeInitial(),
+    setSession: (s: UserSession) => session.set(s),
+    clearSession: () => session.clear(),
+    getSession: () => session.get(),
+    hasSessionChanged: () => session.sessionChanged,
+  }
+}

package/src/services/variables-service.ts

@@ -1,6 +1,11 @@
 export interface VariablesService {
   get: (name: string) => Promise<string | undefined> | string | undefined
+  getJSON: <T = unknown>(name: string) => Promise<T | undefined> | T | undefined
   getAll: () =>
     | Promise<Record<string, string | undefined>>
     | Record<string, string | undefined>
+  set: (name: string, value: string) => Promise<void> | void
+  setJSON: (name: string, value: unknown) => Promise<void> | void
+  has: (name: string) => Promise<boolean> | boolean
+  delete: (name: string) => Promise<void> | void
 }

package/src/services/workflow-service.ts

@@ -0,0 +1,94 @@
+import {
+  SerializedError,
+  CoreSingletonServices,
+  CreateWireServices,
+  CoreConfig,
+} from '../types/core.types.js'
+import {
+  WorkflowRun,
+  WorkflowRunWire,
+  StepState,
+  WorkflowStatus,
+} from '../wirings/workflow/workflow.types.js'
+
+/**
+ * Interface for workflow orchestration
+ * Handles workflow execution, replay, orchestration logic, and run-level state
+ */
+export interface WorkflowService {
+  // Run-level state operations
+  createRun(
+    workflowName: string,
+    input: any,
+    inline: boolean,
+    graphHash: string,
+    wire: WorkflowRunWire
+  ): Promise<string>
+  getRun(id: string): Promise<WorkflowRun | null>
+  getRunHistory(runId: string): Promise<Array<StepState & { stepName: string }>>
+  updateRunStatus(
+    id: string,
+    status: WorkflowStatus,
+    output?: any,
+    error?: SerializedError
+  ): Promise<void>
+  withRunLock<T>(id: string, fn: () => Promise<T>): Promise<T>
+  close(): Promise<void>
+
+  // Orchestration operations
+  resumeWorkflow(runId: string): Promise<void>
+  setServices(
+    singletonServices: CoreSingletonServices,
+    createWireServices: CreateWireServices | undefined,
+    config: CoreConfig
+  ): void
+  startWorkflow<I>(
+    name: string,
+    input: I,
+    wire: WorkflowRunWire,
+    rpcService: any,
+    options?: { inline?: boolean; startNode?: string }
+  ): Promise<{ runId: string }>
+  runWorkflowJob(runId: string, rpcService: any): Promise<void>
+  orchestrateWorkflow(runId: string, rpcService: any): Promise<void>
+  executeWorkflowSleepCompleted(runId: string, stepId: string): Promise<void>
+
+  // Step-level state operations
+  insertStepState(
+    runId: string,
+    stepName: string,
+    rpcName: string,
+    data: any,
+    stepOptions?: { retries?: number; retryDelay?: string | number }
+  ): Promise<StepState>
+  getStepState(runId: string, stepName: string): Promise<StepState>
+  setStepRunning(stepId: string): Promise<void>
+  setStepScheduled(stepId: string): Promise<void>
+  setStepResult(stepId: string, result: any): Promise<void>
+  setStepError(stepId: string, error: Error): Promise<void>
+  createRetryAttempt(
+    stepId: string,
+    status: 'pending' | 'running'
+  ): Promise<StepState>
+
+  // Step execution
+  executeWorkflowStep(
+    runId: string,
+    stepName: string,
+    rpcName: string | null,
+    data: any,
+    rpcService: any
+  ): Promise<void>
+
+  // Version operations
+  upsertWorkflowVersion(
+    name: string,
+    graphHash: string,
+    graph: any,
+    source: string
+  ): Promise<void>
+  getWorkflowVersion(
+    name: string,
+    graphHash: string
+  ): Promise<{ graph: any; source: string } | null>
+}

package/src/types/core.types.ts

@@ -1,10 +1,14 @@
 import type { Logger, LogLevel } from '../services/logger.js'
 import { VariablesService } from '../services/variables-service.js'
+import { SecretService } from '../services/secret-service.js'
 import { SchemaService } from '../services/schema-service.js'
 import { JWTService } from '../services/jwt-service.js'
 import { PikkuHTTP } from '../wirings/http/http.types.js'
-import { SessionService } from '../services/user-session-service.js'
-import { PikkuChannel } from '../wirings/channel/channel.types.js'
+import {
+  PikkuChannel,
+  CorePikkuChannelMiddleware,
+  CorePikkuChannelMiddlewareFactory,
+} from '../wirings/channel/channel.types.js'
 import { PikkuRPC } from '../wirings/rpc/rpc-types.js'
 import { PikkuMCP } from '../wirings/mcp/mcp.types.js'
 import { PikkuScheduledTask } from '../wirings/scheduler/scheduler.types.js'
@@ -16,23 +20,38 @@ import {
   WorkflowServiceConfig,
   WorkflowStepWire,
 } from '../wirings/workflow/workflow.types.js'
+import type { PikkuGraphWire } from '../wirings/workflow/graph/workflow-graph.types.js'
+import { PikkuTrigger } from '../wirings/trigger/trigger.types.js'
 import { SchedulerService } from '../services/scheduler-service.js'
+import { DeploymentService } from '../services/deployment-service.js'
+import { AIStorageService } from '../services/ai-storage-service.js'
+
+import { AIAgentRunnerService } from '../services/ai-agent-runner-service.js'
+import { AIRunStateService } from '../services/ai-run-state-service.js'
+import type { PikkuAIMiddlewareHooks } from '../wirings/ai-agent/ai-agent.types.js'
 
 export type PikkuWiringTypes =
   | 'http'
   | 'scheduler'
+  | 'trigger'
   | 'channel'
   | 'rpc'
   | 'queue'
   | 'mcp'
   | 'cli'
   | 'workflow'
+  | 'agent'
 
 export interface FunctionServicesMeta {
   optimized: boolean
   services: string[]
 }
 
+export interface FunctionWiresMeta {
+  optimized: boolean
+  wires: string[]
+}
+
 /**
  * Metadata for middleware at any level
  * - type: 'http' = HTTP route middleware group (references httpGroup in pikkuState)
@@ -76,19 +95,26 @@ export type PermissionMetadata =
     }
 
 export type FunctionRuntimeMeta = {
-  pikkuFuncName: string
+  pikkuFuncId: string
   inputSchemaName: string | null
   outputSchemaName: string | null
   expose?: boolean
-  internal?: boolean
+  remote?: boolean
+  mcp?: boolean
+  sessionless?: boolean
+  version?: number
+  requiresApproval?: boolean
+  contractHash?: string
 }
 
 export type FunctionMeta = FunctionRuntimeMeta &
   Partial<
     {
       name: string
+      functionType: 'user' | 'inline' | 'helper'
+      funcWrapper: string
       services: FunctionServicesMeta
-      usedWires: string[]
+      wires: FunctionWiresMeta
       inputs: string[] | null
       outputs: string[] | null
       middleware: MiddlewareMetadata[]
@@ -169,12 +195,23 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
   logger: Logger
   /** The variable service to be used */
   variables: VariablesService
+  /** The secrets service to retrieve secrets */
+  secrets: SecretService
   /** The workflow orchestrator service */
   workflowService?: WorkflowService
   /** The queue service */
   queueService?: QueueService
   /** The scheduler service */
   schedulerService?: SchedulerService
+  /** The deployment service for service discovery */
+  deploymentService?: DeploymentService
+  /** AI agent storage service (threads, messages, working memory) */
+  aiStorage?: AIStorageService
+
+  /** AI agent runner service (model calls + tool loop) */
+  aiAgentRunner?: AIAgentRunnerService
+  /** AI run state service (run lifecycle + approval persistence) */
+  aiRunState?: AIRunStateService
 }
 
 /**
@@ -189,7 +226,10 @@ export type PikkuWire<
   IsChannel extends true | null = null,
   MCPTools extends string | never = never,
   TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire,
+  TriggerOutput = unknown,
 > = Partial<{
+  wireType: PikkuWiringTypes
+  wireId: string
   http: PikkuHTTP<In>
   mcp: PikkuMCP<MCPTools>
   rpc: TypedRPC
@@ -201,10 +241,19 @@ export type PikkuWire<
   cli: PikkuCLI
   workflow: TypedWorkflow
   workflowStep: WorkflowStepWire
-  initialSession: HasInitialSession extends true
+  graph: PikkuGraphWire
+  trigger: PikkuTrigger<TriggerOutput>
+  session: HasInitialSession extends true
     ? UserSession
     : UserSession | undefined
-  session: SessionService<UserSession>
+  /** Update and persist the current session */
+  setSession: (session: CoreUserSession) => Promise<void> | void
+  /** Clear and persist the current session */
+  clearSession: () => Promise<void> | void
+  /** Fetch the latest session (may read from backing store) */
+  getSession: () => Promise<UserSession> | UserSession | undefined
+  /** Whether the session was modified during this run */
+  hasSessionChanged: () => boolean
 }>
 
 /**
@@ -318,6 +367,30 @@ export const pikkuMiddlewareFactory = <In = any>(
   return factory
 }
 
+export const pikkuChannelMiddleware = <
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  Event = unknown,
+>(
+  middleware: CorePikkuChannelMiddleware<SingletonServices, Event>
+): CorePikkuChannelMiddleware<SingletonServices, Event> => {
+  return middleware
+}
+
+export const pikkuChannelMiddlewareFactory = <In = any>(
+  factory: CorePikkuChannelMiddlewareFactory<In>
+): CorePikkuChannelMiddlewareFactory<In> => {
+  return factory
+}
+
+export type { PikkuAIMiddlewareHooks } from '../wirings/ai-agent/ai-agent.types.js'
+
+export const pikkuAIMiddleware = <
+  State extends Record<string, unknown> = Record<string, unknown>,
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+>(
+  hooks: PikkuAIMiddlewareHooks<State, SingletonServices>
+): PikkuAIMiddlewareHooks<State, SingletonServices> => hooks
+
 /**
  * Represents the core services used by Pikku, including singleton services.
  */
@@ -365,8 +438,9 @@ export type CreateConfig<
  * Represents the documentation for a route, including summary, description, tags, and errors.
  */
 export type CommonWireMeta = {
-  pikkuFuncName: string
+  pikkuFuncId: string
 
+  title?: string
   tags?: string[]
   summary?: string
   description?: string