@pikku/core 0.12.142 → 0.12.144

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

@@ -8,18 +8,37 @@ class QueueWorkerNotFoundError extends PikkuError {
         super(`Queue processor not found: ${name}`);
     }
 }
+/** Thrown by `queue.fail()` inside a worker. Queue adapters treat it as a failed attempt, so the backend's retry policy applies. */
 export class QueueJobFailedError extends PikkuError {
     constructor(jobId, reason) {
         super(`Queue job ${jobId} failed${reason ? `: ${reason}` : ''}`);
         this.name = 'QueueJobFailedError';
     }
 }
+/** Thrown by `queue.discard()` inside a worker. Queue adapters treat it as the end of the job: it is not retried and is not reported as a failure. */
 export class QueueJobDiscardedError extends PikkuError {
     constructor(jobId, reason) {
         super(`Queue job ${jobId} discarded${reason ? `: ${reason}` : ''}`);
         this.name = 'QueueJobDiscardedError';
     }
 }
+/**
+ * Registers the function that processes jobs on a queue.
+ *
+ * The worker's function is sessionless: a job has no request to authenticate.
+ * The only identity it sees is `queue.pikkuUserId` on its wire, which is set
+ * only when the producer's identity claim verifies against the
+ * `PIKKU_QUEUE_IDENTITY_SECRET` secret, and is dropped otherwise.
+ *
+ * Registration needs the metadata `pikku` generates for the queue. When none is
+ * found the wiring is skipped with a warning rather than throwing. A queue
+ * adapter (BullMQ, pg-boss, SQS, …) picks up registered workers through
+ * {@link registerQueueWorkers}.
+ *
+ * @param queueWorker - The queue name, the function to run per job, and optional worker config and middleware.
+ *
+ * @example snippet: wireQueue
+ */
 export const wireQueueWorker = (queueWorker) => {
     const meta = pikkuState(null, 'queue', 'meta');
     const processorMeta = meta[queueWorker.name];
@@ -37,9 +56,11 @@ export const wireQueueWorker = (queueWorker) => {
     const registrations = pikkuState(null, 'queue', 'registrations');
     registrations.set(queueWorker.name, queueWorker);
 };
+/** Every registered queue worker, keyed by queue name. */
 export function getQueueWorkers() {
     return pikkuState(null, 'queue', 'registrations');
 }
+/** Unregisters the worker for `name`. Throws when no worker is registered under it. */
 export async function removeQueueWorker(name) {
     const registrations = pikkuState(null, 'queue', 'registrations');
     const registration = registrations.get(name);
@@ -48,6 +69,22 @@ export async function removeQueueWorker(name) {
     }
     registrations.delete(name);
 }
+/**
+ * Runs one job through the worker registered for its queue. Queue adapters call this for every job they receive.
+ *
+ * The job's `pikkuUserId` claim is verified before the function runs; an
+ * unsigned or invalid claim is logged and the job runs without one. The function
+ * runs with `auth: false`, the worker's middleware, and a `queue` wire carrying
+ * `updateProgress`, `fail` and `discard`.
+ *
+ * @param params.job - The job as the adapter received it.
+ * @param params.updateProgress - Reports progress to the backend; defaults to logging it.
+ * @param params.traceId - Defaults to `q-<jobId>`.
+ * @returns What the worker's function returned.
+ * @throws {PikkuMissingMetaError} When no metadata was generated for the queue.
+ * @throws {QueueJobFailedError | QueueJobDiscardedError} When the worker called `fail` or `discard`.
+ * @throws Whatever the worker threw, after logging it, so the adapter can apply its retry policy.
+ */
 export async function runQueueJob({ job, updateProgress, traceId, }) {
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();

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

@@ -2,6 +2,7 @@ import type { CommonWireMeta } from '../../types/core.types.js';
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 import type { QueueConfigMapping } from './validate-worker-config.js';
 import type { Safe } from '../../classification/secret-value.js';
+/** Worker settings a queue adapter maps onto its backend. Each adapter supports a subset, reported through its {@link QueueConfigMapping}; the rest are ignored with a warning. */
 export interface PikkuWorkerConfig {
     name?: string;
     /** Total worker concurrency. */
@@ -24,16 +25,19 @@ export interface PikkuWorkerConfig {
     /** Must not exceed {@link batchSize}. */
     groupConcurrency?: number | GroupConcurrencyConfig;
 }
+/** Per-group concurrency limits for a worker, with optional tiers that override the default. */
 export interface GroupConcurrencyConfig {
     /** Limit applied to any group without a matching tier. */
     default: number;
     /** Keyed by {@link JobGroup.tier}. */
     tiers?: Record<string, number>;
 }
+/** The group a job counts against for {@link PikkuWorkerConfig.groupConcurrency}, such as a tenant. */
 export interface JobGroup {
     id: string;
     tier?: string;
 }
+/** Per-job delivery settings: retries, backoff, dead-lettering, priority and timing. */
 export interface PikkuJobConfig {
     retryAttempts?: number;
     /** Milliseconds. */
@@ -50,6 +54,7 @@ export interface PikkuJobConfig {
     /** Milliseconds. */
     delay?: number;
 }
+/** What {@link validateWorkerConfig} did with a worker's config: the settings the adapter applied, those it ignored, and why. */
 export interface ConfigValidationResult {
     applied: Partial<PikkuWorkerConfig>;
     ignored: Partial<PikkuWorkerConfig>;
@@ -58,7 +63,9 @@ export interface ConfigValidationResult {
         [key: string]: any;
     };
 }
+/** The lifecycle state of a queue job. */
 export type QueueJobStatus = 'waiting' | 'active' | 'completed' | 'failed' | 'delayed';
+/** Bookkeeping a backend keeps about a job: progress, attempts and timestamps. */
 export type QueueJobMetadata = {
     progress?: number | string | object | undefined | boolean;
     attemptsMade?: number;
@@ -69,6 +76,12 @@ export type QueueJobMetadata = {
     error?: string;
     createdAt: Date;
 };
+/**
+ * A job as handed to {@link runQueueJob}, or returned by {@link QueueService.getJob}.
+ *
+ * `pikkuUserId` here is the producer's signed claim, not a verified id;
+ * {@link runQueueJob} verifies it before the worker sees it.
+ */
 export interface QueueJob<T = any, R = any> {
     id: string;
     queueName: string;
@@ -79,6 +92,14 @@ export interface QueueJob<T = any, R = any> {
     metadata?: () => Promise<QueueJobMetadata> | QueueJobMetadata;
     pikkuUserId?: string;
 }
+/**
+ * Options for {@link QueueService.add}.
+ *
+ * `pikkuUserId` names the user the job runs on behalf of. It only reaches the
+ * worker when the queue service is wrapped in `SignedQueueService`, which
+ * signs it with `PIKKU_QUEUE_IDENTITY_SECRET`; an unsigned value is dropped
+ * by {@link runQueueJob}.
+ */
 export interface JobOptions {
     priority?: number;
     delay?: number;
@@ -94,21 +115,55 @@ 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[];
+};
+/**
+ * The service functions use to enqueue jobs, available as `queueService` on singleton services.
+ *
+ * `add` resolves to the job id. `data` must be {@link Safe}: a payload with a
+ * `SecretValue` anywhere in it fails to compile, so a secret is not written to
+ * the queue by accident. `getJob` returns `null` on backends that do not keep jobs
+ * (`supportsResults` is then `false`).
+ *
+ * @example snippet: queuePublish
+ */
 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>;
 }
+/** A queue adapter's worker side: it registers every wired queue worker with its backend and reports how each worker's config was applied. */
 export interface QueueWorkers {
     name: string;
     supportsResults: boolean;
     configMappings: QueueConfigMapping;
     registerQueues(): Promise<Record<string, ConfigValidationResult[]>>;
 }
+/** Generated metadata for every wired queue worker, keyed by queue name. */
 export type QueueWorkersMeta = Record<string, CommonWireMeta & {
     name: string;
     config?: PikkuWorkerConfig;
 }>;
+/** The configuration {@link wireQueueWorker} takes. An app's generated `wireQueueWorker` narrows the function type to its own services. */
 export type CoreQueueWorker<PikkuFunctionConfig extends CorePikkuFunctionConfig<any, any, any> = CorePikkuFunctionConfig<any, any, any>> = {
     /** The queue this worker consumes. Whoever enqueues a job names the same string, so it is the contract between producer and consumer. */
     name: string;
@@ -123,6 +178,7 @@ export type CoreQueueWorker<PikkuFunctionConfig extends CorePikkuFunctionConfig<
     /** Wraps every job. There is no request to read from, so this is for tracing, locking and teardown rather than auth. */
     middleware?: PikkuFunctionConfig['middleware'];
 };
+/** The `queue` part of a worker function's wire: which job is running, the verified `pikkuUserId` of whoever enqueued it (if any), and controls to report progress, fail or discard it. */
 export interface PikkuQueue {
     queueName: string;
     jobId: string;

package/dist/wirings/queue/register-queue-helper.d.ts

@@ -1,5 +1,17 @@
 import type { ConfigValidationResult, CoreQueueWorker } from './queue.types.js';
 import type { QueueConfigMapping } from './validate-worker-config.js';
 import type { Logger } from '../../services/logger.js';
+/** Called by {@link registerQueueWorkers} once per wired worker, to attach it to the adapter's backend. */
 export type QueueRegistrationCallback<T = any> = (queueName: string, processor: CoreQueueWorker) => Promise<T>;
+/**
+ * Validates every wired queue worker's config against an adapter's mapping and registers each one through `registerCallback`.
+ *
+ * A worker whose registration throws is logged and skipped, so one bad worker
+ * does not stop the rest.
+ *
+ * @param configMappings - Which {@link PikkuWorkerConfig} keys the adapter supports and how they map.
+ * @param logger - Receives registration progress, config warnings and failures.
+ * @param registerCallback - Attaches one worker to the backend.
+ * @returns The config validation result for each queue.
+ */
 export declare function registerQueueWorkers<T = any>(configMappings: QueueConfigMapping, logger: Logger, registerCallback: QueueRegistrationCallback<T>): Promise<Record<string, ConfigValidationResult[]>>;

package/dist/wirings/queue/register-queue-helper.js

@@ -1,5 +1,16 @@
 import { getQueueWorkers } from './queue-runner.js';
 import { validateWorkerConfig } from './validate-worker-config.js';
+/**
+ * Validates every wired queue worker's config against an adapter's mapping and registers each one through `registerCallback`.
+ *
+ * A worker whose registration throws is logged and skipped, so one bad worker
+ * does not stop the rest.
+ *
+ * @param configMappings - Which {@link PikkuWorkerConfig} keys the adapter supports and how they map.
+ * @param logger - Receives registration progress, config warnings and failures.
+ * @param registerCallback - Attaches one worker to the backend.
+ * @returns The config validation result for each queue.
+ */
 export async function registerQueueWorkers(configMappings, logger, registerCallback) {
     const configValidation = {};
     const queueWorkers = getQueueWorkers();

package/dist/wirings/queue/remote-queue-job.d.ts

@@ -0,0 +1,11 @@
+import type { Logger } from '../../services/logger.js';
+import type { RemoteQueueJobData } from '../../services/remote-jobs.js';
+/**
+ * A dispatched job is delivered, not owned: the sender retries, so a permanent
+ * failure has to read differently from a transient one. An unknown worker or a
+ * discarded job answers 4xx so the sender stops; anything else propagates and
+ * is delivered again.
+ */
+export declare function pikkuRemoteQueueJobFunc({ logger }: {
+    logger: Logger;
+}, { queueName, data, jobId, traceId }: RemoteQueueJobData): Promise<void>;

package/dist/wirings/queue/remote-queue-job.js

@@ -0,0 +1,41 @@
+import { BadRequestError, PikkuMissingMetaError } from '../../errors/errors.js';
+import { QueueJobDiscardedError, runQueueJob } from './queue-runner.js';
+/**
+ * A dispatched job is delivered, not owned: the sender retries, so a permanent
+ * failure has to read differently from a transient one. An unknown worker or a
+ * discarded job answers 4xx so the sender stops; anything else propagates and
+ * is delivered again.
+ */
+export async function pikkuRemoteQueueJobFunc({ logger }, { queueName, data, jobId, traceId }) {
+    const job = {
+        queueName,
+        data,
+        id: jobId ?? traceId ?? `remote-${Date.now()}`,
+        status: async () => 'active',
+        metadata: () => ({
+            processedAt: new Date(),
+            attemptsMade: 0,
+            maxAttempts: undefined,
+            result: undefined,
+            progress: 0,
+            createdAt: new Date(),
+            completedAt: undefined,
+            failedAt: undefined,
+            error: undefined,
+        }),
+        waitForCompletion: async () => {
+            throw new Error('remote jobs do not support waitForCompletion');
+        },
+    };
+    try {
+        await runQueueJob({ job, traceId });
+    }
+    catch (error) {
+        if (error instanceof PikkuMissingMetaError ||
+            error instanceof QueueJobDiscardedError) {
+            throw new BadRequestError(error.message);
+        }
+        logger.error(`remote-jobs: queue '${queueName}' failed: ${error instanceof Error ? error.message : String(error)}`);
+        throw error;
+    }
+}

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/queue/validate-worker-config.d.ts

@@ -1,4 +1,5 @@
 import type { PikkuWorkerConfig, ConfigValidationResult } from './queue.types.js';
+/** How a queue adapter supports {@link PikkuWorkerConfig}: the keys it maps (and to what), the keys it cannot honour, and the fallbacks it uses instead. */
 export interface QueueConfigMapping {
     supported: Partial<Record<keyof PikkuWorkerConfig, {
         queueProperty?: string;

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

@@ -25,6 +25,7 @@ export type CoreSystemRole = {
  * scope id is a role nobody reads correctly.
  */
 export type CoreSystemRoles = Record<string, CoreSystemRole>;
+/** A system role declaration as recorded in generated meta. */
 export type SystemRoleDefinitionMeta = {
     name: string;
     displayName?: string;
@@ -32,7 +33,9 @@ export type SystemRoleDefinitionMeta = {
     scopes: string[];
     sourceFile?: string;
 };
+/** System role declarations as the inspector found them. */
 export type SystemRoleDefinitions = SystemRoleDefinitionMeta[];
+/** System role declarations collected by the CLI, keyed by name. */
 export type SystemRoleDefinitionsMeta = Record<string, SystemRoleDefinitionMeta>;
 /** A declared system role, ready to sync into a scope store. */
 export type SystemRole = {

package/dist/wirings/rpc/rpc-runner.d.ts

@@ -3,13 +3,21 @@ import type { SessionService } from '../../services/user-session-service.js';
 import type { CoreUserSession } from '../../types/core.types.js';
 import { PikkuError } from '../../errors/error-handler.js';
 import type { PikkuRPC, ResolvedFunction } from './rpc-types.js';
+/**
+ * Thrown when an RPC name resolves to no function, or to one that `rpc.exposed` may not call. Maps to HTTP 404 and MCP `-32601`.
+ *
+ * An unexposed function is reported as not found rather than forbidden, so the
+ * response does not reveal whether an internal function by that name exists.
+ */
 export declare class RPCNotFoundError extends PikkuError {
     readonly rpcName: string;
     constructor(rpcName: string);
 }
+/** Thrown when a remote addon's configuration cannot be used, for example when its `serverUrl` resolves empty. Maps to HTTP 500. */
 export declare class RemoteAddonConfigError extends PikkuError {
     constructor(namespace: string, detail: string);
 }
+/** Thrown when a remote addon answers an RPC with a non-2xx status. Maps to HTTP 502; the upstream status is kept on `httpStatus` and the first 300 characters of its body in the message. */
 export declare class RemoteAddonRequestError extends PikkuError {
     readonly httpStatus: number;
     constructor(namespace: string, fnName: string, status: number, detail: string);
@@ -66,12 +74,28 @@ export declare class ContextAwareRPCService {
     get agent(): PikkuRPC['agent'];
     remote<In = any, Out = any>(funcName: string, data: In): Promise<Out>;
 }
+/**
+ * Builds the `rpc` object handed to every function on its wire.
+ *
+ * `rpc.invoke(name, data)` calls another function in-process, or through the
+ * `DeploymentService` when the function lives in another deployment unit.
+ * `rpc.exposed` does the same but only reaches functions marked `expose: true`
+ * (and, for addons, those the consuming app exposes), which is what the public
+ * RPC endpoint uses. `rpc.remote` always goes through the `DeploymentService`.
+ * Calls carry the caller's wire, so the session and trace ID propagate. An addon
+ * can only call the addons it lists in `uses`.
+ *
+ * Runtimes create this through {@link rpcService}; apps reach it as `rpc` on the wire.
+ *
+ * @example snippet: rpcInternalCall
+ */
 export declare class PikkuRPCService<Services extends CoreServices, TypedRPC = PikkuRPC> {
     getContextRPCService(services: Services, wire: PikkuRawWire, requiresAuthOrOptions?: boolean | {
         requiresAuth?: boolean;
         sessionService?: SessionService<CoreUserSession>;
     } | undefined, depth?: number, packageName?: string | null): TypedRPC;
 }
+/** The shared {@link PikkuRPCService}. Function runners call `getContextRPCService` on it to give each invocation its own `rpc`. */
 export declare const rpcService: PikkuRPCService<import("../../types/core.types.js").CoreSingletonServices<{
     logLevel?: import("../../services/logger.js").LogLevel;
     secrets?: {

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

@@ -1,17 +1,34 @@
 import { addonCallerOf, addonMayReach } from '../addon/addon-reach.js';
-import { forwardStepName, isCompensationStepName, } from '../../function/compensation-name.js';
-import { runPikkuFunc } from '../../function/function-runner.js';
+import { forwardStepName, isCompensationStepName, } from '../../compensation-name.js';
 import { addonInstanceForNamespace } from '../addon/addon-runner.js';
 import { isAddonFunctionExposed } from '../addon/wire-addon.js';
 import { pikkuState } from '../../pikku-state.js';
 import { PikkuError, addError } from '../../errors/error-handler.js';
 import { parseVersionedId } from '../../version.js';
 import { resolveRemoteAddonToken } from '../addon/remote-addon-auth.js';
+/**
+ * The function runner, reached lazily. `function-runner` builds every
+ * invocation's `wire.rpc` from this module, so a static import back would be a
+ * module cycle. By the time an rpc call runs the runner is loaded, and the
+ * import resolves from the module cache once.
+ */
+let functionRunner;
+const runPikkuFunc = async (...args) => {
+    functionRunner ??= (await import('../../function/function-runner.js'))
+        .runPikkuFunc;
+    return functionRunner(...args);
+};
 /**
  * The session for a wire: read through `getSession` when a runner attached one,
  * otherwise whatever was placed on the wire directly.
  */
 const resolveWireSession = async (wire) => typeof wire.getSession === 'function' ? await wire.getSession() : wire.session;
+/**
+ * Thrown when an RPC name resolves to no function, or to one that `rpc.exposed` may not call. Maps to HTTP 404 and MCP `-32601`.
+ *
+ * An unexposed function is reported as not found rather than forbidden, so the
+ * response does not reveal whether an internal function by that name exists.
+ */
 export class RPCNotFoundError extends PikkuError {
     rpcName;
     constructor(rpcName) {
@@ -24,6 +41,7 @@ addError(RPCNotFoundError, {
     mcpCode: -32601,
     message: 'RPC function not found.',
 });
+/** Thrown when a remote addon's configuration cannot be used, for example when its `serverUrl` resolves empty. Maps to HTTP 500. */
 export class RemoteAddonConfigError extends PikkuError {
     constructor(namespace, detail) {
         super(`Remote addon '${namespace}' is misconfigured: ${detail}`);
@@ -33,6 +51,7 @@ addError(RemoteAddonConfigError, {
     status: 500,
     message: 'Remote addon is misconfigured.',
 });
+/** Thrown when a remote addon answers an RPC with a non-2xx status. Maps to HTTP 502; the upstream status is kept on `httpStatus` and the first 300 characters of its body in the message. */
 export class RemoteAddonRequestError extends PikkuError {
     httpStatus;
     constructor(namespace, fnName, status, detail) {
@@ -411,6 +430,21 @@ export class ContextAwareRPCService {
         return this.services.deploymentService.invoke(funcName, data, session, this.wire.traceId);
     }
 }
+/**
+ * Builds the `rpc` object handed to every function on its wire.
+ *
+ * `rpc.invoke(name, data)` calls another function in-process, or through the
+ * `DeploymentService` when the function lives in another deployment unit.
+ * `rpc.exposed` does the same but only reaches functions marked `expose: true`
+ * (and, for addons, those the consuming app exposes), which is what the public
+ * RPC endpoint uses. `rpc.remote` always goes through the `DeploymentService`.
+ * Calls carry the caller's wire, so the session and trace ID propagate. An addon
+ * can only call the addons it lists in `uses`.
+ *
+ * Runtimes create this through {@link rpcService}; apps reach it as `rpc` on the wire.
+ *
+ * @example snippet: rpcInternalCall
+ */
 export class PikkuRPCService {
     getContextRPCService(services, wire, requiresAuthOrOptions, depth = 0, packageName = null) {
         const options = typeof requiresAuthOrOptions === 'object' &&
@@ -456,4 +490,5 @@ class ContextRPCView {
         return this.serviceRPC.agent;
     }
 }
+/** The shared {@link PikkuRPCService}. Function runners call `getContextRPCService` on it to give each invocation its own `rpc`. */
 export const rpcService = new PikkuRPCService();

package/dist/wirings/rpc/rpc-types.d.ts

@@ -1,6 +1,7 @@
 import type { CredentialOverrides } from '../credential/credential-overrides.js';
 import type { PikkuRawWire } from '../../types/core.types.js';
 import type { AgentInterruptResult } from '../agent/agent-interrupt.js';
+/** The `rpc` object on a function's wire. An app's generated types narrow `invoke`, `remote`, `startWorkflow` and `agent` to its own functions, workflows and agents; see {@link PikkuRPCService} for how each call is routed. */
 export type PikkuRPC<Invoke extends (...args: any[]) => any = (...args: any[]) => any, Remote extends (...args: any[]) => any = (...args: any[]) => any, startWorkflow extends (...args: any[]) => any = (...args: any[]) => any, AgentRun extends (...args: any[]) => any = (...args: any[]) => any, AgentStream extends (...args: any[]) => any = (...args: any[]) => any> = {
     depth: number;
     global: boolean;
@@ -29,6 +30,7 @@ export type PikkuRPC<Invoke extends (...args: any[]) => any = (...args: any[]) =
         interrupt: (runId: string, reason?: 'speech' | 'user' | 'timeout') => Promise<AgentInterruptResult>;
     };
 };
+/** Generated metadata for one RPC name: the function it resolves to, whether `rpc.exposed` may call it, and whether it is reachable remotely. */
 export type RPCMeta = {
     pikkuFuncId: string;
     expose: boolean;

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

@@ -1,3 +1,4 @@
 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';
+export { pikkuRemoteScheduledJobFunc } from './remote-scheduled-job.js';

package/dist/wirings/scheduler/index.js

@@ -1,2 +1,3 @@
 export { ScheduledTaskNotFoundError, runScheduledTask, wireScheduler, getScheduledTasks, } from './scheduler-runner.js';
 export { logSchedulers } from './log-schedulers.js';
+export { pikkuRemoteScheduledJobFunc } from './remote-scheduled-job.js';

package/dist/wirings/scheduler/log-schedulers.d.ts

@@ -1,2 +1,3 @@
 import type { Logger } from '../../services/index.js';
+/** Logs every wired scheduled task and its schedule at info level, typically once at startup. */
 export declare const logSchedulers: (logger: Logger) => void;

package/dist/wirings/scheduler/log-schedulers.js

@@ -1,4 +1,5 @@
 import { pikkuState } from '../../pikku-state.js';
+/** Logs every wired scheduled task and its schedule at info level, typically once at startup. */
 export const logSchedulers = (logger) => {
     const scheduledTasks = pikkuState(null, 'scheduler', 'tasks');
     if (scheduledTasks.size === 0) {

package/dist/wirings/scheduler/remote-scheduled-job.d.ts

@@ -0,0 +1,11 @@
+import type { Logger } from '../../services/logger.js';
+import type { RemoteScheduledJobData } from '../../services/remote-jobs.js';
+/**
+ * Runs a scheduled task on behalf of a remote job runner, so a task can be triggered in a deployment unit other than the one that scheduled it.
+ * Generated remote-job wiring calls this; apps do not call it directly.
+ *
+ * @throws {BadRequestError} When the named task is not wired in this unit.
+ */
+export declare function pikkuRemoteScheduledJobFunc({ logger }: {
+    logger: Logger;
+}, { taskName }: RemoteScheduledJobData): Promise<void>;

package/dist/wirings/scheduler/remote-scheduled-job.js

@@ -0,0 +1,20 @@
+import { BadRequestError } from '../../errors/errors.js';
+import { ScheduledTaskNotFoundError, runScheduledTask, } from './scheduler-runner.js';
+/**
+ * Runs a scheduled task on behalf of a remote job runner, so a task can be triggered in a deployment unit other than the one that scheduled it.
+ * Generated remote-job wiring calls this; apps do not call it directly.
+ *
+ * @throws {BadRequestError} When the named task is not wired in this unit.
+ */
+export async function pikkuRemoteScheduledJobFunc({ logger }, { taskName }) {
+    try {
+        await runScheduledTask({ name: taskName, traceId: `cron-${taskName}` });
+    }
+    catch (error) {
+        if (error instanceof ScheduledTaskNotFoundError) {
+            throw new BadRequestError(error.message);
+        }
+        logger.error(`remote-jobs: task '${taskName}' failed: ${error instanceof Error ? error.message : String(error)}`);
+        throw error;
+    }
+}

package/dist/wirings/scheduler/scheduler-runner.d.ts

@@ -2,14 +2,43 @@ import type { CoreUserSession } from '../../types/core.types.js';
 import type { CoreScheduledTask } from './scheduler.types.js';
 import { PikkuError } from '../../errors/error-handler.js';
 import type { CorePikkuFunctionConfig, CorePikkuFunctionSessionless } from '../../function/functions.types.js';
+/** Parameters for {@link runScheduledTask}: the task's name, an optional session to run it with, and an optional trace ID. */
 export type RunScheduledTasksParams = {
     name: string;
     session?: CoreUserSession;
     traceId?: string;
 };
+/**
+ * Registers a sessionless function to run on a cron schedule.
+ *
+ * The task only runs once a scheduler service (or a platform cron trigger
+ * calling {@link runScheduledTask}) drives it; wiring alone schedules nothing.
+ * The function receives no input, and can call `scheduledTask.skip()` on its
+ * wire to end the run early.
+ *
+ * Registration needs the metadata `pikku` generates for the task. When none is
+ * found the wiring is skipped with a warning rather than throwing.
+ *
+ * @param scheduledTask - The task's unique name, cron `schedule`, function, and optional middleware.
+ * @throws {Error} When a task with the same name is already wired.
+ *
+ * @example snippet: wireScheduler
+ */
 export declare const wireScheduler: <PikkuFunctionConfig extends CorePikkuFunctionConfig<CorePikkuFunctionSessionless<void, void>>>(scheduledTask: CoreScheduledTask<PikkuFunctionConfig>) => void;
+/** Thrown by {@link runScheduledTask} when no task, or no generated metadata, exists for the requested name. */
 export declare class ScheduledTaskNotFoundError extends PikkuError {
     constructor(title: string);
 }
+/**
+ * Runs one wired scheduled task now. Scheduler services and platform cron handlers call this on each tick.
+ *
+ * When `session` is given it is placed on the wire, so the function and its
+ * middleware see that user; otherwise the task runs without one.
+ *
+ * @param params - See {@link RunScheduledTasksParams}. `traceId` defaults to `cron-<name>-<timestamp>`.
+ * @throws {ScheduledTaskNotFoundError} When the task or its metadata is missing.
+ * @throws The error the function threw, including the one `scheduledTask.skip()` raises, so the caller can tell a skip from a failure.
+ */
 export declare function runScheduledTask({ name, session, traceId, }: RunScheduledTasksParams): Promise<void>;
+/** Every wired scheduled task, keyed by name. Scheduler services read this to know what to schedule. */
 export declare const getScheduledTasks: () => Map<string, CoreScheduledTask>;