@pikku/core 0.12.142 → 0.12.143

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## 0.12.143
+
+### 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.
+
 ## 0.12.142
 
 ### Patch Changes

package/dist/services/in-memory-queue-service.d.ts

@@ -1,8 +1,15 @@
-import type { QueueService, JobOptions } from '../wirings/queue/queue.types.js';
+import type { QueueService, JobOptions, QueueInspection } from '../wirings/queue/queue.types.js';
 export declare class InMemoryQueueService implements QueueService {
     readonly supportsResults = false;
     private jobCounter;
+    private jobs;
+    private finishedTotals;
     add<T>(queueName: string, data: T, options?: JobOptions): Promise<string>;
     private backoffDelay;
     getJob(): Promise<null>;
+    inspect(queueName: string, opts?: {
+        limit?: number;
+    }): Promise<QueueInspection>;
+    private track;
+    private finish;
 }

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

@@ -1,16 +1,34 @@
 import { runQueueJob } from '../wirings/queue/queue-runner.js';
+const FINISHED_JOBS_KEPT = 100;
 // knowledge: decisions/internals/the-dev-queue-copies-prod-timing-and-serialization-semantics.md
 export class InMemoryQueueService {
     supportsResults = false;
     jobCounter = 0;
+    jobs = new Map();
+    finishedTotals = new Map();
     async add(queueName, data, options) {
         const jobId = `inmem-${++this.jobCounter}`;
         const maxAttempts = Math.max(1, options?.attempts ?? 1);
         let attemptsMade = 0;
         const createdAt = new Date();
         const payload = data === undefined ? data : JSON.parse(JSON.stringify(data));
+        const record = {
+            jobId,
+            status: options?.delay ? 'delayed' : 'waiting',
+            attemptsMade: 0,
+            maxAttempts,
+            createdAt,
+            processedAt: null,
+            finishedAt: null,
+            durationMs: null,
+            error: null,
+        };
+        this.track(queueName, record);
         const runAttempt = async () => {
             attemptsMade++;
+            record.attemptsMade = attemptsMade;
+            record.status = 'active';
+            record.processedAt = new Date();
             const job = {
                 id: jobId,
                 queueName,
@@ -21,13 +39,17 @@ export class InMemoryQueueService {
             };
             try {
                 await runQueueJob({ job });
+                this.finish(queueName, record, 'completed', null);
             }
             catch (e) {
+                record.error = e?.message ?? String(e);
                 if (attemptsMade < maxAttempts) {
+                    record.status = 'delayed';
                     // Fire-and-forget retry: runAttempt catches every error itself.
                     setTimeout(() => void runAttempt(), this.backoffDelay(options?.backoff, attemptsMade));
                 }
                 else {
+                    this.finish(queueName, record, 'failed', record.error);
                     console.error(`[InMemoryQueue] Job ${jobId} on ${queueName} failed after ${attemptsMade} attempt(s):`, e.message);
                 }
             }
@@ -51,4 +73,49 @@ export class InMemoryQueueService {
     async getJob() {
         return null;
     }
+    async inspect(queueName, opts) {
+        const records = this.jobs.get(queueName) ?? [];
+        const totals = this.finishedTotals.get(queueName);
+        const counts = {
+            waiting: 0,
+            active: 0,
+            delayed: 0,
+            completed: totals?.completed ?? 0,
+            failed: totals?.failed ?? 0,
+        };
+        for (const record of records) {
+            if (record.status !== 'completed' && record.status !== 'failed') {
+                counts[record.status]++;
+            }
+        }
+        return {
+            counts,
+            recent: records
+                .slice(0, opts?.limit ?? 50)
+                .map((record) => ({ ...record })),
+        };
+    }
+    track(queueName, record) {
+        const records = this.jobs.get(queueName) ?? [];
+        records.unshift(record);
+        this.jobs.set(queueName, records);
+    }
+    finish(queueName, record, status, error) {
+        record.status = status;
+        record.error = error;
+        record.finishedAt = new Date();
+        record.durationMs =
+            record.finishedAt.getTime() -
+                (record.processedAt ?? record.createdAt).getTime();
+        const totals = this.finishedTotals.get(queueName) ?? {
+            completed: 0,
+            failed: 0,
+        };
+        totals[status]++;
+        this.finishedTotals.set(queueName, totals);
+        const records = this.jobs.get(queueName) ?? [];
+        let finished = 0;
+        this.jobs.set(queueName, records.filter((r) => (r.status !== 'completed' && r.status !== 'failed') ||
+            ++finished <= FINISHED_JOBS_KEPT));
+    }
 }

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

@@ -45,4 +45,6 @@ export declare class IncomingWebhookService {
         source?: string;
         limit?: number;
     }): Promise<IncomingWebhookReceiptRecord[]>;
+    /** Null when nothing is stored or no receipt has this id. */
+    getReceipt(_receiptId: string): Promise<IncomingWebhookReceiptRecord | null>;
 }

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

@@ -43,4 +43,8 @@ export class IncomingWebhookService {
     async listReceipts(_opts) {
         return [];
     }
+    /** Null when nothing is stored or no receipt has this id. */
+    async getReceipt(_receiptId) {
+        return null;
+    }
 }

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

@@ -1,4 +1,5 @@
 import type { CoreUserSession } from '../types/core.types.js';
+import type { ScheduledTaskRuns } from '../wirings/scheduler/scheduler.types.js';
 export interface ScheduledTaskSummary {
     taskId: string;
     rpcName: string;
@@ -17,6 +18,8 @@ export declare abstract class SchedulerService {
     abstract getTask(taskId: string): Promise<ScheduledTaskInfo | null>;
     abstract getAllTasks(): Promise<ScheduledTaskSummary[]>;
     abstract close(): Promise<void>;
+    /** Per wired cron task. Empty when this scheduler keeps no run history. */
+    getTaskRuns(): Promise<Record<string, ScheduledTaskRuns>>;
     start(): Promise<void>;
     stop(): Promise<void>;
 }

package/dist/services/scheduler-service.js

@@ -1,4 +1,8 @@
 export class SchedulerService {
+    /** Per wired cron task. Empty when this scheduler keeps no run history. */
+    async getTaskRuns() {
+        return {};
+    }
     async start() { }
     async stop() { }
 }

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

@@ -1,4 +1,4 @@
-export type { ConfigValidationResult, CoreQueueWorker, GroupConcurrencyConfig, JobGroup, JobOptions, PikkuJobConfig, PikkuWorkerConfig, PikkuQueue, QueueJob, QueueJobStatus, QueueService, QueueWorkers, QueueWorkersMeta, } from './queue.types.js';
+export type { ConfigValidationResult, CoreQueueWorker, GroupConcurrencyConfig, JobGroup, JobOptions, PikkuJobConfig, PikkuWorkerConfig, PikkuQueue, QueueInspection, QueueJob, QueueJobCounts, QueueJobRecord, QueueJobStatus, QueueService, QueueWorkers, QueueWorkersMeta, } from './queue.types.js';
 export { wireQueueWorker, runQueueJob, QueueJobDiscardedError, QueueJobFailedError, } from './queue-runner.js';
 export type { QueueIdentityBinding } from './queue-identity.js';
 export { SignedQueueService } from './signed-queue-service.js';

package/dist/wirings/queue/queue.types.d.ts

@@ -94,8 +94,29 @@ export interface JobOptions {
     /** Counts against the worker's {@link PikkuWorkerConfig.groupConcurrency}. */
     group?: JobGroup;
 }
+export type QueueJobCounts = Record<QueueJobStatus, number>;
+export type QueueJobRecord = {
+    jobId: string;
+    status: QueueJobStatus;
+    attemptsMade: number;
+    maxAttempts: number;
+    createdAt: Date;
+    processedAt: Date | null;
+    finishedAt: Date | null;
+    durationMs: number | null;
+    error: string | null;
+};
+export type QueueInspection = {
+    counts: QueueJobCounts;
+    /** Newest first. */
+    recent: QueueJobRecord[];
+};
 export interface QueueService {
     readonly supportsResults: boolean;
+    /** Live counts and recent jobs for one queue. Absent on a queue service that cannot inspect its backlog. */
+    inspect?(queueName: string, opts?: {
+        limit?: number;
+    }): Promise<QueueInspection>;
     add<T>(queueName: string, data: Safe<T>, options?: JobOptions): Promise<string>;
     getJob<T, R>(queueName: string, jobId: string): Promise<QueueJob<T, R> | null>;
 }

package/dist/wirings/queue/signed-queue-service.d.ts

@@ -1,7 +1,7 @@
 import type { Safe } from '../../classification/secret-value.js';
 import type { Logger } from '../../services/logger.js';
 import type { SecretService } from '../../services/secret-service.js';
-import type { JobOptions, QueueJob, QueueService } from './queue.types.js';
+import type { JobOptions, QueueInspection, QueueJob, QueueService } from './queue.types.js';
 /**
  * Wraps any {@link QueueService} so `JobOptions.pikkuUserId` leaves the process
  * as a signed claim that `runQueueJob` can verify.
@@ -14,4 +14,7 @@ export declare class SignedQueueService implements QueueService {
     get supportsResults(): boolean;
     add<T>(queueName: string, data: Safe<T>, options?: JobOptions): Promise<string>;
     getJob<T, R>(queueName: string, jobId: string): Promise<QueueJob<T, R> | null>;
+    get inspect(): ((queueName: string, opts?: {
+        limit?: number;
+    }) => Promise<QueueInspection>) | undefined;
 }

package/dist/wirings/queue/signed-queue-service.js

@@ -39,4 +39,7 @@ export class SignedQueueService {
     async getJob(queueName, jobId) {
         return this.queueService.getJob(queueName, jobId);
     }
+    get inspect() {
+        return this.queueService.inspect?.bind(this.queueService);
+    }
 }

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

@@ -1,3 +1,3 @@
 export { ScheduledTaskNotFoundError, runScheduledTask, wireScheduler, getScheduledTasks, } from './scheduler-runner.js';
 export { logSchedulers } from './log-schedulers.js';
-export type { CoreScheduledTask, ScheduledTasksMeta, } from './scheduler.types.js';
+export type { CoreScheduledTask, ScheduledTasksMeta, ScheduledTaskRun, ScheduledTaskRuns, } from './scheduler.types.js';

package/dist/wirings/scheduler/scheduler.types.d.ts

@@ -25,3 +25,15 @@ export interface PikkuScheduledTask {
     /** Never returns — throws to abort the run. */
     skip: (reason?: string) => void;
 }
+export interface ScheduledTaskRun {
+    startedAt: Date;
+    status: 'completed' | 'failed' | 'skipped';
+    durationMs: number;
+    error: string | null;
+}
+export interface ScheduledTaskRuns {
+    nextRun: Date | null;
+    lastRun: ScheduledTaskRun | null;
+    /** Newest first. */
+    history: ScheduledTaskRun[];
+}

package/knowledge/decisions/internals/a-latency-budget-is-asserted-by-its-cause.md

@@ -0,0 +1,32 @@
+---
+type: decision
+title: A latency budget is asserted by its cause, not by the clock
+description: The per-request key derivation and remote RPC round-trip tests count WebCrypto calls and check the algorithm instead of timing them, because a millisecond budget fails under CI load while the regression it guards is a choice of KDF
+tags: core, testing, crypto
+---
+
+# A latency budget is asserted by its cause, not by the clock
+
+Two tests guarded the per-request crypto path with wall-clock budgets:
+`encryptWithKeyMaterial` + `decryptWithKeyMaterial` under 5ms a pair, and a
+remote RPC round trip (`buildRemoteHeaders` → `pikkuRemoteAuthMiddleware`)
+under 20ms. Both went red on loaded CI runners (8.6ms, 151ms) with nothing
+wrong, blocking unrelated PRs (#2112), after #1175 had already loosened them.
+
+What the budgets protected is a single decision: the per-request path expands
+key material with HKDF, never with the PBKDF2 passphrase KDF `encryptJSON`
+uses (600k iterations, ~170ms). The remote session used to go through
+`encryptJSON`, which made every hop pay two password derivations.
+
+**So the tests spy on `crypto.subtle` with `t.mock.method` and assert the
+calls**: exactly one `importKey` and one `deriveKey` per encrypt and per
+decrypt, both named `HKDF`, and no `deriveBits`. Switching the KDF to PBKDF2,
+adding a second derivation, or routing the remote session back through
+`encryptJSON`/`decryptJSON` each fails them — checked by hand when they were
+written. None of that depends on how busy the machine is.
+
+**What this rules out:** a looser constant kept as a fallback, or a ratio
+against a measurement when the regression is a structural choice. A ratio
+([[a-wall-clock-threshold-is-a-load-test-in-disguise]]) is the right tool when
+the property really is "fewer of an expensive thing" and nothing countable is
+exposed; when the cause is observable, assert the cause.

package/knowledge/decisions/internals/a-wall-clock-threshold-is-a-load-test-in-disguise.md

@@ -44,3 +44,6 @@ and quiet rather than to delete it.
 
 Related: [[an-unref-d-timer-cannot-be-awaited-under-node-test]], the other
 source of nondeterminism found in the same pass.
+
+Where the cause is observable, prefer asserting it outright:
+[[a-latency-budget-is-asserted-by-its-cause]].

package/knowledge/decisions/internals/index.md

@@ -13,6 +13,7 @@ caller is entitled to assume.
 - [A credential name declared twice must agree on its schema and its type](a-credential-name-declared-twice-must-agree-on-schema-and-type.md) — validateAndBuildCredentialDefinitionsMeta throws when two declarations of one credential name differ in schema or in type, and otherwise keeps the first declaration
 - [declareScopes lets an app grant a scope whose addon it does not wire](a-grant-can-name-a-scope-declared-without-its-addon.md) — defineScope is a no-op read by the CLI, and declareScopes declares scope ids so a grant is valid without wiring the addon that owns the scope tree
 - [A held run is woken later, not retried](a-held-run-is-woken-later-not-retried.md) — An orchestrator message that finds its run held enqueues a fresh wake-up a second later instead of failing, because the queue's retry budget is for real failures and a long pass outlasts it
+- [A latency budget is asserted by its cause, not by the clock](a-latency-budget-is-asserted-by-its-cause.md) — The per-request key derivation and remote RPC round-trip tests count WebCrypto calls and check the algorithm instead of timing them, because a millisecond budget fails under CI load while the regression it guards is a choice of KDF
 - [A non-streaming agent run registers with agentRunState on the same terms as a streaming one](a-non-streaming-agent-run-registers-with-agentrunstate-too.md) — Otherwise interruptAgent finds the run, passes the ownership check, then cannot stop it — and reports that as if the run were on another host
 - [With scenarios.reset on, the dev seed is the fixture every assertion is written against](a-reset-suite-makes-the-dev-seed-the-fixture.md) — The rollback restores the database as the suite found it, so seed rows are the shared baseline — which makes an absolute date in the seed a test that expires
 - [A resumed turn is as interruptible as the first one](a-resumed-agent-turn-is-as-interruptible-as-the-first.md) — It is the same person listening to the same voice, and after an approval it is where most of the reply actually gets spoken

package/knowledge/questions/virtual-user-keys-on-cloud-stages-are-pikku-studios-to-build.md

@@ -16,9 +16,8 @@ following is built or confirmed. Pikku Studio Cloud must:
    base64), and accept that name, which starts with neither `PIKKU_` nor `PIKKUSTUDIO_`.
 3. Set `VIRTUAL_USER_API_URL` on every stage that runs virtual users, to the public
    URL including any HTTP prefix.
-4. Replace the operator sign-in route and `PIKKUSTUDIO_OPERATOR_TOKEN` handling: sign
-   statements with the stage's private key for callers acting on a stage, or hand the
-   key to the CLI as `VIRTUAL_USER_SIGNING_KEY` through the channel it already uses
+4. Sign statements with the stage's private key for callers acting on a stage, or hand
+   the key to the CLI as `VIRTUAL_USER_SIGNING_KEY` through the channel it already uses
    for stage credentials.
 5. Stop sending the operator token field in `runVirtualUser` requests; the field no longer
    exists.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.142",
+  "version": "0.12.143",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",