@pikku/core 0.12.83 → 0.12.84

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

@@ -2,26 +2,26 @@
 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: ai-agent
+tags: agent
 ---
 
 # The AG-UI bridge obeys the client's event-ordering contract exactly
 
-`wrapChannelWithAGUI` in `packages/core/src/wirings/ai-agent/ai-agent-agui.ts`
+`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
-`AIRunStateService` run id only exists after the channel has been wrapped, which
-is why `AGUIChannelOptions.getRunId` and `StreamAIAgentOptions.onRunCreated`
+`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. `ai-agent-agui.test.ts` re-implements those ordering rules so
+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

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

@@ -2,12 +2,12 @@
 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: ai-agent
+tags: agent
 ---
 
 # Audio chunks are labelled with the format the provider actually returned
 
-`synthesizeAudio` in `packages/core/src/wirings/ai-agent/voice-output.ts` labels
+`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`.
 

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

@@ -2,7 +2,7 @@
 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
+tags: core, agent
 ---
 
 # Loading agent context waits for a tool result that may still be landing

package/knowledge/decisions/internals/{ai-agent-credential-suspensions-hide-the-tool-result.md → agent-credential-suspensions-hide-the-tool-result.md}

@@ -2,13 +2,13 @@
 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: ai-agent
+tags: agent
 ---
 
 # A credential-required tool result never reaches the client or the transcript
 
 When a tool returns the `__credentialRequired` marker,
-`streamAIAgent` in `packages/core/src/wirings/ai-agent/ai-agent-stream.ts`
+`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

package/knowledge/decisions/internals/{ai-agent-delegate-and-supervise-hide-different-text.md → agent-delegate-and-supervise-hide-different-text.md}

@@ -2,18 +2,18 @@
 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: ai-agent
+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 `streamAIAgent` in `ai-agent-stream.ts`) the parent's `text-delta` and
-`reasoning-delta` events are suppressed *after* the first sub-agent call —
+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 `ai-agent-prepare.ts`) the inverse holds: the sub-agent's text
+`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,

package/knowledge/decisions/internals/{ai-agent-llm-tool-arguments-have-nulls-stripped.md → agent-llm-tool-arguments-have-nulls-stripped.md}

@@ -2,13 +2,13 @@
 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: ai-agent
+tags: agent
 ---
 
 # Nulls are stripped from approved tool arguments before execution
 
-`resumeAIAgentSync` in
-`packages/core/src/wirings/ai-agent/ai-agent-runner.ts` runs `stripNulls` over
+`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

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

@@ -2,13 +2,13 @@
 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: ai-agent
+tags: agent
 ---
 
 # Model resolution stays a single seam even though it is currently a passthrough
 
 `resolveModelConfig` in
-`packages/core/src/wirings/ai-agent/ai-agent-model-config.ts` returns the
+`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.
 
@@ -16,7 +16,7 @@ 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 `ai-agent-prepare.ts` — assembles the
+`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.
 

package/knowledge/decisions/internals/{ai-agent-onerror-hooks-cannot-change-the-failure.md → agent-onerror-hooks-cannot-change-the-failure.md}

@@ -1,15 +1,15 @@
 ---
 type: decision
-title: An aiMiddleware onError hook cannot change how a run fails
+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: ai-agent
+tags: agent
 ---
 
-# An aiMiddleware onError hook cannot change how a run fails
+# An agentMiddleware onError hook cannot change how a run fails
 
-Every `onError` invocation on the agent failure paths — in `streamAIAgent` and
-`continueAfterToolResult` (`ai-agent-stream.ts`) and in `runAIAgent` and
-`continueAfterToolResultSync` (`ai-agent-runner.ts`) — is wrapped in its own
+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.
 

package/knowledge/decisions/internals/{ai-agent-runner-methods-must-keep-their-receiver.md → agent-runner-methods-must-keep-their-receiver.md}

@@ -2,18 +2,18 @@
 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: ai-agent
+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
-`aiAgentRunner.transcribe(...)` and `aiAgentRunner.generateSpeech?.(...)` as
+`agentRunner.transcribe(...)` and `agentRunner.generateSpeech?.(...)` as
 method calls on the service object, and only ever test them for presence.
 
-`AIAgentRunnerService` is an interface implemented by classes — the reference
+`AgentRunnerService` is an interface implemented by classes — the reference
 implementation's `transcribe` calls `this.getModel(...)`. Extracting the method
-into a local (`const { transcribe } = services.aiAgentRunner`) type-checks
+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`.

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

@@ -2,7 +2,7 @@
 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
+tags: core, agent
 ---
 
 # Agent speech travels as a CUSTOM AG-UI event

package/knowledge/decisions/internals/{ai-agent-stream-persistence-is-best-effort.md → agent-stream-persistence-is-best-effort.md}

@@ -2,15 +2,15 @@
 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: ai-agent
+tags: agent
 ---
 
 # Persisting an agent stream from send is best-effort and must never reject
 
 `createPersistingChannel` in
-`packages/core/src/wirings/ai-agent/ai-agent-stream.ts` accumulates step text,
+`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. `AIStreamChannel.send` is synchronous, so it cannot await the
+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
@@ -18,7 +18,7 @@ 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 `ai-agent-stream.test.ts`; because the
+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.
 

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

@@ -2,14 +2,14 @@
 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: ai-agent
+tags: agent
 ---
 
 # A delegated sub-agent inherits the parent run's context block
 
 `buildSubAgentRunInput` in
-`packages/core/src/wirings/ai-agent/ai-agent-prepare.ts` forwards the parent
-run's `AIAgentInput.context` — the "Current context" identifier block with
+`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.

package/knowledge/decisions/internals/{ai-agent-tool-execute-failures-are-logged-unconditionally.md → agent-tool-execute-failures-are-logged-unconditionally.md}

@@ -2,12 +2,12 @@
 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: ai-agent
+tags: agent
 ---
 
 # A tool's execute() failure is logged before the AI SDK swallows it
 
-`buildToolDefs` in `packages/core/src/wirings/ai-agent/ai-agent-prepare.ts`
+`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.
@@ -18,7 +18,7 @@ and turns it into a conversational "tool error" reply to the model. The exceptio
 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
-`aiMiddleware` `afterToolCall` hook happens to be registered.
+`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

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

@@ -2,13 +2,13 @@
 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: ai-agent
+tags: agent
 ---
 
 # Voice input transcribes audio parts sequentially and in place
 
 The `voiceInput` middleware in
-`packages/core/src/wirings/ai-agent/voice-input.ts` walks the last user
+`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.
 

package/knowledge/decisions/internals/{ai-agent-working-memory-is-persisted-only-when-valid.md → agent-working-memory-is-persisted-only-when-valid.md}

@@ -2,13 +2,13 @@
 type: decision
 title: Working memory is persisted only when the merged value validates
 description: A failed schema check logs and drops the update rather than saving it, because invalid state poisons every later read
-tags: ai-agent
+tags: agent
 ---
 
 # Working memory is persisted only when the merged value validates
 
 `createWorkingMemoryMiddleware` in
-`packages/core/src/wirings/ai-agent/ai-agent-memory.ts` parses the model's
+`packages/core/src/wirings/agent/agent-memory.ts` parses the model's
 `<working_memory>` block, deep-merges it into the stored value, validates the
 merge against the agent's working-memory schema when one is declared, and calls
 `saveWorkingMemory` only if the merge is valid. An invalid merge is logged as a

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

@@ -2,7 +2,7 @@
 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
+tags: core, agent
 ---
 
 # An interrupt is not a failure
@@ -14,7 +14,7 @@ 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
+that fragment. `runAgent` 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.
 

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

@@ -2,12 +2,12 @@
 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
+tags: core, agent
 ---
 
 # An interrupt for a run owned by another instance says so
 
-`interruptAIAgent` resolves a run through `aiRunState`, then tries to abort it
+`interruptAgent` resolves a run through `agentRunState`, 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.
 
@@ -19,7 +19,7 @@ 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 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

@@ -2,12 +2,12 @@
 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
+tags: core, 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
+`streamAgent` 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

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

@@ -2,7 +2,7 @@
 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
+tags: core, agent
 ---
 
 # A message with nothing to say carries no text part

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

@@ -2,7 +2,7 @@
 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
+tags: core, agent
 ---
 
 # A transcript is recorded only when something was actually heard

package/knowledge/decisions/internals/speech-synthesis-picks-a-voice-per-sentence-and-warns-once.md

@@ -2,7 +2,7 @@
 type: decision
 title: Speech synthesis picks a voice per sentence but announces a limitation once
 description: A bilingual reply should speak the half it can, and repeating the notice for every sentence would bury the reply itself
-tags: core, ai-agent
+tags: core, agent
 ---
 
 # Speech synthesis picks a voice per sentence, and warns once per reply

package/knowledge/decisions/internals/the-agent-done-event-goes-through-the-middleware-and-is-awaited.md

@@ -2,7 +2,7 @@
 type: decision
 title: The agent `done` event goes through the middleware and is awaited
 description: `done` is the only end-of-reply signal a stream hook gets, and buffering hooks flush on it — sending it raw discards work already paid for
-tags: core, ai-agent
+tags: core, agent
 ---
 
 # The agent `done` event goes through the middleware and is awaited

package/knowledge/decisions/internals/the-embedding-model-is-pinned-per-service-and-doc-query-embedding-is-split.md

@@ -24,6 +24,6 @@ same call.
 
 **What this rules out:** adding a per-call `model` parameter, collapsing
 `embedDocuments` and `embedQuery` into one `embed`, and pointing a vector store
-at `AIAgentRunnerService.embed` / `embedMany` instead — those take a per-call
+at `AgentRunnerService.embed` / `embedMany` instead — those take a per-call
 model on purpose and drag in the whole agent-runner tool loop, and they give back
 neither guarantee.

package/knowledge/decisions/internals/the-per-invocation-rpc-view-is-a-class.md

@@ -11,16 +11,16 @@ tags: core, rpc, performance
 an object literal, and that literal declared `get agent()` so the agent facade
 stayed lazy — most requests never touch it, and reading it builds five closures.
 
-The laziness is right. Declaring the accessor *on the literal* was not: a
+The laziness is right. Declaring the accessor _on the literal_ was not: a
 literal containing an accessor needs a real property descriptor per instance,
 which takes it off V8's fast object-literal construction path and slows the
 whole object, not just the accessor.
 
 Measured with `benchmarks/bench-profile-granular.ts`, three runs each:
 
-| shape | per call |
-| --- | --- |
-| object literal with `get agent()` | 1.106 / 1.433 / 1.147 µs |
+| shape                               | per call                 |
+| ----------------------------------- | ------------------------ |
+| object literal with `get agent()`   | 1.106 / 1.433 / 1.147 µs |
 | class with `agent` on the prototype | 0.523 / 0.461 / 0.525 µs |
 
 Roughly 2.4×, well outside the run-to-run variance, on a path every request
@@ -28,7 +28,7 @@ takes. On the same machine a full `fetchData` measures 12–19µs, so this was o
 the order of a tenth of a request spent constructing one object.
 
 The obvious alternative is worse. Making `agent` an eager property removes the
-accessor but builds those five closures unconditionally, and measured *slower*
+accessor but builds those five closures unconditionally, and measured _slower_
 than the original at 1.967µs. A prototype accessor is the only shape that keeps
 the laziness and the fast construction path.
 

package/knowledge/decisions/internals/the-transcript-event-is-sent-ahead-of-the-run.md

@@ -2,7 +2,7 @@
 type: decision
 title: A voice turn's transcript is sent before the run starts, on the raw channel
 description: The client does not know what it said, and an answer starts streaming within a few hundred milliseconds — a question arriving after its answer reads as the wrong question
-tags: core, ai-agent
+tags: core, agent
 ---
 
 # A voice turn's transcript is sent ahead of the run
@@ -10,7 +10,7 @@ tags: core, ai-agent
 A voice client sends audio, so it does not know what it said. Until the
 transcript reaches it, its own message renders as a blank bubble.
 
-The event is sent *before* the run rather than alongside it because the answer
+The event is sent _before_ the run rather than alongside it because the answer
 begins streaming within a few hundred milliseconds. Sent concurrently, the
 transcript routinely lands after the first tokens of its own answer — and a
 question that appears beneath its answer reads as a question about something

package/knowledge/decisions/internals/thread-history-records-the-transcript-not-the-audio.md

@@ -2,7 +2,7 @@
 type: decision
 title: Thread history records what the model was asked, which for a spoken turn is the transcript
 description: The wire carried a base64 audio blob; persisting it writes megabytes of unreadable data and loses the only readable record of the turn
-tags: core, ai-agent
+tags: core, agent
 ---
 
 # Thread history records the transcript, not the audio that arrived
@@ -13,7 +13,7 @@ carried a base64 audio blob, and `voiceInput` replaced it with a transcript
 before the model ever saw it.
 
 Persisting the blob would write megabytes of unreadable data into the history
-*and* discard the only readable record of what was said — the worst of both.
+_and_ discard the only readable record of what was said — the worst of both.
 
 Both the streaming and non-streaming paths do this, and both check identity
 rather than assuming: a middleware is free to rewrite the message list into

package/knowledge/decisions/internals/voice-output-speaks-unless-voice-input-explicitly-says-otherwise.md

@@ -2,7 +2,7 @@
 type: decision
 title: Only an explicit `false` silences a spoken reply
 description: The key being absent means no voice input is wired and nothing reported either way, so those callers keep the behaviour they had before the option existed
-tags: core, ai-agent
+tags: core, agent
 ---
 
 # Only an explicit `false` silences a spoken reply

package/knowledge/decisions/security/{ai-agent-approval-forwarding-requires-a-symbol-brand.md → agent-approval-forwarding-requires-a-symbol-brand.md}

@@ -2,16 +2,16 @@
 type: decision
 title: Only a Symbol-branded framework result can request tool approval
 description: Approval markers are trusted from the APPROVAL_REQUIRED Symbol on a forwardsApproval tool, never from a JSON key an LLM could emit
-tags: ai-agent
+tags: agent
 ---
 
 # Only a Symbol-branded framework result can request tool approval
 
 `checkForApprovals` in
-`packages/core/src/wirings/ai-agent/ai-agent-stream.ts` honours a forwarded
+`packages/core/src/wirings/agent/agent-stream.ts` honours a forwarded
 approval only when both hold: the tool declares `forwardsApproval` (set solely by
 framework code on the sub-agent delegating tools built in
-`ai-agent-prepare.ts`), and its result carries the `APPROVAL_REQUIRED` unique
+`agent-prepare.ts`), and its result carries the `APPROVAL_REQUIRED` unique
 Symbol. The companion `__approvalRequired` string key exists for transport, but
 is never what the decision reads.
 

package/knowledge/decisions/security/{ai-agent-credential-requests-are-symbol-branded.md → agent-credential-requests-are-symbol-branded.md}

@@ -2,14 +2,14 @@
 type: decision
 title: Credential requests are trusted only when Symbol-branded
 description: The string key is a wire field; the Symbol is the capability, and only core can mint it
-tags: ai-agent
+tags: agent
 ---
 
 # Credential requests are trusted only when Symbol-branded
 
 A tool result asking the run to suspend and prompt for a credential is honoured
 only when it carries the `CREDENTIAL_REQUIRED` Symbol minted in
-`ai-agent-prepare.ts`. `checkForCredentialRequests` in `ai-agent-stream.ts`
+`agent-prepare.ts`. `checkForCredentialRequests` in `agent-stream.ts`
 tests for that Symbol, never for the `__credentialRequired` string key that
 travels beside it on the wire.
 
@@ -24,7 +24,7 @@ primitive inside the product's own UI. This mirrors the `APPROVAL_REQUIRED`
 brand, which exists for the identical reason one function over.
 
 The brand survives because the object is passed by reference the whole way —
-core's `buildToolDefs` wrapper returns it, the Vercel adapter's `aiTool` hands
+core's `buildToolDefs` wrapper returns it, the Vercel adapter's `agentTool` hands
 it back verbatim, and the AI SDK puts the raw value on the stream part rather
 than the JSON form it builds separately for the model.
 
@@ -33,5 +33,5 @@ result` for convenience, or introducing any path where a credential request is
 reconstructed from parsed JSON rather than passed by reference — either one
 silently converts the gate into a formality. Note the inverse holds for the
 `credentialFilteredChannel` suppression later in the same file: that one
-deliberately matches the *string* key, because it hides tool results from the
+deliberately matches the _string_ key, because it hides tool results from the
 client and a broader match leaks less, not more.

package/knowledge/decisions/security/{ai-agent-gate-requires-a-session-only-when-auth-is-true.md → agent-gate-requires-a-session-only-when-auth-is-true.md}

@@ -2,14 +2,14 @@
 type: decision
 title: An agent requires a session only when auth is true, but always enforces scopes and permissions
 description: Agents follow pikkuSessionlessFunc semantics so crons and queue workers can run them; scopes are an AND gate checked before any permission I/O
-tags: ai-agent
+tags: agent
 ---
 
 # An agent requires a session only when auth is true, but always enforces scopes and permissions
 
 `assertAgentAuthorized` in
-`packages/core/src/wirings/ai-agent/ai-agent-prepare.ts` enforces, in order:
-session presence (only when `CoreAIAgent.auth === true`), then `scopes`, then
+`packages/core/src/wirings/agent/agent-prepare.ts` enforces, in order:
+session presence (only when `CoreAgent.auth === true`), then `scopes`, then
 `permissions`. The ordering mirrors the function runner — scopes AND together so
 they can only narrow access, and a missing scope short-circuits before any
 permission function does I/O. Declared `scopes` are narrowed to the generated

package/knowledge/decisions/security/{ai-agent-ownership-failures-never-echo-the-resource.md → agent-ownership-failures-never-echo-the-resource.md}

@@ -2,13 +2,13 @@
 type: decision
 title: An agent ownership failure never echoes the resource it refused
 description: assertResourceOwner throws a bare ForbiddenError so the error cannot be used as an existence oracle, at the cost of thinner debugging output
-tags: ai-agent
+tags: agent
 ---
 
 # An agent ownership failure never echoes the resource it refused
 
 `assertResourceOwner` in
-`packages/core/src/wirings/ai-agent/ai-agent-prepare.ts` compares a stored
+`packages/core/src/wirings/agent/agent-prepare.ts` compares a stored
 thread/run `resourceId` against the caller's composed owner key and throws
 `ForbiddenError('Not authorized to access this thread' | '… run')` on a
 mismatch. The message deliberately carries no id.

package/knowledge/decisions/security/{ai-agent-resume-re-runs-the-authorization-gate.md → agent-resume-re-runs-the-authorization-gate.md}

@@ -2,14 +2,14 @@
 type: decision
 title: Resuming a suspended agent run re-runs the agent's authorization gate
 description: Ownership of the run is not enough — a grant revoked while the run was suspended must block the approval
-tags: ai-agent
+tags: agent
 ---
 
 # Resuming a suspended agent run re-runs the agent's authorization gate
 
-Both `resumeAIAgent` (`ai-agent-stream.ts`) and `resumeAIAgentSync`
-(`ai-agent-runner.ts`) call `assertAgentAuthorized` after asserting run
-ownership and before touching `aiRunState.resolveApproval`.
+Both `resumeAgent` (`agent-stream.ts`) and `resumeAgentSync`
+(`agent-runner.ts`) call `assertAgentAuthorized` after asserting run
+ownership and before touching `agentRunState.resolveApproval`.
 
 Ownership proves the run belongs to the caller, not that the caller may still
 act on it: a suspension can outlive the permission that created it, and the whole