@pikku/core 0.11.2 → 0.12.1

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.test.ts

@@ -0,0 +1,113 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import {
+  PikkuSessionService,
+  createMiddlewareSessionWireProps,
+  createFunctionSessionWireProps,
+} from './user-session-service.js'
+
+describe('PikkuSessionService', () => {
+  test('should set and get session', () => {
+    const service = new PikkuSessionService()
+    service.setInitial({ userId: 'user-1' })
+    const session = service.get()
+    assert.deepStrictEqual(session, { userId: 'user-1' })
+  })
+
+  test('should return undefined when no session set', () => {
+    const service = new PikkuSessionService()
+    assert.strictEqual(service.get(), undefined)
+  })
+
+  test('should mark sessionChanged when set is called', () => {
+    const service = new PikkuSessionService()
+    assert.strictEqual(service.sessionChanged, false)
+    service.set({ userId: 'user-1' })
+    assert.strictEqual(service.sessionChanged, true)
+  })
+
+  test('should clear session', () => {
+    const service = new PikkuSessionService()
+    service.setInitial({ userId: 'user-1' })
+    service.clear()
+    assert.strictEqual(service.get(), undefined)
+    assert.strictEqual(service.sessionChanged, true)
+  })
+
+  test('should freeze initial session', () => {
+    const service = new PikkuSessionService()
+    service.setInitial({ userId: 'user-1' })
+    const frozen = service.freezeInitial()
+    assert.deepStrictEqual(frozen, { userId: 'user-1' })
+  })
+
+  test('should only freeze initial once', () => {
+    const service = new PikkuSessionService()
+    service.setInitial({ userId: 'user-1' })
+    service.freezeInitial()
+    service.set({ userId: 'user-2' })
+    const frozen2 = service.freezeInitial()
+    assert.deepStrictEqual(frozen2, { userId: 'user-1' })
+  })
+
+  test('should throw when channelStore provided without channelId', () => {
+    assert.throws(() => new PikkuSessionService({} as any), {
+      message: 'Channel ID is required when using channel store',
+    })
+  })
+
+  test('should use channelStore when provided', async () => {
+    let storedSession: any
+    const store = {
+      setUserSession: (id: string, session: any) => {
+        storedSession = session
+      },
+      getChannelAndSession: (id: string) => ({ session: { userId: 'stored' } }),
+    }
+    const service = new PikkuSessionService(store as any, 'ch-1')
+    service.set({ userId: 'new' })
+    assert.deepStrictEqual(storedSession, { userId: 'new' })
+
+    const session = service.get()
+    assert.deepStrictEqual(session, { userId: 'stored' })
+  })
+})
+
+describe('createMiddlewareSessionWireProps', () => {
+  test('should return session wire props', () => {
+    const service = new PikkuSessionService()
+    service.setInitial({ userId: 'user-1' })
+    const props = createMiddlewareSessionWireProps(service)
+    assert.ok('session' in props)
+    assert.ok('setSession' in props)
+    assert.ok('getSession' in props)
+    assert.ok('hasSessionChanged' in props)
+  })
+
+  test('setSession should call setInitial', () => {
+    const service = new PikkuSessionService()
+    const props = createMiddlewareSessionWireProps(service)
+    props.setSession({ userId: 'user-2' })
+    assert.deepStrictEqual(service.get(), { userId: 'user-2' })
+  })
+})
+
+describe('createFunctionSessionWireProps', () => {
+  test('should return function session wire props', () => {
+    const service = new PikkuSessionService()
+    service.setInitial({ userId: 'user-1' })
+    const props = createFunctionSessionWireProps(service)
+    assert.ok('session' in props)
+    assert.ok('setSession' in props)
+    assert.ok('clearSession' in props)
+    assert.ok('getSession' in props)
+    assert.ok('hasSessionChanged' in props)
+  })
+
+  test('session should be frozen initial', () => {
+    const service = new PikkuSessionService()
+    service.setInitial({ userId: 'user-1' })
+    const props = createFunctionSessionWireProps(service)
+    assert.deepStrictEqual(props.session, { userId: 'user-1' })
+  })
+})

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

@@ -1,5 +1,5 @@
-import { ChannelStore } from '../wirings/channel/channel-store.js'
-import { CoreUserSession } from '../types/core.types.js'
+import type { ChannelStore } from '../wirings/channel/channel-store.js'
+import type { CoreUserSession } from '../types/core.types.js'
 
 export interface SessionService<UserSession extends CoreUserSession> {
   sessionChanged: boolean
@@ -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() as UserSession | undefined,
+    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

@@ -1,11 +1,7 @@
-import {
-  SerializedError,
-  CoreSingletonServices,
-  CreateWireServices,
-  CoreConfig,
-} from '../types/core.types.js'
-import {
+import type { SerializedError } from '../types/core.types.js'
+import type {
   WorkflowRun,
+  WorkflowRunWire,
   StepState,
   WorkflowStatus,
 } from '../wirings/workflow/workflow.types.js'
@@ -16,7 +12,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(
@@ -30,14 +32,10 @@ export interface WorkflowService {
 
   // Orchestration operations
   resumeWorkflow(runId: string): Promise<void>
-  setServices(
-    singletonServices: CoreSingletonServices,
-    createWireServices: CreateWireServices,
-    config: CoreConfig
-  ): void
   startWorkflow<I>(
     name: string,
     input: I,
+    wire: WorkflowRunWire,
     rpcService: any,
     options?: { inline?: boolean; startNode?: string }
   ): Promise<{ runId: string }>
@@ -71,4 +69,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/time-utils.test.ts

@@ -1,10 +1,10 @@
 import { describe, test } from 'node:test'
 import assert from 'node:assert/strict'
 
+import type { RelativeTimeInput } from './time-utils'
 import {
   getRelativeTimeOffset,
   getRelativeTimeOffsetFromNow,
-  RelativeTimeInput,
 } from './time-utils'
 
 const approxEqual = (a: number, b: number, delta: number = 10): boolean =>

package/src/types/core.types.ts

@@ -1,41 +1,58 @@
 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 { PikkuRPC } from '../wirings/rpc/rpc-types.js'
-import { PikkuMCP } from '../wirings/mcp/mcp.types.js'
-import { PikkuScheduledTask } from '../wirings/scheduler/scheduler.types.js'
-import { PikkuQueue, QueueService } from '../wirings/queue/queue.types.js'
-import { PikkuCLI } from '../wirings/cli/cli.types.js'
-import {
+import type { VariablesService } from '../services/variables-service.js'
+import type { SecretService } from '../services/secret-service.js'
+import type { SchemaService } from '../services/schema-service.js'
+import type { JWTService } from '../services/jwt-service.js'
+import type { PikkuHTTP } from '../wirings/http/http.types.js'
+import type {
+  PikkuChannel,
+  CorePikkuChannelMiddleware,
+  CorePikkuChannelMiddlewareFactory,
+} from '../wirings/channel/channel.types.js'
+import type { PikkuRPC } from '../wirings/rpc/rpc-types.js'
+import type { PikkuMCP } from '../wirings/mcp/mcp.types.js'
+import type { PikkuScheduledTask } from '../wirings/scheduler/scheduler.types.js'
+import type { PikkuQueue, QueueService } from '../wirings/queue/queue.types.js'
+import type { PikkuCLI } from '../wirings/cli/cli.types.js'
+import type {
   PikkuWorkflowWire,
   WorkflowService,
   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 type { PikkuTrigger } from '../wirings/trigger/trigger.types.js'
+import type { SchedulerService } from '../services/scheduler-service.js'
+import type { DeploymentService } from '../services/deployment-service.js'
+import type { AIStorageService } from '../services/ai-storage-service.js'
+
+import type { ContentService } from '../services/content-service.js'
+import type { AIAgentRunnerService } from '../services/ai-agent-runner-service.js'
+import type { 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 +96,29 @@ export type PermissionMetadata =
     }
 
 export type FunctionRuntimeMeta = {
-  pikkuFuncName: string
+  pikkuFuncId: string
   inputSchemaName: string | null
   outputSchemaName: string | null
   expose?: boolean
-  internal?: boolean
+  remote?: boolean
+  mcp?: boolean
+  readonly?: boolean
+  sessionless?: boolean
+  version?: number
+  requiresApproval?: boolean
+  contractHash?: string
+  inputHash?: string
+  outputHash?: 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 +207,17 @@ 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
+
+  /** Content service for file storage and retrieval */
+  content?: ContentService
+  /** AI agent runner service (model calls + tool loop) */
+  aiAgentRunner?: AIAgentRunnerService
+  /** AI run state service (run lifecycle + approval persistence) */
+  aiRunState?: AIRunStateService
 }
 
 /**
@@ -196,6 +234,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 +249,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 +286,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 +330,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 +373,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 +444,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[]