@pikku/schedule 0.12.8 → 0.12.10

package/CHANGELOG.md

@@ -1,3 +1,56 @@
+## 0.12.10
+
+### Patch Changes
+
+- de9af6a: RPCs for Pikku Studio's migrated screens. Runtime state that must be visible on a deployed app lives in `@pikku/addon-admin`; local-copy tools stay in `@pikku/addon-console`.
+
+  `@pikku/addon-admin`:
+
+  - `admin:getSchedulerHistory` returns each scheduled task's last run, next run and recent runs, from a new `SchedulerService.getTaskRuns()` (empty by default). `InMemorySchedulerService` records the last 50 runs per cron task with status, duration and error. Scope `admin:schedules:read`.
+  - `admin:getQueueHistory({ queueNames?, limit? })` returns live counts and recent jobs per queue, from a new optional `QueueService.inspect(queueName, { limit })`, implemented by `InMemoryQueueService` and `BullQueueService` and forwarded by `SignedQueueService`. Scope `admin:queues:read`.
+  - `admin:listIncomingWebhookReceipts` / `admin:getIncomingWebhookReceipt` expose received webhooks, backed by a new `IncomingWebhookService.getReceipt(receiptId)` (null by default; implemented by `KyselyIncomingWebhookService`). Scope `admin:webhooks:read`.
+
+  `@pikku/addon-console`:
+
+  - `console:variableGet` / `console:variableSet` read and write a project variable, gated on `pikku:console:variables:read` / `:write`.
+  - `console:runScenarios({ names?, environment? })` starts `pikku scenario run` as a detached child process and returns `{ runId }` to follow through `listScenarioRuns` / `getScenarioRun`, gated on the new `pikku:console:scenarios:run` scope. `pikku scenario run` takes `--run-id <id>` to record under a caller-chosen id.
+
+- Updated dependencies [de9af6a]
+  - @pikku/core@0.12.143
+
+## 0.12.9
+
+### Patch 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.
+
+- Updated dependencies [6f11bb5]
+- Updated dependencies [0c67e33]
+- Updated dependencies [15c4968]
+- Updated dependencies [d75a23d]
+- Updated dependencies [9b12c8a]
+  - @pikku/core@0.12.138
+
 ## 0.12.8
 
 ### Patch Changes

package/dist/in-memory-scheduler-service.d.ts

@@ -1,5 +1,6 @@
 import type { CoreUserSession } from '@pikku/core/types';
 import type { ScheduledTaskInfo, ScheduledTaskSummary } from '@pikku/core/services';
+import type { ScheduledTaskRuns } from '@pikku/core/scheduler';
 import { SchedulerService } from '@pikku/core/services';
 /**
  * In-memory SchedulerService implementation.
@@ -8,6 +9,7 @@ import { SchedulerService } from '@pikku/core/services';
 export declare class InMemorySchedulerService extends SchedulerService {
     private cronJobs;
     private delayedTasks;
+    private taskRuns;
     private idCounter;
     init(): Promise<void>;
     /**
@@ -17,6 +19,7 @@ export declare class InMemorySchedulerService extends SchedulerService {
     unschedule(taskId: string): Promise<boolean>;
     getTask(taskId: string): Promise<ScheduledTaskInfo | null>;
     getAllTasks(): Promise<ScheduledTaskSummary[]>;
+    getTaskRuns(): Promise<Record<string, ScheduledTaskRuns>>;
     close(): Promise<void>;
     /**
      * Start recurring scheduled tasks.
@@ -27,4 +30,5 @@ export declare class InMemorySchedulerService extends SchedulerService {
      */
     stop(): Promise<void>;
     private startCronJob;
+    private recordRun;
 }

package/dist/in-memory-scheduler-service.js

@@ -5,6 +5,7 @@ import { pikkuState, getSingletonServices } from '@pikku/core/state';
 import { runScheduledTask } from '@pikku/core/scheduler';
 import { getScheduledTasks } from '@pikku/core/scheduler';
 import { rpcService } from '@pikku/core/rpc';
+const RUN_HISTORY_LIMIT = 50;
 const getLogger = () => {
     return pikkuState(null, 'package', 'singletonServices').logger;
 };
@@ -15,6 +16,7 @@ const getLogger = () => {
 export class InMemorySchedulerService extends SchedulerService {
     cronJobs = new Map();
     delayedTasks = new Map();
+    taskRuns = new Map();
     idCounter = 0;
     async init() { }
     /**
@@ -24,7 +26,7 @@ export class InMemorySchedulerService extends SchedulerService {
         const delayMs = typeof delay === 'string' ? parseDurationString(delay) : delay;
         const taskId = `inmem-${++this.idCounter}-${Date.now()}`;
         const scheduledFor = new Date(Date.now() + delayMs);
-        const timer = setTimeout(async () => {
+        const run = async () => {
             this.delayedTasks.delete(taskId);
             try {
                 // An RPC, not a cron task. `runScheduledTask` looks the name up in the
@@ -48,6 +50,10 @@ export class InMemorySchedulerService extends SchedulerService {
             catch (err) {
                 getLogger().error(`Failed to execute delayed RPC '${rpcName}': ${err}`);
             }
+        };
+        // `run` catches and logs every error itself, so nothing can reject
+        const timer = setTimeout(() => {
+            void run();
         }, delayMs);
         this.delayedTasks.set(taskId, {
             taskId,
@@ -88,6 +94,18 @@ export class InMemorySchedulerService extends SchedulerService {
             scheduledFor: t.scheduledFor,
         }));
     }
+    async getTaskRuns() {
+        const runs = {};
+        for (const [name, job] of this.cronJobs) {
+            const history = this.taskRuns.get(name) ?? [];
+            runs[name] = {
+                nextRun: job.isActive ? job.nextDate().toJSDate() : null,
+                lastRun: history[0] ?? null,
+                history: [...history],
+            };
+        }
+        return runs;
+    }
     async close() {
         await this.stop();
         // Clear delayed tasks
@@ -110,16 +128,38 @@ export class InMemorySchedulerService extends SchedulerService {
      */
     async stop() {
         for (const [, job] of this.cronJobs) {
-            job.stop();
+            await job.stop();
         }
         this.cronJobs.clear();
     }
     startCronJob(name, schedule) {
         const job = new CronJob(schedule, async () => {
-            getLogger().info(`Running scheduled task: ${name}`);
-            await runScheduledTask({ name });
-            getLogger().debug(`Completed scheduled task: ${name}`);
+            const startedAt = new Date();
+            try {
+                getLogger().info(`Running scheduled task: ${name}`);
+                await runScheduledTask({ name });
+                getLogger().debug(`Completed scheduled task: ${name}`);
+                this.recordRun(name, startedAt, 'completed', null);
+            }
+            catch (err) {
+                const skipped = err instanceof Error && err.name === 'ScheduledTaskSkippedError';
+                this.recordRun(name, startedAt, skipped ? 'skipped' : 'failed', err instanceof Error ? err.message : String(err));
+                if (!skipped) {
+                    getLogger().error(`Scheduled task '${name}' failed: ${err}`);
+                }
+            }
         }, null, true);
         this.cronJobs.set(name, job);
     }
+    recordRun(name, startedAt, status, error) {
+        const history = this.taskRuns.get(name) ?? [];
+        history.unshift({
+            startedAt,
+            status,
+            durationMs: Date.now() - startedAt.getTime(),
+            error,
+        });
+        history.length = Math.min(history.length, RUN_HISTORY_LIMIT);
+        this.taskRuns.set(name, history);
+    }
 }

package/knowledge/index.md

@@ -0,0 +1,13 @@
+---
+type: overview
+title: Knowledge
+description: Questions raised by the schedule package's in-memory scheduler
+---
+
+# Knowledge
+
+Questions about how the schedule package runs delayed work, where the code does not say what is intended.
+
+<!-- pikku:knowledge-index -->
+- [questions](questions/index.md) — something asked and not yet answered
+<!-- /pikku:knowledge-index -->

package/knowledge/questions/index.md

@@ -0,0 +1,13 @@
+---
+type: overview
+title: Questions
+description: Things asked of the schedule package and not yet answered
+---
+
+# Questions
+
+Something asked and not yet answered. The choice stays, the doubt gets recorded.
+
+<!-- pikku:knowledge-index -->
+- [Should a delayed RPC run as the session it was scheduled with?](should-a-delayed-rpc-run-as-the-session-it-was-scheduled-with.md) — The in-memory scheduler stores the session with the task and returns it from getTask, but the timer runs the RPC without it
+<!-- /pikku:knowledge-index -->

package/knowledge/questions/should-a-delayed-rpc-run-as-the-session-it-was-scheduled-with.md

@@ -0,0 +1,22 @@
+---
+type: question
+title: Should a delayed RPC run as the session it was scheduled with?
+description: The in-memory scheduler stores the session with the task and returns it from getTask, but the timer runs the RPC without it
+tags: [schedule, sessions, rpc]
+---
+
+# Should a delayed RPC run as the session it was scheduled with?
+
+`scheduleRPC` in `packages/schedule/src/in-memory-scheduler-service.ts` takes an optional `session`
+(line 45). It stores it on the task (lines 85-92), and `getTask` returns it (line 115).
+
+The timer callback `run` (line 52) calls `rpcService.getContextRPCService(services, {}, false)` (lines 69-74)
+and then `rpc.invoke(rpcName, data)` (line 75). The `session` is not passed to either call and is not in
+scope inside `run`.
+
+The comment at lines 67-68 says the BullMQ and pg-boss schedulers "enqueue `{ rpcName, data, session }`
+and invoke the RPC with it". This file does not do that for the session.
+
+Question: should the in-memory scheduler run the RPC as the captured session, as the comment says the other
+schedulers do, or is a delayed RPC meant to run with no user? The code does not settle it, and no note in
+this package records the choice.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/schedule",
-  "version": "0.12.8",
+  "version": "0.12.10",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -24,7 +24,7 @@
     "prepublishOnly": "bun run build"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.108"
+    "@pikku/core": "^0.12.143"
   },
   "devDependencies": {
     "@types/node": "^24.13.3"