@pikku/core 0.12.82 → 0.12.84

package/dist/wirings/rpc/wire-addon.d.ts

@@ -11,6 +11,18 @@ export type WireAddonConfig = {
     secretOverrides?: Record<string, string>;
     variableOverrides?: Record<string, string>;
     credentialOverrides?: Record<string, string>;
+    /**
+     * Secrets this instance may read on top of the ones it declared, named as the
+     * addon reads them — the scope check runs before `secretOverrides` renames
+     * them, so an overridden secret is named here by its addon-side key. Listing
+     * one in `secretOverrides` grants it too.
+     *
+     * For an addon whose secret names come off its input rather than its own
+     * source, this is how the host lends names the addon could not declare.
+     */
+    secretGrants?: string[];
+    /** Credentials this instance may read on top of the ones it declared. */
+    credentialGrants?: string[];
     /**
      * Hands this instance the whole `SecretService` instead of one scoped to the
      * secrets it declared. The value is the reason, recorded in the deploy

package/dist/wirings/rpc/wire-addon.js

@@ -16,6 +16,10 @@ export const wireAddon = (config) => {
         ...(config.credentialOverrides
             ? { credentialOverrides: config.credentialOverrides }
             : {}),
+        ...(config.secretGrants ? { secretGrants: config.secretGrants } : {}),
+        ...(config.credentialGrants
+            ? { credentialGrants: config.credentialGrants }
+            : {}),
         ...(config.globalSecrets ? { globalSecrets: config.globalSecrets } : {}),
         ...(config.globalCredentials
             ? { globalCredentials: config.globalCredentials }

package/dist/wirings/virtual-user/prepare-virtual-user-run.js

@@ -42,7 +42,7 @@ export const prepareVirtualUserRun = (input) => {
     }
     const scopes = personaScopes(input.persona, roleScopes);
     // Gated by the same scopes as the RPCs, because an agent is reached rather
-    // than declared: `CoreAIAgent.scopes` is checked against the session, so a
+    // than declared: `CoreAgent.scopes` is checked against the session, so a
     // persona finds the specialists its roles unlock and no others.
     const agents = reachableAgents(input.agentsMeta ?? {}, scopes);
     return { catalogue, intents, scopes, agents };

package/dist/wirings/virtual-user/virtual-user-agents.d.ts

@@ -2,7 +2,7 @@
  * Which of the product's agents a persona can actually talk to.
  *
  * An agent is not something a persona declares. It is something a persona
- * *reaches*, under exactly the rule an RPC is reached by: `CoreAIAgent.scopes`
+ * *reaches*, under exactly the rule an RPC is reached by: `CoreAgent.scopes`
  * is checked against the session, so a persona holding the scopes an agent
  * requires finds it in front of them, and one that does not, does not.
  *

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

@@ -1,4 +1,5 @@
-import type { CoreFeature, CoreWorkflow, FeaturePlanEntry } from './workflow.types.js';
+import type { CoreWorkflow } from './workflow.types.js';
+import type { CoreFeature, FeaturePlanEntry } from './scenario.types.js';
 export declare const addFeature: (featureId: string, feature: CoreFeature, packageName?: string | null) => void;
 export declare const resolveFeatureScenarios: (features: Map<string, CoreFeature>, registrations: Map<string, CoreWorkflow>) => {
     entries: FeaturePlanEntry[];

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

@@ -8,21 +8,10 @@ export { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js';
 export { isRef } from './graph/workflow-graph.types.js';
 export type { RefValue } from './graph/workflow-graph.types.js';
 export { buildRunTimeline, reconstructStateAt, reconstructFinalState, } from './run-timeline.js';
-export type { RunTimeline, ReconstructedRunState, } from './run-timeline.js';
+export type { RunTimeline, ReconstructedRunState } from './run-timeline.js';
 export { addWorkflow } from './dsl/workflow-runner.js';
-export { addFeature, resolveFeatureScenarios } from './feature.js';
 export { template, type TemplateString } from './graph/template.js';
 export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGraphResult, } from './graph/wire-workflow-graph.js';
 export type { WorkflowStepInput as WorkflowStepQueueInput, PikkuWorkflowOrchestratorInput, PikkuWorkflowSleeperInput, } from './workflow-queue-workers.js';
-export type { WorkflowService, WorkflowQueueOptions, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, CoreFeature, FeatureMeta, FeaturesMeta, FeaturePlanEntry, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowsRuntimeMeta, } from './workflow.types.js';
-export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, ScenarioStepInvocation, ScenarioStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './workflow.types.js';
-export type { ScenarioStepPhase, ScenarioStepKind, ScenarioStepOptions, PikkuScenarioStepWire, ScenarioEnvironment, ScenarioSurface, ScenarioSurfaceResolution, } from './scenario-step.types.js';
-export { SCENARIO_SURFACES } from './scenario-step.types.js';
-export { resolveScenarioSurfaces } from './scenario-surface.js';
-export { requireActor, requireScenarioEnv } from './scenario-step-guards.js';
-export { pollUntil, type PollOptions } from './scenario-poll.js';
-export { createCookieJar } from './scenario-cookie-jar.js';
-export type { ScenarioCookieJar } from './scenario-cookie-jar.js';
-export type { ScenarioHttpResponse, ScenarioJsonRequest, } from '../../services/personas-service.js';
-export type { PikkuBrowserWire, TestIdSelector, ScenarioBrowserProvider, ScenarioBrowserFailure, } from './scenario-step.types.js';
-export { composeStepProse, renderStepTemplate } from './scenario-prose.js';
+export type { WorkflowService, WorkflowQueueOptions, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowsRuntimeMeta, } from './workflow.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow.types.js';

package/dist/wirings/workflow/index.js

@@ -7,13 +7,5 @@ export { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js';
 export { isRef } from './graph/workflow-graph.types.js';
 export { buildRunTimeline, reconstructStateAt, reconstructFinalState, } from './run-timeline.js';
 export { addWorkflow } from './dsl/workflow-runner.js';
-export { addFeature, resolveFeatureScenarios } from './feature.js';
 export { template } from './graph/template.js';
 export { pikkuWorkflowGraph, } from './graph/wire-workflow-graph.js';
-export { SCENARIO_SURFACES } from './scenario-step.types.js';
-// Which of a step's bindings run: one for an action, every witness for a `then`
-export { resolveScenarioSurfaces } from './scenario-surface.js';
-export { requireActor, requireScenarioEnv } from './scenario-step-guards.js';
-export { pollUntil } from './scenario-poll.js';
-export { createCookieJar } from './scenario-cookie-jar.js';
-export { composeStepProse, renderStepTemplate } from './scenario-prose.js';

package/dist/wirings/workflow/pikku-scenario-service.d.ts

@@ -5,6 +5,16 @@ import type { PikkuRawWire } from '../../types/core.types.js';
 import type { ScenarioPersonas } from '../../services/personas-service.js';
 import type { ScenarioBrowserProvider, ScenarioEnvironment, ScenarioSurface } from './scenario-step.types.js';
 import type { PikkuWorkflowWire, WorkflowQueueOptions } from './workflow.types.js';
+export { addFeature, resolveFeatureScenarios } from './feature.js';
+export type * from './scenario.types.js';
+export { SCENARIO_SURFACES } from './scenario-step.types.js';
+export { resolveScenarioSurfaces } from './scenario-surface.js';
+export { pollUntil, type PollOptions } from './scenario-poll.js';
+export { createCookieJar } from './scenario-cookie-jar.js';
+export type { ScenarioCookieJar } from './scenario-cookie-jar.js';
+export { composeStepProse, renderStepTemplate } from './scenario-prose.js';
+export { requireActor, requireScenarioEnv } from './scenario-step-guards.js';
+export type { ScenarioHttpResponse, ScenarioJsonRequest, } from '../../services/personas-service.js';
 /**
  * A workflow service with the scenario capability attached — the two lines
  * `pikku scenario run` needs, in one call so no caller has to remember that the

package/dist/wirings/workflow/pikku-scenario-service.js

@@ -7,6 +7,15 @@ import { InMemoryWorkflowService } from '../../services/in-memory-workflow-servi
 import { runScheduledTask } from '../scheduler/scheduler-runner.js';
 import { WorkflowStepNameNotString } from './workflow-errors.js';
 import { resolveScenarioSurfaces, witnessesAgree } from './scenario-surface.js';
+export { addFeature, resolveFeatureScenarios } from './feature.js';
+export { SCENARIO_SURFACES } from './scenario-step.types.js';
+// Which of a step's bindings run: one for an action, every witness for a `then`
+export { resolveScenarioSurfaces } from './scenario-surface.js';
+export { pollUntil } from './scenario-poll.js';
+export { createCookieJar } from './scenario-cookie-jar.js';
+export { composeStepProse, renderStepTemplate } from './scenario-prose.js';
+export { requireActor, requireScenarioEnv } from './scenario-step-guards.js';
+// The readers themselves live on `@pikku/core/persona`
 /**
  * A workflow service with the scenario capability attached — the two lines
  * `pikku scenario run` needs, in one call so no caller has to remember that the

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

@@ -11,7 +11,7 @@ export interface RunTimelineEvent {
     error?: SerializedError;
 }
 export type RunTimeline = RunTimelineEvent[];
-type HistoryEntry = StepState & {
+export type HistoryEntry = StepState & {
     stepName: string;
 };
 export declare function buildRunTimeline(history: HistoryEntry[]): RunTimeline;
@@ -35,4 +35,3 @@ export interface ReconstructedRunState {
 }
 export declare function reconstructStateAt(timeline: RunTimeline, at: number | Date): ReconstructedRunState;
 export declare function reconstructFinalState(timeline: RunTimeline): ReconstructedRunState;
-export {};

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

@@ -0,0 +1,37 @@
+import type { CorePikkuFunctionConfig, CorePikkuFunctionHook } from '../../function/functions.types.js';
+export type { ScenarioStepInvocation, ScenarioStepMeta, PikkuScenarioWire, } from './dsl/workflow-dsl.types.js';
+export type { ScenarioStepPhase, ScenarioStepKind, ScenarioStepOptions, PikkuScenarioStepWire, ScenarioEnvironment, ScenarioSurface, ScenarioSurfaceResolution, PikkuBrowserWire, TestIdSelector, ScenarioBrowserProvider, ScenarioBrowserFailure, } from './scenario-step.types.js';
+export type CoreFeatureScenario = CorePikkuFunctionConfig<any, any, any> | {
+    scenario: CorePikkuFunctionConfig<any, any, any>;
+    data: unknown;
+};
+export type CoreFeature = {
+    name: string;
+    description?: string;
+    tags?: string[];
+    scenarios: readonly CoreFeatureScenario[];
+    before?: CorePikkuFunctionHook;
+    after?: CorePikkuFunctionHook;
+};
+export type FeatureMetaEntry = {
+    scenario: string;
+    data?: unknown;
+};
+export type FeatureMeta = {
+    id: string;
+    name: string;
+    description?: string;
+    tags: string[];
+    entries: FeatureMetaEntry[];
+    unresolvedEntries: number;
+    hasBefore: boolean;
+    hasAfter: boolean;
+};
+export type FeaturesMeta = Record<string, FeatureMeta>;
+export type FeaturePlanEntry = {
+    featureId: string;
+    featureName: string;
+    scenarioName: string;
+    data?: unknown;
+    tags: string[];
+};

package/dist/wirings/workflow/scenario.types.js

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

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

@@ -1,9 +1,8 @@
 import type { SerializedError, CommonWireMeta } from '../../types/core.types.js';
-import type { CorePikkuFunctionConfig, CorePikkuFunctionHook } from '../../function/functions.types.js';
+import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 import type { GroupConcurrencyConfig } from '../queue/queue.types.js';
 export type { WorkflowService } from '../../services/workflow-service.js';
-export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, ScenarioStepInvocation, ScenarioStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './dsl/workflow-dsl.types.js';
-export type { ScenarioStepPhase, ScenarioStepOptions, PikkuScenarioStepWire, PikkuBrowserWire, ScenarioBrowserProvider, } from './scenario-step.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './dsl/workflow-dsl.types.js';
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js';
 export interface WorkflowRunWire {
     type: string;
@@ -141,40 +140,6 @@ export type CoreWorkflow<PikkuFunctionConfig extends CorePikkuFunctionConfig<any
     middleware?: PikkuFunctionConfig['middleware'];
     tags?: string[];
 };
-export type CoreFeatureScenario = CorePikkuFunctionConfig<any, any, any> | {
-    scenario: CorePikkuFunctionConfig<any, any, any>;
-    data: unknown;
-};
-export type CoreFeature = {
-    name: string;
-    description?: string;
-    tags?: string[];
-    scenarios: readonly CoreFeatureScenario[];
-    before?: CorePikkuFunctionHook;
-    after?: CorePikkuFunctionHook;
-};
-export type FeatureMetaEntry = {
-    scenario: string;
-    data?: unknown;
-};
-export type FeatureMeta = {
-    id: string;
-    name: string;
-    description?: string;
-    tags: string[];
-    entries: FeatureMetaEntry[];
-    unresolvedEntries: number;
-    hasBefore: boolean;
-    hasAfter: boolean;
-};
-export type FeaturesMeta = Record<string, FeatureMeta>;
-export type FeaturePlanEntry = {
-    featureId: string;
-    featureName: string;
-    scenarioName: string;
-    data?: unknown;
-    tags: string[];
-};
 export interface PikkuWorkflow {
     start: <I>(input: I) => Promise<{
         runId: string;

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

@@ -1,16 +1,16 @@
 ---
 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
+title: A non-streaming agent run registers with agentRunState on the same terms as a streaming one
+description: Otherwise interruptAgent finds the run, passes the ownership check, then cannot stop it — and reports that as if the run were on another host
+tags: core, agent
 ---
 
-# A non-streaming agent run registers with `aiRunState` too
+# A non-streaming agent run registers with `agentRunState` too
 
-`runAIAgent` registers its run with `aiRunState` exactly as `streamAIAgent`
+`runAgent` registers its run with `agentRunState` exactly as `streamAgent`
 does, even though nothing is streaming and there is no channel to interrupt.
 
-`interruptAIAgent` resolves a run through `aiRunState` first, checks ownership,
+`interruptAgent` resolves a run through `agentRunState` 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

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

@@ -2,7 +2,7 @@
 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
+tags: core, agent
 ---
 
 # A resumed turn is as interruptible as the first one

package/knowledge/decisions/internals/actor-flow-drives-the-target-through-a-transport-seam.md

@@ -19,6 +19,6 @@ including middleware, permissions and session handling, rather than through an
 in-process call that skips all of it. It also lets the engine be unit-tested
 against scripted targets with no server at all.
 
-**What this rules out:** calling `runAIAgent` / `streamAIAgent` directly from the
+**What this rules out:** calling `runAgent` / `streamAgent` directly from the
 conversation engine, and widening `TargetAgentDriver` with transport details
 (headers, cookies, channels) that would tie the engine to HTTP.

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.