@pikku/core 0.12.83 → 0.12.86

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

@@ -1,4 +1,5 @@
-import type { CoreUserSession, SerializedError } from '../../types/core.types.js';
+import type { CoreUserSession } from '../../types/core.types.js';
+import type { SerializedError } from '../../errors/serialized-error.js';
 import type { GroupConcurrencyConfig, JobGroup, JobOptions } from '../queue/queue.types.js';
 import type { PikkuWorkflowWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowQueueOptions, WorkflowStepOptions } from './workflow.types.js';
 import type { WorkflowService } from '../../services/workflow-service.js';

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

@@ -1,7 +1,7 @@
 import { runPikkuFunc } from '../../function/function-runner.js';
 import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../pikku-state.js';
 import { getDurationInMilliseconds } from '../../time-utils.js';
-import { ChildWorkflowStartedException, continueGraph, executeGraphStep, runWorkflowGraph, runFromMeta, } from './graph/graph-runner.js';
+import { ChildWorkflowStartedException, continueGraph, executeGraphStep, runWorkflowGraph, runFromMeta, stripInstanceOrdinal, } from './graph/graph-runner.js';
 import { isExpectedError } from '../../errors/error-handler.js';
 import { PikkuMissingMetaError } from '../../errors/errors.js';
 import { RPCNotFoundError } from '../rpc/rpc-runner.js';
@@ -735,9 +735,8 @@ export class PikkuWorkflowService {
                     graphNodeId = stepName;
                 }
                 else {
-                    const hash = stepName.lastIndexOf('#');
-                    const base = hash > 0 ? stepName.slice(0, hash) : undefined;
-                    if (base && base in workflowMeta.nodes)
+                    const base = stripInstanceOrdinal(stepName);
+                    if (base !== stepName && base in workflowMeta.nodes)
                         graphNodeId = base;
                 }
             }

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

@@ -1,4 +1,4 @@
-import type { SerializedError } from '../../types/core.types.js';
+import type { SerializedError } from '../../errors/serialized-error.js';
 import type { StepState, StepStatus } from './workflow.types.js';
 export interface RunTimelineEvent {
     seq: number;
@@ -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-run.types.d.ts

@@ -0,0 +1,171 @@
+/**
+ * What one `pikku scenario run` leaves behind.
+ *
+ * A run is history: the scenarios it selected, the sentences they were made of,
+ * and the images and footage they produced. The sentences are snapshotted into
+ * the record rather than looked up later, because a scenario is code and the
+ * code moves — a run from last week describes a suite that no longer exists,
+ * and re-deriving its ladder from today's source would quietly rewrite it.
+ *
+ * Everything here is plain serialisable data. That is what lets one record be
+ * a JSON file on disk in OSS and a row in Postgres on a hosted project, read
+ * back by the same console screen either way.
+ */
+import type { ScenarioBrowserFailure } from './scenario-step.types.js';
+/** What a run filed, in the order it filed it. */
+export type ScenarioArtifactKind = 'screenshot' | 'failure' | 'video';
+/**
+ * One image or recording a scenario produced.
+ *
+ * `path` is relative to the run's artifact root and always uses forward
+ * slashes: it is a content key, not a filesystem path. Locally it resolves
+ * under the run's directory; on a hosted project it is the object key in a
+ * bucket, and the same record works unchanged.
+ */
+export interface ScenarioArtifact {
+    /** The scenario label this belongs to, as the report names it. */
+    scenario: string;
+    kind: ScenarioArtifactKind;
+    path: string;
+    /** Whose window it was — a two-actor scenario produces two of everything. */
+    actor?: string;
+    /** The caption the scenario author took a screenshot under. */
+    name?: string;
+}
+/** One step of a run, already joined to the prose that declared it. */
+export interface ScenarioStepRow {
+    sentence: string;
+    status: string;
+    durationMs?: number;
+    error?: string;
+}
+/** Everything known about why one scenario failed. */
+export interface ScenarioFailureDetail {
+    /** The rendered sentence of the failing step; absent if no step failed. */
+    sentence?: string;
+    message: string;
+    stack?: string;
+    /**
+     * True when the failure was a deliberate one (a PikkuError). Its message is
+     * the whole story, so the stack is noise.
+     */
+    expected?: boolean;
+    browser?: ScenarioBrowserFailure[];
+}
+export interface ScenarioResult {
+    name: string;
+    status: 'passed' | 'failed';
+    durationMs: number;
+    output?: unknown;
+    error?: string;
+    steps?: ScenarioStepRow[];
+    failure?: ScenarioFailureDetail;
+    /** The scenario registration this ran, which the label alone does not give. */
+    scenarioName?: string;
+    /** The feature that grouped it, when one did. */
+    feature?: string;
+    tags?: string[];
+    /** Images and footage this scenario produced, filed under the run. */
+    artifacts?: ScenarioArtifact[];
+}
+/** One scenario that was not run, and why. */
+export interface ScenarioSkip {
+    name: string;
+    reason: string;
+}
+export interface ScenarioRunReport {
+    environment: string;
+    results: ScenarioResult[];
+    /**
+     * Scenarios not run at all, each carrying why. A skip is only useful if the
+     * reader can tell a browser scenario held back by `--no-browser` from one the
+     * project itself quarantined, so the reason travels with the name rather than
+     * being assumed by the formatter.
+     */
+    skipped: ScenarioSkip[];
+    /** Feature-level hook failures, which belong to no single scenario. */
+    hookFailures: string[];
+}
+export type ScenarioRunStatus = 'running' | 'passed' | 'failed';
+/**
+ * A whole run, as it is stored and read back.
+ *
+ * `status` is `running` from the moment the run is created until it finishes,
+ * so a console watching a run in progress can tell "still going" from "nothing
+ * came back" — and a run killed halfway stays `running` forever, which is the
+ * honest record of what happened to it.
+ */
+export interface ScenarioRunRecord extends ScenarioRunReport {
+    runId: string;
+    status: ScenarioRunStatus;
+    /** The surface the run targeted: `default`, `browser`, … */
+    surface: string;
+    startedAt: string;
+    finishedAt?: string;
+}
+/** Enough of a run to list it without loading its steps and stacks. */
+export interface ScenarioRunSummary {
+    runId: string;
+    environment: string;
+    surface: string;
+    status: ScenarioRunStatus;
+    startedAt: string;
+    finishedAt?: string;
+    durationMs?: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    /** Whether anything is there to watch, so a list can say so without a second read. */
+    artifacts: number;
+}
+/**
+ * Where runs are kept.
+ *
+ * Deliberately not the workflow service: a scenario run is a workflow run under
+ * the hood, but its history has a different lifetime, a different audience, and
+ * a different home — a JSON file beside the project locally, a project-scoped
+ * table and an object store when hosted.
+ *
+ * Written progressively rather than at the end, so a suite that dies on its
+ * fortieth scenario still leaves the thirty-nine behind.
+ */
+export interface ScenarioRunStore {
+    /** Open a run. Called before the first scenario, with `status: 'running'`. */
+    start(record: ScenarioRunRecord): Promise<void>;
+    /** Append one finished scenario to an open run. */
+    recordScenario(runId: string, result: ScenarioResult): Promise<void>;
+    /**
+     * File the run's artifacts against the scenarios that produced them.
+     *
+     * Separate from `recordScenario` because a scenario's video does not exist
+     * when the scenario ends — it is finalised by the next scenario's reset, and
+     * renamed again when the run closes. Artifacts are matched to a result by the
+     * label the report knows it under.
+     */
+    attachArtifacts(runId: string, artifacts: ScenarioArtifact[]): Promise<void>;
+    /** Close a run, settling everything only known once every scenario has run. */
+    finish(runId: string, outcome: Pick<ScenarioRunRecord, 'status' | 'finishedAt' | 'skipped' | 'hookFailures'>): Promise<void>;
+    /**
+     * The bytes of one artifact, by the `path` its record carries.
+     *
+     * Reading goes through the store because only the store knows where a run's
+     * files actually are — a directory beside the project, or an object store
+     * behind a bucket. Absent when the run or the path is unknown, which is also
+     * the answer for a path that tries to leave the run.
+     *
+     * The bytes are backed by their own `ArrayBuffer` so they can be handed
+     * straight to a `Response` — a view onto a pooled or shared buffer is not a
+     * valid body.
+     */
+    readArtifact(runId: string, path: string): Promise<{
+        body: Uint8Array<ArrayBuffer>;
+        contentType: string;
+    } | undefined>;
+    /** Most recent first. */
+    list(options?: {
+        limit?: number;
+    }): Promise<ScenarioRunSummary[]>;
+    get(runId: string): Promise<ScenarioRunRecord | undefined>;
+    /** Forget a run and everything it filed. */
+    remove(runId: string): Promise<void>;
+}

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

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

package/dist/wirings/workflow/scenario-step-guards.d.ts

@@ -1,3 +1,2 @@
 import type { PikkuScenarioStepWire, ScenarioEnvironment } from './scenario-step.types.js';
-export declare const requireActor: <TActor>(scenarioStep: PikkuScenarioStepWire<TActor> | undefined) => TActor;
-export declare const requireScenarioEnv: (scenarioStep: PikkuScenarioStepWire<unknown> | undefined) => ScenarioEnvironment;
+export declare const requireScenarioEnv: (scenarioStep: PikkuScenarioStepWire | undefined) => ScenarioEnvironment;

package/dist/wirings/workflow/scenario-step-guards.js

@@ -1,11 +1,3 @@
-export const requireActor = (scenarioStep) => {
-    const actor = scenarioStep?.actor;
-    if (!actor) {
-        throw new Error(`[scenario] step '${scenarioStep?.name ?? 'unknown'}' was called without an actor. ` +
-            `Pass { actor: actors.<name> } so it runs as that persona.`);
-    }
-    return actor;
-};
 export const requireScenarioEnv = (scenarioStep) => {
     const env = scenarioStep?.env;
     if (!env) {

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

@@ -1,4 +1,4 @@
-import type { ScenarioPersona } from '../../services/personas-service.js';
+import type { ScenarioArtifact } from './scenario-run.types.js';
 /**
  * Scenario steps: named, typed units of scenario behaviour.
  *
@@ -86,7 +86,10 @@ export type ScenarioSurfaceResolution = {
  * default to no retries.
  */
 export interface ScenarioStepOptions {
-    /** The actor this step runs as. Required for steps declaring a `browser` binding. */
+    /**
+     * The actor this step runs as. Required for a step that declares `actor: true`
+     * or a `browser` binding; the runner refuses to dispatch one without it.
+     */
     actor?: unknown;
     /** Overrides the step's own `description` for this call site only. */
     description?: string;
@@ -107,11 +110,12 @@ export interface ScenarioEnvironment {
 /**
  * The `scenarioStep` wire, present on every scenario step invocation.
  *
- * `TActor` is the project's own actor type, so a step reaches only the RPCs its
- * actors can actually call. It defaults to the open `ScenarioPersona` for a
- * project that declares no registry.
+ * The persona a step runs as is not here: it arrives as `wire.actor`, injected
+ * by the runner and typed as present exactly on the bindings that declared they
+ * need one. Keeping it off this interface is what makes that possible — a wire
+ * member can be required per binding, a property of one cannot.
  */
-export interface PikkuScenarioStepWire<TActor = ScenarioPersona> {
+export interface PikkuScenarioStepWire {
     /** Registered step name (also its pikkuFuncId) */
     name: string;
     /** Durable key within the run; may carry an `#ordinal` suffix when repeated */
@@ -123,12 +127,6 @@ export interface PikkuScenarioStepWire<TActor = ScenarioPersona> {
      * per witness, so its body sees this change between invocations.
      */
     surface: ScenarioSurface;
-    /**
-     * The actor this step runs as, when one was given. Call RPCs through it
-     * (`actor.invoke(...)`) so they run against the target environment as that
-     * persona.
-     */
-    actor?: TActor;
     /**
      * The environment this run targets. A step runs in the CLI process, where
      * there is no `variables` service — this is how a raw-HTTP step learns the
@@ -218,11 +216,28 @@ export interface ScenarioBrowserProvider {
      * folder — findable only by timestamp.
      */
     beginScenario?(scenario: string): void;
+    /**
+     * Report how the scenario that just ran finished.
+     *
+     * Called after each scenario, and separate from `reset()` because artifacts
+     * that only exist once a window closes — a video — are produced by the NEXT
+     * scenario's reset, long after the outcome that decides whether to keep them.
+     */
+    endScenario?(outcome: 'passed' | 'failed'): void;
     /**
      * Snapshot every open window for a failed scenario. `label` identifies the
      * scenario in artifact filenames. Never throws: a failure to capture must
      * not replace the failure being captured.
      */
     captureFailure?(label: string): Promise<ScenarioBrowserFailure[]>;
+    /**
+     * Everything the run filed, each entry naming the scenario it belongs to.
+     *
+     * Reported by the driver rather than discovered by scanning the directory:
+     * only the driver knows which window produced a file and under what caption,
+     * and a video's final name is not settled until the run closes. Read after
+     * `close()`, which is the first moment the answer is complete.
+     */
+    artifacts?(): ScenarioArtifact[];
     close(): Promise<void>;
 }

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

@@ -103,7 +103,8 @@ export const evaluateApprovalStep = async (store, runId, reason, approvalStepNam
         return stepState.result;
     }
     const stateKey = approvalStateKey(approvalStepName);
-    let record = ((await store.getRunState(runId))[stateKey] ?? {});
+    let record = ((await store.getRunState(runId))[stateKey] ??
+        {});
     const policy = {
         approvers: options.approvers,
         approverScope: options.approverScope,

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

@@ -1,4 +1,5 @@
-import type { PikkuRawWire, SerializedError } from '../../types/core.types.js';
+import type { PikkuRawWire } from '../../types/core.types.js';
+import type { SerializedError } from '../../errors/serialized-error.js';
 import type { CoreWorkflow, PikkuWorkflowWire, StepState, WorkflowRun, WorkflowStatus, WorkflowStepOptions } from './workflow.types.js';
 export interface RunLifecycleContext {
     runId: string;

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

@@ -1,4 +1,5 @@
-import type { SerializedError, CommonWireMeta } from '../../types/core.types.js';
+import type { CommonWireMeta } from '../../types/core.types.js';
+import type { SerializedError } from '../../errors/serialized-error.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';

package/knowledge/decisions/index.md

@@ -14,6 +14,8 @@ here first — several of these exist because the obvious simplification was tri
 and broke something.
 
 <!-- pikku:knowledge-index -->
+
 - [internals](internals/index.md) — a rule about how it works under the hood, and why
 - [security](security/index.md) — a rule about who may do what
+
 <!-- /pikku:knowledge-index -->

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/a-scenario-step-template-is-offered-unfilled.md

@@ -14,7 +14,7 @@ A reporter fills those placeholders from a run that already happened. There is
 no run yet at derivation time, so there is nothing to fill them from. More
 importantly, filling them would answer the wrong question: "invites {email}"
 tells the user to choose someone, where "invites ada@example.com" tells it whom
-— and *whom* is the scenario author's answer, not something the virtual user
+— and _whom_ is the scenario author's answer, not something the virtual user
 worked out.
 
 **What this rules out:** substituting example or fixture values to make the

package/knowledge/decisions/internals/a-secret-that-fails-to-decrypt-fails-the-whole-read.md

@@ -37,7 +37,7 @@ that turn that into a one-line fix, and they are known at the catch site and
 nowhere after it.
 
 This matters most at exactly the moment it is least convenient: a change to
-`deriveKEK` makes *every* previously stored secret undecryptable at once. Loud
+`deriveKEK` makes _every_ previously stored secret undecryptable at once. Loud
 failure names the first one; silence produces an empty map and a support ticket.
 
 **What this rules out:** a `getSecrets` that skips unreadable rows; returning

package/knowledge/decisions/internals/a-virtual-user-run-is-not-a-workflow-and-not-a-queued-job.md

@@ -18,9 +18,9 @@ Both of the alternatives are the obvious ones, and both are wrong for this.
 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
+_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
+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.
 

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

@@ -13,11 +13,11 @@ 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 |
+|                               |                                 |
+| ----------------------------- | ------------------------------- |
+| 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
@@ -37,7 +37,7 @@ suite grows or CI moves to a noisier runner. Any assertion of the form
 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
+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.

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

@@ -18,7 +18,7 @@ pikkuUserId: rpcService.wire?.pikkuUserId,
 ```
 
 `PikkuRPC` has no `wire`. Neither does the object `getContextRPCService`
-actually returns — `ContextAwareRPCService` holds its wire *privately* and
+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.

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/addon-singleton-services-are-cached-per-namespace-not-per-package.md

@@ -17,7 +17,7 @@ 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
+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

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

@@ -15,7 +15,7 @@ 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`.
+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

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.