@pikku/core 0.12.137 → 0.12.139

package/CHANGELOG.md

@@ -1,3 +1,43 @@
+## 0.12.139
+
+### Patch Changes
+
+- a196a21: A call over HTTP that names an add-on in `x-pikku-addon` can only reach that add-on's own functions and the add-ons it lists in `uses`. `rpc.exposed` now refuses anything else, including host functions and an add-on nobody wired, and `AddonNotUsedError` answers 403.
+- 53ac40d: An addon can ship screens: `wireAddon({ ui: true })` mounts what the package declares with `defineScreens`, the inspector reads them, `pikku all` emits the screens manifest and the installed-addons registry, and `x-pikku-addon` narrows a session to the addon's role. `pikku new addon --ui` scaffolds one; its tables must be prefixed `<name>_`.
+- 443fd40: Local content uploads stream to disk instead of being buffered in memory, and a rejected or aborted upload leaves no file behind. A 300 MB upload and read no longer grows the server's memory with the file.
+- 56c8047: Content services support `visibility: 'private' | 'public'` (default private). `ContentService` gains `getDownloadURL`, `deleteByPrefix` and `listFilesByPrefix`. `LocalContent` stores under `private/` and `public/` and serves public files unsigned at `<assetUrlPrefix>/_public/<bucket>/<key>`; unprefixed files from before still read as private, and a private bucket may not be named `_public`. S3 makes public objects `public-read` per object (the bucket must allow ACLs), Backblaze uses `publicBucketId` when set, and the scoped addon content service passes visibility through and keeps the new methods inside the addon's folder.
+
+## 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

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/addon-scope-cap.d.ts

@@ -0,0 +1,19 @@
+export declare const ADDON_HEADER = "x-pikku-addon";
+/**
+ * Narrows the session to what an addon is allowed to do. A call that names an
+ * addon in `x-pikku-addon` keeps only the scopes both the viewer and the
+ * addon's role hold, so an addon's screens can never act beyond what it
+ * declared, whoever is looking at them.
+ *
+ * The header is a selector, not a credential: naming an addon can only
+ * reduce a session, so a caller who sends it by hand has capped themselves. An
+ * addon the host does not know is refused, because ignoring it would let a
+ * misspelt name run uncapped.
+ *
+ * Register it after the session middleware: it narrows a session that is
+ * already resolved, and a call with no session has nothing to narrow.
+ */
+export declare const addonScopeCap: import("./middleware.types.js").CorePikkuMiddlewareFactory<{
+    /** The scopes of the addon's role, or `undefined` when no such addon is installed. */
+    resolve: (name: string) => readonly string[] | undefined | Promise<readonly string[] | undefined>;
+}>;

package/dist/middleware/addon-scope-cap.js

@@ -0,0 +1,34 @@
+import { ForbiddenError } from '../errors/errors.js';
+import { intersectScopes } from '../scopes.js';
+import { pikkuMiddleware, pikkuMiddlewareFactory, } from './middleware-factories.js';
+export const ADDON_HEADER = 'x-pikku-addon';
+/**
+ * Narrows the session to what an addon is allowed to do. A call that names an
+ * addon in `x-pikku-addon` keeps only the scopes both the viewer and the
+ * addon's role hold, so an addon's screens can never act beyond what it
+ * declared, whoever is looking at them.
+ *
+ * The header is a selector, not a credential: naming an addon can only
+ * reduce a session, so a caller who sends it by hand has capped themselves. An
+ * addon the host does not know is refused, because ignoring it would let a
+ * misspelt name run uncapped.
+ *
+ * Register it after the session middleware: it narrows a session that is
+ * already resolved, and a call with no session has nothing to narrow.
+ */
+export const addonScopeCap = pikkuMiddlewareFactory(({ resolve }) => pikkuMiddleware(async (_services, { http, setSession, getSession }, next) => {
+    const name = http?.request?.header(ADDON_HEADER);
+    const session = await getSession?.();
+    if (!name || !setSession || !session) {
+        return next();
+    }
+    const role = await resolve(name);
+    if (!role) {
+        throw new ForbiddenError(`Unknown addon '${name}'`);
+    }
+    await setSession({
+        ...session,
+        scopes: intersectScopes(session.scopes, role),
+    });
+    return next();
+}));

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/middleware/index.d.ts

@@ -1,6 +1,7 @@
 export { authAPIKey } from './auth-apikey.js';
 export { authCookie } from './auth-cookie.js';
 export { authBearer } from './auth-bearer.js';
+export { addonScopeCap, ADDON_HEADER, } from './addon-scope-cap.js';
 export { remoteJobsSecret } from './remote-jobs-secret.js';
 export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
 export { cors } from './cors.js';

package/dist/middleware/index.js

@@ -1,6 +1,7 @@
 export { authAPIKey } from './auth-apikey.js';
 export { authCookie } from './auth-cookie.js';
 export { authBearer } from './auth-bearer.js';
+export { addonScopeCap, ADDON_HEADER, } from './addon-scope-cap.js';
 export { remoteJobsSecret } from './remote-jobs-secret.js';
 export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
 export { cors } from './cors.js';

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/scopes.d.ts

@@ -21,3 +21,11 @@ export declare const hasAnyScope: (candidates: readonly string[] | undefined, he
  * nothing.
  */
 export declare const verifyScopes: (required: readonly string[] | undefined, session: CoreUserSession | undefined) => void;
+/**
+ * The scopes both `held` and `cap` grant, by the same parent and wildcard rules
+ * as {@link hasScopes}. Where one side is broader, the narrower grant is kept:
+ * a holder of `invoices:*` capped to `invoices:read` ends with `invoices:read`,
+ * and a holder of `invoices:read` capped to `invoices:*` keeps `invoices:read`.
+ * Fails closed: nothing held, or an empty cap, yields nothing.
+ */
+export declare const intersectScopes: (held: Iterable<string> | undefined, cap: Iterable<string> | undefined) => string[];

package/dist/scopes.js

@@ -64,3 +64,26 @@ export const verifyScopes = (required, session) => {
         throw new MissingScopeError(missing);
     }
 };
+/**
+ * The scopes both `held` and `cap` grant, by the same parent and wildcard rules
+ * as {@link hasScopes}. Where one side is broader, the narrower grant is kept:
+ * a holder of `invoices:*` capped to `invoices:read` ends with `invoices:read`,
+ * and a holder of `invoices:read` capped to `invoices:*` keeps `invoices:read`.
+ * Fails closed: nothing held, or an empty cap, yields nothing.
+ */
+export const intersectScopes = (held, cap) => {
+    const heldSet = new Set(held ?? []);
+    const capSet = new Set(cap ?? []);
+    const result = new Set();
+    for (const scope of heldSet) {
+        if (holds(capSet, scope)) {
+            result.add(scope);
+        }
+    }
+    for (const scope of capSet) {
+        if (holds(heldSet, scope)) {
+            result.add(scope);
+        }
+    }
+    return [...result];
+};

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

@@ -1,6 +1,8 @@
+export type ContentVisibility = 'private' | 'public';
 export interface SignContentKeyArgs<TBucket extends string = string> {
     bucket: TBucket;
     contentKey: string;
+    visibility?: ContentVisibility;
     dateLessThan: Date;
     dateGreaterThan?: Date;
 }
@@ -14,7 +16,7 @@ export interface GetUploadURLArgs<TBucket extends string = string> {
     fileKey: string;
     contentType: string;
     size?: number;
-    visibility?: 'private' | 'public';
+    visibility?: ContentVisibility;
 }
 export interface UploadURLResult {
     uploadUrl: string;
@@ -25,6 +27,10 @@ export interface UploadURLResult {
 export interface BucketKeyArgs<TBucket extends string = string> {
     bucket: TBucket;
     key: string;
+    visibility?: ContentVisibility;
+}
+export interface GetDownloadURLArgs<TBucket extends string = string> extends BucketKeyArgs<TBucket> {
+    expiresInSeconds?: number;
 }
 export interface WriteFileArgs<TBucket extends string = string> extends BucketKeyArgs<TBucket> {
     stream: ReadableStream | NodeJS.ReadableStream;
@@ -42,4 +48,10 @@ export interface ContentService<TBucket extends string = string> {
     copyFile(args: CopyFileArgs<TBucket>): Promise<boolean>;
     readFile(args: BucketKeyArgs<TBucket>): Promise<ReadableStream | NodeJS.ReadableStream>;
     readFileAsBuffer(args: BucketKeyArgs<TBucket>): Promise<Buffer>;
+    /** A signed URL for private content, the plain URL for public content. */
+    getDownloadURL(args: GetDownloadURLArgs<TBucket>): Promise<string>;
+    /** Returns how many files were deleted. */
+    deleteByPrefix(bucket: TBucket, prefix: string, visibility?: ContentVisibility): Promise<number>;
+    /** Returns the keys, relative to the bucket, that start with the prefix. */
+    listFilesByPrefix(bucket: TBucket, prefix: string, visibility?: ContentVisibility): Promise<string[]>;
 }

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

@@ -1,6 +1,7 @@
 export { LogLevel } from './logger.js';
 export { ScopedSecretService } from './scoped-secret-service.js';
 export { ScopedCredentialService } from './scoped-credential-service.js';
+export { ScopedContentService } from './scoped-content-service.js';
 export { PikkuSessionService, createMiddlewareSessionWireProps, } from './user-session-service.js';
 export { TypedSecretService } from './typed-secret-service.js';
 export { PikkuCredentialWireService } from './credential-wire-service.js';
@@ -21,8 +22,7 @@ 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 { ContentService, ContentVisibility, GetDownloadURLArgs, 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';
 export type { EmailAttachment, EmailService, SendEmailInput, SendEmailResult, SendHTMLEmailInput, SendTemplateEmailInput, SendTextEmailInput, } from './email-service.js';

package/dist/services/index.js

@@ -1,6 +1,7 @@
 export { LogLevel } from './logger.js';
 export { ScopedSecretService } from './scoped-secret-service.js';
 export { ScopedCredentialService } from './scoped-credential-service.js';
+export { ScopedContentService } from './scoped-content-service.js';
 export { PikkuSessionService, createMiddlewareSessionWireProps, } from './user-session-service.js';
 export { TypedSecretService } from './typed-secret-service.js';
 export { PikkuCredentialWireService } from './credential-wire-service.js';
@@ -21,7 +22,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';