@pikku/core 0.11.2 → 0.12.0

package/src/services/local-variables.ts

@@ -14,4 +14,26 @@ export class LocalVariablesService implements VariablesService {
   public get(name: string): Promise<string | undefined> | string | undefined {
     return this.variables[name]
   }
+
+  public getJSON<T = unknown>(name: string): T | undefined {
+    const value = this.variables[name]
+    if (value === undefined) return undefined
+    return JSON.parse(value)
+  }
+
+  public set(name: string, value: string): void {
+    this.variables[name] = value
+  }
+
+  public setJSON(name: string, value: unknown): void {
+    this.variables[name] = JSON.stringify(value)
+  }
+
+  public has(name: string): boolean {
+    return name in this.variables && this.variables[name] !== undefined
+  }
+
+  public delete(name: string): void {
+    delete this.variables[name]
+  }
 }

package/src/services/scheduler-service.ts

@@ -1,4 +1,5 @@
-import { CoreUserSession } from '../types/core.types.js'
+import type { CoreUserSession } from '../types/core.types.js'
+import type { Logger } from './logger.js'
 
 /**
  * Minimal metadata for listing scheduled tasks
@@ -24,6 +25,16 @@ export interface ScheduledTaskInfo extends ScheduledTaskSummary {
   status?: 'scheduled' | 'active' | 'completed' | 'failed'
 }
 
+export interface SchedulerRuntimeHandlers {
+  logger: Logger
+  invokeRPC: (
+    rpcName: string,
+    data?: any,
+    session?: CoreUserSession
+  ) => Promise<void>
+  runScheduledTask: (name: string) => Promise<void>
+}
+
 /**
  * Abstract scheduler service for persistent scheduled task management
  * Implementations use queue backends (pg-boss, BullMQ) for distributed scheduling
@@ -73,4 +84,21 @@ export abstract class SchedulerService {
    * Close any open connections
    */
   abstract close(): Promise<void>
+
+  /**
+   * Set services needed for processing recurring tasks.
+   * Called after construction since the scheduler is created before
+   * singletonServices are fully assembled.
+   */
+  setServices(_handlers: SchedulerRuntimeHandlers): void {}
+
+  /**
+   * Start recurring scheduled tasks
+   */
+  async start(): Promise<void> {}
+
+  /**
+   * Stop recurring scheduled tasks
+   */
+  async stop(): Promise<void> {}
 }

package/src/services/schema-service.ts

@@ -23,4 +23,11 @@ export interface SchemaService {
    * @returns {Set<string>} A set containing the names of all available schemas.
    */
   getSchemaNames: () => Set<string>
+
+  /**
+   * Retrieves the property keys from a compiled JSON schema.
+   * @param {string} schemaName - The name of the schema.
+   * @returns {string[]} An array of property keys, or empty array if schema not found.
+   */
+  getSchemaKeys: (schemaName: string) => string[]
 }

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

@@ -0,0 +1,41 @@
+import { SecretService } from './secret-service.js'
+
+/**
+ * A read-only wrapper around SecretService that restricts access
+ * to only a defined set of allowed secret keys.
+ */
+export class ScopedSecretService implements SecretService {
+  constructor(
+    private secrets: SecretService,
+    private allowedKeys: Set<string>
+  ) {}
+
+  private assertAllowed(key: string): void {
+    if (!this.allowedKeys.has(key)) {
+      throw new Error(`Access denied to secret key: ${key}`)
+    }
+  }
+
+  async getSecret(key: string): Promise<string> {
+    this.assertAllowed(key)
+    return this.secrets.getSecret(key)
+  }
+
+  async getSecretJSON<T = {}>(key: string): Promise<T> {
+    this.assertAllowed(key)
+    return this.secrets.getSecretJSON<T>(key)
+  }
+
+  async hasSecret(key: string): Promise<boolean> {
+    this.assertAllowed(key)
+    return this.secrets.hasSecret(key)
+  }
+
+  async setSecretJSON(_key: string, _value: unknown): Promise<void> {
+    throw new Error('setSecretJSON is not allowed in scoped secret service')
+  }
+
+  async deleteSecret(_key: string): Promise<void> {
+    throw new Error('deleteSecret is not allowed in scoped secret service')
+  }
+}

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

@@ -6,6 +6,7 @@ import {
 } from '../types/core.types.js'
 import {
   WorkflowRun,
+  WorkflowRunWire,
   StepState,
   WorkflowStatus,
 } from '../wirings/workflow/workflow.types.js'
@@ -16,7 +17,13 @@ import {
  */
 export interface WorkflowService {
   // Run-level state operations
-  createRun(workflowName: string, input: any, inline?: boolean): Promise<string>
+  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(
@@ -32,12 +39,13 @@ export interface WorkflowService {
   resumeWorkflow(runId: string): Promise<void>
   setServices(
     singletonServices: CoreSingletonServices,
-    createWireServices: CreateWireServices,
+    createWireServices: CreateWireServices | undefined,
     config: CoreConfig
   ): void
   startWorkflow<I>(
     name: string,
     input: I,
+    wire: WorkflowRunWire,
     rpcService: any,
     options?: { inline?: boolean; startNode?: string }
   ): Promise<{ runId: string }>
@@ -71,4 +79,16 @@ export interface WorkflowService {
     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

@@ -4,8 +4,11 @@ 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'
@@ -20,22 +23,35 @@ import {
 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)
@@ -79,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[]
@@ -180,6 +203,15 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
   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
 }
 
 /**
@@ -196,6 +228,8 @@ export type PikkuWire<
   TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire,
   TriggerOutput = unknown,
 > = Partial<{
+  wireType: PikkuWiringTypes
+  wireId: string
   http: PikkuHTTP<In>
   mcp: PikkuMCP<MCPTools>
   rpc: TypedRPC
@@ -209,10 +243,17 @@ export type PikkuWire<
   workflowStep: WorkflowStepWire
   graph: PikkuGraphWire
   trigger: PikkuTrigger<TriggerOutput>
-  initialSession: HasInitialSession extends true
+  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
 }>
 
 /**
@@ -239,8 +280,8 @@ export type CorePikkuMiddlewareConfig<
 > = {
   /** The middleware function */
   func: CorePikkuMiddleware<SingletonServices, UserSession>
-  /** Optional human-readable title for the middleware */
-  title?: string
+  /** Optional human-readable name for the middleware */
+  name?: string
   /** Optional description of what the middleware does */
   description?: string
 }
@@ -283,7 +324,7 @@ export type CorePikkuMiddlewareGroup<
  *
  * // Configuration object syntax with metadata
  * export const logMiddleware = pikkuMiddleware({
- *   title: 'Request Logger',
+ *   name: 'Request Logger',
  *   description: 'Logs request information',
  *   func: async ({ logger }, next) => {
  *     logger.info('Request started')
@@ -326,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.
  */
@@ -373,7 +438,7 @@ 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[]