@pikku/core 0.11.2 → 0.12.1

package/dist/schema.js

@@ -1,19 +1,21 @@
-import { UnprocessableContentError } from './errors/errors.js';
-import { pikkuState } from './pikku-state.js';
+import { MissingSchemaError, UnprocessableContentError, } from './errors/errors.js';
+import { pikkuState, getAllPackageStates } from './pikku-state.js';
+const schemaKey = (name, packageName) => 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 = (name, value, packageName = 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
  */
@@ -25,12 +27,17 @@ export const getSchema = (name, packageName = null) => {
  * @param logger - A logger for logging information.
  */
 export const compileAllSchemas = (logger, 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);
 };
@@ -40,7 +47,7 @@ const validateAllSchemasLoaded = (logger, schemaService) => {
     const missingSchemas = [];
     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)) {
@@ -88,17 +95,15 @@ export const validateSchema = async (logger, schemaService, schemaName, data, pa
                 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) {
             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.`);
         }
-        else {
-            logger.debug(`[validateSchema] Found schema '${schemaName}':`, JSON.stringify(schema));
-        }
-        await schemaService.compileSchema(schemaName, schema);
-        await schemaService.validateSchema(schemaName, data);
+        await schemaService.compileSchema(key, schema);
+        await schemaService.validateSchema(key, data);
     }
 };

package/dist/services/ai-agent-runner-service.d.ts

@@ -0,0 +1,43 @@
+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/dist/services/ai-agent-runner-service.js

@@ -0,0 +1 @@
+export {};

package/dist/services/ai-run-state-service.d.ts

@@ -0,0 +1,13 @@
+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/dist/services/ai-run-state-service.js

@@ -0,0 +1 @@
+export {};

package/dist/services/ai-storage-service.d.ts

@@ -0,0 +1,18 @@
+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/dist/services/ai-storage-service.js

@@ -0,0 +1 @@
+export {};

package/dist/services/content-service.d.ts

@@ -49,4 +49,10 @@ 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>;
 }

package/dist/services/deployment-service.d.ts

@@ -0,0 +1,19 @@
+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/dist/services/deployment-service.js

@@ -0,0 +1 @@
+export {};

package/dist/services/gopass-secrets.d.ts

@@ -0,0 +1,47 @@
+import type { SecretService } from './secret-service.js';
+/**
+ * Service for retrieving secrets from gopass.
+ * Requires gopass to be installed and configured on the system.
+ */
+export declare class GopassSecretService implements SecretService {
+    private prefix;
+    /**
+     * 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(prefix?: string);
+    private getFullKey;
+    /**
+     * 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.
+     */
+    getSecretJSON<R>(key: string): Promise<R>;
+    /**
+     * 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.
+     */
+    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.
+     */
+    hasSecret(key: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    setSecretJSON(key: string, value: unknown): Promise<void>;
+    /**
+     * Deletes a secret from gopass.
+     * @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/dist/services/gopass-secrets.js

@@ -0,0 +1,97 @@
+import { execFileSync } from 'child_process';
+/**
+ * Service for retrieving secrets from gopass.
+ * Requires gopass to be installed and configured on the system.
+ */
+export class GopassSecretService {
+    prefix;
+    /**
+     * 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(prefix = '') {
+        this.prefix = prefix;
+    }
+    getFullKey(key) {
+        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.
+     */
+    async getSecretJSON(key) {
+        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.
+     */
+    async getSecret(key) {
+        const fullKey = this.getFullKey(key);
+        try {
+            return execFileSync('gopass', ['show', '-o', fullKey], {
+                encoding: 'utf8',
+            }).trim();
+        }
+        catch (error) {
+            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.
+     */
+    async hasSecret(key) {
+        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.
+     */
+    async setSecretJSON(key, value) {
+        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) {
+            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.
+     */
+    async deleteSecret(key) {
+        const fullKey = this.getFullKey(key);
+        try {
+            execFileSync('gopass', ['rm', '-f', fullKey], { encoding: 'utf8' });
+        }
+        catch {
+            // Ignore errors if secret doesn't exist
+        }
+    }
+}

package/dist/services/in-memory-ai-run-state-service.d.ts

@@ -0,0 +1,15 @@
+import type { AIRunStateService, CreateRunInput } from './ai-run-state-service.js';
+import type { AgentRunState, PendingApproval } from '../wirings/ai-agent/ai-agent.types.js';
+export declare class InMemoryAIRunStateService implements AIRunStateService {
+    private runs;
+    private counter;
+    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/dist/services/in-memory-ai-run-state-service.js

@@ -0,0 +1,44 @@
+export class InMemoryAIRunStateService {
+    runs = new Map();
+    counter = 0;
+    async createRun(run) {
+        const runId = `run-${++this.counter}-${Date.now()}`;
+        this.runs.set(runId, { ...run, runId });
+        return runId;
+    }
+    async updateRun(runId, updates) {
+        const run = this.runs.get(runId);
+        if (run) {
+            Object.assign(run, updates, { updatedAt: new Date() });
+        }
+    }
+    async getRun(runId) {
+        return this.runs.get(runId) ?? null;
+    }
+    async getRunsByThread(threadId) {
+        return [...this.runs.values()].filter((r) => r.threadId === threadId);
+    }
+    async resolveApproval(toolCallId, status) {
+        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) {
+        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/dist/services/in-memory-trigger-service.d.ts

@@ -0,0 +1,22 @@
+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()
+ * await triggerService.start()
+ *
+ * // On shutdown
+ * await triggerService.stop()
+ * ```
+ */
+export declare class InMemoryTriggerService extends PikkuTriggerService {
+    start(): Promise<void>;
+}

package/dist/services/in-memory-trigger-service.js

@@ -0,0 +1,48 @@
+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() {
+        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)');
+        }
+    }
+}

package/dist/services/in-memory-workflow-service.d.ts

@@ -0,0 +1,59 @@
+import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js';
+import type { SerializedError } from '../types/core.types.js';
+import type { WorkflowRun, WorkflowRunWire, StepState, WorkflowStatus, WorkflowStepOptions } from '../wirings/workflow/workflow.types.js';
+/**
+ * In-memory implementation of WorkflowService for inline-only execution
+ *
+ * This is a lightweight workflow service that stores all state in memory.
+ * It only supports inline execution (no queue workers) and is ideal for:
+ * - CLI tools that need workflow-like step orchestration
+ * - Testing and development
+ * - Single-process applications without persistence requirements
+ *
+ * @example
+ * ```typescript
+ * const workflowService = new InMemoryWorkflowService()
+ * await workflowService.startWorkflow('myWorkflow', input, { type: 'cli' }, rpc, { inline: true })
+ * ```
+ */
+export declare class InMemoryWorkflowService extends PikkuWorkflowService {
+    private runs;
+    private steps;
+    private stepData;
+    private stepHistory;
+    private runState;
+    private branchKeys;
+    private workflowVersions;
+    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(id: string, status: WorkflowStatus, output?: any, error?: SerializedError): Promise<void>;
+    insertStepState(runId: string, stepName: string, rpcName: string | null, data: any, stepOptions?: WorkflowStepOptions): Promise<StepState>;
+    getStepState(runId: string, stepName: string): Promise<StepState>;
+    setStepRunning(stepId: string): Promise<void>;
+    setStepScheduled(stepId: string): Promise<void>;
+    setStepResult(stepId: string, result: any): Promise<void>;
+    setStepError(stepId: string, error: Error): Promise<void>;
+    createRetryAttempt(failedStepId: string, status: 'pending' | 'running'): Promise<StepState>;
+    withRunLock<T>(_id: string, fn: () => Promise<T>): Promise<T>;
+    withStepLock<T>(_runId: string, _stepName: string, fn: () => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+    getCompletedGraphState(runId: string): Promise<{
+        completedNodeIds: string[];
+        failedNodeIds: string[];
+        branchKeys: Record<string, string>;
+    }>;
+    getNodesWithoutSteps(runId: string, nodeIds: string[]): Promise<string[]>;
+    getNodeResults(runId: string, nodeIds: string[]): Promise<Record<string, any>>;
+    setBranchKey(runId: string, nodeId: string, branchKey: string): Promise<void>;
+    setBranchTaken(stepId: string, branchKey: string): Promise<void>;
+    updateRunState(runId: string, name: string, value: unknown): Promise<void>;
+    getRunState(runId: string): Promise<Record<string, unknown>>;
+    upsertWorkflowVersion(name: string, graphHash: string, graph: any, source: string): Promise<void>;
+    getWorkflowVersion(name: string, graphHash: string): Promise<{
+        graph: any;
+        source: string;
+    } | null>;
+}