@pikku/core 0.11.1 → 0.12.0

package/dist/schema.d.ts

@@ -1,23 +1,25 @@
 import { Logger } from './services/logger.js';
 import { SchemaService } from './services/schema-service.js';
 /**
- * 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 declare const addSchema: (name: string, value: any) => void;
+export declare const addSchema: (name: string, value: any, packageName?: string | null) => void;
 /**
- * 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 declare const getSchema: (name: string) => Record<string, unknown> | undefined;
+export declare const getSchema: (name: string, packageName?: string | null) => Record<string, unknown> | undefined;
 /**
  * Loads a schema and compiles it into a validator.
  * @param logger - A logger for logging information.
  */
 export declare const compileAllSchemas: (logger: Logger, schemaService?: SchemaService) => void;
-export declare const coerceTopLevelDataFromSchema: (schemaName: string, data: any) => void;
-export declare const validateSchema: (logger: Logger, schemaService: SchemaService | undefined, schemaName: string | undefined | null, data: any) => Promise<void>;
+export declare const coerceTopLevelDataFromSchema: (schemaName: string, data: any, packageName?: string | null) => void;
+export declare const validateSchema: (logger: Logger, schemaService: SchemaService | undefined, schemaName: string | undefined | null, data: any, packageName?: string | null) => Promise<void>;

package/dist/schema.js

@@ -1,22 +1,25 @@
-import { UnprocessableContentError } from './errors/errors.js';
+import { MissingSchemaError, UnprocessableContentError, } from './errors/errors.js';
 import { pikkuState } from './pikku-state.js';
+const schemaKey = (name, packageName) => 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, value) => {
-    pikkuState('misc', 'schemas').set(name, value);
+export const addSchema = (name, value, packageName = 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) => {
-    return pikkuState('misc', 'schemas').get(name);
+export const getSchema = (name, packageName = null) => {
+    return pikkuState(packageName, 'misc', 'schemas').get(name);
 };
 /**
  * Loads a schema and compiles it into a validator.
@@ -26,19 +29,22 @@ export const compileAllSchemas = (logger, schemaService) => {
     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);
 };
 const validateAllSchemasLoaded = (logger, schemaService) => {
-    const routesMeta = pikkuState('http', 'meta');
+    const routesMeta = pikkuState(null, 'http', 'meta');
     const validators = schemaService.getSchemaNames();
     const missingSchemas = [];
     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;
@@ -55,8 +61,8 @@ const validateAllSchemasLoaded = (logger, schemaService) => {
         logger.info('All schemas loaded');
     }
 };
-export const coerceTopLevelDataFromSchema = (schemaName, data) => {
-    const schema = pikkuState('misc', 'schemas').get(schemaName);
+export const coerceTopLevelDataFromSchema = (schemaName, data, packageName = null) => {
+    const schema = pikkuState(packageName, 'misc', 'schemas').get(schemaName);
     for (const key in schema.properties) {
         const property = schema.properties[key];
         if (typeof property === 'boolean') {
@@ -74,7 +80,7 @@ export const coerceTopLevelDataFromSchema = (schemaName, data) => {
         }
     }
 };
-export const validateSchema = async (logger, schemaService, schemaName, data) => {
+export const validateSchema = async (logger, schemaService, schemaName, data, packageName = null) => {
     if (schemaService) {
         if (!schemaName) {
             if (data && (data.length > 0 || Object.keys(data).length > 0)) {
@@ -85,8 +91,15 @@ export const validateSchema = async (logger, schemaService, schemaName, data) =>
                 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/dist/services/ai-agent-runner-service.d.ts

@@ -0,0 +1,24 @@
+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/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 { 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 { 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/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 { 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,94 @@
+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) {
+        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-trigger-service.d.ts

@@ -0,0 +1,23 @@
+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 declare class InMemoryTriggerService extends PikkuTriggerService {
+    start(): Promise<void>;
+}

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

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

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>;
+}