@pikku/core 0.12.4 → 0.12.5

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

@@ -0,0 +1,76 @@
+export interface ContentService {
+  /**
+   * Signs a content key to generate a secure, time-limited access URL.
+   * @param contentKey - The key representing the content object.
+   * @param dateLessThan - The expiration time for the signed URL.
+   * @param dateGreaterThan - (Optional) Start time before which access is denied.
+   */
+  signContentKey(
+    contentKey: string,
+    dateLessThan: Date,
+    dateGreaterThan?: Date
+  ): Promise<string>
+
+  /**
+   * Signs an arbitrary URL to generate a secure, time-limited access URL.
+   * @param url - The full URL that needs signing.
+   * @param dateLessThan - The expiration time for the signed URL.
+   * @param dateGreaterThan - (Optional) Start time before which access is denied.
+   */
+  signURL(
+    url: string,
+    dateLessThan: Date,
+    dateGreaterThan?: Date
+  ): Promise<string>
+
+  /**
+   * Generates a signed URL for uploading a file directly to storage.
+   * @param fileKey - The desired key/location of the uploaded file.
+   * @param contentType - The MIME type of the file.
+   * @returns A signed upload URL and the finalized asset key.
+   */
+  getUploadURL(
+    fileKey: string,
+    contentType: string
+  ): Promise<{ uploadUrl: string; assetKey: string }>
+
+  /**
+   * Deletes a file from the storage backend.
+   * @param fileName - The name or key of the file to delete.
+   * @returns A boolean indicating success.
+   */
+  deleteFile(fileName: string): Promise<boolean>
+
+  /**
+   * Uploads a file stream to storage under a specified asset key.
+   * @param assetKey - The key where the file will be saved.
+   * @param stream - A readable stream of the file contents.
+   * @returns A boolean indicating success.
+   */
+  writeFile(
+    assetKey: string,
+    stream: ReadableStream | NodeJS.ReadableStream
+  ): Promise<boolean>
+
+  /**
+   * Copies a file from a local absolute path into storage under a new asset key.
+   * @param assetKey - The destination key.
+   * @param fromAbsolutePath - The local absolute file path.
+   * @returns A boolean indicating success.
+   */
+  copyFile(assetKey: string, fromAbsolutePath: string): Promise<boolean>
+
+  /**
+   * Reads a file from storage as a readable stream.
+   * @param assetKey - The key of the file to read.
+   * @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>
+}

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/gateway-service.ts

@@ -0,0 +1,20 @@
+/**
+ * Abstract GatewayService interface.
+ *
+ * Implementations manage listener gateway lifecycle — initializing adapters
+ * and delivering messages to handler functions.
+ *
+ * A `LocalGatewayService` starts all listeners unconditionally;
+ * a distributed implementation could check leader election first.
+ */
+export interface GatewayService {
+  /**
+   * Start all listener gateways
+   */
+  start(): Promise<void>
+
+  /**
+   * Stop all listener gateways
+   */
+  stop(): Promise<void>
+}

package/src/services/gopass-secrets.ts

@@ -0,0 +1,98 @@
+import { execFileSync } from 'child_process'
+import type { 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 {
+    if (!/^[\w.\-/]+$/.test(key)) {
+      throw new Error(`Invalid secret key format: ${key}`)
+    }
+    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-ai-run-state-service.ts

@@ -0,0 +1,73 @@
+import type {
+  AIRunStateService,
+  CreateRunInput,
+} from './ai-run-state-service.js'
+import type {
+  AgentRunState,
+  PendingApproval,
+} from '../wirings/ai-agent/ai-agent.types.js'
+
+export class InMemoryAIRunStateService implements AIRunStateService {
+  private runs = new Map<string, AgentRunState>()
+  private counter = 0
+
+  async createRun(run: CreateRunInput): Promise<string> {
+    const runId = `run-${++this.counter}-${Date.now()}`
+    this.runs.set(runId, { ...run, runId })
+    return runId
+  }
+
+  async updateRun(
+    runId: string,
+    updates: Partial<AgentRunState>
+  ): Promise<void> {
+    const run = this.runs.get(runId)
+    if (run) {
+      Object.assign(run, updates, { updatedAt: new Date() })
+    }
+  }
+
+  async getRun(runId: string): Promise<AgentRunState | null> {
+    return this.runs.get(runId) ?? null
+  }
+
+  async getRunsByThread(threadId: string): Promise<AgentRunState[]> {
+    return [...this.runs.values()].filter((r) => r.threadId === threadId)
+  }
+
+  async resolveApproval(
+    toolCallId: string,
+    status: 'approved' | 'denied'
+  ): Promise<void> {
+    for (const run of this.runs.values()) {
+      if (run.pendingApprovals) {
+        const approval = run.pendingApprovals.find(
+          (a) => a.toolCallId === toolCallId
+        )
+        if (approval) {
+          run.pendingApprovals = run.pendingApprovals.filter(
+            (a) => a.toolCallId !== toolCallId
+          )
+          run.updatedAt = new Date()
+          return
+        }
+      }
+    }
+  }
+
+  async findRunByToolCallId(
+    toolCallId: string
+  ): Promise<{ run: AgentRunState; approval: PendingApproval } | null> {
+    for (const run of this.runs.values()) {
+      if (run.pendingApprovals) {
+        const approval = run.pendingApprovals.find(
+          (a) => a.toolCallId === toolCallId
+        )
+        if (approval) {
+          return { run, approval }
+        }
+      }
+    }
+    return null
+  }
+}

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

@@ -0,0 +1,64 @@
+import { PikkuTriggerService } from '../wirings/trigger/pikku-trigger-service.js'
+import { getSingletonServices } from '../pikku-state.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()
+ * await triggerService.start()
+ *
+ * // On shutdown
+ * await triggerService.stop()
+ * ```
+ */
+export class InMemoryTriggerService extends PikkuTriggerService {
+  async start(): Promise<void> {
+    const singletonServices = getSingletonServices()
+
+    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) {
+        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)
+        singletonServices.logger.info(`Started trigger: ${name}`)
+      } catch (error) {
+        singletonServices.logger.error(
+          `Failed to start trigger ${name}: ${error}`
+        )
+      }
+    }
+
+    if (this.activeTriggers.size === 0) {
+      singletonServices.logger.info(
+        'No triggers started (no matching sources and targets found)'
+      )
+    }
+  }
+}