@pikku/core 0.12.78 → 0.12.80

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

@@ -3,6 +3,7 @@ import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, resolv
 import { checkForApprovals, appendStepMessages } from './ai-agent-stream.js';
 import { AgentInterruptedError, isAbortError, persistOrphanedToolResults, registerInterruptibleRun, trackInterruptNote, trackToolExecution, } from './ai-agent-interrupt.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
+import { applyInputMiddleware, describeApprovals, notifyAfterStep, toAccumulatedStep, } from './ai-agent-turn.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { randomUUID } from './ai-agent-utils.js';
@@ -75,25 +76,13 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
     ];
     // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
     const sharedNotes = {};
-    let modifiedMessages = runnerParams.messages;
-    let modifiedInstructions = runnerParams.instructions;
-    for (const mw of aiMiddlewares) {
-        if (mw.modifyInput) {
-            const result = await mw.modifyInput(singletonServices, {
-                messages: modifiedMessages,
-                instructions: modifiedInstructions,
-                shared: sharedNotes,
-            });
-            modifiedMessages = result.messages;
-            modifiedInstructions = result.instructions;
-        }
-    }
+    const { messages: modifiedMessages, instructions: modifiedInstructions } = await applyInputMiddleware(aiMiddlewares, singletonServices, {
+        messages: runnerParams.messages,
+        instructions: runnerParams.instructions,
+    }, sharedNotes);
     runnerParams.messages = modifiedMessages;
     runnerParams.instructions = modifiedInstructions;
-    // History records what the model was asked, which for a spoken turn is the
-    // transcript rather than the base64 audio that arrived — see the same note on
-    // the streaming path. Identity-checked, because a middleware may legitimately
-    // replace the message list with something unrelated to this turn.
+    // knowledge: decisions/internals/thread-history-records-the-transcript-not-the-audio.md
     const lastModified = modifiedMessages[modifiedMessages.length - 1];
     const persistedUserMessage = lastModified?.id === userMessage.id ? lastModified : userMessage;
     const runId = await aiRunState.createRun({
@@ -105,10 +94,7 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
         createdAt: new Date(),
         updatedAt: new Date(),
     });
-    // Registered on the same terms as `streamAIAgent`. A run created here is
-    // visible to `interruptAIAgent` through `aiRunState` either way, so skipping
-    // this would leave that call finding the run, passing the ownership check and
-    // then failing to stop it — reported as if it were running on another host.
+    // knowledge: decisions/internals/a-non-streaming-agent-run-registers-with-airunstate-too.md
     const interruptHandle = registerInterruptibleRun(runId);
     runnerParams.abortSignal = interruptHandle.signal;
     runnerParams.tools = trackToolExecution(runnerParams.tools, interruptHandle);
@@ -136,44 +122,13 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
             lastStepResult = stepResult;
             totalUsage.inputTokens += stepResult.usage.inputTokens;
             totalUsage.outputTokens += stepResult.usage.outputTokens;
-            for (const mw of aiMiddlewares) {
-                if (mw.afterStep) {
-                    await mw.afterStep(singletonServices, {
-                        stepNumber: step,
-                        text: stepResult.text,
-                        toolCalls: stepResult.toolCalls,
-                        toolResults: stepResult.toolResults,
-                        usage: stepResult.usage,
-                        finishReason: stepResult.finishReason,
-                    });
-                }
-            }
-            accumulatedSteps.push({
-                usage: stepResult.usage,
-                toolCalls: stepResult.toolCalls.map((tc) => {
-                    const tr = stepResult.toolResults.find((r) => r.toolCallId === tc.toolCallId);
-                    return {
-                        name: tc.toolName,
-                        args: tc.args,
-                        result: typeof tr?.result === 'string'
-                            ? tr.result
-                            : JSON.stringify(tr?.result ?? ''),
-                    };
-                }),
-            });
+            await notifyAfterStep(aiMiddlewares, singletonServices, step, stepResult);
+            accumulatedSteps.push(toAccumulatedStep(stepResult));
             if (stepResult.toolCalls.length === 0)
                 break;
             const approvalsNeeded = checkForApprovals(stepResult, runnerParams.tools);
             if (approvalsNeeded.length > 0) {
-                for (const approval of approvalsNeeded) {
-                    const toolDef = runnerParams.tools.find((t) => t.name === approval.toolName);
-                    if (toolDef?.approvalDescriptionFn && !approval.reason) {
-                        try {
-                            approval.reason = await toolDef.approvalDescriptionFn(approval.args);
-                        }
-                        catch { }
-                    }
-                }
+                await describeApprovals(approvalsNeeded, runnerParams.tools);
                 const pendingApprovals = approvalsNeeded.map((a) => a.agentRunId
                     ? {
                         type: 'agent-call',
@@ -270,10 +225,7 @@ export async function runAIAgent(agentName, input, params, agentSessionMap) {
         };
     }
     catch (error) {
-        // An interrupt is not a failure, so it skips the `onError` hooks and never
-        // becomes an `errorMessage`. Unlike the streaming path there is no partial
-        // reply to hand back — nothing was delivered — so the caller gets a typed
-        // throw it can tell apart from a provider outage instead of a result.
+        // knowledge: decisions/internals/an-agent-interrupt-is-not-a-failure.md
         const interruption = interruptHandle.interruption;
         if (interruption || isAbortError(error)) {
             await aiRunState.updateRun(runId, { status: 'interrupted' });
@@ -331,8 +283,18 @@ export async function resumeAIAgentSync(runId, approvals, params, expectedAgentN
     const approvedIds = new Set(approvals.filter((a) => a.approved).map((a) => a.toolCallId));
     const rejectedIds = new Set(approvals.filter((a) => !a.approved).map((a) => a.toolCallId));
     const savedPendingApprovals = [...(run.pendingApprovals ?? [])];
+    // The read above is not a claim — concurrent resumes all see the same pending
+    // list. `resolveApproval` is the claim, and only the caller it returns true
+    // for may run the tool.
+    const claimedIds = new Set();
     for (const { toolCallId, approved } of approvals) {
-        await aiRunState.resolveApproval(toolCallId, approved ? 'approved' : 'denied');
+        const claimed = await aiRunState.resolveApproval(toolCallId, approved ? 'approved' : 'denied');
+        if (claimed) {
+            claimedIds.add(toolCallId);
+        }
+    }
+    if (approvals.length > 0 && claimedIds.size === 0) {
+        throw new Error(`Approvals for run ${runId} were already resolved by another caller`);
     }
     const { tools } = await buildToolDefs(params, new Map(), run.resourceId, resolvedName, packageName, undefined, agent.aiMiddleware ?? []);
     const toolCallMessages = [];
@@ -340,6 +302,8 @@ export async function resumeAIAgentSync(runId, approvals, params, expectedAgentN
         if (pending.type !== 'tool-call')
             continue;
         const toolCallId = pending.toolCallId;
+        if (!claimedIds.has(toolCallId))
+            continue;
         let resultStr;
         if (rejectedIds.has(toolCallId)) {
             resultStr =
@@ -427,19 +391,7 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
     ];
     // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
     const sharedNotes = {};
-    let modifiedMessages = trimmedMessages;
-    let modifiedInstructions = instructions;
-    for (const mw of aiMiddlewares) {
-        if (mw.modifyInput) {
-            const result = await mw.modifyInput(singletonServices, {
-                messages: modifiedMessages,
-                instructions: modifiedInstructions,
-                shared: sharedNotes,
-            });
-            modifiedMessages = result.messages;
-            modifiedInstructions = result.instructions;
-        }
-    }
+    const { messages: modifiedMessages, instructions: modifiedInstructions } = await applyInputMiddleware(aiMiddlewares, singletonServices, { messages: trimmedMessages, instructions: instructions }, sharedNotes);
     const { tools: resumeTools } = await buildToolDefs(params, new Map(), run.resourceId, resolvedName, packageName, undefined, aiMiddlewares);
     const resolved = resolveModelConfig(resolvedName, agent);
     const maxSteps = resolved.maxSteps ?? 10;
@@ -472,44 +424,13 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
             lastStepResult = stepResult;
             totalUsage.inputTokens += stepResult.usage.inputTokens;
             totalUsage.outputTokens += stepResult.usage.outputTokens;
-            for (const mw of aiMiddlewares) {
-                if (mw.afterStep) {
-                    await mw.afterStep(singletonServices, {
-                        stepNumber: step,
-                        text: stepResult.text,
-                        toolCalls: stepResult.toolCalls,
-                        toolResults: stepResult.toolResults,
-                        usage: stepResult.usage,
-                        finishReason: stepResult.finishReason,
-                    });
-                }
-            }
-            accumulatedSteps.push({
-                usage: stepResult.usage,
-                toolCalls: stepResult.toolCalls.map((tc) => {
-                    const tr = stepResult.toolResults.find((r) => r.toolCallId === tc.toolCallId);
-                    return {
-                        name: tc.toolName,
-                        args: tc.args,
-                        result: typeof tr?.result === 'string'
-                            ? tr.result
-                            : JSON.stringify(tr?.result ?? ''),
-                    };
-                }),
-            });
+            await notifyAfterStep(aiMiddlewares, singletonServices, step, stepResult);
+            accumulatedSteps.push(toAccumulatedStep(stepResult));
             if (stepResult.toolCalls.length === 0)
                 break;
             const approvalsNeeded = checkForApprovals(stepResult, runnerParams.tools);
             if (approvalsNeeded.length > 0) {
-                for (const approval of approvalsNeeded) {
-                    const toolDef = runnerParams.tools.find((t) => t.name === approval.toolName);
-                    if (toolDef?.approvalDescriptionFn && !approval.reason) {
-                        try {
-                            approval.reason = await toolDef.approvalDescriptionFn(approval.args);
-                        }
-                        catch { }
-                    }
-                }
+                await describeApprovals(approvalsNeeded, runnerParams.tools);
                 const pendingApprovals = approvalsNeeded.map((a) => a.agentRunId
                     ? {
                         type: 'agent-call',

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

@@ -1,4 +1,5 @@
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
+import { applyInputMiddleware } from './ai-agent-turn.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { randomUUID } from './ai-agent-utils.js';
 import { SPOKEN_TRANSCRIPT } from './voice-input.js';
@@ -414,36 +415,18 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
     ];
     // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
     const sharedNotes = {};
-    let modifiedMessages = runnerParams.messages;
-    let modifiedInstructions = runnerParams.instructions;
-    for (const mw of aiMiddlewares) {
-        if (mw.modifyInput) {
-            const result = await mw.modifyInput(singletonServices, {
-                messages: modifiedMessages,
-                instructions: modifiedInstructions,
-                shared: sharedNotes,
-            });
-            modifiedMessages = result.messages;
-            modifiedInstructions = result.instructions;
-        }
-    }
+    const { messages: modifiedMessages, instructions: modifiedInstructions } = await applyInputMiddleware(aiMiddlewares, singletonServices, {
+        messages: runnerParams.messages,
+        instructions: runnerParams.instructions,
+    }, sharedNotes);
     runnerParams.messages = modifiedMessages;
     runnerParams.instructions = modifiedInstructions;
-    // Sent on the raw channel, ahead of the run. A voice client sent audio and so
-    // has no idea what it said; until this arrives its own message is a blank
-    // bubble. Ahead of the run rather than alongside it because the answer starts
-    // streaming within a few hundred milliseconds, and a question that appears
-    // after its answer reads as the wrong question.
+    // knowledge: decisions/internals/the-transcript-event-is-sent-ahead-of-the-run.md
     const transcript = sharedNotes[SPOKEN_TRANSCRIPT];
     if (typeof transcript === 'string') {
         channel.send({ type: 'transcript', text: transcript });
     }
-    // What goes into thread history is what the model was actually asked. For a
-    // spoken turn that is not what arrived over the wire: the wire carried a
-    // base64 audio blob, and persisting it would write megabytes of unreadable
-    // data into the history while losing the only readable record of the turn.
-    // Identity-checked rather than assumed — a middleware is free to rewrite the
-    // message list into something with no relation to the turn.
+    // knowledge: decisions/internals/thread-history-records-the-transcript-not-the-audio.md
     const lastModified = modifiedMessages[modifiedMessages.length - 1];
     const persistedUserMessage = lastModified?.id === userMessage.id ? lastModified : userMessage;
     const runId = await aiRunState.createRun({
@@ -508,10 +491,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
         : persistingChannel;
     const credentialFilteredChannel = {
         ...wrappedChannel,
-        // Returns what the inner send returns. Middleware runs asynchronously, so
-        // swallowing the promise here makes every `await channel.send(...)` upstream
-        // a no-op — including the one that waits for a buffering hook to flush
-        // before the channel closes.
+        // knowledge: decisions/internals/an-agent-stream-send-must-return-the-inner-sends-promise.md
         send: (event) => {
             if (event.type === 'tool-result' &&
                 event.result !== null &&
@@ -559,11 +539,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
             return persistingChannel.fullText;
         }
         await postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, runnerParams.messages, aiRunState, runId);
-        // Through the middleware rather than straight at the channel, and awaited.
-        // `done` is the only signal a stream hook gets that the reply is over, and
-        // the ones that buffer need it: `voiceOutput` speaks a trailing fragment
-        // that never reached a full stop, and waits for audio it has already paid
-        // to synthesize. Sent raw, that work is discarded by the `close()` below.
+        // knowledge: decisions/internals/the-agent-done-event-goes-through-the-middleware-and-is-awaited.md
         await outputChannel.send({ type: 'done' });
         channel.close();
         return persistingChannel.fullText;
@@ -650,12 +626,7 @@ export async function interruptAIAgent(input, params) {
     const stopped = signalRunInterrupt(input.runId, {
         reason: input.reason ?? 'user',
     });
-    // A run still marked `running` that this process cannot abort is executing on
-    // another instance. Returning a bare `false` there is indistinguishable from
-    // "it already finished", so the one deployment shape this registry does not
-    // cover fails silently — an agent that simply refuses to shut up, with nothing
-    // in the logs. Say so instead. See `signalRunInterrupt` for the fix (fan the
-    // interrupt out over eventHub so every instance tries locally).
+    // knowledge: decisions/internals/an-agent-run-owned-by-another-instance-says-so.md
     if (!stopped && run.status === 'running') {
         logger?.warn(`Could not interrupt run ${input.runId}: it is running in another process. ` +
             'Interrupts are process-local; fan them out over eventHub to support multiple instances.');
@@ -681,7 +652,13 @@ export async function resumeAIAgent(input, channel, params, options) {
     }
     const { agent, packageName, resolvedName } = resolveAgent(run.agentName);
     await assertAgentAuthorized(agent, params, packageName);
-    await aiRunState.resolveApproval(input.toolCallId, input.approved ? 'approved' : 'denied');
+    // The read above is not a claim — concurrent resumes all see the same pending
+    // approval. `resolveApproval` is the claim, and the loser must not go on to
+    // run the tool a second time.
+    const claimed = await aiRunState.resolveApproval(input.toolCallId, input.approved ? 'approved' : 'denied');
+    if (!claimed) {
+        throw new Error(`Approval for toolCallId ${input.toolCallId} was already resolved by another caller`);
+    }
     const { storage } = resolveMemoryServices(agent, singletonServices);
     const memoryConfig = agent.memory;
     const agentRunner = singletonServices.aiAgentRunner;
@@ -865,23 +842,8 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
     ];
     // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
     const sharedNotes = {};
-    let modifiedMessages = trimmedMessages;
-    let modifiedInstructions = instructions;
-    for (const mw of aiMiddlewares) {
-        if (mw.modifyInput) {
-            const result = await mw.modifyInput(singletonServices, {
-                messages: modifiedMessages,
-                instructions: modifiedInstructions,
-                shared: sharedNotes,
-            });
-            modifiedMessages = result.messages;
-            modifiedInstructions = result.instructions;
-        }
-    }
-    // Resuming is as interruptible as the first turn. It is the same person
-    // listening to the same voice, and after an approval it is where most of the
-    // reply actually gets spoken — an approved delete is followed by the agent
-    // talking about it, and that is a normal thing to talk over.
+    const { messages: modifiedMessages, instructions: modifiedInstructions } = await applyInputMiddleware(aiMiddlewares, singletonServices, { messages: trimmedMessages, instructions: instructions }, sharedNotes);
+    // knowledge: decisions/internals/a-resumed-agent-turn-is-as-interruptible-as-the-first.md
     const interruptHandle = registerInterruptibleRun(run.runId);
     const streamMiddleware = aiMiddlewares
         .filter((mw) => mw.modifyOutputStream)
@@ -961,10 +923,7 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             return;
         }
         await postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, runnerParams.messages, aiRunState, run.runId);
-        // Through the middleware, for the same reason as the first turn — and it
-        // matters more here. After an approval, most of what gets spoken is the
-        // agent talking about what it just did, so this is the half of the reply a
-        // dropped flush would silence.
+        // knowledge: decisions/internals/the-agent-done-event-goes-through-the-middleware-and-is-awaited.md
         await wrappedChannel.send({ type: 'done' });
         channel.close();
     }

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

@@ -0,0 +1,56 @@
+import type { CoreSingletonServices } from '../../types/core.types.js';
+import type { PikkuAIMiddlewareHooks } from './ai-agent.types.js';
+/** Exactly what `modifyInput` accepts and returns, taken from the hook itself. */
+type TurnInput = Pick<Parameters<NonNullable<PikkuAIMiddlewareHooks['modifyInput']>>[1], 'messages' | 'instructions'>;
+/**
+ * Run every `modifyInput` hook in order, threading each result into the next.
+ *
+ * Shared by the four places a turn starts — first turn and resume, on both the
+ * streaming and non-streaming paths. `sharedNotes` is one bag per run that the
+ * caller keeps, because hooks use it to pass things forward (`voiceInput`
+ * leaves the transcript there for `voiceOutput`).
+ */
+export declare const applyInputMiddleware: (aiMiddlewares: PikkuAIMiddlewareHooks[], singletonServices: CoreSingletonServices, input: TurnInput, sharedNotes: Record<string, unknown>) => Promise<TurnInput>;
+/** The step fields both agent paths hand to `afterStep`, taken from the hook. */
+type StepResult = Omit<Parameters<NonNullable<PikkuAIMiddlewareHooks['afterStep']>>[1], 'stepNumber'>;
+/**
+ * Notify every `afterStep` hook. The payload is the step verbatim plus its
+ * ordinal — a hook that wants the run's totals accumulates them itself.
+ */
+export declare const notifyAfterStep: (aiMiddlewares: PikkuAIMiddlewareHooks[], singletonServices: CoreSingletonServices, stepNumber: number, stepResult: StepResult) => Promise<void>;
+/**
+ * The step shape kept on the run: each tool call paired with its result.
+ *
+ * A result is stringified unless it already is a string, because this is what
+ * gets persisted and read back as history — an object there is unreadable.
+ */
+export declare const toAccumulatedStep: (stepResult: StepResult) => {
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    toolCalls: {
+        name: string;
+        args: Record<string, unknown>;
+        result: string;
+    }[];
+};
+type PendingApproval = {
+    toolName: string;
+    args: unknown;
+    reason?: string;
+};
+type ToolDef = {
+    name: string;
+    approvalDescriptionFn?: (args: any) => Promise<string> | string;
+};
+/**
+ * Fill in each approval's human-readable reason from the tool's own
+ * `approvalDescriptionFn`, where it did not supply one.
+ *
+ * A description that throws is swallowed: the approval still has to be raised,
+ * and a gate that disappears because its label failed to render is the worst
+ * available outcome.
+ */
+export declare const describeApprovals: (approvals: PendingApproval[], tools: ToolDef[]) => Promise<void>;
+export {};

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

@@ -0,0 +1,81 @@
+/**
+ * Run every `modifyInput` hook in order, threading each result into the next.
+ *
+ * Shared by the four places a turn starts — first turn and resume, on both the
+ * streaming and non-streaming paths. `sharedNotes` is one bag per run that the
+ * caller keeps, because hooks use it to pass things forward (`voiceInput`
+ * leaves the transcript there for `voiceOutput`).
+ */
+export const applyInputMiddleware = async (aiMiddlewares, singletonServices, input, sharedNotes) => {
+    let { messages, instructions } = input;
+    for (const mw of aiMiddlewares) {
+        if (!mw.modifyInput)
+            continue;
+        const result = await mw.modifyInput(singletonServices, {
+            messages,
+            instructions,
+            shared: sharedNotes,
+        });
+        messages = result.messages;
+        instructions = result.instructions;
+    }
+    return { messages, instructions };
+};
+/**
+ * Notify every `afterStep` hook. The payload is the step verbatim plus its
+ * ordinal — a hook that wants the run's totals accumulates them itself.
+ */
+export const notifyAfterStep = async (aiMiddlewares, singletonServices, stepNumber, stepResult) => {
+    for (const mw of aiMiddlewares) {
+        if (!mw.afterStep)
+            continue;
+        await mw.afterStep(singletonServices, {
+            stepNumber,
+            text: stepResult.text,
+            toolCalls: stepResult.toolCalls,
+            toolResults: stepResult.toolResults,
+            usage: stepResult.usage,
+            finishReason: stepResult.finishReason,
+        });
+    }
+};
+/**
+ * The step shape kept on the run: each tool call paired with its result.
+ *
+ * A result is stringified unless it already is a string, because this is what
+ * gets persisted and read back as history — an object there is unreadable.
+ */
+export const toAccumulatedStep = (stepResult) => ({
+    usage: stepResult.usage,
+    toolCalls: stepResult.toolCalls.map((tc) => {
+        const tr = stepResult.toolResults.find((r) => r.toolCallId === tc.toolCallId);
+        return {
+            name: tc.toolName,
+            args: tc.args,
+            result: typeof tr?.result === 'string'
+                ? tr.result
+                : JSON.stringify(tr?.result ?? ''),
+        };
+    }),
+});
+/**
+ * Fill in each approval's human-readable reason from the tool's own
+ * `approvalDescriptionFn`, where it did not supply one.
+ *
+ * A description that throws is swallowed: the approval still has to be raised,
+ * and a gate that disappears because its label failed to render is the worst
+ * available outcome.
+ */
+export const describeApprovals = async (approvals, tools) => {
+    for (const approval of approvals) {
+        if (approval.reason)
+            continue;
+        const toolDef = tools.find((t) => t.name === approval.toolName);
+        if (!toolDef?.approvalDescriptionFn)
+            continue;
+        try {
+            approval.reason = await toolDef.approvalDescriptionFn(approval.args);
+        }
+        catch { }
+    }
+};

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

@@ -400,7 +400,7 @@ export type AIStreamEvent = {
     toolName: string;
     args: unknown;
     reason?: string;
-    runId?: string;
+    runId: string;
     agent?: string;
     session?: string;
 } | {

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

@@ -135,12 +135,7 @@ export const voiceInput = (config) => pikkuAIMiddleware({
         // 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.
+        // knowledge: decisions/internals/an-empty-transcript-is-not-recorded.md
         if (heard.length > 0) {
             shared[SPOKEN_TRANSCRIPT] = heard.join(' ');
         }

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

@@ -105,11 +105,7 @@ export const voiceOutput = (config) => pikkuAIMiddleware({
         const { aiAgentRunner, logger } = services;
         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.
+        // knowledge: decisions/internals/voice-output-speaks-unless-voice-input-explicitly-says-otherwise.md
         if (!config?.always && shared[SPOKEN_TURN] === false)
             return event;
         /**
@@ -124,13 +120,7 @@ export const voiceOutput = (config) => pikkuAIMiddleware({
             if (!config?.model) {
                 throw new Error('voiceOutput requires a speech model (e.g. openai/tts-1)');
             }
-            // Checked per sentence but announced once per reply: a bilingual answer
-            // should still speak the half it can, and repeating the notice for
-            // every sentence of a long one would bury the reply itself.
-            //
-            // Per sentence is also what makes the voice right. A reply that answers
-            // in English and then quotes a Chinese title is two sentences in two
-            // scripts, and each is synthesized in the voice its own script needs.
+            // knowledge: decisions/internals/speech-synthesis-picks-a-voice-per-sentence-and-warns-once.md
             let voice = config.voice;
             if (config.speakableScripts) {
                 const unspeakable = unspeakableScripts(text, config.speakableScripts);

package/dist/wirings/channel/channel-common.js

@@ -12,6 +12,7 @@ export const runChannelLifecycleWithMiddleware = async ({ channelConfig, meta, l
     });
     const allChannelMiddleware = combineChannelMiddleware('channel', `${channelConfig.name}:${lifecycleType}:cm`, {
         wireInheritedChannelMiddleware: channelMiddlewareMeta,
+        // knowledge: questions/channel-middleware-accepts-bare-factories-that-nothing-resolves.md
         wireChannelMiddleware: channelConfig.channelMiddleware,
     });
     let wire = {

package/dist/wirings/channel/channel-handler.js

@@ -46,7 +46,7 @@ export const processMessageHandlers = (services, channelConfig, channelHandler,
                 ? `route '${routingProperty}:${routerValue}'`
                 : 'the default message route';
             logger.error(`Channel ${channelConfig.name} with id ${channelHandler.getChannel().channelId} requires a session for ${routeMessage}. No session is attached to this websocket connection. Ensure auth middleware establishes a session during websocket upgrade, and configure sessionStore when the runtime needs persisted sessions.`);
-            // TODO: Send error message back breaks typescript, but should be implemented somehow
+            // knowledge: questions/unauthorized-channel-replies-escape-the-declared-out-type.md
             channelHandler.getChannel().send(`Unauthorized for ${routeMessage}`);
             return;
         }
@@ -55,10 +55,7 @@ export const processMessageHandlers = (services, channelConfig, channelHandler,
         const pikkuFuncId = routeMeta.pikkuFuncId;
         // Get wire middleware: channel-level middleware + message-specific middleware
         const channelWireMiddleware = channelConfig.middleware || [];
-        // Check if onMessage is a wrapper object vs direct function config:
-        // - Direct config: onMessage.func is a plain Function
-        // - Wrapper: onMessage.func is a CorePikkuFunctionConfig (has onMessage.func.func)
-        // - Simple wrapper: onMessage has both func (plain Function) and middleware properties
+        // knowledge: decisions/internals/channel-message-handlers-accept-three-config-shapes.md
         const isWrapper = onMessage &&
             typeof onMessage === 'object' &&
             'func' in onMessage &&
@@ -83,6 +80,7 @@ export const processMessageHandlers = (services, channelConfig, channelHandler,
             inheritedMiddleware,
             wireMiddleware,
             inheritedChannelMiddleware: channelMeta?.channelMiddleware,
+            // knowledge: questions/channel-middleware-accepts-bare-factories-that-nothing-resolves.md
             wireChannelMiddleware: wireChannelMiddleware,
             coerceDataFromSchema: true,
             tags: channelConfig.tags,

package/dist/wirings/channel/channel-rpc-service.d.ts

@@ -1,12 +1,6 @@
 import type { DeploymentService } from '../../services/deployment-service.js';
 import { ChannelRPCRegistry } from './channel-rpc-registry.js';
 import { type ChannelRPCValidator } from './channel-rpc.types.js';
-/**
- * `remote` for channels that only ever flow one way — a server-sent stream, an
- * agent's output, a local CLI. Nothing is listening for a request on them, so
- * the call is refused rather than waiting out a timeout.
- */
-export declare const unsupportedChannelRemote: (funcName: string) => Promise<never>;
 /**
  * A `DeploymentService` whose transport is an open channel rather than an
  * address, so a server-side function can call back into a peer that has no

package/dist/wirings/channel/channel-rpc-service.js

@@ -1,13 +1,5 @@
 import { ChannelRPCRegistry } from './channel-rpc-registry.js';
 import { CHANNEL_RPC_REQUEST, CHANNEL_RPC_RESPONSE, ChannelRPCError, isChannelRPCPending, isChannelRPCResponse, } from './channel-rpc.types.js';
-/**
- * `remote` for channels that only ever flow one way — a server-sent stream, an
- * agent's output, a local CLI. Nothing is listening for a request on them, so
- * the call is refused rather than waiting out a timeout.
- */
-export const unsupportedChannelRemote = async (funcName) => {
-    throw new ChannelRPCError(`Cannot call "${funcName}" remotely: this channel has no peer that answers`, 'unsupported');
-};
 /**
  * A `DeploymentService` whose transport is an open channel rather than an
  * address, so a server-side function can call back into a peer that has no

package/dist/wirings/channel/channel-rpc.types.d.ts

@@ -88,3 +88,9 @@ export type ApprovalRequester = (request: {
 }) => Promise<boolean> | boolean;
 /** Checks one end of a call — arguments going out, or the answer coming back. */
 export type ChannelRPCValidator = (funcName: string, value: unknown) => Promise<void> | void;
+/**
+ * `remote` for wires with no peer that answers — a server-sent stream, an
+ * agent's output, a local CLI. Nothing is listening for a request on them, so
+ * the call is refused rather than waiting out a timeout.
+ */
+export declare const unsupportedChannelRemote: (funcName: string) => Promise<never>;

package/dist/wirings/channel/channel-rpc.types.js

@@ -48,3 +48,11 @@ export const isCapabilityDef = (capability) => typeof capability === 'object' &&
 export const resolveCapability = (capability) => isCapabilityDef(capability)
     ? capability
     : { execute: capability, needsApproval: true };
+/**
+ * `remote` for wires with no peer that answers — a server-sent stream, an
+ * agent's output, a local CLI. Nothing is listening for a request on them, so
+ * the call is refused rather than waiting out a timeout.
+ */
+export const unsupportedChannelRemote = async (funcName) => {
+    throw new ChannelRPCError(`Cannot call "${funcName}" remotely: this channel has no peer that answers`, 'unsupported');
+};

package/dist/wirings/channel/channel-runner.d.ts

@@ -1,8 +1,6 @@
-import type { CorePikkuPermission } from '../../function/functions.types.js';
 import type { SessionService } from '../../services/user-session-service.js';
-import type { CorePikkuMiddleware } from '../../types/core.types.js';
 import type { ChannelMeta, CoreChannel, RunChannelOptions, RunChannelParams } from './channel.types.js';
-export declare const wireChannel: <In, Channel extends string, PikkuPermission extends CorePikkuPermission<In>, PikkuMiddleware extends CorePikkuMiddleware, ChannelFunction>(channel: CoreChannel<In, Channel, PikkuPermission, PikkuMiddleware, ChannelFunction>) => void;
+export declare const wireChannel: <In, Channel extends string, ChannelConnect, ChannelDisconnect, ChannelFunctionMessage>(channel: CoreChannel<In, Channel, ChannelConnect, ChannelDisconnect, ChannelFunctionMessage>) => void;
 export declare const openChannel: ({ route, coerceDataFromSchema, request, }: Pick<CoreChannel<unknown, string>, "route"> & RunChannelParams<unknown> & {
     userSession: SessionService<any>;
 } & RunChannelOptions) => Promise<{