@pikku/core 0.11.1 → 0.12.0

package/src/schema.ts

@@ -1,28 +1,41 @@
 import { Logger } from './services/logger.js'
 import { SchemaService } from './services/schema-service.js'
-import { UnprocessableContentError } from './errors/errors.js'
+import {
+  MissingSchemaError,
+  UnprocessableContentError,
+} from './errors/errors.js'
 import { pikkuState } from './pikku-state.js'
 
+const schemaKey = (name: string, packageName: string | null): string =>
+  packageName ? `${packageName}:${name}` : name
+
 /**
- * Adds a schema to the global schemas map.
+ * 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).
  * @ignore
  */
-export const addSchema = (name: string, value: any) => {
-  pikkuState('misc', 'schemas').set(name, value)
+export const addSchema = (
+  name: string,
+  value: any,
+  packageName: string | null = null
+) => {
+  pikkuState(packageName, 'misc', 'schemas').set(name, value)
 }
 
 /**
- * Retrieves a schema from the global schemas map.
+ * 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).
  * @returns The schema value or undefined if not found.
  * @ignore
  */
 export const getSchema = (
-  name: string
+  name: string,
+  packageName: string | null = null
 ): Record<string, unknown> | undefined => {
-  return pikkuState('misc', 'schemas').get(name)
+  return pikkuState(packageName, 'misc', 'schemas').get(name)
 }
 
 /**
@@ -36,9 +49,11 @@ export const compileAllSchemas = (
   if (!schemaService) {
     throw new Error('SchemaService needs to be defined to load schemas')
   }
-  const schemas = pikkuState('misc', 'schemas')
-  for (const [name, schema] of schemas) {
-    schemaService.compileSchema(name, schema)
+  for (const [pkgName, packageState] of globalThis.pikkuState!) {
+    const resolvedPkgName = pkgName === '__main__' ? null : pkgName
+    for (const [name, schema] of packageState.misc.schemas) {
+      schemaService.compileSchema(schemaKey(name, resolvedPkgName), schema)
+    }
   }
   validateAllSchemasLoaded(logger, schemaService)
 }
@@ -47,14 +62,15 @@ const validateAllSchemasLoaded = (
   logger: Logger,
   schemaService: SchemaService
 ) => {
-  const routesMeta = pikkuState('http', 'meta')
+  const routesMeta = pikkuState(null, 'http', 'meta')
   const validators = schemaService.getSchemaNames()
 
   const missingSchemas: string[] = []
 
   for (const routePaths of Object.values(routesMeta)) {
     for (const meta of Object.values(routePaths)) {
-      const inputs = pikkuState('function', 'meta')[meta.pikkuFuncName]?.inputs
+      const inputs = pikkuState(null, 'function', 'meta')[meta.pikkuFuncId]
+        ?.inputs
       const input = inputs?.[0]
       if (!input || validators.has(input)) {
         continue
@@ -74,8 +90,12 @@ const validateAllSchemasLoaded = (
   }
 }
 
-export const coerceTopLevelDataFromSchema = (schemaName: string, data: any) => {
-  const schema = pikkuState('misc', 'schemas').get(schemaName)
+export const coerceTopLevelDataFromSchema = (
+  schemaName: string,
+  data: any,
+  packageName: string | null = null
+) => {
+  const schema = pikkuState(packageName, 'misc', 'schemas').get(schemaName)
   for (const key in schema.properties) {
     const property = schema.properties[key]
     if (typeof property === 'boolean') {
@@ -97,7 +117,8 @@ export const validateSchema = async (
   logger: Logger,
   schemaService: SchemaService | undefined,
   schemaName: string | undefined | null,
-  data: any
+  data: any,
+  packageName: string | null = null
 ) => {
   if (schemaService) {
     if (!schemaName) {
@@ -108,8 +129,19 @@ export const validateSchema = async (
         return
       }
     }
-    const schema = pikkuState('misc', 'schemas').get(schemaName)
-    await schemaService.compileSchema(schemaName, schema)
-    await schemaService.validateSchema(schemaName, data)
+    const key = schemaKey(schemaName, packageName)
+    const schemas = pikkuState(packageName, 'misc', 'schemas')
+    const schema = schemas.get(schemaName)
+    if (schema === undefined) {
+      const availableSchemas = Array.from(schemas.keys())
+      logger.error(
+        `Schema '${schemaName}' not found for package '${packageName ?? 'main'}'. Available schemas: ${availableSchemas.join(', ') || '(none)'}`
+      )
+      throw new MissingSchemaError(
+        `Schema '${schemaName}' not found. Ensure schema generation has been run.`
+      )
+    }
+    await schemaService.compileSchema(key, schema)
+    await schemaService.validateSchema(key, data)
   }
 }

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

@@ -0,0 +1,29 @@
+import {
+  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 interface AIAgentRunnerService {
+  stream(params: AIAgentRunnerParams, channel: AIStreamChannel): Promise<void>
+  run(params: AIAgentRunnerParams): Promise<AIAgentRunnerResult>
+}

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

@@ -0,0 +1,20 @@
+import {
+  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 { 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/deployment-service.ts

@@ -0,0 +1,22 @@
+export interface DeploymentServiceConfig {
+  heartbeatInterval?: number
+  heartbeatTtl?: number
+}
+
+export interface DeploymentConfig {
+  deploymentId: string
+  endpoint: string
+  functions?: string[]
+}
+
+export interface DeploymentInfo {
+  deploymentId: string
+  endpoint: string
+}
+
+export interface DeploymentService {
+  init(): Promise<void>
+  start(config: DeploymentConfig): Promise<void>
+  stop(): Promise<void>
+  findFunction(name: string): Promise<DeploymentInfo[]>
+}

package/src/services/gopass-secrets.ts

@@ -0,0 +1,95 @@
+import { execFileSync } from 'child_process'
+import { SecretService } from './secret-service.js'
+
+/**
+ * Service for retrieving secrets from gopass.
+ * Requires gopass to be installed and configured on the system.
+ */
+export class GopassSecretService implements SecretService {
+  /**
+   * Creates an instance of GopassSecretService.
+   * @param prefix - Optional prefix for all secret keys (e.g., 'pikku/' will look up 'pikku/mykey' for key 'mykey')
+   */
+  constructor(private prefix: string = '') {}
+
+  private getFullKey(key: string): string {
+    return this.prefix ? `${this.prefix}${key}` : 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 parsed secret value.
+   * @throws {Error} If the secret is not found or gopass fails.
+   */
+  public async getSecretJSON<R>(key: string): Promise<R> {
+    const value = await this.getSecret(key)
+    return JSON.parse(value)
+  }
+
+  /**
+   * 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 {Error} If the secret is not found or gopass fails.
+   */
+  public async getSecret(key: string): Promise<string> {
+    const fullKey = this.getFullKey(key)
+    try {
+      return execFileSync('gopass', ['show', '-o', fullKey], {
+        encoding: 'utf8',
+      }).trim()
+    } catch (error: any) {
+      throw new Error(`Secret Not Found: ${key}`, { cause: error })
+    }
+  }
+
+  /**
+   * 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.
+   */
+  public async hasSecret(key: string): Promise<boolean> {
+    const fullKey = this.getFullKey(key)
+    try {
+      execFileSync('gopass', ['show', '-o', fullKey], { encoding: 'utf8' })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Stores a JSON value as a secret in gopass.
+   * @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.
+   */
+  public async setSecretJSON(key: string, value: unknown): Promise<void> {
+    const fullKey = this.getFullKey(key)
+    const jsonValue = JSON.stringify(value)
+    try {
+      execFileSync('gopass', ['insert', '-f', fullKey], {
+        encoding: 'utf8',
+        input: jsonValue,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      })
+    } catch (error: any) {
+      throw new Error(`Failed to set secret: ${key}`, { cause: error })
+    }
+  }
+
+  /**
+   * Deletes a secret from gopass.
+   * @param key - The key of the secret to delete.
+   * @returns A promise that resolves when the secret is deleted.
+   */
+  public async deleteSecret(key: string): Promise<void> {
+    const fullKey = this.getFullKey(key)
+    try {
+      execFileSync('gopass', ['rm', '-f', fullKey], { encoding: 'utf8' })
+    } catch {
+      // Ignore errors if secret doesn't exist
+    }
+  }
+}

package/src/services/in-memory-trigger-service.ts

@@ -0,0 +1,68 @@
+import { PikkuTriggerService } from '../wirings/trigger/pikku-trigger-service.js'
+
+/**
+ * In-memory TriggerService implementation.
+ *
+ * Reads both `wireTrigger` declarations and `wireTriggerSource` registrations
+ * from pikkuState. Only starts triggers that have both a declaration and a source.
+ * On fire, invokes target via `ContextAwareRPCService`.
+ *
+ * Single owner — one process runs triggers, no distributed claiming.
+ *
+ * @example
+ * ```typescript
+ * const triggerService = new InMemoryTriggerService()
+ * triggerService.setServices(singletonServices, createWireServices)
+ * await triggerService.start()
+ *
+ * // On shutdown
+ * await triggerService.stop()
+ * ```
+ */
+export class InMemoryTriggerService extends PikkuTriggerService {
+  async start(): Promise<void> {
+    if (!this.singletonServices) {
+      throw new Error(
+        'InMemoryTriggerService requires singletonServices to start triggers'
+      )
+    }
+
+    const triggerTargets = this.getTriggerTargets()
+    const triggerSources = this.getTriggerSources()
+
+    for (const [name, source] of triggerSources) {
+      if (this.activeTriggers.has(name)) {
+        continue
+      }
+
+      const targets = triggerTargets.get(name)
+      if (!targets || targets.length === 0) {
+        this.singletonServices.logger.info(
+          `Trigger source '${name}' has no targets, skipping`
+        )
+        continue
+      }
+
+      try {
+        const triggerInstance = await this.setupTriggerInstance(
+          name,
+          source.input,
+          (data) => this.onTriggerFire(name, targets, data)
+        )
+
+        this.activeTriggers.set(name, triggerInstance)
+        this.singletonServices.logger.info(`Started trigger: ${name}`)
+      } catch (error) {
+        this.singletonServices.logger.error(
+          `Failed to start trigger ${name}: ${error}`
+        )
+      }
+    }
+
+    if (this.activeTriggers.size === 0) {
+      this.singletonServices.logger.info(
+        'No triggers started (no matching sources and targets found)'
+      )
+    }
+  }
+}