@pikku/core 0.11.2 → 0.12.1

package/src/pikku-state.ts

@@ -1,22 +1,31 @@
-import { PikkuPackageState } from './index.js'
-import { HTTPWiringsMeta } from './wirings/http/http.types.js'
-import {
+import type { PikkuPackageState } from './index.js'
+import type {
+  CoreSingletonServices,
+  CreateWireServices,
+} from './types/core.types.js'
+import type { HTTPWiringsMeta } from './wirings/http/http.types.js'
+import type {
   MCPResourceMeta,
   MCPToolMeta,
   MCPPromptMeta,
 } from './wirings/mcp/mcp.types.js'
-import { ScheduledTasksMeta } from './wirings/scheduler/scheduler.types.js'
-import { TriggerMeta } from './wirings/trigger/trigger.types.js'
+import type { AIAgentMeta } from './wirings/ai-agent/ai-agent.types.js'
+import type { ScheduledTasksMeta } from './wirings/scheduler/scheduler.types.js'
+import type { TriggerMeta } from './wirings/trigger/trigger.types.js'
 
-declare global {
-  // eslint-disable-next-line no-var
-  var pikkuState: Map<string, PikkuPackageState> | undefined
+const PIKKU_STATE_KEY = Symbol.for('@pikku/core/state')
+
+export const getAllPackageStates = (): Map<string, PikkuPackageState> => {
+  if (!(globalThis as any)[PIKKU_STATE_KEY]) {
+    ;(globalThis as any)[PIKKU_STATE_KEY] = new Map<string, PikkuPackageState>()
+  }
+  return (globalThis as any)[PIKKU_STATE_KEY] as Map<string, PikkuPackageState>
 }
 
 /**
  * Get or set package-scoped pikku state
  *
- * @param packageName - Package name (null for main package, '@scope/package' for external packages)
+ * @param packageName - Package name (null for main package, '@scope/package' for addon packages)
  * @param type - State category (function, rpc, http, etc.)
  * @param content - Content key within the category
  * @param value - Optional value to set
@@ -26,7 +35,7 @@ declare global {
  * // Main package
  * pikkuState(null, 'function', 'functions').get(funcName)
  *
- * // External package
+ * // Addon package
  * pikkuState('@acme/stripe-functions', 'rpc', 'meta')
  */
 export const pikkuState = <
@@ -41,14 +50,11 @@ export const pikkuState = <
   const resolvedPackageName = packageName ?? '__main__'
 
   // Initialize package state if it doesn't exist
-  if (
-    !globalThis.pikkuState ||
-    !globalThis.pikkuState.has(resolvedPackageName)
-  ) {
+  if (!getAllPackageStates().has(resolvedPackageName)) {
     initializePikkuState(resolvedPackageName)
   }
 
-  const packageState = globalThis.pikkuState!.get(resolvedPackageName)!
+  const packageState = getAllPackageStates().get(resolvedPackageName)!
 
   if (value !== undefined) {
     packageState[type][content] = value
@@ -65,7 +71,7 @@ const createEmptyPackageState = (): PikkuPackageState => ({
   rpc: {
     meta: {},
     files: new Map(),
-    externalPackages: new Map(),
+    addons: new Map(),
   },
   http: {
     middleware: new Map(),
@@ -95,23 +101,26 @@ const createEmptyPackageState = (): PikkuPackageState => ({
   },
   workflows: {
     registrations: new Map(),
-    graphRegistrations: new Map(),
-    wirings: new Map(),
-    graphWirings: new Map(),
     meta: {},
   },
   trigger: {
+    functions: new Map(),
     triggers: new Map(),
+    triggerSources: new Map(),
     meta: {} as TriggerMeta,
+    sourceMeta: {},
   },
   mcp: {
     resources: new Map(),
     resourcesMeta: {} as MCPResourceMeta,
-    tools: new Map(),
     toolsMeta: {} as MCPToolMeta,
     prompts: new Map(),
     promptsMeta: {} as MCPPromptMeta,
   },
+  agent: {
+    agents: new Map(),
+    agentsMeta: {} as AIAgentMeta,
+  },
   cli: {
     meta: { programs: {}, renderers: {} },
     programs: {},
@@ -119,24 +128,28 @@ const createEmptyPackageState = (): PikkuPackageState => ({
   middleware: {
     tagGroup: {},
     httpGroup: {},
-    tagGroupMeta: {},
-    httpGroupMeta: {},
+  },
+  channelMiddleware: {
+    tagGroup: {},
   },
   permissions: {
     tagGroup: {},
     httpGroup: {},
-    tagGroupMeta: {},
-    httpGroupMeta: {},
   },
   misc: {
     errors: new Map(),
     schemas: new Map(),
     middleware: {},
+    channelMiddleware: {},
     permissions: {},
   },
+  models: {
+    config: null,
+  },
   package: {
     factories: null,
     singletonServices: null,
+    metaDir: null,
   },
 })
 
@@ -144,37 +157,48 @@ const createEmptyPackageState = (): PikkuPackageState => ({
  * Initialize state for a new package
  */
 export const initializePikkuState = (packageName: string): void => {
-  if (!globalThis.pikkuState) {
-    globalThis.pikkuState = new Map()
-  }
-  if (!globalThis.pikkuState.has(packageName)) {
-    globalThis.pikkuState.set(packageName, createEmptyPackageState())
+  if (!getAllPackageStates().has(packageName)) {
+    getAllPackageStates().set(packageName, createEmptyPackageState())
   }
 }
 
 export const resetPikkuState = () => {
   // Preserve the errors map before resetting
-  const existingErrors = globalThis.pikkuState?.get('__main__')?.misc.errors
+  const existingErrors = getAllPackageStates().get('__main__')?.misc.errors
 
-  globalThis.pikkuState = new Map()
+  ;(globalThis as any)[PIKKU_STATE_KEY] = new Map<string, PikkuPackageState>()
   initializePikkuState('__main__')
 
   // Restore the errors map if it existed
   if (existingErrors) {
-    const mainState = globalThis.pikkuState.get('__main__')!
+    const mainState = getAllPackageStates().get('__main__')!
     mainState.misc.errors = existingErrors
   }
 }
 
-if (!globalThis.pikkuState) {
+if (!getAllPackageStates().has('__main__')) {
   resetPikkuState()
 }
 
+export const getPikkuMetaDir = (packageName?: string | null): string | null => {
+  return pikkuState(packageName ?? null, 'package', 'metaDir')
+}
+
+export const getSingletonServices = (): CoreSingletonServices => {
+  const services = pikkuState(null, 'package', 'singletonServices')
+  if (!services) throw new Error('Singleton services not initialized')
+  return services
+}
+
+export const getCreateWireServices = (): CreateWireServices | undefined => {
+  return pikkuState(null, 'package', 'factories')?.createWireServices
+}
+
 /**
- * Register service factories for an external package.
+ * Register service factories for an addon package.
  * These factories are used to create services when the package's functions are invoked.
  *
- * @param packageName - The package name (e.g., '@pikku/templates-function-external')
+ * @param packageName - The package name (e.g., '@pikku/templates-function-addon')
  * @param factories - The service factory functions
  */
 export const addPackageServiceFactories = (

package/src/run-tests-script.test.ts

@@ -0,0 +1,49 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const thisDir = path.dirname(fileURLToPath(import.meta.url))
+const packageRoot = path.resolve(thisDir, '..')
+const runTestsScriptPath = path.join(packageRoot, 'run-tests.sh')
+
+describe('run-tests.sh discovery behavior', () => {
+  test('returns success by default when no tests are found', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pikku-core-tests-'))
+    const srcDir = path.join(tempDir, 'src')
+    fs.mkdirSync(srcDir, { recursive: true })
+    fs.copyFileSync(runTestsScriptPath, path.join(tempDir, 'run-tests.sh'))
+
+    const result = spawnSync('bash', ['run-tests.sh'], {
+      cwd: tempDir,
+      encoding: 'utf8',
+      env: { ...process.env, CI: 'false' },
+    })
+
+    assert.equal(result.status, 0)
+    assert.match(result.stdout, /No test files found matching pattern/)
+
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  })
+
+  test('returns failure in strict mode when no tests are found', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pikku-core-tests-'))
+    const srcDir = path.join(tempDir, 'src')
+    fs.mkdirSync(srcDir, { recursive: true })
+    fs.copyFileSync(runTestsScriptPath, path.join(tempDir, 'run-tests.sh'))
+
+    const result = spawnSync('bash', ['run-tests.sh'], {
+      cwd: tempDir,
+      encoding: 'utf8',
+      env: { ...process.env, STRICT_TEST_DISCOVERY: '1' },
+    })
+
+    assert.equal(result.status, 1)
+    assert.match(result.stdout, /No test files found matching pattern/)
+
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  })
+})

package/src/schema.test.ts

@@ -1,11 +1,55 @@
-import { test, describe, before } from 'node:test'
+import { test, describe, before, beforeEach } from 'node:test'
 import * as assert from 'assert'
-import { addSchema, coerceTopLevelDataFromSchema } from './schema.js'
+import {
+  addSchema,
+  getSchema,
+  coerceTopLevelDataFromSchema,
+  validateSchema,
+  compileAllSchemas,
+} from './schema.js'
+import { resetPikkuState } from './pikku-state.js'
 
 describe('Schema', () => {
-  describe('coerceQueryStringToArray', () => {
+  describe('addSchema and getSchema', () => {
+    beforeEach(() => {
+      resetPikkuState()
+    })
+
+    test('should add and retrieve a schema', () => {
+      const schema = { properties: { name: { type: 'string' } } }
+      addSchema('testAdd', schema)
+      const result = getSchema('testAdd')
+      assert.deepStrictEqual(result, schema)
+    })
+
+    test('should return undefined for non-existent schema', () => {
+      const result = getSchema('nonExistent')
+      assert.strictEqual(result, undefined)
+    })
+
+    test('should add schema for specific package', () => {
+      const schema = { properties: { id: { type: 'number' } } }
+      addSchema('pkgSchema', schema, '@addon/pkg')
+      const result = getSchema('pkgSchema', '@addon/pkg')
+      assert.deepStrictEqual(result, schema)
+    })
+
+    test('should not find package schema in main', () => {
+      addSchema('pkgOnly', { properties: {} }, '@addon/pkg')
+      const result = getSchema('pkgOnly', null)
+      assert.strictEqual(result, undefined)
+    })
+
+    test('should unwrap default export', () => {
+      const schema = { default: { properties: { x: { type: 'string' } } } }
+      addSchema('withDefault', schema)
+      const result = getSchema('withDefault')
+      assert.deepStrictEqual(result, { properties: { x: { type: 'string' } } })
+    })
+  })
+
+  describe('coerceTopLevelDataFromSchema', () => {
     before(() => {
-      // Add schemas dynamically using addSchema
       addSchema('testSchema', {
         properties: {
           tags: { type: 'array' },
@@ -16,10 +60,16 @@ describe('Schema', () => {
 
       addSchema('booleanSchema', {
         properties: {
-          isActive: true, // Invalid schema definition, but the function should handle it
+          isActive: true,
           tags: { type: 'array' },
         },
       })
+
+      addSchema('dateSchema', {
+        properties: {
+          createdAt: { type: 'string', format: 'date-time' },
+        },
+      })
     })
 
     test('should split a string into an array for properties of type array', () => {
@@ -51,7 +101,149 @@ describe('Schema', () => {
       const data = { tags: 'a,b,c', isActive: 'true' }
       coerceTopLevelDataFromSchema('booleanSchema', data)
       assert.deepStrictEqual(data.tags, ['a', 'b', 'c'])
-      assert.strictEqual(data.isActive, 'true') // No coercion should happen
+      assert.strictEqual(data.isActive, 'true')
+    })
+
+    test('should coerce date-time strings to Date objects', () => {
+      const data = { createdAt: '2024-01-01T00:00:00Z' } as any
+      coerceTopLevelDataFromSchema('dateSchema', data)
+      assert.ok(data.createdAt instanceof Date)
+    })
+  })
+
+  describe('validateSchema', () => {
+    beforeEach(() => {
+      resetPikkuState()
+    })
+
+    test('should pass when no schema service provided', async () => {
+      const logger = {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      } as any
+      await validateSchema(logger, undefined, 'some-schema', { data: 1 })
+    })
+
+    test('should warn when no schema name but data is passed', async () => {
+      let warningMsg = ''
+      const logger = {
+        info: () => {},
+        warn: (msg: string) => {
+          warningMsg = msg
+        },
+        error: () => {},
+        debug: () => {},
+      } as any
+      const schemaService = {
+        compileSchema: async () => {},
+        validateSchema: async () => {},
+        getSchemaNames: () => new Set<string>(),
+      }
+      await assert.rejects(
+        () => validateSchema(logger, schemaService, null, { key: 'value' }),
+        (err: any) => err.message === 'No data expected'
+      )
+    })
+
+    test('should return early when no schema name and empty data', async () => {
+      const logger = {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      } as any
+      const schemaService = {
+        compileSchema: async () => {},
+        validateSchema: async () => {},
+        getSchemaNames: () => new Set<string>(),
+      }
+      await validateSchema(logger, schemaService, null, {})
+    })
+
+    test('should throw MissingSchemaError when schema not found', async () => {
+      const logger = {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      } as any
+      const schemaService = {
+        compileSchema: async () => {},
+        validateSchema: async () => {},
+        getSchemaNames: () => new Set<string>(),
+      }
+      await assert.rejects(
+        () => validateSchema(logger, schemaService, 'nonExistent', { data: 1 }),
+        (err: any) => err.message.includes('not found')
+      )
+    })
+
+    test('should compile and validate schema when found', async () => {
+      addSchema('validSchema', { properties: { name: { type: 'string' } } })
+      const logger = {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      } as any
+      let compiled = false
+      let validated = false
+      const schemaService = {
+        compileSchema: async () => {
+          compiled = true
+        },
+        validateSchema: async () => {
+          validated = true
+        },
+        getSchemaNames: () => new Set<string>(),
+      }
+      await validateSchema(logger, schemaService, 'validSchema', {
+        name: 'test',
+      })
+      assert.strictEqual(compiled, true)
+      assert.strictEqual(validated, true)
+    })
+  })
+
+  describe('compileAllSchemas', () => {
+    beforeEach(() => {
+      resetPikkuState()
+    })
+
+    test('should throw when no schema service available', () => {
+      const logger = {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      } as any
+      assert.throws(() => compileAllSchemas(logger), {
+        message: 'SchemaService needs to be defined to load schemas',
+      })
+    })
+
+    test('should compile all schemas across packages', () => {
+      addSchema('schema1', { properties: { a: { type: 'string' } } })
+      addSchema('schema2', { properties: { b: { type: 'number' } } })
+
+      const compiled: string[] = []
+      const logger = {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      } as any
+      const schemaService = {
+        compileSchema: (name: string, _schema: any) => {
+          compiled.push(name)
+        },
+        getSchemaNames: () => new Set(compiled),
+      }
+      compileAllSchemas(logger, schemaService as any)
+      assert.ok(compiled.includes('schema1'))
+      assert.ok(compiled.includes('schema2'))
     })
   })
 })

package/src/schema.ts

@@ -1,13 +1,19 @@
-import { Logger } from './services/logger.js'
-import { SchemaService } from './services/schema-service.js'
-import { UnprocessableContentError } from './errors/errors.js'
-import { pikkuState } from './pikku-state.js'
+import type { Logger } from './services/logger.js'
+import type { SchemaService } from './services/schema-service.js'
+import {
+  MissingSchemaError,
+  UnprocessableContentError,
+} from './errors/errors.js'
+import { pikkuState, getAllPackageStates } from './pikku-state.js'
+
+const schemaKey = (name: string, packageName: string | null): string =>
+  packageName ? `${packageName}:${name}` : name
 
 /**
  * Adds a schema to the schemas map for a specific package.
  * @param name - The name of the schema.
  * @param value - The schema value.
- * @param packageName - The package name (null for main package, '@scope/package' for external packages).
+ * @param packageName - The package name (null for main package, '@scope/package' for addon packages).
  * @ignore
  */
 export const addSchema = (
@@ -15,13 +21,14 @@ export const addSchema = (
   value: any,
   packageName: string | null = null
 ) => {
-  pikkuState(packageName, 'misc', 'schemas').set(name, value)
+  const schema = value?.default ?? value
+  pikkuState(packageName, 'misc', 'schemas').set(name, schema)
 }
 
 /**
  * Retrieves a schema from the schemas map for a specific package.
  * @param name - The name of the schema.
- * @param packageName - The package name (null for main package, '@scope/package' for external packages).
+ * @param packageName - The package name (null for main package, '@scope/package' for addon packages).
  * @returns The schema value or undefined if not found.
  * @ignore
  */
@@ -40,12 +47,17 @@ export const compileAllSchemas = (
   logger: Logger,
   schemaService?: SchemaService
 ) => {
+  if (!schemaService) {
+    schemaService = pikkuState(null, 'package', 'singletonServices')?.schema
+  }
   if (!schemaService) {
     throw new Error('SchemaService needs to be defined to load schemas')
   }
-  const schemas = pikkuState(null, 'misc', 'schemas')
-  for (const [name, schema] of schemas) {
-    schemaService.compileSchema(name, schema)
+  for (const [pkgName, packageState] of getAllPackageStates()) {
+    const resolvedPkgName = pkgName === '__main__' ? null : pkgName
+    for (const [name, schema] of packageState.misc.schemas) {
+      schemaService.compileSchema(schemaKey(name, resolvedPkgName), schema)
+    }
   }
   validateAllSchemasLoaded(logger, schemaService)
 }
@@ -61,7 +73,7 @@ const validateAllSchemasLoaded = (
 
   for (const routePaths of Object.values(routesMeta)) {
     for (const meta of Object.values(routePaths)) {
-      const inputs = pikkuState(null, 'function', 'meta')[meta.pikkuFuncName]
+      const inputs = pikkuState(null, 'function', 'meta')[meta.pikkuFuncId]
         ?.inputs
       const input = inputs?.[0]
       if (!input || validators.has(input)) {
@@ -121,10 +133,7 @@ export const validateSchema = async (
         return
       }
     }
-    logger.debug(
-      `[validateSchema] Validating schema '${schemaName}' for package '${packageName ?? 'main'}' with data:`,
-      JSON.stringify(data)
-    )
+    const key = schemaKey(schemaName, packageName)
     const schemas = pikkuState(packageName, 'misc', 'schemas')
     const schema = schemas.get(schemaName)
     if (schema === undefined) {
@@ -132,13 +141,11 @@ export const validateSchema = async (
       logger.error(
         `Schema '${schemaName}' not found for package '${packageName ?? 'main'}'. Available schemas: ${availableSchemas.join(', ') || '(none)'}`
       )
-    } else {
-      logger.debug(
-        `[validateSchema] Found schema '${schemaName}':`,
-        JSON.stringify(schema)
+      throw new MissingSchemaError(
+        `Schema '${schemaName}' not found. Ensure schema generation has been run.`
       )
     }
-    await schemaService.compileSchema(schemaName, schema)
-    await schemaService.validateSchema(schemaName, data)
+    await schemaService.compileSchema(key, schema)
+    await schemaService.validateSchema(key, data)
   }
 }

package/src/services/ai-agent-runner-service.ts

@@ -0,0 +1,41 @@
+import type {
+  AIMessage,
+  AIAgentStep,
+  AIAgentToolDef,
+  AIStreamChannel,
+} from '../wirings/ai-agent/ai-agent.types.js'
+
+export type AIAgentRunnerParams = {
+  model: string
+  temperature?: number
+  instructions: string
+  messages: AIMessage[]
+  tools: AIAgentToolDef[]
+  maxSteps: number
+  toolChoice: 'auto' | 'required' | 'none'
+  outputSchema?: Record<string, unknown>
+}
+
+export type AIAgentRunnerResult = {
+  text: string
+  object?: unknown
+  steps: AIAgentStep[]
+  usage: { inputTokens: number; outputTokens: number }
+}
+
+export type AIAgentStepResult = {
+  text: string
+  object?: unknown
+  toolCalls: { toolCallId: string; toolName: string; args: unknown }[]
+  toolResults: { toolCallId: string; toolName: string; result: unknown }[]
+  usage: { inputTokens: number; outputTokens: number }
+  finishReason: 'stop' | 'tool-calls' | 'length' | 'error' | 'unknown'
+}
+
+export interface AIAgentRunnerService {
+  stream(
+    params: AIAgentRunnerParams,
+    channel: AIStreamChannel
+  ): Promise<AIAgentStepResult>
+  run(params: AIAgentRunnerParams): Promise<AIAgentStepResult>
+}

package/src/services/ai-run-state-service.ts

@@ -0,0 +1,20 @@
+import type {
+  AgentRunState,
+  PendingApproval,
+} from '../wirings/ai-agent/ai-agent.types.js'
+
+export type CreateRunInput = Omit<AgentRunState, 'runId'>
+
+export interface AIRunStateService {
+  createRun(run: CreateRunInput): Promise<string>
+  updateRun(runId: string, updates: Partial<AgentRunState>): Promise<void>
+  getRun(runId: string): Promise<AgentRunState | null>
+  getRunsByThread(threadId: string): Promise<AgentRunState[]>
+  resolveApproval(
+    toolCallId: string,
+    status: 'approved' | 'denied'
+  ): Promise<void>
+  findRunByToolCallId(
+    toolCallId: string
+  ): Promise<{ run: AgentRunState; approval: PendingApproval } | null>
+}

package/src/services/ai-storage-service.ts

@@ -0,0 +1,39 @@
+import type { AIThread, AIMessage } from '../wirings/ai-agent/ai-agent.types.js'
+
+export interface AIStorageService {
+  createThread(
+    resourceId: string,
+    options?: {
+      threadId?: string
+      title?: string
+      metadata?: Record<string, unknown>
+    }
+  ): Promise<AIThread>
+
+  getThread(threadId: string): Promise<AIThread>
+
+  getThreads(resourceId: string): Promise<AIThread[]>
+
+  deleteThread(threadId: string): Promise<void>
+
+  getMessages(
+    threadId: string,
+    options?: {
+      lastN?: number
+      cursor?: string
+    }
+  ): Promise<AIMessage[]>
+
+  saveMessages(threadId: string, messages: AIMessage[]): Promise<void>
+
+  getWorkingMemory(
+    id: string,
+    scope: 'resource' | 'thread'
+  ): Promise<Record<string, unknown> | null>
+
+  saveWorkingMemory(
+    id: string,
+    scope: 'resource' | 'thread',
+    data: Record<string, unknown>
+  ): Promise<void>
+}

package/src/services/content-service.ts

@@ -66,4 +66,11 @@ export interface ContentService {
    * @returns A readable file stream.
    */
   readFile(assetKey: string): Promise<ReadableStream | NodeJS.ReadableStream>
+
+  /**
+   * Reads an entire file from storage into a Buffer.
+   * @param assetKey - The key of the file to read.
+   * @returns The file contents as a Buffer.
+   */
+  readFileAsBuffer(assetKey: string): Promise<Buffer>
 }