@pikku/core 0.12.148 → 0.12.151

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

@@ -1,5 +1,6 @@
 import { NotFoundError } from '../../errors/errors.js';
 import { createWeakUID, isSerializable } from '../../utils.js';
+import { resolveHTTPTrace } from '../../trace.js';
 import { getSingletonServices, getCreateWireServices, } from '../../pikku-state.js';
 import { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../services/user-session-service.js';
 import { getErrorResponse } from '../../errors/error-handler.js';
@@ -120,7 +121,7 @@ export const createHTTPWire = (request, response) => {
 };
 const executeRoute = async (services, matchedRoute, http, options) => {
     const { params, route, meta } = matchedRoute;
-    const { singletonServices, createWireServices, skipUserSession, requestId } = services;
+    const { singletonServices, createWireServices, skipUserSession, trace } = services;
     const userSession = new PikkuSessionService(singletonServices.sessionStore);
     http?.request?.setParams(params);
     if (meta.headersSchemaName && http.request && singletonServices.schema) {
@@ -206,7 +207,8 @@ const executeRoute = async (services, matchedRoute, http, options) => {
         });
     }
     const wire = {
-        traceId: requestId,
+        traceId: trace.traceId,
+        trace,
         http,
         channel,
         ...createMiddlewareSessionWireProps(userSession),
@@ -295,9 +297,9 @@ export const pikkuFetch = async (request, params = {}) => {
  *
  * The lower-level form of {@link fetch} for adapters that bring their own
  * request and response objects (Express, Fastify, uWS). A web `Request` is
- * wrapped with the `maxBodySize` limit. The trace ID is taken from `traceId`,
- * then the `x-request-id` header, then `generateRequestId`, and is returned to
- * the client as `errorId` on failures.
+ * wrapped with the `maxBodySize` limit. The trace comes from a valid `traceId`,
+ * then `traceparent` when `trustInboundTraceparent` is set, and is otherwise new.
+ * Its id is returned to the client as `errorId` on failures.
  *
  * Errors are written to `response`: a 4xx keeps its message and payload, while a
  * 5xx or an unknown error hides its message unless `exposeErrors` is set outside
@@ -311,22 +313,16 @@ export const pikkuFetch = async (request, params = {}) => {
  * @throws The original error when `bubbleErrors` is set, after the error response has been written.
  * @throws {Error} When `skipUserSession` is set on a route that requires auth.
  */
-export const fetchData = async (request, response, { skipUserSession = false, respondWith404 = true, logWarningsForStatusCodes = [], coerceDataFromSchema = true, bubbleErrors = false, exposeErrors = !isProduction(), generateRequestId, traceId: externalTraceId, maxBodySize, } = {}) => {
+export const fetchData = async (request, response, { skipUserSession = false, respondWith404 = true, logWarningsForStatusCodes = [], coerceDataFromSchema = true, bubbleErrors = false, exposeErrors = !isProduction(), traceId, trustInboundTraceparent, maxBodySize, } = {}) => {
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();
     let result;
     const pikkuRequest = request instanceof Request
         ? new PikkuFetchHTTPRequest(request, { maxBodySize })
         : request;
-    let requestId = externalTraceId ?? null;
-    if (!requestId) {
-        try {
-            requestId = pikkuRequest.header('x-request-id');
-        }
-        catch { }
-    }
-    requestId = requestId || generateRequestId?.() || createWeakUID();
-    const scopedLogger = singletonServices.logger.scope?.(requestId) ?? singletonServices.logger;
+    const trace = resolveHTTPTrace(() => pikkuRequest.header('traceparent'), singletonServices.logger, { traceId, trustInboundTraceparent });
+    // Read at the point of logging: mesh auth can continue the caller's trace.
+    const scopedLogger = () => singletonServices.logger.scope?.(trace.traceId) ?? singletonServices.logger;
     const http = createHTTPWire(pikkuRequest, response);
     const apiType = http.request.method();
     const apiRoute = http.request.path();
@@ -344,7 +340,7 @@ export const fetchData = async (request, response, { skipUserSession = false, re
                 response.status(204).json(undefined);
                 return;
             }
-            scopedLogger.info({
+            scopedLogger().info({
                 message: 'Route not found',
                 apiRoute,
                 apiType,
@@ -356,11 +352,11 @@ export const fetchData = async (request, response, { skipUserSession = false, re
             singletonServices,
             createWireServices,
             skipUserSession,
-            requestId,
+            trace,
         }, matchedRoute, http, { coerceDataFromSchema }));
         return result;
     }
     catch (e) {
-        handleHTTPError(e, http, requestId, scopedLogger, logWarningsForStatusCodes, respondWith404, bubbleErrors, exposeErrors);
+        handleHTTPError(e, http, trace.traceId, scopedLogger(), logWarningsForStatusCodes, respondWith404, bubbleErrors, exposeErrors);
     }
 };

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

@@ -20,7 +20,7 @@ export type AssertHTTPWiringParams<In, HTTPWiring extends string> = ExtractHTTPW
  * - `coerceDataFromSchema` – coerce query and path strings to the schema's types (default `true`).
  * - `bubbleErrors` – rethrow after writing the error response.
  * - `exposeErrors` – include messages and stacks of 5xx errors; ignored in production.
- * - `generateRequestId` – produce a trace ID when neither `traceId` nor `x-request-id` is present.
+ * - `trustInboundTraceparent` – continue the trace named by `traceparent` on every request. Off by default, because the header is caller-supplied.
  */
 export type RunHTTPWiringOptions = Partial<{
     skipUserSession: boolean;
@@ -29,8 +29,8 @@ export type RunHTTPWiringOptions = Partial<{
     coerceDataFromSchema: boolean;
     bubbleErrors: boolean;
     exposeErrors: boolean;
-    generateRequestId: () => string;
-    /** Pre-resolved trace ID (e.g. CF-Ray). Falls back to x-request-id header or generated ID. */
+    trustInboundTraceparent: boolean;
+    /** A trace ID the runtime already holds: 32 lowercase hex, anything else is ignored. */
     traceId: string;
     /** Maximum request body size in bytes, applied when pikku wraps a fetch `Request`. */
     maxBodySize: number;

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>;