@pikku/core 0.12.13 → 0.12.15

package/dist/services/meta-service.js

@@ -0,0 +1,310 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Node.js filesystem implementation of MetaService.
+ * Reads .gen.json files from a local .pikku directory.
+ */
+export class LocalMetaService {
+    basePath;
+    httpMetaCache = null;
+    channelsMetaCache = null;
+    schedulerMetaCache = null;
+    queueMetaCache = null;
+    cliMetaCache = null;
+    mcpMetaCache = null;
+    rpcMetaCache = null;
+    workflowMetaCache = null;
+    triggerMetaCache = null;
+    triggerSourceMetaCache = null;
+    functionsMetaCache = null;
+    servicesMetaCache = null;
+    secretsMetaCache = null;
+    credentialsMetaCache = null;
+    variablesMetaCache = null;
+    middlewareGroupsMetaCache = null;
+    permissionsGroupsMetaCache = null;
+    agentsMetaCache = null;
+    schemaCache = new Map();
+    constructor(basePath) {
+        this.basePath = basePath;
+    }
+    async readFile(relativePath) {
+        try {
+            return await readFile(join(this.basePath, relativePath), 'utf-8');
+        }
+        catch {
+            return null;
+        }
+    }
+    async readDir(relativePath) {
+        try {
+            return await readdir(join(this.basePath, relativePath));
+        }
+        catch {
+            return [];
+        }
+    }
+    clearCache() {
+        this.httpMetaCache = null;
+        this.channelsMetaCache = null;
+        this.schedulerMetaCache = null;
+        this.queueMetaCache = null;
+        this.cliMetaCache = null;
+        this.mcpMetaCache = null;
+        this.rpcMetaCache = null;
+        this.workflowMetaCache = null;
+        this.triggerMetaCache = null;
+        this.triggerSourceMetaCache = null;
+        this.functionsMetaCache = null;
+        this.servicesMetaCache = null;
+        this.secretsMetaCache = null;
+        this.credentialsMetaCache = null;
+        this.variablesMetaCache = null;
+        this.middlewareGroupsMetaCache = null;
+        this.permissionsGroupsMetaCache = null;
+        this.agentsMetaCache = null;
+        this.schemaCache.clear();
+    }
+    // -- Private helpers --
+    async readMetaJson(dir, baseName) {
+        const verbose = await this.readFile(`${dir}/${baseName}-verbose.gen.json`);
+        if (verbose)
+            return verbose;
+        const minimal = await this.readFile(`${dir}/${baseName}.gen.json`);
+        if (minimal)
+            return minimal;
+        return null;
+    }
+    // -- Typed metadata accessors --
+    async getHttpMeta() {
+        if (this.httpMetaCache)
+            return this.httpMetaCache;
+        const content = await this.readMetaJson('http', 'pikku-http-wirings-meta');
+        this.httpMetaCache = content
+            ? JSON.parse(content)
+            : {
+                get: {},
+                post: {},
+                put: {},
+                delete: {},
+                patch: {},
+                head: {},
+                options: {},
+            };
+        return this.httpMetaCache;
+    }
+    async getChannelsMeta() {
+        if (this.channelsMetaCache)
+            return this.channelsMetaCache;
+        const content = await this.readMetaJson('channel', 'pikku-channels-meta');
+        this.channelsMetaCache = content ? JSON.parse(content) : {};
+        return this.channelsMetaCache;
+    }
+    async getSchedulerMeta() {
+        if (this.schedulerMetaCache)
+            return this.schedulerMetaCache;
+        const content = await this.readMetaJson('scheduler', 'pikku-schedulers-wirings-meta');
+        this.schedulerMetaCache = content ? JSON.parse(content) : {};
+        return this.schedulerMetaCache;
+    }
+    async getQueueMeta() {
+        if (this.queueMetaCache)
+            return this.queueMetaCache;
+        const content = await this.readMetaJson('queue', 'pikku-queue-workers-wirings-meta');
+        this.queueMetaCache = content ? JSON.parse(content) : {};
+        return this.queueMetaCache;
+    }
+    async getCliMeta() {
+        if (this.cliMetaCache)
+            return this.cliMetaCache;
+        const content = await this.readMetaJson('cli', 'pikku-cli-wirings-meta');
+        this.cliMetaCache = content
+            ? JSON.parse(content)
+            : { programs: {}, renderers: {} };
+        return this.cliMetaCache;
+    }
+    async getMcpMeta() {
+        if (this.mcpMetaCache)
+            return this.mcpMetaCache;
+        const content = await this.readMetaJson('mcp', 'pikku-mcp-wirings-meta');
+        if (content) {
+            const mcpData = JSON.parse(content);
+            this.mcpMetaCache = {
+                resources: mcpData.resourcesMeta || {},
+                tools: mcpData.toolsMeta || {},
+                prompts: mcpData.promptsMeta || {},
+            };
+        }
+        else {
+            this.mcpMetaCache = { resources: {}, tools: {}, prompts: {} };
+        }
+        return this.mcpMetaCache;
+    }
+    async getRpcMeta() {
+        if (this.rpcMetaCache)
+            return this.rpcMetaCache;
+        try {
+            const content = await this.readFile('rpc/pikku-rpc-wirings-meta.gen.json');
+            this.rpcMetaCache = content ? JSON.parse(content) : {};
+            return this.rpcMetaCache;
+        }
+        catch (error) {
+            console.error('Error reading RPC wirings metadata:', error);
+            this.rpcMetaCache = {};
+            return this.rpcMetaCache;
+        }
+    }
+    async getWorkflowMeta() {
+        if (this.workflowMetaCache)
+            return this.workflowMetaCache;
+        try {
+            const files = await this.readDir('workflow/meta');
+            const jsonFiles = files.filter((f) => f.endsWith('.gen.json'));
+            const verboseFiles = jsonFiles.filter((f) => f.includes('-verbose'));
+            const minimalFiles = jsonFiles.filter((f) => !f.includes('-verbose'));
+            const verboseNames = new Set(verboseFiles.map((f) => f.replace('-verbose.gen.json', '')));
+            const filesToRead = [
+                ...verboseFiles,
+                ...minimalFiles.filter((f) => !verboseNames.has(f.replace('.gen.json', ''))),
+            ];
+            const result = {};
+            await Promise.all(filesToRead.map(async (file) => {
+                const content = await this.readFile(`workflow/meta/${file}`);
+                if (content) {
+                    const meta = JSON.parse(content);
+                    result[meta.name] = meta;
+                }
+            }));
+            this.workflowMetaCache = result;
+            return this.workflowMetaCache;
+        }
+        catch (error) {
+            console.error('Error reading Workflow wirings metadata:', error);
+            this.workflowMetaCache = {};
+            return this.workflowMetaCache;
+        }
+    }
+    async getTriggerMeta() {
+        if (this.triggerMetaCache)
+            return this.triggerMetaCache;
+        const content = await this.readMetaJson('trigger', 'pikku-trigger-wirings-meta');
+        this.triggerMetaCache = content ? JSON.parse(content) : {};
+        return this.triggerMetaCache;
+    }
+    async getTriggerSourceMeta() {
+        if (this.triggerSourceMetaCache)
+            return this.triggerSourceMetaCache;
+        const content = await this.readMetaJson('trigger', 'pikku-trigger-sources-meta');
+        this.triggerSourceMetaCache = content ? JSON.parse(content) : {};
+        return this.triggerSourceMetaCache;
+    }
+    async getFunctionsMeta() {
+        if (this.functionsMetaCache)
+            return this.functionsMetaCache;
+        const content = await this.readMetaJson('function', 'pikku-functions-meta');
+        this.functionsMetaCache = content ? JSON.parse(content) : {};
+        return this.functionsMetaCache;
+    }
+    async getMiddlewareGroupsMeta() {
+        if (this.middlewareGroupsMetaCache)
+            return this.middlewareGroupsMetaCache;
+        const content = await this.readMetaJson('middleware', 'pikku-middleware-groups-meta');
+        this.middlewareGroupsMetaCache = content
+            ? JSON.parse(content)
+            : { definitions: {}, instances: {}, httpGroups: {}, tagGroups: {} };
+        return this.middlewareGroupsMetaCache;
+    }
+    async getPermissionsGroupsMeta() {
+        if (this.permissionsGroupsMetaCache)
+            return this.permissionsGroupsMetaCache;
+        const content = await this.readMetaJson('permissions', 'pikku-permissions-groups-meta');
+        this.permissionsGroupsMetaCache = content
+            ? JSON.parse(content)
+            : { definitions: {}, httpGroups: {}, tagGroups: {} };
+        return this.permissionsGroupsMetaCache;
+    }
+    async getAgentsMeta() {
+        if (this.agentsMetaCache)
+            return this.agentsMetaCache;
+        const content = await this.readMetaJson('agent', 'pikku-agent-wirings-meta');
+        if (content) {
+            const parsed = JSON.parse(content);
+            this.agentsMetaCache = parsed.agentsMeta || parsed;
+        }
+        else {
+            this.agentsMetaCache = {};
+        }
+        return this.agentsMetaCache;
+    }
+    async getSecretsMeta() {
+        if (this.secretsMetaCache)
+            return this.secretsMetaCache;
+        const content = await this.readFile('secrets/pikku-secrets-meta.gen.json');
+        this.secretsMetaCache = content ? JSON.parse(content) : {};
+        return this.secretsMetaCache;
+    }
+    async getCredentialsMeta() {
+        if (this.credentialsMetaCache)
+            return this.credentialsMetaCache;
+        const content = await this.readFile('credentials/pikku-credentials-meta.gen.json');
+        this.credentialsMetaCache = content ? JSON.parse(content) : {};
+        return this.credentialsMetaCache;
+    }
+    async getVariablesMeta() {
+        if (this.variablesMetaCache)
+            return this.variablesMetaCache;
+        const content = await this.readFile('variables/pikku-variables-meta.gen.json');
+        this.variablesMetaCache = content ? JSON.parse(content) : {};
+        return this.variablesMetaCache;
+    }
+    async getServicesMeta() {
+        if (this.servicesMetaCache)
+            return this.servicesMetaCache;
+        try {
+            const files = await this.readDir('services');
+            const jsonFiles = files.filter((f) => f.endsWith('.gen.json'));
+            const result = {};
+            await Promise.all(jsonFiles.map(async (file) => {
+                const content = await this.readFile(`services/${file}`);
+                if (content) {
+                    const meta = JSON.parse(content);
+                    result[meta.name] = meta;
+                }
+            }));
+            this.servicesMetaCache = result;
+            return this.servicesMetaCache;
+        }
+        catch (error) {
+            console.error('Error reading Services metadata:', error);
+            this.servicesMetaCache = {};
+            return this.servicesMetaCache;
+        }
+    }
+    async getSchema(schemaName) {
+        if (this.schemaCache.has(schemaName)) {
+            return this.schemaCache.get(schemaName);
+        }
+        if (!/^[a-zA-Z0-9_\-\.]+$/.test(schemaName)) {
+            return null;
+        }
+        try {
+            const content = await this.readFile(`schemas/schemas/${schemaName}.schema.json`);
+            if (!content)
+                return null;
+            const schema = JSON.parse(content);
+            this.schemaCache.set(schemaName, schema);
+            return schema;
+        }
+        catch (error) {
+            console.error(`Error reading schema ${schemaName}:`, error);
+            return null;
+        }
+    }
+    async getSchemas(schemaNames) {
+        const results = {};
+        await Promise.all(schemaNames.map(async (name) => {
+            results[name] = await this.getSchema(name);
+        }));
+        return results;
+    }
+}

package/dist/services/pikku-user-id.d.ts

@@ -0,0 +1,3 @@
+import type { PikkuWire } from '../types/core.types.js';
+export type PikkuUserIdResolver = (wire: PikkuWire) => string | undefined;
+export declare const defaultPikkuUserIdResolver: PikkuUserIdResolver;

package/dist/services/pikku-user-id.js

@@ -0,0 +1,16 @@
+export const defaultPikkuUserIdResolver = (wire) => {
+    // Explicit pikkuUserId on wire (set by earlier middleware or runner)
+    if (wire.pikkuUserId)
+        return wire.pikkuUserId;
+    // Session userId (from auth middleware — user-defined session shape)
+    const session = wire.session;
+    if (session?.userId && typeof session.userId === 'string')
+        return session.userId;
+    // Queue job: carried in job metadata
+    if (wire.queue?.pikkuUserId)
+        return wire.queue.pikkuUserId;
+    // Workflow: carried in run wire metadata
+    if (wire.workflow?.pikkuUserId)
+        return wire.workflow.pikkuUserId;
+    return undefined;
+};

package/dist/services/typed-credential-service.d.ts

@@ -22,6 +22,8 @@ export declare class TypedCredentialService<TMap = Record<string, unknown>> impl
     delete(name: string, userId?: string): Promise<void>;
     has(name: string, userId?: string): Promise<boolean>;
     getAll(userId: string): Promise<Record<string, unknown>>;
+    getUsersWithCredential(name: string): Promise<string[]>;
+    getAllUsers(): Promise<string[]>;
     getAllStatus(userId?: string): Promise<CredentialStatusInfo[]>;
     getMissing(userId?: string): Promise<CredentialStatusInfo[]>;
 }

package/dist/services/typed-credential-service.js

@@ -20,6 +20,12 @@ export class TypedCredentialService {
     async getAll(userId) {
         return this.credentials.getAll(userId);
     }
+    async getUsersWithCredential(name) {
+        return this.credentials.getUsersWithCredential(name);
+    }
+    async getAllUsers() {
+        return this.credentials.getAllUsers();
+    }
     async getAllStatus(userId) {
         const results = [];
         for (const [name, meta] of Object.entries(this.credentialsMeta)) {

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

@@ -1,5 +1,5 @@
 import type { SerializedError } from '../types/core.types.js';
-import type { WorkflowRun, WorkflowRunWire, StepState, WorkflowStatus, WorkflowVersionStatus } from '../wirings/workflow/workflow.types.js';
+import type { WorkflowRun, WorkflowRunWire, WorkflowRunStatus, StepState, WorkflowStatus, WorkflowVersionStatus } from '../wirings/workflow/workflow.types.js';
 /**
  * Interface for workflow orchestration
  * Handles workflow execution, replay, orchestration logic, and run-level state
@@ -7,6 +7,7 @@ import type { WorkflowRun, WorkflowRunWire, StepState, WorkflowStatus, WorkflowV
 export interface WorkflowService {
     createRun(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire): Promise<string>;
     getRun(id: string): Promise<WorkflowRun | null>;
+    getRunStatus(id: string): Promise<WorkflowRunStatus | null>;
     getRunHistory(runId: string): Promise<Array<StepState & {
         stepName: string;
     }>>;
@@ -20,6 +21,10 @@ export interface WorkflowService {
     }): Promise<{
         runId: string;
     }>;
+    runToCompletion<I>(name: string, input: I, rpcService: any, options?: {
+        pollIntervalMs?: number;
+        wire?: WorkflowRunWire;
+    }): Promise<unknown>;
     runWorkflowJob(runId: string, rpcService: any): Promise<void>;
     orchestrateWorkflow(runId: string, rpcService: any): Promise<void>;
     executeWorkflowSleepCompleted(runId: string, stepId: string): Promise<void>;

package/dist/testing/service-tests.js

@@ -482,14 +482,6 @@ export function defineServiceTests(config) {
                     endpoint: 'http://localhost:3000',
                     functions: ['funcA', 'funcB'],
                 });
-                const infos = await service.findFunction('funcA');
-                assert.ok(infos.length >= 1);
-                assert.equal(infos[0].deploymentId, 'deploy-1');
-                assert.equal(infos[0].endpoint, 'http://localhost:3000');
-            });
-            test('findFunction returns empty for unknown function', async () => {
-                const infos = await service.findFunction('unknown-func');
-                assert.deepEqual(infos, []);
             });
         });
     }

package/dist/types/core.types.d.ts

@@ -24,6 +24,7 @@ import type { AgentRunService } from '../wirings/ai-agent/ai-agent.types.js';
 import type { PikkuAIMiddlewareHooks } from '../wirings/ai-agent/ai-agent.types.js';
 import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js';
 import type { CredentialService } from '../services/credential-service.js';
+import type { MetaService } from '../services/meta-service.js';
 export type PikkuWiringTypes = 'http' | 'scheduler' | 'trigger' | 'channel' | 'rpc' | 'queue' | 'mcp' | 'cli' | 'workflow' | 'agent' | 'gateway';
 export interface FunctionServicesMeta {
     optimized: boolean;
@@ -75,6 +76,7 @@ export type FunctionRuntimeMeta = {
     remote?: boolean;
     mcp?: boolean;
     readonly?: boolean;
+    deploy?: 'serverless' | 'server' | 'auto';
     sessionless?: boolean;
     version?: number;
     approvalRequired?: boolean;
@@ -94,6 +96,8 @@ export type FunctionMeta = FunctionRuntimeMeta & Partial<{
     middleware: MiddlewareMetadata[];
     permissions: PermissionMetadata[];
     isDirectFunction: boolean;
+    sourceFile: string;
+    exportedName: string;
 } & CommonWireMeta>;
 export type FunctionsRuntimeMeta = Record<string, FunctionRuntimeMeta>;
 export type FunctionsMeta = Record<string, FunctionMeta>;
@@ -175,6 +179,8 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
     workflowRunService?: WorkflowRunService;
     /** Credential service for dynamic/managed credentials (OAuth tokens, per-user API keys) */
     credentialService?: CredentialService;
+    /** Meta service for reading .pikku metadata files (filesystem on Node, R2/KV on CF) */
+    metaService?: MetaService;
 }
 /**
  * Represents different forms of wire within Pikku and the outside world.
@@ -182,6 +188,8 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
 export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boolean = false, UserSession extends CoreUserSession = CoreUserSession, TypedRPC extends PikkuRPC = PikkuRPC, IsChannel extends true | null = null, MCPTools extends string | never = never, TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire, TriggerOutput = unknown> = Partial<{
     wireType: PikkuWiringTypes;
     wireId: string;
+    /** Trace ID for distributed tracing — propagated across remote RPC calls via x-trace-id header */
+    traceId: string;
     http: PikkuHTTP<In>;
     mcp: PikkuMCP<MCPTools>;
     rpc: TypedRPC;
@@ -203,10 +211,14 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     getSession: () => Promise<UserSession> | UserSession | undefined;
     /** Whether the session was modified during this run */
     hasSessionChanged: () => boolean;
+    /** The resolved user identity for credential lookups */
+    pikkuUserId: string;
     /** Set a credential value (available in middleware) */
     setCredential: (name: string, value: unknown) => void;
-    /** Get all resolved credentials (only available in pikkuWireServices) */
-    getCredentials: () => Record<string, unknown>;
+    /** Get a single credential by name — lazy-loads from CredentialService on first call, sync thereafter */
+    getCredential: <T = unknown>(name: string) => T | null | Promise<T | null>;
+    /** Get all resolved credentials — lazy-loads from CredentialService on first call, sync thereafter */
+    getCredentials: () => Record<string, unknown> | Promise<Record<string, unknown>>;
 }>;
 /**
  * A function that can wrap an wire and be called before or after

package/dist/types/state.types.d.ts

@@ -130,7 +130,14 @@ export interface PikkuPackageState {
         } | null;
         /** Cached singleton services for this package */
         singletonServices: CoreSingletonServices | null;
-        /** Absolute path to this package's .pikku directory */
-        metaDir: string | null;
+        /** Credential metadata for this addon package */
+        credentialsMeta: Record<string, {
+            name: string;
+            displayName: string;
+            type: string;
+            oauth2?: boolean;
+        }> | null;
+        /** Services this addon needs from the parent project */
+        requiredParentServices: string[] | null;
     };
 }

package/dist/wirings/ai-agent/ai-agent-prepare.d.ts

@@ -19,6 +19,27 @@ export declare class ToolApprovalRequired extends PikkuError {
     readonly agentRunId?: string;
     constructor(toolCallId: string, toolName: string, args: unknown, reason?: string, displayToolName?: string, displayArgs?: unknown, agentRunId?: string);
 }
+export declare class ToolCredentialRequired extends PikkuError {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly args: unknown;
+    readonly credentialName: string;
+    readonly credentialType: 'oauth2' | 'apikey';
+    readonly connectUrl?: string;
+    constructor(toolCallId: string, toolName: string, args: unknown, credentialName: string, credentialType: 'oauth2' | 'apikey', connectUrl?: string);
+}
+export interface AddonCredentialRequirement {
+    credentialName: string;
+    displayName: string;
+    addonNamespace: string;
+    type: 'wire';
+    oauth2: boolean;
+}
+/**
+ * Given a list of tool names (e.g. ["oauth-api:getProfile"]),
+ * returns the wire OAuth credentials required by their addons.
+ */
+export declare function getAddonCredentialRequirements(toolNames: string[]): AddonCredentialRequirement[];
 export type StreamContext = {
     channel: AIStreamChannel;
     options?: StreamAIAgentOptions;