@pikku/core 0.12.72 → 0.12.77

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

@@ -1,7 +1,9 @@
 import type { CorePermissionGroup, CorePikkuPermission } from '../../function/functions.types.js';
 import type { CorePikkuMiddleware, MiddlewareMetadata, PermissionMetadata } from '../../types/core.types.js';
+import type { AIProviderOptions } from '../../services/ai-agent-runner-service.js';
 import type { PikkuChannel } from '../channel/channel.types.js';
 import type { CorePikkuChannelMiddleware } from '../channel/channel.types.js';
+import type { ApprovalPolicy } from '../channel/channel-rpc.js';
 export interface AIThread {
     id: string;
     resourceId: string;
@@ -49,6 +51,23 @@ export interface AIMessage {
     toolCalls?: AIToolCall[];
     toolResults?: AIToolResult[];
     reasoningContent?: string;
+    /**
+     * Set on an assistant message whose generation was cut short by
+     * an interrupt — the text is a mid-sentence fragment, not a reply.
+     * Carried into the next turn's context so the model can see it said only
+     * this much before being talked over, and decide for itself whether to
+     * resume, restate or move on. Storage that drops unknown fields loses the
+     * marker but keeps the fragment, which degrades to a truncated reply.
+     */
+    interrupted?: boolean;
+    /**
+     * Set on a tool message whose result arrived after the run was interrupted,
+     * so the model never got to describe it. The work happened; only the reply
+     * about it was lost. It is ordinary thread context on the next turn — the
+     * model raises it unprompted ("that deploy did go through") rather than the
+     * result being silently dropped or replayed as a fresh tool call.
+     */
+    undelivered?: boolean;
     createdAt: Date;
 }
 export interface AIAgentStep {
@@ -113,13 +132,24 @@ export interface AIAgentOutput {
  * another user's or org's threads.
  */
 export type SessionScope = 'user' | 'org';
-export interface AIAgentToolDef {
+/**
+ * `ApprovalPolicy` is shared with channel capabilities, but `Partial` here:
+ * absent `needsApproval` means "do not ask", which is safe because a tool is
+ * written by whoever runs the server it executes on. A capability runs on
+ * someone else's machine, so it requires the field instead.
+ */
+export interface AIAgentToolDef extends Partial<ApprovalPolicy> {
     name: string;
     description: string;
     inputSchema: Record<string, unknown>;
     execute: (input: unknown) => Promise<unknown>;
-    needsApproval?: boolean;
-    approvalDescriptionFn?: (input: unknown) => Promise<string>;
+    /**
+     * Mirrors the pikku function's `readonly` flag. A read that gets interrupted
+     * is discarded rather than reported: nothing changed, and by the next turn
+     * the data may be stale anyway — re-reading is cheaper than explaining a
+     * result the user never asked to hear about.
+     */
+    readonly?: boolean;
     /**
      * Set only by the framework on sub-agent delegating tools. Such a tool may
      * legitimately return an `__approvalRequired` marker to forward a nested
@@ -133,6 +163,23 @@ export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> =
     modifyInput?: (services: Services, 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;
@@ -143,7 +190,31 @@ export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> =
     modifyOutputStream?: (services: Services, 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.
+         *
+         * Returning events blocks the stream until the hook resolves, which is
+         * right for anything derived from the event and wrong for anything slow.
+         * Speech is the motivating case: awaiting a text-to-speech call before
+         * returning the text delta stalls the reader at every full stop and
+         * serialises synthesis behind playback. Return the text immediately,
+         * start the slow work, and `emit` its result when it lands.
+         *
+         * Ordering among emitted events is the caller's problem — chain them if
+         * it matters — and a hook that emits must make sure anything still
+         * outstanding has landed before it lets `done` through.
+         */
+        emit: (event: AIStreamEvent) => Promise<void>;
+        /**
+         * Aborts when the run is interrupted. Pass it to any provider call the
+         * hook makes: work started for a reply the user has already talked over
+         * is billed but never heard.
+         */
+        signal?: AbortSignal;
     }) => Promise<AIStreamEvent | AIStreamEvent[] | null> | AIStreamEvent | AIStreamEvent[] | null;
     modifyOutput?: (services: Services, ctx: {
         text: string;
@@ -216,8 +287,19 @@ export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMi
     description: string;
     summary?: string;
     errors?: string[];
+    /**
+     * The three fields below are the system prompt. `buildInstructions` joins
+     * whichever are set with a blank line, always in this order — role, then
+     * personality, then goal — and appends the tool-usage rules if the agent has
+     * tools. Nothing checks them against each other: the split is there to keep a
+     * prompt legible, and text put in the wrong one still reaches the model.
+     *
+     * Who the agent is. 'You are a support engineer triaging inbound bugs.'
+     */
     role?: string;
+    /** How it should sound: tone, vocabulary, how much it says at a time. */
     personality?: string;
+    /** What it is for — the only one of the three that is required. */
     goal: string;
     model: string;
     temperature?: number;
@@ -230,6 +312,16 @@ export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMi
     memory?: AIAgentMemoryConfig;
     maxSteps?: number;
     toolChoice?: 'auto' | 'required' | 'none';
+    /**
+     * Per-provider model settings, keyed by provider id and passed through
+     * untouched — for anything only one vendor offers, which the fields above
+     * deliberately do not try to unify.
+     *
+     * `{ openai: { reasoningEffort: 'minimal' } }` is the one that matters for
+     * voice: on gpt-5-mini it measured 0.9s to first token against 2.5s at the
+     * default, and a spoken reply is waited through rather than skimmed.
+     */
+    providerOptions?: AIProviderOptions;
     input?: unknown;
     output?: unknown;
     tags?: string[];
@@ -340,12 +432,32 @@ 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;
@@ -361,6 +473,14 @@ export type AIStreamEvent = {
     type: 'suspended';
     reason: 'rpc-missing';
     missingRpcs: string[];
+} | {
+    type: 'interrupted';
+    runId: string;
+    /** The truncated assistant text at the moment generation stopped. */
+    text: string;
+    reason: 'speech' | 'user' | 'timeout';
+    agent?: string;
+    session?: string;
 } | {
     type: 'done';
 };
@@ -392,7 +512,7 @@ export interface AgentRunState {
     agentName: string;
     threadId: string;
     resourceId: string;
-    status: 'running' | 'suspended' | 'completed' | 'failed';
+    status: 'running' | 'suspended' | 'completed' | 'failed' | 'interrupted';
     errorMessage?: string;
     suspendReason?: 'approval' | 'credential' | 'rpc-missing';
     missingRpcs?: string[];

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

@@ -1,9 +1,11 @@
-export { agent, agentStream, agentResume, agentApprove, } from './ai-agent-helpers.js';
+export { agent, agentStream, agentResume, agentApprove, agentInterrupt, } from './ai-agent-helpers.js';
 export { wrapChannelWithAGUI, type AGUIEvent } from './ai-agent-agui.js';
 export { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
-export { streamAIAgent, resumeAIAgent } from './ai-agent-stream.js';
-export { voiceInput } from './voice-input.js';
-export { voiceOutput } from './voice-output.js';
+export { streamAIAgent, resumeAIAgent, interruptAIAgent, } from './ai-agent-stream.js';
+export { voiceInput, readsAsNonSpeech, NoSpeechDetectedError, SPOKEN_TURN, SPOKEN_TRANSCRIPT, } from './voice-input.js';
+export { voiceOutput, unspeakableScripts, voiceForText, type SpeakableScripts, } from './voice-output.js';
+export { AgentInterruptedError, awaitPendingInterruptNote, getInFlightTools, isAbortError, isRunInterruptible, persistOrphanedToolResults, registerInterruptibleRun, signalRunInterrupt, trackInterruptNote, trackToolExecution, } from './ai-agent-interrupt.js';
+export type { AgentInterruption, AgentInterruptResult, InterruptibleRunHandle, OrphanedToolResult, } from './ai-agent-interrupt.js';
 export { type RunAIAgentParams, type StreamAIAgentOptions, ToolApprovalRequired, ToolCredentialRequired, canAccessThread, isOwnedByPrincipal, sessionPrincipals, threadOwnerConstraint, } from './ai-agent-prepare.js';
 export { addAIAgent, approveAIAgent, getAIAgents, getAIAgentsMeta, } from './ai-agent-registry.js';
 export type { AIAgentInput, AIAgentInputAttachment, AIAgentMeta, AIAgentMemoryConfig, AIAgentStep, AIContentPart, AgentRunRow, AgentRunService, AgentRunState, AIMessage, AIStreamChannel, AIStreamEvent, AIThread, CoreAIAgent, PendingApproval, PikkuAIMiddlewareHooks, } from './ai-agent.types.js';

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

@@ -1,8 +1,9 @@
-export { agent, agentStream, agentResume, agentApprove, } from './ai-agent-helpers.js';
+export { agent, agentStream, agentResume, agentApprove, agentInterrupt, } from './ai-agent-helpers.js';
 export { wrapChannelWithAGUI } from './ai-agent-agui.js';
 export { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
-export { streamAIAgent, resumeAIAgent } from './ai-agent-stream.js';
-export { voiceInput } from './voice-input.js';
-export { voiceOutput } from './voice-output.js';
+export { streamAIAgent, resumeAIAgent, interruptAIAgent, } from './ai-agent-stream.js';
+export { voiceInput, readsAsNonSpeech, NoSpeechDetectedError, SPOKEN_TURN, SPOKEN_TRANSCRIPT, } from './voice-input.js';
+export { voiceOutput, unspeakableScripts, voiceForText, } from './voice-output.js';
+export { AgentInterruptedError, awaitPendingInterruptNote, getInFlightTools, isAbortError, isRunInterruptible, persistOrphanedToolResults, registerInterruptibleRun, signalRunInterrupt, trackInterruptNote, trackToolExecution, } from './ai-agent-interrupt.js';
 export { ToolApprovalRequired, ToolCredentialRequired, canAccessThread, isOwnedByPrincipal, sessionPrincipals, threadOwnerConstraint, } from './ai-agent-prepare.js';
 export { addAIAgent, approveAIAgent, getAIAgents, getAIAgentsMeta, } from './ai-agent-registry.js';

package/dist/wirings/ai-agent/voice-input.d.ts

@@ -1,10 +1,68 @@
+/**
+ * Raised when every audio part in a turn turned out to be non-speech.
+ *
+ * Distinct from a transcription failure, because the response is different: a
+ * failure is worth reporting, whereas this is the microphone doing its job on a
+ * pause. A voice loop should catch it and go back to listening without running
+ * the agent — answering a hallucinated sentence is worse than answering nothing.
+ */
+export declare class NoSpeechDetectedError extends Error {
+    constructor();
+}
+/**
+ * Whether nothing usable was said — an empty transcript, and nothing cleverer
+ * than that.
+ *
+ * There was a confidence gate here once, and it is worth recording why it is
+ * gone. Whisper is trained on subtitles, so audio it cannot parse comes back
+ * not as nothing but as stock filler appended to real speech: "Hello, my name
+ * is Yasir. Thank you." where only the first sentence was spoken. The obvious
+ * defence is to drop low-confidence segments, and it does not work. Measured on
+ * a real turn, the invented "Thank you." scored `avg_logprob` -0.52 against
+ * -0.30 for the genuine sentence beside it, and `no_speech_prob` read 0.000 for
+ * both. Whisper is *confident* when it invents, because the text it invents is
+ * high-probability text. No threshold separates those two numbers, and one set
+ * low enough to try would take real quiet speech with it.
+ *
+ * The fix belongs at the model, not behind it: an ASR that is not a
+ * subtitle-trained autoregressive decoder returns an empty string on non-speech
+ * and there is nothing left to filter. Hence this reduces to asking whether
+ * anything came back at all — which is a property every provider reports
+ * honestly, unlike per-segment confidence (Nemotron, for one, hardcodes
+ * `avg_logprob` to 0.0).
+ */
+export declare const readsAsNonSpeech: (result: {
+    text?: string;
+}) => boolean;
+/**
+ * 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 declare 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 declare const SPOKEN_TRANSCRIPT = "voice:transcript";
 export declare const voiceInput: (config?: {
     language?: string;
     model?: string;
     allowedAudioHosts?: string[];
 }) => import("./ai-agent.types.js").PikkuAIMiddlewareHooks<Record<string, unknown>, import("../../types/core.types.js").CoreSingletonServices<{
     logLevel?: import("../../services/logger.js").LogLevel;
-    secrets?: {};
+    secrets?: {
+        requireAllowedHosts?: boolean;
+    };
     workflow?: import("../workflow/workflow.types.js").WorkflowServiceConfig;
     webhook?: import("../../services/webhook-service.js").WebhookServiceConfig;
     postgres?: import("../../types/core.types.js").PostgresConfig;

package/dist/wirings/ai-agent/voice-input.js

@@ -9,6 +9,43 @@ function base64ToUint8Array(base64) {
     return bytes;
 }
 const MAX_AUDIO_SIZE = 50 * 1024 * 1024;
+/**
+ * Raised when every audio part in a turn turned out to be non-speech.
+ *
+ * Distinct from a transcription failure, because the response is different: a
+ * failure is worth reporting, whereas this is the microphone doing its job on a
+ * pause. A voice loop should catch it and go back to listening without running
+ * the agent — answering a hallucinated sentence is worse than answering nothing.
+ */
+export class NoSpeechDetectedError extends Error {
+    constructor() {
+        super('No speech was detected in the audio.');
+        this.name = 'NoSpeechDetectedError';
+    }
+}
+/**
+ * Whether nothing usable was said — an empty transcript, and nothing cleverer
+ * than that.
+ *
+ * There was a confidence gate here once, and it is worth recording why it is
+ * gone. Whisper is trained on subtitles, so audio it cannot parse comes back
+ * not as nothing but as stock filler appended to real speech: "Hello, my name
+ * is Yasir. Thank you." where only the first sentence was spoken. The obvious
+ * defence is to drop low-confidence segments, and it does not work. Measured on
+ * a real turn, the invented "Thank you." scored `avg_logprob` -0.52 against
+ * -0.30 for the genuine sentence beside it, and `no_speech_prob` read 0.000 for
+ * both. Whisper is *confident* when it invents, because the text it invents is
+ * high-probability text. No threshold separates those two numbers, and one set
+ * low enough to try would take real quiet speech with it.
+ *
+ * The fix belongs at the model, not behind it: an ASR that is not a
+ * subtitle-trained autoregressive decoder returns an empty string on non-speech
+ * and there is nothing left to filter. Hence this reduces to asking whether
+ * anything came back at all — which is a property every provider reports
+ * honestly, unlike per-segment confidence (Nemotron, for one, hardcodes
+ * `avg_logprob` to 0.0).
+ */
+export const readsAsNonSpeech = (result) => !(result.text ?? '').trim();
 async function fetchAsUint8Array(url, allowedAudioHosts) {
     const response = await safeFetch(url, {}, { allowedHosts: allowedAudioHosts });
     const contentLength = response.headers.get('content-length');
@@ -21,25 +58,44 @@ async function fetchAsUint8Array(url, allowedAudioHosts) {
     }
     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) => pikkuAIMiddleware({
-    modifyInput: async (services, { messages, instructions }) => {
+    modifyInput: async (services, { messages, instructions, shared }) => {
         const aiAgentRunner = services.aiAgentRunner;
         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;
-        if (!parts)
+        const parts = last?.role === 'user' && typeof last.content !== 'string'
+            ? last.content
+            : undefined;
+        const hasAudio = !!parts?.some((p) => p.type === 'file' && !!p.mediaType?.startsWith('audio/'));
+        // 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 hasAudio = parts.some((p) => p.type === 'file' && !!p.mediaType?.startsWith('audio/'));
-        if (!hasAudio)
-            return { messages, instructions };
-        // Process parts in order, replacing each audio part with its transcription
-        // in place. Sequential, so no unbounded parallel downloads/transcriptions
-        // and original content ordering is preserved.
         const updatedContent = [];
+        const heard = [];
         for (const p of parts) {
             if (!(p.type === 'file' && p.mediaType?.startsWith('audio/'))) {
                 updatedContent.push(p);
@@ -51,6 +107,9 @@ export const voiceInput = (config) => pikkuAIMiddleware({
             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,
@@ -64,8 +123,27 @@ export const voiceInput = (config) => pikkuAIMiddleware({
                     }
                     : {}),
             });
+            // Dropped when nothing was said: an empty text part is still a turn the
+            // 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', text: result.text });
         }
+        // Every part was audio, and none of it was speech. There is nothing left
+        // 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/dist/wirings/ai-agent/voice-output.d.ts

@@ -1,6 +1,47 @@
 type VoiceOutputState = {
     textBuffer?: string;
+    /**
+     * The audio emitted so far, as a chain.
+     *
+     * Synthesis for every finished sentence starts immediately, so the second
+     * sentence is being generated while the first is still being spoken. That
+     * also means the second can finish first — a short sentence after a long one
+     * routinely does. Chaining the *emissions* keeps the client receiving audio
+     * in the order it was written while leaving the generation overlapped.
+     */
+    tail?: Promise<void>;
+    /** Whether this reply has already said it cannot be spoken aloud. */
+    reportedUnspeakable?: boolean;
 };
+/**
+ * The scripts a model can pronounce, and optionally the voice each one needs.
+ *
+ * The array form is for a model whose voice is the same whatever the script.
+ * The record form exists because that is not the common case: Kokoro speaks
+ * Mandarin, Japanese and Hindi well, but only through a voice belonging to that
+ * language. Asked for Chinese in its default American-English voice it spells
+ * the characters out — 9.9 seconds of "Chinese letter, Chinese letter" for a
+ * sentence the right voice says in 3.5. Same model, same text, same price.
+ */
+export type SpeakableScripts = string[] | Record<string, string>;
+/**
+ * The scripts present in `text` that the model was not said to handle.
+ *
+ * Silence would be the wrong answer here and so would a best effort. Handed
+ * Arabic — which it has no voice for at all — Kokoro does not fail and does not
+ * stay quiet: it reads out the *letter names*, twenty-four seconds of "Arabic
+ * meem, Arabic ra" for a one-line sentence, which is worse than either. Naming
+ * the gap lets the caller say so instead.
+ */
+export declare const unspeakableScripts: (text: string, speakable: SpeakableScripts) => string[];
+/**
+ * The voice to speak `text` in, or `fallback` if no mapped script appears.
+ *
+ * A sentence is regularly in more than one script, so which one decides is
+ * settled by {@link SCRIPT_PRECEDENCE} rather than by the order the config
+ * happens to be written in.
+ */
+export declare const voiceForText: (text: string, speakable: SpeakableScripts, fallback?: string) => string | undefined;
 export declare const voiceOutput: (config?: {
     model?: string;
     format?: string;
@@ -8,9 +49,36 @@ export declare const voiceOutput: (config?: {
     instructions?: string;
     speed?: number;
     language?: string;
+    /**
+     * Scripts the configured model can actually pronounce, and the voice each
+     * needs — see {@link SpeakableScripts}. Anything written in another script is
+     * left unspoken and reported once, as a `voice-unsupported` data event,
+     * rather than sent to a model that will mangle it.
+     *
+     * Omitted means no check: every model is trusted with every script, which is
+     * 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;
 }) => import("./ai-agent.types.js").PikkuAIMiddlewareHooks<VoiceOutputState, import("../../types/core.types.js").CoreSingletonServices<{
     logLevel?: import("../../services/logger.js").LogLevel;
-    secrets?: {};
+    secrets?: {
+        requireAllowedHosts?: boolean;
+    };
     workflow?: import("../workflow/workflow.types.js").WorkflowServiceConfig;
     webhook?: import("../../services/webhook-service.js").WebhookServiceConfig;
     postgres?: import("../../types/core.types.js").PostgresConfig;