@pikku/core 0.12.22 → 0.12.24

package/src/services/index.ts

@@ -17,6 +17,7 @@ export {
 } from './credential-wire-service.js'
 export { TypedVariablesService } from './typed-variables-service.js'
 export { LocalSecretService } from './local-secrets.js'
+export { LocalEmailService } from './local-email-service.js'
 export { LocalCredentialService } from './local-credential-service.js'
 export { LocalVariablesService } from './local-variables.js'
 export { ConsoleLogger, JsonConsoleLogger } from './logger-console.js'
@@ -36,6 +37,15 @@ export type {
   CopyFileArgs,
 } from './content-service.js'
 export type { JWTService } from './jwt-service.js'
+export type {
+  EmailService,
+  EmailTemplateReference,
+  SendEmailInput,
+  SendEmailResult,
+  SendHTMLEmailInput,
+  SendTemplateEmailInput,
+  SendTextEmailInput,
+} from './email-service.js'
 export type { Logger } from './logger.js'
 export type { SecretService } from './secret-service.js'
 export type { VariablesService } from './variables-service.js'
@@ -78,6 +88,25 @@ export type {
 export type { VariableStatus, VariableMeta } from './typed-variables-service.js'
 export type { MetaService } from './meta-service.js'
 export type { SessionStore } from './session-store.js'
+export {
+  NoopAuditService,
+  createInvocationAudit,
+  resolveAuditActorFromWire,
+  resolveAuditConfig,
+} from './audit-service.js'
+export type {
+  AuditActor,
+  AuditConfig,
+  AuditDurability,
+  AuditEvent,
+  AuditEventBatch,
+  AuditLog,
+  AuditLogWriteInput,
+  AuditOutcome,
+  AuditService,
+  AuditSource,
+  ResolvedAuditConfig,
+} from './audit-service.js'
 export { InMemorySessionStore } from './in-memory-session-store.js'
 export type {
   MCPMeta,
@@ -96,4 +125,8 @@ export type {
   PermissionMeta,
   AgentsMeta,
   AgentMeta,
+  EmailsMeta,
+  EmailTemplateMeta,
+  EmailTemplateLocaleMeta,
+  EmailTemplateAssets,
 } from './meta-service.js'

package/src/services/local-content.ts

@@ -106,6 +106,7 @@ export class LocalContent implements ContentService {
   }
 
   public async getUploadURL(args: GetUploadURLArgs): Promise<UploadURLResult> {
+    void args.visibility
     const fullKey = this.joinKey(args.bucket, args.fileKey)
     this.logger.debug(`Going to upload with key: ${fullKey}`)
     return {

package/src/services/local-email-service.test.ts

@@ -0,0 +1,108 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+
+import { LocalEmailService } from './local-email-service.js'
+
+test('LocalEmailService logs sent email metadata as JSON', async () => {
+  const service = new LocalEmailService()
+  const writes: string[] = []
+  const originalInfo = console.info
+  console.info = (value?: unknown) => {
+    writes.push(String(value))
+  }
+
+  try {
+    await service.send({
+      to: 'user@example.com',
+      from: 'hello@example.com',
+      subject: 'Welcome',
+      template: {
+        name: 'welcome',
+        locale: 'en',
+        data: { userName: 'Yasser' },
+      },
+    })
+  } finally {
+    console.info = originalInfo
+  }
+
+  assert.equal(writes.length, 1)
+  const payload = JSON.parse(writes[0])
+  assert.equal(payload.type, 'email')
+  assert.equal(payload.message, 'this email was sent')
+  assert.equal(payload.to, 'user@example.com')
+  assert.equal(payload.from, 'hello@example.com')
+  assert.equal(payload.subject, 'Welcome')
+  assert.deepEqual(payload.template, {
+    name: 'welcome',
+    locale: 'en',
+    data: { userName: 'Yasser' },
+  })
+})
+
+test('LocalEmailService logs htmlLength and textLength for HTML email', async () => {
+  const service = new LocalEmailService()
+  const writes: string[] = []
+  const originalInfo = console.info
+  console.info = (value?: unknown) => {
+    writes.push(String(value))
+  }
+
+  try {
+    await service.send({
+      to: 'user@example.com',
+      html: '<p>Hello</p>',
+      text: 'Hello',
+    })
+  } finally {
+    console.info = originalInfo
+  }
+
+  const payload = JSON.parse(writes[0])
+  assert.equal(payload.htmlLength, '<p>Hello</p>'.length)
+  assert.equal(payload.textLength, 'Hello'.length)
+})
+
+test('LocalEmailService logs textLength only for plain text email', async () => {
+  const service = new LocalEmailService()
+  const writes: string[] = []
+  const originalInfo = console.info
+  console.info = (value?: unknown) => {
+    writes.push(String(value))
+  }
+
+  try {
+    await service.send({
+      to: 'user@example.com',
+      text: 'Plain text body',
+    })
+  } finally {
+    console.info = originalInfo
+  }
+
+  const payload = JSON.parse(writes[0])
+  assert.equal(payload.textLength, 'Plain text body'.length)
+  assert.equal(payload.htmlLength, undefined)
+})
+
+test('LocalEmailService logs null textLength for HTML email without plain text', async () => {
+  const service = new LocalEmailService()
+  const writes: string[] = []
+  const originalInfo = console.info
+  console.info = (value?: unknown) => {
+    writes.push(String(value))
+  }
+
+  try {
+    await service.send({
+      to: 'user@example.com',
+      html: '<p>Hello</p>',
+    })
+  } finally {
+    console.info = originalInfo
+  }
+
+  const payload = JSON.parse(writes[0])
+  assert.equal(payload.htmlLength, '<p>Hello</p>'.length)
+  assert.equal(payload.textLength, null)
+})

package/src/services/local-email-service.ts

@@ -0,0 +1,30 @@
+import type { EmailService, SendEmailInput, SendEmailResult } from './email-service.js'
+
+export class LocalEmailService implements EmailService {
+  async send(input: SendEmailInput): Promise<SendEmailResult> {
+    const payload: Record<string, unknown> = {
+      type: 'email',
+      message: 'this email was sent',
+      to: input.to,
+      from: input.from ?? null,
+      cc: input.cc ?? null,
+      bcc: input.bcc ?? null,
+      replyTo: input.replyTo ?? null,
+      subject: input.subject ?? null,
+    }
+
+    if ('template' in input && input.template) {
+      payload.template = input.template
+    }
+    if ('html' in input && typeof input.html === 'string') {
+      payload.htmlLength = input.html.length
+      payload.textLength = input.text?.length ?? null
+    }
+    if ('text' in input && typeof input.text === 'string') {
+      payload.textLength = input.text.length
+    }
+
+    console.info(JSON.stringify(payload))
+    return {}
+  }
+}

package/src/services/local-secrets.ts

@@ -9,6 +9,15 @@ import type { VariablesService } from './variables-service.js'
 export class LocalSecretService implements SecretService {
   private localSecrets: Map<string, string> = new Map()
 
+  // TODO: Drop this fallback once secrets and variables expose aligned typed/raw access paths again.
+  private parseSecret<R>(raw: string): R {
+    try {
+      return JSON.parse(raw) as R
+    } catch {
+      return raw as unknown as R
+    }
+  }
+
   /**
    * Creates an instance of LocalSecretService.
    */
@@ -27,13 +36,13 @@ export class LocalSecretService implements SecretService {
     // Check local storage first
     const localValue = this.localSecrets.get(key)
     if (localValue) {
-      return JSON.parse(localValue)
+      return this.parseSecret(localValue)
     }
 
     // Fall back to environment variables
     const value = await this.variables.get(key)
     if (value) {
-      return JSON.parse(value)
+      return this.parseSecret(value)
     }
     throw new Error('Requested secret not found')
   }

package/src/services/meta-service.ts

@@ -109,6 +109,38 @@ export interface PermissionsGroupsMeta {
   tagGroups: Record<string, GroupMeta>
 }
 
+export interface EmailTemplateLocaleMeta {
+  contentHash: string
+  htmlHash: string
+  subjectHash: string
+  textHash: string
+}
+
+export interface EmailTemplateMeta {
+  variables: string[]
+  hasHtml: boolean
+  hasSubject: boolean
+  hasText: boolean
+  locales: Record<string, EmailTemplateLocaleMeta>
+}
+
+export interface EmailsMeta {
+  src: string
+  themeHash: string
+  templates: Record<string, EmailTemplateMeta>
+}
+
+export interface EmailTemplateAssets {
+  theme: Record<string, unknown>
+  strings: Record<string, unknown>
+  layout: string
+  partials: Record<string, string>
+  html: string
+  subject: string
+  text: string
+  missing: string[]
+}
+
 /**
  * Abstraction over .pikku metadata file access.
  * All paths are relative to the .pikku root directory.
@@ -123,6 +155,8 @@ export interface MetaService {
   readFile(relativePath: string): Promise<string | null>
   /** List files in a directory by relative path. Returns empty array if not found. */
   readDir(relativePath: string): Promise<string[]>
+  /** Read a project source file relative to the project root (one level above .pikku). */
+  readProjectFile(relativePath: string): Promise<string | null>
 
   // -- Typed metadata accessors --
 
@@ -143,6 +177,11 @@ export interface MetaService {
   getSecretsMeta(): Promise<SecretDefinitionsMeta>
   getCredentialsMeta(): Promise<CredentialDefinitionsMeta>
   getVariablesMeta(): Promise<VariableDefinitionsMeta>
+  getEmailMeta(): Promise<EmailsMeta>
+  getEmailTemplateAssets(
+    templateName: string,
+    locale: string
+  ): Promise<EmailTemplateAssets>
   getServicesMeta(): Promise<ServicesMetaRecord>
 
   getSchema(schemaName: string): Promise<JSONSchema7 | null>
@@ -173,6 +212,7 @@ export class LocalMetaService implements MetaService {
   private secretsMetaCache: SecretDefinitionsMeta | null = null
   private credentialsMetaCache: CredentialDefinitionsMeta | null = null
   private variablesMetaCache: VariableDefinitionsMeta | null = null
+  private emailMetaCache: EmailsMeta | null = null
   private middlewareGroupsMetaCache: MiddlewareGroupsMeta | null = null
   private permissionsGroupsMetaCache: PermissionsGroupsMeta | null = null
   private agentsMetaCache: AgentsMeta | null = null
@@ -198,6 +238,14 @@ export class LocalMetaService implements MetaService {
     }
   }
 
+  async readProjectFile(relativePath: string): Promise<string | null> {
+    try {
+      return await readFile(join(this.basePath, '..', relativePath), 'utf-8')
+    } catch {
+      return null
+    }
+  }
+
   clearCache(): void {
     this.httpMetaCache = null
     this.channelsMetaCache = null
@@ -214,6 +262,7 @@ export class LocalMetaService implements MetaService {
     this.secretsMetaCache = null
     this.credentialsMetaCache = null
     this.variablesMetaCache = null
+    this.emailMetaCache = null
     this.middlewareGroupsMetaCache = null
     this.permissionsGroupsMetaCache = null
     this.agentsMetaCache = null
@@ -459,6 +508,72 @@ export class LocalMetaService implements MetaService {
     return this.variablesMetaCache!
   }
 
+  async getEmailMeta(): Promise<EmailsMeta> {
+    if (this.emailMetaCache) return this.emailMetaCache
+
+    const content = await this.readFile('email/pikku-emails-meta.gen.json')
+    this.emailMetaCache = content
+      ? JSON.parse(content)
+      : {
+          src: '',
+          themeHash: '',
+          templates: {},
+        }
+    return this.emailMetaCache!
+  }
+
+  async getEmailTemplateAssets(
+    templateName: string,
+    locale: string
+  ): Promise<EmailTemplateAssets> {
+    const emailsMeta = await this.getEmailMeta()
+    if (!emailsMeta.src) {
+      throw new Error(
+        'No generated email metadata found. Run `pikku emails generate`.'
+      )
+    }
+
+    const baseDir = emailsMeta.src
+    const [
+      themeRaw,
+      localeRaw,
+      layoutRaw,
+      footerRaw,
+      templateHtml,
+      templateSubject,
+      templateText,
+    ] = await Promise.all([
+      this.readProjectFile(`${baseDir}/theme.json`),
+      this.readProjectFile(`${baseDir}/locales/${locale}.json`),
+      this.readProjectFile(`${baseDir}/partials/layout.html`),
+      this.readProjectFile(`${baseDir}/partials/footer.html`),
+      this.readProjectFile(`${baseDir}/templates/${templateName}.html`),
+      this.readProjectFile(`${baseDir}/templates/${templateName}.subject.txt`),
+      this.readProjectFile(`${baseDir}/templates/${templateName}.text.txt`),
+    ])
+
+    return {
+      theme: themeRaw ? (JSON.parse(themeRaw) as Record<string, unknown>) : {},
+      strings: localeRaw
+        ? (JSON.parse(localeRaw) as Record<string, unknown>)
+        : {},
+      layout: layoutRaw ?? '',
+      partials: {
+        footer: footerRaw ?? '',
+      },
+      html: templateHtml ?? '',
+      subject: templateSubject ?? '',
+      text: templateText ?? '',
+      missing: [
+        ...(themeRaw ? [] : ['theme']),
+        ...(localeRaw ? [] : ['locale']),
+        ...(templateHtml ? [] : ['html']),
+        ...(templateSubject ? [] : ['subject']),
+        ...(templateText ? [] : ['text']),
+      ],
+    }
+  }
+
   async getServicesMeta(): Promise<ServicesMetaRecord> {
     if (this.servicesMetaCache) return this.servicesMetaCache
 

package/src/types/core.types.ts

@@ -35,8 +35,13 @@ 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'
@@ -196,7 +201,10 @@ 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 {}
+export interface CoreUserSession {
+  userId?: string
+  orgId?: string
+}
 
 /**
  * Interface for core singleton services provided by Pikku.
@@ -239,8 +247,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
 }
@@ -263,6 +275,8 @@ export type PikkuWire<
   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
@@ -281,7 +295,7 @@ export type PikkuWire<
     ? 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) */
@@ -298,6 +312,10 @@ export type PikkuWire<
   getCredentials: () =>
     | Record<string, unknown>
     | Promise<Record<string, unknown>>
+  /** Resolved function audit metadata for this invocation, if enabled */
+  audit: {
+    durability: AuditDurability
+  }
 }>
 
 /**

package/src/wirings/ai-agent/ai-agent-prepare.ts

@@ -16,7 +16,7 @@ import { AIProviderNotConfiguredError } from '../../errors/errors.js'
 import { pikkuState, getSingletonServices } from '../../pikku-state.js'
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js'
 import type { SessionService } 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 {
@@ -32,6 +32,8 @@ import { resolveModelConfig } from './ai-agent-model-config.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 = {
@@ -616,11 +618,18 @@ export async function prepareAgentRun(
   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<{ apiKey: string }>('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

package/src/wirings/ai-agent/ai-agent-runner.test.ts

@@ -970,3 +970,108 @@ describe('resumeAIAgentSync', () => {
     assert.equal(result.text, 'Recovered')
   })
 })
+
+describe('getCredential API key override', () => {
+  test('uses withApiKey runner when getCredential returns apiKey', async () => {
+    addTestAgent('api-key-agent')
+
+    const originalRunCalls: string[] = []
+    const overrideRunCalls: string[] = []
+
+    const overrideRunner = {
+      run: async (): Promise<AIAgentStepResult> => {
+        overrideRunCalls.push('override')
+        return makeStepResult({ text: 'from-override', finishReason: 'stop' })
+      },
+    }
+
+    const mockServices = {
+      logger: { info: () => {}, warn: () => {}, error: () => {}, debug: () => {} },
+      aiAgentRunner: {
+        run: async (): Promise<AIAgentStepResult> => {
+          originalRunCalls.push('original')
+          return makeStepResult({ text: 'from-original', finishReason: 'stop' })
+        },
+        withApiKey: (_key: string) => overrideRunner,
+      },
+      aiRunState: {
+        createRun: async () => 'run-key-override',
+        updateRun: async () => {},
+      },
+    } as any
+
+    pikkuState(null, 'package', 'singletonServices', mockServices)
+
+    const result = await runAIAgent(
+      'api-key-agent',
+      { message: 'hi', threadId: 't-key', resourceId: 'r-key' },
+      { getCredential: async () => ({ apiKey: 'my-secret-key' }) }
+    )
+
+    assert.equal(result.text, 'from-override')
+    assert.equal(overrideRunCalls.length, 1)
+    assert.equal(originalRunCalls.length, 0)
+  })
+
+  test('uses original runner when getCredential returns null', async () => {
+    addTestAgent('no-cred-agent')
+
+    const originalRunCalls: string[] = []
+
+    const mockServices = {
+      logger: { info: () => {}, warn: () => {}, error: () => {}, debug: () => {} },
+      aiAgentRunner: {
+        run: async (): Promise<AIAgentStepResult> => {
+          originalRunCalls.push('original')
+          return makeStepResult({ text: 'from-original', finishReason: 'stop' })
+        },
+        withApiKey: (_key: string) => ({ run: async () => makeStepResult({ text: 'should-not-be-called', finishReason: 'stop' }) }),
+      },
+      aiRunState: {
+        createRun: async () => 'run-no-cred',
+        updateRun: async () => {},
+      },
+    } as any
+
+    pikkuState(null, 'package', 'singletonServices', mockServices)
+
+    const result = await runAIAgent(
+      'no-cred-agent',
+      { message: 'hi', threadId: 't-no-cred', resourceId: 'r-no-cred' },
+      { getCredential: async () => null }
+    )
+
+    assert.equal(result.text, 'from-original')
+    assert.equal(originalRunCalls.length, 1)
+  })
+
+  test('uses original runner when runner does not implement withApiKey', async () => {
+    addTestAgent('no-withkey-agent')
+
+    const originalRunCalls: string[] = []
+
+    const mockServices = {
+      logger: { info: () => {}, warn: () => {}, error: () => {}, debug: () => {} },
+      aiAgentRunner: {
+        run: async (): Promise<AIAgentStepResult> => {
+          originalRunCalls.push('original')
+          return makeStepResult({ text: 'from-original', finishReason: 'stop' })
+        },
+      },
+      aiRunState: {
+        createRun: async () => 'run-no-withkey',
+        updateRun: async () => {},
+      },
+    } as any
+
+    pikkuState(null, 'package', 'singletonServices', mockServices)
+
+    await runAIAgent(
+      'no-withkey-agent',
+      { message: 'hi', threadId: 't-no-withkey', resourceId: 'r-no-withkey' },
+      { getCredential: async () => ({ apiKey: 'ignored-key' }) }
+    )
+
+    assert.equal(originalRunCalls.length, 1)
+  })
+})

package/src/wirings/ai-agent/ai-agent-runner.ts

@@ -33,6 +33,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: unknown): unknown {
   if (obj === null) return undefined
@@ -46,7 +47,6 @@ function stripNulls(obj: unknown): unknown {
   }
   return result
 }
-import { randomUUID } from 'crypto'
 
 function extractStructuredAssistantOutput(object: unknown): {
   text: string | null
@@ -84,6 +84,8 @@ export async function runAIAgent(
     workingMemorySchemaName,
   } = await prepareAgentRun(agentName, input, params, sessionMap)
 
+  runnerParams.agentId = agentName
+
   const singletonServices = getSingletonServices()
   const { aiRunState } = singletonServices
   if (!aiRunState) {
@@ -597,6 +599,7 @@ async function continueAfterToolResultSync(
     outputSchema: meta?.outputSchema
       ? pikkuState(packageName, 'misc', 'schemas').get(meta.outputSchema)
       : undefined,
+    agentId: run.agentName,
   }
 
   try {

package/src/wirings/ai-agent/ai-agent-stream.ts

@@ -11,11 +11,11 @@ import type {
 } from './ai-agent.types.js'
 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 type { AIStorageService } from '../../services/ai-storage-service.js'
 import type {
   AIAgentRunnerParams,
@@ -595,6 +595,8 @@ export async function streamAIAgent(
     streamContext
   )
 
+  runnerParams.agentId = agentName
+
   const singletonServices = getSingletonServices()
   const { aiRunState } = singletonServices
   if (!aiRunState) {

package/src/wirings/ai-agent/ai-agent-utils.ts

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