@pikku/core 0.12.136 → 0.12.138

package/CHANGELOG.md

@@ -1,3 +1,44 @@
+## 0.12.138
+
+### Patch Changes
+
+- 6f11bb5: A deployed Cloudflare Worker is always production. The adapter now pins `process.env.NODE_ENV` to `"production"` in the bundle, and core's `isProduction()` reads the literal `process.env.NODE_ENV` so that pin takes effect. Before, a Worker had no `NODE_ENV`, so `isProduction()` was false and every 5xx response returned the error message and stack trace to the client. `process.env.NODE_ENV` now wins over a variables service when it is set.
+- 0c67e33: `@pikku/core` no longer imports `node:async_hooks`, so it is edge-clean end to end. The function abort scope that `beginChanges()` observes is now passed explicitly (agent tool `execute(input, { abortScope })` onto `wire.abortScope`, carried through nested `rpc` calls) instead of living in `AsyncLocalStorage`, which also means concurrent runs in one process or isolate cannot see each other's scope. `AgentToolDef.execute` gains an optional second argument; nothing else in the public API changes.
+- 15c4968: The default runtime path no longer needs `node:*`, `Buffer` or an unguarded `process`, so it loads on edge runtimes (Web APIs only).
+
+  **Breaking:** `FileScenarioRunStore`, `scenarioArtifactContentType` and `scenarioRunSummary` leave the `@pikku/core/services` barrel because they use `node:fs`. Import them from `@pikku/core/services/file-scenario-run-store`. Pre-0.13 breaking changes still ship as a patch.
+
+  **Breaking:** the HMAC helpers in `@pikku/core/hmac` run on Web Crypto, which is async. `hmacSha256Hex`, `hmacDigest`, `verifyHmacSignature` and `verifyPublicKeySignature` now return a Promise; `timingSafeStringEqual` stays synchronous. `WebhookService.sign` and `WebhookService.verify` return a Promise, and so does `verifySlackSignature` in `@pikku/gateway-slack`: `await` them. A function-style `verify` on a webhook source may return a Promise as well. `verifyPublicKeySignature` accepts RSA and EC (P-256, P-384, P-521) PEM keys; Ed25519 and RSA-PSS keys verify as false.
+
+  `isProduction()` (and the `PIKKU_MODEL_ALIASES` and `PIKKU_ENV` reads) now ask the registered singleton services' `variables` service first, then `process.env` when `process` exists. With neither, `isProduction()` is true, so an edge deployment never exposes error details by accident. `LocalVariablesService` resolves its `process.env` default when constructed and falls back to an empty store without `process`.
+
+  Workflow invocation ids use a built-in SHA-1 and stay byte-identical. `@pikku/kysely` and the Cloudflare hibernation server use `globalThis.crypto.randomUUID()` and no `Buffer`; `@pikku/kysely` is marked `sideEffects: false`. `@pikku/ai-deepinfra` reads `DEEPINFRA_API_KEY` only when `process` exists and decodes base64 audio without `Buffer`.
+
+  Runtime tiers. A package declares where it can run in `package.json`: `"pikku": { "runtime": "edge" | "serverless" | "server" }`, with optional per-subpath overrides (`"exports": { "./dev": "server" }`). `server` is the default. `@pikku/core` and the default services are `edge` (core's Node-only subpaths are `server`), `@pikku/better-auth`, `@pikku/addon-admin` and `@pikku/cloudflare` are `serverless` (better-auth statically imports `node:crypto` scrypt), and `@pikku/addon-console` is `server` and must never land in a deployed unit.
+
+  `pikku deploy` now verifies each deployed unit before bundling it. The unit is bundled with esbuild (neutral platform, `workerd`/`worker`/`browser` conditions) under its tier's profile, ahead of the adapter's aliases and stubs so they cannot hide anything, and the build fails when the bundle holds a package declared above the unit's tier or a Node built-in the runtime does not provide. The error names the unit, package, import chain and the fix. A built-in the provider stubs is a warning. On an edge unit, a bundled `InMemory*` class also fails the build. The unit's tier is its `runtime`, else the project's own `pikku.runtime`, else the provider default (`serverless` on Cloudflare). Packages that declare nothing are judged by their imports only.
+
+  `ProviderAdapter.getRuntimeProfile(tier?)` returns the compat date, compat flags, the built-ins the runtime provides (keyed by compat date), the stubbed ones and the externals. The Cloudflare adapter derives `wrangler.toml`, the upload metadata and the bundle externals from it; `node:os` and `node:fs` are not provided before compat date 2025-09-15. The default is `nodejs_compat_v2` with compat date 2024-12-18, which is what `wrangler.toml` and Fabric's live workers already use, so Fabric deploys see no runtime change. Only the direct-API upload in `@pikku/deploy-cloudflare` (`createWorker`, used by its own `deploy()`) moves: it sent `nodejs_compat` with 2024-01-01 before. A newer date or flag is opt-in through the adapter option `new CloudflareProviderAdapter({ compatDate })` or `getCloudflareRuntimeProfile(tier, compatDate)`. From 2025-08-15 `node:http` and `node:https` exist, and from 2025-09-15 `node:os`, `node:fs` (stubbed by the build regardless) and `node:perf_hooks`; the verifier's allowed built-ins follow the effective date. A newer date changes the runtime of every worker deployed with it.
+
+  `declareScopes(['pikku:console'])` (from `@pikku/core/scope`) declares scopes by id without wiring anything. `wireAddon({ scopes })` only requires a scope of an addon's functions; the tree arrives with the addon's metadata, so a role granting `pikku:console` used to fail PKU124 unless the addon was wired, and a wired `@pikku/addon-console` lands in every unit carrying the `/rpc` catch-all. An app that grants the scope without the console now calls `declareScopes` and no longer needs the scaffold or the addon. When the addon is wired its tree and descriptions win and the bare id adds nothing.
+
+  More packages declare a tier after bundling each with the edge profile. `edge`: `@pikku/addon-graph`, `@pikku/pino`, `@pikku/jose`, `@pikku/ai-vercel`, `@pikku/ai-voice`. `serverless`: `@pikku/kysely-postgres` (postgres.js needs `node:buffer`, `stream`, `events`), `@pikku/backblaze` (`copyFile` reads a local file, which the build stubs), `@pikku/gateway-slack` (`@slack/web-api` imports `node:os` and `zlib`). `server`: `@pikku/schedule` (`cron` imports `child_process`), `@pikku/aws-services` (the AWS SDK's Node handler needs `node:http2`), `@pikku/browser` (puppeteer), and `@pikku/modelcontextprotocol` except its `./fetch` subpath, which is `edge`.
+
+  `@pikku/addon-graph` no longer needs `node:crypto` or `Buffer`: the Crypto function hashes and HMACs on Web Crypto (MD5 is built in, since Web Crypto has none) and encodes with `TextEncoder`/`atob`/`btoa`, with output unchanged.
+
+- d75a23d: Await previously un-awaited promises (session setters, channel sends, schema compile, trigger and CLI renderer calls) and handle rejections in fire-and-forget timers and signal handlers, found by type-aware `no-floating-promises` / `no-misused-promises`.
+- 9b12c8a: Harden webhook signature verification. An empty or missing secret now fails closed at every call site (`verifyHmacSignature`, webhook source verification, `WebhookService.verify`, `verifySlackSignature`), including a signature computed over an empty key. HMAC verification now decodes the signature to bytes and compares with `crypto.subtle.verify('HMAC', ...)` instead of a pure-JS string compare, and a malformed hex signature is rejected. `verifyPublicKeySignature` accepts Ed25519 SPKI keys again.
+
+## 0.12.137
+
+### Patch Changes
+
+- 0c865d9: Changes and changesets replace milestones. The changes commands run on a local queue when the checkout has no fabric project; `pikku changes next` routes to a changes, upgrade or knowledge agent and merges finished changesets. A changeset that creates or alters a table, or has 6 or more changes, needs a plan at `knowledge/plans/<changeset>.plan.json` (anything else goes to an optional judge at `PIKKU_PLAN_JUDGE_URL`), and `changes done` holds it to that plan. `pikku knowledge gaps` replaces `knowledge next`/`reconcile`, and also reports code a merged plan built that is gone and notes that were deleted.
+- c36b066: Scenario coverage moves into OSS. `@pikku/core/scenario/coverage` adds `readScenarioCoverage`, which reports the lines no scenario reaches, the mutations no scenario drives, and the pages scenarios open. It is exposed through `pikku scenario coverage`, `console:getScenarioCoverage`, and a "Not tested by any scenario" card on the Scenarios page. `LocalMetaService.getRpcMeta` now reads the `.internal.gen.json` file that codegen actually writes.
+- 0963b73: Every scope tree now records where it came from: `origin` on `ScopeDefinitionMeta` is `{ kind: 'app' }` for the app's own `defineScope`, `{ kind: 'generated' }` for a tree the CLI wrote into the project (a `.gen.ts`, or the `app` root derived from personas), and `{ kind: 'addon', package, displayName }` for one an installed addon declared. An addon's build stamps its own package and display name on its trees, and the host keeps that name while recording the package it actually installed. `MetaService.getScopesMeta()` reads the result, and the console's all-meta payload carries it as `scopes`.
+
+  The console's Scopes page becomes **Permissions** and is grouped by that origin: the app's own permissions first, then what Pikku generated into the project, then one card per addon (Pikku's own before third-party, each alphabetical), each card folding to its header — the app's own starts open, every addon's starts folded, and any search or filter opens them all. Above the cards, two filters narrow the page to what one role is given (or to what no role is given yet) and to one source. A permission group no longer says "Not part of any role yet" above lines that are each given to a role.
+
 ## 0.12.136
 
 ### Patch Changes

package/dist/dev/hot-reload.js

@@ -105,14 +105,17 @@ export async function pikkuDevReloader(options) {
         pendingChanges.add(filePath);
         if (debounceTimer)
             clearTimeout(debounceTimer);
-        debounceTimer = setTimeout(async () => {
+        const flush = async () => {
             const files = [...pendingChanges];
             pendingChanges.clear();
             for (const file of files) {
                 postCodegenQueue.add(file);
                 await safeHandleFileChange(file);
             }
-        }, 50);
+        };
+        // Fire-and-forget timer callback: safeHandleFileChange catches and logs
+        // every error, so nothing can reject here.
+        debounceTimer = setTimeout(() => void flush(), 50);
     };
     for (const srcDir of absSrcDirs) {
         try {

package/dist/env.d.ts

@@ -1 +1,19 @@
+/**
+ * Reads one variable without `process`, which edge runtimes do not have.
+ *
+ * Looks in the registered singleton services' `variables` service first, then
+ * in `process.env` when there is one. Never throws: services that were never
+ * registered (a unit test, an early boot path) simply fall through, which is
+ * why this reads the state directly instead of calling
+ * `getSingletonServices()`.
+ *
+ * The read is synchronous, so a `VariablesService` that answers with a Promise
+ * is ignored and the lookup falls through to `process.env`.
+ */
+export declare const readEnvVariable: (name: string) => string | undefined;
+/**
+ * `NODE_ENV` decides whether error details are exposed. With neither a
+ * variables service nor `process` to say, this is production: failing closed
+ * means an edge deployment never leaks error details by accident.
+ */
 export declare const isProduction: () => boolean;

package/dist/env.js

@@ -1 +1,60 @@
-export const isProduction = () => process.env.NODE_ENV === 'production';
+import { pikkuState } from './pikku-state.js';
+/**
+ * Reads one variable without `process`, which edge runtimes do not have.
+ *
+ * Looks in the registered singleton services' `variables` service first, then
+ * in `process.env` when there is one. Never throws: services that were never
+ * registered (a unit test, an early boot path) simply fall through, which is
+ * why this reads the state directly instead of calling
+ * `getSingletonServices()`.
+ *
+ * The read is synchronous, so a `VariablesService` that answers with a Promise
+ * is ignored and the lookup falls through to `process.env`.
+ */
+export const readEnvVariable = (name) => {
+    try {
+        const variables = pikkuState(null, 'package', 'singletonServices')?.variables;
+        if (variables) {
+            const value = variables.get(name);
+            if (value instanceof Promise) {
+                value.catch(() => { });
+            }
+            else if (typeof value === 'string' ||
+                typeof value === 'number' ||
+                typeof value === 'boolean') {
+                return String(value);
+            }
+        }
+    }
+    catch {
+        // A faulty variables service must not take error handling down with it.
+    }
+    return hasProcessEnv() ? globalThis.process.env[name] : undefined;
+};
+const hasProcessEnv = () => typeof globalThis.process?.env === 'object';
+/**
+ * The literal `process.env.NODE_ENV`, kept as a literal on purpose: a deploy
+ * adapter pins it with a bundler `define` (a Cloudflare Worker is always
+ * production), and `define` only rewrites this exact expression, not
+ * `process.env[name]`. Without that define it reads the real value, and on a
+ * runtime with no `process` the ReferenceError means "unknown".
+ */
+const buildTimeNodeEnv = () => {
+    try {
+        return process.env.NODE_ENV;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * `NODE_ENV` decides whether error details are exposed. With neither a
+ * variables service nor `process` to say, this is production: failing closed
+ * means an edge deployment never leaks error details by accident.
+ */
+export const isProduction = () => {
+    const nodeEnv = buildTimeNodeEnv() ?? readEnvVariable('NODE_ENV');
+    if (nodeEnv !== undefined)
+        return nodeEnv === 'production';
+    return !hasProcessEnv();
+};

package/dist/function/abort-scope.d.ts

@@ -14,10 +14,6 @@ export interface AbortScope {
     /** Called by `beginChanges()` once a function commits to mutating. */
     onBeginChanges?: () => void;
 }
-/** Run `fn` with an abort scope that `beginChanges()` will observe. */
-export declare const runInAbortScope: <T>(scope: AbortScope, fn: () => T) => T;
-/** The current scope, if the caller is running inside one. */
-export declare const getAbortScope: () => AbortScope | undefined;
 /**
  * Declare that everything after this line changes something.
  *
@@ -38,10 +34,15 @@ export declare const getAbortScope: () => AbortScope | undefined;
  * ignoring the answer, and the failure mode of ignoring it is a mutation nobody
  * asked for.
  *
+ * The scope is passed explicitly — the function runner binds it from
+ * `wire.abortScope` — rather than looked up ambiently, so concurrent runs in
+ * one process (or one edge isolate) can never see each other's scope and core
+ * needs no `AsyncLocalStorage`.
+ *
  * Entirely cooperative, and safe to call anywhere — outside a scope it is a
  * no-op, so a function does not need to know how it was invoked. A function
  * that never calls it keeps the conservative default: if it is not marked
  * `readonly`, an interrupt assumes it changed something and says so. The tool
  * that forgot to call this is exactly the one that cannot be assumed harmless.
  */
-export declare const beginChanges: () => Promise<void>;
+export declare const beginChanges: (scope?: AbortScope) => Promise<void>;

package/dist/function/abort-scope.js

@@ -1,4 +1,3 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
 /**
  * Raised by {@link beginChanges} when the caller has gone away before anything
  * was changed. Distinct from a failure: nothing happened, so there is nothing
@@ -12,20 +11,6 @@ export class AbandonedError extends Error {
         this.name = 'AbandonedError';
     }
 }
-/**
- * The ambient "is my caller still there?" signal.
- *
- * Ambient rather than a parameter because the question is the same one for
- * every wiring — an agent run that was interrupted, an HTTP request whose
- * client disconnected, a cancelled workflow — and threading it through every
- * signature would mean changing every function that merely sits between the
- * wiring and the mutation.
- */
-const scopeStorage = new AsyncLocalStorage();
-/** Run `fn` with an abort scope that `beginChanges()` will observe. */
-export const runInAbortScope = (scope, fn) => scopeStorage.run(scope, fn);
-/** The current scope, if the caller is running inside one. */
-export const getAbortScope = () => scopeStorage.getStore();
 /**
  * Declare that everything after this line changes something.
  *
@@ -46,14 +31,18 @@ export const getAbortScope = () => scopeStorage.getStore();
  * ignoring the answer, and the failure mode of ignoring it is a mutation nobody
  * asked for.
  *
+ * The scope is passed explicitly — the function runner binds it from
+ * `wire.abortScope` — rather than looked up ambiently, so concurrent runs in
+ * one process (or one edge isolate) can never see each other's scope and core
+ * needs no `AsyncLocalStorage`.
+ *
  * Entirely cooperative, and safe to call anywhere — outside a scope it is a
  * no-op, so a function does not need to know how it was invoked. A function
  * that never calls it keeps the conservative default: if it is not marked
  * `readonly`, an interrupt assumes it changed something and says so. The tool
  * that forgot to call this is exactly the one that cannot be assumed harmless.
  */
-export const beginChanges = async () => {
-    const scope = scopeStorage.getStore();
+export const beginChanges = async (scope) => {
     if (!scope)
         return;
     if (scope.abandoned) {

package/dist/function/function-runner.js

@@ -235,7 +235,8 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         // and offering it there would invite the contradiction of a `readonly`
         // function announcing where its changes begin.
         if (!funcMeta.readonly) {
-            invocationWire.beginChanges = beginChanges;
+            const abortScope = resolvedWire.abortScope;
+            invocationWire.beginChanges = () => beginChanges(abortScope);
         }
         // knowledge: decisions/security/addon-scopes-are-resolved-where-the-function-runs.md
         const addonScopes = resolveAddonScopes(packageName, addonInstance?.namespace);

package/dist/middleware/auth-apikey.js

@@ -19,7 +19,7 @@ export const authAPIKey = pikkuMiddlewareFactory(({ source }) => pikkuMiddleware
     if (apiKey && jwtService) {
         const userSession = await jwtService.decode(apiKey);
         if (userSession) {
-            setSession?.(userSession);
+            await setSession?.(userSession);
         }
     }
     return next();

package/dist/middleware/auth-bearer.js

@@ -48,7 +48,7 @@ export const authBearer = pikkuMiddlewareFactory(({ token } = {}) => pikkuMiddle
             userSession = await jwtService.decode(bearerToken);
         }
         if (userSession) {
-            setSession?.(userSession);
+            await setSession?.(userSession);
         }
     }
     return next();

package/dist/middleware/auth-cookie.js

@@ -47,7 +47,7 @@ export const authCookie = pikkuMiddlewareFactory(({ name, options, expiresIn })
             // 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);
+                await setSession?.(userSession);
             }
         }
         await next();

package/dist/schema.js

@@ -18,7 +18,9 @@ export const compileAllSchemas = (logger, schemaService) => {
     for (const [pkgName, packageState] of getAllPackageStates()) {
         const resolvedPkgName = pkgName === '__main__' ? null : pkgName;
         for (const [name, schema] of packageState.misc.schemas) {
-            schemaService.compileSchema(schemaKey(name, resolvedPkgName), schema);
+            // compileSchema may be async; this function is synchronous (public
+            // signature), so a rejection is logged instead of left unhandled.
+            Promise.resolve(schemaService.compileSchema(schemaKey(name, resolvedPkgName), schema)).catch((e) => logger.error(`Failed to compile schema '${name}': ${e?.message ?? e}`));
         }
     }
     validateAllSchemasLoaded(logger, schemaService);

package/dist/services/in-memory-queue-service.js

@@ -24,7 +24,8 @@ export class InMemoryQueueService {
             }
             catch (e) {
                 if (attemptsMade < maxAttempts) {
-                    setTimeout(runAttempt, this.backoffDelay(options?.backoff, attemptsMade));
+                    // Fire-and-forget retry: runAttempt catches every error itself.
+                    setTimeout(() => void runAttempt(), this.backoffDelay(options?.backoff, attemptsMade));
                 }
                 else {
                     console.error(`[InMemoryQueue] Job ${jobId} on ${queueName} failed after ${attemptsMade} attempt(s):`, e.message);
@@ -32,7 +33,8 @@ export class InMemoryQueueService {
             }
         };
         const delay = options?.delay ?? 100 + Math.floor(Math.random() * 201);
-        setTimeout(runAttempt, delay);
+        // Fire-and-forget: runAttempt catches every error itself.
+        setTimeout(() => void runAttempt(), delay);
         return jobId;
     }
     backoffDelay(backoff, attemptsMade) {

package/dist/services/in-memory-workflow-service.js

@@ -1,4 +1,3 @@
-import { randomUUID } from 'crypto';
 import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js';
 import { isExpectedError } from '../errors/error-handler.js';
 import { isStepLeaseLive } from '../wirings/workflow/workflow-constants.js';
@@ -17,7 +16,7 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
     branchKeys = new Map(); // keyed by stepId
     workflowVersions = new Map(); // keyed by `${name}:${graphHash}`
     async createRunImpl(workflowName, input, inline, graphHash, wire, options) {
-        const runId = randomUUID();
+        const runId = globalThis.crypto.randomUUID();
         const now = new Date();
         const run = {
             id: runId,
@@ -41,7 +40,7 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         return runId;
     }
     async scheduleSleep(runId, stepId, duration) {
-        const timer = setTimeout(async () => {
+        const resume = async () => {
             this.sleepTimers.delete(timer);
             try {
                 await this.executeWorkflowSleepCompleted(runId, stepId);
@@ -49,7 +48,9 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
             catch (error) {
                 this.logger?.error(`Failed to resume workflow sleep for runId ${runId}: ${error?.message ?? error}`);
             }
-        }, duration);
+        };
+        // Fire-and-forget timer callback: resume catches and logs every error.
+        const timer = setTimeout(() => void resume(), duration);
         this.sleepTimers.add(timer);
         return true;
     }
@@ -71,7 +72,7 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         }
     }
     async insertStepStateImpl(runId, stepName, rpcName, data, stepOptions, fromStepName) {
-        const stepId = randomUUID();
+        const stepId = globalThis.crypto.randomUUID();
         const now = new Date();
         const step = {
             stepId,
@@ -202,7 +203,7 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
             throw new Error(`Step not found: ${failedStepId}`);
         }
         const failedStepData = this.stepData.get(failedStepId);
-        const newStepId = randomUUID();
+        const newStepId = globalThis.crypto.randomUUID();
         const now = new Date();
         const newStep = {
             stepId: newStepId,

package/dist/services/index.d.ts

@@ -21,7 +21,6 @@ export { LeaseLostError, LeaseTakenError, holdLease, type Lease, type LeaseServi
 export { InMemoryLeaseService } from './in-memory-lease-service.js';
 export { InMemoryAgentRunStateService } from './in-memory-agent-run-state-service.js';
 export { LocalGatewayService } from './local-gateway-service.js';
-export { FileScenarioRunStore, scenarioArtifactContentType, scenarioRunSummary, type FileScenarioRunStoreOptions, } from './file-scenario-run-store.js';
 export type { ContentService, SignContentKeyArgs, SignURLArgs, GetUploadURLArgs, UploadURLResult, BucketKeyArgs, WriteFileArgs, CopyFileArgs, } from './content-service.js';
 export type { ScenarioPersona, ResolvedPersona, ScenarioPersonas, } from './personas-service.js';
 export type { JWTService } from './jwt-service.js';

package/dist/services/index.js

@@ -21,7 +21,6 @@ export { LeaseLostError, LeaseTakenError, holdLease, } from './lease-service.js'
 export { InMemoryLeaseService } from './in-memory-lease-service.js';
 export { InMemoryAgentRunStateService } from './in-memory-agent-run-state-service.js';
 export { LocalGatewayService } from './local-gateway-service.js';
-export { FileScenarioRunStore, scenarioArtifactContentType, scenarioRunSummary, } from './file-scenario-run-store.js';
 export { renderEmail, } from './email-template.js';
 export { DEFAULT_WEBHOOK_RETRIES, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, } from './webhook-service.js';
 export { ACTOR_ROOT_SECRET_MIN_LENGTH, ACTOR_SECRET_INFO, ACTOR_SECRET_NAME, actorSecretSubject, deriveActorSecret, verifyActorSecret, } from './persona-actor-secret.js';

package/dist/services/local-variables.d.ts

@@ -1,6 +1,11 @@
 import type { VariablesService } from './variables-service.js';
 export declare class LocalVariablesService implements VariablesService {
     private variables;
+    /**
+     * Defaults to `process.env`, resolved when the service is built rather than
+     * when this module loads, and guarded so a runtime without `process` gets an
+     * empty store instead of a ReferenceError.
+     */
     constructor(variables?: Record<string, string | undefined>);
     getAll(): Record<string, string | undefined>;
     getVariables<T extends Record<string, unknown> = Record<string, unknown>>(names: (keyof T & string)[]): Partial<T>;

package/dist/services/local-variables.js

@@ -1,7 +1,12 @@
 export class LocalVariablesService {
     variables;
-    constructor(variables = process.env) {
-        this.variables = variables;
+    /**
+     * Defaults to `process.env`, resolved when the service is built rather than
+     * when this module loads, and guarded so a runtime without `process` gets an
+     * empty store instead of a ReferenceError.
+     */
+    constructor(variables) {
+        this.variables = variables ?? globalThis.process?.env ?? {};
     }
     getAll() {
         return this.variables || {};

package/dist/services/meta-service.d.ts

@@ -10,6 +10,7 @@ import type { FeaturesMeta } from '../wirings/workflow/scenario.types.js';
 import type { ResolvedPersona } from './personas-service.js';
 import type { SystemRoleDefinitionsMeta } from '../wirings/role/role.types.js';
 import type { FeatureFlagDefinitionsMeta } from '../wirings/flag/flag.types.js';
+import type { ScopeDefinitionsMeta } from '../wirings/scope/scope.types.js';
 import type { AnalyticsEventsMeta } from '../analytics/analytics.types.js';
 import type { TriggerMeta, TriggerSourceMeta } from '../wirings/trigger/trigger.types.js';
 import type { SecretDefinitionsMeta } from '../wirings/secret/secret.types.js';
@@ -156,6 +157,14 @@ export interface MetaService {
      * seed granted from rather than a second one.
      */
     getSystemRolesMeta(): Promise<SystemRoleDefinitionsMeta>;
+    /**
+     * The scope trees declared with `defineScope`, keyed by root, each carrying
+     * where it came from.
+     *
+     * The scope store holds the grantable ids; this holds what the store does
+     * not — a root's display name and which addon, if any, declared it.
+     */
+    getScopesMeta(): Promise<ScopeDefinitionsMeta>;
     /**
      * The flags declared with `defineFeatureFlags`, keyed by name.
      *
@@ -199,6 +208,7 @@ export declare class LocalMetaService implements MetaService {
     private workflowMetaCache;
     private personasMetaCache;
     private systemRolesMetaCache;
+    private scopesMetaCache;
     private featureFlagsMetaCache;
     private analyticsMetaCache;
     private featuresMetaCache;
@@ -236,6 +246,7 @@ export declare class LocalMetaService implements MetaService {
     getWorkflowMeta(): Promise<WorkflowsMeta>;
     getPersonasMeta(): Promise<Record<string, ResolvedPersona>>;
     getSystemRolesMeta(): Promise<SystemRoleDefinitionsMeta>;
+    getScopesMeta(): Promise<ScopeDefinitionsMeta>;
     getFeatureFlagsMeta(): Promise<FeatureFlagDefinitionsMeta>;
     getAnalyticsMeta(): Promise<AnalyticsEventsMeta>;
     getFeaturesMeta(): Promise<FeaturesMeta>;

package/dist/services/meta-service.js

@@ -16,6 +16,7 @@ export class LocalMetaService {
     workflowMetaCache = null;
     personasMetaCache = null;
     systemRolesMetaCache = null;
+    scopesMetaCache = null;
     featureFlagsMetaCache = null;
     analyticsMetaCache = null;
     featuresMetaCache = null;
@@ -115,6 +116,7 @@ export class LocalMetaService {
         this.workflowMetaCache = null;
         this.personasMetaCache = null;
         this.systemRolesMetaCache = null;
+        this.scopesMetaCache = null;
         this.featureFlagsMetaCache = null;
         this.analyticsMetaCache = null;
         this.featuresMetaCache = null;
@@ -216,7 +218,7 @@ export class LocalMetaService {
         if (this.rpcMetaCache)
             return this.rpcMetaCache;
         try {
-            const content = await this.readFile('rpc/pikku-rpc-wirings-meta.gen.json');
+            const content = await this.readFile('rpc/pikku-rpc-wirings-meta.internal.gen.json');
             this.rpcMetaCache = content ? JSON.parse(content) : {};
             return this.rpcMetaCache;
         }
@@ -278,6 +280,13 @@ export class LocalMetaService {
         this.systemRolesMetaCache = content ? JSON.parse(content) : {};
         return this.systemRolesMetaCache;
     }
+    async getScopesMeta() {
+        if (this.scopesMetaCache)
+            return this.scopesMetaCache;
+        const content = await this.readFile('scopes/pikku-scopes-meta.gen.json');
+        this.scopesMetaCache = content ? JSON.parse(content) : {};
+        return this.scopesMetaCache;
+    }
     async getFeatureFlagsMeta() {
         if (this.featureFlagsMetaCache)
             return this.featureFlagsMetaCache;

package/dist/services/queue-webhook-service.js

@@ -39,7 +39,7 @@ export class QueueWebhookService extends WebhookService {
         }
         if (secret) {
             const signatureHeader = webhookConfig?.signatureHeader ?? DEFAULT_WEBHOOK_SIGNATURE_HEADER;
-            headers[signatureHeader] = this.sign(secret, body);
+            headers[signatureHeader] = await this.sign(secret, body);
         }
         const jobData = {
             url: input.url,

package/dist/services/webhook-service.d.ts

@@ -87,9 +87,9 @@ export declare const DEFAULT_WEBHOOK_RETRIES = 3;
 export declare abstract class WebhookService {
     abstract send<T extends SendWebhookInput>(input: Safe<T>): Promise<SendWebhookResult>;
     /** Produces the header value, `sha256=<hex>`, not the bare digest. */
-    protected sign(secret: string, body: string): string;
+    protected sign(secret: string, body: string): Promise<string>;
     /** Public because receivers verify with it; they share the signing scheme. */
-    verify(secret: string, signature: string, body: string): boolean;
+    verify(secret: string, signature: string, body: string): Promise<boolean>;
     /**
      * The three methods below are optional capability: the default queue-only
      * service keeps no history, and a store-backed implementation (e.g.

package/dist/services/webhook-service.js

@@ -5,12 +5,14 @@ export const DEFAULT_WEBHOOK_SIGNATURE_HEADER = 'X-Pikku-Signature';
 export const DEFAULT_WEBHOOK_RETRIES = 3;
 export class WebhookService {
     /** Produces the header value, `sha256=<hex>`, not the bare digest. */
-    sign(secret, body) {
-        return `sha256=${hmacSha256Hex(secret, body)}`;
+    async sign(secret, body) {
+        return `sha256=${await hmacSha256Hex(secret, body)}`;
     }
     /** Public because receivers verify with it; they share the signing scheme. */
-    verify(secret, signature, body) {
-        return timingSafeStringEqual(this.sign(secret, body), signature);
+    async verify(secret, signature, body) {
+        if (!secret || !signature)
+            return false;
+        return timingSafeStringEqual(await this.sign(secret, body), signature);
     }
     /**
      * The three methods below are optional capability: the default queue-only

package/dist/types/core.types.d.ts

@@ -1,3 +1,4 @@
+import type { AbortScope } from '../function/abort-scope.js';
 import type { IncomingWebhookService } from '../services/incoming-webhook-service.js';
 import type { TriggerSourceStore } from '../services/trigger-source-store.js';
 import type { LeaseService } from '../services/lease-service.js';
@@ -287,7 +288,15 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     beginChanges: () => Promise<void>;
 }>;
 /** Wire as constructed by runners, before the function runner adds `rpc` and the credential readers. */
-export type PikkuRawWire = Omit<PikkuWire, 'rpc' | 'getCredential' | 'getCredentials'> & Partial<Pick<PikkuWire, 'getCredential' | 'getCredentials'>>;
+export type PikkuRawWire = Omit<PikkuWire, 'rpc' | 'getCredential' | 'getCredentials'> & Partial<Pick<PikkuWire, 'getCredential' | 'getCredentials'>> & {
+    /**
+     * Whether whatever asked for this work is still there. Set by wirings that
+     * can be abandoned (an interrupted agent run); the function runner binds
+     * `wire.beginChanges` to it. Carried through nested `rpc` calls by the
+     * wire spread, so a sub-call observes the same scope.
+     */
+    abortScope?: AbortScope;
+};
 export type CoreServices<SingletonServices = CoreSingletonServices> = SingletonServices;
 /** Strips `secrets` from a services type. */
 export type SecretlessServices<Services> = Omit<Services, 'secrets'>;

package/dist/utils/hmac.d.ts

@@ -1,22 +1,37 @@
 /**
- * HMAC-SHA256 of a payload, hex-encoded. Senders wrap this in their own scheme
- * prefix (`sha256=`, `v0=`, …).
+ * Web Crypto only: no `node:crypto` and no `Buffer`, so this loads on edge
+ * runtimes. Web Crypto is async, so everything that touches a key returns a
+ * Promise; `timingSafeStringEqual` is plain JS and stays synchronous.
  */
-export declare function hmacSha256Hex(secret: string, payload: string): string;
 /**
- * Constant-time signature comparison. Returns false on a length mismatch,
- * where `timingSafeEqual` itself throws.
+ * Constant-time string comparison (pure JS; for opaque tokens, not HMACs, which
+ * `verifyHmacSignature` checks with Web Crypto). Returns false on a length mismatch
+ * (the lengths of the two values are not secret).
  */
 export declare function timingSafeStringEqual(a: string, b: string): boolean;
 export type WebhookPayload = string | Uint8Array;
 export type HmacAlgorithm = 'sha1' | 'sha256' | 'sha512';
 export type SecretEncoding = 'utf8' | 'hex' | 'base64';
+/**
+ * HMAC-SHA256 of a payload, hex-encoded. Senders wrap this in their own scheme
+ * prefix (`sha256=`, `v0=`, …).
+ */
+export declare function hmacSha256Hex(secret: string, payload: string): Promise<string>;
 /** The HMAC of `payload` under `secret`, for handshakes that answer with a digest. */
-export declare function hmacDigest(secret: string, algorithm: HmacAlgorithm, payload: WebhookPayload, encoding: 'hex' | 'base64', secretEncoding?: SecretEncoding): string;
-/** Whether `signature` is the HMAC of `payload` under `secret`, compared in constant time. */
-export declare function verifyHmacSignature(secret: string, signature: string | undefined, algorithm: HmacAlgorithm, payload: WebhookPayload, encoding: 'hex' | 'base64', secretEncoding?: SecretEncoding): boolean;
-/** Whether `signature` (base64) is `payload` signed by the private half of `publicKey` (PEM). */
+export declare function hmacDigest(secret: string, algorithm: HmacAlgorithm, payload: WebhookPayload, encoding: 'hex' | 'base64', secretEncoding?: SecretEncoding): Promise<string>;
+/**
+ * Whether `signature` is the HMAC of `payload` under `secret`. Fails closed on
+ * an empty secret (or one that decodes to an empty key) and on a missing or
+ * malformed signature. The comparison is `crypto.subtle.verify('HMAC', ...)`,
+ * so it runs in the platform's constant-time implementation.
+ */
+export declare function verifyHmacSignature(secret: string, signature: string | undefined, algorithm: HmacAlgorithm, payload: WebhookPayload, encoding: 'hex' | 'base64', secretEncoding?: SecretEncoding): Promise<boolean>;
+/**
+ * Whether `signature` (base64) is `payload` signed by the private half of
+ * `publicKey` (an RSA, EC or Ed25519 PEM `SPKI` key). RSA-PSS keys are not
+ * supported and verify as false. Ed25519 ignores `algorithm` and `dsaEncoding`.
+ */
 export declare function verifyPublicKeySignature(publicKey: string, signature: string | undefined, payload: WebhookPayload, options?: {
     algorithm?: string;
     dsaEncoding?: 'der' | 'ieee-p1363';
-}): boolean;
+}): Promise<boolean>;