@pikku/core 0.12.150 → 0.12.151

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

@@ -5,6 +5,7 @@ import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
 import { resolveNamespace } from '../rpc/rpc-runner.js';
 import { BadRequestError, NotFoundError } from '../../errors/errors.js';
 import { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../services/user-session-service.js';
+import { traceWire, tracedLogger } from '../../trace.js';
 /**
  * A JSON-RPC error raised by `runMCPTool`, `runMCPResource` and `runMCPPrompt`; `error` is the
  * response body to send back to the MCP client.
@@ -154,6 +155,10 @@ async function runMCPPikkuFunc(request, type, name, mcp, pikkuFuncId, { mcp: mcp
 metaKey = name) {
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();
+    // Here rather than left to the function runner: a call refused before it
+    // gets there still has to be found in the logs.
+    const trace = traceWire();
+    const logger = tracedLogger(singletonServices.logger, trace.traceId);
     try {
         if (request.jsonrpc !== '2.0') {
             throw new BadRequestError('Invalid JSON-RPC version, only supoorted version is 2.0');
@@ -167,6 +172,7 @@ metaKey = name) {
         singletonServices.logger.debug(`Running MCP ${type}: ${name}`);
         const mcpSessionService = new PikkuSessionService(singletonServices.sessionStore);
         const wire = {
+            ...trace,
             mcp: mcpWire,
             // Only when the transport supplied one. Setting `http: undefined`
             // explicitly would be the same to a reader and different to a spread.
@@ -212,27 +218,31 @@ metaKey = name) {
         };
     }
     catch (e) {
-        singletonServices.logger.error(`Error running MCP ${type} '${name}':`, e.constructor);
+        logger.error(`Error running MCP ${type} '${name}':`, e.constructor);
         const errorResponse = getErrorResponse(e);
         if (errorResponse?.mcpCode) {
             throw new MCPError({
                 id: request.id,
                 code: errorResponse.mcpCode,
                 message: errorResponse.message,
+                data: { errorId: trace.traceId },
             });
         }
         else {
             if (errorResponse) {
-                singletonServices.logger.warn(`Got error without a mapping: ${errorResponse.message}`);
+                logger.warn(`Got error without a mapping: ${errorResponse.message}`);
             }
             throw new MCPError({
                 id: request.id,
                 code: -32603,
                 message: 'Internal error',
                 // knowledge: decisions/security/mcp-internal-error-details-are-double-gated-on-production.md
-                data: exposeErrors && !isProduction() && e instanceof Error
-                    ? { message: e.message, stack: e.stack }
-                    : undefined,
+                data: {
+                    errorId: trace.traceId,
+                    ...(exposeErrors && !isProduction() && e instanceof Error
+                        ? { message: e.message, stack: e.stack }
+                        : {}),
+                },
             });
         }
     }

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

@@ -4,7 +4,7 @@ import type { QueueService, JobOptions, QueueInspection } from './queue.types.js
  *
  * Jobs run after a short delay, payloads are JSON round-tripped as a real
  * backend would, and failed jobs are retried up to `attempts` with the given
- * backoff. Nothing is persisted, `getJob` always returns `null`, and jobs still
+ * backoff. A job its worker discarded is not retried. Nothing is persisted, `getJob` always returns `null`, and jobs still
  * pending when the process exits are lost.
  */
 export declare class InMemoryQueueService implements QueueService {

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

@@ -1,4 +1,4 @@
-import { runQueueJob } from './queue-runner.js';
+import { QueueJobDiscardedError, runQueueJob } from './queue-runner.js';
 const FINISHED_JOBS_KEPT = 100;
 // knowledge: decisions/internals/the-dev-queue-copies-prod-timing-and-serialization-semantics.md
 /**
@@ -6,7 +6,7 @@ const FINISHED_JOBS_KEPT = 100;
  *
  * Jobs run after a short delay, payloads are JSON round-tripped as a real
  * backend would, and failed jobs are retried up to `attempts` with the given
- * backoff. Nothing is persisted, `getJob` always returns `null`, and jobs still
+ * backoff. A job its worker discarded is not retried. Nothing is persisted, `getJob` always returns `null`, and jobs still
  * pending when the process exits are lost.
  */
 export class InMemoryQueueService {
@@ -44,12 +44,18 @@ export class InMemoryQueueService {
                 status: () => 'active',
                 metadata: () => ({ attemptsMade, maxAttempts, createdAt }),
                 pikkuUserId: options?.pikkuUserId,
+                traceparent: options?.traceparent,
             };
             try {
                 await runQueueJob({ job });
                 this.finish(queueName, record, 'completed', null);
             }
             catch (e) {
+                // As on a real backend, a discard ends the job and is not a failure.
+                if (e instanceof QueueJobDiscardedError) {
+                    this.finish(queueName, record, 'completed', null);
+                    return;
+                }
                 record.error = e?.message ?? String(e);
                 if (attemptsMade < maxAttempts) {
                     record.status = 'delayed';

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

@@ -2,6 +2,7 @@ export type { ConfigValidationResult, CoreQueueWorker, GroupConcurrencyConfig, J
 export { wireQueueWorker, runQueueJob, QueueJobDiscardedError, QueueJobFailedError, } from './queue-runner.js';
 export type { QueueIdentityBinding } from './queue-identity.js';
 export { SignedQueueService } from './signed-queue-service.js';
+export { unwrapJobTrace, wrapJobTrace } from './queue-trace.js';
 export type { QueueConfigMapping } from './validate-worker-config.js';
 export { registerQueueWorkers } from './register-queue-helper.js';
 export type { QueueRegistrationCallback } from './register-queue-helper.js';

package/dist/wirings/queue/index.js

@@ -1,4 +1,5 @@
 export { wireQueueWorker, runQueueJob, QueueJobDiscardedError, QueueJobFailedError, } from './queue-runner.js';
 export { SignedQueueService } from './signed-queue-service.js';
+export { unwrapJobTrace, wrapJobTrace } from './queue-trace.js';
 export { registerQueueWorkers } from './register-queue-helper.js';
 export { pikkuRemoteQueueJobFunc } from './remote-queue-job.js';

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

@@ -37,18 +37,17 @@ export declare function removeQueueWorker(name: string): Promise<void>;
  * 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`.
+ * `updateProgress`, `fail` and `discard`. It continues the job's `traceparent`,
+ * or starts a new trace when the job has no valid one.
  *
  * @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 declare function runQueueJob({ job, updateProgress, traceId, }: {
+export declare function runQueueJob({ job, updateProgress, }: {
     job: QueueJob;
     updateProgress?: (progress: number | string | object) => Promise<void>;
-    traceId?: string;
 }): Promise<void>;

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

@@ -3,6 +3,7 @@ import { PikkuMissingMetaError } from '../../errors/errors.js';
 import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../pikku-state.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
 import { resolveQueueJobIdentity } from './queue-identity.js';
+import { continueTrace } from '../../trace.js';
 class QueueWorkerNotFoundError extends PikkuError {
     constructor(name) {
         super(`Queue processor not found: ${name}`);
@@ -75,22 +76,21 @@ export async function removeQueueWorker(name) {
  * 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`.
+ * `updateProgress`, `fail` and `discard`. It continues the job's `traceparent`,
+ * or starts a new trace when the job has no valid one.
  *
  * @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, }) {
+export async function runQueueJob({ job, updateProgress, }) {
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();
-    const resolvedTraceId = traceId ?? `q-${job.id}`;
-    const logger = singletonServices.logger.scope?.(resolvedTraceId) ??
-        singletonServices.logger;
+    const trace = continueTrace(job.traceparent);
+    const logger = singletonServices.logger.scope?.(trace.traceId) ?? singletonServices.logger;
     const meta = pikkuState(null, 'queue', 'meta');
     const processorMeta = meta[job.queueName];
     if (!processorMeta) {
@@ -126,7 +126,8 @@ export async function runQueueJob({ job, updateProgress, traceId, }) {
     try {
         logger.info(`Processing job ${job.id} in queue ${job.queueName}`);
         const wire = {
-            traceId: resolvedTraceId,
+            traceId: trace.traceId,
+            trace,
             queue,
         };
         const result = await runPikkuFunc('queue', job.queueName, processorMeta.pikkuFuncId, {

package/dist/wirings/queue/queue-trace.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Puts a job's `traceparent` and signed identity claim next to its payload, for
+ * queues with no per-message metadata that survives a retry. Applied by the
+ * adapter, below `SignedQueueService`, so the signature still covers `data`.
+ * A job with neither is sent as it is, unless its data looks like an envelope,
+ * or a worker would unwrap it.
+ */
+export declare const wrapJobTrace: (data: unknown, traceparent?: string, pikkuUserId?: string) => any;
+/**
+ * Undoes {@link wrapJobTrace}. A payload without the envelope is the job's data
+ * as enqueued. `pikkuUserId` is the unverified claim: only `runQueueJob` may
+ * turn it into an identity.
+ */
+export declare const unwrapJobTrace: (payload: any) => {
+    data: any;
+    traceparent?: string;
+    pikkuUserId?: string;
+};

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

@@ -0,0 +1,42 @@
+const TRACEPARENT_KEY = '__pikkuTraceparent';
+const IDENTITY_KEY = '__pikkuUserId';
+const ENVELOPE_KEYS = new Set([TRACEPARENT_KEY, IDENTITY_KEY, 'data']);
+const isOptionalString = (value) => value === undefined || typeof value === 'string';
+const isEnvelope = (payload) => typeof payload === 'object' &&
+    payload !== null &&
+    (payload[TRACEPARENT_KEY] !== undefined ||
+        payload[IDENTITY_KEY] !== undefined) &&
+    isOptionalString(payload[TRACEPARENT_KEY]) &&
+    isOptionalString(payload[IDENTITY_KEY]) &&
+    Object.keys(payload).every((key) => ENVELOPE_KEYS.has(key));
+/**
+ * Puts a job's `traceparent` and signed identity claim next to its payload, for
+ * queues with no per-message metadata that survives a retry. Applied by the
+ * adapter, below `SignedQueueService`, so the signature still covers `data`.
+ * A job with neither is sent as it is, unless its data looks like an envelope,
+ * or a worker would unwrap it.
+ */
+// knowledge: decisions/internals/bullmq-and-pg-boss-carry-traceparent-in-a-payload-envelope.md
+export const wrapJobTrace = (data, traceparent, pikkuUserId) => traceparent || pikkuUserId || isEnvelope(data)
+    ? {
+        [TRACEPARENT_KEY]: traceparent ?? '',
+        ...(pikkuUserId ? { [IDENTITY_KEY]: pikkuUserId } : {}),
+        data,
+    }
+    : data;
+/**
+ * Undoes {@link wrapJobTrace}. A payload without the envelope is the job's data
+ * as enqueued. `pikkuUserId` is the unverified claim: only `runQueueJob` may
+ * turn it into an identity.
+ */
+export const unwrapJobTrace = (payload) => {
+    if (!isEnvelope(payload))
+        return { data: payload };
+    const traceparent = payload[TRACEPARENT_KEY];
+    const pikkuUserId = payload[IDENTITY_KEY];
+    return {
+        data: payload.data,
+        ...(traceparent ? { traceparent } : {}),
+        ...(pikkuUserId !== undefined ? { pikkuUserId } : {}),
+    };
+};

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

@@ -91,6 +91,8 @@ export interface QueueJob<T = any, R = any> {
     waitForCompletion?: (ttl?: number) => Promise<R>;
     metadata?: () => Promise<QueueJobMetadata> | QueueJobMetadata;
     pikkuUserId?: string;
+    /** The W3C trace the producer was in, when the adapter carried one. */
+    traceparent?: string;
 }
 /**
  * Options for {@link QueueService.add}.
@@ -114,6 +116,11 @@ export interface JobOptions {
     pikkuUserId?: string;
     /** Counts against the worker's {@link PikkuWorkerConfig.groupConcurrency}. */
     group?: JobGroup;
+    /**
+     * The W3C trace the job continues. Stamped from the calling function's wire
+     * when left unset, so set it only to move the job onto another trace.
+     */
+    traceparent?: string;
 }
 export type QueueJobCounts = Record<QueueJobStatus, number>;
 export type QueueJobRecord = {

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

@@ -8,4 +8,4 @@ import type { RemoteQueueJobData } from '../../services/remote-jobs.js';
  */
 export declare function pikkuRemoteQueueJobFunc({ logger }: {
     logger: Logger;
-}, { queueName, data, jobId, traceId }: RemoteQueueJobData): Promise<void>;
+}, { queueName, data, jobId, traceparent, pikkuUserId }: RemoteQueueJobData): Promise<void>;

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

@@ -6,11 +6,13 @@ import { QueueJobDiscardedError, runQueueJob } from './queue-runner.js';
  * discarded job answers 4xx so the sender stops; anything else propagates and
  * is delivered again.
  */
-export async function pikkuRemoteQueueJobFunc({ logger }, { queueName, data, jobId, traceId }) {
+export async function pikkuRemoteQueueJobFunc({ logger }, { queueName, data, jobId, traceparent, pikkuUserId }) {
     const job = {
         queueName,
         data,
-        id: jobId ?? traceId ?? `remote-${Date.now()}`,
+        id: jobId ?? `remote-${globalThis.crypto.randomUUID()}`,
+        traceparent,
+        pikkuUserId,
         status: async () => 'active',
         metadata: () => ({
             processedAt: new Date(),
@@ -28,7 +30,7 @@ export async function pikkuRemoteQueueJobFunc({ logger }, { queueName, data, job
         },
     };
     try {
-        await runQueueJob({ job, traceId });
+        await runQueueJob({ job });
     }
     catch (error) {
         if (error instanceof PikkuMissingMetaError ||

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

@@ -41,8 +41,13 @@ export declare class ContextAwareRPCService {
         requiresAuth?: boolean;
         sessionService?: SessionService<CoreUserSession>;
     }, packageName?: string | null);
+    get traceparent(): string | undefined;
     rpcExposed(funcName: string, data: any): Promise<any>;
     rpc<In = any, Out = any>(funcName: string, data: In): Promise<Out>;
+    /** A call runs as a span of its own under the caller's. */
+    private callSpan;
+    /** The services' logger, on the trace of the wire this service belongs to. */
+    private get logger();
     private mapUsedAddon;
     /**
      * Resolution half of an addon RPC call: never executes anything, so an
@@ -63,6 +68,7 @@ export declare class ContextAwareRPCService {
             type: string;
             id?: string;
             parentRunId?: string;
+            traceparent?: string;
         };
     }): Promise<{
         runId: string;
@@ -107,7 +113,7 @@ export declare const rpcService: PikkuRPCService<import("../../types/core.types.
     secrets?: {
         requireAllowedHosts?: boolean;
     };
-    workflow?: import("../workflow/workflow.types.js").WorkflowServiceConfig;
+    workflow?: Partial<import("../workflow/workflow.types.js").WorkflowServiceConfig>;
     webhook?: import("../../services/webhook-service.js").WebhookServiceConfig;
     postgres?: import("../../types/core.types.js").PostgresConfig;
 }>, PikkuRPC>;

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

@@ -1,3 +1,4 @@
+import { childTraceWire, outgoingTraceparent, tracedLogger, } from '../../trace.js';
 import { AddonNotUsedError, addonCallerOf, addonMayReach, mapAddonCall, } from '../addon/addon-reach.js';
 import { forwardStepName, isCompensationStepName, } from '../../compensation-name.js';
 import { addonInstanceForNamespace } from '../addon/addon-runner.js';
@@ -80,7 +81,7 @@ addError(RemoteAddonTimeoutError, {
 /** Headers a wiring's `headers` hook cannot set: the call's auth, trace and contract. */
 const RESERVED_REMOTE_HEADERS = new Set([
     'authorization',
-    'x-request-id',
+    'traceparent',
     REMOTE_CONTRACT_HEADER,
     'content-type',
     'accept',
@@ -264,6 +265,9 @@ export class ContextAwareRPCService {
         this.options = options;
         this.packageName = packageName;
     }
+    get traceparent() {
+        return outgoingTraceparent(this.wire);
+    }
     async rpcExposed(funcName, data) {
         const addonCaller = addonCallerOf(this.wire);
         if (addonCaller && !addonMayReach(addonCaller, funcName)) {
@@ -323,14 +327,15 @@ export class ContextAwareRPCService {
         return await this.rpc(funcName, data);
     }
     async rpc(funcName, data) {
-        const updatedWire = {
-            ...this.wire,
-        };
+        // A local function is a span of its own. Across a boundary the callee's
+        // parent must be a span that exists, so that is the caller's.
+        const updatedWire = { ...this.wire };
+        const localWire = { ...updatedWire, ...this.callSpan() };
         if (funcName.includes(':')) {
             funcName = this.mapUsedAddon(funcName);
             const addonCall = this.resolveAddonFunction(funcName);
             if (addonCall !== NOT_RESOLVED) {
-                return await this.executeAddonFunction(addonCall, data, updatedWire);
+                return await this.executeAddonFunction(addonCall, data, addonCall.kind === 'remote' ? updatedWire : localWire);
             }
         }
         let resolved;
@@ -341,7 +346,7 @@ export class ContextAwareRPCService {
             if (e instanceof RPCNotFoundError) {
                 if (!this.packageName && this.services.deploymentService) {
                     const session = await resolveWireSession(this.wire);
-                    return this.services.deploymentService.invoke(funcName, data, session, this.wire.traceId);
+                    return this.services.deploymentService.invoke(funcName, data, session, outgoingTraceparent(this.wire));
                 }
             }
             throw e;
@@ -353,11 +358,19 @@ export class ContextAwareRPCService {
             auth: this.options.requiresAuth,
             singletonServices: this.services,
             data: () => data,
-            wire: updatedWire,
+            wire: localWire,
             packageName: resolved.packageName,
             addonInstance,
         });
     }
+    /** A call runs as a span of its own under the caller's. */
+    callSpan() {
+        return this.wire.trace ? childTraceWire(this.wire.trace) : {};
+    }
+    /** The services' logger, on the trace of the wire this service belongs to. */
+    get logger() {
+        return tracedLogger(this.services.logger, this.wire.traceId);
+    }
     mapUsedAddon(funcName) {
         return mapAddonCall(this.wire.addonNamespace, funcName);
     }
@@ -427,7 +440,7 @@ export class ContextAwareRPCService {
      */
     async executeAddonFunction(addonCall, data, wire) {
         if (addonCall.kind === 'remote') {
-            return this.invokeRemoteAddonFunction(addonCall.namespace, addonCall.fnName, data, addonCall.addonConfig);
+            return this.invokeRemoteAddonFunction(addonCall.namespace, addonCall.fnName, data, addonCall.addonConfig, outgoingTraceparent(wire));
         }
         return runPikkuFunc('rpc', addonCall.namespacedFunction, addonCall.pikkuFuncId, {
             auth: addonCall.auth,
@@ -439,7 +452,7 @@ export class ContextAwareRPCService {
             addonInstance: addonCall.addonInstance,
         });
     }
-    async invokeRemoteAddonFunction(namespace, fnName, data, cfg) {
+    async invokeRemoteAddonFunction(namespace, fnName, data, cfg, traceparent) {
         const serverUrl = typeof cfg.serverUrl === 'function'
             ? await cfg.serverUrl(this.services)
             : cfg.serverUrl;
@@ -476,8 +489,8 @@ export class ContextAwareRPCService {
         if (token) {
             headers.authorization = `Bearer ${token}`;
         }
-        if (this.wire.traceId) {
-            headers['x-request-id'] = this.wire.traceId;
+        if (traceparent) {
+            headers.traceparent = traceparent;
         }
         const timeoutMs = cfg.remoteTimeoutMs ?? DEFAULT_REMOTE_ADDON_TIMEOUT_MS;
         const base = serverUrl.replace(/\/+$/, '');
@@ -496,11 +509,11 @@ export class ContextAwareRPCService {
             if (e?.name === 'TimeoutError') {
                 throw new RemoteAddonTimeoutError(namespace, remoteFn, timeoutMs);
             }
-            this.services.logger.error(`Remote addon '${namespace}:${remoteFn}' could not be reached: ${e instanceof Error ? e.message : e}`);
+            this.logger.error(`Remote addon '${namespace}:${remoteFn}' could not be reached: ${e instanceof Error ? e.message : e}`);
             throw new RemoteAddonFailedError(namespace, remoteFn);
         }
         if (!res.ok) {
-            throw await remoteAddonResponseError(res, namespace, remoteFn, this.services.logger);
+            throw await remoteAddonResponseError(res, namespace, remoteFn, this.logger);
         }
         if (res.status === 204) {
             return undefined;
@@ -513,7 +526,7 @@ export class ContextAwareRPCService {
             return JSON.parse(text);
         }
         catch {
-            this.services.logger.error(`Remote addon '${namespace}:${remoteFn}' answered ${res.status} with a body that is not JSON`);
+            this.logger.error(`Remote addon '${namespace}:${remoteFn}' answered ${res.status} with a body that is not JSON`);
             throw new RemoteAddonFailedError(namespace, remoteFn);
         }
     }
@@ -538,7 +551,7 @@ export class ContextAwareRPCService {
                 !this.packageName &&
                 this.services.deploymentService) {
                 const session = await resolveWireSession(mergedWire);
-                return this.services.deploymentService.invoke(rpcName, data, session, mergedWire.traceId);
+                return this.services.deploymentService.invoke(rpcName, data, session, outgoingTraceparent(mergedWire));
             }
             throw e;
         }
@@ -562,11 +575,17 @@ export class ContextAwareRPCService {
             workflowName = this.mapUsedAddon(workflowName);
         }
         const parentRunId = this.wire.workflowStep?.runId ?? this.wire.graph?.runId;
-        const wire = options?.wire ?? {
-            type: this.wire.wireType ?? 'unknown',
-            id: this.wire.wireId,
-            ...(parentRunId ? { parentRunId } : {}),
-            ...(this.wire.pikkuUserId ? { pikkuUserId: this.wire.pikkuUserId } : {}),
+        const traceparent = options?.wire?.traceparent ?? this.traceparent;
+        const wire = {
+            ...(options?.wire ?? {
+                type: this.wire.wireType ?? 'unknown',
+                id: this.wire.wireId,
+                ...(parentRunId ? { parentRunId } : {}),
+                ...(this.wire.pikkuUserId
+                    ? { pikkuUserId: this.wire.pikkuUserId }
+                    : {}),
+            }),
+            ...(traceparent ? { traceparent } : {}),
         };
         return this.services.workflowService.startWorkflow(workflowName, input, wire, this, options);
     }
@@ -593,7 +612,7 @@ export class ContextAwareRPCService {
                 `Set up a DeploymentService to enable mesh function calls.`);
         }
         const session = await resolveWireSession(this.wire);
-        return this.services.deploymentService.invoke(funcName, data, session, this.wire.traceId);
+        return this.services.deploymentService.invoke(funcName, data, session, outgoingTraceparent(this.wire));
     }
 }
 /**
@@ -652,6 +671,9 @@ class ContextRPCView {
         this.startWorkflow = serviceRPC.startWorkflow.bind(serviceRPC);
         this.rpcWithWire = serviceRPC.rpcWithWire.bind(serviceRPC);
     }
+    get traceparent() {
+        return this.serviceRPC.traceparent;
+    }
     get agent() {
         return this.serviceRPC.agent;
     }

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

@@ -5,6 +5,8 @@ import type { AgentInterruptResult } from '../agent/agent-interrupt.js';
 export type PikkuRPC<Invoke extends (...args: any[]) => any = (...args: any[]) => any, Mesh 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;
+    /** The W3C trace of the invocation holding this `rpc`, if it is in one. */
+    traceparent?: string;
     invoke: Invoke;
     mesh: Mesh;
     exposed: (name: string, data: any) => Promise<any>;

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

@@ -8,4 +8,4 @@ import type { RemoteScheduledJobData } from '../../services/remote-jobs.js';
  */
 export declare function pikkuRemoteScheduledJobFunc({ logger }: {
     logger: Logger;
-}, { taskName }: RemoteScheduledJobData): Promise<void>;
+}, { taskName, traceparent }: RemoteScheduledJobData): Promise<void>;

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

@@ -6,9 +6,9 @@ import { ScheduledTaskNotFoundError, runScheduledTask, } from './scheduler-runne
  *
  * @throws {BadRequestError} When the named task is not wired in this unit.
  */
-export async function pikkuRemoteScheduledJobFunc({ logger }, { taskName }) {
+export async function pikkuRemoteScheduledJobFunc({ logger }, { taskName, traceparent }) {
     try {
-        await runScheduledTask({ name: taskName, traceId: `cron-${taskName}` });
+        await runScheduledTask({ name: taskName, traceparent });
     }
     catch (error) {
         if (error instanceof ScheduledTaskNotFoundError) {

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

@@ -2,11 +2,11 @@ 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. */
+/** Parameters for {@link runScheduledTask}: the task's name, an optional session to run it with, and an optional W3C trace to continue. */
 export type RunScheduledTasksParams = {
     name: string;
     session?: CoreUserSession;
-    traceId?: string;
+    traceparent?: string;
 };
 /**
  * Registers a sessionless function to run on a cron schedule.
@@ -35,10 +35,10 @@ export declare class ScheduledTaskNotFoundError extends PikkuError {
  * 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>`.
+ * @param params - See {@link RunScheduledTasksParams}. A missing or invalid `traceparent` starts a new trace.
  * @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>;
+export declare function runScheduledTask({ name, session, traceparent, }: 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>;

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

@@ -1,6 +1,7 @@
 import { getErrorResponse, PikkuError } from '../../errors/error-handler.js';
 import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../pikku-state.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
+import { continueTrace } from '../../trace.js';
 import { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../services/user-session-service.js';
 /**
  * Registers a sessionless function to run on a cron schedule.
@@ -56,16 +57,15 @@ class ScheduledTaskSkippedError extends PikkuError {
  * 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>`.
+ * @param params - See {@link RunScheduledTasksParams}. A missing or invalid `traceparent` starts a new trace.
  * @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 async function runScheduledTask({ name, session, traceId, }) {
+export async function runScheduledTask({ name, session, traceparent, }) {
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();
-    const resolvedTraceId = traceId ?? `cron-${name}-${Date.now()}`;
-    const scopedLogger = singletonServices.logger.scope?.(resolvedTraceId) ??
-        singletonServices.logger;
+    const trace = continueTrace(traceparent);
+    const scopedLogger = singletonServices.logger.scope?.(trace.traceId) ?? singletonServices.logger;
     const task = pikkuState(null, 'scheduler', 'tasks').get(name);
     const meta = pikkuState(null, 'scheduler', 'meta')[name];
     const userSession = new PikkuSessionService(singletonServices.sessionStore);
@@ -79,7 +79,8 @@ export async function runScheduledTask({ name, session, traceId, }) {
         throw new ScheduledTaskNotFoundError(`Scheduled task meta not found: ${name}`);
     }
     const wire = {
-        traceId: resolvedTraceId,
+        traceId: trace.traceId,
+        trace,
         scheduledTask: {
             name,
             schedule: task.schedule,

package/dist/wirings/trigger/pikku-trigger-service.js

@@ -1,6 +1,7 @@
 import { rpcService } from '../rpc/rpc-runner.js';
 import { setupTrigger } from './trigger-runner.js';
 import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../pikku-state.js';
+import { traceWire, tracedLogger } from '../../trace.js';
 /**
  * Base class for a {@link TriggerService}: pairs registered trigger sources with
  * the triggers listening to them and owns teardown. Subclasses decide where and
@@ -54,9 +55,11 @@ export class PikkuTriggerService {
         // The user rides on the wire, where the function runner resolves the
         // target's session and credentials from it and a started workflow records
         // it on the run.
-        const wire = options?.pikkuUserId
-            ? { pikkuUserId: options.pikkuUserId }
-            : {};
+        // One trace per event, shared by every target it fires.
+        const wire = {
+            ...traceWire(),
+            ...(options?.pikkuUserId ? { pikkuUserId: options.pikkuUserId } : {}),
+        };
         const wireServices = await createWireServices?.(singletonServices, wire);
         const services = { ...singletonServices, ...wireServices };
         const rpc = rpcService.getContextRPCService(services, wire, false);
@@ -74,7 +77,7 @@ export class PikkuTriggerService {
                 }
             }
             catch (error) {
-                singletonServices.logger.error(`Error invoking ${target.targetType} '${target.targetName}' from trigger '${triggerName}': ${error}`);
+                tracedLogger(singletonServices.logger, wire.traceId).error(`Error invoking ${target.targetType} '${target.targetName}' from trigger '${triggerName}': ${error}`);
             }
         }
     }