@foldrun/core 2.4.0 → 2.5.0

package/dist/src/operator.d.ts

@@ -19,7 +19,42 @@ export type OperatorEvent = {
     text: string;
     by?: string | null;
     at: string;
+}
+/** A colleague running beside this step sent it a message (tools: [peers]). */
+ | {
+    kind: "peer";
+    from: string;
+    text: string;
+    at: string;
+}
+/** This step sent a colleague a message. `to` is the agents it reached. */
+ | {
+    kind: "told";
+    to: string[];
+    text: string;
+    at: string;
 };
+/** A step running in the same parallel group, as its siblings see it. */
+export interface PeerInfo {
+    /** The sibling's agent name — what `peers_message` is addressed to. */
+    agent: string;
+    /** Its index in run.steps: which inbox a message to it goes to. */
+    step: number;
+    /** The first line of its instruction, so a sibling knows what it is on. */
+    instruction: string;
+}
+/** A sibling's address: `agent#step`, the step as the flow numbers it
+ *  (1-based). A fan-out's instances share an agent name, so the bare name
+ *  reaches every instance and the address reaches one. */
+export declare const peerAddress: (p: {
+    agent: string;
+    step: number;
+}) => string;
+/** Does `to` name this sibling? `all`, its agent name, or its address. */
+export declare const peerMatches: (p: PeerInfo, to: string) => boolean;
+/** `by` on an inbox message from a colleague, not a person: `peer:<address>`. */
+export declare const PEER_BY_PREFIX = "peer:";
+export declare const peerOf: (by: string | null | undefined) => string | null;
 export interface OperatorMessage {
     text: string;
     by?: string | null;
@@ -40,6 +75,15 @@ export interface OperatorChannel {
     /** Nobody will read this question's answer now (the wait timed out):
      *  stop offering it to people. Best effort; optional for fakes. */
     close?(id: string): Promise<void>;
+    /** tools: [peers] — the siblings this step may message, as the lease
+     *  carries them; empty when the step runs alone. Optional: an older
+     *  proxy, or a fake, has no colleagues to offer. */
+    peers?(): Promise<PeerInfo[]>;
+    /** Leave `text` in the inbox of the sibling named `to` (or of every
+     *  sibling, `"all"`). Resolves with the agents it reached. */
+    tell?(to: string, text: string): Promise<{
+        to: string[];
+    }>;
 }
 export declare const QUESTION_MAX = 2000;
 export declare const OPTION_MAX = 200;
@@ -57,6 +101,21 @@ export declare function operatorEndpoint(egress: string | undefined | null): {
 } | null;
 /** The channel over the egress proxy. `fetchImpl` is for tests. */
 export declare function httpChannel(egress: string | undefined | null, fetchImpl?: typeof fetch): OperatorChannel | null;
+/**
+ * The colleagues' line for steps that run in this process (`foldrun run`
+ * on a laptop, a host without a proxy): one bus per run, an inbox per step,
+ * the same shape the proxy serves. A person has no door here — nobody can
+ * write in from outside — but siblings can still reach each other.
+ */
+export declare function localPeerBus(): {
+    /** The step is over (however it ended): nobody can reach it now. */
+    leave(step: number): void;
+    /** The channel for one step: who its siblings are, and its own inbox. */
+    channelFor(self: {
+        agent: string;
+        step: number;
+    }, siblings: PeerInfo[]): OperatorChannel;
+};
 /** `ask: {timeout: 2h}` in an agent's frontmatter → seconds, clamped. */
 export declare function askTimeoutSec(front: Record<string, unknown>): number;
 /** "90s", "30m", "2h", "1d" or a number of seconds; null when unreadable. */
@@ -179,6 +238,224 @@ export declare function buildAskTool(opts: {
 };
 /** The granted name of the tool — the same on every path. */
 export declare const ASK_TOOL = "mcp__foldrun_ask__ask_person";
+/** The granted names of the colleagues' tools — the same on every path. */
+export declare const PEER_TOOLS: string[];
+export declare const PEER_TEXT_MAX = 4000;
+/** The in-sandbox `peers_list` and `peers_message` tools (tools: [peers]).
+ *  `siblings` is what the runner knew at launch: the other steps of this
+ *  step's parallel group. The channel delivers; with none (no proxy and no
+ *  local bus) the tools say so rather than pretend. */
+export declare function buildPeerTools(opts: {
+    channel: OperatorChannel | null;
+    self: string;
+    siblings: PeerInfo[];
+    emit: Emit;
+    now?: () => number;
+}): {
+    server: import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;
+    /** The tools' own functions, for tests. */
+    list: () => Promise<{
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        content: ({
+            type: "text";
+            text: string;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            type: "image";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            type: "audio";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            uri: string;
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            size?: number | undefined;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "dark" | "light" | undefined;
+            }[] | undefined;
+            name: string;
+            title?: string | undefined;
+            type: "resource_link";
+        } | {
+            type: "resource";
+            resource: {
+                uri: string;
+                mimeType?: string | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                text: string;
+            } | {
+                uri: string;
+                mimeType?: string | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                blob: string;
+            };
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        })[];
+        structuredContent?: {
+            [x: string]: unknown;
+        } | undefined;
+        isError?: boolean | undefined;
+    }>;
+    message: (args: {
+        to: string;
+        text: string;
+    }) => Promise<{
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        content: ({
+            type: "text";
+            text: string;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            type: "image";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            type: "audio";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            uri: string;
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            size?: number | undefined;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "dark" | "light" | undefined;
+            }[] | undefined;
+            name: string;
+            title?: string | undefined;
+            type: "resource_link";
+        } | {
+            type: "resource";
+            resource: {
+                uri: string;
+                mimeType?: string | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                text: string;
+            } | {
+                uri: string;
+                mimeType?: string | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                blob: string;
+            };
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        })[];
+        structuredContent?: {
+            [x: string]: unknown;
+        } | undefined;
+        isError?: boolean | undefined;
+    }>;
+    toolNames: string[];
+    promptLines: string[];
+};
+/** The line the system prompt gets for tools: [peers]. */
+export declare function peersPromptLine(siblings: PeerInfo[]): string;
 /** The line the system prompt gets for it. */
 export declare function askPromptLine(timeoutSec: number): string;
 /** Reads the run's inbox after tool calls and turns messages into context

package/dist/src/operator.js

@@ -20,8 +20,34 @@
 //
 // Both leave a trace event with an `operator` field, which the runner turns
 // into step.questions / step.messages on the record.
+//
+// And a third line, between colleagues (20 Oct 2026):
+//
+//   tools: [peers]  the agent gets `peers_list` and `peers_message` — who
+//                   else is running in its parallel group right now, and a
+//                   message to one of them (or all). It lands in the
+//                   sibling's own inbox, so it reaches that model after its
+//                   next tool call, the same door a person's message uses,
+//                   and the sender hears any reply the same way. A step that
+//                   finds mid-way that it needs something a sibling has —
+//                   a file name, a decision, a number — asks for it instead
+//                   of guessing or failing. Nothing waits: the step goes on
+//                   and the answer, if one comes, arrives as context.
+//
+// Peer messages travel the person's inbox with `by` set to `peer:<agent>`,
+// so the reader can tell a colleague from a person without a second store
+// or a second door on the proxy.
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { z } from "zod";
+/** A sibling's address: `agent#step`, the step as the flow numbers it
+ *  (1-based). A fan-out's instances share an agent name, so the bare name
+ *  reaches every instance and the address reaches one. */
+export const peerAddress = (p) => `${p.agent}#${p.step + 1}`;
+/** Does `to` name this sibling? `all`, its agent name, or its address. */
+export const peerMatches = (p, to) => to === "all" || to === p.agent || to === peerAddress(p);
+/** `by` on an inbox message from a colleague, not a person: `peer:<address>`. */
+export const PEER_BY_PREFIX = "peer:";
+export const peerOf = (by) => typeof by === "string" && by.startsWith(PEER_BY_PREFIX) ? by.slice(PEER_BY_PREFIX.length) : null;
 export const QUESTION_MAX = 2_000;
 export const OPTION_MAX = 200;
 export const OPTIONS_MAX = 10;
@@ -76,6 +102,68 @@ export function httpChannel(egress, fetchImpl = fetch) {
                 signal: AbortSignal.timeout(5_000),
             }));
         },
+        async peers() {
+            const body = await json(await fetchImpl(`${ep.base}/peers/${ep.token}`, { signal: AbortSignal.timeout(5_000) }));
+            return Array.isArray(body.peers) ? body.peers : [];
+        },
+        async tell(to, text) {
+            const body = await json(await fetchImpl(`${ep.base}/peers/${ep.token}/message`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ to, text }),
+                signal: AbortSignal.timeout(10_000),
+            }));
+            return { to: Array.isArray(body.to) ? body.to : [] };
+        },
+    };
+}
+/**
+ * The colleagues' line for steps that run in this process (`foldrun run`
+ * on a laptop, a host without a proxy): one bus per run, an inbox per step,
+ * the same shape the proxy serves. A person has no door here — nobody can
+ * write in from outside — but siblings can still reach each other.
+ */
+export function localPeerBus() {
+    const inboxes = new Map();
+    /** Steps that have ended: off every roster, and a message to one reaches
+     *  nobody — it would never be read. */
+    const gone = new Set();
+    const live = (siblings) => siblings.filter((p) => !gone.has(p.step));
+    return {
+        /** The step is over (however it ended): nobody can reach it now. */
+        leave(step) {
+            gone.add(step);
+            inboxes.delete(step);
+        },
+        /** The channel for one step: who its siblings are, and its own inbox. */
+        channelFor(self, siblings) {
+            return {
+                async ask() {
+                    throw new Error("nobody can answer here");
+                },
+                async poll() {
+                    return null;
+                },
+                async inbox() {
+                    const mine = inboxes.get(self.step) ?? [];
+                    inboxes.delete(self.step);
+                    return mine;
+                },
+                async peers() {
+                    return live(siblings);
+                },
+                async tell(to, text) {
+                    const targets = live(siblings).filter((p) => peerMatches(p, to));
+                    const at = new Date().toISOString();
+                    for (const p of targets) {
+                        const list = inboxes.get(p.step) ?? [];
+                        list.push({ text: text.slice(0, MESSAGE_MAX), by: PEER_BY_PREFIX + peerAddress(self), at });
+                        inboxes.set(p.step, list.slice(-50));
+                    }
+                    return { to: targets.map(peerAddress) };
+                },
+            };
+        },
     };
 }
 /** `ask: {timeout: 2h}` in an agent's frontmatter → seconds, clamped. */
@@ -167,6 +255,71 @@ export function buildAskTool(opts) {
 }
 /** The granted name of the tool — the same on every path. */
 export const ASK_TOOL = "mcp__foldrun_ask__ask_person";
+/** The granted names of the colleagues' tools — the same on every path. */
+export const PEER_TOOLS = ["mcp__foldrun_peers__peers_list", "mcp__foldrun_peers__peers_message"];
+export const PEER_TEXT_MAX = MESSAGE_MAX;
+/** The in-sandbox `peers_list` and `peers_message` tools (tools: [peers]).
+ *  `siblings` is what the runner knew at launch: the other steps of this
+ *  step's parallel group. The channel delivers; with none (no proxy and no
+ *  local bus) the tools say so rather than pretend. */
+export function buildPeerTools(opts) {
+    const text = (t) => ({ content: [{ type: "text", text: t }] });
+    const roster = () => opts.siblings.length
+        ? opts.siblings.map((p) => `- ${peerAddress(p)}: ${p.instruction}`).join("\n")
+        : "Nobody: this step runs alone in its group.";
+    const list = tool("peers_list", "Who else is running beside you right now — the other steps of your parallel group, each as agent#step with what it is doing. Message one with peers_message, addressed as agent#step (or the bare agent name, which reaches every instance of that agent).", {}, async () => {
+        let peers = opts.siblings;
+        try {
+            peers = (await opts.channel?.peers?.()) ?? opts.siblings;
+        }
+        catch {
+            /* the launch-time roster stands */
+        }
+        opts.siblings = peers;
+        return text(`Running beside you in this group:\n${roster()}`);
+    });
+    const message = tool("peers_message", "Send a short message to a colleague running beside you in this parallel group — to ask for something it has (a file name, a figure, a decision) or to tell it something it needs. It reaches that agent after its next tool call; any reply reaches you the same way, after your next tool call, so carry on working and check what arrives. Not a way to hand over your work.", {
+        to: z.string().describe("The colleague's address from peers_list (agent#step), its bare agent name (every instance of it), or \"all\" for every sibling"),
+        text: z.string().describe("The complete message — the colleague has not read your context; say who you are, what you need and where to put it"),
+    }, async ({ to, text: body }) => {
+        const target = String(to).trim();
+        const msg = String(body).trim().slice(0, PEER_TEXT_MAX);
+        if (!target || !msg)
+            return { ...text("peers_message needs `to` and `text`."), isError: true };
+        if (!opts.siblings.some((p) => peerMatches(p, target))) {
+            return { ...text(`No colleague named "${target}" runs beside you. ${roster()}`), isError: true };
+        }
+        if (!opts.channel?.tell)
+            return { ...text("No line to colleagues here (no proxy): the message was not delivered."), isError: true };
+        let reached;
+        try {
+            ({ to: reached } = await opts.channel.tell(target, msg));
+        }
+        catch (err) {
+            return { ...text(`Could not deliver: ${err instanceof Error ? err.message : String(err)}`), isError: true };
+        }
+        const at = new Date(opts.now?.() ?? Date.now()).toISOString();
+        opts.emit("info", `told ${reached.join(", ") || "nobody"}: ${msg}`, { operator: { kind: "told", to: reached, text: msg, at } });
+        if (!reached.length)
+            return text(`Nobody received it: "${target}" is not running beside you now.`);
+        return text(`Delivered to ${reached.join(", ")}. It reaches them after their next tool call; a reply reaches you after yours.`);
+    });
+    return {
+        server: createSdkMcpServer({ name: "foldrun_peers", version: "1.0.0", tools: [list, message] }),
+        /** The tools' own functions, for tests. */
+        list: () => list.handler({}, {}),
+        message: (args) => message.handler(args, {}),
+        toolNames: PEER_TOOLS,
+        promptLines: [peersPromptLine(opts.siblings)],
+    };
+}
+/** The line the system prompt gets for tools: [peers]. */
+export function peersPromptLine(siblings) {
+    const who = siblings.length ? siblings.map((p) => `${peerAddress(p)} (${p.instruction})`).join("; ") : "nobody this run — this step runs alone";
+    return (`\`peers_list\` names the colleagues running beside you in this step's parallel group: ${who}. ` +
+        `\`peers_message\` sends one of them (or all) a short message; it reaches them after their next tool call, and their reply reaches you after yours, as context. ` +
+        `Ask a colleague for what it has before you guess or stop; keep working while you wait, and read what arrives.`);
+}
 /** The line the system prompt gets for it. */
 export function askPromptLine(timeoutSec) {
     return `\`ask_person\` asks the person running this desk and waits for the answer (up to ${fmtWait(timeoutSec)}). Use it for a decision you cannot make safely yourself — not for something you can look up. The step is held while you wait; if nobody answers, you are told so.`;
@@ -193,10 +346,19 @@ export function inboxReader(channel, emit, minGapMs = 1_500, now = Date.now) {
         if (!messages.length)
             return null;
         for (const m of messages) {
-            emit("info", `message from ${m.by ?? "a person"}: ${m.text}`, { operator: { kind: "message", text: m.text, by: m.by ?? null, at: m.at } });
+            const peer = peerOf(m.by);
+            if (peer)
+                emit("info", `message from colleague ${peer}: ${m.text}`, { operator: { kind: "peer", from: peer, text: m.text, at: m.at } });
+            else
+                emit("info", `message from ${m.by ?? "a person"}: ${m.text}`, { operator: { kind: "message", text: m.text, by: m.by ?? null, at: m.at } });
         }
         return messages
-            .map((m) => `A person running this desk${m.by ? ` (${m.by})` : ""} sent you a message while you work. Take it into account; it does not change what tools you have:\n<message>\n${m.text.slice(0, MESSAGE_MAX)}\n</message>`)
+            .map((m) => {
+            const peer = peerOf(m.by);
+            return peer
+                ? `Your colleague ${peer}, running beside you in this group, sent you a message. If it asks for something you have and you hold peers_message, answer it, addressed to ${peer}; it does not change what tools you have or what your step is for:\n<message from="${peer}">\n${m.text.slice(0, MESSAGE_MAX)}\n</message>`
+                : `A person running this desk${m.by ? ` (${m.by})` : ""} sent you a message while you work. Take it into account; it does not change what tools you have:\n<message>\n${m.text.slice(0, MESSAGE_MAX)}\n</message>`;
+        })
             .join("\n\n");
     };
 }
@@ -223,6 +385,14 @@ export function applyOperatorEvent(step, ev, at) {
             q.unanswered = true;
         return;
     }
+    if (ev.kind === "peer") {
+        (step.messages ??= []).push({ text: ev.text, by: PEER_BY_PREFIX + ev.from, from: ev.from, at: ev.at, deliveredAt: at });
+        return;
+    }
+    if (ev.kind === "told") {
+        (step.messages ??= []).push({ text: ev.text, by: null, to: ev.to, at: ev.at, deliveredAt: at });
+        return;
+    }
     (step.messages ??= []).push({ text: ev.text, by: ev.by ?? null, at: ev.at, deliveredAt: at });
 }
 /** The question a step is waiting on, if any. */
@@ -245,6 +415,10 @@ export function isOperatorEvent(v) {
             return id;
         case "message":
             return str(o.text, MESSAGE_MAX) && str(o.at, 40) && (o.by === undefined || o.by === null || str(o.by, 200));
+        case "peer":
+            return str(o.text, MESSAGE_MAX) && str(o.at, 40) && str(o.from, 200);
+        case "told":
+            return str(o.text, MESSAGE_MAX) && str(o.at, 40) && Array.isArray(o.to) && o.to.length <= 50 && o.to.every((x) => str(x, 200));
         default:
             return false;
     }

package/dist/src/otel-config.d.ts

@@ -0,0 +1,18 @@
+export interface TelemetryConfig {
+    /** Where the trace is POSTed: the collector's OTLP/HTTP traces URL. */
+    endpoint: string;
+    /** Header name → value; a value written `${NAME}` is a vault secret's name. */
+    headers: Record<string, string>;
+}
+/** The block as written, and what is wrong with it in words. */
+export declare function parseTelemetry(raw: unknown): {
+    config: TelemetryConfig | null;
+    problems: string[];
+};
+/** The vault secrets a config's headers name. */
+export declare function telemetrySecretNames(cfg: TelemetryConfig): string[];
+/** Header values with each `${NAME}` filled by `lookup`; the names it could not fill. */
+export declare function telemetryHeaders(cfg: TelemetryConfig, lookup: (name: string) => string | null): {
+    headers: Record<string, string>;
+    missing: string[];
+};

package/dist/src/otel-config.js

@@ -0,0 +1,69 @@
+// `telemetry:` as written in AGENTS.md — read, checked and its header
+// secrets filled. No node imports: the dashboard's settings form reads it
+// in the browser. The trace itself is otel.ts.
+const SECRET_REF = /^\$\{([A-Z][A-Z0-9_]{1,63})\}$/;
+const HEADER_NAME = /^[A-Za-z0-9-]{1,64}$/;
+/** The block as written, and what is wrong with it in words. */
+export function parseTelemetry(raw) {
+    if (raw === undefined || raw === null)
+        return { config: null, problems: [] };
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        return { config: null, problems: ["telemetry: is a block — otlp: <https URL of the collector's /v1/traces>, and headers:"] };
+    }
+    const o = raw;
+    const problems = [];
+    for (const k of Object.keys(o))
+        if (k !== "otlp" && k !== "headers")
+            problems.push(`telemetry: ${k} — not a key; the keys are otlp and headers`);
+    const endpoint = typeof o.otlp === "string" ? o.otlp.trim() : "";
+    let url = null;
+    try {
+        url = endpoint ? new URL(endpoint) : null;
+    }
+    catch {
+        url = null;
+    }
+    if (!url || url.protocol !== "https:")
+        problems.push(`telemetry: otlp ${endpoint || "(missing)"} — an https:// URL, the collector's OTLP/HTTP traces endpoint (…/v1/traces)`);
+    const headers = {};
+    if (o.headers !== undefined) {
+        if (!o.headers || typeof o.headers !== "object" || Array.isArray(o.headers))
+            problems.push("telemetry: headers is a block of name: value");
+        else {
+            for (const [name, value] of Object.entries(o.headers)) {
+                if (!HEADER_NAME.test(name))
+                    problems.push(`telemetry: header "${name}" — letters, digits and dashes`);
+                else if (typeof value !== "string" || !value.trim())
+                    problems.push(`telemetry: header ${name} — a value, or \${SECRET_NAME} for one in the vault`);
+                else if (!SECRET_REF.test(value.trim()) && /token|key|secret|auth/i.test(name)) {
+                    problems.push(`telemetry: header ${name} is written into the file — put it in the vault (foldrun secrets set NAME) and write \${NAME}`);
+                }
+                else
+                    headers[name.toLowerCase()] = value.trim();
+            }
+        }
+    }
+    return { config: problems.length ? null : { endpoint, headers }, problems };
+}
+/** The vault secrets a config's headers name. */
+export function telemetrySecretNames(cfg) {
+    return Object.values(cfg.headers).map((v) => SECRET_REF.exec(v)?.[1]).filter((n) => !!n);
+}
+/** Header values with each `${NAME}` filled by `lookup`; the names it could not fill. */
+export function telemetryHeaders(cfg, lookup) {
+    const headers = {};
+    const missing = [];
+    for (const [k, v] of Object.entries(cfg.headers)) {
+        const ref = SECRET_REF.exec(v)?.[1];
+        if (!ref)
+            headers[k] = v;
+        else {
+            const value = lookup(ref);
+            if (value === null)
+                missing.push(ref);
+            else
+                headers[k] = value;
+        }
+    }
+    return { headers, missing };
+}

package/dist/src/otel.d.ts

@@ -0,0 +1,38 @@
+import type { RunRecord } from "./store.ts";
+export { parseTelemetry, telemetrySecretNames, telemetryHeaders, type TelemetryConfig } from "./otel-config.ts";
+type AttrValue = {
+    stringValue: string;
+} | {
+    intValue: string;
+} | {
+    doubleValue: number;
+} | {
+    boolValue: boolean;
+};
+type Attr = {
+    key: string;
+    value: AttrValue;
+};
+export interface TraceContext {
+    tenant: string;
+    workspace: string;
+    /** Agent name → its owner (owner: …), stamped on its step spans. */
+    owners?: Record<string, string | null>;
+    /** The platform version, as the instrumentation scope's. */
+    version?: string;
+}
+/** The ExportTraceServiceRequest for one run. */
+export declare function runToOtlp(run: RunRecord, ctx: TraceContext, now?: number): {
+    resourceSpans: {
+        resource: {
+            attributes: Attr[];
+        };
+        scopeSpans: {
+            scope: {
+                name: string;
+                version?: string | undefined;
+            };
+            spans: unknown[];
+        }[];
+    }[];
+};