@pikku/core 0.12.82 → 0.12.84

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

package/knowledge/decisions/security/{ai-agent-sessionless-deployments-have-no-thread-ownership.md → agent-sessionless-deployments-have-no-thread-ownership.md}

@@ -2,14 +2,14 @@
 type: decision
 title: Agent thread ownership fails closed when there is no principal
 description: A sessionless caller gets an ephemeral owner and reaches no stored thread, rather than reaching all of them
-tags: ai-agent
+tags: agent
 ---
 
 # Agent thread ownership fails closed when there is no principal
 
 `canAccessThread` returns `false` and `threadOwnerConstraint` returns `[]` when
 the session carries neither `userId` nor `orgId`
-(`packages/core/src/wirings/ai-agent/ai-agent-prepare.ts`).
+(`packages/core/src/wirings/agent/agent-prepare.ts`).
 `resolveOwnerResourceId` never accepts the client-supplied `resourceId` as an
 ownership key; without a principal it mints an ephemeral `anon-<uuid>` owner
 memoized on the request's params object.
@@ -17,8 +17,8 @@ memoized on the request's params object.
 Agent wirings default to `auth: false`, so "no session" is the common case
 rather than an exotic one. Treating it as "no ownership model to enforce" made
 every ownership check vacuous: a caller named any `resourceId` and reached that
-thread, and because `undefined` on `AgentRunService.listThreads` means *no
-filter* rather than *no rows*, a sessionless `getAgentThreads` returned every
+thread, and because `undefined` on `AgentRunService.listThreads` means _no
+filter_ rather than _no rows_, a sessionless `getAgentThreads` returned every
 thread in the deployment. The ephemeral owner is what keeps one-shot
 conversations working while denying continuity — it is unguessable, so nothing
 stored can be reached, and it is stable within a request, so a sub-agent
@@ -32,7 +32,7 @@ field, never in its body.
 
 **What this rules out:** returning `undefined` from `threadOwnerConstraint` for
 any caller; deriving `owners` from request input instead of the session; reading
-`auth: false` as permission to skip ownership on a *stored* thread; and
+`auth: false` as permission to skip ownership on a _stored_ thread; and
 persisting the anonymous owner anywhere, which would turn an ephemeral identity
 into a forgeable one. Cross-request thread continuity without a session is not
 available by design — wire a session to get it back. See

package/knowledge/decisions/security/{ai-agent-thread-ownership-composes-the-session-principal.md → agent-thread-ownership-composes-the-session-principal.md}

@@ -2,12 +2,12 @@
 type: decision
 title: An agent thread key is always prefixed with the trusted principal
 description: Ownership keys are composed as principal:resourceId, so a client id can sub-divide its own boundary but never widen it
-tags: ai-agent
+tags: agent
 ---
 
 # An agent thread key is always prefixed with the trusted principal
 
-`resolveOwnerResourceId` in `packages/core/src/wirings/ai-agent/ai-agent-prepare.ts`
+`resolveOwnerResourceId` in `packages/core/src/wirings/agent/agent-prepare.ts`
 composes the ownership key for a thread or run as `principal:resourceId`. The
 principal is the trusted one — `session.userId` for the default `'user'`
 `SessionScope`, `session.orgId` for `'org'` — and the client-supplied

package/knowledge/decisions/security/{ai-agent-tool-filtering-reads-the-live-function-config.md → agent-tool-filtering-reads-the-live-function-config.md}

@@ -2,12 +2,12 @@
 type: decision
 title: Agent tool permission filtering reads the live function config, not the metadata
 description: The pikkuAuth brand survives only on live permission objects, so a metadata-driven check would silently admit every gated tool
-tags: ai-agent
+tags: agent
 ---
 
 # Agent tool permission filtering reads the live function config, not the metadata
 
-`buildToolDefs` in `packages/core/src/wirings/ai-agent/ai-agent-prepare.ts`
+`buildToolDefs` in `packages/core/src/wirings/agent/agent-prepare.ts`
 decides which tools and sub-agents to expose to the model by calling
 `checkAuthPermissions` against the permission objects held in the live function
 (or agent) config in `pikkuState`, using the metadata only to learn that a

package/knowledge/decisions/security/an-agent-approval-is-claimed-before-the-tool-runs.md

@@ -2,7 +2,7 @@
 type: decision
 title: An agent approval is claimed before the tool runs
 description: resolveApproval is a compare-and-swap returning whether this caller won, because the read that precedes it is not a claim and ten concurrent approvals would otherwise mean ten refunds
-tags: ai-agent
+tags: agent
 ---
 
 # An agent approval is claimed before the tool runs
@@ -15,7 +15,7 @@ same tool call all observed `suspended`, all snapshotted the same list, and all
 reached `execute`. `resolveApproval` returned `void`, so a loser could not even
 tell.
 
-`resolveApproval` is now the claim, and returns whether *this* caller made it.
+`resolveApproval` is now the claim, and returns whether _this_ caller made it.
 The stores implement it as a compare-and-swap: Kysely updates the run row only
 while `status = 'suspended'` and `pendingApprovals` still equals the list it
 read; the tool-call stores move the row off `approvalStatus = 'pending'` and
@@ -23,7 +23,7 @@ count the rows they changed. Both resume paths run the tool only for the ids the
 claimed, and a caller that claimed nothing gets an error rather than a silent
 re-run.
 
-The claim is per tool call, not per run, so concurrent approvals of *different*
+The claim is per tool call, not per run, so concurrent approvals of _different_
 tool calls on one run all proceed — which is the case that made a run-level
 `claimSuspendedRun` the worse fit.
 

package/knowledge/decisions/security/an-empty-owners-constraint-matches-nothing.md

@@ -2,13 +2,13 @@
 type: decision
 title: An empty owners constraint matches nothing
 description: owners is an authorization boundary, so every storage backend must treat [] as no rows rather than no filter
-tags: ai-agent, storage
+tags: agent, storage
 ---
 
 # An empty owners constraint matches nothing
 
 Every `AgentRunService.listThreads` implementation returns `[]` immediately when
-`owners` is present and empty — `kysely-ai-agent-run-service.ts`,
+`owners` is present and empty — `kysely-agent-run-service.ts`,
 `redis-agent-run-service.ts`, `mongodb-agent-run-service.ts`. The conformance
 suite in `packages/core/src/testing/service-tests.ts` pins it, so a new backend
 inherits the requirement instead of rediscovering it.
@@ -27,4 +27,4 @@ return; the two decisions only hold together.
 `if (owners)` path; treating `owners: []` as equivalent to `owners: undefined`
 at any layer; and adding a backend without the conformance suite.
 
-See [[ai-agent-sessionless-deployments-have-no-thread-ownership]].
+See [[agent-sessionless-deployments-have-no-thread-ownership]].

package/knowledge/decisions/security/console-addon-privileged-functions-gate-themselves.md

@@ -2,7 +2,7 @@
 type: decision
 title: The console addon's privileged functions gate themselves
 description: Thread listing is owner-scoped unless the caller holds admin, and addon installation requires an admin session, rather than trusting the host to register a global permission
-tags: addon, ai-agent, rpc
+tags: addon, agent, rpc
 ---
 
 # The console addon's privileged functions gate themselves
@@ -27,14 +27,18 @@ runner's, which for a `pikkuSessionlessFunc` fires only when the function itself
 sets `auth: true`.
 
 The addon's original authorization story was a single package-scoped
-`addGlobalPermission([isAdmin], '@pikku/addon-console')` that the *host*
+`addGlobalPermission([isAdmin], '@pikku/addon-console')` that the _host_
 registered, which `runPermissions` resolves in the callee's package namespace and
 applies to every function at once. Nothing generated that call — the scaffold
 emitted only a comment recommending it, and `resolveGlobalPermissions` returns an
 empty list when the host registered none, which `runPermissions` treats as
 allow. An app that followed the scaffold and stopped there had a fully open
-console surface. The scaffold now emits `wireAddon({ …, scopes: ['admin'] })`
-instead, which the function runner enforces on every function in the package.
+console surface. Every console function now declares its own
+`pikku:console:<area>:<action>` scope instead, which the function runner
+enforces per call. A blanket `wireAddon({ …, scopes: ['admin'] })` stood in for
+that briefly; it is gone, because a single grant covering secrets, source
+editing and the audit trail alike is not something an operator can reason
+about.
 
 The two functions whose failure mode is worst still do not depend on any
 package-wide gate:
@@ -51,16 +55,19 @@ storage backend already treats as no rows.
 attacker-chosen package name and write a wiring file into the project. They were
 `pikkuSessionlessFunc` with `auth: false`, which — behind a `no-auth` RPC route
 and with no host global permission — meant an unauthenticated POST reached
-`execFileSync`. They now declare `auth: true` and `scopes: ['admin']`, enforced
-by `verifyScopes` in the function runner before the body runs. Both gates are
-checked whether or not the host registered a global permission, and whether or
-not the addon itself was wired with scopes — an app that hand-wires
-`wireAddon({ name: 'console', package: '@pikku/addon-console' })` without them
+`execFileSync`. They now declare `auth: true` and
+`scopes: ['pikku:console:addons:install']`, enforced by `verifyScopes` in the
+function runner before the body runs. Both gates are
+checked whether or not the host registered a global permission — an app that
+hand-wires `wireAddon({ name: 'console', package: '@pikku/addon-console' })`
 still cannot reach `execFileSync` unauthenticated.
 
-`admin` is spelled as a literal here because it is a scope id in the addon's own
-`wireScope` tree, the same tree the `pikku:scopes:*` gates on the scope-admin
-functions come from.
+The scopes are spelled as literals here because they are scope ids in the
+addon's own `wireScope` tree — the same tree the `pikku:console:scopes:*` gates
+on the scope-admin functions come from. The generated secret and variable
+brokers live in the app's own scaffold rather than the addon, so the addon
+boundary never covered them; they carry `pikku:console:secrets:*` and
+`pikku:console:variables:*` themselves.
 
 **What this rules out:** treating the host's `addGlobalPermission` as the only
 gate in front of an operation that installs code or reads another principal's
@@ -72,5 +79,5 @@ is-this-localhost test.
 
 See [[addon-scopes-are-resolved-where-the-function-runs]],
 [[an-empty-owners-constraint-matches-nothing]],
-[[ai-agent-sessionless-deployments-have-no-thread-ownership]] and
+[[agent-sessionless-deployments-have-no-thread-ownership]] and
 [[global-permissions-and-function-permissions-are-independent-gates]].

package/knowledge/decisions/security/index.md

@@ -15,7 +15,7 @@ A rule about who may do what, and which way it fails when it is unsure.
 - [A permission gets a wire it cannot reply on](a-permission-gets-a-wire-it-cannot-reply-on.md) — The permission wire is typed with Out = never so a permission cannot send on the channel; that narrowing is not a subtype, so the call site asserts
 - [A step runs the function the workflow dispatched it with](a-step-runs-the-function-the-workflow-dispatched-it-with.md) — StepState records the step's function name so the worker can reject a queue message naming a different one, because the step executes under the run owner's identity
 - [A virtual user is never offered a scenario, platform or addon step](a-virtual-user-is-never-offered-a-step-that-would-forge-its-own-oracle.md) — Being able to invoke "the webhook arrives" lets the user manufacture the outcome it exists to discover, which invalidates every finding downstream
-- [A workflow run is read by its owner, and answered by whoever its gate declares](a-workflow-run-is-read-and-approved-by-its-owner.md) — A run started through a session records that user and only that user may read it; who may answer an approval gate is the gate's own declaration, and a run with no recorded owner has no ownership to enforce
+- [A workflow run is read and approved by its owner](a-workflow-run-is-read-and-approved-by-its-owner.md) — A run started through a session records that user and only that user may read it or answer its approval gates; a run with no recorded owner has no ownership to enforce
 - [An actor's missing approval decision defaults to denied](actor-flow-missing-approval-decisions-default-to-denied.md) — Every pending tool call gets an explicit decision; an id the persona LLM omitted is denied, so a dropped field can never read as consent
 - [Actor sign-in is proven by Set-Cookie, not a non-empty jar](actor-sign-in-is-proven-by-set-cookie-not-a-non-empty-jar.md) — HttpScenarioActor tracks its own signedIn flag and requires the sign-in response itself to set a cookie, because a populated jar proves nothing
 - [Actor sign-in only works for actor-flagged users](actor-sign-in-only-works-for-actor-flagged-users.md) — The scenario actor secret mints sessions for user rows flagged actor and nothing else, so holding it never impersonates a real user
@@ -31,7 +31,6 @@ A rule about who may do what, and which way it fails when it is unsure.
 - [An agent thread key is always prefixed with the trusted principal](ai-agent-thread-ownership-composes-the-session-principal.md) — Ownership keys are composed as principal:resourceId, so a client id can sub-divide its own boundary but never widen it
 - [Agent tool permission filtering reads the live function config, not the metadata](ai-agent-tool-filtering-reads-the-live-function-config.md) — The pikkuAuth brand survives only on live permission objects, so a metadata-driven check would silently admit every gated tool
 - [An agent approval is claimed before the tool runs](an-agent-approval-is-claimed-before-the-tool-runs.md) — resolveApproval is a compare-and-swap returning whether this caller won, because the read that precedes it is not a claim and ten concurrent approvals would otherwise mean ten refunds
-- [An approval answer outlives the run it answered](an-approval-answer-outlives-the-run-it-answered.md) — Run state holds a decision only while the gate is open, so the settled answer carries decidedBy/decidedAt into the step result and every attempt is written to the audit sink, which has no foreign key to the run
 - [An empty owners constraint matches nothing](an-empty-owners-constraint-matches-nothing.md) — owners is an authorization boundary, so every storage backend must treat [] as no rows rather than no filter
 - [An exposed function with no gate is reported at codegen, not at boot](an-exposed-ungated-function-is-a-codegen-warning.md) — The check runs in the inspector where function meta and every wireAddon declaration are both in hand, because neither source alone can tell a gated function from an ungated one
 - [An upload is counted as it arrives, not buffered and then measured](an-upload-is-counted-as-it-arrives-not-buffered-then-measured.md) — Reading the whole body before checking its size hands an unauthenticated caller a way to spend the server's memory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.82",
+  "version": "0.12.84",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -49,8 +49,8 @@
     "./safe-fetch": "./dist/utils/safe-fetch.js",
     "./node-host-resolver": "./dist/utils/node-host-resolver.js",
     "./mcp": "./dist/wirings/mcp/index.js",
-    "./ai-agent": "./dist/wirings/ai-agent/index.js",
-    "./ai-scorer": "./dist/wirings/ai-scorer/index.js",
+    "./agent": "./dist/wirings/agent/index.js",
+    "./agent-scorer": "./dist/wirings/agent-scorer/index.js",
     "./gateway": "./dist/wirings/gateway/index.js",
     "./cli": "./dist/wirings/cli/index.js",
     "./cli/command-parser": "./dist/wirings/cli/command-parser.js",
@@ -74,7 +74,7 @@
     "./crypto-utils": "./dist/crypto-utils.js",
     "./hmac": "./dist/utils/hmac.js",
     "./ecosystem": "./dist/ecosystem.js",
-    "./internal": "./dist/ecosystem.js",
+    "./ecosystem/*": "./dist/ecosystem/*.js",
     "./schema": "./dist/schema.js",
     "./testing": "./dist/testing/index.js",
     "./dev": "./dist/dev/hot-reload.js"

package/scripts/generate-api-report.mts

@@ -22,7 +22,7 @@
  *
  * Run: yarn api-report
  */
-import { readFileSync, writeFileSync } from 'node:fs'
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { resolve, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import ts from 'typescript'
@@ -32,15 +32,36 @@ const pkg = JSON.parse(
   readFileSync(resolve(packageRoot, 'package.json'), 'utf-8')
 )
 
-const entryPoints = Object.entries(pkg.exports as Record<string, string>).map(
-  ([subpath, dist]) => ({
+/**
+ * A wildcard subpath stands for as many entry points as there are files behind
+ * it, and the report is per entry point. Left as a pattern it resolves to no
+ * source file at all, so every sub-barrel it publishes goes unreported.
+ */
+const expand = ([subpath, dist]: [string, string]): [string, string][] => {
+  if (!subpath.includes('*')) return [[subpath, dist]]
+  const [prefix] = dist.split('*') as [string]
+  return readdirSync(
+    resolve(packageRoot, prefix.replace('./dist/', './src/')),
+    {
+      recursive: true,
+      encoding: 'utf-8',
+    }
+  )
+    .filter((file) => file.endsWith('.ts') && !file.endsWith('.d.ts'))
+    .map((file) => file.slice(0, -'.ts'.length))
+    .sort()
+    .map((area) => [subpath.replace('*', area), dist.replace('*', area)])
+}
+
+const entryPoints = Object.entries(pkg.exports as Record<string, string>)
+  .flatMap(expand)
+  .map(([subpath, dist]) => ({
     subpath,
     file: resolve(
       packageRoot,
       dist.replace('./dist/', './src/').replace(/\.js$/, '.ts')
     ),
-  })
-)
+  }))
 
 const program = ts.createProgram(
   entryPoints.map((e) => e.file),
@@ -218,7 +239,10 @@ const signature = (exported: ts.Symbol): string => {
  *
  * knowledge: decisions/internals/the-ecosystem-entry-point-carries-the-adapter-surface.md
  */
-const ECOSYSTEM_SUBPATHS = new Set(['./ecosystem', './internal'])
+const isEcosystem = (subpath: string) =>
+  subpath === './ecosystem' ||
+  subpath === './internal' ||
+  subpath.startsWith('./ecosystem/')
 
 type Exported = { name: string; members: number; signature: string }
 
@@ -264,7 +288,7 @@ for (const { subpath, file } of entryPoints) {
 const tierOf = new Map<string, string>()
 const membersOf = new Map<string, number>()
 for (const [subpath, exports] of modules) {
-  const tier = ECOSYSTEM_SUBPATHS.has(subpath) ? 'ecosystem' : 'stable'
+  const tier = isEcosystem(subpath) ? 'ecosystem' : 'stable'
   for (const { name, members } of exports) {
     if (tier === 'stable' || !tierOf.has(name)) tierOf.set(name, tier)
     membersOf.set(name, Math.max(membersOf.get(name) ?? 0, members))
@@ -275,7 +299,7 @@ const tally = (tier: string) => {
   const names = [...tierOf].filter(([, t]) => t === tier).map(([n]) => n)
   return {
     entryPoints: [...modules.keys()].filter(
-      (s) => (ECOSYSTEM_SUBPATHS.has(s) ? 'ecosystem' : 'stable') === tier
+      (s) => (isEcosystem(s) ? 'ecosystem' : 'stable') === tier
     ).length,
     names: names.length,
     members: names.reduce((total, n) => total + (membersOf.get(n) ?? 0), 0),