@pikku/core 0.12.143 → 0.12.144

package/knowledge/decisions/internals/a-virtual-user-run-is-not-a-workflow-but-it-needs-a-trigger.md

@@ -1,65 +0,0 @@
----
-type: decision
-title: A virtual user run is not a workflow, but it needs a trigger
-description: runVirtualUser writes its record and dispatches the run onto a queue at one attempt — an exploratory run has nothing to replay, but a deployment that puts each function in its own unit has nothing to fire it either
-tags: virtual-user, storage, deploy
----
-
-# A virtual user run is not a workflow, but it needs a trigger
-
-`runVirtualUser` — the RPC `scaffold.virtualUser` generates — does three things
-in order: writes a `VirtualUserRunStore` record, dispatches
-`executeVirtualUserRun`, and returns the `runId`. The request never waits for
-the run; a run takes minutes and survives neither a rollout nor a proxy timeout.
-
-**A workflow** is still the wrong shape, for the reason it always was. Its value
-is that a run can be resumed at the step it died on, and that the same input
-reaches the same step. A virtual user is the opposite by construction — it is an
-LLM deciding what to try next, so no two attempts take the same steps, and there
-is no step to resume _to_. Recording a run as a workflow puts entries in the
-workflow store that can never be replayed, and gives every operator reading that
-store a row that lies about what it is. The seed makes a run _reproducible_ —
-run it again and it explores the same way — which is a different property from
-resumable, and one the record already carries.
-
-**A queue was rejected once, on durability, and that was the wrong question.**
-The original reasoning weighed a broker dependency against a retry nobody wants,
-and concluded the in-process dispatch was enough. It is enough in one process.
-It is not a dispatch at all under a deployment that puts each function in its own
-unit: there is no in-process promise to leave running, and `executeVirtualUserRun`
-— sessionless, unexposed, wired to nothing — is not a function any unit can be
-reached at. The RPC resolves to nothing, the rejection is swallowed by the
-`catch` that exists to stop it taking the process down, and the run parks at
-`running` with zero steps and no error anywhere. That is what a cloud stage did.
-
-So the queue is not bought for durability. It is bought because **a trigger is
-what makes a function deployable**: `wireQueueWorker` puts `executeVirtualUserRun`
-in the manifest, which gives it a unit and gives the platform somewhere to
-deliver to. The job is dispatched at `attempts: 1`, because a redelivery is a
-second different outing writing into a record that already has an outcome — the
-retry the queue offers is precisely the part that stays unused.
-
-A project with no queue service keeps the in-process dispatch. That is not a
-fallback that hides a failure: a project without a broker runs in one process,
-where an unawaited promise is a real dispatch and the only correct one.
-
-The record remains the run's only trace, and that is what `VirtualUserRunStore`
-exists for. It is also why `fail()` is a method rather than an absence: a run
-that crashed and a run that found nothing are different answers, and a record
-left at `running` is neither.
-
-The cost is smaller than it was but has not gone: **a restart mid-run strands a
-record at `running` with nothing left to finish it**, since nothing retries. A
-run older than its budget window and still `running` is dead, not working — a
-read-side rule. A stranded run is started again, with its seed if the caller
-wants the same exploration.
-
-Where that rule is actually applied is
-[the schedule tick](a-virtual-user-cadence-is-a-row-not-a-timer.md), which has
-to: a record stuck at `running` would otherwise block its virtual user's cadence
-forever.
-
-**What this rules out:** dispatching the run through `startWorkflow`; awaiting
-the engine inside the request; retrying a run that failed; storing the operator
-token on the record rather than on the dispatch; and inferring `status` from
-`finishedAt` being unset, which cannot separate a crash from a run still going.

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

@@ -1,49 +0,0 @@
----
-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.
-
-Where the cause is observable, prefer asserting it outright:
-[[a-latency-budget-is-asserted-by-its-cause]].

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

@@ -1,45 +0,0 @@
----
-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/addon-package-roots-resolve-by-walking-node-module-search-paths.md

@@ -1,26 +0,0 @@
----
-type: decision
-title: Addon package roots resolve by walking node module search paths
-description: LocalMetaService finds an addon's directory by scanning resolve.paths, not by require.resolve, because addon packages expose no main entry
-tags: services
----
-
-# Addon package roots resolve by walking node module search paths
-
-`LocalMetaService.resolvePackageRoot` (`packages/core/src/services/meta-service.ts`)
-builds a `createRequire` anchored one level above `.pikku` — the app root — then
-walks `require.resolve.paths(packageName)` and takes the first candidate
-directory that contains a `package.json`. The result is memoised in
-`packageRootCache`.
-
-The obvious call, `require.resolve(packageName)`, throws for these packages:
-Pikku addon packages ship a `.pikku` directory and subpath exports but no main
-`exports` entry, so there is nothing for Node to resolve to. Walking the search
-paths asks the same question Node would ask — where would this package be
-found from the app root — without requiring the package to be importable.
-
-**What this rules out:** replacing the loop with `require.resolve(pkg)`,
-`import.meta.resolve`, or `createRequire(import.meta.url)`. The first two fail on
-every addon; the third anchors resolution at `@pikku/core`'s own location rather
-than the app's, so an addon installed only in the app's `node_modules` becomes
-invisible.

package/knowledge/decisions/internals/addon-pikku-meta-ships-at-the-package-root-or-under-dist.md

@@ -1,32 +0,0 @@
----
-type: decision
-title: An addon's .pikku meta ships at the package root or under dist, and readers probe both
-description: The layout depends on the addon's build and files field, so a consumer resolving the directory by path must try `<pkg>/.pikku` and `<pkg>/dist/.pikku` before concluding an addon declares nothing
-tags: services
----
-
-# An addon's .pikku meta ships at the package root or under dist, and readers probe both
-
-An addon generates `.pikku/` at its project root, and whether that directory
-reaches the published tarball at the root or inside `dist/` depends on the
-addon's own `tsconfig` and `files` — both layouts are in the wild and both are
-supported. The published `exports` map hides the difference for anyone
-resolving by specifier: `"./.pikku/*"` points at wherever it landed, so
-`require.resolve('<pkg>/.pikku/scopes/pikku-scopes-meta.gen.json')` works for
-either shape, and that is the resolution every consumer should prefer.
-
-Code that builds the path itself must probe both. `addonPikkuDir`
-(`packages/addon/pikku-console/src/lib/derive-instance-overrides.ts`) tries
-`<pkg>/.pikku` then `<pkg>/dist/.pikku` and returns `null` when neither exists.
-The reason to say so out loud is the failure mode: a reader that assumes the
-root finds nothing under a `dist`-shipping addon and cannot distinguish that
-from an addon that declares no secrets, variables or scopes at all. Both answers
-are "empty", and the wrong one is indistinguishable from a correct one until
-something downstream reports an addon as ready when its secrets were never
-checked.
-
-**What this rules out:** hardcoding either path in a consumer, and treating a
-missing directory as evidence an addon declares nothing without having tried
-both. It also rules out normalising the layout by making the CLI move the
-directory at publish time — the export map already makes the layout private to
-the package, and the addons shipping each shape are already published.

package/knowledge/decisions/internals/addon-singleton-services-are-cached-per-namespace-not-per-package.md

@@ -1,33 +0,0 @@
----
-type: decision
-title: Addon singleton services are cached per namespace, not per package
-description: Each wireAddon instance gets its own services built from its own overrides, at the cost of one service graph per wired instance
-tags: rpc
----
-
-# Addon singleton services are cached per namespace, not per package
-
-`getOrCreatePackageSingletonServices` in
-`packages/core/src/wirings/rpc/addon-runner.ts` keys its `pikkuState` cache on
-`addonInstance?.namespace ?? packageName`. The namespace is the consumer-facing
-name given to `wireAddon`/`wireRemoteAddon`, and it is what selects the
-instance's `secretOverrides`, `variableOverrides` and `credentialOverrides`.
-
-One package may be wired twice — the same payments addon against a live and a
-sandbox account, say — with different secret and variable names. Caching by
-package name would build the service graph once, from whichever instance called
-first, and silently hand the other instance the wrong credentials. Because the
-overrides have to be visible to the addon's _own_ `createSingletonServices`, they
-are applied by wrapping the parent `secrets` and `variables` services
-(`aliasSecretService`, `aliasVariablesService`) so that every logical name the
-addon reads is remapped to the real project name before resolution. A call with
-no instance attached still falls back to per-package caching.
-
-`addonInstanceForNamespace` rebuilds this descriptor for bare intra-addon calls
-from the namespace currently executing on the wire, and returns `undefined`
-unless that namespace maps to the package being resolved — so a bare call cannot
-pick up another instance's overrides.
-
-**What this rules out:** simplifying the cache key to `packageName`, resolving
-overrides at the call site instead of aliasing the resolver services, and
-assuming two `wireAddon` entries for one package share a service instance.

package/knowledge/decisions/internals/addon-workflow-names-are-prefixed-with-the-consumer-namespace.md

@@ -1,28 +0,0 @@
----
-type: decision
-title: Bare workflow names from inside an addon are prefixed with the consumer's namespace
-description: The addon's workflowService is proxied so an addon never has to hardcode the name its consumer chose
-tags: rpc
----
-
-# Bare workflow names from inside an addon are prefixed with the consumer's namespace
-
-`wrapWorkflowServiceForPackage` in
-`packages/core/src/wirings/rpc/addon-runner.ts` proxies an addon package's
-`workflowService`, intercepting `startWorkflow` and `runToCompletion`. A bare
-name — one with no `:` — is rewritten to `${namespace}:${name}`, using the
-instance namespace when known and otherwise the package's sole namespace via
-`findAddonNamespaceForPackage`.
-
-Workflows declared by an addon are registered under the addon's package scope,
-but the namespace they answer to is chosen by the _consumer_ in `wireAddon`.
-Without the proxy, `runToCompletion('myWorkflow')` written inside the addon
-resolves against root meta, misses, and throws `WorkflowNotFoundError` — leaving
-the addon author no option but to hardcode the consumer-defined namespace, which
-couples a reusable package to one particular caller. Explicit `'ns:name'` calls
-and bare names that already resolve in root are untouched; only bare names that
-would otherwise miss get prefixed.
-
-**What this rules out:** dropping the proxy and requiring addons to namespace
-their own workflow calls, and widening the rewrite to names that already contain
-a `:` or already exist at root — either turns a working call into a lookup miss.

package/knowledge/decisions/internals/agent-agui-bridge-obeys-the-client-ordering-contract.md

@@ -1,29 +0,0 @@
----
-type: decision
-title: The AG-UI bridge obeys the client's event-ordering contract exactly
-description: RUN_STARTED opens lazily, RUN_FINISHED fires once on done, and step names are globally sequential — a violation makes the client drop the whole stream
-tags: agent
----
-
-# The AG-UI bridge obeys the client's event-ordering contract exactly
-
-`wrapChannelWithAGUI` in `packages/core/src/wirings/agent/agent-agui.ts`
-translates pikku stream events into AG-UI events under three rules that
-`@ag-ui/client`'s `verifyEvents` enforces on the browser side:
-
-`RUN_STARTED` is emitted lazily, from the first translated event, because the
-client rejects anything that arrives before it — and because the real
-`AgentRunStateService` run id only exists after the channel has been wrapped, which
-is why `AGUIChannelOptions.getRunId` and `StreamAgentOptions.onRunCreated`
-exist as late-bound sources. `RUN_FINISHED` is terminal for the client, so it is
-sent exactly once, on `done`, carrying usage accumulated across all steps; per-step
-`usage` events must not finish the run, or a multi-step tool run would emit later
-steps after the terminal event and the client would drop the whole stream.
-Step names must be unique among active steps, and sub-agents reuse step numbers
-on the shared channel, so each `step-start` closes the previous step and takes a
-sequential name. `agent-agui.test.ts` re-implements those ordering rules so
-the bridge is checked against the same contract the browser applies.
-
-**What this rules out:** emitting `RUN_STARTED` eagerly at wrap time; finishing
-the run on the `usage` event so token counts arrive earlier; and naming AG-UI
-steps after `event.stepNumber`.

package/knowledge/decisions/internals/agent-audio-chunks-carry-the-format-the-provider-returned.md

@@ -1,20 +0,0 @@
----
-type: decision
-title: Audio chunks are labelled with the format the provider actually returned
-description: The configured format is only a request, so the response's own format wins with the request and pcm16 as fallbacks
-tags: agent
----
-
-# Audio chunks are labelled with the format the provider actually returned
-
-`synthesizeAudio` in `packages/core/src/wirings/agent/voice-output.ts` labels
-each `audio-delta` event with `result.audio.format` first, falling back to the
-requested `config.format` and finally to `pcm16`.
-
-Speech providers treat the output format as a preference: an unsupported or
-omitted value silently yields whatever the provider defaults to. Stamping the
-requested format on the chunk would tell the client to decode bytes it did not
-receive, producing noise rather than an error.
-
-**What this rules out:** labelling chunks from `config.format` because "we asked
-for it", and dropping the fallback chain to a single source.

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

@@ -1,21 +0,0 @@
----
-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, 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-credential-suspensions-hide-the-tool-result.md

@@ -1,26 +0,0 @@
----
-type: decision
-title: A credential-required tool result never reaches the client or the transcript
-description: The run suspends with credential-request events instead, leaving the tool call unresulted so it can be resumed after connecting
-tags: agent
----
-
-# A credential-required tool result never reaches the client or the transcript
-
-When a tool returns the `__credentialRequired` marker,
-`streamAgent` in `packages/core/src/wirings/agent/agent-stream.ts`
-filters that `tool-result` out of the channel before it can be streamed or
-persisted, and `handleCredentialRequests` suspends the run and emits
-`credential-request` events carrying the `runId` instead. Those events — not the
-tool result — are what tells a client to show Connect/Ignore, mirroring how
-approval suspensions work.
-
-Leaving the tool call unresulted in the persisted history is what makes the
-resume possible: once the credential is connected, `/resume` re-executes the call
-against a history that does not already contain a bogus answer. `runStreamStepLoop`
-still appends the step messages before returning the credential outcome, so the
-assistant's tool call itself survives into the resume.
-
-**What this rules out:** streaming the marker result as a normal tool result and
-filtering it client-side; persisting it as the tool's answer; and skipping
-`appendStepMessages` on the credential path because the run is about to suspend.

package/knowledge/decisions/internals/agent-delegate-and-supervise-hide-different-text.md

@@ -1,26 +0,0 @@
----
-type: decision
-title: Delegate mode hides the parent's later text, supervise mode hides the sub-agent's
-description: Exactly one voice reaches the client per agent-mode; approvals and tool events always flow through either way
-tags: agent
----
-
-# Delegate mode hides the parent's later text, supervise mode hides the sub-agent's
-
-An agent with sub-agents runs in one of two modes. In `'delegate'` (the default,
-handled in `streamAgent` in `agent-stream.ts`) the parent's `text-delta` and
-`reasoning-delta` events are suppressed _after_ the first sub-agent call —
-`delegateState.delegated` is the latch — so a parent that answers directly still
-streams normally, while a parent that hands off does not narrate over its
-sub-agent. In `'supervise'` (handled where the sub-agent channel is built in
-`buildToolDefs` in `agent-prepare.ts`) the inverse holds: the sub-agent's text
-and reasoning are dropped and only the supervisor speaks.
-
-Suppression is confined to text and reasoning. Approval requests, tool calls,
-tool results, usage and errors flow through in both modes, because a suppressed
-approval would deadlock the run.
-
-**What this rules out:** filtering sub-agent events at the transport instead of
-at the scoped channel; suppressing parent text unconditionally in delegate mode
-(direct answers would vanish); and adding new event types to either filter
-without checking they are not part of the approval handshake.

package/knowledge/decisions/internals/agent-llm-tool-arguments-have-nulls-stripped.md

@@ -1,23 +0,0 @@
----
-type: decision
-title: Nulls are stripped from approved tool arguments before execution
-description: LLMs emit null for optional fields where the schema layer expects undefined, so a resumed tool call is cleaned recursively first
-tags: agent
----
-
-# Nulls are stripped from approved tool arguments before execution
-
-`resumeAgentSync` in
-`packages/core/src/wirings/agent/agent-runner.ts` runs `stripNulls` over
-the persisted arguments of an approved tool call before invoking the tool.
-
-Models routinely fill every property in a JSON schema, using `null` to mean "not
-provided". Pikku's validation layer models an absent optional field as
-`undefined`, and a `null` fails the check outright. The value is stored as the
-model produced it — the approval prompt should show what the model actually asked
-for — so the cleanup happens at execution time, recursively, including inside
-arrays and nested objects.
-
-**What this rules out:** normalizing the arguments at approval-capture time
-(the approval UI would no longer reflect the model's real request), and a
-shallow single-level null strip.

package/knowledge/decisions/internals/agent-model-config-stays-a-single-resolution-seam.md

@@ -1,25 +0,0 @@
----
-type: decision
-title: Model resolution stays a single seam even though it is currently a passthrough
-description: resolveModelConfig looks removable but is the one merge point for per-request model overrides
-tags: agent
----
-
-# Model resolution stays a single seam even though it is currently a passthrough
-
-`resolveModelConfig` in
-`packages/core/src/wirings/agent/agent-model-config.ts` returns the
-agent's `model`, `temperature` and `maxSteps` unchanged, and ignores its
-`_agentName` argument. It reads as dead indirection and is not.
-
-Models are declared per agent in the provider-qualified `provider/model` form
-(`openai/gpt-5-mini`); there is no config-level alias map to consult, which is
-why the current body is a copy. The function exists so that every caller —
-`prepareAgentRun`, both resume paths, and the per-request `input.model` /
-`input.temperature` overrides applied in `agent-prepare.ts` — assembles the
-effective config the same way, through one place that can grow an alias map,
-per-tenant defaults or provider fallbacks without touching them.
-
-**What this rules out:** inlining `agent.model` / `agent.temperature` at the four
-call sites and deleting the function, and dropping the unused `_agentName`
-parameter from the signature.

package/knowledge/decisions/internals/agent-onerror-hooks-cannot-change-the-failure.md

@@ -1,22 +0,0 @@
----
-type: decision
-title: An agentMiddleware onError hook cannot change how a run fails
-description: Hook throws are swallowed so observability code can never convert, mask, or replace the original error
-tags: agent
----
-
-# An agentMiddleware onError hook cannot change how a run fails
-
-Every `onError` invocation on the agent failure paths — in `streamAgent` and
-`continueAfterToolResult` (`agent-stream.ts`) and in `runAgent` and
-`continueAfterToolResultSync` (`agent-runner.ts`) — is wrapped in its own
-`try/catch` that discards whatever the hook throws. The run is then marked
-`failed` with the original error message, and the original error propagates.
-
-`onError` is an observability hook: logging, metrics, alerting. A logger that is
-itself broken must not turn a diagnosable agent failure into a confusing one, and
-must not stop the remaining hooks from running or the run state from being
-updated.
-
-**What this rules out:** awaiting the hooks without a guard, and using `onError`
-as an error-transformation hook whose throw replaces the original failure.

package/knowledge/decisions/internals/agent-runner-methods-must-keep-their-receiver.md

@@ -1,22 +0,0 @@
----
-type: decision
-title: AI runner methods must be called on the runner, never as detached references
-description: Implementations use this internally, so grabbing transcribe or generateSpeech as a bare function loses the receiver and throws at runtime
-tags: agent
----
-
-# AI runner methods must be called on the runner, never as detached references
-
-The voice middlewares in `voice-input.ts` and `voice-output.ts` invoke
-`agentRunner.transcribe(...)` and `agentRunner.generateSpeech?.(...)` as
-method calls on the service object, and only ever test them for presence.
-
-`AgentRunnerService` is an interface implemented by classes — the reference
-implementation's `transcribe` calls `this.getModel(...)`. Extracting the method
-into a local (`const { transcribe } = services.agentRunner`) type-checks
-cleanly and then fails at runtime with `this` undefined. The regression is
-pinned by a runner in `voice-input.test.ts` whose `transcribe` deliberately reads
-instance state through `this`.
-
-**What this rules out:** destructuring runner methods for brevity, and passing
-`runner.transcribe` as a callback without binding it.

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

@@ -1,22 +0,0 @@
----
-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, 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/agent-stream-persistence-is-best-effort.md

@@ -1,27 +0,0 @@
----
-type: decision
-title: Persisting an agent stream from send is best-effort and must never reject
-description: The persisting channel flushes fire-and-forget because send is synchronous; a storage failure degrades the transcript instead of killing the process
-tags: agent
----
-
-# Persisting an agent stream from send is best-effort and must never reject
-
-`createPersistingChannel` in
-`packages/core/src/wirings/agent/agent-stream.ts` accumulates step text,
-tool calls and tool results, and writes them via `flushDetached` on the `usage`
-and `done` events. `AgentStreamChannel.send` is synchronous, so it cannot await the
-write. An unawaited rejection has nothing to propagate to and surfaces as an
-`unhandledRejection`, which takes the whole server process down — a model
-reusing a `toolCallId`, which is a primary key in AI storage, is enough to
-trigger it. `flushDetached` therefore catches and logs, and the run carries on.
-
-The awaited `flush()` on the suspend paths (`handleApprovals`,
-`handleCredentialRequests`) is the seam that still surfaces persistence failures
-to a caller. The regression test lives in `agent-stream.test.ts`; because the
-floating promise settles on a later macrotask, the assertion has to wait a real
-timer before checking that no `unhandledRejection` fired.
-
-**What this rules out:** letting `flushStep()` be called bare from `send`,
-rethrowing from the catch to "not hide" storage errors, and asserting on
-unhandled rejections synchronously after the last event.

package/knowledge/decisions/internals/agent-sub-agents-inherit-the-parent-context-block.md

@@ -1,26 +0,0 @@
----
-type: decision
-title: A delegated sub-agent inherits the parent run's context block
-description: The sub-agent tool schema carries only message and session, so the parent's identifier block is forwarded rather than re-typed by the model
-tags: agent
----
-
-# A delegated sub-agent inherits the parent run's context block
-
-`buildSubAgentRunInput` in
-`packages/core/src/wirings/agent/agent-prepare.ts` forwards the parent
-run's `AgentInput.context` — the "Current context" identifier block with
-organization, project and stage ids — into every delegated sub-agent run, on
-both the streaming and non-streaming paths. `buildToolDefs` threads it down as
-`parentContext` for the same reason.
-
-A sub-agent is exposed to the parent model as a tool whose input schema is only
-`{ message, session }`. Without inheritance the sub-agent never sees the
-authoritative ids and has to rely on the parent model re-typing them into
-`message`. Weaker models mangle that, and the result is schema and permission
-rejections followed by retry loops rather than a clean failure.
-
-**What this rules out:** constructing the sub-agent run input inline from
-`{ message, threadId, resourceId }`, widening the sub-agent tool schema so the
-model supplies the ids itself, and dropping `parentContext` from `buildToolDefs`
-because "nothing reads it here".

package/knowledge/decisions/internals/agent-tool-execute-failures-are-logged-unconditionally.md

@@ -1,25 +0,0 @@
----
-type: decision
-title: A tool's execute() failure is logged before the AI SDK swallows it
-description: Every agent tool is wrapped in a logging try/catch, because a thrown tool error otherwise becomes a conversational reply and is invisible server-side
-tags: agent
----
-
-# A tool's execute() failure is logged before the AI SDK swallows it
-
-`buildToolDefs` in `packages/core/src/wirings/agent/agent-prepare.ts`
-wraps every tool it builds — RPC tools, sub-agent delegations and workflow tools
-alike — in a `try/catch` that logs through `singletonServices.logger` and
-rethrows.
-
-A tool's `execute()` can throw for ordinary reasons: bad model-supplied input, an
-RPC failure, a database error. The AI SDK catches that at the tool-call boundary
-and turns it into a conversational "tool error" reply to the model. The exception
-never reaches pikku's own logger, so without this wrapper a consistently failing
-tool is undiagnosable from the server side — the only symptom is an agent that
-keeps apologising. The wrapper is applied unconditionally, not only when an
-`agentMiddleware` `afterToolCall` hook happens to be registered.
-
-**What this rules out:** folding the logging into the optional middleware
-wrapper below it, and relying on the AI SDK's own error reporting for tool
-failures.

package/knowledge/decisions/internals/agent-voice-input-transcribes-audio-parts-in-place.md

@@ -1,22 +0,0 @@
----
-type: decision
-title: Voice input transcribes audio parts sequentially and in place
-description: Each audio part is replaced by its text where it sat, one at a time, bounding concurrent downloads and preserving content order
-tags: agent
----
-
-# Voice input transcribes audio parts sequentially and in place
-
-The `voiceInput` middleware in
-`packages/core/src/wirings/agent/voice-input.ts` walks the last user
-message's content parts in order and swaps each audio part for a text part at the
-same index, awaiting one transcription before starting the next.
-
-Order matters because the surrounding text parts are the user's own framing of
-the audio; hoisting transcripts to the end would reorder the prompt. Sequencing
-matters because a message can carry many attachments: a `Promise.all` would fan
-out an unbounded number of concurrent multi-megabyte downloads and provider
-transcription calls from a single request.
-
-**What this rules out:** parallelizing the loop with `Promise.all`, and
-collecting transcripts into a separate block appended to the message.