@pikku/core 0.12.78 → 0.12.80

package/dist/wirings/workflow/workflow-recovery.js

@@ -0,0 +1,101 @@
+import { DEFAULT_STALLED_RUN_LIMIT, DEFAULT_STALLED_RUN_MS, DEFAULT_UNDISPATCHED_STEP_LIMIT, DEFAULT_UNDISPATCHED_STEP_MS, REDISPATCH_BACKOFF_MAX_ENTRIES, REDISPATCH_BACKOFF_MAX_MS, REDISPATCH_BACKOFF_MS, } from './workflow-constants.js';
+/**
+ * Per-process, advisory record of when a run may next be re-dispatched.
+ *
+ * Keyed by run rather than by step because the run is the unit of re-drive:
+ * `resumeWorkflow` replays the whole run and re-dispatches every step still
+ * owed a job, so holding off a single step while resuming its run would
+ * suppress nothing.
+ *
+ * Losing this on restart costs extra dispatches, never correctness.
+ */
+export class RedispatchBackoff {
+    eligibleAt = new Map();
+    delays = new Map();
+    isEligible(runId, now) {
+        const at = this.eligibleAt.get(runId);
+        return at === undefined || at <= now;
+    }
+    note(runId, now) {
+        const previous = this.delays.get(runId);
+        const delay = Math.min(previous === undefined ? REDISPATCH_BACKOFF_MS : previous * 2, REDISPATCH_BACKOFF_MAX_MS);
+        // A run that settles is never returned again, so entries are only evicted
+        // by this bound — oldest first, which is also least recently re-dispatched.
+        if (this.eligibleAt.size >= REDISPATCH_BACKOFF_MAX_ENTRIES) {
+            const oldest = this.eligibleAt.keys().next();
+            if (!oldest.done) {
+                this.eligibleAt.delete(oldest.value);
+                this.delays.delete(oldest.value);
+            }
+        }
+        this.delays.set(runId, delay);
+        this.eligibleAt.set(runId, now + delay);
+    }
+}
+const resumeEach = async (runIds, { resume, logger }, failure) => {
+    const succeeded = [];
+    for (const runId of runIds) {
+        try {
+            await resume(runId);
+            succeeded.push(runId);
+        }
+        catch (err) {
+            // One unresumable run must not stop the sweep from recovering the rest.
+            logger?.error(failure(runId, err instanceof Error ? err.message : String(err)));
+        }
+    }
+    return succeeded;
+};
+/**
+ * Re-drive runs whose next move was lost, and report which were resumed.
+ *
+ * Arming a step is two writes to two systems — the step row, then the queue or
+ * scheduler job — so a process that dies between them leaves a run that is
+ * `running` with nothing in flight. Nothing notices: the run parks on a step
+ * that will never complete and never error, so it neither finishes nor fails.
+ * (Seen on a `workflow.sleep()`: a deploy restart landed between the sleep
+ * step's insert and its timer, parking the run permanently.)
+ *
+ * Replay is the recovery — `resumeWorkflow` re-orchestrates from persisted step
+ * state, and every settled step is memoized, so resuming a run that was not
+ * actually stuck costs an orchestration pass and changes nothing. That
+ * idempotence is what makes an idle-time heuristic safe here; a run that is
+ * legitimately mid-sleep is excluded anyway, since its step is `scheduled`.
+ */
+export const sweepStalledRuns = async (findStalledRunIds, options, deps) => {
+    const before = new Date(Date.now() - (options?.stalledAfterMs ?? DEFAULT_STALLED_RUN_MS));
+    const runIds = await findStalledRunIds(before, options?.limit ?? DEFAULT_STALLED_RUN_LIMIT);
+    return {
+        resumed: await resumeEach(runIds, deps, (runId, detail) => `Failed to resume stalled workflow run ${runId}: ${detail}`),
+    };
+};
+/**
+ * Re-drive steps whose dispatch was lost, and report which runs were nudged.
+ *
+ * The step row is the outbox record and this is the relay. Age is the only
+ * signal available — a step `pending` because its dispatch was lost is
+ * indistinguishable from one whose job is merely still queued — so a step past
+ * `undispatchedAfterMs` is re-dispatched regardless, and correctness rests on
+ * the claim in `executeWorkflowStepInner` rather than on the guess being right.
+ * A redundant dispatch costs one queue message: the loser reads `running` and
+ * returns without invoking anything.
+ *
+ * Re-dispatches back off per run (doubling from 30s, capped at 10m) so a
+ * genuine queue backlog is not amplified by a tick that keeps firing at the
+ * steps the backlog is already delaying.
+ */
+export const sweepUndispatchedSteps = async (findUndispatchedSteps, backoff, options, deps) => {
+    const before = new Date(Date.now() - (options?.undispatchedAfterMs ?? DEFAULT_UNDISPATCHED_STEP_MS));
+    const steps = await findUndispatchedSteps(before, options?.limit ?? DEFAULT_UNDISPATCHED_STEP_LIMIT);
+    const now = Date.now();
+    const runIds = new Set();
+    for (const { runId } of steps) {
+        if (!backoff.isEligible(runId, now))
+            continue;
+        backoff.note(runId, now);
+        runIds.add(runId);
+    }
+    return {
+        redispatched: await resumeEach(runIds, deps, (runId, detail) => `Failed to re-dispatch workflow run ${runId}: ${detail}`),
+    };
+};

package/dist/wirings/workflow/workflow-run-engine.types.d.ts

@@ -0,0 +1,54 @@
+import type { PikkuRawWire, SerializedError } from '../../types/core.types.js';
+import type { CoreWorkflow, PikkuWorkflowWire, StepState, WorkflowRun, WorkflowStatus, WorkflowStepOptions } from './workflow.types.js';
+export interface RunLifecycleContext {
+    runId: string;
+    run: WorkflowRun;
+    workflowMeta: any;
+    workflow: CoreWorkflow;
+    wire: PikkuRawWire;
+    packageName: string | null;
+}
+/**
+ * The subset of the workflow service a step executor is allowed to call back
+ * into.
+ */
+export interface WorkflowRunEngine {
+    inlineStep(runId: string, logicalStepName: string, fn: Function, stepOptions?: WorkflowStepOptions, data?: any, funcName?: string): Promise<any>;
+    updateRunStatus(runId: string, status: WorkflowStatus, output?: any, error?: SerializedError): Promise<void>;
+    onChildWorkflowFailed(run: WorkflowRun, error: unknown): Promise<void>;
+    verifyStepName(stepName: unknown): void;
+}
+/**
+ * Hooks a host may install to decorate runs it did not start. Used by the
+ * scenario service to attach its own per-run state.
+ */
+export interface WorkflowRunExtension {
+    attachRunContext(runId: string, workflowMeta: any, options?: Record<string, any>): Promise<void>;
+    detachRunContext(runId: string): void;
+    decorateRunWire(wire: PikkuRawWire, context: {
+        runId: string;
+        workflowMeta: any;
+        workflowWire: PikkuWorkflowWire;
+    }): void;
+    decorateWorkflowWire(workflowWire: PikkuWorkflowWire, context: {
+        name: string;
+        runId: string;
+        rpcService: any;
+        addonNamespace?: string | null;
+    }): void;
+    onBeforeRunFunc(context: RunLifecycleContext): Promise<void>;
+    onAfterRunFunc(context: RunLifecycleContext, outcome: 'completed' | 'failed' | 'interrupted', failure: unknown): Promise<void>;
+}
+/**
+ * Per-run bookkeeping held only for the lifetime of an in-process execution.
+ */
+export type RunContext = {
+    activeExecutions: number;
+    inline?: boolean;
+    ordinals: Map<string, number>;
+    lastStep?: string;
+    replay?: {
+        steps?: Map<string, StepState>;
+        run?: WorkflowRun;
+    };
+};

package/dist/wirings/workflow/workflow-run-engine.types.js

@@ -0,0 +1 @@
+export {};

package/dist/wirings/workflow/workflow-run-ownership.d.ts

@@ -0,0 +1,16 @@
+import { ForbiddenError } from '../../errors/errors.js';
+import type { CoreUserSession } from '../../types/core.types.js';
+import type { WorkflowRunWire } from './workflow.types.js';
+export declare class WorkflowRunForbiddenError extends ForbiddenError {
+    constructor();
+}
+/**
+ * A run started through a session records that session's user as its owner, and
+ * only that user may read it or answer its approval gates.
+ *
+ * A run with no recorded owner — started by a trigger, a scheduler, or a route
+ * wired without auth — has nobody to compare a caller against, so ownership is
+ * not a control that exists for it. Gate those with `auth` or `permissions` on
+ * the entrypoint instead.
+ */
+export declare const assertWorkflowRunOwner: (wire: WorkflowRunWire | undefined, session: CoreUserSession | undefined) => void;

package/dist/wirings/workflow/workflow-run-ownership.js

@@ -0,0 +1,29 @@
+import { ForbiddenError } from '../../errors/errors.js';
+import { addError } from '../../errors/error-handler.js';
+export class WorkflowRunForbiddenError extends ForbiddenError {
+    constructor() {
+        super('Not authorized to access this workflow run');
+    }
+}
+addError(WorkflowRunForbiddenError, {
+    status: 403,
+    message: 'Not authorized to access this workflow run.',
+});
+/**
+ * A run started through a session records that session's user as its owner, and
+ * only that user may read it or answer its approval gates.
+ *
+ * A run with no recorded owner — started by a trigger, a scheduler, or a route
+ * wired without auth — has nobody to compare a caller against, so ownership is
+ * not a control that exists for it. Gate those with `auth` or `permissions` on
+ * the entrypoint instead.
+ */
+export const assertWorkflowRunOwner = (wire, session) => {
+    const owner = wire?.pikkuUserId;
+    if (!owner) {
+        return;
+    }
+    if (!session?.userId || session.userId !== owner) {
+        throw new WorkflowRunForbiddenError();
+    }
+};

package/dist/wirings/workflow/workflow-suspend.d.ts

@@ -0,0 +1,12 @@
+import type { ApprovalStore } from './workflow-approval.js';
+/** The durable step name a suspension point is recorded under. */
+export declare const suspendStepNameFor: (reason: string) => string;
+/** What the suspend gate needs from the workflow service. */
+export type SuspendStore = Pick<ApprovalStore, 'getStepState' | 'insertStepState' | 'setStepRunning' | 'setStepResult'>;
+/**
+ * Record a suspension point and unwind the run.
+ *
+ * A suspension that has already succeeded returns instead of throwing, so a
+ * replay walks past a gate the run has already passed through.
+ */
+export declare const recordSuspension: (store: SuspendStore, runId: string, reason: string, stepName: string, fromStepName: string | undefined) => Promise<void>;

package/dist/wirings/workflow/workflow-suspend.js

@@ -0,0 +1,33 @@
+import { WorkflowSuspendedException } from './workflow-errors.js';
+/** The durable step name a suspension point is recorded under. */
+export const suspendStepNameFor = (reason) => `__workflow_suspend:${reason}`;
+/**
+ * Record a suspension point and unwind the run.
+ *
+ * A suspension that has already succeeded returns instead of throwing, so a
+ * replay walks past a gate the run has already passed through.
+ */
+export const recordSuspension = async (store, runId, reason, stepName, fromStepName) => {
+    const insert = () => store.insertStepState(runId, stepName, 'pikkuWorkflowSuspend', { reason }, undefined, fromStepName);
+    let stepState;
+    try {
+        stepState = await store.getStepState(runId, stepName);
+    }
+    catch {
+        stepState = await insert();
+    }
+    if (!stepState.stepId) {
+        stepState = await insert();
+    }
+    if (stepState.status === 'succeeded') {
+        return;
+    }
+    if (stepState.status === 'pending') {
+        await store.setStepRunning(stepState.stepId);
+    }
+    await store.setStepResult(stepState.stepId, {
+        reason,
+        suspendedAt: new Date().toISOString(),
+    });
+    throw new WorkflowSuspendedException(runId, reason);
+};

package/dist/wirings/workflow/workflow.types.d.ts

@@ -49,6 +49,13 @@ export interface WorkflowRun {
 export interface StepState {
     stepId: string;
     status: StepStatus;
+    /**
+     * The function the workflow dispatched this step with, recorded so a worker
+     * can reject a queue message naming anything else. `null` is a step with no
+     * function of its own (inline work); `undefined` is a store that never
+     * recorded one, and cannot be compared against.
+     */
+    rpcName?: string | null;
     result?: any;
     error?: SerializedError;
     attemptCount: number;

package/knowledge/decisions/internals/a-non-streaming-agent-run-registers-with-airunstate-too.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: A non-streaming agent run registers with aiRunState on the same terms as a streaming one
+description: Otherwise interruptAIAgent finds the run, passes the ownership check, then cannot stop it — and reports that as if the run were on another host
+tags: core, ai-agent
+---
+
+# A non-streaming agent run registers with `aiRunState` too
+
+`runAIAgent` registers its run with `aiRunState` exactly as `streamAIAgent`
+does, even though nothing is streaming and there is no channel to interrupt.
+
+`interruptAIAgent` resolves a run through `aiRunState` first, checks ownership,
+then looks for a local abort handle. A run that skipped registration is invisible
+at the first step. A run that registered but has no handle is visible, passes the
+ownership check, and then cannot be stopped — which the interrupt path reports as
+"running on another instance". That message would be wrong and actively
+misleading: the run is right here, and the deployment is single-instance.
+
+**What this rules out:** treating registration as a streaming concern. It is an
+addressability concern, and the two paths have to be addressable the same way for
+the interrupt path's diagnosis to mean anything.

package/knowledge/decisions/internals/a-resumed-agent-turn-is-as-interruptible-as-the-first.md

@@ -0,0 +1,20 @@
+---
+type: decision
+title: A resumed turn is as interruptible as the first one
+description: It is the same person listening to the same voice, and after an approval it is where most of the reply actually gets spoken
+tags: core, ai-agent
+---
+
+# A resumed turn is as interruptible as the first one
+
+Resuming after an approval registers for interruption on the same terms as the
+original turn.
+
+It is the same person listening to the same voice, so the reason to allow
+interruption has not changed. And after an approval is precisely where most of
+the reply gets spoken: an approved delete is followed by the agent describing
+what it did, which is a normal thing for a listener to talk over.
+
+**What this rules out:** treating the resume as a short continuation not worth
+wiring for interruption. By volume of speech it is usually the larger half of
+the exchange.

package/knowledge/decisions/internals/a-scenario-step-template-is-offered-unfilled.md

@@ -0,0 +1,21 @@
+---
+type: decision
+title: A scenario step's prose template is offered to a virtual user unfilled
+description: A reporter fills placeholders from a run that happened; there is no run yet, and the filled form would answer the question the user is there to answer
+tags: core, virtual-user
+---
+
+# A scenario step's prose template is offered unfilled
+
+When a scenario step becomes a catalogue entry, its prose template goes in with
+its placeholders intact — braces and all.
+
+A reporter fills those placeholders from a run that already happened. There is
+no run yet at derivation time, so there is nothing to fill them from. More
+importantly, filling them would answer the wrong question: "invites {email}"
+tells the user to choose someone, where "invites ada@example.com" tells it whom
+— and *whom* is the scenario author's answer, not something the virtual user
+worked out.
+
+**What this rules out:** substituting example or fixture values to make the
+catalogue read more naturally. It reads better and tests less.

package/knowledge/decisions/internals/a-virtual-user-decides-whether-to-trust-memory-once-per-turn.md

@@ -0,0 +1,21 @@
+---
+type: decision
+title: A virtual user decides whether to trust its notes once per turn, by one roll
+description: The difference between the stale, newcomer and auditor dispositions is expressed as a single probability rather than as prose in each prompt
+tags: core, virtual-user
+---
+
+# A virtual user decides whether to trust its notes once per turn
+
+Each turn the run makes one weighted decision: does this user act on what it
+already recorded, or go and look again.
+
+That single roll is where the dispositions differ. `stale` almost always trusts
+its notes — that is what makes it stale. A `newcomer` has none to trust. An
+`auditor` re-checks nearly everything, which is the entire point of an auditor.
+Expressing it as one probability keeps the difference between those runs in one
+readable place instead of spread through three prompts as English that drifts.
+
+**What this rules out:** encoding "you are suspicious of your own notes" into
+each disposition's prompt text, where the behaviour becomes a property of how
+the model reads prose rather than something the run controls and can report.

package/knowledge/decisions/internals/a-wall-clock-threshold-is-a-load-test-in-disguise.md

@@ -0,0 +1,46 @@
+---
+type: decision
+title: A wall-clock threshold is a load test in disguise
+description: The KEK derivation test asserted a fixed 50ms budget for work that took 10ms, which went red about one run in five once the suite was large enough to compete for the machine
+tags: core, testing, crypto
+---
+
+# A wall-clock threshold is a load test in disguise
+
+`crypto-utils.test.ts` guards a real property: unwrapping N secrets must not
+cost N KEK derivations. Deriving a KEK is a deliberately slow KDF, so doing it
+per secret turns a 10ms operation into a 4-second one.
+
+It guarded it with `assert.ok(elapsed < 50)`. Measured on this machine:
+
+| | |
+| --- | --- |
+| one `deriveKEK` | ~86ms |
+| 50 `envelopeDecrypt` | 10.8ms |
+| the old 50ms threshold | 4.6x headroom |
+| the failure it guards against | ~4281ms — a **396x** separation |
+
+So the assertion had 4.6x of margin to detect a 396x regression. Everything
+between those two numbers was noise, and once core's suite reached ~2000 tests
+competing for the same cores, a 10ms window drifting past 50ms became routine:
+roughly one run in five went red, always on a machine where nothing was wrong.
+
+**Calibrate against a measurement taken in the same run.** The test already
+derives a KEK, so timing that call is free, and the assertion becomes
+`elapsed < oneDerivation` — unwrapping all fifty must cost less than deriving
+once. Under load both sides slow down together, so the ratio holds.
+
+**What this rules out:** raising the constant. 100ms or 200ms buys a smaller
+flake rate and the same class of bug, and it drifts again the next time the
+suite grows or CI moves to a noisier runner. Any assertion of the form
+"operation X takes less than N milliseconds" has this problem; express it as a
+ratio against something measured alongside it.
+
+Worth knowing: `envelopeDecrypt(kek: CryptoKey, …)` takes the derived key as a
+parameter, so it *cannot* derive one — the property is already enforced by the
+signature, and [[the-api-report-pins-members-not-just-names]] would catch a
+change to it. The test is defence in depth, which is a reason to make it cheap
+and quiet rather than to delete it.
+
+Related: [[an-unref-d-timer-cannot-be-awaited-under-node-test]], the other
+source of nondeterminism found in the same pass.

package/knowledge/decisions/internals/a-workflow-wire-is-built-from-the-run-not-from-the-rpc-service.md

@@ -0,0 +1,45 @@
+---
+type: decision
+title: A workflow's wire is built from the run record, not from the RPC service
+description: The RPC service exposes no wire, so every rpcService.wire read was undefined; the run record is the only thing that carries the caller across a step boundary
+tags: core, workflow
+---
+
+# A workflow's wire is built from the run record, not from the RPC service
+
+`PikkuWorkflowService` builds a fresh wire each time it runs a workflow body or
+starts a child. For a while it filled parts of that wire from the RPC service it
+had been handed:
+
+```ts
+session: rpcService?.wire?.session,
+rpc: rpcService?.wire?.rpc,
+pikkuUserId: rpcService.wire?.pikkuUserId,
+```
+
+`PikkuRPC` has no `wire`. Neither does the object `getContextRPCService`
+actually returns — `ContextAwareRPCService` holds its wire *privately* and
+exposes `invoke`, `remote`, `exposed`, `startWorkflow`, `agent` and
+`rpcWithWire`, and nothing else. Every one of those reads was `undefined`, and
+the `rpcService: any` parameter type is what kept the compiler quiet about it.
+
+The consequence was silent and one-directional: a child workflow started from a
+step never inherited the `pikkuUserId` its parent was running as, so a queued
+child ran as nobody. Nothing failed — the field was simply absent, and the run
+proceeded.
+
+**The run record is the carrier.** `WorkflowRun.wire` is durable, is written
+when the run is created, and survives the process boundary a queued step
+crosses, which is exactly what a live service reference cannot do. Both the
+run-body wire and the child-run wire now read `run.wire?.pikkuUserId`.
+
+`session` and `rpc` are not copied at all. `runPikkuFunc` attaches `rpc` lazily
+for the duration of an invocation and restores the previous descriptor
+afterwards, and it resolves the session from the session store using
+`pikkuUserId` — so both were being overwritten moments later anyway. The wire
+these paths construct is a `PikkuRawWire` for that reason: it genuinely has no
+`rpc` yet, and saying so is what let the dead reads be found.
+
+**What this rules out:** reaching for the RPC service to answer "who is this
+running as". It cannot answer, and the shape of the question hides that.
+Anything a step needs to know about its caller has to be on the run.

package/knowledge/decisions/internals/agent-context-waits-for-a-tool-result-still-being-written.md

@@ -0,0 +1,21 @@
+---
+type: decision
+title: Loading agent context waits for a tool result that may still be landing
+description: An interrupted run's tool can still be writing to the thread, and in voice the next turn arrives within seconds — soon enough to load context missing what it is about to be asked about
+tags: core, ai-agent
+---
+
+# Loading agent context waits for a tool result that may still be landing
+
+Before a turn loads its thread, it settles any tool whose run was interrupted
+but whose result is still being written to that thread.
+
+The window is small and, on a typed interface, usually irrelevant — a person
+takes seconds to write the next message. In voice it is not: the next turn lands
+within a second or two of the last one. Without the wait, the model loads a
+thread that is missing the very result the user is about to ask about, and
+answers as though the tool never ran.
+
+**What this rules out:** treating the settle as belt-and-braces and dropping it
+to save a round trip. The failure it prevents is a confidently wrong answer, not
+an error, and it only appears on the fastest transport.

package/knowledge/decisions/internals/agent-speech-travels-as-a-custom-agui-event.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: Agent speech travels as a CUSTOM AG-UI event rather than being dropped
+description: AG-UI has no speech event, and dropping it makes a voice agent reached over HTTP silently inaudible while the provider still bills for the audio
+tags: core, ai-agent
+---
+
+# Agent speech travels as a CUSTOM AG-UI event
+
+The AG-UI protocol has no event type for synthesized speech, so the bridge
+forwards it as `CUSTOM`, the same way it forwards the other pikku-specific
+events.
+
+The alternative was tried: the mapper dropped the event, on the reasoning that a
+protocol without a speech event has no way to carry one. The result is a voice
+agent reached over HTTP that is completely silent — `voiceOutput` synthesizes
+every sentence, the provider bills for every one of them, and none of it gets
+past the mapper. Nothing errors, so there is nothing to find.
+
+**What this rules out:** filtering unknown event types at the AG-UI boundary as
+a tidiness measure. `CUSTOM` exists precisely so a protocol gap degrades to
+"the client ignores it" rather than "the server threw the work away".

package/knowledge/decisions/internals/an-agent-interrupt-is-not-a-failure.md

@@ -0,0 +1,23 @@
+---
+type: decision
+title: An interrupt is not a failure, and the non-streaming path throws rather than returning
+description: It skips the onError hooks and never becomes an errorMessage; with no partial reply to hand back, a typed throw is what distinguishes it from a provider outage
+tags: core, ai-agent
+---
+
+# An interrupt is not a failure
+
+Interrupting a run skips the `onError` hooks entirely and never becomes an
+`errorMessage`. Someone asked the agent to stop and it stopped; that is the
+feature working, and running failure handlers over it would report an incident
+that did not happen.
+
+The streaming and non-streaming paths then diverge, because what they can hand
+back differs. A stream has already delivered part of the reply, so it returns
+that fragment. `runAIAgent` has delivered nothing — there is no partial answer to
+return — so it throws a typed error instead. A caller can tell that apart from a
+provider outage, which returning an empty result would not allow.
+
+**What this rules out:** unifying the two paths on "return whatever you have".
+For the non-streaming path that is an empty string, and an empty string is
+indistinguishable from a model that answered with nothing.

package/knowledge/decisions/internals/an-agent-run-owned-by-another-instance-says-so.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: An interrupt for a run owned by another instance says so, rather than returning false
+description: A bare false is indistinguishable from "already finished", which is the one deployment shape the in-process registry cannot cover
+tags: core, ai-agent
+---
+
+# An interrupt for a run owned by another instance says so
+
+`interruptAIAgent` resolves a run through `aiRunState`, then tries to abort it
+via the in-process registry. A run still marked `running` that this process has
+no abort handle for is executing on another instance.
+
+Returning a bare `false` there is indistinguishable from "the run already
+finished" — the ordinary, uninteresting outcome. So the single deployment shape
+the in-process registry does not cover, multi-instance, fails silently: an agent
+that will not stop talking, and nothing in the logs to say why. The call reports
+the condition instead.
+
+**What this rules out:** collapsing the two outcomes into one boolean because
+the caller "only cares whether it stopped". The caller cares a great deal about
+the difference between *stopped* and *cannot be stopped from here*.
+
+The fix for the underlying gap is `signalRunInterrupt`, which fans the interrupt
+out over `eventHub` so every instance tries locally.

package/knowledge/decisions/internals/an-agent-stream-send-must-return-the-inner-sends-promise.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: A wrapped agent-stream send must return the inner send's promise
+description: Middleware runs asynchronously, so dropping the returned promise turns every awaited channel.send upstream into a no-op
+tags: core, ai-agent
+---
+
+# A wrapped agent-stream send must return the inner send's promise
+
+`streamAIAgent` wraps the caller's channel so every event passes through the
+stream middleware. That wrapper's `send` returns whatever the inner `send`
+returns, and it must: the middleware chain is asynchronous, so a wrapper that
+calls the inner `send` and returns `undefined` resolves immediately while the
+event is still in flight.
+
+Every `await channel.send(...)` upstream then becomes a no-op that resolves
+before the thing it is waiting for has happened. The one that matters is the
+final flush — a buffering hook such as `voiceOutput` is still synthesizing audio
+when the awaited send resolves, and the `close()` that follows discards it.
+
+**What this rules out:** writing the wrapper as a fire-and-forget `(msg) => {
+inner.send(msg) }`, which reads as equivalent and is not.

package/knowledge/decisions/internals/an-empty-text-part-is-omitted-from-an-agent-message.md

@@ -0,0 +1,20 @@
+---
+type: decision
+title: A message with nothing to say carries no text part at all
+description: An attachment on its own is a real turn, and providers are entitled to reject an empty text part sitting beside it
+tags: core, ai-agent
+---
+
+# A message with nothing to say carries no text part
+
+When a turn has no text, the text part is omitted rather than included as an
+empty string.
+
+An attachment on its own is a legitimate turn — a spoken one carries audio and
+no text whatsoever — so "no text" is a normal state, not a degenerate one.
+Providers are entitled to reject a message part with empty content, and that
+rejection would land on a caller who never wrote any text to begin with.
+
+**What this rules out:** normalising the text to `''` for a uniform message
+shape. Uniformity here buys nothing and costs a provider error on the one turn
+type that most needs to work.

package/knowledge/decisions/internals/an-empty-transcript-is-not-recorded.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: A transcript is recorded only when something was actually heard
+description: Recording an empty string sends a transcript event saying the user said nothing, which renders as an empty bubble rather than a pending one
+tags: core, ai-agent
+---
+
+# A transcript is recorded only when something was actually heard
+
+A turn can carry audio that reads entirely as non-speech and still have content
+— an image with a silent caption clip — so there is nothing above to throw.
+`voiceInput` records the transcript only when speech was found.
+
+Writing `''` instead would emit a transcript event asserting that the user said
+nothing. A client that distinguishes "not transcribed yet" from "transcribed"
+by whether the key is present would then render that turn as a permanently
+empty bubble rather than a pending one — a worse outcome than showing nothing,
+because it looks settled.
+
+**What this rules out:** defaulting the transcript to an empty string for a
+uniform event shape. Absence and emptiness mean different things to the client,
+and only absence is recoverable.