@pikku/core 0.12.9 → 0.12.11

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## 0.12.4
 
+## 0.12.11
+
+### Patch Changes
+
+- 4e52200: Add \_\_raw CLI channel handler for server-side arg parsing. Enables WebSocket CLI clients to send raw args without needing client-side command metadata.
+
+## 0.12.10
+
+### Patch Changes
+
+- 0f59432: Add per-user credential system with CredentialService, OAuth2 route handlers, and KyselyCredentialService with envelope encryption
+- 52b64d1: Provide workflow wire to graph nodes for sleep/suspend support. Graph nodes now receive a workflow wire alongside the graph wire, enabling tools like `graph:sleep` to work in graph execution context. Improves dynamic workflow system instructions with output path documentation, nested path examples, and design principles for AI agents.
+
 ## 0.12.9
 
 ### Patch Changes

package/dist/function/function-runner.d.ts

@@ -2,11 +2,12 @@ import type { CoreServices, CoreUserSession, CorePikkuMiddleware, PikkuWiringTyp
 import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js';
 import type { CorePermissionGroup, CorePikkuFunctionConfig, CorePikkuPermission } from './functions.types.js';
 import type { SessionService } from '../services/user-session-service.js';
+import type { PikkuCredentialWireService } from '../services/credential-wire-service.js';
 export declare const addFunction: (funcName: string, funcConfig: CorePikkuFunctionConfig<any, any>, packageName?: string | null) => void;
 export declare const getFunctionNames: (packageName?: string | null) => string[];
 export declare const getAllFunctionNames: () => string[];
 export declare const runPikkuFuncDirectly: <In, Out>(funcName: string, allServices: CoreServices, wire: PikkuWire, data: In, userSession?: SessionService<CoreUserSession>, packageName?: string | null) => Promise<Out>;
-export declare const runPikkuFunc: <In = any, Out = any>(wireType: PikkuWiringTypes, wireId: string, funcName: string, { singletonServices, createWireServices, data, auth: wiringAuth, inheritedMiddleware, wireMiddleware, inheritedChannelMiddleware, wireChannelMiddleware, inheritedPermissions, wirePermissions, coerceDataFromSchema, tags, wire, sessionService, packageName, }: {
+export declare const runPikkuFunc: <In = any, Out = any>(wireType: PikkuWiringTypes, wireId: string, funcName: string, { singletonServices, createWireServices, data, auth: wiringAuth, inheritedMiddleware, wireMiddleware, inheritedChannelMiddleware, wireChannelMiddleware, inheritedPermissions, wirePermissions, coerceDataFromSchema, tags, wire, sessionService, credentialWireService, packageName, }: {
     singletonServices: CoreSingletonServices;
     createWireServices?: CreateWireServices;
     data: () => Promise<In> | In;
@@ -21,5 +22,6 @@ export declare const runPikkuFunc: <In = any, Out = any>(wireType: PikkuWiringTy
     tags?: string[];
     wire: PikkuWire;
     sessionService?: SessionService<CoreUserSession>;
+    credentialWireService?: PikkuCredentialWireService;
     packageName?: string | null;
 }) => Promise<Out>;

package/dist/function/function-runner.js

@@ -6,6 +6,7 @@ import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js';
 import { parseVersionedId } from '../version.js';
 import { createFunctionSessionWireProps } from '../services/user-session-service.js';
 import { ForbiddenError, ReadonlySessionError } from '../errors/errors.js';
+import { createWireServicesCredentialWireProps } from '../services/credential-wire-service.js';
 import { rpcService } from '../wirings/rpc/rpc-runner.js';
 import { closeWireServices } from '../utils.js';
 /**
@@ -70,7 +71,7 @@ export const runPikkuFuncDirectly = async (funcName, allServices, wire, data, us
     };
     return (await funcConfig.func(allServices, data, wireWithSession));
 };
-export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServices, createWireServices, data, auth: wiringAuth, inheritedMiddleware, wireMiddleware, inheritedChannelMiddleware, wireChannelMiddleware, inheritedPermissions, wirePermissions, coerceDataFromSchema, tags = [], wire, sessionService, packageName = null, }) => {
+export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServices, createWireServices, data, auth: wiringAuth, inheritedMiddleware, wireMiddleware, inheritedChannelMiddleware, wireChannelMiddleware, inheritedPermissions, wirePermissions, coerceDataFromSchema, tags = [], wire, sessionService, credentialWireService, packageName = null, }) => {
     wire.wireType ??= wireType;
     wire.wireId ??= wireId;
     const funcMap = pikkuState(packageName, 'function', 'functions');
@@ -188,6 +189,9 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
                 packageName,
             });
         }
+        if (credentialWireService) {
+            Object.assign(resolvedWire, createWireServicesCredentialWireProps(credentialWireService));
+        }
         const wireServices = await resolvedCreateWireServices?.(resolvedSingletonServices, resolvedWire);
         try {
             const services = wireServices && Object.keys(wireServices).length > 0

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

@@ -0,0 +1,40 @@
+/**
+ * Interface for managing dynamic/managed credentials.
+ * Used for OAuth tokens, per-user API keys, and other credentials
+ * that change at runtime (as opposed to SecretService which is for
+ * static, developer-configured values).
+ */
+export interface CredentialService {
+    /**
+     * Retrieves a credential by name and optional user ID.
+     * @param name - The credential name (e.g. 'stripe', 'google-sheets').
+     * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
+     * @returns The credential value, or null if not found.
+     */
+    get<T = unknown>(name: string, userId?: string): Promise<T | null>;
+    /**
+     * Stores a credential.
+     * @param name - The credential name.
+     * @param value - The credential value to store.
+     * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
+     */
+    set(name: string, value: unknown, userId?: string): Promise<void>;
+    /**
+     * Deletes a credential.
+     * @param name - The credential name.
+     * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
+     */
+    delete(name: string, userId?: string): Promise<void>;
+    /**
+     * Checks if a credential exists.
+     * @param name - The credential name.
+     * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
+     */
+    has(name: string, userId?: string): Promise<boolean>;
+    /**
+     * Retrieves all credentials for a user.
+     * @param userId - The user ID.
+     * @returns A record of credential name to value.
+     */
+    getAll(userId: string): Promise<Record<string, unknown>>;
+}

package/dist/services/credential-service.js

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

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

@@ -0,0 +1,13 @@
+export declare class PikkuCredentialWireService {
+    private credentials;
+    set(name: string, value: unknown): void;
+    getAll(): Record<string, unknown>;
+    getScoped(allowedNames: string[]): Record<string, unknown>;
+}
+export declare function createMiddlewareCredentialWireProps(credentialWire: PikkuCredentialWireService): {
+    setCredential: (name: string, value: unknown) => void;
+};
+export declare function createWireServicesCredentialWireProps(credentialWire: PikkuCredentialWireService, allowedNames?: string[]): {
+    setCredential: (name: string, value: unknown) => void;
+    getCredentials: () => Record<string, unknown>;
+};

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

@@ -0,0 +1,31 @@
+export class PikkuCredentialWireService {
+    credentials = {};
+    set(name, value) {
+        this.credentials[name] = value;
+    }
+    getAll() {
+        return this.credentials;
+    }
+    getScoped(allowedNames) {
+        const scoped = {};
+        for (const name of allowedNames) {
+            if (name in this.credentials) {
+                scoped[name] = this.credentials[name];
+            }
+        }
+        return scoped;
+    }
+}
+export function createMiddlewareCredentialWireProps(credentialWire) {
+    return {
+        setCredential: (name, value) => credentialWire.set(name, value),
+    };
+}
+export function createWireServicesCredentialWireProps(credentialWire, allowedNames) {
+    return {
+        setCredential: (name, value) => credentialWire.set(name, value),
+        getCredentials: () => allowedNames
+            ? credentialWire.getScoped(allowedNames)
+            : credentialWire.getAll(),
+    };
+}

package/dist/services/index.d.ts

@@ -5,8 +5,10 @@ export { LogLevel } from './logger.js';
 export { ScopedSecretService } from './scoped-secret-service.js';
 export { PikkuSessionService, createMiddlewareSessionWireProps, createFunctionSessionWireProps, } from './user-session-service.js';
 export { TypedSecretService } from './typed-secret-service.js';
+export { PikkuCredentialWireService, createMiddlewareCredentialWireProps, createWireServicesCredentialWireProps, } from './credential-wire-service.js';
 export { TypedVariablesService } from './typed-variables-service.js';
 export { LocalSecretService } from './local-secrets.js';
+export { LocalCredentialService } from './local-credential-service.js';
 export { LocalVariablesService } from './local-variables.js';
 export { ConsoleLogger } from './logger-console.js';
 export { InMemoryWorkflowService } from './in-memory-workflow-service.js';
@@ -28,4 +30,7 @@ export type { AIStorageService } from './ai-storage-service.js';
 export type { AIAgentRunnerParams, AIAgentRunnerResult, AIAgentStepResult, AIAgentRunnerService, } from './ai-agent-runner-service.js';
 export type { CreateRunInput, AIRunStateService, } from './ai-run-state-service.js';
 export type { CredentialStatus, CredentialMeta, } from './typed-secret-service.js';
+export type { CredentialService } from './credential-service.js';
+export { TypedCredentialService } from './typed-credential-service.js';
+export type { CredentialStatusInfo, CredentialMetaInfo, } from './typed-credential-service.js';
 export type { VariableStatus, VariableMeta } from './typed-variables-service.js';

package/dist/services/index.js

@@ -5,11 +5,14 @@ export { LogLevel } from './logger.js';
 export { ScopedSecretService } from './scoped-secret-service.js';
 export { PikkuSessionService, createMiddlewareSessionWireProps, createFunctionSessionWireProps, } from './user-session-service.js';
 export { TypedSecretService } from './typed-secret-service.js';
+export { PikkuCredentialWireService, createMiddlewareCredentialWireProps, createWireServicesCredentialWireProps, } from './credential-wire-service.js';
 export { TypedVariablesService } from './typed-variables-service.js';
 export { LocalSecretService } from './local-secrets.js';
+export { LocalCredentialService } from './local-credential-service.js';
 export { LocalVariablesService } from './local-variables.js';
 export { ConsoleLogger } from './logger-console.js';
 export { InMemoryWorkflowService } from './in-memory-workflow-service.js';
 export { InMemoryTriggerService } from './in-memory-trigger-service.js';
 export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js';
 export { LocalGatewayService } from './local-gateway-service.js';
+export { TypedCredentialService } from './typed-credential-service.js';

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

@@ -0,0 +1,10 @@
+import type { CredentialService } from './credential-service.js';
+export declare class LocalCredentialService implements CredentialService {
+    private store;
+    private makeKey;
+    get<T = unknown>(name: string, userId?: string): Promise<T | null>;
+    set(name: string, value: unknown, userId?: string): Promise<void>;
+    delete(name: string, userId?: string): Promise<void>;
+    has(name: string, userId?: string): Promise<boolean>;
+    getAll(userId: string): Promise<Record<string, unknown>>;
+}

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

@@ -0,0 +1,33 @@
+export class LocalCredentialService {
+    store = new Map();
+    makeKey(name, userId) {
+        return userId ? `${userId}:${name}` : name;
+    }
+    async get(name, userId) {
+        const key = this.makeKey(name, userId);
+        const value = this.store.get(key);
+        return value ?? null;
+    }
+    async set(name, value, userId) {
+        const key = this.makeKey(name, userId);
+        this.store.set(key, value);
+    }
+    async delete(name, userId) {
+        const key = this.makeKey(name, userId);
+        this.store.delete(key);
+    }
+    async has(name, userId) {
+        const key = this.makeKey(name, userId);
+        return this.store.has(key);
+    }
+    async getAll(userId) {
+        const prefix = `${userId}:`;
+        const result = {};
+        for (const [key, value] of this.store) {
+            if (key.startsWith(prefix)) {
+                result[key.slice(prefix.length)] = value;
+            }
+        }
+        return result;
+    }
+}

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

@@ -0,0 +1,27 @@
+import type { CredentialService } from './credential-service.js';
+export interface CredentialStatusInfo {
+    name: string;
+    displayName: string;
+    isConfigured: boolean;
+    type: 'singleton' | 'wire';
+    oauth2?: boolean;
+}
+export type CredentialMetaInfo = {
+    name: string;
+    displayName: string;
+    type: 'singleton' | 'wire';
+    oauth2?: boolean;
+};
+export declare class TypedCredentialService<TMap = Record<string, unknown>> implements CredentialService {
+    private credentials;
+    private credentialsMeta;
+    constructor(credentials: CredentialService, credentialsMeta: Record<string, CredentialMetaInfo>);
+    get<K extends keyof TMap & string>(name: K, userId?: string): Promise<TMap[K] | null>;
+    get<T = unknown>(name: string, userId?: string): Promise<T | null>;
+    set<K extends string>(name: K, value: K extends keyof TMap ? TMap[K] : unknown, userId?: string): Promise<void>;
+    delete(name: string, userId?: string): Promise<void>;
+    has(name: string, userId?: string): Promise<boolean>;
+    getAll(userId: string): Promise<Record<string, unknown>>;
+    getAllStatus(userId?: string): Promise<CredentialStatusInfo[]>;
+    getMissing(userId?: string): Promise<CredentialStatusInfo[]>;
+}

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

@@ -0,0 +1,40 @@
+export class TypedCredentialService {
+    credentials;
+    credentialsMeta;
+    constructor(credentials, credentialsMeta) {
+        this.credentials = credentials;
+        this.credentialsMeta = credentialsMeta;
+    }
+    async get(name, userId) {
+        return this.credentials.get(name, userId);
+    }
+    async set(name, value, userId) {
+        return this.credentials.set(name, value, userId);
+    }
+    async delete(name, userId) {
+        return this.credentials.delete(name, userId);
+    }
+    async has(name, userId) {
+        return this.credentials.has(name, userId);
+    }
+    async getAll(userId) {
+        return this.credentials.getAll(userId);
+    }
+    async getAllStatus(userId) {
+        const results = [];
+        for (const [name, meta] of Object.entries(this.credentialsMeta)) {
+            results.push({
+                name,
+                displayName: meta.displayName,
+                isConfigured: await this.credentials.has(name, userId),
+                type: meta.type,
+                oauth2: meta.oauth2,
+            });
+        }
+        return results;
+    }
+    async getMissing(userId) {
+        const all = await this.getAllStatus(userId);
+        return all.filter((c) => !c.isConfigured);
+    }
+}

package/dist/testing/service-tests.d.ts

@@ -6,6 +6,7 @@ import type { DeploymentService } from '../services/deployment-service.js';
 import type { AIStorageService } from '../services/ai-storage-service.js';
 import type { AIRunStateService } from '../services/ai-run-state-service.js';
 import type { SecretService } from '../services/secret-service.js';
+import type { CredentialService } from '../services/credential-service.js';
 import type { AgentRunService } from '../wirings/ai-agent/ai-agent.types.js';
 export interface ServiceTestConfig {
     name: string;
@@ -26,6 +27,13 @@ export interface ServiceTestConfig {
         }) => Promise<SecretService & {
             rotateKEK?(): Promise<number>;
         }>;
+        credentialService?: (config: {
+            key: string;
+            keyVersion?: number;
+            previousKey?: string;
+        }) => Promise<CredentialService & {
+            rotateKEK?(): Promise<number>;
+        }>;
     };
 }
 export declare function defineServiceTests(config: ServiceTestConfig): void;

package/dist/testing/service-tests.js

@@ -570,6 +570,112 @@ export function defineServiceTests(config) {
             });
         });
     }
+    if (services.credentialService) {
+        const factory = services.credentialService;
+        const kek = 'test-key-encryption-key-32chars!';
+        describe(`CredentialService [${name}]`, () => {
+            test('set and get (global)', async () => {
+                const service = await factory({ key: kek });
+                await service.set('stripe', { apiKey: 'sk-123' });
+                const result = await service.get('stripe');
+                assert.deepEqual(result, { apiKey: 'sk-123' });
+            });
+            test('get returns null for missing', async () => {
+                const service = await factory({ key: kek });
+                const result = await service.get('nonexistent');
+                assert.equal(result, null);
+            });
+            test('has returns true/false', async () => {
+                const service = await factory({ key: kek });
+                await service.set('exists', { key: 'val' });
+                assert.strictEqual(await service.has('exists'), true);
+                assert.strictEqual(await service.has('nope'), false);
+            });
+            test('set upserts existing credential', async () => {
+                const service = await factory({ key: kek });
+                await service.set('upsert', { v: 1 });
+                await service.set('upsert', { v: 2 });
+                const result = await service.get('upsert');
+                assert.deepEqual(result, { v: 2 });
+            });
+            test('delete removes credential', async () => {
+                const service = await factory({ key: kek });
+                await service.set('to-delete', { bye: true });
+                assert.strictEqual(await service.has('to-delete'), true);
+                await service.delete('to-delete');
+                assert.strictEqual(await service.has('to-delete'), false);
+            });
+            test('per-user isolation', async () => {
+                const service = await factory({ key: kek });
+                await service.set('token', { access: 'user1' }, 'user-1');
+                await service.set('token', { access: 'user2' }, 'user-2');
+                const u1 = await service.get('token', 'user-1');
+                const u2 = await service.get('token', 'user-2');
+                assert.deepEqual(u1, { access: 'user1' });
+                assert.deepEqual(u2, { access: 'user2' });
+            });
+            test('per-user delete does not affect other users', async () => {
+                const service = await factory({ key: kek });
+                await service.set('cred', { val: 'a' }, 'user-a');
+                await service.set('cred', { val: 'b' }, 'user-b');
+                await service.delete('cred', 'user-a');
+                assert.strictEqual(await service.has('cred', 'user-a'), false);
+                assert.strictEqual(await service.has('cred', 'user-b'), true);
+            });
+            test('global and per-user are separate', async () => {
+                const service = await factory({ key: kek });
+                await service.set('shared', { scope: 'global' });
+                await service.set('shared', { scope: 'user' }, 'user-1');
+                const global = await service.get('shared');
+                const perUser = await service.get('shared', 'user-1');
+                assert.deepEqual(global, { scope: 'global' });
+                assert.deepEqual(perUser, { scope: 'user' });
+            });
+            test('getAll returns all credentials for a user', async () => {
+                const service = await factory({ key: kek });
+                await service.set('cred-a', { a: 1 }, 'user-x');
+                await service.set('cred-b', { b: 2 }, 'user-x');
+                await service.set('cred-c', { c: 3 }, 'user-y');
+                const all = await service.getAll('user-x');
+                assert.deepEqual(all['cred-a'], { a: 1 });
+                assert.deepEqual(all['cred-b'], { b: 2 });
+                assert.strictEqual(all['cred-c'], undefined);
+            });
+            test('getAll returns empty for unknown user', async () => {
+                const service = await factory({ key: kek });
+                const all = await service.getAll('nobody');
+                assert.deepEqual(all, {});
+            });
+            test('rotateKEK re-wraps all credentials', async () => {
+                const newKEK = 'new-key-encryption-key-rotated!';
+                const oldService = await factory({ key: kek });
+                await oldService.set('rotate-cred', { important: 'data' }, 'user-r');
+                const rotatedService = await factory({
+                    key: newKEK,
+                    keyVersion: 2,
+                    previousKey: kek,
+                });
+                const before = await rotatedService.get('rotate-cred', 'user-r');
+                assert.deepEqual(before, { important: 'data' });
+                assert.ok(rotatedService.rotateKEK);
+                const count = await rotatedService.rotateKEK();
+                assert.ok(count > 0);
+                const newOnlyService = await factory({
+                    key: newKEK,
+                    keyVersion: 2,
+                });
+                const after = await newOnlyService.get('rotate-cred', 'user-r');
+                assert.deepEqual(after, { important: 'data' });
+            });
+            test('rotateKEK throws without previousKey', async () => {
+                const service = await factory({ key: kek });
+                assert.ok(service.rotateKEK);
+                await assert.rejects(() => service.rotateKEK(), {
+                    message: 'No previousKey configured — nothing to rotate from',
+                });
+            });
+        });
+    }
     if (services.agentRunService) {
         const factory = services.agentRunService;
         describe(`AgentRunService [${name}]`, () => {

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

@@ -23,6 +23,7 @@ import type { AIRunStateService } from '../services/ai-run-state-service.js';
 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';
 export type PikkuWiringTypes = 'http' | 'scheduler' | 'trigger' | 'channel' | 'rpc' | 'queue' | 'mcp' | 'cli' | 'workflow' | 'agent' | 'gateway';
 export interface FunctionServicesMeta {
     optimized: boolean;
@@ -172,6 +173,8 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
     agentRunService?: AgentRunService;
     /** Workflow run service (listing workflow runs) */
     workflowRunService?: WorkflowRunService;
+    /** Credential service for dynamic/managed credentials (OAuth tokens, per-user API keys) */
+    credentialService?: CredentialService;
 }
 /**
  * Represents different forms of wire within Pikku and the outside world.
@@ -200,6 +203,10 @@ 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;
+    /** 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>;
 }>;
 /**
  * A function that can wrap an wire and be called before or after