@pikku/core 0.12.23 → 0.12.25

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/services/scoped-secret-service.test.ts

@@ -3,10 +3,9 @@ import assert from 'node:assert'
 import { ScopedSecretService } from './scoped-secret-service.js'
 
 const createMockSecrets = () => ({
-  getSecret: async (key: string) => `value-of-${key}`,
-  getSecretJSON: async (key: string) => ({ key }),
+  getSecret: async <T>(key: string) => ({ key }) as T,
   hasSecret: async () => true,
-  setSecretJSON: async () => {},
+  setSecret: async () => {},
   deleteSecret: async () => {},
 })
 
@@ -15,7 +14,7 @@ describe('ScopedSecretService', () => {
     const mock = createMockSecrets()
     const scoped = new ScopedSecretService(mock, new Set(['KEY1', 'KEY2']))
     const result = await scoped.getSecret('KEY1')
-    assert.strictEqual(result, 'value-of-KEY1')
+    assert.deepStrictEqual(result, { key: 'KEY1' })
   })
 
   test('should deny access to non-allowed keys', async () => {
@@ -26,17 +25,17 @@ describe('ScopedSecretService', () => {
     })
   })
 
-  test('should allow getSecretJSON for allowed keys', async () => {
+  test('should allow getSecret for allowed keys', async () => {
     const mock = createMockSecrets()
     const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
-    const result = await scoped.getSecretJSON('KEY1')
+    const result = await scoped.getSecret('KEY1')
     assert.deepStrictEqual(result, { key: 'KEY1' })
   })
 
-  test('should deny getSecretJSON for non-allowed keys', async () => {
+  test('should deny getSecret for non-allowed keys', async () => {
     const mock = createMockSecrets()
     const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
-    await assert.rejects(() => scoped.getSecretJSON('FORBIDDEN'), {
+    await assert.rejects(() => scoped.getSecret('FORBIDDEN'), {
       message: 'Access denied to secret key: FORBIDDEN',
     })
   })
@@ -56,11 +55,11 @@ describe('ScopedSecretService', () => {
     })
   })
 
-  test('should always throw on setSecretJSON', async () => {
+  test('should always throw on setSecret', async () => {
     const mock = createMockSecrets()
     const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
-    await assert.rejects(() => scoped.setSecretJSON('KEY1', 'val'), {
-      message: 'setSecretJSON is not allowed in scoped secret service',
+    await assert.rejects(() => scoped.setSecret('KEY1', 'val'), {
+      message: 'setSecret is not allowed in scoped secret service',
     })
   })
 

package/src/services/scoped-secret-service.ts

@@ -16,14 +16,9 @@ export class ScopedSecretService implements SecretService {
     }
   }
 
-  async getSecret(key: string): Promise<string> {
+  async getSecret<T = string>(key: string): Promise<T> {
     this.assertAllowed(key)
-    return this.secrets.getSecret(key)
-  }
-
-  async getSecretJSON<T = {}>(key: string): Promise<T> {
-    this.assertAllowed(key)
-    return this.secrets.getSecretJSON<T>(key)
+    return this.secrets.getSecret<T>(key)
   }
 
   async hasSecret(key: string): Promise<boolean> {
@@ -31,8 +26,8 @@ export class ScopedSecretService implements SecretService {
     return this.secrets.hasSecret(key)
   }
 
-  async setSecretJSON(_key: string, _value: unknown): Promise<void> {
-    throw new Error('setSecretJSON is not allowed in scoped secret service')
+  async setSecret(_key: string, _value: unknown): Promise<void> {
+    throw new Error('setSecret is not allowed in scoped secret service')
   }
 
   async deleteSecret(_key: string): Promise<void> {

package/src/services/secret-service.ts

@@ -3,19 +3,12 @@
  */
 export interface SecretService {
   /**
-   * Retrieves a secret by key and parses it as JSON.
-   * @param key - The key of the secret to retrieve.
-   * @returns A promise that resolves to the parsed secret value.
-   * @throws If the secret is not found.
-   */
-  getSecretJSON<Return = {}>(key: string): Promise<Return>
-  /**
-   * Retrieves a secret by key as a string.
+   * Retrieves a secret by key, typed as T (defaults to string).
    * @param key - The key of the secret to retrieve.
    * @returns A promise that resolves to the secret value.
    * @throws If the secret is not found.
    */
-  getSecret(key: string): Promise<string>
+  getSecret<T = string>(key: string): Promise<T>
   /**
    * Checks if a secret exists without throwing.
    * @param key - The key of the secret to check.
@@ -23,12 +16,12 @@ export interface SecretService {
    */
   hasSecret(key: string): Promise<boolean>
   /**
-   * Stores a JSON value as a secret.
+   * Stores a secret value.
    * @param key - The key to store the secret under.
-   * @param value - The JSON value to store.
+   * @param value - The value to store.
    * @returns A promise that resolves when the secret is stored.
    */
-  setSecretJSON(key: string, value: unknown): Promise<void>
+  setSecret(key: string, value: unknown): Promise<void>
   /**
    * Deletes a secret by key.
    * @param key - The key of the secret to delete.

package/src/services/typed-secret-service.test.ts

@@ -3,18 +3,17 @@ import assert from 'node:assert'
 import { TypedSecretService } from './typed-secret-service.js'
 
 const createMockSecrets = (store: Map<string, string> = new Map()) => ({
-  getSecret: async (key: string) => {
+  getSecret: async <T = string>(key: string): Promise<T> => {
     const val = store.get(key)
     if (!val) throw new Error(`Not found: ${key}`)
-    return val
-  },
-  getSecretJSON: async (key: string) => {
-    const val = store.get(key)
-    if (!val) throw new Error(`Not found: ${key}`)
-    return JSON.parse(val)
+    try {
+      return JSON.parse(val) as T
+    } catch {
+      return val as unknown as T
+    }
   },
   hasSecret: async (key: string) => store.has(key),
-  setSecretJSON: async (key: string, value: unknown) => {
+  setSecret: async (key: string, value: unknown) => {
     store.set(key, JSON.stringify(value))
   },
   deleteSecret: async (key: string) => {
@@ -24,42 +23,42 @@ const createMockSecrets = (store: Map<string, string> = new Map()) => ({
 
 describe('TypedSecretService', () => {
   test('should delegate getSecret to underlying service', async () => {
-    const store = new Map([['API_KEY', 'sk-123']])
+    const store = new Map([['API_KEY', '"sk-123"']])
     const service = new TypedSecretService(createMockSecrets(store), {})
     const result = await service.getSecret('API_KEY')
     assert.strictEqual(result, 'sk-123')
   })
 
-  test('should delegate getSecretJSON to underlying service', async () => {
+  test('should delegate getSecret with type to underlying service', async () => {
     const store = new Map([['CONFIG', '{"port":3000}']])
     const service = new TypedSecretService(createMockSecrets(store), {})
-    const result = await service.getSecretJSON('CONFIG')
+    const result = await service.getSecret<{ port: number }>('CONFIG')
     assert.deepStrictEqual(result, { port: 3000 })
   })
 
   test('should delegate hasSecret to underlying service', async () => {
-    const store = new Map([['EXISTS', 'val']])
+    const store = new Map([['EXISTS', '"val"']])
     const service = new TypedSecretService(createMockSecrets(store), {})
     assert.strictEqual(await service.hasSecret('EXISTS'), true)
     assert.strictEqual(await service.hasSecret('MISSING'), false)
   })
 
-  test('should delegate setSecretJSON to underlying service', async () => {
+  test('should delegate setSecret to underlying service', async () => {
     const store = new Map<string, string>()
     const service = new TypedSecretService(createMockSecrets(store), {})
-    await service.setSecretJSON('NEW_KEY', { data: 'val' })
+    await service.setSecret('NEW_KEY', { data: 'val' })
     assert.strictEqual(store.get('NEW_KEY'), '{"data":"val"}')
   })
 
   test('should delegate deleteSecret to underlying service', async () => {
-    const store = new Map([['KEY', 'val']])
+    const store = new Map([['KEY', '"val"']])
     const service = new TypedSecretService(createMockSecrets(store), {})
     await service.deleteSecret('KEY')
     assert.strictEqual(store.has('KEY'), false)
   })
 
   test('should get all status for credentials', async () => {
-    const store = new Map([['STRIPE_KEY', 'sk-123']])
+    const store = new Map([['STRIPE_KEY', '"sk-123"']])
     const meta = {
       STRIPE_KEY: { name: 'stripe', displayName: 'Stripe' },
       GITHUB_TOKEN: {
@@ -80,7 +79,7 @@ describe('TypedSecretService', () => {
   })
 
   test('should get missing credentials', async () => {
-    const store = new Map([['STRIPE_KEY', 'sk-123']])
+    const store = new Map([['STRIPE_KEY', '"sk-123"']])
     const meta = {
       STRIPE_KEY: { name: 'stripe', displayName: 'Stripe' },
       GITHUB_TOKEN: { name: 'github', displayName: 'GitHub' },

package/src/services/typed-secret-service.ts

@@ -22,13 +22,9 @@ export class TypedSecretService<
     private credentialsMeta: Record<string, CredentialMeta>
   ) {}
 
-  async getSecretJSON<K extends keyof TMap & string>(key: K): Promise<TMap[K]>
-  async getSecretJSON<T = unknown>(key: string): Promise<T>
-  async getSecretJSON(key: string): Promise<unknown> {
-    return this.secrets.getSecretJSON(key)
-  }
-
-  async getSecret(key: string): Promise<string> {
+  async getSecret<K extends keyof TMap & string>(key: K): Promise<TMap[K]>
+  async getSecret<T = string>(key: string): Promise<T>
+  async getSecret(key: string): Promise<unknown> {
     return this.secrets.getSecret(key)
   }
 
@@ -36,11 +32,11 @@ export class TypedSecretService<
     return this.secrets.hasSecret(key)
   }
 
-  async setSecretJSON<K extends string>(
+  async setSecret<K extends string>(
     key: K,
     value: K extends keyof TMap ? TMap[K] : unknown
   ): Promise<void> {
-    return this.secrets.setSecretJSON(key, value)
+    return this.secrets.setSecret(key, value)
   }
 
   async deleteSecret(key: string): Promise<void> {

package/src/services/typed-variables-service.test.ts

@@ -36,15 +36,15 @@ describe('TypedVariablesService', () => {
     assert.strictEqual(service.has('DB_URL'), false)
   })
 
-  test('should delegate getJSON to underlying service', () => {
+  test('should delegate get to underlying service', () => {
     const service = createService({ DATA: '{"key":"val"}' })
-    assert.deepStrictEqual(service.getJSON('DATA'), { key: 'val' })
+    assert.deepStrictEqual(service.get('DATA'), { key: 'val' })
   })
 
-  test('should delegate setJSON to underlying service', () => {
+  test('should delegate set to underlying service', () => {
     const service = createService()
-    service.setJSON('DATA', { key: 'val' })
-    assert.strictEqual(service.get('DATA'), '{"key":"val"}')
+    service.set('DATA', { key: 'val' })
+    assert.deepStrictEqual(service.get('DATA'), { key: 'val' })
   })
 
   test('should get all status for configured variables', async () => {

package/src/services/typed-variables-service.ts

@@ -20,20 +20,12 @@ export class TypedVariablesService<
     private variablesMeta: Record<string, VariableMeta>
   ) {}
 
-  get(
-    name: keyof TMap & string
-  ): Promise<string | undefined> | string | undefined
-  get(name: string): Promise<string | undefined> | string | undefined
-  get(name: string): Promise<string | undefined> | string | undefined {
-    return this.variables.get(name)
-  }
-
-  getJSON<K extends keyof TMap & string>(
+  get<K extends keyof TMap & string>(
     name: K
   ): Promise<TMap[K] | undefined> | TMap[K] | undefined
-  getJSON<T = unknown>(name: string): Promise<T | undefined> | T | undefined
-  getJSON(name: string): Promise<unknown> | unknown {
-    return this.variables.getJSON(name)
+  get<T = string>(name: string): Promise<T | undefined> | T | undefined
+  get(name: string): Promise<unknown> | unknown {
+    return this.variables.get(name)
   }
 
   getAll():
@@ -42,14 +34,10 @@ export class TypedVariablesService<
     return this.variables.getAll()
   }
 
-  set(name: string, value: string): Promise<void> | void {
+  set(name: string, value: unknown): Promise<void> | void {
     return this.variables.set(name, value)
   }
 
-  setJSON(name: string, value: unknown): Promise<void> | void {
-    return this.variables.setJSON(name, value)
-  }
-
   has(name: string): Promise<boolean> | boolean {
     return this.variables.has(name)
   }

package/src/services/variables-service.ts

@@ -1,11 +1,9 @@
 export interface VariablesService {
-  get: (name: string) => Promise<string | undefined> | string | undefined
-  getJSON: <T = unknown>(name: string) => Promise<T | undefined> | T | undefined
+  get<T = string>(name: string): Promise<T | undefined> | T | undefined
   getAll: () =>
     | Promise<Record<string, string | undefined>>
     | Record<string, string | undefined>
-  set: (name: string, value: string) => Promise<void> | void
-  setJSON: (name: string, value: unknown) => Promise<void> | void
+  set: (name: string, value: unknown) => Promise<void> | void
   has: (name: string) => Promise<boolean> | boolean
   delete: (name: string) => Promise<void> | void
 }

package/src/testing/service-tests.ts

@@ -782,13 +782,13 @@ export function defineServiceTests(config: ServiceTestConfig): void {
     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<{
+        const result = await service.getSecret<{
           token: string
           endpoint: string
         }>('api-key')
@@ -800,9 +800,9 @@ export function defineServiceTests(config: ServiceTestConfig): void {
 
       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 () => {
@@ -818,17 +818,17 @@ export function defineServiceTests(config: ServiceTestConfig): void {
         })
       })
 
-      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<{ v: number }>('upsert-key')
+        await service.setSecret('upsert-key', { v: 1 })
+        await service.setSecret('upsert-key', { v: 2 })
+        const result = await service.getSecret<{ v: number }>('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)
@@ -837,7 +837,7 @@ export function defineServiceTests(config: ServiceTestConfig): void {
       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,
@@ -845,7 +845,7 @@ export function defineServiceTests(config: ServiceTestConfig): void {
           previousKey: kek,
         })
 
-        const before = await rotatedService.getSecretJSON<{
+        const before = await rotatedService.getSecret<{
           important: string
         }>('rotate-test')
         assert.deepEqual(before, { important: 'data' })
@@ -858,7 +858,7 @@ export function defineServiceTests(config: ServiceTestConfig): void {
           key: newKEK,
           keyVersion: 2,
         })
-        const after = await newOnlyService.getSecretJSON<{
+        const after = await newOnlyService.getSecret<{
           important: string
         }>('rotate-test')
         assert.deepEqual(after, { important: 'data' })

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
+  }
 }>
 
 /**