@pikku/core 0.12.78 → 0.12.80

package/CHANGELOG.md

@@ -1,3 +1,237 @@
+## 0.12.80
+
+### Patch Changes
+
+- 41c1a95: Move the adapter surface to `@pikku/core/ecosystem` so the root can promise stability
+
+  The types and helpers a runtime adapter, a service package, the code generator and the CLI implement against sat on the package root, mixed in with the API application code uses. That made the root impossible to commit to: `runPikkuFunc` was reshaped repeatedly over the last year while every field on `PikkuWire` survived untouched, and promising stability on both would mean promising the weaker of the two.
+
+  They now live on `@pikku/core/ecosystem`. The root is what 0.13's compatibility promise covers.
+
+  Not `/internal`: generated bootstrap files import from here, so the specifier lands in the user's own `.pikku` directory — telling someone they are touching internals when the code generator put it there is both wrong and self-defeating. Not `/runtime` either: that reads as runtime-versus-compile-time, `packages/runtimes/*` already claims the word, and the CLI is the largest consumer.
+
+  `./internal` remains as an alias to the same module, because the pinned bootstrap CLI still emits it.
+
+  Breaking for adapter authors; appropriate pre-0.13.
+
+- ce96383: A child workflow now inherits the `pikkuUserId` its parent was running as
+
+  `PikkuWorkflowService` filled parts of the wire it builds for a workflow body and for a child run from the RPC service it had been handed — `rpcService.wire?.session`, `rpcService.wire?.rpc`, `rpcService.wire?.pikkuUserId`. `PikkuRPC` has no `wire`, and neither does the object the RPC service actually returns, so every one of those reads was `undefined`; the `rpcService: any` parameter type is what kept it quiet. The visible consequence was that a child workflow started from a step ran as nobody.
+
+  Those reads now come from the run record, which is durable and survives the process boundary a queued step crosses. `session` and `rpc` are not copied at all: `runPikkuFunc` attaches `rpc` lazily per invocation and resolves the session from the session store, so both were overwritten moments later regardless. The wires these paths build are typed `PikkuRawWire`, which is what they have always been.
+
+  `PikkuRPC` also now declares `rpcWithWire`, which the RPC service has always returned and the workflow service has always called.
+
+- 7e60867: Delete exports nothing references
+
+  A sweep of the `@pikku/core` surface for exports with no consumer anywhere in the repo — no package, template, verifier or e2e project imports them: `ExtractFunctionOutput`, `CLICommandDefinition`, `RequestHeaders`, `HTTPFunctionsMeta`, `HTTPWiringMiddleware`, `JsonRpcError`, `TriggerSourceInfo`, `getMCPResources`, `getMCPPrompts`, `onGraphNodeComplete` and `InputRef`.
+
+  Every one was a compatibility promise with nothing on the other end of it. Removing them narrows what 0.13 has to keep stable.
+
+  `isRef` looked like the twelfth, and isn't. It is the type guard that reads what `createRef` writes — the `__isRef` brand marking a graph node input as "substitute another node's output here". Nothing imported it because neither it nor `RefValue` was reachable from any entry point, so the one consumer that needed it, the inspector's graph serializer, had reimplemented the same four conditions privately as `isRefValue` along with its own structural copy of `RefValue`. Deleting `isRef` would have made that duplicate permanent, with the brand's shape asserted in two places free to drift apart.
+
+  So `isRef` and `RefValue` are exported from `@pikku/core/workflow` instead, and the inspector imports them rather than keeping its own copy.
+
+- f8f1244: Fix `onConnect`/`onDisconnect` wrapper handlers, and correct `wireChannel`'s generic arguments
+
+  `CoreChannel` accepts three shapes for a handler: a function config, a simple wrapper (`{ func, middleware }`), and a wrapper around a function config (`{ func: { func }, middleware }`). `wireChannel` unwrapped the third shape for `onMessage` and `onMessageWiring`, but registered `onConnect` and `onDisconnect` as-is — so the registered config's `func` was an object, and the function runner threw when it tried to call it. All three shapes now register a callable config on every handler.
+
+  `wireChannel`'s type arguments were also misaligned with `CoreChannel`'s parameter list: `PikkuPermission` was being passed into the `ChannelConnect` slot and `PikkuMiddleware` into `ChannelDisconnect`, which made `wireChannel({ onConnect: { func } })` fail to typecheck with "not assignable to `CorePikkuPermission`". End users did not see this — the CLI's generated `wireChannel` wrapper casts before calling core — but anyone importing `wireChannel` from `@pikku/core/channel` directly did. The signature is now `wireChannel<In, Channel>(channel: CoreChannel<In, Channel>)`; the three surplus type parameters were never used for anything correct and are gone.
+
+- dcf20cb: Pin the public API, and declare which modules have import-time side effects
+
+  Nothing caught a change to what `@pikku/core` publishes. An export could appear, vanish, or have a member's signature change, and the only signal was a downstream break after release.
+
+  `public-surface.json` now pins every runtime export reachable through a `package.json` `exports` subpath, and `api-report.md` pins the API at **member** level — a method added to an interface is the change that breaks a consumer's build, and an export list cannot see it. Both regenerate from the code and are asserted against it, so widening the API is a visible diff rather than a side effect of an `export *`.
+
+  The report is written to state what the API _is_ rather than merely list identifiers, so the diff is readable by a reviewer.
+
+  `sideEffects` is declared as an allowlist rather than `false`: core genuinely has some. The error registry is built by `addError` calls that run on import, so claiming `sideEffects: false` would let a bundler drop it and leave `getErrorResponse` unable to find any error. A test detects the modules that actually have side effects and fails if the allowlist disagrees.
+
+- 6512384: feat: give scenarios a `scenario.context` their `before`/`after` hooks can read
+
+  A hook only ever received the run's _input_, so teardown could not reach an id
+  the scenario body minted — which is exactly what a failing run needs to clean
+  up. `wire.scenario.context` is a per-run scratch object shared by `before`, the
+  body and `after`. It is typed as a `Partial` of the scenario's output, because a
+  run that failed early has none of it.
+
+  ```ts
+  pikkuScenario<void, { projectId: string }>({
+    func: async (_services, _data, { scenario }) => {
+      const { projectId } = await scenario.when('creates a project', 'createsProject', …)
+      scenario.context.projectId = projectId
+      …
+    },
+    after: pikkuScenarioHook<void, { projectId: string }>(
+      async (_services, _data, { scenario, actors }) => {
+        if (scenario.context.projectId) {
+          await actors.admin.invoke('deleteProject', { projectId: scenario.context.projectId })
+        }
+      }
+    ),
+  })
+  ```
+
+  Deliberately not a world: it is scoped to a single run, and scenario _steps_
+  cannot reach it — state still flows between steps as return values.
+
+  Feature-level `before`/`after` get the same member, scoped to their feature, so
+  group setup can hand group teardown what it created. It is a separate object
+  from the scenarios' contexts: one bag shared across a group is the invisible
+  coupling a Cucumber world had.
+
+- e3b4c14: Remove the `addTagPermission`, `addHTTPPermission` and `ZodLike` compatibility stubs
+
+  Tag- and HTTP-route-level permissions were removed in #972; `addTagPermission` and `addHTTPPermission` survived only as throwing stubs so the pinned bootstrap CLI could resolve their imports at build time. `@pikku/cli@0.12.96` — the currently pinned bootstrap version — emits neither name, so the stubs and the `packages/cli/build.sh` rewrite rules that fed them are gone.
+
+  Declare permissions on the function instead: `pikkuFunc({ permissions })`, or app-wide with `addGlobalPermission`.
+
+  `ZodLike` was an alias for `StandardSchemaV1<T, T>` kept for generated code that no longer references it. Import `StandardSchemaV1` from `@standard-schema/spec` directly.
+
+- efd0ed1: **An explicitly-`undefined` property no longer kills a step.** JSON Schema
+  cannot describe such a property, so the validator rejected the whole instance
+  rather than the field — `{ a: undefined }` threw
+  `Instances of "undefined" type are not supported`. Whether a payload could
+  contain one depended on how the call travelled: `JSON.stringify` drops those
+  keys over HTTP, while an in-process dispatch hands the object over intact, so
+  `workflow.do('step', 'rpc', { retries: data.maybeRetries })` failed only when
+  the step ran inline. `validateSchema` now strips them first, and an
+  explicitly-undefined _required_ field reports as the missing property it is.
+- cba98fb: Security hardening sweep
+  - **Content uploads require a signature**, matching reads. `handleUpload` previously validated the path and the size limit and then wrote the file, so an unauthenticated `PUT` to the upload prefix landed on disk. The express server, which verified nothing at all, now verifies both uploads and reads.
+  - **The remote-RPC prefix is matched case-insensitively.** The router matches routes case-insensitively, so `/Remote/RPC/fn` reached the same handler while a case-sensitive `startsWith('/remote/rpc/')` let it past the mesh trust gate and the token's `fn` binding.
+  - **Dev quick-login refuses proxied requests.** The gate checked the hostname only, so a request forwarded with `Host: localhost` was auto-provisioned a root-admin session. Proxy markers (`forwarded`, `x-forwarded-*`) now refuse regardless of what they claim, and dev login is inert in production.
+  - **Logout clears the session cookie** instead of re-signing an absent session into a fresh, unexpired one.
+  - **Short-flag cluster parsing is bounded**, closing a CLI-over-channel denial of service.
+  - `allowedHosts` is carried into secret definition meta.
+
+- ce96383: Split `pikku-workflow-service.ts` into composable modules and report missing workflow metadata as such
+
+  `PikkuWorkflowService`'s module carried its error catalog, run-engine interfaces, queue routing and queue wiring alongside the class. Those now live in `workflow-errors.ts`, `workflow-run-engine.types.ts`, `workflow-constants.ts`, `workflow-meta-resolver.ts`, `workflow-queue-routing.ts` and `workflow-queue-wiring.ts`, with the approval and recovery paths in `workflow-approval.ts` and `workflow-recovery.ts`. The `@pikku/core/workflow` entry point exports the same names as before.
+
+  Typing the workflow meta resolver surfaced a crash: a run whose workflow had no generated metadata threw `TypeError: Cannot read properties of undefined` from deep inside the runner, or `WorkflowNotFoundError` — neither of which points at the actual cause. It now throws `PikkuMissingMetaError`, matching how the queue and trigger runners already report the same condition.
+
+- f8f1244: Tighten several public types that `as any` was masking
+  - `AIStreamEvent`'s `approval-request` variant now declares `runId: string` rather than `runId?: string`. Every emitter already set it, and `AIAgentResult['pendingApprovals']` has always required it — the optional let `undefined` reach a field consumers rely on to resume a suspended run.
+  - `PikkuWire` gains an optional `logger`. The no-op audit service already read `wire.logger` before falling back to the singleton, but nothing declared it, so a host had no typed way to attach an invocation-scoped logger.
+  - `pikkuAuth`'s marker is now the exported `AuthBranded` type instead of an untyped property, so the brand that agent tool filtering depends on is visible to the type system at both the site that sets it and the sites that read it.
+
+  Internally this takes core's non-test modules from 108 `as any` casts to none. Each is replaced by an assertion to the type actually wanted, or by a change to the surrounding types that makes the assertion unnecessary. A test holds the count at zero.
+
+- f8f1244: Declare `CoreUserSession.readonly` and `ChannelMeta.gateway`, which the runtime already used
+
+  The function runner throws `ReadonlySessionError` when a session is marked `readonly` and the function is not, but `CoreUserSession` never declared the field — so there was no typed way to build a readonly session, and even core's own test had to cast. Likewise `wireGateway` writes `gateway: true` onto a websocket channel's meta, which `ChannelMeta` did not admit. Both are now declared.
+
+  The gateway websocket path also wrote channel meta without `input`, `disconnect` or `messageWirings`, all of which `ChannelMeta` requires and `channel-handler` indexes without a guard. It now writes a complete record.
+
+- 6e93a35: Give each wire an explicit set of crossovers
+
+  `wire.rpc.agent` was implemented inline in `rpc-runner.ts`, which put the agent turn logic — run, stream, resume, interrupt, approve — inside the RPC primitive. It moves to `ai-agent/agent-rpc.ts`, next to the runner and stream code it delegates to; `rpc-runner` imports it and the getter stays, so a request that never touches an agent never builds the facade.
+
+  The wires (`http`, `channel`, `queue`, `scheduler`, `cli`, `rpc`, `ai-agent`, `workflow`) previously imported each other ad hoc, so an accidental edge was indistinguishable from a designed one. Each wire now declares the crossovers it is allowed, and a test walks the import graph to hold it — failing both on an undeclared edge and on a declared crossover that no longer exists, so the declaration cannot rot into a rubber stamp.
+
+  `unsupportedChannelRemote` moves from `channel-rpc-service.ts` to `channel-rpc.types.ts`, alongside the error it throws.
+
+  The shared storage conformance suite splits from one 1216-line module into one module per service, so a backend author can read the contract for the service they implement. `defineServiceTests` is unchanged for callers.
+
+- 6dada45: fix(workflow,ai-agent): make a run's owner, entry node and step function authoritative
+
+  A graph run may only start at a node the graph declared in `meta.entryNodeIds`, and
+  the generated `POST /workflow/:workflowName/graph/:nodeId` route that let an HTTP
+  caller pick the entry node is gone. `startNode` stays for `PikkuTriggerService`,
+  which names a declared entry node anyway.
+
+  `StepState` now records the `rpcName` the workflow dispatched a step with, and the
+  step claim rejects a queue message naming a different function with
+  `WorkflowStepFunctionMismatchError` before mutating any status — a step runs under
+  the run owner's identity and without the `expose` gate, so the message must not
+  choose what runs.
+
+  `approveStep` takes the caller's session, and the generated status routes and
+  streams assert the same `assertWorkflowRunOwner` check: a run started through a
+  session may only be read and approved by that session's user. A run with no
+  recorded owner (trigger, scheduler, unauthenticated route) has nobody to compare
+  against and is still gated by the entrypoint's own `auth`/`permissions`.
+
+  `AIRunStateService.resolveApproval` is now a compare-and-swap returning whether
+  _this_ caller made the claim, and both agent resume paths run a tool only for the
+  approvals they claimed — concurrent approvals of one tool call no longer all
+  execute it.
+
+## 0.12.79
+
+### Patch Changes
+
+- e848eb2: Add `relayUndispatchedSteps()`, which re-drives steps whose queue or scheduler
+  dispatch was lost.
+
+  Arming a step is two writes to two systems — the step row lands `pending`, then
+  a job is published — and nothing spans both, so a crash in between leaves a
+  durable row nothing will ever pick up. The run then neither finishes nor fails.
+
+  The step row is the outbox record and this is the relay. It is safe to
+  re-dispatch a step that already has a live job because `executeWorkflowStepInner`
+  claims the step under `withStepLock` before invoking anything: the loser reads
+  `running` and returns. Stores opt in by overriding `findUndispatchedSteps`; the
+  default returns nothing, so a store without an atomic step lock gains no
+  re-dispatches. Opted in: `kysely-postgres` and `kysely-mysql` (real locks) and
+  in-memory (inline, single-process, no queues). Not opted in: `mongodb` and
+  `kysely-sqlite`, whose `withStepLock` is a pass-through.
+
+  Not self-starting — call it from a scheduled task.
+
+- b170489: Gateway handlers now run under the metadata their author actually wrote, instead
+  of a fabricated meta object.
+
+  `registerGatewayHandler` used to synthesize `{ sessionless: true,
+inputSchemaName: null, outputSchemaName: null }` for every gateway handler, so a
+  function declared with `pikkuFunc` — which records "session required" in meta
+  rather than through an `auth` property — was silently made sessionless, and its
+  input schema was never validated. It now inherits `sessionless`, the schema
+  names, `scopes` and tag middleware from the function the gateway was wired with,
+  falling back to the old sessionless default only when nothing was declared (a
+  gateway wired by hand rather than through codegen).
+
+  Tag middleware also reaches gateways for the first time. `addTagMiddleware('x',
+…)` combined with `wireGateway({ tags: ['x'] })` previously resolved to nothing
+  at all — the inspector computed the middleware and no runtime path read it — so
+  a tag that read like a gate applied none.
+
+  **Both are tightening changes.** A gateway whose handler declared a session
+  requirement, or whose tags name registered middleware, now enforces what it
+  already said it enforced.
+
+- ae4e898: Carry a secret's `allowedHosts` through code generation, and close three gaps in
+  the SSRF guard.
+
+  `allowedHosts` was declared and enforced but never survived codegen: the
+  inspector did not read the property off the `defineSecret` literal, and the meta
+  builder rebuilt its objects without it. Enforcement in `assertSecretAllowedForHost`
+  then always saw `undefined`, so the egress restriction was a no-op by default —
+  and, with `secrets.requireAllowedHosts` set, threw for every secret including the
+  ones that correctly declared hosts. Both stages now carry the field, and the
+  secrets verifier asserts it against the generated JSON rather than a hand-written
+  meta literal, which is why the existing tests stayed green.
+
+  `isPrivateHost` now checks an explicit CIDR table instead of ad-hoc octet
+  comparisons. It previously missed `100.64.0.0/10` — which contains Alibaba
+  Cloud's `100.100.100.200` metadata endpoint — along with `192.0.0.0/24`,
+  `198.18.0.0/15`, `192.88.99.0/24`, the TEST-NETs, multicast and reserved space.
+  IPv6 gains a real parser, so `fec0::/10`, `ff00::/8`, and NAT64 (`64:ff9b::/96`)
+  and 6to4 (`2002::/16`) forms wrapping an internal IPv4 address are caught.
+
+  `safeFetch` takes an optional `resolveHost`, checked on the initial URL and every
+  redirect hop, so a _public_ hostname pointing at a private address is refused —
+  the `169-254-169-254.nip.io` shape a literal-only check cannot see. Core cannot
+  resolve DNS itself (Workers has no DNS API), so the Node resolver ships as
+  `@pikku/core/node-host-resolver` and the Node server runtimes install it during
+  `init()`. The connection is not pinned to the address that was checked, so a
+  rebind between check and connect is still possible.
+
+  The graph addon's `httpRequest` node called bare `fetch`, bypassing the guard
+  entirely; it now goes through `safeFetch`.
+
 ## 0.12.78
 
 ### Patch Changes

package/dist/dev/hot-reload.js

@@ -61,12 +61,7 @@ export async function pikkuDevReloader(options) {
             logger.error(`Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)`);
             return;
         }
-        // Register every function-config export, replacing known functions and
-        // adding new ones. Write into the map captured at startup, NOT pikkuState's
-        // current one: a dev-server watcher may have temporarily swapped in a
-        // codegen-scoped map, whose writes are discarded when it restores.
-        // Schemas are NOT touched here: `input`/`output` hold raw zod schemas while
-        // the schema map carries codegen JSON schemas; mixing them crashed reloads.
+        // knowledge: decisions/internals/hot-reload-writes-into-the-function-map-captured-at-startup.md
         for (const [exportName, exportValue] of Object.entries(mod)) {
             if (!isFunctionConfig(exportValue))
                 continue;

package/dist/ecosystem.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The surface a package in the Pikku ecosystem reaches for — a runtime adapter,
+ * a service, the code generator's output, the CLI — and application code does
+ * not.
+ *
+ * Split out from the package root so 1.0's compatibility promise covers what
+ * applications actually import. These signatures move when the runtime needs
+ * them to — `runPikkuFunc` was reshaped over the last year while every field on
+ * `PikkuWire` survived — and promising stability on both would mean promising
+ * the weaker of the two.
+ *
+ * Not `/internal`: generated bootstrap files import from here, so the specifier
+ * lands in the user's own `.pikku` directory, and telling someone they are
+ * touching internals when the code generator put it there is both wrong and
+ * self-defeating — it could never be broken anyway. Not `/runtime` either: that
+ * reads as runtime-versus-compile-time, i.e. the real API, and `packages/runtimes/*`
+ * already claims the word while the CLI is the largest consumer here.
+ *
+ * `/internal` stays as an alias because the pinned bootstrap CLI still emits it.
+ *
+ * knowledge: decisions/internals/the-ecosystem-entry-point-carries-the-adapter-surface.md
+ */
+export { pikkuState, resetPikkuState, getAllPackageStates, getSingletonServices, getCreateWireServices, setSingletonServices, } from './pikku-state.js';
+export { runPikkuFunc, addFunction } from './function/function-runner.js';
+export { addGlobalMiddleware, addTagMiddleware as addMiddleware, } from './middleware-runner.js';
+export { httpRouter } from './wirings/http/routers/http-router.js';
+export type { CreateSingletonServices, CreateWireServices, } from './types/core.types.js';

package/dist/ecosystem.js

@@ -0,0 +1,26 @@
+/**
+ * The surface a package in the Pikku ecosystem reaches for — a runtime adapter,
+ * a service, the code generator's output, the CLI — and application code does
+ * not.
+ *
+ * Split out from the package root so 1.0's compatibility promise covers what
+ * applications actually import. These signatures move when the runtime needs
+ * them to — `runPikkuFunc` was reshaped over the last year while every field on
+ * `PikkuWire` survived — and promising stability on both would mean promising
+ * the weaker of the two.
+ *
+ * Not `/internal`: generated bootstrap files import from here, so the specifier
+ * lands in the user's own `.pikku` directory, and telling someone they are
+ * touching internals when the code generator put it there is both wrong and
+ * self-defeating — it could never be broken anyway. Not `/runtime` either: that
+ * reads as runtime-versus-compile-time, i.e. the real API, and `packages/runtimes/*`
+ * already claims the word while the CLI is the largest consumer here.
+ *
+ * `/internal` stays as an alias because the pinned bootstrap CLI still emits it.
+ *
+ * knowledge: decisions/internals/the-ecosystem-entry-point-carries-the-adapter-surface.md
+ */
+export { pikkuState, resetPikkuState, getAllPackageStates, getSingletonServices, getCreateWireServices, setSingletonServices, } from './pikku-state.js';
+export { runPikkuFunc, addFunction } from './function/function-runner.js';
+export { addGlobalMiddleware, addTagMiddleware as addMiddleware, } from './middleware-runner.js';
+export { httpRouter } from './wirings/http/routers/http-router.js';

package/dist/errors/error-handler.js

@@ -12,7 +12,8 @@ export class PikkuError extends Error {
  * plain `Error`. Callers log the message alone for these, the full stack for
  * everything else.
  */
-export const isExpectedError = (error) => error instanceof PikkuError || error?.expected === true;
+export const isExpectedError = (error) => error instanceof PikkuError ||
+    error?.expected === true;
 export const addError = (error, { status, message, mcpCode }) => {
     pikkuState(null, 'misc', 'errors').set(error, mcpCode === undefined ? { status, message } : { status, message, mcpCode });
 };
@@ -31,7 +32,8 @@ export const getErrorResponse = (error) => {
         }
         ctor = Object.getPrototypeOf(ctor);
     }
-    const name = error?.constructor?.name;
+    const name = error
+        ?.constructor?.name;
     return name
         ? Array.from(errors.entries()).find(([e]) => e.name === name)?.[1]
         : undefined;

package/dist/function/function-runner.js

@@ -124,6 +124,23 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
     const previousAudit = invocationWire.audit;
     const previousAddonNamespace = invocationWire.addonNamespace;
     const previousRpcDescriptor = Object.getOwnPropertyDescriptor(invocationWire, 'rpc');
+    // knowledge: decisions/internals/core-function-runner-restores-the-wire-fields-it-overwrites.md
+    const restoreInvocationWire = () => {
+        if (previousRpcDescriptor) {
+            Object.defineProperty(invocationWire, 'rpc', previousRpcDescriptor);
+        }
+        restoreField('functionId', previousFunctionId);
+        restoreField('audit', previousAudit);
+        restoreField('addonNamespace', previousAddonNamespace);
+    };
+    function restoreField(key, previous) {
+        if (previous === undefined) {
+            delete invocationWire[key];
+        }
+        else {
+            invocationWire[key] = previous;
+        }
+    }
     invocationWire.functionId = resolvedFunctionId;
     invocationWire.audit = resolvedAuditConfig;
     // Track which addon instance is executing so intra-addon sibling calls
@@ -187,6 +204,7 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
             services: keepsSecrets
                 ? resolvedSingletonServices
                 : withoutSecrets(resolvedSingletonServices, 'a permission'),
+            // knowledge: decisions/security/a-permission-gets-a-wire-it-cannot-reply-on.md
             wire: invocationWire,
             data: actualData,
             packageName,
@@ -244,53 +262,13 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
             return (await runMiddleware(resolvedSingletonServices, invocationWire, allMiddleware, executeFunction));
         }
         finally {
-            if (previousRpcDescriptor) {
-                Object.defineProperty(invocationWire, 'rpc', previousRpcDescriptor);
-            }
-            if (previousFunctionId === undefined) {
-                delete invocationWire.functionId;
-            }
-            else {
-                invocationWire.functionId = previousFunctionId;
-            }
-            if (previousAudit === undefined) {
-                delete invocationWire.audit;
-            }
-            else {
-                invocationWire.audit = previousAudit;
-            }
-            if (previousAddonNamespace === undefined) {
-                delete invocationWire.addonNamespace;
-            }
-            else {
-                invocationWire.addonNamespace = previousAddonNamespace;
-            }
+            restoreInvocationWire();
         }
     }
     try {
         return (await executeFunction());
     }
     finally {
-        if (previousRpcDescriptor) {
-            Object.defineProperty(invocationWire, 'rpc', previousRpcDescriptor);
-        }
-        if (previousFunctionId === undefined) {
-            delete invocationWire.functionId;
-        }
-        else {
-            invocationWire.functionId = previousFunctionId;
-        }
-        if (previousAudit === undefined) {
-            delete invocationWire.audit;
-        }
-        else {
-            invocationWire.audit = previousAudit;
-        }
-        if (previousAddonNamespace === undefined) {
-            delete invocationWire.addonNamespace;
-        }
-        else {
-            invocationWire.addonNamespace = previousAddonNamespace;
-        }
+        restoreInvocationWire();
     }
 };

package/dist/function/functions.types.d.ts

@@ -5,11 +5,6 @@ import type { PikkuError } from '../errors/error-handler.js';
 import type { CoreNodeConfig } from '../wirings/node/node.types.js';
 import type { ScenarioSurface } from '../wirings/workflow/scenario-step.types.js';
 import type { Safe } from '../secret-value.js';
-/**
- * @deprecated Use StandardSchemaV1 from @standard-schema/spec instead.
- * This alias exists only for backward compatibility with generated code.
- */
-export type ZodLike<T = any> = StandardSchemaV1<T, T>;
 export type CorePikkuFunction<In, Out, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession, Wire extends PikkuWire<In, Out, true, Session, PikkuRPC, null, string> = PikkuWire<In, Out, true, Session>> = (services: Services, data: In, wire: Wire) => Wire['channel'] extends null ? Promise<Safe<Out>> : Promise<Safe<Out>> | Promise<void>;
 export type CorePikkuFunctionSessionless<In, Out, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession, Wire extends PikkuWire<In, Out, false, Session, PikkuRPC, null, string> = PikkuWire<In, Out, false, Session>> = (services: Services, data: In, wire: Wire) => Wire['channel'] extends null ? Promise<Safe<Out>> : Promise<Safe<Out>> | Promise<void>;
 export type CorePikkuPermission<In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> = PikkuWire<In, never, false, any, PikkuRPC, never, never>> = (services: Services, data: In, wire: Wire) => Promise<boolean>;
@@ -33,6 +28,15 @@ export type CorePikkuAuthConfig<Services extends CoreSecretlessSingletonServices
     name?: string;
     description?: string;
 };
+/**
+ * Marks a permission produced by `pikkuAuth`, so agent tool filtering can tell a
+ * session check apart from an ordinary permission.
+ *
+ * knowledge: decisions/security/permission-auth-filtering-requires-live-permission-functions.md
+ */
+export type AuthBranded = {
+    __pikkuAuth?: true;
+};
 export declare const pikkuAuth: <Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession>(auth: CorePikkuAuth<Services, Session> | CorePikkuAuthConfig<Services, Session>) => CorePikkuPermission<any, Services, any>;
 export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> = Record<string, PikkuPermission | PikkuPermission[]> | undefined;
 /**

package/dist/index.d.ts

@@ -3,22 +3,18 @@
  */
 export type { AuthInstance, CommonWireMeta, CoreConfig, CorePikkuMiddleware, CorePikkuMiddlewareConfig, CorePikkuMiddlewareFactory, CorePikkuMiddlewareGroup, CoreServices, CoreSecretlessSingletonServices, CoreSingletonServices, CoreUserSession, SecretlessServices, CreateConfig, ServerLifecycle, FunctionMeta, FunctionRuntimeMeta, FunctionServicesMeta, FunctionWiresMeta, FunctionsMeta, FunctionsRuntimeMeta, JSONPrimitive, JSONValue, MakeRequired, MiddlewareMetadata, MiddlewarePriority, PermissionMetadata, PickOptional, PickRequired, PikkuAIMiddlewareHooks, PikkuWire, PikkuRawWire, PikkuWiringTypes, PostgresConfig, RequireAtLeastOne, SecurityAuditIssue, SecurityAuditReport, SecurityAuditSummary, SecurityAuditUpdate, SecuritySeverity, SecurityUpdateLevel, SerializedError, WireServices, } from './types/core.types.js';
 export { pikkuAIMiddleware, pikkuChannelMiddleware, pikkuChannelMiddlewareFactory, pikkuMiddleware, pikkuMiddlewareFactory, } from './types/core.types.js';
-export type { CorePikkuAuth, CorePikkuAuthConfig, CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuFunctionHook, CorePikkuPermission, CorePikkuPermissionConfig, CorePikkuPermissionFactory, CorePikkuApprovalDescription, CorePermissionGroup, ZodLike, } from './function/functions.types.js';
+export type { CorePikkuAuth, CorePikkuAuthConfig, CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuFunctionHook, CorePikkuPermission, CorePikkuPermissionConfig, CorePikkuPermissionFactory, CorePikkuApprovalDescription, CorePermissionGroup, } from './function/functions.types.js';
 export { pikkuAuth, pikkuPermission, pikkuPermissionFactory, pikkuApprovalDescription, } from './function/functions.types.js';
-export { addFunction, getAllFunctionNames } from './function/index.js';
+export { getAllFunctionNames } from './function/index.js';
 export type { ListInput, ListOutput, Filter, LeafFilter, LeafValue, } from './function/list.types.js';
+export { pikkuCLIRender } from './wirings/cli/cli-runner.js';
 export { PikkuRequest } from './pikku-request.js';
 export { getRelativeTimeOffsetFromNow, parseDurationString, } from './time-utils.js';
 export type { RelativeTimeInput } from './time-utils.js';
 export { formatVersionedId, isVersionedId, parseVersionedId, } from './version.js';
-export { runPikkuFunc } from './function/function-runner.js';
 export { AbandonedError, beginChanges, getAbortScope, runInAbortScope, type AbortScope, } from './function/abort-scope.js';
-export { runCLICommand, pikkuCLIRender } from './wirings/cli/cli-runner.js';
 export { fetch } from './wirings/http/http-runner.js';
-export { runMCPTool, runMCPResource, runMCPPrompt, } from './wirings/mcp/mcp-runner.js';
 export type { MCPToolResponse, MCPResourceResponse, MCPPromptResponse, } from './wirings/mcp/mcp.types.js';
-export { runQueueJob } from './wirings/queue/queue-runner.js';
-export { runScheduledTask } from './wirings/scheduler/scheduler-runner.js';
 export { AIProviderAuthError, AIProviderNotConfiguredError, BadGatewayError, BadRequestError, ConflictError, ExpectationFailedError, ForbiddenError, GatewayTimeoutError, GoneError, HTTPVersionNotSupportedError, InternalServerError, InvalidMiddlewareWireError, InvalidOriginError, InvalidSessionError, LengthRequiredError, LocalEnvironmentOnlyError, LockedError, MaxComputeTimeReachedError, MethodNotAllowedError, MissingCredentialError, MissingSchemaError, MissingScopeError, MissingServiceError, MissingSessionError, NotAcceptableError, NotFoundError, NotImplementedError, PayloadTooLargeError, PaymentRequiredError, PikkuMissingMetaError, PreconditionFailedError, ProxyAuthenticationRequiredError, RangeNotSatisfiableError, ReadonlySessionError, RequestTimeoutError, ServiceUnavailableError, TooManyRequestsError, URITooLongError, UnauthorizedError, UnprocessableContentError, UnsupportedMediaTypeError, } from './errors/errors.js';
 export { PikkuError, isExpectedError } from './errors/error-handler.js';
 export type { EventHubService } from './wirings/channel/eventhub-service.js';
@@ -51,11 +47,10 @@ export type { WireAddonConfig } from './wirings/rpc/wire-addon.js';
 export { wireRemoteAddon } from './wirings/rpc/wire-remote-addon.js';
 export type { WireRemoteAddonConfig, RemoteAddonAuth, } from './wirings/rpc/wire-remote-addon.js';
 export type { PikkuPackageState } from './types/state.types.js';
-export { runMiddleware, addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, } from './middleware-runner.js';
+export { runMiddleware, addTagMiddleware } from './middleware-runner.js';
 export { addGlobalPermission, checkAuthPermissions } from './permissions.js';
 export { hasScopes, verifyScopes } from './scopes.js';
 export { isSerializable, stopSingletonServices, pikkuServerLifecycle, } from './utils.js';
-export { getSingletonServices, getCreateWireServices, setSingletonServices, } from './pikku-state.js';
 export { clearPikkuRuntimeState } from './test-utils.js';
 export { type ScheduledTaskInfo, type ScheduledTaskSummary, } from './services/scheduler-service.js';
 export { SchedulerService } from './services/scheduler-service.js';

package/dist/index.js

@@ -1,16 +1,12 @@
 export { pikkuAIMiddleware, pikkuChannelMiddleware, pikkuChannelMiddlewareFactory, pikkuMiddleware, pikkuMiddlewareFactory, } from './types/core.types.js';
 export { pikkuAuth, pikkuPermission, pikkuPermissionFactory, pikkuApprovalDescription, } from './function/functions.types.js';
-export { addFunction, getAllFunctionNames } from './function/index.js';
+export { getAllFunctionNames } from './function/index.js';
+export { pikkuCLIRender } from './wirings/cli/cli-runner.js';
 export { PikkuRequest } from './pikku-request.js';
 export { getRelativeTimeOffsetFromNow, parseDurationString, } from './time-utils.js';
 export { formatVersionedId, isVersionedId, parseVersionedId, } from './version.js';
-export { runPikkuFunc } from './function/function-runner.js';
 export { AbandonedError, beginChanges, getAbortScope, runInAbortScope, } from './function/abort-scope.js';
-export { runCLICommand, pikkuCLIRender } from './wirings/cli/cli-runner.js';
 export { fetch } from './wirings/http/http-runner.js';
-export { runMCPTool, runMCPResource, runMCPPrompt, } from './wirings/mcp/mcp-runner.js';
-export { runQueueJob } from './wirings/queue/queue-runner.js';
-export { runScheduledTask } from './wirings/scheduler/scheduler-runner.js';
 export { AIProviderAuthError, AIProviderNotConfiguredError, BadGatewayError, BadRequestError, ConflictError, ExpectationFailedError, ForbiddenError, GatewayTimeoutError, GoneError, HTTPVersionNotSupportedError, InternalServerError, InvalidMiddlewareWireError, InvalidOriginError, InvalidSessionError, LengthRequiredError, LocalEnvironmentOnlyError, LockedError, MaxComputeTimeReachedError, MethodNotAllowedError, MissingCredentialError, MissingSchemaError, MissingScopeError, MissingServiceError, MissingSessionError, NotAcceptableError, NotFoundError, NotImplementedError, PayloadTooLargeError, PaymentRequiredError, PikkuMissingMetaError, PreconditionFailedError, ProxyAuthenticationRequiredError, RangeNotSatisfiableError, ReadonlySessionError, RequestTimeoutError, ServiceUnavailableError, TooManyRequestsError, URITooLongError, UnauthorizedError, UnprocessableContentError, UnsupportedMediaTypeError, } from './errors/errors.js';
 export { PikkuError, isExpectedError } from './errors/error-handler.js';
 export { SecretAccessDeniedError, withoutSecrets, } from './services/secretless.js';
@@ -19,11 +15,10 @@ export { NoopAuditService, createInvocationAudit, resolveAuditConfig, resolveAud
 export { createGraph } from './wirings/workflow/graph/graph-node.js';
 export { wireAddon } from './wirings/rpc/wire-addon.js';
 export { wireRemoteAddon } from './wirings/rpc/wire-remote-addon.js';
-export { runMiddleware, addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, } from './middleware-runner.js';
+export { runMiddleware, addTagMiddleware } from './middleware-runner.js';
 export { addGlobalPermission, checkAuthPermissions } from './permissions.js';
 export { hasScopes, verifyScopes } from './scopes.js';
 export { isSerializable, stopSingletonServices, pikkuServerLifecycle, } from './utils.js';
-export { getSingletonServices, getCreateWireServices, setSingletonServices, } from './pikku-state.js';
 export { clearPikkuRuntimeState } from './test-utils.js';
 export { SchedulerService } from './services/scheduler-service.js';
 export { hashToken, unsafeAsWrapped, unsafeAsSealed, unsafeAsHashed, } from './column-form.js';

package/dist/middleware/auth-cookie.d.ts

@@ -1,9 +1,5 @@
 import type { SerializeOptions } from 'cookie';
 import type { RelativeTimeInput } from '../time-utils.js';
-/**
- * Reads a JWT session from a cookie, and re-issues the cookie after the
- * request whenever the session changed (e.g. after login).
- */
 export declare const authCookie: import("../types/core.types.js").CorePikkuMiddlewareFactory<{
     name: string;
     options: SerializeOptions;

package/dist/middleware/auth-cookie.js

@@ -4,6 +4,26 @@ import { getRelativeTimeOffsetFromNow } from '../time-utils.js';
  * Reads a JWT session from a cookie, and re-issues the cookie after the
  * request whenever the session changed (e.g. after login).
  */
+/** Standard JWT registered claims — present on a token even with no session. */
+const JWT_REGISTERED_CLAIMS = new Set([
+    'iat',
+    'exp',
+    'nbf',
+    'iss',
+    'aud',
+    'sub',
+    'jti',
+]);
+/**
+ * Whether a decoded payload carries an actual session, as opposed to being
+ * absent or a bare JWT envelope of `{ iat, exp }`. True only for a non-null
+ * object with at least one key that is not a registered JWT claim.
+ */
+const hasSessionIdentity = (session) => {
+    if (!session || typeof session !== 'object')
+        return false;
+    return Object.keys(session).some((key) => !JWT_REGISTERED_CLAIMS.has(key));
+};
 export const authCookie = pikkuMiddlewareFactory(({ name, options, expiresIn }) => {
     const mergedOptions = {
         httpOnly: true,
@@ -19,7 +39,12 @@ export const authCookie = pikkuMiddlewareFactory(({ name, options, expiresIn })
         const cookieValue = http.request.cookie(name);
         if (cookieValue && jwtService) {
             const userSession = await jwtService.decode(cookieValue);
-            if (userSession) {
+            // Not just truthy: a JWT of an absent session still decodes to a
+            // `{ iat, exp }` object, which is truthy and which the function runner
+            // would accept as a session. Require at least one claim that is not a
+            // standard JWT timestamp, so an identity-less token is treated as no
+            // session rather than as an authenticated one.
+            if (userSession && hasSessionIdentity(userSession)) {
                 setSession?.(userSession);
             }
         }
@@ -29,7 +54,18 @@ export const authCookie = pikkuMiddlewareFactory(({ name, options, expiresIn })
         }
         if (hasSessionChanged?.()) {
             const currentSession = await getSession?.();
-            if (jwtService) {
+            // Logout path: `clearSession()` marks the session changed while leaving
+            // it absent. Re-signing that into a fresh, unexpired cookie would hand
+            // the browser a credential on the way out — so clear the cookie instead
+            // of minting one, and never call `encode` with an absent session.
+            if (!hasSessionIdentity(currentSession)) {
+                http.response.cookie(name, '', {
+                    ...mergedOptions,
+                    expires: new Date(0),
+                    maxAge: 0,
+                });
+            }
+            else if (jwtService) {
                 http.response.cookie(name, await jwtService.encode(expiresIn, currentSession), {
                     ...mergedOptions,
                     expires: getRelativeTimeOffsetFromNow(expiresIn),

package/dist/middleware/cors.js

@@ -45,6 +45,7 @@ export const cors = pikkuMiddlewareFactory(({ origin = '*', methods = ['GET', 'P
             }
             if (request.method() === 'options') {
                 response.header('Access-Control-Max-Age', String(maxAge));
+                // 204 carries no body, and `json` has no no-content overload.
                 response.status(204).json(undefined);
                 return;
             }

package/dist/middleware/index.d.ts

@@ -5,4 +5,4 @@ export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
 export { cors } from './cors.js';
 export { telemetryOuter, telemetryInner } from './telemetry.js';
 export { addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, runMiddleware, } from '../middleware-runner.js';
-export { addGlobalPermission, addTagPermission } from '../permissions.js';
+export { addGlobalPermission } from '../permissions.js';

package/dist/middleware/index.js

@@ -5,4 +5,4 @@ export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
 export { cors } from './cors.js';
 export { telemetryOuter, telemetryInner } from './telemetry.js';
 export { addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, runMiddleware, } from '../middleware-runner.js';
-export { addGlobalPermission, addTagPermission } from '../permissions.js';
+export { addGlobalPermission } from '../permissions.js';