@pikku/core 0.12.148 → 0.12.151

package/dist/testing/trace-matrix/workflow-cases.js

@@ -0,0 +1,147 @@
+import { ConflictError, ForbiddenError, NotFoundError, UnauthorizedError, UnprocessableContentError, } from '../../errors/errors.js';
+import { AbandonedError } from '../../function/abort-scope.js';
+import { RemoteAddonAuthError } from '../../wirings/addon/remote-addon-auth.js';
+import { RemoteAddonFailedError, RemoteAddonTimeoutError, } from '../../wirings/rpc/rpc-runner.js';
+import { QueueJobDiscardedError } from '../../wirings/queue/queue-runner.js';
+import { InMemoryWorkflowService } from '../../wirings/workflow/in-memory-workflow-service.js';
+import { PikkuWorkflowService } from '../../wirings/workflow/pikku-workflow-service.js';
+/** Sleeps go through the scheduler, as in a deployment, so the wake-up is driven by hand. */
+export class ScheduledSleeps extends InMemoryWorkflowService {
+    scheduleSleep(...args) {
+        return PikkuWorkflowService.prototype['scheduleSleep'].apply(this, args);
+    }
+}
+/** What a step's RPC throws for an outcome: the class a real call would raise. */
+export const outcomeError = (outcome) => {
+    switch (outcome) {
+        case 'throw-pikku-error':
+        case 'step-compensated':
+        case 'fan-out-sibling-failure':
+            return new ConflictError('refused');
+        case 'throw-plain-error':
+        case 'job-exhausted':
+            return new Error('boom');
+        case 'schema-invalid':
+        case 'job-poison':
+            return new UnprocessableContentError('schema refused the data');
+        case 'auth-mesh-jwt':
+            return new UnauthorizedError();
+        case 'auth-remote-addon':
+            return new RemoteAddonAuthError('far', 'resolved token was empty');
+        case 'permission-denied':
+            return new ForbiddenError();
+        case 'remote-4xx':
+            return new NotFoundError();
+        case 'remote-5xx':
+        case 'remote-network':
+            return new RemoteAddonFailedError('far', 'fn');
+        case 'remote-timeout':
+            return new RemoteAddonTimeoutError('far', 'fn', 2);
+        case 'job-discarded':
+            return new QueueJobDiscardedError('job', 'not wanted');
+        case 'abandoned':
+            return new AbandonedError('the caller left');
+        default:
+            return undefined;
+    }
+};
+const isDsl = (workflow) => workflow.startsWith('dsl');
+/**
+ * Registers a workflow named `flow-<id>` that reaches `step`, then has its last
+ * RPC meet `outcome`. Returns what brings the run to its end.
+ */
+export const defineRun = (h, run, child = false) => {
+    const { id, workflow, step, outcome } = run;
+    const queued = workflow.endsWith('-queued');
+    const failure = () => outcomeError(outcome);
+    let released = false;
+    let calls = 0;
+    const last = {
+        queued,
+        forward: async () => {
+            const error = failure();
+            if (error)
+                throw error;
+            if (step === 'retry' && ++calls === 1)
+                throw new Error('flaky');
+            return {};
+        },
+    };
+    const undoable = step === 'compensation' || outcome === 'step-compensated'
+        ? { compensate: async () => { } }
+        : {};
+    h.register(`first-${id}`, {
+        queued,
+        ...undoable,
+        forward: async (_data, wire) => {
+            if (outcome === 'workflow-cancelled') {
+                await h.ws.cancelRun(wire.workflow?.runId ?? wire.workflowStep?.runId, h.rpc);
+            }
+            return {};
+        },
+    });
+    h.register(`last-${id}`, last);
+    h.register(`left-${id}`, { queued, forward: async () => ({}) });
+    const inner = child ? `inner-${id}` : `flow-${id}`;
+    if (isDsl(workflow)) {
+        h.defineDsl(inner, async (w) => {
+            await w.do('First', `first-${id}`, {});
+            if (step === 'sleep')
+                await w.sleep('Nap', 1);
+            if (step === 'suspend' && !released)
+                await w.suspend('Hold');
+            if (step === 'approval') {
+                const decision = await w.approval('Sign off', {
+                    schema: {
+                        '~standard': {
+                            version: 1,
+                            vendor: 'matrix',
+                            validate: (value) => ({ value }),
+                        },
+                    },
+                });
+                if (decision.data?.ok === false) {
+                    throw new ConflictError('the approval was rejected');
+                }
+            }
+            if (step === 'fan-out') {
+                await Promise.all([
+                    w.do('Left', `left-${id}`, {}),
+                    w.do('Last', `last-${id}`, {}),
+                ]);
+            }
+            else {
+                await w.do('Last', `last-${id}`, {}, step === 'retry' ? { retries: 2 } : undefined);
+            }
+        });
+    }
+    else {
+        h.defineGraph(inner, `first-${id}`, {
+            [`first-${id}`]: {
+                next: step === 'fan-out' ? [`left-${id}`, `last-${id}`] : `last-${id}`,
+            },
+            [`left-${id}`]: {},
+            [`last-${id}`]: step === 'retry' ? { retries: 2 } : {},
+        });
+    }
+    if (child) {
+        h.defineDsl(`flow-${id}`, async (w) => w.do('Child', inner, {}));
+    }
+    return {
+        /** Wakes whatever the run is waiting on, then lets it finish. */
+        settle: async (runId, wakeSleeps) => {
+            if (step === 'sleep')
+                await wakeSleeps();
+            if (step === 'suspend') {
+                released = true;
+                await h.ws.resumeWorkflow(runId);
+            }
+            if (step === 'approval') {
+                await h.ws.approveStep(runId, 'Sign off', {
+                    ok: outcome !== 'approval-rejected',
+                });
+            }
+            await h.pump();
+        },
+    };
+};

package/dist/trace.d.ts

@@ -0,0 +1,66 @@
+import type { Logger } from './services/logger.js';
+/** One invocation's place in a W3C trace. */
+export type TraceContext = {
+    /** 32 lowercase hex characters, shared by every hop of the trace. */
+    traceId: string;
+    /** 16 lowercase hex characters, identifying this invocation. */
+    spanId: string;
+    /** The caller's span, when the trace was continued from another hop. */
+    parentSpanId?: string;
+    sampled: boolean;
+};
+/** Whether `value` is a usable trace id: 32 lowercase hex, not all zero. */
+export declare const isValidTraceId: (value: unknown) => value is string;
+/** A new trace, or a new span in `traceId` when one is given. */
+export declare const createTrace: (traceId?: string) => TraceContext;
+/**
+ * Reads a W3C `traceparent` header. Returns `undefined` for anything malformed,
+ * an all-zero id, version `ff`, or a version `00` header with extra fields.
+ */
+export declare const parseTraceparent: (header: unknown) => (Pick<TraceContext, 'traceId' | 'sampled'> & {
+    parentSpanId: string;
+}) | undefined;
+/** Formats `trace` as the `traceparent` of a call it makes: it is the parent. */
+export declare const formatTraceparent: (trace: Pick<TraceContext, 'traceId' | 'spanId' | 'sampled'>) => string;
+/**
+ * Resolves the trace for an inbound HTTP request: a valid `traceId` from the
+ * runtime, then the `traceparent` header if the deployment opted in, then a new
+ * trace.
+ *
+ * knowledge: decisions/security/inbound-traceparent-is-ignored-until-the-caller-is-authenticated.md
+ */
+export declare const resolveHTTPTrace: (readHeader: () => unknown, logger: Logger, { traceId, trustInboundTraceparent, }: {
+    traceId?: string;
+    trustInboundTraceparent?: boolean;
+}) => TraceContext;
+/**
+ * Starts this hop's span in the trace a job, scheduled task or workflow run
+ * carried, or a new trace when it carried nothing usable. A carried value needs
+ * no signature: it names a trace, never an identity.
+ */
+export declare const continueTrace: (traceparent: unknown) => TraceContext;
+/**
+ * Continues the caller's trace on an already-running invocation. Only for a
+ * caller that has been authenticated, and in place because the HTTP runner
+ * holds `wire.trace` for its error response.
+ */
+export declare const adoptTraceparent: (wire: {
+    traceId?: string;
+    trace?: TraceContext;
+}, header: unknown) => void;
+/** `logger` scoped to a trace, so what it writes can be found by that id. */
+export declare const tracedLogger: (logger: Logger, traceId?: string) => Logger;
+/** The wire fields for a hop that continues `traceparent`, or starts a new trace. */
+export declare const traceWire: (traceparent?: unknown) => {
+    traceId: string;
+    trace: TraceContext;
+};
+/** {@link traceWire} for a child of `parent`, when there is a parent. */
+export declare const childTraceWire: (parent: TraceContext | undefined) => {
+    traceId: string;
+    trace: TraceContext;
+};
+/** The `traceparent` for a call made from `wire`, if it is in a W3C trace. */
+export declare const outgoingTraceparent: (wire: {
+    trace?: TraceContext;
+}) => string | undefined;

package/dist/trace.js

@@ -0,0 +1,97 @@
+const TRACE_ID = /^[0-9a-f]{32}$/;
+const TRACEPARENT = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})(-.*)?$/;
+const ALL_ZERO = /^0+$/;
+const randomHex = (bytes) => {
+    const hex = Array.from(globalThis.crypto.getRandomValues(new Uint8Array(bytes)), (byte) => byte.toString(16).padStart(2, '0')).join('');
+    // All zeroes means "invalid" in W3C, so it can never be issued.
+    return ALL_ZERO.test(hex) ? randomHex(bytes) : hex;
+};
+/** Whether `value` is a usable trace id: 32 lowercase hex, not all zero. */
+export const isValidTraceId = (value) => typeof value === 'string' && TRACE_ID.test(value) && !ALL_ZERO.test(value);
+/** A new trace, or a new span in `traceId` when one is given. */
+export const createTrace = (traceId) => ({
+    traceId: traceId ?? randomHex(16),
+    spanId: randomHex(8),
+    sampled: true,
+});
+/**
+ * Reads a W3C `traceparent` header. Returns `undefined` for anything malformed,
+ * an all-zero id, version `ff`, or a version `00` header with extra fields.
+ */
+export const parseTraceparent = (header) => {
+    if (typeof header !== 'string')
+        return undefined;
+    const match = TRACEPARENT.exec(header);
+    if (!match)
+        return undefined;
+    const [, version, traceId, parentSpanId, flags, extra] = match;
+    if (version === 'ff' || (version === '00' && extra !== undefined)) {
+        return undefined;
+    }
+    if (ALL_ZERO.test(traceId) || ALL_ZERO.test(parentSpanId))
+        return undefined;
+    return {
+        traceId: traceId,
+        parentSpanId: parentSpanId,
+        sampled: (Number.parseInt(flags, 16) & 1) === 1,
+    };
+};
+/** Formats `trace` as the `traceparent` of a call it makes: it is the parent. */
+export const formatTraceparent = (trace) => `00-${trace.traceId}-${trace.spanId}-${trace.sampled ? '01' : '00'}`;
+/**
+ * Resolves the trace for an inbound HTTP request: a valid `traceId` from the
+ * runtime, then the `traceparent` header if the deployment opted in, then a new
+ * trace.
+ *
+ * knowledge: decisions/security/inbound-traceparent-is-ignored-until-the-caller-is-authenticated.md
+ */
+export const resolveHTTPTrace = (readHeader, logger, { traceId, trustInboundTraceparent, }) => {
+    if (traceId !== undefined) {
+        if (isValidTraceId(traceId))
+            return createTrace(traceId);
+        logger.warn('Ignoring a traceId that is not 32 lowercase hex characters');
+    }
+    if (trustInboundTraceparent) {
+        let header;
+        try {
+            header = readHeader();
+        }
+        catch { }
+        const inbound = parseTraceparent(header);
+        if (inbound)
+            return { ...inbound, spanId: randomHex(8) };
+    }
+    return createTrace();
+};
+/**
+ * Starts this hop's span in the trace a job, scheduled task or workflow run
+ * carried, or a new trace when it carried nothing usable. A carried value needs
+ * no signature: it names a trace, never an identity.
+ */
+export const continueTrace = (traceparent) => {
+    const carried = parseTraceparent(traceparent);
+    return carried ? { ...carried, spanId: randomHex(8) } : createTrace();
+};
+/**
+ * Continues the caller's trace on an already-running invocation. Only for a
+ * caller that has been authenticated, and in place because the HTTP runner
+ * holds `wire.trace` for its error response.
+ */
+export const adoptTraceparent = (wire, header) => {
+    const inbound = parseTraceparent(header);
+    if (!inbound)
+        return;
+    wire.traceId = inbound.traceId;
+    wire.trace = Object.assign(wire.trace ?? createTrace(inbound.traceId), inbound);
+};
+/** `logger` scoped to a trace, so what it writes can be found by that id. */
+export const tracedLogger = (logger, traceId) => (traceId && logger.scope?.(traceId)) || logger;
+/** The wire fields for a hop that continues `traceparent`, or starts a new trace. */
+export const traceWire = (traceparent) => {
+    const trace = continueTrace(traceparent);
+    return { traceId: trace.traceId, trace };
+};
+/** {@link traceWire} for a child of `parent`, when there is a parent. */
+export const childTraceWire = (parent) => traceWire(parent && formatTraceparent(parent));
+/** The `traceparent` for a call made from `wire`, if it is in a W3C trace. */
+export const outgoingTraceparent = (wire) => wire.trace && formatTraceparent(wire.trace);

package/dist/types/core.types.d.ts

@@ -1,4 +1,6 @@
 import type { AbortScope } from '../function/abort-scope.js';
+import type { TraceContext } from '../trace.js';
+export type { TraceContext };
 import type { IncomingWebhookService } from '../services/incoming-webhook-service.js';
 import type { TriggerSourceStore } from '../services/trigger-source-store.js';
 import type { LeaseService } from '../services/lease-service.js';
@@ -88,7 +90,7 @@ export type CoreConfig<Config extends Record<string, unknown> = {}> = {
         /** Refuse a secret that declares no `allowedHosts` rather than treating it as unrestricted. */
         requireAllowedHosts?: boolean;
     };
-    workflow?: WorkflowServiceConfig;
+    workflow?: Partial<WorkflowServiceConfig>;
     webhook?: WebhookServiceConfig;
     postgres?: PostgresConfig;
 } & Config;
@@ -255,8 +257,10 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
      * sets it; services that log fall back to the singleton logger.
      */
     logger: Logger;
-    /** Trace ID for distributed tracing — propagated across mesh RPC calls via the x-request-id header */
+    /** Trace ID for distributed tracing — propagated across mesh RPC calls via the traceparent header */
     traceId: string;
+    /** This invocation's place in the trace, when it has a W3C one. */
+    trace: TraceContext;
     functionId: string;
     addonNamespace: string;
     http: PikkuHTTP<In>;

package/dist/wirings/addon/addon-reach.d.ts

@@ -5,6 +5,9 @@ export declare const addonCallerOf: (wire: PikkuRawWire) => string | undefined;
 export declare class AddonNotUsedError extends PikkuError {
     constructor(caller: string, target: string);
 }
+export declare class AddonUsesShadowedError extends PikkuError {
+    constructor(name: string, target: string);
+}
 /**
  * The name an addon's call resolves to on this host, through its `uses`.
  *

package/dist/wirings/addon/addon-reach.js

@@ -29,6 +29,15 @@ addError(AddonNotUsedError, {
     status: 403,
     message: 'Addon called another addon it does not use.',
 });
+export class AddonUsesShadowedError extends PikkuError {
+    constructor(name, target) {
+        super(`Addon '${name}' maps its own name in 'uses' to '${target}', but a call to '${name}:<function>' always reaches the addon itself, so the mapping can never be used. Mount the addon under another name.`);
+    }
+}
+addError(AddonUsesShadowedError, {
+    status: 500,
+    message: 'Addon uses maps its own name.',
+});
 /**
  * The name an addon's call resolves to on this host, through its `uses`.
  *

package/dist/wirings/addon/define-plugin.d.ts

@@ -22,6 +22,22 @@ type StudioScreenBase = {
     layout?: 'bare';
     /** Hides the screen and its nav for viewers without access. The addon's functions must enforce the same scopes: hiding a screen is not access control. */
     scopes?: string[];
+    /**
+     * The agent that answers in Studio's chat panel while this screen is open.
+     * `'studio:<name>'` names an agent Studio ships (e.g. `'studio:knowledge'`);
+     * `pikku all` only checks its format. A bare name is an agent the addon ships:
+     * it resolves to `agents/<name>.md` in the addon package: the agent's
+     * instructions, which name the skills it follows. Its frontmatter has a
+     * `title` and a `description`, both message keys in the addon's catalog.
+     * Lowercase letters, digits and hyphens, starting with a letter. Leave it out and the chat is unchanged.
+     */
+    agent?: string;
+    /**
+     * Whether Studio's general Chat tab shows on this screen, beside the
+     * screen's agent tab. Defaults to `true`. `false` hides it; with no `agent`
+     * the screen then has no chat at all.
+     */
+    defaultChat?: boolean;
 } & ({
     /** `'studio'` gives `/<path>`, `'team'` gives `/<team>/<path>`. */
     scope: 'studio' | 'team';

package/dist/wirings/addon/wire-addon.js

@@ -1,5 +1,6 @@
 import { pikkuState } from '../../pikku-state.js';
 import { getTagGroups } from '../../utils.js';
+import { AddonUsesShadowedError } from './addon-reach.js';
 /**
  * Installs an addon into this project: its functions, wirings and scopes become
  * part of the app, under the namespace and options given here.
@@ -7,6 +8,10 @@ import { getTagGroups } from '../../utils.js';
  * @example snippet: addonWiring
  */
 export const wireAddon = (config) => {
+    const shadowed = config.uses?.[config.name];
+    if (shadowed !== undefined && shadowed !== config.name) {
+        throw new AddonUsesShadowedError(config.name, shadowed);
+    }
     pikkuState(null, 'addons', 'packages').set(config.name, {
         package: config.package,
         rpcEndpoint: config.rpcEndpoint,

package/dist/wirings/addon/wire-remote-addon.d.ts

@@ -51,6 +51,17 @@ export type WireRemoteAddonConfig = {
      * knowledge: decisions/security/wire-addon-expose-selects-the-rpc-surface.md
      */
     expose?: boolean | string[];
+    /**
+     * A package installed in this project that carries the screens and
+     * contributors shown under this name, when they live apart from the contract
+     * package. Read at build time, never at runtime. `ui` mounts its screens;
+     * `contributors` opts in to the ones it registers.
+     */
+    local?: {
+        package: string;
+        ui?: boolean;
+        contributors?: string[];
+    };
     /** Milliseconds a call may take before it is aborted. Defaults to {@link DEFAULT_REMOTE_ADDON_TIMEOUT_MS}. */
     timeoutMs?: number;
     /** Extra headers for every call to the host. Cannot replace the auth, trace or contract headers. */

package/dist/wirings/agent/agent-finalize.d.ts

@@ -12,6 +12,8 @@ export type RunUsage = {
  * a scorer is shown is exactly what was stored — including the redactions.
  */
 export type FinalizedRun = {
+    /** The trace the run's scoring jobs stay in. */
+    traceparent?: string;
     runId: string;
     agentName: string;
     threadId: string;

package/dist/wirings/agent/agent-finalize.js

@@ -130,7 +130,7 @@ export const finalizeAgentRun = async (agentRunState, run) => {
     // Best-effort and last: the client already has its answer, so a grading
     // failure must not surface as a failed run.
     try {
-        await scoreFinishedRun(snapshot, services);
+        await scoreFinishedRun(snapshot, services, run.traceparent);
     }
     catch (error) {
         services.logger?.error(`[pikku] Live scoring failed for run ${run.runId}`, error);

package/dist/wirings/agent/agent-prepare.d.ts

@@ -1,8 +1,9 @@
 import type { CoreUserSession, GetCredential } from '../../types/core.types.js';
 import type { CoreAgent, AgentInput, AgentToolDef, AgentMessage, AgentStreamChannel, PikkuAgentMiddlewareHooks, SessionScope } from './agent.types.js';
-import type { AgentRunnerParams } from '../../services/agent-runner-service.js';
+import type { AgentRunnerParams, AgentRunnerService } from '../../services/agent-runner-service.js';
 import { PikkuError } from '../../errors/error-handler.js';
 import type { SessionService } from '../../services/user-session-service.js';
+import { type TraceContext } from '../../trace.js';
 /**
  * Per-request context for running an agent: the caller's session, credential access and, for
  * a sessionless request, the minted anonymous owner id.
@@ -13,6 +14,8 @@ export type RunAgentParams = {
     getCredential?: GetCredential;
     /** Ephemeral owner identity minted for a sessionless request; never client-supplied, never reused across requests. */
     anonymousOwnerResourceId?: string;
+    /** The caller's trace. Each tool call is a span in it. */
+    trace?: TraceContext;
 };
 export declare function resolveSessionPrincipal(params: RunAgentParams, sessionScope: SessionScope | undefined): string | undefined;
 export declare function resolveOwnerResourceId(params: RunAgentParams, sessionScope: SessionScope | undefined, requestedResourceId: string): string;
@@ -155,11 +158,18 @@ export declare function buildToolDefs(params: RunAgentParams, agentSessionMap: M
     tools: AgentToolDef[];
     missingRpcs: string[];
 }>;
+/**
+ * The singleton `agentRunner`, keyed with the caller's `AI_API_KEY` credential when one is set.
+ * Every entry that calls the model (run, stream, approve, resume) goes through this.
+ */
+export declare function resolveAgentRunner(singletonServices: {
+    agentRunner?: AgentRunnerService;
+}, params: RunAgentParams): Promise<AgentRunnerService>;
 export declare function prepareAgentRun(agentName: string, input: AgentInput, params: RunAgentParams, agentSessionMap: Map<string, string>, streamContext?: StreamContext): Promise<{
     agent: CoreAgent;
     packageName: string | null;
     resolvedName: string;
-    agentRunner: import("../../services/agent-runner-service.js").AgentRunnerService;
+    agentRunner: AgentRunnerService;
     storage: import("../../services/agent-storage-service.js").AgentStorageService | undefined;
     memoryConfig: import("./agent.types.js").AgentMemoryConfig | undefined;
     threadId: string;

package/dist/wirings/agent/agent-prepare.js

@@ -11,6 +11,7 @@ import { resolveNamespace, ContextAwareRPCService, } from '../../wirings/rpc/rpc
 import { getOrCreatePackageSingletonServices } from '../../wirings/addon/addon-runner.js';
 import { resolveMemoryServices, loadContextMessages, trimMessages, } from './agent-memory.js';
 import { resolveModelConfig } from './agent-model-config.js';
+import { childTraceWire, createTrace, outgoingTraceparent, tracedLogger, } from '../../trace.js';
 export function resolveSessionPrincipal(params, sessionScope) {
     const session = params.sessionService?.get();
     if ((sessionScope ?? 'user') === 'org') {
@@ -321,6 +322,8 @@ export function buildSubAgentRunInput(message, threadId, resourceId, parentConte
 export async function buildToolDefs(params, agentSessionMap, resourceId, agentName, packageName, streamContext, agentMiddlewares, agentMode, parentContext) {
     const singletonServices = getSingletonServices();
     const tools = [];
+    // Every tool of a run sits under one trace, whoever started the run.
+    const trace = params.trace ?? createTrace();
     const missingRpcs = [];
     const approvalPolicy = streamContext?.options?.requiresToolApproval ?? 'explicit';
     const meta = pikkuState(packageName, 'agent', 'agentsMeta')[agentName];
@@ -442,9 +445,14 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                 approvalDescriptionFn,
                 readonly: fnMeta?.readonly || undefined,
                 execute: async (toolInput, options) => {
-                    const wire = params.sessionService
-                        ? { ...createMiddlewareSessionWireProps(params.sessionService) }
-                        : {};
+                    // The call below is the tool's span, under the run's.
+                    const wire = {
+                        traceId: trace.traceId,
+                        trace,
+                        ...(params.sessionService
+                            ? createMiddlewareSessionWireProps(params.sessionService)
+                            : {}),
+                    };
                     if (options?.abortScope)
                         wire.abortScope = options.abortScope;
                     const rpcService = new ContextAwareRPCService(singletonServices, wire, { sessionService: params.sessionService });
@@ -594,13 +602,21 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                     if (!workflowService) {
                         throw new Error(`workflowService is not configured — cannot run workflow tool '${workflowName}'`);
                     }
-                    const wire = params.sessionService
-                        ? { ...createMiddlewareSessionWireProps(params.sessionService) }
-                        : {};
+                    const wire = {
+                        ...childTraceWire(trace),
+                        ...(params.sessionService
+                            ? createMiddlewareSessionWireProps(params.sessionService)
+                            : {}),
+                    };
                     if (options?.abortScope)
                         wire.abortScope = options.abortScope;
                     const rpcService = new ContextAwareRPCService(singletonServices, wire, { sessionService: params.sessionService });
-                    return workflowService.runToCompletion(workflowName, toolInput, rpcService, { wire: { type: 'internal' } });
+                    return workflowService.runToCompletion(workflowName, toolInput, rpcService, {
+                        wire: {
+                            type: 'internal',
+                            traceparent: outgoingTraceparent(wire),
+                        },
+                    });
                 },
             });
         }
@@ -619,7 +635,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                         ...err.payload,
                     };
                 }
-                singletonServices.logger.error(`AI agent tool '${tool.name}' threw during execute()`, err);
+                tracedLogger(singletonServices.logger, trace.traceId).error(`AI agent tool '${tool.name}' threw during execute()`, err);
                 throw err;
             }
         };
@@ -679,20 +695,28 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
     }
     return { tools, missingRpcs };
 }
-export async function prepareAgentRun(agentName, input, params, agentSessionMap, streamContext) {
-    const singletonServices = getSingletonServices();
-    const { agent, packageName, resolvedName } = resolveAgent(agentName);
-    await assertAgentAuthorized(agent, params, packageName);
-    let agentRunner = singletonServices.agentRunner;
+/**
+ * The singleton `agentRunner`, keyed with the caller's `AI_API_KEY` credential when one is set.
+ * Every entry that calls the model (run, stream, approve, resume) goes through this.
+ */
+export async function resolveAgentRunner(singletonServices, params) {
+    const agentRunner = singletonServices.agentRunner;
     if (!agentRunner) {
         throw new AIProviderNotConfiguredError();
     }
     if (params.getCredential && agentRunner.withApiKey) {
         const aiCredential = await params.getCredential('AI_API_KEY');
         if (aiCredential?.apiKey?.trim()) {
-            agentRunner = agentRunner.withApiKey(aiCredential.apiKey);
+            return agentRunner.withApiKey(aiCredential.apiKey);
         }
     }
+    return agentRunner;
+}
+export async function prepareAgentRun(agentName, input, params, agentSessionMap, streamContext) {
+    const singletonServices = getSingletonServices();
+    const { agent, packageName, resolvedName } = resolveAgent(agentName);
+    await assertAgentAuthorized(agent, params, packageName);
+    const agentRunner = await resolveAgentRunner(singletonServices, params);
     const { storage } = resolveMemoryServices(agent, singletonServices);
     const memoryConfig = agent.memory;
     const threadId = input.threadId;

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

@@ -14,6 +14,7 @@ export const createAgentRPC = (wire, options) => {
     const params = () => ({
         sessionService: options.sessionService,
         getCredential: wire.getCredential?.bind(wire),
+        trace: wire.trace,
     });
     const streamingChannel = () => {
         const channel = wire.channel;
@@ -50,7 +51,7 @@ export const createAgentRPC = (wire, options) => {
             await resumeAgent({ runId, ...input }, wrapChannelWithAGUI(streamingChannel(), { runId }), params(), streamOptions);
         },
         interrupt: async (runId, reason) => interruptAgent({ runId, ...(reason ? { reason } : {}) }, { sessionService: options.sessionService }),
-        approve: async (runId, approvals, expectedAgentName) => asRunResult(await resumeAgentSync(runId, approvals, { sessionService: options.sessionService }, expectedAgentName === undefined
+        approve: async (runId, approvals, expectedAgentName) => asRunResult(await resumeAgentSync(runId, approvals, params(), expectedAgentName === undefined
             ? undefined
             : mapAddonCall(wire.addonNamespace, expectedAgentName))),
     };

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

@@ -1,5 +1,6 @@
+import { outgoingTraceparent } from '../../trace.js';
 import { saveMessages, resolveMemoryServices, loadContextMessages, trimMessages, getWorkingMemoryMiddleware, } from './agent-memory.js';
-import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, resolveOwnerResourceId, agentSessionScope, assertResourcePrincipalOwner, assertRunBelongsToAgent, assertAgentAuthorized, } from './agent-prepare.js';
+import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, resolveOwnerResourceId, agentSessionScope, assertResourcePrincipalOwner, assertRunBelongsToAgent, assertAgentAuthorized, resolveAgentRunner, } from './agent-prepare.js';
 import { checkForApprovals, appendStepMessages } from './agent-stream.js';
 import { AgentInterruptedError, isAbortError, persistOrphanedToolResults, registerInterruptibleRun, trackInterruptNote, trackToolExecution, } from './agent-interrupt.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
@@ -7,7 +8,6 @@ import { applyInputMiddleware, describeApprovals, notifyAfterStep, toAccumulated
 import { applyOutputMiddleware, finalizeAgentRun, lastUserMessageText, } from './agent-finalize.js';
 import { resolveModelConfig } from './agent-model-config.js';
 import { validateAgentOutput } from './agent-output.js';
-import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { deniedToolResult, randomUUID } from './agent-utils.js';
 function stripNulls(obj) {
     if (obj === null)
@@ -225,6 +225,7 @@ export async function runAgent(agentName, input, params, agentSessionMap) {
             uiSpec: structuredOutput.uiSpec,
         });
         await finalizeAgentRun(agentRunState, {
+            traceparent: outgoingTraceparent({ trace: params.trace }),
             runId,
             agentName,
             threadId,
@@ -308,10 +309,7 @@ export async function resumeAgentSync(runId, approvals, params, expectedAgentNam
     await assertAgentAuthorized(agent, params, packageName);
     const { storage } = resolveMemoryServices(agent, singletonServices);
     const memoryConfig = agent.memory;
-    const agentRunner = singletonServices.agentRunner;
-    if (!agentRunner) {
-        throw new AIProviderNotConfiguredError();
-    }
+    const agentRunner = await resolveAgentRunner(singletonServices, params);
     const approvedIds = new Set(approvals.filter((a) => a.approved).map((a) => a.toolCallId));
     const rejectedIds = new Set(approvals.filter((a) => !a.approved).map((a) => a.toolCallId));
     const savedPendingApprovals = [...(run.pendingApprovals ?? [])];
@@ -561,6 +559,7 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
             steps: accumulatedSteps,
         });
         await finalizeAgentRun(agentRunState, {
+            traceparent: outgoingTraceparent({ trace: params.trace }),
             runId: run.runId,
             agentName: resolvedName,
             threadId: run.threadId,