@pikku/core 0.12.94 → 0.12.96

package/CHANGELOG.md

@@ -1,3 +1,182 @@
+## 0.12.96
+
+### Patch Changes
+
+- 88629af: Say why a hot-reload import failed instead of only that it did.
+
+  The dev module runner caught every failure bare and returned `null`, and the reloader turned that into a single line: `Failed to import: … (keeping old code)`. Keeping the old code is the right call, but it leaves the running process disagreeing with the file on disk, and the only symptom is a function returning stale output while the editor shows the new source — `tsc` passes, every import resolves, and there is nothing anywhere to explain it.
+
+  `run` now returns `{ ok: true, exports }` or `{ ok: false, error }`, so the failure case cannot be read past, and the reloader prints the error's message and stack under the existing line. A failure matching pikku's own documented limitation — a file using top-level `await`, which the `cjs` emit cannot express — says so outright, because in that case nothing is wrong with the file and re-reading it will never reveal that.
+
+- f1ccfe3: A step ladder reads as one paragraph, not a list of restatements
+
+  Every step prefixed its actor with `the `, named that actor again, and repeated
+  the phase keyword. A three-step run by one person said their name three times
+  and `Given` three times, only read as English when the persona key happened to
+  be a role noun, and never said who that person was — the fabric template's own
+  placeholder came out as `the nadia opens /app`.
+
+  ```
+  Given yasser (the founder) signs in
+  When  yasser opens the dashboard
+  And   sees the audit log
+  And   nadia reviews the invite
+  ```
+
+  The article is gone: the actor key is the subject verbatim, so a persona named
+  after a person reads as that person. A repeated phase reads as `And`, the way
+  Gherkin has always written it. A step that continues both the phase and the
+  actor drops the repeated subject, because English drops a repeated subject in a
+  compound predicate — it takes both, since eliding across a phase change gives
+  `When opens the dashboard`, and a pronoun rather than a name would give `they
+sees`, step templates being authored in the third person singular.
+
+  An actor is introduced once, by the persona's `jobTitle` — prose someone wrote
+  for a reader. `roles` is authorisation, so a persona whose only description is a
+  `reviewer` grant gets no introduction rather than one assembled out of grants.
+  A row carries `sentenceWithRole` alongside `sentence`, set only where an actor
+  is first named, so a renderer can offer the introduction as a toggle without
+  parsing a composed sentence back apart.
+
+  `{placeholder}` filling, the `#ordinal` lookup for repeated step names and an
+  actorless step reading as its description alone are all unchanged.
+
+## 0.12.95
+
+### Patch Changes
+
+- 1cc50ef: Queue a workflow step that names another workflow, instead of running it inside its parent.
+
+  `dispatchStep` decided by reading `workflowQueued` off `rpc` meta, but `addWorkflow` never registers there, so a child workflow could never be queued. It always took the inline path: the parent started the child with `inline: true` and then sat in an unbounded `awaitRunEnd` poll, holding its run lock and that lock's connection until the child ended — and the child, being inline, ran its own `sleep` as a real in-process wait rather than a suspension. A parent whose child polled for fifteen minutes held two lock connections for fifteen minutes, and enough of them exhausted the lock pool and stalled every other run behind it.
+
+  A step naming a workflow now queues whenever a queue service exists, reaching the `ChildWorkflowStartedException` path that already unwinds the parent and resumes it when the child completes. An inline parent still runs its children inline.
+
+- a3deea4: Stop the scheduler declaring `auth: false` for every task.
+
+  A task whose middleware sets a session runs a session-taking function, and the
+  hardcoded `auth: false` made the runner log "requires a session but auth was
+  explicitly disabled — use pikkuSessionlessFunc instead" on every single run.
+  Nothing else changes: a task with no session still throws `MissingSessionError`
+  when its function needs one.
+
+- 2a02288: Let a virtual user run against a deployed stage.
+
+  Until now the scaffolded run could only sign its personas in with
+  `SCENARIO_ACTOR_SECRET`, which only `pikku dev` serves — so a run against a
+  deployed target failed before its first turn. `runVirtualUser` now takes an
+  optional short-lived Fabric operator token, handed in by whoever starts the run
+  and passed through to `createPersonas` as `operator`.
+
+  Handed in rather than fetched on demand: a stage that could ask for a token
+  would be holding a credential able to mint admin sessions for itself for as long
+  as the box lives. It holds one receipt, for one run, and the receipt expires. It
+  is never written to the run record — only `FABRIC_OPERATOR_TOKEN` in the
+  environment is read, and only as the fallback for a run nobody handed a token to.
+
+  `HttpPersonasConfig.signInPath` now applies to the operator path too, so an app
+  that mounts auth under `/api` can say so once.
+
+  The framework's own virtual-user RPCs no longer enter a virtual user's
+  catalogue. A persona whose role carries `virtualUser:*` could otherwise start
+  further runs, read back every run's transcript — an adversarial run's steps are
+  working exploits against the same app — and put a persona on a schedule that
+  outlives it.
+
+  The scheduled tick now runs as the platform user, and starts its runs through
+  the same door a person uses.
+
+  The scaffolded `startVirtualUserRun` RPC is gone — not the `startVirtualUserRun`
+  helper `@pikku/core/virtual-user` now exports, which is the shared record-writer
+  `runVirtualUser` calls. The RPC existed only so the tick could record a run
+  without holding a session, which meant the persona checks, the
+  production-disposition rule and the record lived in two places that would
+  eventually disagree. The tick calls `runVirtualUser` over RPC instead, and the
+  scaffold emits `virtualUserPlatformSession` to give it an identity:
+
+  ```ts
+  wireScheduler({
+    name: 'virtualUsers',
+    schedule: '0 * * * *',
+    middleware: [virtualUserPlatformSession],
+    func: tickVirtualUserSchedules,
+  })
+  ```
+
+  `pikku-platform` is the platform's own principal and already exists for exactly
+  this — a reserved user row created with no credential account of any kind, so no
+  sign-in method can resolve it, and one the user directory already filters out, so
+  unlike a seeded service account it costs no phantom member in any list, seat
+  count or bill.
+
+  The middleware is attached to the task rather than declared as tag middleware
+  over `/rpc`, which cannot set a session at all: `runScheduledTask` builds its
+  wire with a `sessionService`, so the session set here is the one the function is
+  frozen with. A tick wired without it is refused for want of a session, and one
+  carrying the wrong scope is refused on `virtualUser:run` — both now covered by
+  tests.
+
+  A Fabric operator can now actually start the run it signs in to start.
+
+  `fabric()` granted its operator row `admin` and nothing else. `admin` is this
+  package's own root — pikku's parent-grant rule walks down from a root that is
+  held, and the virtual-user scaffold declares `virtualUser` as a root of its own
+  precisely so a role can carry `virtualUser:run` without also implying
+  administration. So the operator was refused by `runVirtualUser`, the one
+  function the operator sign-in exists to reach.
+
+  The operator is now granted the roots in `OPERATOR_SCOPE_ROOTS`
+  (`admin`, `virtualUser`) rather than a bare `admin`. Listed rather than
+  collapsed to `*`, which would make every operator a superuser on every app for
+  the sake of one function: an operator still holds nothing in the application's
+  own domain, and a root the app never declared is skipped rather than stored.
+
+  The grant is also re-checked on every operator sign-in instead of only when the
+  row is created. It is deliberately logged rather than thrown, so a single
+  failure used to leave that operator permanently unprivileged with nothing to
+  retry it, and a root added to the set later would never have reached the
+  operators that already existed.
+
+  The scaffolds no longer keep their logic inside the CLI's template strings.
+
+  Code written as text inside a template literal is never compiled, never linted,
+  and testable only by matching the source the CLI emits — so a dead branch or a
+  duplicated loop survives there indefinitely. Five scaffolds were carrying real
+  logic that way, and it now lives in `@pikku/core` alongside the types it uses,
+  leaving each serializer to emit only what is genuinely per-application.
+
+  - **virtual-user** — 677 lines: the run driver, the persona and disposition
+    rules, the schedule writer and the serializers, now
+    `@pikku/core/virtual-user`. The guarantee that an operator token never
+    reaches the run record used to be a regex over emitted text; it is now
+    structural, because `startVirtualUserRun` has no parameter to pass one to.
+  - **workflow** — the two status streams were an ~80-line poll loop each,
+    identical apart from three fields, now one `streamWorkflowRunStatus` told
+    whether to be detailed. Fixes three latent bugs both copies shared: a
+    `setInterval(async …)` whose poll threw produced an unhandled rejection; a
+    poll that threw left the channel open rather than ending the stream; and the
+    interval fired whether or not the previous poll had returned, so a slow store
+    put two polls in flight and sent the init frame twice.
+  - **emails** — ~190 lines of HTML escaping, trusted-root allowlist and
+    single-pass substitution, now `renderEmail` in `@pikku/core/services`. This
+    was the security-sensitive one, and compiling it surfaced a bug the template
+    string had been hiding: `{{ content }}` was written unescaped in every render
+    rather than only in the layout it is the slot for, so a caller passing
+    `data.content` to a template that named it got raw HTML out. Nested lookups
+    also used `in`, which walks the prototype chain; nothing inherited actually
+    reached the output — every step past a prototype hit lands on a function,
+    which is neither traversed nor written — so that one is a closed door rather
+    than a fixed leak.
+  - **agent** — both callers built the same options object; now
+    `agentCallOptions`, typed against `AgentInput` rather than a second copy of
+    its shape.
+  - **console** — two branches that could only survive uncompiled: a catch block
+    identical to its try, and an if/else whose arms were the same call.
+
+  Behaviour is unchanged throughout, and the emitted modules are the same modules
+  — the emails scaffold's ten escaping tests pass untouched through core. The five
+  serializers shrink from 1,936 lines to 1,281, and what they used to emit is now
+  covered by 75 tests that run the code rather than by regexes over the text.
+
 ## 0.12.94
 
 ### Patch Changes

package/dist/dev/hot-reload.js

@@ -6,7 +6,7 @@ import { clearMiddlewareCache } from '../middleware-runner.js';
 import { clearPermissionsCache } from '../permissions.js';
 import { clearChannelMiddlewareCache } from '../wirings/channel/channel-middleware-runner.js';
 import { httpRouter } from '../wirings/http/routers/http-router.js';
-import { createModuleRunner } from './module-runner.js';
+import { createModuleRunner, isTopLevelAwaitLimitation, } from './module-runner.js';
 export { reloadGeneratedMeta, reconcileAddonRegistry } from './reload-meta.js';
 const isFunctionConfig = (value) => {
     return (typeof value === 'object' &&
@@ -40,6 +40,20 @@ const isWatchedTsFile = (filename) => {
         // Hidden files: editor/sed atomic-write temps must never trigger a reload.
         !basename(filename).startsWith('.'));
 };
+/** Not every reload failure is a mistake in the file: pikku's reloader emits
+ *  `cjs`, which has no way to express top-level `await`, so a perfectly valid
+ *  module can fail here forever. Saying so outright saves the reader from
+ *  hunting a bug that is not in their code. The stack is dropped in that case
+ *  because it points into esbuild rather than at anything actionable. */
+const reloadFailureReason = (error) => {
+    if (isTopLevelAwaitLimitation(error)) {
+        return (`  ${error.message}\n` +
+            '  This is a pikku limitation, not a mistake in your file: the hot-reloader compiles to `cjs`, ' +
+            'which cannot express top-level `await`. Move the awaited work into a function, or restart the ' +
+            'dev server to pick the file up.');
+    }
+    return `  ${error.stack ?? error.message}`;
+};
 export async function pikkuDevReloader(options) {
     const { srcDirectories, logger, pikkuDir = '.pikku' } = options;
     const absSrcDirs = srcDirectories.map((d) => resolve(d));
@@ -56,11 +70,17 @@ export async function pikkuDevReloader(options) {
             return;
         const compiledFile = await findCompiledFile(changedTsFile, srcDir, absPikkuDir);
         const importPath = compiledFile ?? changedTsFile;
-        const mod = await moduleRunner.run(importPath);
-        if (!mod) {
-            logger.error(`Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)`);
+        const result = await moduleRunner.run(importPath);
+        if (!result.ok) {
+            // Keeping the old code leaves the process disagreeing with the file on
+            // disk, and the only symptom is stale output from a function that looks
+            // correct in the editor — so the reason has to be printed here, where it
+            // is still known, rather than left for the developer to reconstruct.
+            logger.error(`Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)\n` +
+                reloadFailureReason(result.error));
             return;
         }
+        const mod = result.exports;
         // knowledge: decisions/internals/hot-reload-writes-into-the-function-map-captured-at-startup.md
         for (const [exportName, exportValue] of Object.entries(mod)) {
             if (!isFunctionConfig(exportValue))

package/dist/dev/module-runner.d.ts

@@ -1,10 +1,27 @@
+/** The outcome of one run. A failure carries its error rather than collapsing
+ *  to `null`: the caller keeps serving the previously-loaded code, so unless the
+ *  reason travels with the failure the running process silently disagrees with
+ *  the file on disk and nothing anywhere says why. */
+export type PikkuModuleRunResult = {
+    ok: true;
+    exports: Record<string, unknown>;
+} | {
+    ok: false;
+    error: Error;
+};
 export interface PikkuModuleRunner {
     /** Run a user module by absolute path. Repeated runs of one path overwrite a
-     *  single registry slot. Returns `null` on failure so the caller can keep the
-     *  previously-loaded code. */
-    run: (absPath: string) => Promise<Record<string, unknown> | null>;
+     *  single registry slot. Failure is returned, not thrown, so the caller can
+     *  keep the previously-loaded code — and the discriminant makes that case
+     *  impossible to read past by accident. */
+    run: (absPath: string) => Promise<PikkuModuleRunResult>;
     evict: (absPath: string) => void;
     clear: () => void;
     readonly size: number;
 }
+/** esbuild states pikku's one documented reload limitation only in the text of
+ *  its transform error. Matching it is worth the fragility: the developer's file
+ *  is correct, and no amount of re-reading it will reveal that the reloader —
+ *  not the file — is what cannot cope. */
+export declare const isTopLevelAwaitLimitation: (error: Error) => boolean;
 export declare const createModuleRunner: () => PikkuModuleRunner;

package/dist/dev/module-runner.js

@@ -13,6 +13,11 @@ const loadTransform = async () => {
     transformSync = esbuild.transformSync;
     return transformSync;
 };
+/** esbuild states pikku's one documented reload limitation only in the text of
+ *  its transform error. Matching it is worth the fragility: the developer's file
+ *  is correct, and no amount of re-reading it will reveal that the reloader —
+ *  not the file — is what cannot cope. */
+export const isTopLevelAwaitLimitation = (error) => /top-level await/i.test(error.message);
 export const createModuleRunner = () => {
     const registry = new Map();
     const run = async (filePath) => {
@@ -30,12 +35,20 @@ export const createModuleRunner = () => {
             const moduleObj = { exports: {} };
             fn(require, moduleObj.exports, moduleObj, absPath, dirname(absPath));
             registry.set(absPath, moduleObj.exports);
-            return moduleObj.exports;
+            return { ok: true, exports: moduleObj.exports };
         }
-        catch {
+        catch (thrown) {
             // A bad edit, or the one known limitation: a file using top-level
-            // `await`, which cannot be emitted in `cjs` form.
-            return null;
+            // `await`, which cannot be emitted in `cjs` form. Normalised to an
+            // `Error` so the caller always has a message and a stack to print
+            // without re-deriving them; a non-`Error` throw keeps its original value
+            // as the `cause`.
+            return {
+                ok: false,
+                error: thrown instanceof Error
+                    ? thrown
+                    : new Error(String(thrown), { cause: thrown }),
+            };
         }
     };
     return {

package/dist/services/email-template.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The renderer behind a generated `pikku-emails.gen.ts`.
+ *
+ * The generated module supplies the assets — theme, locale strings, partials and
+ * the templates themselves — and a typed wrapper over `renderEmail`. Everything
+ * here is the same for every application, which is why it lives in core rather
+ * than in the string the CLI writes: this is HTML escaping, and code inside a
+ * template literal is never compiled, never linted, and testable only by
+ * matching the text it emits.
+ */
+export interface EmailTemplateHashes {
+    contentHash: string;
+    htmlHash: string;
+    subjectHash: string;
+    textHash: string;
+}
+export interface EmailTemplateAssets {
+    html: string;
+    subject: string;
+    text: string;
+    variables: ReadonlyArray<string>;
+    hashes: Record<string, EmailTemplateHashes>;
+}
+export interface EmailAssets {
+    theme: Record<string, unknown>;
+    locales: Record<string, Record<string, unknown>>;
+    partials: Record<string, string>;
+    templates: Record<string, EmailTemplateAssets>;
+}
+export interface RenderEmailRequest {
+    name: string;
+    locale?: string;
+    data?: Record<string, unknown>;
+}
+export interface RenderedEmailResult {
+    locale: string;
+    subject: string;
+    html: string;
+    text?: string;
+    variables: ReadonlyArray<string>;
+    hash: string;
+}
+export declare const renderEmail: ({ theme, locales, partials, templates }: EmailAssets, { name, locale: requestedLocale, data }: RenderEmailRequest) => RenderedEmailResult;

package/dist/services/email-template.js

@@ -0,0 +1,139 @@
+/**
+ * The renderer behind a generated `pikku-emails.gen.ts`.
+ *
+ * The generated module supplies the assets — theme, locale strings, partials and
+ * the templates themselves — and a typed wrapper over `renderEmail`. Everything
+ * here is the same for every application, which is why it lives in core rather
+ * than in the string the CLI writes: this is HTML escaping, and code inside a
+ * template literal is never compiled, never linted, and testable only by
+ * matching the text it emits.
+ */
+const HTML_ESCAPES = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+};
+const escapeHtml = (value) => value.replace(/[&<>"']/g, (char) => HTML_ESCAPES[char] ?? char);
+// Matches the raw {{{ value }}} form before the escaped {{ value }} form, so the
+// opt-in escape hatch is never mistaken for a normal substitution.
+const TEMPLATE_TOKEN = /\{\{\{\s*([^{}]+?)\s*\}\}\}|\{\{\s*([^}]+?)\s*\}\}/g;
+const PARTIAL_TOKEN = /\{\{\s*>\s*([a-zA-Z0-9-_/.]+)\s*\}\}/g;
+const MAX_TEMPLATE_DEPTH = 5;
+// theme.json and the locale files ship with the templates, so they are treated as
+// template-author input: expanded before caller data and allowed to contain their
+// own placeholders. Everything else is caller-supplied.
+const TRUSTED_ROOTS = ['theme', 't'];
+const isTrustedKey = (key) => TRUSTED_ROOTS.includes(String(key.split('.')[0]));
+const getNestedValue = (source, path) => {
+    const segments = path.split('.');
+    let current = source;
+    for (const segment of segments) {
+        // `hasOwn`, not `in`: `in` walks the prototype chain, so a path is answered
+        // by what an object inherits rather than only by what it carries. Nothing
+        // inherited reaches the output today — every step past a prototype hit lands
+        // on a function, which is neither traversed nor written — so this closes the
+        // lookup rather than fixing a value that escapes through it.
+        if (!current ||
+            typeof current !== 'object' ||
+            !Object.hasOwn(current, segment)) {
+            return '';
+        }
+        current = current[segment];
+    }
+    return typeof current === 'string' || typeof current === 'number'
+        ? String(current)
+        : '';
+};
+const readToken = (rawTriple, rawDouble) => {
+    const raw = typeof rawTriple === 'string';
+    return { raw, key: String(raw ? rawTriple : rawDouble).trim() };
+};
+const expandPartials = (source, partials, depth = 0) => {
+    if (depth >= MAX_TEMPLATE_DEPTH)
+        return source;
+    let found = false;
+    const expanded = source.replace(PARTIAL_TOKEN, (_match, partialName) => {
+        found = true;
+        const partial = partials[String(partialName).trim()];
+        return typeof partial === 'string' ? partial : '';
+    });
+    return found ? expandPartials(expanded, partials, depth + 1) : expanded;
+};
+const expandTrusted = (source, context, escape) => {
+    let rendered = source;
+    for (let i = 0; i < MAX_TEMPLATE_DEPTH; i += 1) {
+        let found = false;
+        const next = rendered.replace(TEMPLATE_TOKEN, (match, rawTriple, rawDouble) => {
+            const { raw, key } = readToken(rawTriple, rawDouble);
+            if (!isTrustedKey(key))
+                return match;
+            found = true;
+            const value = getNestedValue(context, key);
+            return raw || !escape ? value : escapeHtml(value);
+        });
+        if (!found || next === rendered)
+            break;
+        rendered = next;
+    }
+    return rendered;
+};
+// A single substitution pass — the replacement text is never rescanned, so a
+// caller-supplied value can never be reinterpreted as a template.
+const substitute = (source, context, escape, slot) => source.replace(TEMPLATE_TOKEN, (_match, rawTriple, rawDouble) => {
+    const { raw, key } = readToken(rawTriple, rawDouble);
+    // `content` is the layout's slot for the body that was already rendered and
+    // escaped, so it is the one value written in raw. Only the layout gets it:
+    // honouring it everywhere would let a caller pass `data.content` into a
+    // template that happens to name it and have it emitted unescaped.
+    if (slot !== undefined && key === slot) {
+        return typeof context[slot] === 'string' ? context[slot] : '';
+    }
+    if (key.startsWith('>')) {
+        return '';
+    }
+    const value = getNestedValue(context, key);
+    return raw || !escape ? value : escapeHtml(value);
+});
+const renderTemplate = (source, partials, context, escape, slot) => {
+    const composed = expandTrusted(expandPartials(source, partials), context, escape);
+    return substitute(composed, context, escape, slot);
+};
+export const renderEmail = ({ theme, locales, partials, templates }, { name, locale: requestedLocale, data }) => {
+    const locale = requestedLocale ?? 'en';
+    const template = templates[name];
+    if (!template) {
+        throw new Error(`Unknown email template: ${name}`);
+    }
+    const strings = locales[locale];
+    if (!strings) {
+        throw new Error(`Unknown email locale: ${locale}`);
+    }
+    const values = data ?? {};
+    const appName = (typeof values.appName === 'string' && values.appName) ||
+        getNestedValue(theme, 'appName');
+    const baseContext = {
+        ...values,
+        locale,
+        theme,
+        t: strings,
+        appName,
+    };
+    const subject = renderTemplate(template.subject, partials, baseContext, false).trim();
+    const htmlBody = renderTemplate(template.html, partials, { ...baseContext, subject }, true);
+    const html = partials.layout
+        ? renderTemplate(partials.layout, partials, { ...baseContext, subject, content: htmlBody }, true, 'content')
+        : htmlBody;
+    const text = template.text
+        ? renderTemplate(template.text, partials, { ...baseContext, subject }, false).trim()
+        : undefined;
+    return {
+        locale,
+        subject,
+        html,
+        ...(text ? { text } : {}),
+        variables: template.variables,
+        hash: template.hashes[locale]?.contentHash ?? '',
+    };
+};

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

@@ -27,7 +27,12 @@ export interface HttpPersonasConfig {
     operator?: OperatorSignInOptions;
     /** Persona id → the declaration with its address filled in. */
     personas: Record<string, ResolvedPersona>;
-    /** Sign-in path under apiUrl. Default: the actor plugin's `/auth/sign-in/actor`. */
+    /**
+     * Sign-in path under apiUrl, for whichever of the two paths is in use — an
+     * app that mounts auth under `/api` moves both. Default: the actor plugin's
+     * `/auth/sign-in/actor`, or `/auth/sign-in/fabric` for an operator.
+     * {@link OperatorSignInOptions.signInPath} overrides it.
+     */
     signInPath?: string;
     /** Where the session (and its roles) is read back. Default `/auth/get-session`. */
     sessionPath?: string;

package/dist/services/http-personas.js

@@ -32,7 +32,10 @@ export class HttpPersona {
         this.config = config;
         this.jar = createCookieJar(config.apiUrl);
         if (config.operator) {
-            this.signIn = new OperatorSignIn(config.apiUrl, config.operator);
+            this.signIn = new OperatorSignIn(config.apiUrl, {
+                ...config.operator,
+                signInPath: config.operator.signInPath ?? config.signInPath,
+            });
         }
         else if (config.secret) {
             this.signIn = new ActorSignIn(config.apiUrl, config.secret, config.signInPath ?? '/auth/sign-in/actor');

package/dist/services/index.d.ts

@@ -21,6 +21,7 @@ export type { ContentService, SignContentKeyArgs, SignURLArgs, GetUploadURLArgs,
 export type { ScenarioPersona, ResolvedPersona, ScenarioPersonas, } from './personas-service.js';
 export type { JWTService } from './jwt-service.js';
 export type { EmailService, SendEmailInput, SendEmailResult, SendHTMLEmailInput, SendTemplateEmailInput, SendTextEmailInput, } from './email-service.js';
+export { renderEmail, type EmailAssets, type EmailTemplateAssets, type EmailTemplateHashes, type RenderEmailRequest, type RenderedEmailResult, } from './email-template.js';
 export { DEFAULT_WEBHOOK_RETRIES, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, type SendWebhookInput, type SendWebhookResult, type WebhookAttemptResult, type WebhookDeliveryRecord, type WebhookDeliveryWithAttempts, type WebhookJobData, type WebhookServiceConfig, } from './webhook-service.js';
 export type { Logger } from './logger.js';
 export type { SecretService, SecretValues } from './secret-service.js';

package/dist/services/index.js

@@ -17,6 +17,7 @@ export { InMemoryTriggerService } from './in-memory-trigger-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 { SchedulerService } from './scheduler-service.js';
 export { TypedCredentialService } from './typed-credential-service.js';

package/dist/wirings/agent/agent-prepare.d.ts

@@ -28,6 +28,20 @@ export declare function canAccessThread(storedResourceId: string, session: {
     userId?: string;
     orgId?: string;
 } | undefined): boolean;
+/**
+ * An agent call with the fields nobody supplied left out.
+ *
+ * Omitted rather than passed as `undefined`, because an explicit `undefined`
+ * overrides the agent's own declared default with nothing — a request that
+ * names no model would silently unset the one the agent declares.
+ *
+ * Shared by the scaffolded `run` and `stream` routes, which receive the same
+ * input and differ only in what they do with the reply. `agentName` is not part
+ * of it: both callers pass that separately, because `rpc.agent.run` and
+ * `rpc.agent.stream` take it as their first argument and type the rest
+ * against it.
+ */
+export declare const agentCallOptions: (input: AgentInput) => AgentInput;
 export type StreamAgentOptions = {
     requiresToolApproval?: 'all' | 'explicit' | false;
     onRunCreated?: (runId: string) => void;

package/dist/wirings/agent/agent-prepare.js

@@ -65,6 +65,30 @@ export function canAccessThread(storedResourceId, session) {
         return false;
     return principals.some((principal) => isOwnedByPrincipal(storedResourceId, principal));
 }
+/**
+ * An agent call with the fields nobody supplied left out.
+ *
+ * Omitted rather than passed as `undefined`, because an explicit `undefined`
+ * overrides the agent's own declared default with nothing — a request that
+ * names no model would silently unset the one the agent declares.
+ *
+ * Shared by the scaffolded `run` and `stream` routes, which receive the same
+ * input and differ only in what they do with the reply. `agentName` is not part
+ * of it: both callers pass that separately, because `rpc.agent.run` and
+ * `rpc.agent.stream` take it as their first argument and type the rest
+ * against it.
+ */
+export const agentCallOptions = (input) => ({
+    message: input.message,
+    threadId: input.threadId,
+    resourceId: input.resourceId,
+    ...(input.attachments ? { attachments: input.attachments } : {}),
+    ...(input.model ? { model: input.model } : {}),
+    ...(input.temperature !== undefined
+        ? { temperature: input.temperature }
+        : {}),
+    ...(input.context ? { context: input.context } : {}),
+});
 export const APPROVAL_REQUIRED = Symbol('pikku.ai.approvalRequired');
 /**
  * In-process brand proving a credential request was produced by pikku itself and

package/dist/wirings/agent/index.d.ts

@@ -7,6 +7,6 @@ export { voiceInput, NoSpeechDetectedError, SPOKEN_TURN, SPOKEN_TRANSCRIPT, } fr
 export { voiceOutput, unspeakableScripts, voiceForText, type SpeakableScripts, type VoiceOutputState, } from './voice-output.js';
 export { AgentInterruptedError, signalRunInterrupt } from './agent-interrupt.js';
 export type { AgentInterruption, AgentInterruptResult, InterruptibleRunHandle, } from './agent-interrupt.js';
-export { type RunAgentParams, type StreamAgentOptions, ToolApprovalRequired, ToolCredentialRequired, canAccessThread, isOwnedByPrincipal, threadOwnerConstraint, } from './agent-prepare.js';
+export { type RunAgentParams, type StreamAgentOptions, ToolApprovalRequired, ToolCredentialRequired, agentCallOptions, canAccessThread, isOwnedByPrincipal, threadOwnerConstraint, } from './agent-prepare.js';
 export { addAgent } from './agent-registry.js';
 export type { AgentInput, AgentsMeta, AgentMemoryConfig, AgentStep, AgentContentPart, AgentRunRow, AgentRunService, AgentRunState, AgentMessage, AgentStreamChannel, AgentStreamEvent, AgentThread, CoreAgent, PendingApproval, PikkuAgentMiddlewareHooks, } from './agent.types.js';

package/dist/wirings/agent/index.js

@@ -6,5 +6,5 @@ export { streamAgent, resumeAgent, interruptAgent } from './agent-stream.js';
 export { voiceInput, NoSpeechDetectedError, SPOKEN_TURN, SPOKEN_TRANSCRIPT, } from './voice-input.js';
 export { voiceOutput, unspeakableScripts, voiceForText, } from './voice-output.js';
 export { AgentInterruptedError, signalRunInterrupt } from './agent-interrupt.js';
-export { ToolApprovalRequired, ToolCredentialRequired, canAccessThread, isOwnedByPrincipal, threadOwnerConstraint, } from './agent-prepare.js';
+export { ToolApprovalRequired, ToolCredentialRequired, agentCallOptions, canAccessThread, isOwnedByPrincipal, threadOwnerConstraint, } from './agent-prepare.js';
 export { addAgent } from './agent-registry.js';

package/dist/wirings/scheduler/scheduler-runner.js

@@ -68,7 +68,6 @@ export async function runScheduledTask({ name, session, traceId, }) {
         await runPikkuFunc('scheduler', meta.name, meta.pikkuFuncId, {
             singletonServices,
             createWireServices,
-            auth: false,
             data: () => undefined,
             inheritedMiddleware: meta.middleware,
             wireMiddleware: task.middleware,

package/dist/wirings/virtual-user/index.d.ts

@@ -29,3 +29,4 @@ export { type AgentReachability, type ReachableAgent, } from './virtual-user-age
 export { IntentStack, intentsForPersona } from './virtual-user-intents.js';
 export { deriveCatalogue, deriveIntents, type SchemaMap, } from './virtual-user-derive.js';
 export { personaVirtualUserTarget, type PersonaTargetOptions, } from './virtual-user-target.js';
+export { executeVirtualUserRun, logVirtualUserTick, requireVirtualUserRunStore, requireVirtualUserScheduleStore, runnablePersona, serializeVirtualUserRun, serializeVirtualUserSchedule, serializeVirtualUserSteps, signInPathFor, startVirtualUserRun, VIRTUAL_USER_VARIABLES, virtualUserScheduleRunInput, writeVirtualUserSchedule, type ExecuteVirtualUserRunParams, type ScaffoldPersonas, type StartedVirtualUserRun, type StartVirtualUserRunParams, type WriteVirtualUserScheduleParams, } from './virtual-user-scaffold.js';

package/dist/wirings/virtual-user/index.js

@@ -7,3 +7,4 @@ export { catalogueClassification, catalogueLookup, isReadOnly, reachableCatalogu
 export { IntentStack, intentsForPersona } from './virtual-user-intents.js';
 export { deriveCatalogue, deriveIntents, } from './virtual-user-derive.js';
 export { personaVirtualUserTarget, } from './virtual-user-target.js';
+export { executeVirtualUserRun, logVirtualUserTick, requireVirtualUserRunStore, requireVirtualUserScheduleStore, runnablePersona, serializeVirtualUserRun, serializeVirtualUserSchedule, serializeVirtualUserSteps, signInPathFor, startVirtualUserRun, VIRTUAL_USER_VARIABLES, virtualUserScheduleRunInput, writeVirtualUserSchedule, } from './virtual-user-scaffold.js';

package/dist/wirings/virtual-user/virtual-user-derive.js

@@ -24,6 +24,15 @@ export const deriveCatalogue = (functions, schemas = {}) => {
         // knowledge: decisions/internals/only-exposed-functions-enter-a-virtual-user-catalogue.md
         if (meta.expose !== true)
             continue;
+        // A virtual user is not offered the machinery that runs virtual users. A
+        // persona whose role carries `virtualUser:*` would otherwise be able to
+        // start further runs, read every run's findings — an adversarial run's
+        // transcript is working exploits against this same app — and put a persona
+        // on a schedule that outlives it. Same reasoning as the scenario-step rule
+        // above: the tool is about the run, not about the product being explored.
+        if (meta.scopes?.some((scope) => scope.split(':')[0] === 'virtualUser')) {
+            continue;
+        }
         const inputSchema = meta.inputSchemaName
             ? schemas[meta.inputSchemaName]
             : undefined;