@pikku/core 0.12.79 → 0.12.80

package/CHANGELOG.md

@@ -1,3 +1,164 @@
+## 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

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';

package/dist/middleware/remote-auth.js

@@ -1,6 +1,15 @@
 import { UnauthorizedError } from '../errors/errors.js';
 import { pikkuMiddleware } from '../types/core.types.js';
 import { assertStrongKeyMaterial, decryptWithKeyMaterial, REMOTE_SESSION_INFO, } from '../crypto-utils.js';
+const REMOTE_RPC_PREFIX = '/remote/rpc/';
+/**
+ * Whether this request targets the remote-RPC surface. Compared case-insensitively
+ * because the router matches routes that way (path-to-regexp defaults to
+ * `sensitive: false`), so `/Remote/RPC/fn` reaches the same handler as
+ * `/remote/rpc/fn`. A case-sensitive check here let a case-varied path slip
+ * past the trust gate and the token's `fn` binding while still being dispatched.
+ */
+const isRemoteRpcPath = (path) => path.toLowerCase().startsWith(REMOTE_RPC_PREFIX);
 export const pikkuRemoteAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }, { http, setSession }, next) => {
     if (!http?.request || !secrets) {
         return next();
@@ -10,7 +19,7 @@ export const pikkuRemoteAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }
         secret = (await secrets.getSecret('PIKKU_REMOTE_SECRET')).reveal();
     }
     catch {
-        if (http.request.path().startsWith('/remote/rpc/')) {
+        if (isRemoteRpcPath(http.request.path())) {
             throw new UnauthorizedError();
         }
         return next();
@@ -38,8 +47,10 @@ export const pikkuRemoteAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }
     if (payload?.aud !== 'pikku-remote') {
         throw new UnauthorizedError();
     }
-    if (payload?.fn && http.request.path().startsWith('/remote/rpc/')) {
-        const fn = decodeURIComponent(http.request.path().slice('/remote/rpc/'.length));
+    if (payload?.fn && isRemoteRpcPath(http.request.path())) {
+        // The prefix length is the same in any case, so slicing the raw path
+        // keeps the requested function name in its original case for the compare.
+        const fn = decodeURIComponent(http.request.path().slice(REMOTE_RPC_PREFIX.length));
         if (fn && payload.fn !== fn) {
             throw new UnauthorizedError();
         }

package/dist/permissions.d.ts

@@ -1,20 +1,18 @@
 import type { CoreServices, CoreUserSession, PikkuWire } from './types/core.types.js';
+import type { PikkuRPC } from './wirings/rpc/rpc-types.js';
+/**
+ * The wire a permission function sees. `Out = never` denies it `channel.send`.
+ *
+ * knowledge: decisions/security/a-permission-gets-a-wire-it-cannot-reply-on.md
+ */
+export type PermissionWire = PikkuWire<any, never, false, any, PikkuRPC, never, never>;
 import type { CorePermissionGroup, CorePikkuPermission } from './function/functions.types.js';
 export declare const clearPermissionsCache: () => void;
 export declare const addGlobalPermission: (permissions: CorePermissionGroup | CorePikkuPermission[], packageName?: string | null) => CorePermissionGroup | CorePikkuPermission[];
-/**
- * @deprecated Tag-level permissions were removed in #972 — permissions are now
- * function-scoped only (declare them on the function via `pikkuFunc({ permissions })`).
- * This throwing stub exists solely so the pinned bootstrap CLI (which still
- * generates an `addTagPermission` wrapper) can resolve the import at build time;
- * it is never called. Delete once `PIKKU_CLI_VERSION` in the CLI build is bumped
- * past the release that removes tag permissions.
- */
-export declare const addTagPermission: (_tag: string, _permissions: CorePermissionGroup | CorePikkuPermission[], _packageName?: string | null) => never;
 export declare const runPermissions: ({ funcPermissions, services, wire, data, packageName, label, }: {
     funcPermissions?: CorePermissionGroup | CorePikkuPermission[];
     services: CoreServices;
-    wire: PikkuWire<any, never, any, CoreUserSession, never, never, never>;
+    wire: PermissionWire;
     data: any;
     packageName?: string | null;
     /** What the non-global gate is called in debug logs, e.g. 'function', 'agent'. */