@pikku/core 0.12.72 → 0.12.77

package/dist/services/logger-console.d.ts

@@ -1,9 +1,6 @@
 import type { Logger } from './logger.js';
 import { LogLevel } from './logger.js';
-/**
- * Text-mode console logger.
- * Output: `INFO: message` or `[traceId] INFO: message`
- */
+/** Emits `INFO: message`, or `[traceId] INFO: message` when scoped. */
 export declare class ConsoleLogger implements Logger {
     private level;
     private prefix;
@@ -19,9 +16,8 @@ export declare class ConsoleLogger implements Logger {
     log(level: string, message: string, ...meta: any[]): void;
 }
 /**
- * JSON-mode console logger.
- * Output: `{"level":"info","message":"...","traceId":"..."}`
- * CF Workers Logs auto-indexes JSON keys for filtering.
+ * Emits `{"level":"info","message":"...","traceId":"..."}` — one JSON object per
+ * line, because Cloudflare Workers Logs auto-indexes JSON keys for filtering.
  */
 export declare class JsonConsoleLogger implements Logger {
     private level;

package/dist/services/logger-console.js

@@ -1,8 +1,5 @@
 import { LogLevel } from './logger.js';
-/**
- * Text-mode console logger.
- * Output: `INFO: message` or `[traceId] INFO: message`
- */
+/** Emits `INFO: message`, or `[traceId] INFO: message` when scoped. */
 export class ConsoleLogger {
     level = LogLevel.info;
     prefix;
@@ -61,9 +58,8 @@ export class ConsoleLogger {
     }
 }
 /**
- * JSON-mode console logger.
- * Output: `{"level":"info","message":"...","traceId":"..."}`
- * CF Workers Logs auto-indexes JSON keys for filtering.
+ * Emits `{"level":"info","message":"...","traceId":"..."}` — one JSON object per
+ * line, because Cloudflare Workers Logs auto-indexes JSON keys for filtering.
  */
 export class JsonConsoleLogger {
     level = LogLevel.info;

package/dist/services/logger.d.ts

@@ -1,5 +1,6 @@
+import type { Safe } from '../secret-value.js';
 export declare enum LogLevel {
-    'trace' = 0,// Add this level
+    'trace' = 0,
     'debug' = 1,
     'info' = 2,
     'warn' = 3,
@@ -7,47 +8,28 @@ export declare enum LogLevel {
     'critical' = 5
 }
 /**
- * Interface for logging messages at various levels.
+ * A log line is the easiest place to leak a vault secret, so every parameter is
+ * `Safe<>`-guarded: a `SecretValue` anywhere in the message or the metadata,
+ * however deeply nested, collapses to `never` and fails the build. Reveal it
+ * first if you genuinely mean to log it.
  */
 export interface Logger {
-    /**
-     * Logs an informational message.
-     * @param messageOrObj - The message or object to log.
-     * @param meta - Additional metadata to log.
-     */
-    info(messageOrObj: string | Record<string, any>, ...meta: any[]): void;
-    /**
-     * Logs a warning message.
-     * @param messageOrObj - The message or object to log.
-     * @param meta - Additional metadata to log.
-     */
-    warn(messageOrObj: string | Record<string, any>, ...meta: any[]): void;
-    /**
-     * Logs an error message.
-     * @param messageOrObj - The message, object, or error to log.
-     * @param meta - Additional metadata to log.
-     */
-    error(messageOrObj: string | Record<string, any> | Error, ...meta: any[]): void;
-    /**
-     * Logs a debug message.
-     * @param message - The message to log.
-     * @param meta - Additional metadata to log.
-     */
-    debug(message: string, ...meta: any[]): void;
-    /**
-     * Logs a trace message.
-     * @param message - The message to log.
-     * @param meta - Additional metadata to log.
-     */
-    trace?(message: string, ...meta: any[]): void;
-    /**
-     * Sets the logging level.
-     * @param level - The logging level to set.
-     */
+    info<M extends string | Record<string, any>, A extends unknown[]>(messageOrObj: Safe<M>, ...meta: {
+        [K in keyof A]: Safe<A[K]>;
+    }): void;
+    warn<M extends string | Record<string, any>, A extends unknown[]>(messageOrObj: Safe<M>, ...meta: {
+        [K in keyof A]: Safe<A[K]>;
+    }): void;
+    error<M extends string | Record<string, any> | Error, A extends unknown[]>(messageOrObj: Safe<M>, ...meta: {
+        [K in keyof A]: Safe<A[K]>;
+    }): void;
+    debug<A extends unknown[]>(message: string, ...meta: {
+        [K in keyof A]: Safe<A[K]>;
+    }): void;
+    trace?<A extends unknown[]>(message: string, ...meta: {
+        [K in keyof A]: Safe<A[K]>;
+    }): void;
     setLevel(level: LogLevel): void;
-    /**
-     * Creates a scoped logger with a traceId included in every log entry.
-     * Used per-request to correlate logs across function calls.
-     */
+    /** A logger carrying a traceId on every entry, taken per-request to correlate calls. */
     scope?(traceId: string): Logger;
 }

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

@@ -6,7 +6,8 @@ import type { QueueWorkersMeta } from '../wirings/queue/queue.types.js';
 import type { CLIMeta } from '../wirings/cli/cli.types.js';
 import type { MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from '../wirings/mcp/mcp.types.js';
 import type { FeaturesMeta, WorkflowsMeta } from '../wirings/workflow/workflow.types.js';
-import type { ScenarioActorConfig } from './scenario-actors-service.js';
+import type { ResolvedPersona } from './personas-service.js';
+import type { SystemRoleDefinitionsMeta } from '../wirings/role/role.types.js';
 import type { TriggerMeta, TriggerSourceMeta } from '../wirings/trigger/trigger.types.js';
 import type { SecretDefinitionsMeta } from '../wirings/secret/secret.types.js';
 import type { CredentialDefinitionsMeta } from '../wirings/credential/credential.types.js';
@@ -114,32 +115,21 @@ export interface EmailTemplateAssets {
     text: string;
     missing: string[];
 }
-/**
- * Abstraction over .pikku metadata file access.
- * All paths are relative to the .pikku root directory.
- *
- * Node.js uses LocalMetaService (filesystem).
- * Cloudflare uses an R2/KV implementation.
- */
+/** Every `relativePath` below is relative to the `.pikku` root directory. */
 export interface MetaService {
-    /** Base path for local filesystem implementations. Undefined for remote/non-local implementations. */
+    /** Undefined for remote/non-local implementations. */
     readonly basePath?: string;
-    /** Read a file's content by relative path. Returns null if not found. */
     readFile(relativePath: string): Promise<string | null>;
-    /** List files in a directory by relative path. Returns empty array if not found. */
     readDir(relativePath: string): Promise<string[]>;
-    /** Read a project source file relative to the project root (one level above .pikku). */
+    /** Relative to the project root, one level above `.pikku`. */
     readProjectFile(relativePath: string): Promise<string | null>;
     /**
-     * Read a file from an *installed addon package's* own `.pikku` directory
-     * (resolved from node_modules), NOT the app's `.pikku`. `relativePath` is
-     * relative to that package's `.pikku` root (use `../` to reach the package
-     * root itself, e.g. `../README.md`). Returns null if the package or file is
-     * absent. Only local/Node implementations resolve packages; remote impls omit
-     * this and callers guard with `?.`.
+     * Reads an *installed addon package's* own `.pikku`, not the app's, with
+     * `relativePath` rooted there (`../README.md` reaches the package root).
+     * Optional because only local/Node implementations resolve packages — remote
+     * ones omit it and callers guard with `?.`.
      */
     readPackageFile?(packageName: string, relativePath: string): Promise<string | null>;
-    /** List a directory inside an installed addon package's `.pikku`. */
     readPackageDir?(packageName: string, relativePath: string): Promise<string[]>;
     getHttpMeta(): Promise<HTTPWiringsMeta>;
     getChannelsMeta(): Promise<ChannelsMeta>;
@@ -150,7 +140,16 @@ export interface MetaService {
     getGatewayMeta(): Promise<GatewaysMeta>;
     getRpcMeta(): Promise<RPCMetaRecord>;
     getWorkflowMeta(): Promise<WorkflowsMeta>;
-    getScenarioActorsMeta(): Promise<Record<string, ScenarioActorConfig>>;
+    getPersonasMeta(): Promise<Record<string, ResolvedPersona>>;
+    /**
+     * The roles declared with `defineSystemRole`, keyed by name.
+     *
+     * A persona declares roles; a function checks scopes. Anything showing what a
+     * persona can reach — the console's persona page, a run's catalogue — needs
+     * this to get from one to the other, and needs it to be the same expansion the
+     * seed granted from rather than a second one.
+     */
+    getSystemRolesMeta(): Promise<SystemRoleDefinitionsMeta>;
     getFeaturesMeta(): Promise<FeaturesMeta>;
     getTriggerMeta(): Promise<TriggerMeta>;
     getTriggerSourceMeta(): Promise<TriggerSourceMeta>;
@@ -168,10 +167,6 @@ export interface MetaService {
     getSchemas(schemaNames: string[]): Promise<Record<string, JSONSchema7 | null>>;
     clearCache(): void;
 }
-/**
- * Node.js filesystem implementation of MetaService.
- * Reads .gen.json files from a local .pikku directory.
- */
 export declare class LocalMetaService implements MetaService {
     readonly basePath: string;
     private httpMetaCache;
@@ -183,7 +178,8 @@ export declare class LocalMetaService implements MetaService {
     private gatewayMetaCache;
     private rpcMetaCache;
     private workflowMetaCache;
-    private scenarioActorsMetaCache;
+    private personasMetaCache;
+    private systemRolesMetaCache;
     private featuresMetaCache;
     private triggerMetaCache;
     private triggerSourceMetaCache;
@@ -216,7 +212,8 @@ export declare class LocalMetaService implements MetaService {
     getRpcMeta(): Promise<RPCMetaRecord>;
     private readWorkflowMetaDir;
     getWorkflowMeta(): Promise<WorkflowsMeta>;
-    getScenarioActorsMeta(): Promise<Record<string, ScenarioActorConfig>>;
+    getPersonasMeta(): Promise<Record<string, ResolvedPersona>>;
+    getSystemRolesMeta(): Promise<SystemRoleDefinitionsMeta>;
     getFeaturesMeta(): Promise<FeaturesMeta>;
     getTriggerMeta(): Promise<TriggerMeta>;
     getTriggerSourceMeta(): Promise<TriggerSourceMeta>;

package/dist/services/meta-service.js

@@ -2,10 +2,6 @@ import { readFile, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
-/**
- * Node.js filesystem implementation of MetaService.
- * Reads .gen.json files from a local .pikku directory.
- */
 export class LocalMetaService {
     basePath;
     httpMetaCache = null;
@@ -17,7 +13,8 @@ export class LocalMetaService {
     gatewayMetaCache = null;
     rpcMetaCache = null;
     workflowMetaCache = null;
-    scenarioActorsMetaCache = null;
+    personasMetaCache = null;
+    systemRolesMetaCache = null;
     featuresMetaCache = null;
     triggerMetaCache = null;
     triggerSourceMetaCache = null;
@@ -57,10 +54,7 @@ export class LocalMetaService {
             return null;
         }
     }
-    // Resolve an installed addon package's root dir from the app's node_modules.
-    // The addon packages have no main `exports` entry, so `require.resolve(pkg)`
-    // throws; instead we walk the node_modules search paths (anchored at the app
-    // root, one level above `.pikku`) and pick the first that contains the package.
+    // knowledge: decisions/internals/addon-package-roots-resolve-by-walking-node-module-search-paths.md
     packageRootCache = new Map();
     resolvePackageRoot(packageName) {
         const cached = this.packageRootCache.get(packageName);
@@ -115,7 +109,8 @@ export class LocalMetaService {
         this.gatewayMetaCache = null;
         this.rpcMetaCache = null;
         this.workflowMetaCache = null;
-        this.scenarioActorsMetaCache = null;
+        this.personasMetaCache = null;
+        this.systemRolesMetaCache = null;
         this.featuresMetaCache = null;
         this.triggerMetaCache = null;
         this.triggerSourceMetaCache = null;
@@ -129,7 +124,6 @@ export class LocalMetaService {
         this.agentsMetaCache = null;
         this.schemaCache.clear();
     }
-    // -- Private helpers --
     async readMetaJson(dir, baseName) {
         const verbose = await this.readFile(`${dir}/${baseName}-verbose.gen.json`);
         if (verbose)
@@ -139,7 +133,6 @@ export class LocalMetaService {
             return minimal;
         return null;
     }
-    // -- Typed metadata accessors --
     async getHttpMeta() {
         if (this.httpMetaCache)
             return this.httpMetaCache;
@@ -248,9 +241,7 @@ export class LocalMetaService {
             return this.workflowMetaCache;
         try {
             const result = {};
-            // Scenarios keep their meta in `scenarios/meta` so nothing app-facing
-            // imports them, but they are still workflows to anything reading meta off
-            // disk — the console's scenario list among them.
+            // knowledge: decisions/internals/scenario-meta-lives-apart-from-app-meta-but-merges-when-read-off-disk.md
             await Promise.all([
                 this.readWorkflowMetaDir('workflow/meta', result),
                 this.readWorkflowMetaDir('scenarios/meta', result),
@@ -264,12 +255,20 @@ export class LocalMetaService {
             return this.workflowMetaCache;
         }
     }
-    async getScenarioActorsMeta() {
-        if (this.scenarioActorsMetaCache)
-            return this.scenarioActorsMetaCache;
-        const content = await this.readFile('workflow/scenario-actors.gen.json');
-        this.scenarioActorsMetaCache = content ? JSON.parse(content) : {};
-        return this.scenarioActorsMetaCache;
+    async getPersonasMeta() {
+        if (this.personasMetaCache)
+            return this.personasMetaCache;
+        const content = await this.readFile('workflow/personas.gen.json');
+        this.personasMetaCache = content ? JSON.parse(content) : {};
+        return this.personasMetaCache;
+    }
+    async getSystemRolesMeta() {
+        if (this.systemRolesMetaCache)
+            return this.systemRolesMetaCache;
+        // Beside the scopes it is composed from, which is where codegen writes it.
+        const content = await this.readFile('scopes/pikku-roles-meta.gen.json');
+        this.systemRolesMetaCache = content ? JSON.parse(content) : {};
+        return this.systemRolesMetaCache;
     }
     async getFeaturesMeta() {
         if (this.featuresMetaCache)
@@ -297,8 +296,6 @@ export class LocalMetaService {
             return this.functionsMetaCache;
         const [content, scenarioContent] = await Promise.all([
             this.readMetaJson('function', 'pikku-functions-meta'),
-            // Scenario steps register only into the scenario bootstrap, but they are
-            // still functions to anything reading meta off disk.
             this.readMetaJson('scenarios', 'pikku-scenario-functions-meta'),
         ]);
         this.functionsMetaCache = {
@@ -360,12 +357,7 @@ export class LocalMetaService {
         return this.variablesMetaCache;
     }
     async getEmailMeta() {
-        // Read fresh every call — never cache. The email meta file is generated by
-        // `pikku all`/`pikku emails generate` and is regenerated DURING a long-lived
-        // session (sandbox boots the orchestrator before the user project's codegen
-        // has written it). Caching here once returned an empty {templates:{}} that
-        // then stuck for the whole session, leaving the console emails screen blank
-        // even after the file appeared. A local JSON read is essentially free.
+        // knowledge: decisions/internals/email-meta-is-read-uncached-because-codegen-rewrites-it-mid-session.md
         const content = await this.readFile('email/pikku-emails-meta.gen.json');
         return content
             ? JSON.parse(content)
@@ -380,9 +372,7 @@ export class LocalMetaService {
         if (!emailsMeta.src) {
             throw new Error('No generated email metadata found. Run `pikku emails generate`.');
         }
-        // emailsMeta.src is an absolute path resolved by the CLI at generation time.
-        // Read directly rather than through readProjectFile (which prepends the project
-        // root and produces a wrong compound path when baseDir is absolute).
+        // knowledge: decisions/internals/generated-src-paths-in-pikku-meta-are-absolute.md
         const baseDir = emailsMeta.src;
         const readEmailFile = async (rel) => {
             try {
@@ -409,10 +399,6 @@ export class LocalMetaService {
             ...(templateText ? [] : ['text']),
         ];
         if (missing.length > 0) {
-            // Diagnostic for the intermittent "Missing source files" report: logs which
-            // process and which resolved baseDir saw the gap. Different pids across
-            // failures => multiple runtime workers with divergent cached `src`; same pid
-            // + transient absence => files being rewritten under us (e.g. regeneration).
             console.warn(`[email-assets] pid=${process.pid} template=${templateName} locale=${locale} baseDir=${baseDir} missing=${missing.join(',')}`);
         }
         return {

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

@@ -0,0 +1,134 @@
+import type { ConverseOptions, ActorFlowVerdict } from '../wirings/actor-flow/actor-flow.types.js';
+import type { PersonaMeta } from '../wirings/persona/persona.types.js';
+/**
+ * What the transport answered, for a step that treats the status as data.
+ *
+ * An HTTP response with its body already drained: the stream can only be read
+ * once, and a step's return value crosses into the run record, so the response
+ * object itself cannot travel. This is the shape every caller ends up with.
+ */
+export interface ScenarioHttpResponse<T = unknown> {
+    status: number;
+    ok: boolean;
+    /**
+     * The parsed JSON body — or, when the body was not JSON, the raw text it was
+     * parsed from, so an HTML error page is still readable rather than lost.
+     * `undefined` for an empty response.
+     *
+     * `T` is a claim the caller makes, not one the transport checked: a step that
+     * knows the route's payload names it here instead of casting at every use.
+     */
+    body: T;
+    /**
+     * The whole body as text, so an assertion can search it without knowing the
+     * payload's shape — and so an error body that is HTML rather than JSON still
+     * says what went wrong.
+     */
+    serialized: string;
+}
+/**
+ * Drain a response into the shape a step can carry: the parsed body (an empty
+ * one counting as no body at all) alongside the text it was parsed from.
+ *
+ * `invokeRaw` returns this, and a step that has to reach past a persona — a
+ * route with no RPC, an identity no persona can hold — reaches for this rather
+ * than writing the same record by hand.
+ */
+export declare const readScenarioHttpResponse: <T = unknown>(res: Response) => Promise<ScenarioHttpResponse<T>>;
+/** How to send one JSON request, for `postScenarioJson`. */
+export interface ScenarioJsonRequest {
+    /** Serialised as the JSON body. Omit for a request that carries none. */
+    body?: unknown;
+    /** Sent alongside `content-type: application/json`, and may override it. */
+    headers?: Record<string, string>;
+    /** Defaults to `POST` — the method every scenario route here answers. */
+    method?: string;
+    /**
+     * The `fetch` to send it with. Pass a `ScenarioCookieJar`'s to keep the
+     * session; the global `fetch` otherwise, which is what a step asserting on a
+     * sessionless call wants.
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * POST JSON somewhere and report what came back, without throwing on a 4xx/5xx.
+ *
+ * Every scenario that reaches past a persona was writing this by hand — the same
+ * `content-type`, the same `JSON.stringify`, the same drain — and the copies had
+ * drifted: some returned `res.json()`, which loses the status and throws
+ * outright when the target answers an empty body or an HTML error page. A
+ * refusal is the expected outcome of a permissions scenario, so it has to
+ * survive as data.
+ */
+export declare const postScenarioJson: <T = unknown>(url: string, { body, headers, method, fetch: send, }?: ScenarioJsonRequest) => Promise<ScenarioHttpResponse<T>>;
+/** Per-call transport options. */
+export interface ScenarioInvokeOptions {
+    /**
+     * Headers to send alongside the persona's own session. This is how a step
+     * expresses an identity no declared persona can — an impersonation header, or
+     * one of the header-shim principals a credential scenario invents.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * The RPC surface a persona can reach, as name → input/output. A project binds
+ * its generated exposed RPC map here; the default leaves every name open, which
+ * is what a persona built by hand (or by a third-party driver) gets.
+ */
+export type ScenarioRpcMap = Record<string, {
+    input: any;
+    output: any;
+}>;
+/**
+ * The persona a step's `actor` slot carries, for a project whose personas are
+ * known. No declared personas keeps the open type rather than collapsing to
+ * `never` — a project may still build one itself.
+ */
+export type ScenarioPersonaOf<TPersonas> = [keyof TPersonas] extends [never] ? ScenarioPersona : TPersonas[keyof TPersonas];
+/**
+ * A declared person, signed in and acting over the real transport.
+ *
+ * The runtime half of `definePersonas()`: sign-in materialises a user row
+ * flagged `actor: true`, and everything a step or a virtual user does goes
+ * through here.
+ */
+export interface ScenarioPersona<TAgentName extends string = string, TRpcMap extends ScenarioRpcMap = ScenarioRpcMap> {
+    /** The id it was declared under — what a step's `actor` slot names. */
+    readonly name: string;
+    /** Their address, computed from the id. Flows use it for invites/lookups. */
+    readonly email: string;
+    /** Invoke an exposed RPC as this person over the real transport. */
+    invoke<TName extends keyof TRpcMap & string>(rpcName: TName, data: TRpcMap[TName]['input']): Promise<TRpcMap[TName]['output']>;
+    /**
+     * The same call, reporting what the transport answered rather than throwing.
+     * A refusal is the expected outcome of a permissions or scopes scenario, and
+     * `invoke`'s error truncates the body that names which scope was missing.
+     */
+    invokeRaw<TName extends keyof TRpcMap & string>(rpcName: TName, data: TRpcMap[TName]['input'], options?: ScenarioInvokeOptions): Promise<ScenarioHttpResponse>;
+    /** Converse with a Pikku AI agent in character and return its verdict. */
+    converse(options: ConverseOptions<TAgentName>): Promise<ActorFlowVerdict>;
+    /**
+     * The roles this person actually holds on the stage, read back after signing
+     * in — what a run compares against the declaration before its first step.
+     *
+     * `null` when the target does not say. That is not the same as "no roles": a
+     * run that treats silence as an empty list refuses to start against every
+     * stage whose auth reports roles somewhere else, so the caller must decide
+     * whether it can verify at all.
+     */
+    sessionRoles(): Promise<string[] | null>;
+}
+/**
+ * A declared persona with its address filled in — what codegen writes and what
+ * a seed, a scenario run and a virtual-user run all read.
+ *
+ * The address is not declared. It is derived from the persona's id and the
+ * project's persona domain, so two people can never accidentally share one and
+ * sign in as the same user row — which would silently collapse exactly the
+ * isolation scenarios a second person exists for.
+ */
+export type ResolvedPersona = PersonaMeta & {
+    email: string;
+};
+/** The injected `personas` service: persona id → persona. */
+export type ScenarioPersonas = Record<string, ScenarioPersona>;

package/dist/services/personas-service.js

@@ -0,0 +1,40 @@
+/**
+ * Drain a response into the shape a step can carry: the parsed body (an empty
+ * one counting as no body at all) alongside the text it was parsed from.
+ *
+ * `invokeRaw` returns this, and a step that has to reach past a persona — a
+ * route with no RPC, an identity no persona can hold — reaches for this rather
+ * than writing the same record by hand.
+ */
+export const readScenarioHttpResponse = async (res) => {
+    const text = res.status === 204 ? '' : await res.text().catch(() => '');
+    return {
+        status: res.status,
+        ok: res.ok,
+        body: (text ? parseJsonBody(text) : undefined),
+        serialized: text,
+    };
+};
+const parseJsonBody = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+};
+/**
+ * POST JSON somewhere and report what came back, without throwing on a 4xx/5xx.
+ *
+ * Every scenario that reaches past a persona was writing this by hand — the same
+ * `content-type`, the same `JSON.stringify`, the same drain — and the copies had
+ * drifted: some returned `res.json()`, which loses the status and throws
+ * outright when the target answers an empty body or an HTML error page. A
+ * refusal is the expected outcome of a permissions scenario, so it has to
+ * survive as data.
+ */
+export const postScenarioJson = async (url, { body, headers, method = 'POST', fetch: send = fetch, } = {}) => readScenarioHttpResponse(await send(url, {
+    method,
+    headers: { 'content-type': 'application/json', ...headers },
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+}));

package/dist/services/pikku-user-id.js

@@ -1,15 +1,11 @@
 export const defaultPikkuUserIdResolver = (wire) => {
-    // Explicit pikkuUserId on wire (set by earlier middleware or runner)
     if (wire.pikkuUserId)
         return wire.pikkuUserId;
-    // Session userId (from auth middleware — user-defined session shape)
     const session = wire.session;
     if (session?.userId && typeof session.userId === 'string')
         return session.userId;
-    // Queue job: carried in job metadata
     if (wire.queue?.pikkuUserId)
         return wire.queue.pikkuUserId;
-    // Workflow: carried in run wire metadata
     if (wire.workflow?.pikkuUserId)
         return wire.workflow.pikkuUserId;
     return undefined;

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

@@ -1,54 +1,20 @@
 import type { JobOptions, QueueService } from '../wirings/queue/queue.types.js';
 import type { Logger } from './logger.js';
 import { type SendWebhookInput, type SendWebhookResult, type WebhookJobData, WebhookService } from './webhook-service.js';
-/**
- * Default {@link WebhookService} implementation: serializes and signs the
- * payload, then enqueues a delivery job onto the `pikku-outgoing-webhooks`
- * queue. The signature is computed at enqueue time so the signing key never
- * enters the queue payload; the actual HTTP POST happens in
- * {@link pikkuWebhookWorkerFunc}, and the queue's `attempts`/`backoff`
- * options drive retries.
- */
 export declare class QueueWebhookService extends WebhookService {
     protected queueService: QueueService;
-    /**
-     * The queue is a constructor dependency rather than a `getSingletonServices()`
-     * lookup so that a project wiring up outgoing webhooks without a queue fails
-     * to compile, instead of throwing on the first `send()`.
-     */
     constructor(queueService: QueueService);
     send(input: SendWebhookInput): Promise<SendWebhookResult>;
     /**
-     * Build the signed job payload and its retry options — the shared work a
-     * `send()` does before enqueueing. Factored out (and `protected`) so a
-     * store-backed subclass can persist a delivery row and attach its
-     * `deliveryId` without re-implementing signing or the retry policy.
+     * `protected` so a store-backed subclass can persist a delivery row and attach
+     * its `deliveryId` without re-implementing signing or the retry policy.
      */
     protected prepareDelivery(input: SendWebhookInput): Promise<{
         jobData: WebhookJobData;
         options: JobOptions;
     }>;
-    /**
-     * Resolve a delivery's retry policy into queue job options, mirroring the
-     * workflow service: per-call values win over `config.webhook` defaults, an
-     * explicitly-set `retries` (including 0) is always honored, and `attempts`
-     * is ALWAYS passed so the queue can never fall back to its own default.
-     * Backoff is exponential unless a concrete `retryDelay` selects a fixed one.
-     */
     private resolveJobOptions;
 }
-/**
- * Queue worker for the `pikku-outgoing-webhooks` queue: POSTs the delivery to its
- * target URL. Any non-2xx response (or network error) throws so the queue
- * retries the job according to the `attempts`/`backoff` set at enqueue time;
- * the queue runner logs each failed attempt.
- *
- * A `deliveryId` is only present when a store-backed `webhookService` (e.g.
- * `KyselyWebhookService`) enqueued the job, so each attempt (success or failure)
- * is persisted via `webhookService.recordAttempt` before the throw — the console
- * delivery history reflects every try, not just the outcome. The queue-only
- * default never sets a `deliveryId`, so its base `recordAttempt` is never hit.
- */
 export declare function pikkuWebhookWorkerFunc(services: {
     logger: Logger;
     webhookService?: WebhookService;