@pikku/core 0.12.74 → 0.12.77

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

@@ -171,7 +171,27 @@ export interface PikkuAIMiddlewareHooks<
 > {
   modifyInput?: (
     services: Services,
-    ctx: { messages: AIMessage[]; instructions: string }
+    ctx: {
+      messages: AIMessage[]
+      instructions: string
+      /**
+       * Notes about this run that every middleware can read and write, as
+       * opposed to {@link modifyOutputStream}'s `state`, which is private to
+       * one middleware.
+       *
+       * It exists because middlewares transform the turn for each other, and
+       * the transformation can destroy what a later one needed to know. Voice
+       * is the case in point: `voiceInput` replaces the user's audio with its
+       * transcript, so by the time anything downstream looks, the turn is
+       * indistinguishable from one that was typed — and whether it was typed is
+       * exactly what `voiceOutput` needs in order to decide whether to answer
+       * aloud. Only the middleware that consumed the audio can still say so.
+       *
+       * Namespace what you put here (`voice:spokenTurn`); it is one bag for
+       * everybody. Cleared between runs.
+       */
+      shared: Record<string, unknown>
+    }
   ) =>
     | Promise<{ messages: AIMessage[]; instructions: string }>
     | { messages: AIMessage[]; instructions: string }
@@ -181,7 +201,10 @@ export interface PikkuAIMiddlewareHooks<
     ctx: {
       event: AIStreamEvent
       allEvents: readonly AIStreamEvent[]
+      /** Private to this middleware, for this run. Cross-middleware facts go in `shared`. */
       state: State
+      /** Per-run notes shared with every middleware — see {@link modifyInput}. */
+      shared: Record<string, unknown>
       /**
        * Push an event into the stream *after* this call has returned.
        *
@@ -418,10 +441,31 @@ export type AIStreamEvent =
       type: 'audio-delta'
       data: string
       format: string
+      /**
+       * The sentence this audio says.
+       *
+       * Carried alongside the bytes because a client that gets talked over has
+       * to tell the model what the user actually heard, and playback position
+       * is the only place that is knowable. Without it a barge-in can stop the
+       * sound but not report it, and the next turn is answered as though the
+       * whole reply had landed.
+       */
+      text?: string
       agent?: string
       session?: string
     }
   | { type: 'audio-done'; agent?: string; session?: string }
+  | {
+      /**
+       * What the user was heard to say, sent once at the start of a spoken
+       * turn. Only the server knows this — the client sent audio — and a chat
+       * surface needs it to show the user's own message.
+       */
+      type: 'transcript'
+      text: string
+      agent?: string
+      session?: string
+    }
   | {
       type: 'data'
       name: string

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

@@ -16,6 +16,8 @@ export {
   voiceInput,
   readsAsNonSpeech,
   NoSpeechDetectedError,
+  SPOKEN_TURN,
+  SPOKEN_TRANSCRIPT,
 } from './voice-input.js'
 export {
   voiceOutput,

package/src/wirings/ai-agent/voice-input.test.ts

@@ -5,6 +5,8 @@ import {
   voiceInput,
   readsAsNonSpeech,
   NoSpeechDetectedError,
+  SPOKEN_TURN,
+  SPOKEN_TRANSCRIPT,
 } from './voice-input.js'
 import type { AIContentPart, AIMessage } from './ai-agent.types.js'
 
@@ -39,6 +41,7 @@ describe('voiceInput', () => {
     const result = await mw.modifyInput!(services as any, {
       messages: [audioMessage()],
       instructions: 'sys',
+      shared: {},
     })
 
     const last = result.messages[result.messages.length - 1]!
@@ -67,6 +70,7 @@ describe('voiceInput', () => {
     const result = await mw.modifyInput!(services as any, {
       messages,
       instructions: 'sys',
+      shared: {},
     })
 
     assert.equal(result.messages[0]!.content, 'just text')
@@ -81,6 +85,7 @@ describe('voiceInput', () => {
         mw.modifyInput!(services as any, {
           messages: [audioMessage()],
           instructions: 'sys',
+          shared: {},
         }),
       /voiceInput requires a transcription model/
     )
@@ -105,6 +110,7 @@ describe('voiceInput', () => {
         mw.modifyInput!({ aiAgentRunner: silent } as any, {
           messages: [audioMessage()],
           instructions: 'sys',
+          shared: {},
         }),
       NoSpeechDetectedError
     )
@@ -127,6 +133,7 @@ describe('voiceInput', () => {
     const result = await mw.modifyInput!({ aiAgentRunner: spaced } as any, {
       messages: [audioMessage()],
       instructions: 'sys',
+      shared: {},
     })
 
     const parts = result.messages.at(-1)!.content as AIContentPart[]
@@ -152,4 +159,62 @@ describe('readsAsNonSpeech', () => {
     assert.equal(readsAsNonSpeech({ text: 'yes' }), false)
     assert.equal(readsAsNonSpeech({ text: 'Thank you.' }), false)
   })
+  test('records that the turn was spoken, for voiceOutput to read', async () => {
+    // The note has to be written here: the transcript this middleware puts in
+    // the message's place is indistinguishable from something typed, so no
+    // later middleware can tell what it started as.
+    const mw = voiceInput({ model: 'mock/whisper' })
+    const shared: Record<string, unknown> = {}
+
+    await mw.modifyInput!({ aiAgentRunner: new ThisDependentRunner() } as any, {
+      messages: [audioMessage()],
+      instructions: 'sys',
+      shared,
+    })
+
+    assert.equal(shared[SPOKEN_TURN], true)
+  })
+
+  test('records a typed turn as not spoken, rather than leaving it unsaid', async () => {
+    const mw = voiceInput({ model: 'mock/whisper' })
+    const shared: Record<string, unknown> = {}
+
+    await mw.modifyInput!({ aiAgentRunner: new ThisDependentRunner() } as any, {
+      messages: [{ role: 'user', content: 'typed' } as any],
+      instructions: 'sys',
+      shared,
+    })
+
+    // Explicitly false, not absent: absent is what a caller with no voice input
+    // at all looks like, and that one should still be spoken to.
+    assert.equal(shared[SPOKEN_TURN], false)
+  })
+
+  test('records what was heard, so the client can show the user their own turn', async () => {
+    const mw = voiceInput({ model: 'mock/whisper' })
+    const shared: Record<string, unknown> = {}
+
+    await mw.modifyInput!({ aiAgentRunner: new ThisDependentRunner() } as any, {
+      messages: [audioMessage()],
+      instructions: 'sys',
+      shared,
+    })
+
+    assert.equal(shared[SPOKEN_TRANSCRIPT], 'the transcribed spoken words')
+  })
+
+  test('a typed turn leaves no transcript behind', async () => {
+    // Absence is the signal: the stream only announces a transcript when there
+    // was one, and a typed message is already on the client's screen.
+    const mw = voiceInput({ model: 'mock/whisper' })
+    const shared: Record<string, unknown> = {}
+
+    await mw.modifyInput!({ aiAgentRunner: new ThisDependentRunner() } as any, {
+      messages: [{ role: 'user', content: 'typed' } as any],
+      instructions: 'sys',
+      shared,
+    })
+
+    assert.equal(SPOKEN_TRANSCRIPT in shared, false)
+  })
 })

package/src/wirings/ai-agent/voice-input.ts

@@ -70,13 +70,35 @@ async function fetchAsUint8Array(
   return new Uint8Array(buffer)
 }
 
+/**
+ * Shared-notes key recording whether the user's turn arrived as audio.
+ *
+ * Written here because this is the last point at which it is knowable: the
+ * transcript that replaces the audio is indistinguishable from something typed.
+ * Read by `voiceOutput` to decide whether to answer aloud.
+ *
+ * Absent — rather than `false` — when this middleware is not wired at all, which
+ * is what lets `voiceOutput` still speak for a caller that has no voice input.
+ */
+export const SPOKEN_TURN = 'voice:spokenTurn'
+
+/**
+ * Shared-notes key holding what the user was heard to say, when they spoke.
+ *
+ * Absent on a typed turn. Read by the stream wiring, which forwards it to the
+ * client as a `transcript` event — a voice client has no idea what its own
+ * audio said, and without this the user's turn shows up in the UI as an empty
+ * bubble followed by an answer to a question they cannot see.
+ */
+export const SPOKEN_TRANSCRIPT = 'voice:transcript'
+
 export const voiceInput = (config?: {
   language?: string
   model?: string
   allowedAudioHosts?: string[]
 }) =>
   pikkuAIMiddleware({
-    modifyInput: async (services, { messages, instructions }) => {
+    modifyInput: async (services, { messages, instructions, shared }) => {
       const aiAgentRunner = (
         services as {
           aiAgentRunner?: AIAgentRunnerService
@@ -85,19 +107,22 @@ export const voiceInput = (config?: {
       if (!aiAgentRunner?.transcribe) return { messages, instructions }
 
       const last = messages[messages.length - 1]
-      if (!last || last.role !== 'user' || typeof last.content === 'string') {
-        return { messages, instructions }
-      }
-
-      const parts = last.content as AIContentPart[]
-      if (!parts) return { messages, instructions }
+      const parts =
+        last?.role === 'user' && typeof last.content !== 'string'
+          ? (last.content as AIContentPart[] | undefined)
+          : undefined
 
-      const hasAudio = parts.some(
+      const hasAudio = !!parts?.some(
         (p) => p.type === 'file' && !!p.mediaType?.startsWith('audio/')
       )
-      if (!hasAudio) return { messages, instructions }
+      // Recorded on every turn this middleware sees, spoken or not, so that a
+      // typed turn is an explicit `false` downstream rather than a silence that
+      // could equally mean nobody was asked.
+      shared[SPOKEN_TURN] = hasAudio
+      if (!hasAudio || !parts) return { messages, instructions }
 
       const updatedContent: AIContentPart[] = []
+      const heard: string[] = []
       for (const p of parts) {
         if (!(p.type === 'file' && p.mediaType?.startsWith('audio/'))) {
           updatedContent.push(p)
@@ -111,6 +136,9 @@ export const voiceInput = (config?: {
         const audioData = p.data
           ? base64ToUint8Array(p.data)
           : await fetchAsUint8Array(p.url!, config.allowedAudioHosts)
+        if (audioData.byteLength > MAX_AUDIO_SIZE) {
+          throw new Error('Audio file exceeds maximum size')
+        }
         const result = await aiAgentRunner.transcribe({
           model: config.model,
           audio: audioData,
@@ -128,6 +156,7 @@ export const voiceInput = (config?: {
         // model will answer, and what it answers is a guess about what it could
         // not hear.
         if (readsAsNonSpeech(result)) continue
+        heard.push(result.text)
         updatedContent.push({ type: 'text' as const, text: result.text })
       }
 
@@ -135,6 +164,16 @@ export const voiceInput = (config?: {
       // to send, and a message with no content is not a question.
       if (updatedContent.length === 0) throw new NoSpeechDetectedError()
 
+      // Only when something was actually heard. A turn can carry audio that all
+      // reads as non-speech and still have content — an image with a silent
+      // caption clip — which leaves nothing above to throw. Recording `''` here
+      // would send a transcript event saying the user said nothing, and a client
+      // that tells "not transcribed yet" from "transcribed" by the key being
+      // absent would render the turn as an empty bubble rather than a pending one.
+      if (heard.length > 0) {
+        shared[SPOKEN_TRANSCRIPT] = heard.join(' ')
+      }
+
       return {
         messages: [
           ...messages.slice(0, -1),

package/src/wirings/ai-agent/voice-output.test.ts

@@ -7,6 +7,7 @@ import {
   voiceForText,
 } from './voice-output.js'
 import type { AIStreamEvent } from './ai-agent.types.js'
+import { SPOKEN_TURN } from './voice-input.js'
 
 const KOKORO_SCRIPTS = ['latin', 'devanagari', 'han', 'kana']
 
@@ -33,7 +34,8 @@ const deferred = () => {
  */
 const createStream = (
   mw: ReturnType<typeof voiceOutput>,
-  services: unknown
+  services: unknown,
+  shared: Record<string, unknown> = {}
 ) => {
   const state: Record<string, unknown> = {}
   const allEvents: AIStreamEvent[] = []
@@ -54,6 +56,7 @@ const createStream = (
         event,
         allEvents,
         state,
+        shared,
         emit: next,
       })
       if (result == null) return
@@ -314,6 +317,93 @@ describe('voiceOutput', () => {
     ])
   })
 
+  test('a typed turn is answered in text only', async () => {
+    // The cost case. One agent serves both kinds of caller, so a reply to
+    // something typed must not quietly synthesize speech nobody asked to hear
+    // — it is billed per sentence, on every turn.
+    const asked: string[] = []
+    const services = {
+      aiAgentRunner: {
+        generateSpeech: async ({ text }: { text: string }) => {
+          asked.push(text)
+          return speechFor(text)
+        },
+      },
+    }
+    const stream = createStream(voiceOutput({ model: 'mock/tts' }), services, {
+      [SPOKEN_TURN]: false,
+    })
+
+    await stream.send({ type: 'text-delta', text: 'Added it.' })
+    await stream.send({ type: 'done' })
+
+    assert.deepEqual(asked, [])
+    assert.deepEqual(stream.types(), ['text-delta', 'done'])
+  })
+
+  test('a spoken turn is answered aloud', async () => {
+    const asked: string[] = []
+    const services = {
+      aiAgentRunner: {
+        generateSpeech: async ({ text }: { text: string }) => {
+          asked.push(text)
+          return speechFor(text)
+        },
+      },
+    }
+    const stream = createStream(voiceOutput({ model: 'mock/tts' }), services, {
+      [SPOKEN_TURN]: true,
+    })
+
+    await stream.send({ type: 'text-delta', text: 'Added it.' })
+    await stream.send({ type: 'done' })
+
+    assert.deepEqual(asked, ['Added it.'])
+  })
+
+  test('`always` speaks a typed turn too', async () => {
+    // Read-aloud modes exist, and for them speech is not a reply to speech.
+    const asked: string[] = []
+    const services = {
+      aiAgentRunner: {
+        generateSpeech: async ({ text }: { text: string }) => {
+          asked.push(text)
+          return speechFor(text)
+        },
+      },
+    }
+    const stream = createStream(
+      voiceOutput({ model: 'mock/tts', always: true }),
+      services,
+      { [SPOKEN_TURN]: false }
+    )
+
+    await stream.send({ type: 'text-delta', text: 'Added it.' })
+    await stream.send({ type: 'done' })
+
+    assert.deepEqual(asked, ['Added it.'])
+  })
+
+  test('speaks when nothing reported how the turn arrived', async () => {
+    // voiceOutput without voiceInput: nobody set the note, so there is no
+    // evidence the turn was typed and the pre-existing behaviour stands.
+    const asked: string[] = []
+    const services = {
+      aiAgentRunner: {
+        generateSpeech: async ({ text }: { text: string }) => {
+          asked.push(text)
+          return speechFor(text)
+        },
+      },
+    }
+    const stream = createStream(voiceOutput({ model: 'mock/tts' }), services)
+
+    await stream.send({ type: 'text-delta', text: 'Added it.' })
+    await stream.send({ type: 'done' })
+
+    assert.deepEqual(asked, ['Added it.'])
+  })
+
   test('a script with no voice mapped is still refused, not mis-voiced', async () => {
     const asked: string[] = []
     const services = {

package/src/wirings/ai-agent/voice-output.ts

@@ -1,5 +1,6 @@
 import type { AIAgentRunnerService } from '../../services/ai-agent-runner-service.js'
 import { pikkuAIMiddleware } from '../../types/core.types.js'
+import { SPOKEN_TURN } from './voice-input.js'
 
 type VoiceOutputState = {
   textBuffer?: string
@@ -178,15 +179,40 @@ export const voiceOutput = (config?: {
    * the right default for a provider that genuinely is multilingual.
    */
   speakableScripts?: SpeakableScripts
+  /**
+   * Speak every reply, including answers to turns that were typed.
+   *
+   * The default is to speak only what was spoken to. An agent is usually one
+   * agent serving both kinds of caller — the same thread is typed at from a
+   * desk and talked to from a phone — and synthesizing a reply nobody is
+   * listening to costs real money on every sentence of every turn. Whether the
+   * user is in a call is not something the client needs to declare: sending
+   * audio is what saying so looks like.
+   *
+   * Set this for the cases where speech is not a reply to speech at all — a
+   * read-aloud accessibility mode, a kiosk, anything whose whole output is
+   * meant to be heard.
+   */
+  always?: boolean
 }) =>
   pikkuAIMiddleware<VoiceOutputState>({
-    modifyOutputStream: async (services, { event, state, emit, signal }) => {
+    modifyOutputStream: async (
+      services,
+      { event, state, shared, emit, signal }
+    ) => {
       const { aiAgentRunner, logger } = services as {
         aiAgentRunner?: AIAgentRunnerService
         logger?: { error: (message: string) => void }
       }
       if (!aiAgentRunner?.generateSpeech) return event
 
+      // Only an explicit `false` silences the reply. `voiceInput` sets this on
+      // every turn it handles, so `false` means a real user really typed; the
+      // key being absent means nothing reported either way — no voice input is
+      // wired — and that caller's replies are spoken exactly as they were before
+      // this option existed.
+      if (!config?.always && shared[SPOKEN_TURN] === false) return event
+
       /**
        * Queue a finished sentence for speech.
        *
@@ -261,6 +287,7 @@ export const voiceOutput = (config?: {
             type: 'audio-delta',
             data: bufferToBase64(result.audio.bytes),
             format: result.audio.format,
+            text,
           })
         })
       }

package/src/wirings/cli/channel/cli-raw-client-runner.ts

@@ -7,18 +7,48 @@ import type {
   Capabilities,
 } from '../../channel/channel-rpc.js'
 import { approverForMode, takeApprovalFlags } from './cli-approval.js'
-import type { CorePikkuCLIRender } from '../cli.types.js'
+import type { Logger } from '../../../services/logger.js'
+
+/**
+ * Everything a renderer gets when the command ran on the server: a logger, and
+ * nothing else. There is no container on this side of the socket to resolve a
+ * service from, so this is the whole of it rather than a subset of
+ * `CoreSingletonServices` — which requires `config`, `variables` and `secrets`
+ * the client does not have and cannot invent.
+ */
+export type ClientCLIRenderServices = { logger: Logger }
+
+/**
+ * A renderer that runs on the client of a CLI-over-channel connection.
+ *
+ * Deliberately not `CorePikkuCLIRender`: that type's `Services` parameter is
+ * constrained to `CoreSingletonServices`, so the honest logger-only shape
+ * cannot be spelled through it.
+ */
+export type CorePikkuCLIClientRender<Data> = (
+  services: ClientCLIRenderServices,
+  data: Data,
+  session?: undefined
+) => void | Promise<void>
 
 /** The normal case once the server owns the command tree. */
-const defaultJSONRenderer: CorePikkuCLIRender<any> = (_services, data) => {
+const defaultJSONRenderer: CorePikkuCLIClientRender<any> = (_services, data) => {
   console.log(JSON.stringify(data))
 }
 
-/**
- * The command ran on the server, so there are no services here — but a renderer
- * written for local execution can still reach for `services.logger`.
- */
-const clientServices = { logger: console } as any
+// `console` is the whole logger a CLI wants — its output is the command's output.
+// `setLevel` is a no-op rather than an omission because `Logger` requires it and
+// there is no level to set: a renderer writes what the user asked to see.
+const clientServices: ClientCLIRenderServices = {
+  logger: {
+    info: (...args: any[]) => console.info(...(args as [any])),
+    warn: (...args: any[]) => console.warn(...(args as [any])),
+    error: (...args: any[]) => console.error(...(args as [any])),
+    debug: (...args: any[]) => console.debug(...(args as [any])),
+    trace: (...args: any[]) => console.trace(...(args as [any])),
+    setLevel: () => {},
+  },
+}
 
 /**
  * Runs a CLI command entirely on the server. Unlike `executeCLIViaChannel`,
@@ -40,8 +70,8 @@ export async function executeRawCLIViaChannel({
 }: {
   pikkuWS: any // CorePikkuWebsocket instance
   args?: string[]
-  renderers?: Record<string, CorePikkuCLIRender<any>>
-  defaultRenderer?: CorePikkuCLIRender<any>
+  renderers?: Record<string, CorePikkuCLIClientRender<any>>
+  defaultRenderer?: CorePikkuCLIClientRender<any>
   capabilities?: Capabilities
   approve?: ApprovalRequester
 }): Promise<number> {

package/src/wirings/cli/channel/index.ts

@@ -2,6 +2,10 @@ export { executeCLIViaChannel } from './cli-channel-runner.js'
 export { handleRawCLI } from './cli-raw-channel-runner.js'
 export type { RawCLIFrame, RawCLIResult } from './cli-raw-channel-runner.js'
 export { executeRawCLIViaChannel } from './cli-raw-client-runner.js'
+export type {
+  ClientCLIRenderServices,
+  CorePikkuCLIClientRender,
+} from './cli-raw-client-runner.js'
 export {
   APPROVAL_FLAGS,
   approverForMode,

package/src/wirings/persona/define-personas.ts

@@ -11,6 +11,10 @@ import type { CorePersonas } from './persona.types.js'
  * running: a persona that exists only to be acted upon (the account an admin
  * bans, the colleague a document is shared with) is seeded and never run.
  *
+ * Exactly one `definePersonas(...)` is allowed per codebase, so there is one
+ * place to read the cast from and one place to add to. A second call — even in
+ * the same file — fails the build.
+ *
  * @example
  * ```typescript
  * definePersonas({

package/src/wirings/persona/persona.types.ts

@@ -38,6 +38,16 @@ export type CorePersona = {
   name: string
   jobTitle?: string
   description?: string
+  /**
+   * A picture of this person, as any URL a browser can load: a file your app
+   * serves, an asset on a CDN, a Gravatar link.
+   *
+   * Optional because it is decoration. Omitted, the console draws a colour and
+   * an icon derived from the persona's id, which is stable, needs no network and
+   * is more legible than the identicon a synthetic address would resolve to —
+   * which is also why nothing is derived here.
+   */
+  avatarUrl?: string
   /**
    * The roles this person holds. Only system roles may be named — a custom
    * role can be deleted from the console, so a persona pinned to one silently
@@ -112,6 +122,7 @@ export type PersonaMeta = {
   name: string
   jobTitle?: string
   description?: string
+  avatarUrl?: string
   roles: string[]
   personality?: string
   goals: string[]

package/src/wirings/queue/queue-identity.test.ts

@@ -21,6 +21,7 @@ import type {
   QueueJob,
   QueueService,
 } from './queue.types.js'
+import { createSecretValue } from '../../secret-value.js'
 
 const QUEUE_NAME = 'identity-queue'
 const SECRET = 'a'.repeat(48)
@@ -49,7 +50,7 @@ const createSecretService = (secrets: Record<string, string>) =>
       if (value === undefined) {
         throw new Error(`Secret not found: ${key}`)
       }
-      return value
+      return createSecretValue(value)
     },
     hasSecret: async (key: string) => secrets[key] !== undefined,
     setSecret: async () => {},

package/src/wirings/queue/queue-identity.ts

@@ -59,7 +59,10 @@ export const getQueueIdentitySecret = async (
   secrets?: SecretService
 ): Promise<string | undefined> => {
   try {
-    return (await secrets?.getSecret(QUEUE_IDENTITY_SECRET_NAME)) || undefined
+    return (
+      (await secrets?.getSecret(QUEUE_IDENTITY_SECRET_NAME))?.reveal() ||
+      undefined
+    )
   } catch {
     return undefined
   }

package/src/wirings/queue/queue.types.ts

@@ -1,6 +1,7 @@
 import type { CommonWireMeta } from '../../types/core.types.js'
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
 import type { QueueConfigMapping } from './validate-worker-config.js'
+import type { Safe } from '../../secret-value.js'
 
 export interface PikkuWorkerConfig {
   name?: string
@@ -107,7 +108,11 @@ export interface JobOptions {
 export interface QueueService {
   readonly supportsResults: boolean
 
-  add<T>(queueName: string, data: T, options?: JobOptions): Promise<string>
+  add<T>(
+    queueName: string,
+    data: Safe<T>,
+    options?: JobOptions
+  ): Promise<string>
 
   getJob<T, R>(queueName: string, jobId: string): Promise<QueueJob<T, R> | null>
 }

package/src/wirings/queue/signed-queue-service.ts

@@ -1,3 +1,4 @@
+import type { Safe } from '../../secret-value.js'
 import type { Logger } from '../../services/logger.js'
 import type { SecretService } from '../../services/secret-service.js'
 import {
@@ -24,7 +25,7 @@ export class SignedQueueService implements QueueService {
 
   public async add<T>(
     queueName: string,
-    data: T,
+    data: Safe<T>,
     options?: JobOptions
   ): Promise<string> {
     const pikkuUserId = options?.pikkuUserId