@pikku/core 0.12.23 → 0.12.25

package/dist/testing/service-tests.js

@@ -517,13 +517,13 @@ export function defineServiceTests(config) {
         const factory = services.secretService;
         const kek = 'test-key-encryption-key-32chars!';
         describe(`SecretService [${name}]`, () => {
-            test('setSecretJSON and getSecretJSON', async () => {
+            test('setSecret and getSecret', async () => {
                 const service = await factory({ key: kek });
-                await service.setSecretJSON('api-key', {
+                await service.setSecret('api-key', {
                     token: 'sk-123',
                     endpoint: 'https://api.example.com',
                 });
-                const result = await service.getSecretJSON('api-key');
+                const result = await service.getSecret('api-key');
                 assert.deepEqual(result, {
                     token: 'sk-123',
                     endpoint: 'https://api.example.com',
@@ -531,9 +531,9 @@ export function defineServiceTests(config) {
             });
             test('getSecret returns raw string', async () => {
                 const service = await factory({ key: kek });
-                await service.setSecretJSON('string-secret', 'plain-value');
+                await service.setSecret('string-secret', 'plain-value');
                 const result = await service.getSecret('string-secret');
-                assert.strictEqual(result, '"plain-value"');
+                assert.strictEqual(result, 'plain-value');
             });
             test('hasSecret returns true/false', async () => {
                 const service = await factory({ key: kek });
@@ -546,16 +546,16 @@ export function defineServiceTests(config) {
                     message: 'Requested secret not found',
                 });
             });
-            test('setSecretJSON upserts existing key', async () => {
+            test('setSecret upserts existing key', async () => {
                 const service = await factory({ key: kek });
-                await service.setSecretJSON('upsert-key', { v: 1 });
-                await service.setSecretJSON('upsert-key', { v: 2 });
-                const result = await service.getSecretJSON('upsert-key');
+                await service.setSecret('upsert-key', { v: 1 });
+                await service.setSecret('upsert-key', { v: 2 });
+                const result = await service.getSecret('upsert-key');
                 assert.deepEqual(result, { v: 2 });
             });
             test('deleteSecret removes the key', async () => {
                 const service = await factory({ key: kek });
-                await service.setSecretJSON('to-delete', 'bye');
+                await service.setSecret('to-delete', 'bye');
                 assert.strictEqual(await service.hasSecret('to-delete'), true);
                 await service.deleteSecret('to-delete');
                 assert.strictEqual(await service.hasSecret('to-delete'), false);
@@ -563,13 +563,13 @@ export function defineServiceTests(config) {
             test('rotateKEK re-wraps all secrets', async () => {
                 const newKEK = 'new-key-encryption-key-rotated!';
                 const oldService = await factory({ key: kek });
-                await oldService.setSecretJSON('rotate-test', { important: 'data' });
+                await oldService.setSecret('rotate-test', { important: 'data' });
                 const rotatedService = await factory({
                     key: newKEK,
                     keyVersion: 2,
                     previousKey: kek,
                 });
-                const before = await rotatedService.getSecretJSON('rotate-test');
+                const before = await rotatedService.getSecret('rotate-test');
                 assert.deepEqual(before, { important: 'data' });
                 assert.ok(rotatedService.rotateKEK);
                 const count = await rotatedService.rotateKEK();
@@ -578,7 +578,7 @@ export function defineServiceTests(config) {
                     key: newKEK,
                     keyVersion: 2,
                 });
-                const after = await newOnlyService.getSecretJSON('rotate-test');
+                const after = await newOnlyService.getSecret('rotate-test');
                 assert.deepEqual(after, { important: 'data' });
             });
             test('rotateKEK throws without previousKey', async () => {

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

@@ -25,8 +25,10 @@ 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 { EmailService } from '../services/email-service.js';
 import type { MetaService } from '../services/meta-service.js';
 import type { SessionStore } from '../services/session-store.js';
+import type { AuditDurability, AuditService } from '../services/audit-service.js';
 export type PikkuWiringTypes = 'http' | 'scheduler' | 'trigger' | 'channel' | 'rpc' | 'queue' | 'mcp' | 'cli' | 'workflow' | 'agent' | 'gateway';
 export interface FunctionServicesMeta {
     optimized: boolean;
@@ -143,6 +145,8 @@ export type CoreConfig<Config extends Record<string, unknown> = {}> = {
  * Represents a core user session, which can be extended for more specific session information.
  */
 export interface CoreUserSession {
+    userId?: string;
+    orgId?: string;
 }
 /**
  * Interface for core singleton services provided by Pikku.
@@ -184,8 +188,12 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
     workflowRunService?: WorkflowRunService;
     /** Credential service for dynamic/managed credentials (OAuth tokens, per-user API keys) */
     credentialService?: CredentialService;
+    /** Email service for outbound messages and template-backed delivery */
+    emailService?: EmailService;
     /** Meta service for reading .pikku metadata files (filesystem on Node, R2/KV on CF) */
     metaService?: MetaService;
+    /** Audit service for durable or staged audit event capture */
+    audit?: AuditService;
     /** Session store for persisting user sessions keyed by pikkuUserId */
     sessionStore?: SessionStore;
 }
@@ -197,6 +205,8 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     wireId: string;
     /** Trace ID for distributed tracing — propagated across remote RPC calls via x-trace-id header */
     traceId: string;
+    /** Function id for the current invocation */
+    functionId: string;
     http: PikkuHTTP<In>;
     mcp: PikkuMCP<MCPTools>;
     rpc: TypedRPC;
@@ -211,7 +221,7 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     gateway: PikkuGateway;
     session: HasInitialSession extends true ? UserSession : UserSession | undefined;
     /** Update and persist the current session */
-    setSession: (session: CoreUserSession) => Promise<void> | void;
+    setSession: (session: UserSession) => Promise<void> | void;
     /** Clear and persist the current session */
     clearSession: () => Promise<void> | void;
     /** Fetch the latest session (may read from backing store) */
@@ -226,6 +236,10 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     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>>;
+    /** Resolved function audit metadata for this invocation, if enabled */
+    audit: {
+        durability: AuditDurability;
+    };
 }>;
 /**
  * A function that can wrap an wire and be called before or after

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

@@ -5,6 +5,8 @@ import { PikkuError } from '../../errors/error-handler.js';
 import type { SessionService } from '../../services/user-session-service.js';
 export type RunAIAgentParams = {
     sessionService?: SessionService<CoreUserSession>;
+    /** Credential accessor for the current request — used to read per-user overrides (e.g. AI_API_KEY). */
+    getCredential?: <T = unknown>(name: string) => T | null | Promise<T | null>;
 };
 export type StreamAIAgentOptions = {
     requiresToolApproval?: 'all' | 'explicit' | false;

package/dist/wirings/ai-agent/ai-agent-prepare.js

@@ -3,7 +3,7 @@ import { checkAuthPermissions } from '../../permissions.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js';
-import { randomUUID } from 'crypto';
+import { randomUUID } from './ai-agent-utils.js';
 import { streamAIAgent } from './ai-agent-stream.js';
 import { runAIAgent } from './ai-agent-runner.js';
 import { resolveNamespace, ContextAwareRPCService, } from '../../wirings/rpc/rpc-runner.js';
@@ -434,10 +434,16 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
 export async function prepareAgentRun(agentName, input, params, agentSessionMap, streamContext) {
     const singletonServices = getSingletonServices();
     const { agent, packageName, resolvedName } = resolveAgent(agentName);
-    const agentRunner = singletonServices.aiAgentRunner;
+    let agentRunner = singletonServices.aiAgentRunner;
     if (!agentRunner) {
         throw new AIProviderNotConfiguredError();
     }
+    if (params.getCredential && agentRunner.withApiKey) {
+        const aiCredential = await params.getCredential('AI_API_KEY');
+        if (aiCredential?.apiKey?.trim()) {
+            agentRunner = agentRunner.withApiKey(aiCredential.apiKey);
+        }
+    }
     const { storage } = resolveMemoryServices(agent, singletonServices);
     const memoryConfig = agent.memory;
     const threadId = input.threadId;
@@ -488,7 +494,10 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
     const trimmedMessages = trimMessages(allMessages);
     const aiMiddlewares = agent.aiMiddleware ?? [];
     const { tools, missingRpcs } = await buildToolDefs(params, agentSessionMap, input.resourceId, resolvedName, packageName, streamContext, aiMiddlewares, agent.agentMode);
-    const instructions = await buildInstructions(resolvedName, packageName);
+    let instructions = await buildInstructions(resolvedName, packageName);
+    if (input.context) {
+        instructions = `${instructions}\n\nCurrent context (use these identifiers directly in tool calls — do not ask the user for them):\n${input.context}`;
+    }
     const resolved = resolveModelConfig(resolvedName, agent);
     // Per-request overrides
     if (input.model) {

package/dist/wirings/ai-agent/ai-agent-runner.js

@@ -4,6 +4,7 @@ import { checkForApprovals, appendStepMessages } from './ai-agent-stream.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
+import { randomUUID } from './ai-agent-utils.js';
 function stripNulls(obj) {
     if (obj === null)
         return undefined;
@@ -19,7 +20,6 @@ function stripNulls(obj) {
     }
     return result;
 }
-import { randomUUID } from 'crypto';
 function extractStructuredAssistantOutput(object) {
     if (!object || typeof object !== 'object') {
         return { text: null, uiSpec: null };

package/dist/wirings/ai-agent/ai-agent-stream.js

@@ -1,7 +1,7 @@
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
+import { randomUUID } from './ai-agent-utils.js';
 import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../channel/channel-middleware-runner.js';
-import { randomUUID } from 'crypto';
 import { resolveMemoryServices, loadContextMessages, trimMessages, getWorkingMemoryMiddleware, } from './ai-agent-memory.js';
 import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, createScopedChannel, ToolApprovalRequired, ToolCredentialRequired, } from './ai-agent-prepare.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';

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

@@ -0,0 +1 @@
+export declare const randomUUID: () => string;

package/dist/wirings/ai-agent/ai-agent-utils.js

@@ -0,0 +1 @@
+export const randomUUID = () => globalThis.crypto.randomUUID();

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

@@ -76,6 +76,10 @@ export interface AIAgentInput {
     attachments?: AIAgentInputAttachment[];
     model?: string;
     temperature?: number;
+    /** Structured context injected into the system instructions for this request.
+     *  Use to provide upfront state (e.g. current org/project/branch/deployment)
+     *  so the agent can call tools without asking the user for identifiers. */
+    context?: string;
 }
 export interface AIAgentOutput {
     runId: string;

package/dist/wirings/oauth2/oauth2-client.js

@@ -98,7 +98,7 @@ export class OAuth2Client {
             throw new Error('OAuth2 token expired and no refresh token available');
         }
         // Load from secrets
-        const token = await this.secrets.getSecretJSON(this.oauth2Config.tokenSecretId);
+        const token = await this.secrets.getSecret(this.oauth2Config.tokenSecretId);
         this.cachedToken = token;
         // Check if loaded token is expired and needs refresh
         if (!this.isTokenValid(token)) {
@@ -167,7 +167,7 @@ export class OAuth2Client {
             tokenType: data.token_type || 'Bearer',
             scope: data.scope,
         };
-        await this.secrets.setSecretJSON(this.oauth2Config.tokenSecretId, token);
+        await this.secrets.setSecret(this.oauth2Config.tokenSecretId, token);
         this.cachedToken = token;
         return token;
     }
@@ -188,7 +188,7 @@ export class OAuth2Client {
             return this.cachedAppCredential;
         }
         this.cachedAppCredential =
-            await this.secrets.getSecretJSON(this.appCredentialSecretId);
+            await this.secrets.getSecret(this.appCredentialSecretId);
         return this.cachedAppCredential;
     }
     // ========================================

package/dist/wirings/rpc/rpc-runner.js

@@ -250,6 +250,7 @@ export class ContextAwareRPCService {
             run: async (agentName, input) => {
                 const result = await runAIAgent(agentName, input, {
                     sessionService: this.options.sessionService,
+                    getCredential: this.wire.getCredential?.bind(this.wire),
                 });
                 return {
                     runId: result.runId,
@@ -265,13 +266,19 @@ export class ContextAwareRPCService {
                 const channel = this.wire.channel;
                 if (!channel)
                     throw new Error('No channel available for streaming');
-                await streamAIAgent(agentName, input, channel, { sessionService: this.options.sessionService }, undefined, options);
+                await streamAIAgent(agentName, input, channel, {
+                    sessionService: this.options.sessionService,
+                    getCredential: this.wire.getCredential?.bind(this.wire),
+                }, undefined, options);
             },
             resume: async (runId, input, options) => {
                 const channel = this.wire.channel;
                 if (!channel)
                     throw new Error('No channel available for streaming');
-                await resumeAIAgent({ runId, ...input }, channel, { sessionService: this.options.sessionService }, options);
+                await resumeAIAgent({ runId, ...input }, channel, {
+                    sessionService: this.options.sessionService,
+                    getCredential: this.wire.getCredential?.bind(this.wire),
+                }, options);
             },
             approve: async (runId, approvals, expectedAgentName) => {
                 const result = await resumeAIAgentSync(runId, approvals, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.23",
+  "version": "0.12.25",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",

package/src/data-classification.ts

@@ -0,0 +1,15 @@
+export type Private<T> = T & { readonly __pii__: 'private' }
+export type Secret<T> = T & { readonly __pii__: 'secret' }
+
+export type Classification = 'public' | 'private' | 'secret'
+export type AnonymizeStrategy = 'fake:email' | 'fake:name' | 'hash' | 'keep' | null
+
+export interface ColumnClassification {
+  classification: Classification
+  anonymize_strategy: AnonymizeStrategy
+}
+
+export type ClassificationManifest = {
+  version: 1
+  tables: Record<string, Record<string, ColumnClassification>>
+}

package/src/function/function-runner.test.ts

@@ -785,6 +785,55 @@ describe('runPikkuFunc - Integration Tests', () => {
     assert.deepEqual(receivedSession, { userId: 'user-1', loaded: true })
   })
 
+  test('should expose middleware-set session to createWireServices credential lookups', async () => {
+    let credentialLookups = 0
+    let receivedCredential: any
+    const sessionService = new PikkuSessionService<any>()
+
+    addTestFunction('credentialWire', {
+      middleware: [
+        async (_services: any, wire: any, next: any) => {
+          wire.setSession({ userId: 'user-1' })
+          await next()
+        },
+      ],
+      func: async (_services: any, _data: any, wire: any) => {
+        return wire.getSession()
+      },
+    })
+
+    await runPikkuFunc('rpc', Math.random().toString(), 'credentialWire', {
+      singletonServices: {
+        ...mockSingletonServices,
+        credentialService: {
+          getAll: async (userId: string) => {
+            credentialLookups++
+            assert.equal(userId, 'user-1')
+            return {
+              'user-oauth': { accessToken: 'token-1' },
+            }
+          },
+        },
+      } as any,
+      createWireServices: async (_services: any, wire: any) => {
+        receivedCredential = await wire.getCredential('user-oauth')
+        return {}
+      },
+      data: () => ({}),
+      auth: false,
+      wire: {
+        session: undefined,
+        setSession: (session: any) => sessionService.setInitial(session),
+        getSession: () => sessionService.get(),
+        hasSessionChanged: () => sessionService.sessionChanged,
+      } as any,
+      sessionService,
+    })
+
+    assert.equal(credentialLookups, 1)
+    assert.deepEqual(receivedCredential, { accessToken: 'token-1' })
+  })
+
   test('should pass addon-scoped singleton services and wrap bare workflow names', async () => {
     pikkuState(null, 'addons', 'packages').set('stripe', {
       package: '@addon/stripe',
@@ -969,6 +1018,212 @@ describe('runPikkuFunc - Integration Tests', () => {
     assert.equal(result, true)
     assert.ok(receivedWire.rpc)
   })
+
+  test('should expose resolved audit metadata on the wire for audited functions', async () => {
+    let receivedAudit: any
+
+    addTestFunction('auditedWire', {
+      audit: { durability: 'transactional' },
+      func: async (_services: any, _data: any, wire: any) => {
+        receivedAudit = wire.audit
+        return 'ok'
+      },
+    })
+
+    const result = await runPikkuFunc('rpc', 'wire-audit-on', 'auditedWire', {
+      singletonServices: mockSingletonServices,
+      data: () => ({}),
+      auth: false,
+      wire: {},
+    })
+
+    assert.equal(result, 'ok')
+    assert.deepEqual(receivedAudit, { durability: 'transactional' })
+  })
+
+  test('should leave wire audit metadata undefined when audit is disabled', async () => {
+    let receivedWire: any
+
+    addTestFunction('plainWire', {
+      func: async (_services: any, _data: any, wire: any) => {
+        receivedWire = wire
+        return 'ok'
+      },
+    })
+
+    const result = await runPikkuFunc('rpc', 'wire-audit-off', 'plainWire', {
+      singletonServices: mockSingletonServices,
+      data: () => ({}),
+      auth: false,
+      wire: {},
+    })
+
+    assert.equal(result, 'ok')
+    assert.equal(receivedWire.audit, undefined)
+  })
+
+  test('should restore parent audit metadata after nested non-audited calls', async () => {
+    let auditBeforeChild: any
+    let auditAfterChild: any
+
+    addTestFunction('childPlain', {
+      func: async () => 'child-ok',
+    })
+
+    addTestFunction('parentAudited', {
+      audit: true,
+      func: async (_services: any, _data: any, wire: any) => {
+        auditBeforeChild = wire.audit
+        await runPikkuFunc('rpc', 'nested-child-wire', 'childPlain', {
+          singletonServices: mockSingletonServices,
+          data: () => ({}),
+          auth: false,
+          wire,
+        })
+        auditAfterChild = wire.audit
+        return 'parent-ok'
+      },
+    })
+
+    const result = await runPikkuFunc(
+      'rpc',
+      'nested-parent-wire',
+      'parentAudited',
+      {
+        singletonServices: mockSingletonServices,
+        data: () => ({}),
+        auth: false,
+        wire: {},
+      }
+    )
+
+    assert.equal(result, 'parent-ok')
+    assert.deepEqual(auditBeforeChild, { durability: 'best-effort' })
+    assert.deepEqual(auditAfterChild, { durability: 'best-effort' })
+  })
+
+  test('should preserve parent audit metadata across rpc sub-calls to non-audited functions', async () => {
+    let parentAuditBeforeChild: any
+    let parentAuditAfterChild: any
+    let parentFunctionIdBeforeChild: any
+    let parentFunctionIdAfterChild: any
+    let childAudit: any
+    let childFunctionId: any
+
+    addTestFunction('rpcChildPlain', {
+      func: async (_services: any, _data: any, wire: any) => {
+        childAudit = wire.audit
+        childFunctionId = wire.functionId
+        return 'child-ok'
+      },
+    })
+
+    addTestFunction('rpcParentAudited', {
+      audit: true,
+      func: async (_services: any, _data: any, wire: any) => {
+        parentAuditBeforeChild = wire.audit
+        parentFunctionIdBeforeChild = wire.functionId
+        const childResult = await wire.rpc.invoke('rpcChildPlain', {})
+        parentAuditAfterChild = wire.audit
+        parentFunctionIdAfterChild = wire.functionId
+        return childResult
+      },
+    })
+
+    const result = await runPikkuFunc(
+      'rpc',
+      'rpc-parent-wire',
+      'rpcParentAudited',
+      {
+        singletonServices: mockSingletonServices,
+        data: () => ({}),
+        auth: false,
+        wire: {},
+      }
+    )
+
+    assert.equal(result, 'child-ok')
+    assert.deepEqual(parentAuditBeforeChild, { durability: 'best-effort' })
+    assert.deepEqual(parentAuditAfterChild, { durability: 'best-effort' })
+    assert.equal(parentFunctionIdBeforeChild, 'rpcParentAudited')
+    assert.equal(parentFunctionIdAfterChild, 'rpcParentAudited')
+    assert.equal(childAudit, undefined)
+    assert.equal(childFunctionId, 'rpcChildPlain')
+  })
+
+  test('should bind audited rpc sub-calls to the child invocation context', async () => {
+    let parentAuditBeforeChild: any
+    let parentAuditAfterChild: any
+    let parentFunctionIdAfterChild: any
+    let childAudit: any
+    let childFunctionId: any
+
+    addTestFunction('rpcChildAudited', {
+      audit: { durability: 'transactional' },
+      func: async (_services: any, _data: any, wire: any) => {
+        childAudit = wire.audit
+        childFunctionId = wire.functionId
+        return 'child-audited-ok'
+      },
+    })
+
+    addTestFunction('rpcParentAuditedChild', {
+      audit: true,
+      func: async (_services: any, _data: any, wire: any) => {
+        parentAuditBeforeChild = wire.audit
+        const childResult = await wire.rpc.invoke('rpcChildAudited', {})
+        parentAuditAfterChild = wire.audit
+        parentFunctionIdAfterChild = wire.functionId
+        return childResult
+      },
+    })
+
+    const result = await runPikkuFunc(
+      'rpc',
+      'rpc-parent-child-audit-wire',
+      'rpcParentAuditedChild',
+      {
+        singletonServices: mockSingletonServices,
+        data: () => ({}),
+        auth: false,
+        wire: {},
+      }
+    )
+
+    assert.equal(result, 'child-audited-ok')
+    assert.deepEqual(parentAuditBeforeChild, { durability: 'best-effort' })
+    assert.deepEqual(parentAuditAfterChild, { durability: 'best-effort' })
+    assert.equal(parentFunctionIdAfterChild, 'rpcParentAuditedChild')
+    assert.deepEqual(childAudit, { durability: 'transactional' })
+    assert.equal(childFunctionId, 'rpcChildAudited')
+  })
+
+  test('should expose the resolved base function id after version fallback', async () => {
+    let receivedFunctionId: any
+
+    addTestFunction('versionedBase', {
+      audit: true,
+      func: async (_services: any, _data: any, wire: any) => {
+        receivedFunctionId = wire.functionId
+        return 'ok'
+      },
+    })
+
+    const result = await runPikkuFunc(
+      'rpc',
+      'wire-version-fallback',
+      'versionedBase@v2',
+      {
+        singletonServices: mockSingletonServices,
+        data: () => ({}),
+        auth: false,
+        wire: {},
+      }
+    )
+
+    assert.equal(result, 'ok')
+    assert.equal(receivedFunctionId, 'versionedBase')
+  })
 })
 
 describe('function-runner helpers', () => {