@pikku/core 0.12.72 → 0.12.74

package/CHANGELOG.md

@@ -1,3 +1,796 @@
+## 0.12.74
+
+### Patch Changes
+
+- 6a307f0: Fix four latent correctness bugs in the function, RPC and error runtimes, and
+  remove dead code from the workflow service surface.
+
+  `WorkflowService.getNodesWithoutSteps` is gone. It was declared on the abstract
+  service and implemented by all five storage backends, and nothing ever called
+  it — hence the non-core packages in this changeset, which only lose that method.
+
+  **An RPC could execute twice.** `RPCService.invoke`, its addon path, and
+  `rpcWithWire` each wrapped the _execution_ of a resolved function in a `try`
+  whose `catch` treated `RPCNotFoundError` as "not found locally" and re-dispatched
+  the call through `deploymentService`. A nested `rpc.invoke` to a missing name,
+  raised from inside an already-running function, therefore re-ran that function on
+  a remote instance after its local side effects had already committed. Resolution
+  is now separated from execution on all three paths, so only a genuinely
+  unresolvable name reaches the fallback. What escapes to callers is unchanged.
+
+  **`addonNamespace` leaked between sibling calls.** The function runner's
+  middleware path restored `rpc`, `functionId`, `audit` and `addonNamespace` after
+  an invocation; the non-middleware path restored the first three but not the
+  fourth. A call into an addon function with no middleware left the addon's
+  namespace on the wire, so subsequent sibling calls resolved the wrong
+  per-instance singletons and `credentialOverrides`.
+
+  **Errors registered on a subclass never resolved.** `misc.errors` was typed
+  `Map<PikkuError, ErrorDetails>` — instances — while `addError` stores
+  constructors, a mismatch hidden by its `error: any` parameter. The instance
+  lookup in `getErrorResponse` was consequently dead, and lookup fell through to a
+  scan comparing `constructor.name`, so a subclass of a registered error got no
+  status mapping at all. The map is now typed `Map<PikkuErrorConstructor, …>` and
+  lookup walks the prototype chain first. Name matching is retained, deliberately,
+  as the fallback that keeps error mapping working when two copies of
+  `@pikku/core` are installed.
+
+  **`createWeakUID` collided across instances.** The prefix was
+  `Date.now().toString(36)` evaluated at module load, so any two instances loading
+  the module in the same millisecond emitted identical `channelId` and `requestId`
+  sequences — reproducibly, not just in principle. It is now seeded lazily from
+  `crypto.randomUUID()`.
+
+  Also: `pikkuState` keys its global map with `Symbol.for` rather than `Symbol`, so
+  two copies of the package share registrations instead of silently getting
+  disjoint state; and the local channel upgrade path no longer keys its middleware
+  cache on the raw request path, which grew the cache without bound while the
+  cached value never varied by path.
+
+- afef587: Close eleven security weaknesses found in a review of `@pikku/core`. Most are
+  breaking, and two invalidate data or credentials already in the wild — read the
+  migration notes before upgrading.
+
+  **Breaking: AI agent thread ownership now fails closed.** Reading, listing,
+  resuming or approving an existing thread or run requires a resolved session
+  principal (`userId`, or `orgId` for `sessionScope: 'org'`), regardless of the
+  agent's `auth` setting. Previously a request without a session had no ownership
+  model at all: the caller-supplied `resourceId` was accepted as the ownership
+  key, so any caller could read or resume another party's thread by naming its
+  `resourceId`. Worse, `threadOwnerConstraint` returned `undefined` for a
+  sessionless caller, and `undefined` means _no filter_ rather than _no rows_ —
+  so `getAgentThreads` returned every thread in the deployment. It now returns
+  `string[]`, empty for a sessionless caller, which every storage backend already
+  treats as matching nothing. Sessionless agents still run one-shot conversations,
+  each with a fresh unguessable owner; what they lose is cross-request continuity.
+  Wire a session to restore it.
+
+  **Breaking: stored secrets and credentials must be re-entered.** `deriveKey` ran
+  a single unsalted round of SHA-256 over the passphrase and used the digest
+  directly as the AES-GCM key — roughly one hash per brute-force guess, with one
+  rainbow table working against every deployment. It is now PBKDF2-HMAC-SHA256 at
+  600,000 iterations over a random salt. There is no compatibility path: every
+  value held by the kysely, mongodb and redis secret services and the kysely
+  credential service becomes undecryptable. They fail loud, naming the key and
+  `key_version`, so the app hard-fails on first secret read until each is re-set.
+
+  The KEK salt is scoped to the key version and stored alongside it, rather than
+  per secret, so a bulk read costs one derivation instead of N — `getSecrets` over
+  50 secrets went from ~2.3s to ~48ms, and rotation from ~4.6s to ~94ms. This adds
+  a salt table (kysely), hash field (redis) or collection (mongodb), created
+  automatically on first use.
+
+  **Breaking: `PIKKU_REMOTE_SECRET` must be at least 32 characters.** The
+  remote-RPC session envelope moved from PBKDF2 to HKDF, which expands
+  high-entropy key material rather than stretching a low-entropy passphrase. That
+  took a remote hop from ~269ms to ~0.4ms — PBKDF2 was running twice per request —
+  but HKDF supplies no brute-force resistance, so the secret must carry the
+  entropy itself. A shorter secret now throws `WeakKeyMaterialError` at both ends.
+  Generate one with `openssl rand -base64 32` and roll it out to every service in
+  the mesh together: existing bearer tokens are format-incompatible, so a partial
+  rollout produces 401s until every instance is updated. The Cloudflare, Lambda
+  and Azure deployment services each hand-rolled a copy of `buildRemoteHeaders`
+  and now call the shared one, which is what keeps the two sides in step.
+
+  **Breaking: previously signed content URLs stop verifying.** `LocalContent`
+  signed only `{signedAt, expiresAt, notBefore}`, so a signature proved when a URL
+  was issued but never what it was issued for — any valid token was a skeleton
+  key, and swapping the pathname from a public thumbnail to a private document
+  still verified. The signature now binds the request path. Separately, the
+  verifier returned "valid" when no JWT service was wired, which is how
+  `pikku serve` ran: a forged `?signedAt=0&expiresAt=99999999999999` was accepted.
+  It now rejects with 403, `LocalContent` requires a `JWTService`, and
+  `pikku serve`/`pikku dev` mint an ephemeral per-process signing key so local
+  development works without shipping a fail-open path. In-flight signed URLs must
+  be re-issued.
+
+  **Request body size limits now apply to every adapter.** The `maxBodySize` cap
+  existed only in `PikkuFetchHTTPRequest`. The real hole was uWebSockets, which
+  drove `res.onData` itself and concatenated every chunk with no bound and nothing
+  downstream able to intervene; it now drops chunks past the limit and replies 413
+  before routing. Fastify delegates to its native `bodyLimit` (set only when
+  `maxBodySize` is configured, so fastify's stricter 1 MB default is never
+  loosened), and `PikkuExpressServer` feeds the limit into its body parsers. Two
+  paths can only reject rather than prevent, and are documented as such:
+  `express-middleware` mounted on your own app receives an already-parsed body, so
+  that deployment must bound its own parser; Next server actions bottom out at
+  `experimental.serverActions.bodySizeLimit`.
+
+  **Breaking: the console addon's privileged functions are gated by default.**
+  `wireAddon` gains a `scopes` option that applies to every function in the
+  addon's namespace, and the console scaffold now generates
+  `wireAddon({ name: 'console', package: '@pikku/addon-console', scopes: ['admin'] })`.
+  Previously the console's entire privileged surface — around 54 functions
+  including `credentialGet`, which returns a resolved OAuth token for an arbitrary
+  `userId`, `updateFunctionBody`, and `installAddon`, which shells out to a
+  package install — was protected only by an optional host-registered
+  `addGlobalPermission`. `resolveGlobalPermissions` returns `[]` when none is
+  registered and permission checking then no-ops, so an app that never registered
+  one served those functions to anyone, and with the template's default
+  `scaffold.rpc: "no-auth"` that meant unauthenticated. All of them now return 403
+  `MissingScopeError` without an `admin`, `admin:*` or `*` scope. **Regenerating
+  is required** — an app holding an old `console.gen.ts` stays open.
+  `installAddon` and `installOpenapiAddon` additionally declare their own
+  `auth: true, scopes: ['admin']`, and `getAgentThreads` now scopes its listing to
+  the session's own threads unless the caller holds admin.
+
+  Addon scopes are enforced in `runPikkuFunc` rather than at the RPC boundary,
+  because a wiring can reference an addon function directly — the inspector
+  records the addon's `packageName` on HTTP, channel, schedule, queue, CLI,
+  trigger, gateway and MCP wirings — and those paths never call `resolveNamespace`.
+  Enforcing at the RPC seam would have covered only the `namespace:function` form
+  while reading as complete.
+
+  **Breaking: `wireAddon`'s `auth` and `tags` now apply on direct wirings too.**
+  Both were read only by `resolveAddonFunction`, so they had exactly the hole
+  scopes had: `wireAddon({ name: 'console', package: '@pikku/addon-console', auth:
+true, tags: ['admin'] })` gated `rpc('console:credentialGet')` and gated nothing
+  at all on an HTTP route wired straight to `credentialGet`. A consumer who
+  reached for the documented way to lock an addon down got a control that was
+  silently inert on every wiring except one. Both now resolve in `runPikkuFunc`.
+  `auth` merges as an OR — `auth: false` from an addon is ignored on a direct
+  wiring, because an addon may require a session the wiring did not but must never
+  waive one it did. Addon tags resolve to concrete middleware against the **root**
+  tag groups before the call rather than being folded into the function's
+  inherited middleware: `addTagMiddleware('admin', …)` is written by the consuming
+  app and registers under the root package, whereas `combineMiddleware` would look
+  the tag up under the addon's own `packageName`, where it does not exist.
+
+  One consequence worth naming: an addon that wires `auth: true` and also runs its
+  own sessionless internal work — a scheduled task or queue worker inside the
+  addon calling a sibling function — is now gated where it previously was not,
+  because a bare `rpc('fn')` from inside the addon reaches `runPikkuFunc` with the
+  addon's `packageName` like any other call. This reverses a decision that
+  deliberately scoped the gate to the namespaced boundary; that reasoning held
+  only while the boundary was real, and a direct wiring can enter an addon without
+  crossing it, so "already inside" is not something the runtime can infer. Such an
+  addon should carry authorization on the function via
+  `pikkuFunc({ permissions })`, which has always been enforced on every path. A
+  follow-up will add execution provenance so an intra-addon call can be
+  distinguished from an external one and skip the addon-level check; that needs a
+  marker no caller outside the process can set, which is its own design problem
+  and does not belong in a security fix.
+
+  **Codegen now warns when an exposed function has no gate (PKU574).** The
+  generated `POST /rpc/:rpcName` dispatcher forwards to `rpc.exposed`, which
+  refuses anything without `expose: true` — but nothing checked whether the
+  target was gated, because a dispatcher cannot know what it dispatches to. The
+  console shipped ~54 privileged functions through that gap and the toolchain was
+  silent. The inspector now reports every function that is exposed, sessionless,
+  and carries no `auth`, `scopes` or `permissions` of its own and none from a
+  governing `wireAddon`. It is a `warn`, not a critical: `expose: true` on an
+  ungated sessionless function is correct for a genuinely public endpoint, so it
+  blocks a build only under `--fail-on-warn`.
+
+  Two pieces of metadata were missing for this to be answerable statically, and
+  both are now recorded. A `pikkuSessionlessFunc`'s own `auth: true` was read at
+  runtime but never written to function meta, so a self-gated function was
+  indistinguishable from an ungated one — `sessionless` carries the baseline, and
+  `auth` now carries the tightening. And `wireAddon`'s `scopes`, `auth` and `tags`
+  were not parsed at all: the inspector recorded the addon's `rpcEndpoint` and its
+  secret, variable and credential overrides, and dropped every one of its gates.
+  An addon whose gates are not statically knowable is treated as gated, because a
+  false positive on a correctly-secured addon costs more than the one case it
+  would catch.
+
+  **Breaking: an application's global permissions now apply inside addons.**
+  `resolveGlobalPermissions` read only the bucket matching the function's own
+  package, but the generated `addGlobalPermission` wrapper takes no package
+  argument and always registers under the root. An app-wide rule like "every
+  request needs a signed-in user" therefore stopped at the addon boundary, and the
+  bucket an addon's functions did read was one no host could write to — which is
+  why the console addon's recommended `addGlobalPermission([isAdmin],
+'@pikku/addon-console')` was never a gate anybody could actually install. A
+  function now resolves the root bucket and its own package's, root first.
+  Unioning is safe in a way nothing else here would be: globals AND, so adding the
+  root ones can only tighten. Package buckets stay one-way — a package's globals
+  never reach root functions, or an installed addon could gate the whole
+  application. Apps with both a root global and addon-provided functions will see
+  those functions gated where they previously were not.
+
+  **Codegen now records whether each HTTP route requires a session, and warns
+  about inert addon tags (PKU575).** Four separate things can demand a session —
+  the function's `sessionless`, its own `auth`, the route's (or its group's)
+  `auth`, and the addon it belongs to — and answering "which routes are open?"
+  meant joining all four by hand and knowing which wins. Each route's meta now
+  carries the resolved `requiresSession` alongside the route's own `auth`. Scopes
+  count as requiring one, since they are matched against the session's and fail
+  closed. Anything not statically knowable resolves to `true`, matching PKU574:
+  a route that looks stricter than it is costs less than one that looks open and
+  isn't. Separately, `wireAddon({ tags: ['admin'] })` reads like a gate and is
+  applied like one right up until no `addTagMiddleware('admin', …)` exists, at
+  which point it resolves to an empty list and gates nothing; that now warns.
+  Only addon tags are reported — a tag on a function is as likely to be
+  organizational, and warning about those would bury the case that matters.
+
+  **Object-shorthand permissions were missing from meta.** The inspector visited
+  `ts.PropertyAssignment` but not `ts.ShorthandPropertyAssignment`, so
+  `permissions: { canAdminOrg }` — enforced identically to the longhand form at
+  runtime, since `verifyPermissions` has a non-array branch — was recorded as _no
+  permissions at all_. That is the most dangerous direction for meta to be wrong
+  in: an audit reading it sees an open door where one is shut. It cost this review
+  a false IDOR report across ~35 billing and org functions before the source
+  contradicted the metadata.
+
+  **Functions that authorize in their own body can say so.** A webhook receiver
+  verifying a signature, or a handler redeeming a signed invite, is genuinely
+  closed while carrying no session, scope or permission — indistinguishable in
+  meta from one nobody remembered to gate, and so warned about forever by PKU574.
+  `selfAuthenticated: true` on the function config records the claim and silences
+  the warning for that function. It is declarative only: nothing at runtime reads
+  it and it grants nothing. Detection was rejected deliberately — inferring it
+  from the body means a function that _looks_ like it checks something silences
+  the warning while checking nothing, and a warning that is usually wrong stops
+  being read.
+
+  **Breaking: `scaffold.<feature>` is now `boolean | { auth?, path? }`, and `true`
+  means authenticated.** The old `'auth' | 'no-auth' | false` read like a
+  starter-file preference while being a live authorization decision, set three
+  directories from the functions it governed — the shape the console incident
+  took. A surface now becomes public only by writing `{ auth: false }`, so
+  omitting a field can never open anything: the failure mode of a forgotten flag
+  is a locked door. `{ path }` additionally overrides where the file is
+  generated, which previously could only be set for all features at once via
+  `pikkuDir`.
+
+  The legacy strings are **refused, not coerced**. `resolveScaffoldFeature` throws
+  naming the key and its replacement (`"rpc": "no-auth"` → `"rpc": { "auth":
+false }`), and it does so at config load, not downstream. An earlier design used
+  a bare `string` for the output path, under which `"no-auth"` would have parsed
+  as a file named `no-auth` and every unmigrated config would have silently
+  produced nonsense; the object form makes any string invalid, so the failure is
+  loud.
+
+  The collapse is deliberately not uniform in effect. For `rpc` the flag was a
+  blanket "no anonymous RPC in this app" set on a dispatcher that cannot know what
+  it dispatches to; for `userAdmin` it was redundant, since the generated
+  functions are already `pikkuFunc` with `scopes: ['admin:users:list']`. But for
+  `agent`, `workflow`, `events` and `scenarios` it is the only gate — those
+  generate real endpoints the app never authors — so `true` keeps them
+  authenticated rather than opening them as a side effect of a config cleanup.
+  `webhook` and `remoteRpc` have no auth dimension at all (`serialize-remote-rpc.ts`
+  hardcodes `auth: false`), so an `{ auth }` on them is ignored. The three
+  configs in this repo are migrated preserving their current behaviour exactly.
+
+  **Queue job identities are signed.** A job carried the producer's `pikkuUserId`
+  as a plain string and the worker resolved a session from it with no
+  verification, so write access to the queue backend was act-as-any-user. The
+  identity is now `pq1.<claim>.<hmac>`, HMAC-SHA256 over the claim and the
+  canonicalized job payload, keyed by HKDF expansion of a new
+  `PIKKU_QUEUE_IDENTITY_SECRET`. Producers opt in by wrapping their queue service
+  with `SignedQueueService`. This fails safe rather than closed: with no secret
+  configured the identity is dropped and jobs still process, warning once per
+  process, so no existing deployment breaks on upgrade — it simply loses queue
+  identity until the secret is set. The payload rather than the job id is bound
+  because SQS, Cloudflare Queues, Azure and the in-memory service all mint ids
+  after `add` returns.
+
+  **Workflow inline state is read from the run record.** `isInline` consulted a
+  process-local `Map`, while `WorkflowRun.inline` is durable. Any instance that
+  did not start a run disagreed with the record, so one instance could dispatch a
+  queued job for a workflow another was already executing in-process. It is now
+  async and resolves through the durable identity, cached only when a context
+  already exists so a passive reader allocates nothing. The same `Map` also leaked:
+  `nextStepKey` fabricated replay state on every step, and `releaseContext`
+  refused to free anything carrying it, so runs whose steps executed outside a
+  `beginReplay` bracket — the step-worker queue path — stranded their context and
+  step state for the process lifetime. Contexts are now released by an explicit
+  execution counter. Step ordinals reset per execution rather than accumulating
+  across step-worker invocations in one process, which makes step naming
+  independent of how work was distributed.
+
+  **Secret reads fail loud in every store.** `MongoDBSecretService.getSecrets`
+  skipped rows that failed to decrypt, and the redis equivalent dropped every
+  rejection via `Promise.allSettled`, including the "No KEK available for
+  key_version N" configuration error. Both now throw, naming the key and its key
+  version, matching the kysely behaviour. This matters most alongside the KEK
+  change above: without it, an upgrade surfaces as a partial secrets map and an
+  opaque downstream failure instead of an error naming the secret to re-enter.
+
+  **A second middleware registration for a pattern no longer erases the first.**
+  `addHTTPMiddleware`, `addTagMiddleware` and `addChannelMiddleware` groups are
+  keyed by pattern or tag and held one source file each, so a second file's call
+  overwrote the first's. Codegen emits its imports from what is stored, so the
+  losing file was never imported and its middleware never registered — the
+  runtime composes repeated registrations for a pattern happily, and only codegen
+  dropped one. Adding an unrelated `addHTTPMiddleware('*', …)` to an app was
+  enough to silently unregister the generated better-auth session bridge, which
+  fails open and gives no sign until a request arrives without a session. A group
+  now carries every registration made for it, and all of them are imported.
+
+- 8075f6a: Confine `SecretService` to the places an app is wired.
+
+  `secrets` is now omitted from the services every function, AI agent, workflow,
+  permission and wire receives, and the function runner replaces it with a
+  throwing accessor so a cast cannot reach past the type. It stays available in
+  `pikkuServices`, `pikkuWireServices`, addon service factories and middleware —
+  read a secret there, give it to a service, and have the function ask that
+  service.
+
+  Alongside it:
+  - `wireSecret` gains `allowedHosts`, refusing a secret attached to a host it was
+    not declared for. Permissive by default; strict via
+    `config.secrets.requireAllowedHosts`.
+  - `pikku-graph`'s `httpRequest` resolves and attaches its credential inside a new
+    `httpRequester` service instead of holding the plaintext in the function.
+  - New inspector diagnostics: `PKU950` (a `SecretService` exposed under another
+    service name), `PKU951` (a secret read that no `wireSecret` declares) and
+    `PKU952` (a secret read with a non-literal key).
+
+## 0.12.73
+
+### Patch Changes
+
+- c984df6: Give an agent's tools back the descriptions their authors wrote
+
+  A tool's description is what the model is told the tool does, and the main
+  thing it chooses between tools on. It was not reaching the model. `description`
+  is classed as a verbose field, so it is stripped from the metadata bundled into
+  the generated bootstrap — the copy `pikkuState('function', 'meta')` is built
+  from. `buildToolDefs` read the description from there, found it always
+  undefined, and fell through to the tool's own name. Every agent has been
+  choosing between bare identifiers. The same fallback was offering an addon's
+  MCP tools under their names, for the same reason.
+
+  Tool definitions now resolve descriptions through `metaService`, which reads
+  the verbose metadata and falls back to the minimal copy, so the authored text
+  is recovered wherever the generated `.pikku` directory is readable. Where it is
+  not — no `metaService`, or a deployment shipping only the stripped copy — a
+  tool falls back to its name, which is what it did before. Addon metadata is
+  likewise loaded verbose-first. `title` is no longer part of the chain: a title
+  labels a tool in a UI, it does not tell a model when to reach for it.
+
+  An addon has to ship the verbose file for any of this to reach it. `tsc` only
+  emits the JSON it sees imported and nothing imports the verbose meta, so the
+  bundled addons now copy it into `dist` explicitly.
+
+  `ref()` is resolved at build time. It used to be pushed through codegen as an
+  opaque string, so `ref('todos:doesNotExist')` generated cleanly and failed only
+  when the agent ran. The inspector now resolves each reference against the
+  project's functions, or — using the namespace-to-package mapping `wireAddon`
+  already provides — against the addon's own metadata, and reports an unwired
+  namespace (`PKU152`) or a missing function (`PKU153`) at codegen. An addon that
+  has not been built yet contributed no metadata and is skipped rather than
+  reported missing.
+
+  New `pikku --strict-meta` additionally fails the build on any agent tool with
+  no description (`PKU154`), including tools reached through an addon. It is off
+  by default, so nothing that builds today stops building; turn it on to hold a
+  project to the metadata its agents actually run on.
+
+- 63ff32b: Run a CLI's commands on the server, over the connection the client opened
+
+  A CLI that talks to a service has to ship the service's command tree, so the
+  two versions drift: the binary someone installed months ago still believes in
+  flags and commands the server has since changed. This makes the command tree
+  the server's, and leaves the client holding only a socket.
+
+  `wireCLI` gains `auth`, and a program wired with a channel entrypoint now
+  generates a `__raw` route: the client forwards argv untouched, the server
+  parses it, runs the command, and streams the output back as it happens. The
+  terminating frame carries the exit code, so a failed remote command still exits
+  non-zero locally. Renderers stay on the client and are matched by the command
+  id the server reports; an unrecognised command falls back to JSON rather than
+  failing.
+
+  Every channel gains `channel.remote(...)`: calling a function on the peer at
+  the other end of the connection and waiting for its answer. A channel is
+  otherwise fire-and-forget in both directions, so this is what reaches a peer
+  that has no address of its own — a CLI on a laptop, a browser tab, a sandbox
+  behind NAT. It is on `channel` rather than `rpc` because it is bound to one
+  connection: which peer answers is the socket the call goes out on, not
+  something the RPC map could resolve. Any `wireChannel` gets it — a client
+  registers what it is willing to answer to, and a name outside that list is
+  refused.
+
+  Requests are correlated by id, time out, and fail fast when the socket closes
+  rather than waiting out the timeout. Replies are taken off the socket ahead of
+  routing, so a channel needs no route for them and an answer can never be
+  mistaken for a new message; the transport is created on first use and released
+  when the channel closes, which is also what fails anything the departing peer
+  still owed an answer to. Channels that only flow one way — SSE, an agent's
+  output stream, a locally-run CLI — refuse the call outright instead of waiting
+  for an answer that was never going to come.
+
+  What a peer answers with is its word, so it is checked before a caller sees it
+  — against the schema codegen already generated from the function's declared
+  return type, the same one an agent tool or an HTTP response is checked against.
+  A capability is declared with `pikkuRemoteChannelFunc`, which takes the usual
+  `title` / `description` / `input` / `output` but no `func` — this side owns the
+  contract, the peer owns the body. It registers under its name like any other
+  function, so `channel.remote` is typed off the same generated map as
+  `rpc.remote` and no caller has to cast, and a local call throws rather than
+  missing: reaching it locally means a command asked the server for something
+  only a client knows. A client on an older build fails the call it answered
+  rather than the caller failing later somewhere with no reason to expect a bad
+  shape; a name with no declared contract is left alone. Both frame guards
+  validate the whole envelope rather than the action tag alone, and a failure
+  payload with a non-string name or message falls back rather than being attached
+  to an `Error`.
+
+  The arguments going the other way are checked too, against the schema for the
+  capability's declared input, before anything is registered or sent. That is not
+  a boundary — the peer runs the code and has to check what it was handed, and a
+  caller that meant harm would send arguments that pass. It catches drift, where a
+  server built against a newer capability signature calls a client that predates
+  it, and fails it here rather than inside someone else's process.
+
+  A channel-driven CLI command uses this to ask its caller for machine-local
+  facts mid-run — a git sha, a working tree, a local file. The CLI wire's own
+  channel is synthetic (it exists so a command can stream progress without
+  knowing where that goes), so it delegates `remote` to the connection the
+  command actually arrived on.
+
+  Because that runs code on someone's machine at a remote caller's request, the
+  capability map says what _can_ run and approval says whether a particular call
+  _should_. A capability may be declared `{ execute, needsApproval }`, sharing
+  `ApprovalPolicy` — `needsApproval` and `approvalDescriptionFn` — with
+  `AIAgentToolDef`, which has carried both since before channels could call back:
+  both are an allowlist of named callables invoked by something other than the
+  code that wrote them. The runtime around them is deliberately not shared, since
+  an agent suspends its run and resumes it later while a reverse call is a live
+  await with a person at the other end.
+
+  A capability written as a bare function is unclassified, and unclassified means
+  approval is required — the annotation nobody got round to writing is the one
+  most likely to matter, so it fails closed. Declare
+  `{ execute, needsApproval: false }` for a capability that may run unattended.
+  Nothing infers this: core cannot tell a read-only capability from a destructive
+  one, so `needsApproval: false` is the author asserting it, and the assertion is
+  the only thing standing between a remote caller and the machine.
+
+  The default is the opposite of `AIAgentToolDef`'s, where absence means "do not
+  ask" — a tool is written by the same people who run the server it executes on,
+  and a capability is not.
+
+  `executeRawCLIViaChannel` reads `--auto-approve` and
+  `--dangerously-auto-approve` out of argv (or `PIKKU_AUTO_APPROVE` /
+  `PIKKU_DANGEROUSLY_AUTO_APPROVE`) and strips them before argv reaches the
+  server — what may run on this machine is this machine's decision, and a flag
+  the server can see is one the server could act on. `--auto-approve` permits the
+  classified-safe set and refuses the rest; `--dangerously-auto-approve` permits
+  everything and says so once on stderr. Interactively the user is asked per
+  call, with `y` / `n` / `a`, where `a` is remembered for that one capability for
+  the rest of the run and never written to disk — widening it to the session
+  would quietly turn an interactive run into `--dangerously-auto-approve`. A run
+  with no terminal and no flag refuses rather than assuming yes, because CI is
+  exactly where an unattended `git push` would otherwise happen. The tiers are
+  meaningful here in a way they would not be for an agent: the caller is a
+  deterministic program whose source can be read, so "these calls are always
+  fine" is a claim someone can actually justify.
+
+  A peer that is asking a human sends a pending frame first, which stops the
+  caller's timeout. Without it any approval slower than the timeout would fail
+  the call and then discard the decision when it finally arrived. The call is
+  still failed the moment the socket drops — what actually happens when a peer
+  dies mid-prompt — and a peer that sends the frame dishonestly can do nothing
+  but keep its own call waiting. A refusal is sent as an answer, so a denied call
+  fails its command immediately rather than hanging.
+
+  Fixes found on the way, each of which broke this path:
+  - A websocket upgrade wrote middleware headers (CORS, on every request)
+    straight onto the socket, so the first bytes a client saw were headers rather
+    than `ws`'s `101` status line and the handshake failed to parse. Header
+    writes are now buffered and flushed behind a status line only when the
+    upgrade is actually being rejected.
+  - An upgrade socket had no error listener while the channel opened, so a client
+    that gave up mid-handshake took the whole server process down with an
+    unhandled `ECONNRESET`.
+  - `onConnect` and `onDisconnect` never saw the session established during the
+    upgrade, so a channel could not tell who had just connected.
+  - Setting the routing key on a channel result mutated the value in place, which
+    throws for a primitive under ESM strict mode.
+
+- ba6cc08: fix: stop leaking internal error detail and bound the request body size
+
+  HTTP error responses no longer forward an error's `payload` or its raw `message` for
+  registered 5xx errors — those responses carry the registered error message instead, so an
+  internal error that happens to hold a `payload` cannot leak it to the client. Errors
+  registered with a 4xx status keep their message and payload, and `exposeErrors` still
+  surfaces the full detail outside production.
+
+  `PikkuFetchHTTPRequest` now caps how much of a request body it buffers, rejecting the
+  declared `content-length` up front and measuring the stream as it arrives so a lying or
+  absent header cannot exhaust memory. Exceeding the limit throws `PayloadTooLargeError`
+  (413). The ceiling defaults to 10MB and is configurable via the new `maxBodySize` option on
+  the constructor and on `RunHTTPWiringOptions`.
+
+- d007191: `cors()` takes an `exposeHeaders` option.
+
+  Without `Access-Control-Expose-Headers` a cross-origin caller can read only the
+  CORS-safelisted response headers, so any header the client is meant to act on was
+  invisible to it. The cross-site session relay in `@pikku/better-auth` is the case that
+  surfaced it: the client cannot read `x-pikku-cross-site-set-cookie` off a cross-origin
+  response without being told it may.
+
+  Defaults to none, so nothing new is exposed unless it is named.
+
+- a7b26c5: rename the inspected declarations to `define*`: `wireScope` → `defineScope`, `wireSecret` → `defineSecret`, `wireVariable` → `defineVariable`, `wireCredential` → `defineCredential`
+
+  `wire*` meant two unrelated things. A transport wiring attaches a function to
+  something that can invoke it — `wireHTTP`, `wireChannel`, `wireScheduler`,
+  `wireQueueWorker` and the rest — and the thing it wires runs. These four wire
+  nothing: they are no-ops that exist only so the call typechecks, they are
+  tree-shaken out of the build, and their whole job is to be found by the
+  inspector's AST pass and turned into a type union. One word for both left the
+  declaration reading like a registration with a runtime.
+
+  So the vocabulary splits: **`wire*` is a transport, `define*` is an inspected
+  declaration.**
+
+  ```ts
+  import { defineScope } from '@pikku/core/scope'
+  import { defineSecret } from '@pikku/core/secret'
+  import { defineVariable } from '@pikku/core/variable'
+  import { defineCredential } from '@pikku/core/credential'
+
+  defineScope({ admin: { scopes: { invoices: { scopes: { create: {} } } } } })
+  ```
+
+  **Breaking:** no alias is kept. Rename the four call sites; the module subpaths
+  (`@pikku/core/scope`, `/secret`, `/variable`) are unchanged.
+
+  The inspector matches these by identifier text, so a stale `wire*` call is not a
+  type error — it is silently not extracted, and the generated union comes back
+  empty. That fails as "this scope isn't declared" on code that was fine a moment
+  ago, nowhere near the declaration. Grep for the old names rather than trusting a
+  clean build.
+
+  An addon published with `.pikku` output generated before this release re-exports
+  `wireSecret` from `@pikku/core/secret` and will not typecheck against this core
+  until it is rebuilt and republished.
+
+- 457cb25: Add `definePersonas()`: the people a project's scenarios and virtual users run
+  as, declared in code.
+
+  There used to be three names for two-and-a-bit things — an _actor_ in
+  `scenarios.actors`, a _persona_ in `scenarios.personas`, and a _virtual user_
+  declared separately against an actor. In practice almost every actor was its own
+  kind, so the second set carried no information and the third was a third place
+  for a name to drift. There is now one declaration:
+
+  ```ts
+  definePersonas({
+    shopper: {
+      name: 'Sam Shopper',
+      jobTitle: 'Shopper',
+      personality: 'Buys in a hurry and leaves tabs open',
+      roles: ['customer'],
+      disposition: 'careless',
+      goals: ['Buy something without reading anything'],
+      account: {},
+    },
+  })
+  ```
+
+  A persona is a person: what they are like, what they want, the roles they hold,
+  and **one** account they sign in with — `account: {}` plus `linkedAccounts` for
+  the rare case of more, modelled on how better-auth does linking. A persona with a
+  `disposition` is a virtual user; `runnable: false` marks someone who only ever
+  exists to be acted upon — banned, shared with, reset — and is never handed a
+  session.
+
+  **A persona names roles, never scopes.** Scopes come from `defineSystemRole()`
+  expansion, so the build fails if a persona names a role nobody declared, and
+  fails again if a role confers a scope no `defineScope` declares. Running one only
+  ever has to check that its roles are still valid.
+
+  **Addresses are computed, never declared.** `personaEmail(id, domain, runId)`
+  derives `<id>[+runId]@<domain>` from `scenarios.emailDomain`, so a seed, a
+  scenario run and a virtual-user run cannot disagree about who they are signing in
+  as. `scenarios.actors` and `scenarios.personas` are gone from
+  `pikku.config.json` — only `emailDomain` remains.
+
+  `actor` survives in exactly one place: the name of a **slot in a scenario step**,
+  which is the role a persona is cast in for that step. `pikkuVirtualUser()`,
+  `kind`, `grants` and the `actor` field are removed; the `actors` service is now
+  `personas`, and the CLI's `virtual-user` commands are now `pikku persona list` /
+  `pikku persona run`. `budget` and `allowApprovalRequired` moved to run flags —
+  how much you will spend today is not a fact about a person.
+
+  `@pikku/cucumber` drops its `Actor` class and `ActorDispatchContext`: a
+  hand-rolled cookie jar that a persona's own typed session replaces outright.
+
+- f7567ad: Add `defineSystemRole()`: roles that ship with the product, declared in code.
+
+  A system role is to a console-composed role what an AWS managed policy is to a
+  customer-managed one — the console may show and grant it, but not rename,
+  re-scope or delete it. The CLI extracts declarations by AST and generates a
+  `SystemRoleName` union, so naming a role that does not exist fails the build,
+  and a role granting a scope no `defineScope` declares fails it too.
+
+  Removal is additive on the same terms as `defineScope`: deleting a declaration
+  leaves an inert row rather than revoking everyone's grant mid-deploy.
+
+  `ScopeService` gains `syncSystemRoles`, `findStaleSystemRoles` and
+  `pruneSystemRoles`; `Role` gains `system` and `declared`. Implementations
+  enforce immutability through the shared `assertRoleIsMutable` /
+  `assertRoleNameAvailable` guards rather than each inventing the rule.
+
+- ba6cc08: Security hardening: removed the gopass secret service and stopped MCP internal errors leaking stack traces.
+
+  **Breaking:** `GopassSecretService` and the `@pikku/core/services/gopass-secrets` subpath export are gone. The service shelled out to the `gopass` binary and its key validation accepted `../`, so a caller-supplied key could traverse out of the configured prefix namespace and read secrets outside it. Rather than harden a shell-out that few projects used, the service is removed. Anyone importing it should implement `SecretService` against their own secret backend. Pre-0.13 breaking changes still ship as a patch.
+
+  MCP internal errors (JSON-RPC `-32603`) previously always attached `data: { message, stack }`, handing any MCP client an internal stack trace. That payload is now gated on `exposeErrors`, which defaults to `!isProduction()` — the same convention `handleHTTPError` already uses. In production a client receives a bare `Internal error` with no `message` and no `stack`; `RunMCPEndpointParams` accepts an explicit `exposeErrors` to override the default.
+
+- a2e21e5: Keep the persona runtime off the production barrels
+
+  `@pikku/core/services` exported `HttpPersona`, `createHttpPersonas` and
+  `readScenarioHttpResponse` as values, and `@pikku/core/workflow` exported
+  `readScenarioHttpResponse` and `postScenarioJson`. Both are barrels a production
+  server imports, and `http-personas` reaches the actor-flow conversation runner
+  and through it the agent runner — so signing-in-as-a-persona machinery sat in the
+  module graph of every app that imported services.
+
+  Tree-shaking only removes that if you bundle. An unbundled Node or Lambda deploy
+  loads whatever the graph names, which is the case this matters in.
+
+  The values now come from `@pikku/core/persona`, which is where the rest of the
+  persona API already lives. **Types stay exactly where they were** — `import type`
+  erases, so it costs a bundle nothing, and moving them would put core in a cycle
+  with the code that describes its own function types.
+
+  `serialize-personas` generates the new import, so a regenerated
+  `pikku-personas.gen.ts` picks it up with no edit. Anything importing these four
+  values from `@pikku/core/services` or `@pikku/core/workflow` changes the
+  specifier to `@pikku/core/persona`; the names and signatures are unchanged.
+
+  A test walks each barrel's value-import graph and fails if scenario runtime
+  reappears, so this cannot regress quietly.
+
+- 457cb25: Let a persona do a real job in production, and say where it may act.
+
+  A persona was only ever a test subject: something you pointed at a stage to find
+  out what the product does wrong. But the same declaration — a name, a job, the
+  roles it holds and what it is trying to get done — describes a teammate doing
+  the work for real, and nothing about the engine cared which one it was.
+
+  Four changes make that difference explicit and enforced.
+
+  **`environments` moves to the top level of `pikku.config.json`**, out from under
+  `scenarios`. It was never a scenario's anything: `persona run` targets one, and
+  now so does `persona sync`. An environment may be flagged `production: true` —
+  a flag rather than a reserved name, because projects call it `prod`, `live` or
+  `eu-prod`, and more than one environment can be production.
+
+  **A persona may name its `environments`.** Omitting them means every configured
+  environment _except_ the production ones, so nothing reaches production by being
+  forgotten. Naming a production environment requires `disposition: 'accountable'`.
+  The rule is checked twice, on purpose: the inspector refuses to generate a
+  declaration that breaks it, and sign-in re-checks against the environment
+  actually resolved — the build check trusts the file, and the run check does not
+  trust which artifact got deployed. An unresolved environment fails closed.
+
+  **`disposition: 'accountable'`** is that production disposition. It sits opposite
+  `adversarial` on the intent axis rather than the care axis: what it changes stays
+  changed, every call is recorded against its name, and it stops to ask rather than
+  acting and reporting afterwards. Alongside it, **agents now appear in a persona's
+  computed catalogue**, gated by the same scopes as the RPCs — an agent is reached
+  rather than declared, so a persona finds the specialists its roles unlock and
+  chooses between calling the API itself and handing the work over. That also fixes
+  a latent gap: `talkTo` was wired at the target but never advertised in the
+  instructions, so it was never used.
+
+  **`pikku persona sync <environment>`** provisions them: it creates each account
+  and applies the roles it declares, additively, and never revokes. Seeding is test
+  data and `db seed` does not run in production; a teammate doing a real job still
+  needs an account and its grants. It needs both halves of an environment — its API
+  to sign the person in, its database to write the grants — and `--dry-run` reports
+  who would be provisioned, with what, and why anyone was skipped.
+
+  In the console, a virtual user now says where it may act — the environments it
+  named, or the rule when it named none — and its dossier carries the `sync`
+  command alongside the `run` one, because the account is not a by-product of a
+  run. `accountable` reads as a disposition like the rest.
+
+- 86a50b9: scenario: replace `browser: true` + `func` with per-surface bindings on `pikkuScenarioStep`
+
+  A step now declares one implementation per surface it can be driven through:
+
+  ```ts
+  export const buysTheItem = pikkuScenarioStep<{ sku: string }, { orderId: string }>({
+    name: 'buysTheItem',
+    description: 'buys the item',
+    browser: async (services, data, { browser }) => { ... },
+    default: async (services, data, { rpc }) => { ... },
+  })
+  ```
+
+  `pikku scenario run --run browser|cli|default` picks which surface the run drives,
+  and the two phases resolve bindings differently:
+  - **Actions** (`given` / `when` / `step`) run exactly one binding — the run
+    surface if it has one, otherwise `default`. A step with neither now fails with
+    `ScenarioNoSurfaceBinding` instead of silently running server-side.
+  - **Assertions** (`then`) are witnesses, not alternatives: every declared binding
+    runs and they must agree. Two surfaces reporting different things fails the run
+    with `ScenarioWitnessDisagreement` rather than reporting a pass. An assertion
+    with no witness the run can execute at all fails with `ScenarioNoWitness` —
+    without it the step returns `undefined` and renders as a tick, reporting a pass
+    for something nobody checked.
+
+  A scenario written as a step ladder that never calls `then` is now a **PKU680**
+  critical. It proves only that nothing threw, so an assertion-free ladder of
+  browser-bound actions would score perfect coverage while checking nothing.
+
+  The report gains a surface-coverage line — `n/m steps ran on browser`, counted
+  over every step, so an action that fell back to the server lowers the ratio
+  rather than needing a footnote. That also makes surfaces comparable over one
+  denominator: a scenario is `4/4` on a default run and `3/4` on a browser one.
+  Assertions that fell back are named separately and gate `--strict`, since a
+  sentence claiming the actor saw something nobody looked at is a different problem
+  from an action taking a shortcut.
+
+  **Breaking:** `browser: true` and the third `B extends boolean` type argument are
+  gone. Rename `func` to `default` (or to `browser` where the step drove a browser)
+  and drop the type argument.
+
+- 0e0f6eb: Add virtual users: LLM-driven synthetic users that work a real stage in
+  character.
+
+  A scenario proves a path somebody thought of. A virtual user works the same
+  ground without the script — it signs in as a declared persona over the app's own
+  auth, is handed the scenarios' BDD prose and the schema of every endpoint it may
+  reach, and decides for itself what to do. It asserts nothing; a run produces
+  findings, and their absence only ever means "not this time, not with this seed".
+
+  There is nothing extra to declare. A persona with a `disposition` is a virtual
+  user, and running it is what makes it one — see the `definePersonas` changeset
+  for the declaration itself. Listing, describing or running one never loads the
+  app: the inspector reads the literal declaration, the CLI writes
+  `scopes/pikku-personas-meta.gen.json`, and `MetaService.getPersonasMeta()`
+  serves it.
+
+  **Dispositions are engine dials, not prose.** Each carries its own intent weights
+  (continue / suspend / resume / abandon), temperature, re-read and repeat rates,
+  and switches: `careless` puts things down and picks them up in the wrong order,
+  `newcomer` starts with no memory, `auditor` is never offered a mutation,
+  `adversarial` is shown the catalogue its roles do not cover — being offered a
+  call it should not be able to make is the test — while those roles stay live as
+  the oracle, so a success outside them is authorization drift rather than a pass.
+
+  **Nothing is retrieved against.** The whole reachable catalogue goes into the
+  instructions (~8k tokens on a 430-RPC project, cached for the run), because a
+  ranking function would make the user only as adventurous as the ranking and lose
+  exactly the endpoints worth stumbling into. Schema first: an endpoint must be
+  described before it may be called.
+
+  **No money in core.** The engine counts steps, calls, mutations and tokens; what
+  they cost is the app's to decide through `stop(tally)`.
+
+  CLI: `pikku persona list` and `pikku persona run <environment> [name]`, with
+  flags overriding a declaration for reproduction (`--seed`, `--steps`,
+  `--disposition`). Spending is a run flag too — `--steps`, `--mutations` and
+  `--duration` bound a run, because how much you will spend today is not a fact
+  about a person. Console: a Virtual Users screen beside Scenarios, built out of
+  core's own derivation functions so it shows a run's actual inputs rather than a
+  second implementation of them.
+
+  `dev-ai-runner` now ships its own `@pikku/ai-vercel` and
+  `@ai-sdk/openai-compatible` instead of requiring them from the project. Behind a
+  proxy one openai-compatible provider answers for every prefix, so there was never
+  a per-vendor package worth making somebody install; the project's copies still
+  win when it has them, and both load from the same place or neither does.
+
 ## 0.12.72
 
 ### Patch Changes