@pikku/core 0.12.63 → 0.12.66

package/CHANGELOG.md

@@ -1,3 +1,371 @@
+## 0.12.66
+
+### Patch Changes
+
+- 5f19016: Widen the generated agent HTTP surface, and guard attachment downloads against SSRF.
+
+  `agentCaller` and `agentStreamCaller` declared only `message`, `threadId` and
+  `resourceId` (plus `context` on the stream route), so `attachments`, `model`,
+  `temperature` — all accepted by `AIAgentInput` — were unreachable over the
+  shipped HTTP contract. No deployed app could send an attachment or a per-request
+  model override. Both callers now share an `AgentCallerInput` type covering every
+  optional field and forward each one to the RPC.
+
+  Both callers declare that shape **inline** in the generic position rather than
+  behind a shared named alias: the schema extractor only reads type literals there
+  and synthesises the schema name from the function name. Behind an alias it
+  records an `inputSchemaName` with no schema generated for it, and every agent
+  HTTP call then fails at runtime with `MissingSchemaError`.
+
+  Widening that surface makes caller-supplied attachment URLs reachable, which is
+  an SSRF vector: the AI SDK downloads attachment URLs **server-side** whenever the
+  model cannot consume them natively, using an unguarded `fetch`. A caller could
+  point an attachment at the cloud metadata endpoint or another internal host and
+  have the response relayed into the model's context. `VercelAIAgentRunner` now
+  passes an `experimental_download` implementation backed by `safeFetch` (which
+  refuses private/internal hosts and non-HTTP schemes, and re-validates every
+  redirect hop) to both `streamText` and `generateText`. URLs the model supports
+  natively are passed through untouched, so the provider still fetches those
+  itself.
+
+  The runner takes an optional `allowedAttachmentHosts` allowlist, carried across
+  `withApiKey`. `safeFetch` is now exported from `@pikku/core/safe-fetch`.
+
+- 78e4778: Stop a failed message persist during an agent stream from killing the process.
+
+  The persisting channel flushes from inside `send`, which is synchronous and so cannot await the flush. Any rejection — a dropped storage connection, or a model reusing a `toolCallId`, which is a primary key in AI storage — escaped as an unhandled rejection and took the whole server down. Persistence from `send` is now best-effort and logged; the awaited `flush()` on the suspend paths still surfaces failures to its caller.
+
+- 4324652: Scope AI agent thread reads to the calling session.
+
+  The generated thread-management functions (`getAgentThreads`,
+  `getAgentThreadMessages`, `getAgentThreadRuns`, `deleteAgentThread`) keyed purely
+  off a caller-supplied `threadId` and treated `resourceId` as an optional filter,
+  so omitting it enumerated every tenant's threads.
+  - `listThreads` gains an `owners` **authorization constraint** (distinct from the
+    `resourceId` filter): an empty array matches nothing, and it is always derived
+    from the session, never from input. Implemented across the Kysely, Redis and
+    MongoDB agent run services, with LIKE/regex metacharacter escaping so an owner
+    id containing `_` or `%` cannot match a foreign owner.
+  - The three `threadId`-keyed functions are now guarded by an `isThreadOwner`
+    `pikkuPermission` rather than an in-body check. A thread that does not exist is
+    denied rather than 404'd, so it is indistinguishable from one owned by someone
+    else.
+  - New `@pikku/core/ai-agent` helpers: `canAccessThread`, `threadOwnerConstraint`,
+    `sessionPrincipals`, `isOwnedByPrincipal`.
+
+  Services destructured by a wired function are now non-optional inside it.
+
+  The inspector already aggregated the services used by every wired `func`,
+  `permissions` and `middleware` into `RequiredSingletonServices`, but the
+  generated function types defaulted their service parameter to the raw `Services`
+  — so a service declared `foo?: Foo` still arrived as possibly-undefined, forcing
+  `if (!foo) throw new MissingServiceError(...)` guards that could never fire.
+  Generated types now expose `WiredSingletonServices` / `WiredServices`
+  (`RequiredSingletonServices & Services`) and default the `RequiredServices`
+  generic of functions, permissions, middleware, auth and approval-description
+  helpers to them. Optionality now means only what it should: "this service may
+  not be created, because nothing uses it".
+
+- de044f8: Fix the agent tool-list permission filter failing open.
+
+  `buildToolDefs` filtered permission-gated tools by resolving `checkAuthPermissions` from a function's _metadata_ — a by-name lookup into the `misc/permissions` state that nothing ever populates. It therefore collected no predicate and returned `true`, so every auth-gated tool was offered to the model regardless of session (its input schema and description leaked, and the model could attempt calls that then failed at invocation).
+
+  `checkAuthPermissions` now takes the live `CorePermissionGroup` from the function/agent config, where the `pikkuAuth` brand actually survives — matching how the agent's own gate and the function runner already resolve permissions by reference. The dead by-name lookup (`getPermissionByName`) is removed. Enforcement on invocation was never affected; this closes the exposure gap in the offered tool list.
+
+- cd1a811: warn instead of silently ignoring unknown long CLI options
+
+  An unknown long option (`--sektion functions` or `--sektion=functions`) was parsed
+  into the options object and then silently dropped by the command's input schema —
+  the command ran with the real option at its default and produced plausible-but-wrong
+  output. Unknown long options are still accepted (forward compatibility is preserved),
+  but the parser now records a warning that the runner prints to stderr, e.g.
+  `Warning: Unknown option: --sektion (ignored) Did you mean --section?`.
+
+- 19fa6f0: Fix `HTTPRouteConfig` and `HTTPRoutesGroupConfig`'s default `PikkuPermission`/`PikkuMiddleware` type parameters under-specifying their own generic arguments (e.g. `CorePikkuPermission<any>` instead of `CorePikkuPermission<any, any, any>`). The missing arguments silently fell back to `CorePikkuPermission`'s own defaults (`CoreServices`, with `schema` optional) instead of `any`, so a project whose generated services type guarantees `schema` is always present (any project using `WiredServices`-style non-optional services) failed to type-check against `defineHTTPRoutes`/`wireHTTPRoutes` with a misleading `index signature` error.
+- b501612: Enforce authorization consistently across `pikku*` primitives.
+  - `pikkuAIAgent` now enforces `permissions` (previously accepted but never
+    checked) and gains `auth` and `scopes`. Scopes are checked before permissions.
+    `auth` defaults to `false`, matching `pikkuSessionlessFunc`, since agents are
+    typically invoked from an already-authenticated function or from sessionless
+    contexts such as crons and queue workers.
+  - `pikkuWorkflowFunc` / `pikkuWorkflowComplexFunc` schema config gains `auth`
+    and `scopes` alongside `permissions`.
+  - `pikkuScenario` no longer accepts `auth`, `scopes`, or `permissions` —
+    scenarios drive the app as actors and authorize per step.
+  - `wireGateway` no longer accepts `permissions`. A gateway proxies to an agent,
+    so access is governed by normal auth plus the target agent's own rules.
+  - Removed the dead `permissions` field from `CoreWorkflow`, which was never read.
+
+  Closed two paths that reached user code without authorization:
+  - Gateway handlers were invoked directly, so a handler's own `auth`, `scopes`
+    and `permissions` were never evaluated. Webhook, websocket and listener
+    gateways now invoke the handler through the function runner. Handlers are
+    sessionless by default (inbound gateway traffic is platform-authenticated by
+    the adapter, not session-bearing); declare `auth: true` to require a session.
+    A gateway's own `auth` field is now honoured too — it was previously ignored.
+    Gateway middleware runs before the gate, so `wire.setSession()` in gateway
+    middleware — the idiomatic way to map a verified platform sender to a user —
+    is visible to the handler's `auth` and `scopes`.
+  - Resuming a suspended agent run (`resumeAIAgentSync`, `resumeAIAgent`) checked
+    run ownership but never re-ran the agent's own gate, so a scope or permission
+    revoked while a run was suspended did not prevent the caller from resuming it
+    and approving its pending tool calls. Both now re-run `assertAgentAuthorized`
+    before any state is mutated.
+
+- eb37b1e: Fix `voiceInput` middleware losing the runner receiver: it grabbed
+  `aiAgentRunner.transcribe` as a bare method reference, so calling it left `this`
+  undefined and threw `Cannot read properties of undefined (reading 'getModel')`
+  on the first audio attachment. It now calls `aiAgentRunner.transcribe(...)`
+  directly, preserving the receiver.
+
+## 0.12.65
+
+### Patch Changes
+
+- 1a86d3f: Fix a fanout collapsing into a single step, and preserve graph node config.
+  - A fanout took its `stepName` from the first step of its body. Node ids _are_
+    step names, so the loop and that step got the same id and the step overwrote
+    the loop: `await Promise.all(users.map(...))` rendered as one plain call, and
+    everything after the loop became unreachable. A fanout is not itself a cached
+    step, so it no longer borrows a name.
+  - A `workflow.sleep` or `workflow.suspend` inside a fanout body was dropped at
+    extraction — `FanoutStepMeta.body` was typed RPC-only. It now admits sleep and
+    suspend, and the regenerated body emits them.
+  - Regenerating a `pikkuWorkflowGraph` dropped `onError`, `retries` and
+    `retryDelay` from every node, and graph-level `notes`. All four are honoured
+    at runtime, so the round trip silently changed behaviour.
+
+- 1a86d3f: Support multi-step fanout bodies in DSL workflows.
+
+  A `Promise.all(array.map(...))` (or `for...of`) body containing more than one
+  `workflow.do` call previously extracted only a single step: `const`-captured
+  steps were skipped entirely by the parallel extractor, so a body like
+
+  ```ts
+  await Promise.all(
+    users.map(async (u) => {
+      const digestData = await workflow.do('Get pipeline', 'getDigestData', {
+        userId: u.id,
+      })
+      await workflow.do('Send digest', 'sendDigestEmail', { ...digestData })
+    })
+  )
+  ```
+
+  produced a graph with `getDigestData` missing and `sendDigestEmail` referencing
+  an unregistered variable. `FanoutStepMeta.child` is replaced by
+  `FanoutStepMeta.body: RpcStepMeta[]`, holding the per-iteration steps inline in
+  the same workflow — no sub-workflow boundary. Per-iteration `const` bindings are
+  now registered so later steps in the same iteration can reference them, and the
+  sequential path no longer hard-errors on bodies with more than one step.
+
+- 1a86d3f: Add `onError` compensation to DSL workflows.
+
+  A DSL workflow had no way to express error handling at all — `try/catch` is not
+  an allowed statement, and step options carried only `retries`/`retryDelay`. A
+  step can now name a compensation RPC:
+
+  ```ts
+  await workflow.do(
+    'Charge',
+    'chargeCard',
+    { id },
+    {
+      retries: 3,
+      onError: 'refundOrder',
+    }
+  )
+  ```
+
+  Semantics mirror a graph node's `onError` exactly: once the step's retries are
+  exhausted the handler is invoked with `{ error: { message } }` and the original
+  error is still thrown. This is compensation, not recovery — the workflow fails
+  either way. The handler runs as its own durable step, so a replay cannot
+  compensate twice, and it does not inherit `onError` itself.
+
+  The handler is materialised as a real graph node, so it is wired like any other
+  RPC and the console draws a dashed red "on error" edge to it rather than the
+  route being invisible.
+
+- 1a86d3f: Stop silently dropping switch cases and spread returns from workflow graphs.
+  - A fall-through case (`case 'a': case 'b': ...`) recorded only the last value.
+    A run entering on `'a'` therefore appeared to match no case at all. Empty
+    clauses now carry through to the entry they fall into — the next non-empty
+    case, otherwise `default`, otherwise the switch exit.
+  - `return { ...r, extra: 1 }` produced a return node listing only `extra`, so
+    the graph claimed an output shape the workflow does not have, with no
+    diagnostic. `return r` produced no return node at all. `ReturnStepMeta` now
+    records a `spread` list, and the regenerated code emits it.
+
+- 1a86d3f: Stop corrupting values when regenerating a workflow from its graph.
+  - A numeric `workflow.sleep('Wait', 5000)` came back as `'5000'`, and a numeric
+    `retryDelay` likewise. Durations are `string | number`; only strings are
+    quoted now.
+  - An assignment to a context variable was stored as an opaque `value`, so
+    `count = count + 1` regenerated as `count = 'count + 1'` — an expression
+    turned into a string literal. `SetStepMeta` now carries a separate
+    `expression` field (mirroring `SwitchCaseMeta`), so a string literal and a
+    code expression are no longer indistinguishable in the meta.
+  - A `next` that was not a single node id was coerced with a string cast: an
+    array became the bogus id `'a,b'` and a branch-key record became
+    `'[object Object]'`, severing every downstream node. Arrays, key-based
+    routing tables and condition lists now each render in their own shape.
+  - A `filter`/`some`/`every` node with no `outputVar` emitted
+    `const undefined = ...`, which does not parse.
+
+- 1a86d3f: Keep a `workflow.sleep` whose duration is only known at runtime (a loop
+  variable, a field off the input). The closure evaluates it, so it is legal DSL;
+  its source text is recorded as an `expression` and emitted raw when regenerating
+  code, as a set step already does.
+- 3d76f51: Add an optional `docsUrl` to `wireSecret`, `wireVariable`, and `wireCredential`, so a console or deploy UI reporting a missing value can link the user to where they obtain it instead of showing a bare identifier.
+
+## 0.12.64
+
+### Patch Changes
+
+- 7ab5287: Security hardening (follow-up to the #966 C1/C3 fixes):
+  - SSRF (C1): `isPrivateHost` now also rejects alias/encoded forms that resolve to internal targets — trailing-dot FQDNs (`localhost.`), the reserved `*.localhost` name, IPv4-mapped IPv6 (`::ffff:127.0.0.1`), octal/decimal/hex-encoded IPv4 (`0177.0.0.1`, `2130706433`, `0x7f000001`), and the full `fe80::/10` link-local range. `safeFetch` also strips `Authorization` and `Cookie` headers whenever a redirect crosses origin so credentials cannot leak to a redirected host.
+  - Forgeable approval markers (C3): the sub-agent approval marker is now identified by a non-forgeable `Symbol` brand set only by framework code, instead of the plain `__approvalRequired` string key. A delegating tool's LLM-shaped `result.object` (plain JSON) can no longer conjure an approval/suspension even though the tool is allowed to forward approvals.
+
+- e86bc17: Security + feature: bind AI agent thread/run ownership to the authenticated session and add `sessionScope: 'user' | 'org'` to agents. The owner key is now the trusted principal (`session.userId`, or `session.orgId` for org-scoped agents) composed with the client `resourceId` (`principal:resourceId`), so a client-supplied `resourceId` sub-partitions within the caller's own boundary but can never widen access to another user's or org's threads. Resolution is idempotent (safe for sub-agent recursion and resume); org scope with no session org is denied; sessionless `user` wirings fall back to the bare `resourceId`.
+- a9b96a0: Security: only honor the `__approvalRequired` suspension marker from framework sub-agent tools (`forwardsApproval`), so an attacker-influenced ordinary tool result can no longer forge an approval/suspension.
+- 3f7fc54: Security: SSRF-harden outgoing webhook delivery and voice-input audio fetch (validate scheme + block private/internal hosts, re-validate every redirect hop via a shared `safeFetch`); stop the channel stream-middleware cache from reusing an earlier run's per-invocation middleware closures across runs.
+- c478794: Simplify authorization to be session + function based (#972). Permissions are now function-scoped only: global permissions AND together, a function's own permissions OR together, and the two are independent gates that both must pass — a broad global can no longer satisfy an admin-only function. Removed wire-, tag-, and HTTP-route-level permissions (`addTagPermission`, `addHTTPPermission`, wire-level `permissions` on HTTP/channel/MCP wirings). Tags are now organizational only. `auth` (session presence) and tag/HTTP middleware are unchanged.
+- 3f04ae4: Fix `pikku dev` hot-reload memory leak (#975). Changed user files were re-imported under a fresh URL on every reload (a `data:` URL on Node, a uniquely-named temp sibling on Bun), which permanently leaked a record in the native ESM loader map — the dev server climbed to `JavaScript heap out of memory` during long editing sessions (worse on Bun, which the sandbox dev server runs on). Reloading now goes through an evictable module runner that transpiles the source and runs it via `vm.compileFunction`, holding exports under a stable path key so each edit overwrites one slot and the previous module is collected. Heap stays bounded on both runtimes.
+- 90d9f04: Scope `console:getAddonInstalledPackage` to the addon's own `.pikku` metadata.
+
+  Previously every addon returned the _app's_ secrets/wirings (read from the app's
+  `.pikku` root), so the installed-package view couldn't show what a given addon
+  actually requires. `MetaService` gains optional `readPackageFile`/`readPackageDir`
+  helpers (implemented by `LocalMetaService`, which resolves the addon package's
+  root from node_modules), and `getAddonInstalledPackage` now reads secrets,
+  variables, wirings, schemas, README and package.json from the addon package
+  itself. It also reads and returns the addon's `credentials` meta (OAuth2 + wire
+  credentials), which was never surfaced before — entries with an `oauth2` field
+  are the OAuth integrations to connect.
+
+- cb079cc: A workflow-graph node's `func` can now reference a registered AI agent by name, dispatched as an agent run like sub-workflows, with `ref()` resolving the agent's output keys.
+- cb079cc: `pikkuAIAgent` gains a `workflows: []` capability: a referenced workflow is exposed to the LLM as a tool that runs inline and returns its output.
+- 0a7db82: AI agent tool `execute()` failures are now logged via `logger.error` unconditionally (then rethrown), instead of only surfacing when a tool-call middleware hook is registered.
+- 981c4db: Add a model-baked `AIEmbeddingService` interface and optional `aiEmbedding` slot on `CoreSingletonServices`, with separate `embedDocuments`/`embedQuery` methods for vector-store addons.
+- 13474a6: Generate a `ScopeId` union from `wireScope` declarations.
+
+  `pikku all` now emits `.pikku/scopes/pikku-scopes.gen.ts` with a `ScopeId` union
+  of every declared scope, plus a wildcard form for each node that has
+  descendants. A project's generated `pikkuFunc` narrows `scopes` to that union,
+  so an undeclared scope is a compile error with editor autocomplete:
+
+  ```ts
+  wireScope({ admin: { scopes: { invoices: { scopes: { create: {} } } } } })
+
+  pikkuFunc({
+    scopes: ['admin:invoices:create'],  // ✓ autocompleted
+    func: ...,
+  })
+
+  pikkuFunc({
+    scopes: ['admin:invoice:create'],   // ✗ compile error (typo)
+    func: ...,
+  })
+  ```
+
+  The inspector independently rejects undeclared scopes, so a cast that defeats
+  the compiler is still caught at build time.
+
+  Also fixes `getArrayPropertyValue` dropping any array behind a cast — idiomatic
+  `tags: ['a'] as const` was previously invisible to the inspector and silently
+  omitted from meta.
+
+- 5a2b0d5: Prune removed addons on `pikku dev` hot-reload. Deleting an addon wiring (`*.addon.ts`) regenerated `.pikku` on disk but left its `wireAddon` entry stranded in the live `pikkuState(null,'addons','packages')` map until a full restart (the reimport path is add-only), so `getInstalledAddons` kept reporting deleted addons. `reloadGeneratedMeta`'s sibling `reconcileAddonRegistry(declaredNamespaces)` now drops any addon namespace the fresh inspection no longer declares, and the dev watcher calls it with `inspectorState.rpc.wireAddonDeclarations`. Routes already reconcile (http meta is replaced wholesale + router reset); function-impl entries are intentionally left since the workflow service registers framework internals there that aren't in the generated set.
+- 13474a6: feat(scopes): grant scopes directly to a user, not only through roles
+
+  A scope can now be granted to a user directly, outside of any role.
+  `resolveScopes` returns the union of a user's role-derived scopes and their
+  direct grants, so a one-off capability no longer requires inventing a role.
+  - `@pikku/core`: `ScopeService` gains `addScopeToUser` / `removeScopeFromUser` /
+    `listUserScopes`.
+  - `@pikku/kysely`: a new `pikku_user_scope` table (FK into `pikku_scopes`, so the
+    database still refuses an undeclared grant; `ON DELETE CASCADE` from `user`,
+    so deleting a user takes their direct grants with it). `resolveScopes` unions
+    it with the role join.
+  - `@pikku/addon-console`: `scopeAddScopeToUser` / `scopeRemoveScopeFromUser`
+    (gated by `pikku:scopes:manage`), and `scopeListUserRoles` now also returns
+    `directScopes`.
+  - `@pikku/console`: a **Direct scopes** section in the user roles drawer to grant
+    and revoke scopes directly, showing them distinctly from the resolved union.
+
+  Also: the Scopes page now distinguishes a permission error (a console admin
+  without `pikku:scopes:read`) from an actual scope-service outage, instead of
+  showing "the scope service may be unavailable" for both.
+
+- ee040dc: fix(ai-agent): resolve addon-scoped services when generating a tool's approval description. The `approvalDescription` for an addon function ran against a cold per-package services cache and silently fell back to root services, so descriptions reading addon-only services (e.g. a todo store) threw and the approval `reason` never reached the client. It now builds the addon's singleton services the same way the tool's `execute` path does (#971).
+- cb079cc: `pikkuWorkflowGraph` nodes accept an optional `notes?: string` and the graph an optional `notes?: string[]`; notes are documentation only and excluded from `graphHash`.
+- 13474a6: feat: ScopeService.listScopes
+
+  Exposes the scope vocabulary held in the store — everything a role can be
+  composed from — flagging any scope that is still present but no longer declared
+  in code (inert, and awaiting `pikku scopes prune`).
+
+- 9f0d0eb: Migrate the `--oauth` addon scaffold off `OAuth2Client`. A scaffolded OAuth2
+  addon service used to construct `new OAuth2Client(config, appCredentialSecretId,
+secrets)` and do its own token exchange/refresh — the responsibility better-auth
+  now owns via the credential service. The `pikku new addon --oauth` scaffold (and
+  the OpenAPI `--openapi` generator) now emit a service that receives a ready
+  access token: `services.ts` uses `createWireServices` + `wire.getCredential<{
+accessToken: string }>(name)` and the service does a plain `fetch` with
+  `Authorization: Bearer ${accessToken}`, matching the existing per-user
+  bearer/apikey credential scaffold. With no remaining consumers, `OAuth2Client`
+  (`@pikku/core/oauth2`) and its test are removed; the `./oauth2` export keeps the
+  `OAuth2AppCredential` / `OAuth2Token` types.
+- 13474a6: Add scopes: declared, statically-checked authorization scopes on pikkuFunc.
+
+  A scope is a capability string the session must hold. Unlike `permissions` —
+  which OR together across global/wire/tag/function levels — scopes are an AND
+  gate that runs before them, so adding one can only ever narrow access.
+
+  ```ts
+  wireScope({
+    admin: {
+      scopes: { invoices: { scopes: { create: {} } } },
+    },
+  })
+
+  export const createInvoice = pikkuFunc({
+    scopes: ['admin:invoices:create'],
+    func: async (services, data) => { ... },
+  })
+  ```
+
+  The gate runs after the auth check and before the request body is evaluated,
+  since scopes depend only on the session. A session lacking a required scope
+  gets a `MissingScopeError` (403) naming it. Wildcards grant subtrees:
+  `admin:*` satisfies `admin` and `admin:invoices:create`.
+
+  `session.scopes` is populated by whoever builds the session — core reads it and
+  never fetches, keeping the runner free of I/O. The new `ScopeService` interface
+  resolves scopes at the session boundary.
+
+- 70fa400: Add outgoing webhooks — `webhookService.send()` enqueues signed deliveries onto a retrying queue, `@pikku/kysely`'s `KyselyWebhookService` persists per-attempt delivery history, and `@pikku/console` gains a read-only `/webhooks` page; also caches resolved secrets in `TypedSecretService` and registers inline-`func` metadata for queue/scheduler/trigger/gateway wirings.
+- 7b2ea23: `wireAddon` can install one addon package as multiple named instances, each with its own per-instance singleton services and `secretOverrides`/`variableOverrides`/`credentialOverrides` that alias logical names to real project secrets/variables/credentials.
+- 1dc77d5: Remove the old, pre-better-auth OAuth2 credential runtime now that the
+  `credentialOAuth` plugin owns credential linking, storage and refresh.
+  - `@pikku/core`: drop the unused `createOAuth2Handler` HTTP-routes flow (and its
+    `CreateOAuth2HandlerOptions`) from the `./oauth2` entrypoint. The credential
+    schema types (`OAuth2AppCredential`, `OAuth2Token`) and the `OAuth2Client`
+    API helper remain exported.
+  - `@pikku/addon-console`: delete the six `oauth-*` console functions
+    (connect/disconnect/status/exchange-tokens/refresh-token/test-token) and the
+    `OAuthService` behind them — credential connections now flow through
+    better-auth's `/credential-oauth/link` + `/callback`.
+  - `@pikku/console`: the credential UI no longer calls the removed
+    `console:oauth*` RPCs. Per-user and singleton (platform) OAuth2 credentials
+    connect via the `/credential-oauth/link` full-page redirect and disconnect via
+    `console:credentialDelete`; the `/oauth/callback` popup page is removed.
+
+- 416606c: Fix a TypeScript 6 `PikkuWire` constraint collapse that made `rpc` a required field: narrow `PikkuRPC` default type params from `any` to `Function` and replace bare `any` TypedRPC args with `PikkuRPC`.
+- d2a6eea: Add `wireRemoteAddon` — consume a hosted addon's `remote: true` RPCs transparently over HTTP, with the addon installed as a devDependency (types only). `rpc('ns:fn', input)` dispatches to the host's `/remote/rpc/:rpcName`, authenticating as a client with a token bound from a local source (`{ credentialId }` per-user, `{ secretId }` platform, or a custom `resolve()`), or omitted for a public surface. This is any-machine → hosted-library client auth, distinct from the trusted mesh (`PIKKU_REMOTE_SECRET`). A new `.remote.gen.d.ts` RPC map exposes only the `remote: true` surface to consumers. `pikku` verify errors if a `wireRemoteAddon` package is a production dependency (or missing) instead of a devDependency, and if a bound `credentialId`/`secretId` isn't wired.
+- 30e62ee: Add `workflow.approval(reason, { schema, expiry })` — a return-valued, expiring human-in-the-loop gate that stays closed until a decision is recorded (via `workflowService.approveStep` or `POST /workflow/:workflowName/approve/:runId`), unlike the one-shot `workflow.suspend()`.
+
 ## 0.12.63
 
 ### Patch Changes

package/dist/dev/hot-reload.js

@@ -1,13 +1,12 @@
 import { watch } from 'node:fs';
-import { stat, readFile, copyFile, rm } from 'node:fs/promises';
-import { basename, dirname, join, resolve, relative } from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { register } from 'tsx/esm/api';
+import { stat } from 'node:fs/promises';
+import { basename, join, resolve, relative } from 'node:path';
 import { pikkuState } from '../pikku-state.js';
 import { clearMiddlewareCache } from '../middleware-runner.js';
 import { clearPermissionsCache } from '../permissions.js';
 import { clearChannelMiddlewareCache } from '../wirings/channel/channel-middleware-runner.js';
 import { httpRouter } from '../wirings/http/routers/http-router.js';
+import { createModuleRunner } from './module-runner.js';
 export * from './reload-meta.js';
 const isFunctionConfig = (value) => {
     return (typeof value === 'object' &&
@@ -33,57 +32,18 @@ const findCompiledFile = async (tsFile, srcDir, pikkuDir) => {
     }
     return null;
 };
-// Use data: URLs to import modules. This bypasses TypeScript loaders
-// (e.g. tsx) that intercept file:// imports and break dynamic ESM loading.
-// Each import gets unique content so there's no module cache to worry about.
-let tsxRegistered = false;
-const ensureTsxRegistered = () => {
-    if (tsxRegistered)
-        return;
-    register();
-    tsxRegistered = true;
-};
-let tempCounter = 0;
-const reimportModule = async (filePath, useTsx = false) => {
-    try {
-        if (useTsx) {
-            // Import a uniquely-named sibling copy: a `?t=` query does NOT bust
-            // the cache on either runtime (Bun keys module identity on the bare
-            // path; tsx's transform cache keys on the file path too), so a fresh
-            // path is the only reliable re-import. Same directory → identical
-            // resolution for relative and package-`imports` (#…) specifiers. The
-            // dot-prefix keeps it out of the watcher.
-            if (!process.versions.bun) {
-                // Node needs tsx's loader to import raw .ts; Bun imports it natively.
-                ensureTsxRegistered();
-            }
-            const abs = resolve(filePath);
-            const tempPath = join(dirname(abs), `.pikku-hot-${++tempCounter}-${basename(abs)}`);
-            await copyFile(abs, tempPath);
-            try {
-                return await import(pathToFileURL(tempPath).href);
-            }
-            finally {
-                await rm(tempPath, { force: true }).catch(() => {
-                    // Best-effort temp cleanup; a leftover dotfile is watcher-ignored.
-                });
-            }
-        }
-        const content = await readFile(resolve(filePath), 'utf-8');
-        const dataUrl = 'data:text/javascript;base64,' + Buffer.from(content).toString('base64');
-        return await import(dataUrl);
-    }
-    catch {
-        return null;
-    }
-};
+// Changed user files are re-run through an evictable module runner keyed by a
+// stable path (createModuleRunner), NOT re-imported under a fresh URL. A
+// fresh-URL import (a `data:` URL on Node, a uniquely-named temp sibling on
+// Bun) permanently leaks a record in the native ESM loader map on every
+// reload, OOMing long editing sessions; the runner overwrites a single slot so
+// the previous module is collected. See ./module-runner.ts.
 const isWatchedTsFile = (filename) => {
     return (filename.endsWith('.ts') &&
         !filename.endsWith('.test.ts') &&
         !filename.endsWith('.d.ts') &&
         !filename.endsWith('.gen.ts') &&
-        // Hidden files: editor/sed atomic-write temps and our own hot-reload
-        // sibling copies must never trigger a reload of themselves.
+        // Hidden files: editor/sed atomic-write temps must never trigger a reload.
         !basename(filename).startsWith('.'));
 };
 export async function pikkuDevReloader(options) {
@@ -92,6 +52,7 @@ export async function pikkuDevReloader(options) {
     const absPikkuDir = resolve(pikkuDir);
     const watchers = [];
     const functionsMap = pikkuState(null, 'function', 'functions');
+    const moduleRunner = createModuleRunner();
     const handleFileChange = async (changedTsFile) => {
         const start = Date.now();
         const reloadedNames = [];
@@ -101,11 +62,7 @@ export async function pikkuDevReloader(options) {
             return;
         const compiledFile = await findCompiledFile(changedTsFile, srcDir, absPikkuDir);
         const importPath = compiledFile ?? changedTsFile;
-        const usedTsxFallback = !compiledFile;
-        if (usedTsxFallback) {
-            logger.debug(`Hot-reload using tsx fallback for: ${relative(process.cwd(), changedTsFile)}`);
-        }
-        const mod = await reimportModule(importPath, usedTsxFallback);
+        const mod = await moduleRunner.run(importPath);
         if (!mod) {
             logger.error(`Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)`);
             return;
@@ -197,6 +154,7 @@ export async function pikkuDevReloader(options) {
             for (const watcher of watchers) {
                 watcher.close();
             }
+            moduleRunner.clear();
         },
         // Drain the queue of recently re-imported files and import them again.
         // A dev-server watcher calls this AFTER its codegen pass has refreshed

package/dist/dev/module-runner.d.ts

@@ -0,0 +1,14 @@
+export interface PikkuModuleRunner {
+    /** Run a user module by absolute path, returning its exports. Repeated runs
+     *  of the same path overwrite a single registry slot (the previous module is
+     *  collected). Returns `null` if transpile/compile/evaluation fails, so the
+     *  caller can keep the previously-loaded code. */
+    run: (absPath: string) => Promise<Record<string, unknown> | null>;
+    /** Drop a single module from the registry. */
+    evict: (absPath: string) => void;
+    /** Drop every module from the registry. */
+    clear: () => void;
+    /** Number of modules currently held. */
+    readonly size: number;
+}
+export declare const createModuleRunner: () => PikkuModuleRunner;

package/dist/dev/module-runner.js

@@ -0,0 +1,59 @@
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { compileFunction } from 'node:vm';
+let transformSync;
+const loadTransform = async () => {
+    if (transformSync)
+        return transformSync;
+    // esbuild is a dev-only dependency, hoisted from @pikku/cli at runtime — the
+    // same lazy pattern the reloader previously used for tsx. It is never loaded
+    // in production runtimes (the `./dev` export is dev-only).
+    const esbuild = await import('esbuild');
+    transformSync = esbuild.transformSync;
+    return transformSync;
+};
+export const createModuleRunner = () => {
+    const registry = new Map();
+    const run = async (filePath) => {
+        const absPath = resolve(filePath);
+        try {
+            const transform = await loadTransform();
+            const source = await readFile(absPath, 'utf-8');
+            // No sourcemap: an inline sourcemap embeds a base64 copy of the source
+            // that the engine retains per compile, reintroducing linear growth on
+            // Node — the exact leak this runner exists to remove. `filename` still
+            // anchors stack traces to the user file.
+            const { code } = transform(source, {
+                loader: absPath.endsWith('.ts') ? 'ts' : 'js',
+                format: 'cjs',
+                sourcefile: absPath,
+            });
+            const fn = compileFunction(code, ['require', 'exports', 'module', '__filename', '__dirname'], { filename: absPath });
+            const require = createRequire(pathToFileURL(absPath));
+            const moduleObj = { exports: {} };
+            fn(require, moduleObj.exports, moduleObj, absPath, dirname(absPath));
+            registry.set(absPath, moduleObj.exports);
+            return moduleObj.exports;
+        }
+        catch {
+            // Transpile/compile/evaluate failure (a bad edit, or the one known
+            // limitation — a file using top-level `await`, which can't be emitted in
+            // `cjs` form). Return null so the caller keeps the previously-loaded code.
+            return null;
+        }
+    };
+    return {
+        run,
+        evict: (filePath) => {
+            registry.delete(resolve(filePath));
+        },
+        clear: () => {
+            registry.clear();
+        },
+        get size() {
+            return registry.size;
+        },
+    };
+};

package/dist/dev/reload-meta.d.ts

@@ -22,3 +22,16 @@ export interface ReloadGeneratedMetaOptions {
  * never imported); those still need a restart.
  */
 export declare function reloadGeneratedMeta(options: ReloadGeneratedMetaOptions): Promise<void>;
+/**
+ * Prunes the live addon registry down to what the current source still declares.
+ *
+ * Dev hot-reload re-imports only changed/added files, so a deleted `*.addon.ts`
+ * leaves its `wireAddon` entry stranded in `pikkuState(null,'addons','packages')`
+ * until a full restart — the reason `getInstalledAddons` reports removed addons.
+ * The Map holds definitions (namespace → package config), not runtime state, so
+ * dropping any namespace the fresh inspection no longer declares is safe.
+ *
+ * `declaredNamespaces` is the set of `wireAddon` names from the just-regenerated
+ * inspection (`inspectorState.rpc.wireAddonDeclarations.keys()`).
+ */
+export declare function reconcileAddonRegistry(declaredNamespaces: Iterable<string>, logger?: Logger): void;

package/dist/dev/reload-meta.js

@@ -97,3 +97,25 @@ export async function reloadGeneratedMeta(options) {
         logger.error(`Hot-reload schema recompilation failed: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+/**
+ * Prunes the live addon registry down to what the current source still declares.
+ *
+ * Dev hot-reload re-imports only changed/added files, so a deleted `*.addon.ts`
+ * leaves its `wireAddon` entry stranded in `pikkuState(null,'addons','packages')`
+ * until a full restart — the reason `getInstalledAddons` reports removed addons.
+ * The Map holds definitions (namespace → package config), not runtime state, so
+ * dropping any namespace the fresh inspection no longer declares is safe.
+ *
+ * `declaredNamespaces` is the set of `wireAddon` names from the just-regenerated
+ * inspection (`inspectorState.rpc.wireAddonDeclarations.keys()`).
+ */
+export function reconcileAddonRegistry(declaredNamespaces, logger) {
+    const declared = new Set(declaredNamespaces);
+    const addons = pikkuState(null, 'addons', 'packages');
+    for (const namespace of [...addons.keys()]) {
+        if (!declared.has(namespace)) {
+            addons.delete(namespace);
+            logger?.info(`• Removed unwired addon "${namespace}"`);
+        }
+    }
+}

package/dist/errors/errors.d.ts

@@ -60,6 +60,18 @@ export declare class MissingCredentialError extends PikkuError {
     };
     constructor(credentialName: string, credentialType: 'oauth2' | 'apikey', connectUrl?: string);
 }
+/**
+ * The session does not hold a scope required by the function. The payload
+ * names the missing scope so the client can surface what to request.
+ * @group Error
+ */
+export declare class MissingScopeError extends PikkuError {
+    payload: {
+        error: 'missing_scope';
+        scope: string;
+    };
+    constructor(scope: string);
+}
 /**
  * The session is readonly and cannot access a non-readonly function.
  * @group Error

package/dist/errors/errors.js

@@ -105,6 +105,25 @@ addError(MissingCredentialError, {
     status: 403,
     message: 'A required credential is not configured.',
 });
+/**
+ * The session does not hold a scope required by the function. The payload
+ * names the missing scope so the client can surface what to request.
+ * @group Error
+ */
+export class MissingScopeError extends PikkuError {
+    payload;
+    constructor(scope) {
+        super(`Missing required scope: ${scope}`);
+        this.payload = {
+            error: 'missing_scope',
+            scope,
+        };
+    }
+}
+addError(MissingScopeError, {
+    status: 403,
+    message: 'The session does not hold a scope required by this function.',
+});
 /**
  * The session is readonly and cannot access a non-readonly function.
  * @group Error