@gr8ful/spf 0.17.0 → 0.19.0

package/dist/core/agents.d.ts

@@ -146,6 +146,12 @@ interface RunForAgents {
         envelopeRow: (phase: Phase, agent: string, outputType: string, payloadJson: string, valid: boolean, attempt: number) => Promise<void>;
         gateRow: (phase: Phase, gate: string, report: GateReport, attempt: number) => Promise<void>;
         agentSessionRow: (adwId: string, agent: AgentConfig, sessionId: string, contextTokens?: number, contextWindow?: number) => Promise<void>;
+        otel?: {
+            agentCallTraceContext: (phaseId: string, agentName: string) => {
+                traceparent: string;
+                spanId: string;
+            } | null;
+        } | null;
     };
     console: {
         agentStarted: (name: string, model: string, sessionId: string) => Promise<void>;

package/dist/core/agents.js

@@ -808,6 +808,19 @@ export async function execute(run, phase, call) {
         // WHOLE run rather than on the first call of each phase. See
         // `assertRunBudget` for why it is checked before, not after.
         assertRunBudget(run);
+        // Outbound OTel propagation (SPF's otel-sdk extension): the CURRENTLY
+        // OPEN agent-call span's own trace context, when one exists — `null`
+        // whenever `observability.otel` is unconfigured for this run (the
+        // common case, and byte-identical to before this field existed) or the
+        // exporter has no agent call open (shouldn't happen here — agent_start
+        // fires before `send()` is ever reached — but a `null` is a silent
+        // no-op either way, never an error). `otelBlock` threads the SAME
+        // endpoint/headers/service_name through so `agent_flue.ts` can install
+        // its own (separate, process-scoped) http/undici propagation without
+        // needing the whole `SFConfig` — see `data_types.ts`'s `AgentRequest.
+        // otel` doc comment.
+        const otelBlock = run.cfg.observability.otel;
+        const otelCtx = otelBlock ? (run.tracer.otel?.agentCallTraceContext(phase.phase_id, agent.name) ?? null) : null;
         const request = {
             prompt: promptText,
             system_prompt: systemText,
@@ -822,6 +835,15 @@ export async function execute(run, phase, call) {
             flue_db_path: path.join(run.data_dir, "flue.db"),
             env: agentEnv(agent),
             sandbox: spec,
+            otel: otelCtx && otelBlock
+                ? {
+                    traceparent: otelCtx.traceparent,
+                    x_request_id: otelCtx.spanId,
+                    endpoint: otelBlock.endpoint,
+                    headers: otelBlock.headers,
+                    service_name: otelBlock.service_name,
+                }
+                : undefined,
         };
         const forward = eventForwarder(run, phase, agent.name, agent.coding_agent);
         // Best-effort, fire-and-forget: these fire from a plain process-lifecycle

package/dist/core/data_types.d.ts

@@ -685,6 +685,7 @@ export declare const AgentConfigSchema: v.ObjectSchema<{
     readonly writes: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
     readonly env_allowlist: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
     readonly sandbox: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["local", "opensandbox", "cloudflare"], undefined>, undefined>, undefined>;
+    readonly lora_adapter: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
 }, undefined>;
 export type AgentConfig = v.InferOutput<typeof AgentConfigSchema>;
 export declare const ConfigDefaultsSchema: v.ObjectSchema<{
@@ -756,13 +757,45 @@ export type ConfigDefaults = v.InferOutput<typeof ConfigDefaultsSchema>;
  * (`https://collector:4318/v1/traces`) or a bare origin (`/v1/traces` is
  * appended — see `resolveTracesUrl`). `headers` is where a collector's auth
  * token goes; its VALUES are treated as secrets and never logged.
+ *
+ * `metrics` (default `true`) additionally gates `otel_metrics.ts`'s
+ * process-scoped meter — set `false` to keep trace export on while opting
+ * out of the metrics pipeline entirely. It has no effect on activation
+ * either way: `endpoint`'s presence is still the sole switch for BOTH
+ * signals, this field only narrows what a configured block sends.
+ *
+ * `allow_env` (default `false`) is a narrow, opt-in exception to EXPLICIT
+ * CONFIG ONLY (see `core/otel.ts`'s header): when `true` AND this block is
+ * ALREADY active (`endpoint` set here, in the file), the standard
+ * `OTEL_EXPORTER_OTLP_ENDPOINT`/`OTEL_EXPORTER_OTLP_HEADERS` env vars may
+ * SUPPLEMENT it — e.g. a CI-injected collector token added to `headers`
+ * without checking it into the repo. It can NEVER activate export from
+ * nothing (there is no `endpoint` to fall back to when this block is absent
+ * at all — that case is unaffected by this flag either way) and a
+ * config-declared value always wins over the env on conflict. Defaults to
+ * `false` because this is still a deliberate loosening of an adversarially-
+ * reviewed, test-pinned invariant — an operator opts in per-repo.
  */
 export declare const OTelConfigSchema: v.ObjectSchema<{
     readonly endpoint: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>;
     readonly headers: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
     readonly service_name: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
+    readonly metrics: v.OptionalSchema<v.BooleanSchema<undefined>, true>;
+    readonly allow_env: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
 }, undefined>;
 export type OTelConfig = v.InferOutput<typeof OTelConfigSchema>;
+/**
+ * `allow_env`'s narrow env-supplement path (see `OTelConfigSchema`'s doc
+ * comment above): called ONLY when `cfg.observability.otel` already exists
+ * with a real `endpoint` — this function never activates anything on its
+ * own and is never called when the block is absent. `OTEL_EXPORTER_OTLP_
+ * HEADERS` follows the OTel spec's env-var shape (comma-separated
+ * `key=value` pairs, URL-decoded); config-declared headers win over the env
+ * on a key collision. `OTEL_EXPORTER_OTLP_ENDPOINT`, when set, overrides
+ * `endpoint` itself — the one field this can change, since a CI runner
+ * commonly injects a different collector per job/environment.
+ */
+export declare function applyOtelEnvSupplement(otel: OTelConfig, env?: NodeJS.ProcessEnv): OTelConfig;
 /**
  * MIGRATION NOTE (BT-issue #66, 3 PRs): `observability.db` used to be ONLY a
  * bare string (a local sqlite path, defaulting to ".spf/data/spf.db"). This
@@ -868,6 +901,8 @@ export declare const ObservabilityConfigSchema: v.ObjectSchema<{
         readonly endpoint: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>;
         readonly headers: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
         readonly service_name: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
+        readonly metrics: v.OptionalSchema<v.BooleanSchema<undefined>, true>;
+        readonly allow_env: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
     }, undefined>, undefined>;
 }, undefined>;
 export type ObservabilityConfig = v.InferOutput<typeof ObservabilityConfigSchema>;
@@ -1525,6 +1560,8 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             readonly endpoint: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>;
             readonly headers: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
             readonly service_name: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
+            readonly metrics: v.OptionalSchema<v.BooleanSchema<undefined>, true>;
+            readonly allow_env: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
         }, undefined>, undefined>;
     }, undefined>, () => {
         db: string | {
@@ -1543,6 +1580,8 @@ export declare const SFConfigSchema: v.ObjectSchema<{
                 [x: string]: string;
             } | undefined;
             service_name: string;
+            metrics: boolean;
+            allow_env: boolean;
         } | undefined;
     }>;
     readonly agents: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
@@ -1561,6 +1600,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         readonly writes: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
         readonly env_allowlist: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
         readonly sandbox: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["local", "opensandbox", "cloudflare"], undefined>, undefined>, undefined>;
+        readonly lora_adapter: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     }, undefined>, undefined>, () => never[]>;
     readonly quality: v.OptionalSchema<v.ObjectSchema<{
         readonly checks: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
@@ -1974,6 +2014,26 @@ export interface AgentRequest {
     env?: Record<string, string>;
     /** Absent (the default) => local(), byte-identical to before this field existed. See sandbox.ts. */
     sandbox?: SandboxSpec;
+    /**
+     * Outbound OTel trace-context propagation — set by `agents.ts`'s `send()`
+     * from `otel.ts`'s `OtelExporter.agentCallTraceContext()` ONLY when
+     * `observability.otel` is configured for this run; absent otherwise, and
+     * every backend that ignores it (`opencode` today) is byte-identical to
+     * before this field existed. `traceparent`/`x_request_id` are this call's
+     * own span context (`agent_cc.ts`'s single `spawn()` choke point turns
+     * them into `TRACEPARENT`/`ANTHROPIC_CUSTOM_HEADERS`); `endpoint`/
+     * `headers`/`service_name` are the SAME `observability.otel` block,
+     * carried through so `agent_flue.ts` can install its own (separate,
+     * process-scoped — see `otel_propagation.ts`) global http/undici
+     * propagation without needing the full `SFConfig`.
+     */
+    otel?: {
+        traceparent: string;
+        x_request_id: string;
+        endpoint: string;
+        headers?: Record<string, string>;
+        service_name: string;
+    };
 }
 /**
  * Tokens and the dollars they cost, per component, summed over a call.

package/dist/core/data_types.js

@@ -508,6 +508,13 @@ export const AgentConfigSchema = v.object({
     //   "local" -> force local for this agent
     //   null    -> same as unset (the writes/env_allowlist spelling)
     sandbox: v.optional(v.nullable(SandboxBackendSchema)),
+    // Explicit override for `otel.ts`'s `spf.lora_adapter` span attribute —
+    // the unambiguous source of truth when set. Unset (the common case) falls
+    // back to parsing `model` itself; see `loraAdapterFor()`'s own doc comment
+    // in `core/otel.ts` for the two zero-config conventions it recognizes.
+    // Purely descriptive: it does not change routing, dispatch, or which
+    // model actually serves the call — only what an OTel backend sees.
+    lora_adapter: v.optional(v.string()),
 });
 export const ConfigDefaultsSchema = v.object({
     coding_agent: v.optional(v.picklist(["flue", "claude_code", "opencode"]), "flue"),
@@ -581,12 +588,74 @@ export const ConfigDefaultsSchema = v.object({
  * (`https://collector:4318/v1/traces`) or a bare origin (`/v1/traces` is
  * appended — see `resolveTracesUrl`). `headers` is where a collector's auth
  * token goes; its VALUES are treated as secrets and never logged.
+ *
+ * `metrics` (default `true`) additionally gates `otel_metrics.ts`'s
+ * process-scoped meter — set `false` to keep trace export on while opting
+ * out of the metrics pipeline entirely. It has no effect on activation
+ * either way: `endpoint`'s presence is still the sole switch for BOTH
+ * signals, this field only narrows what a configured block sends.
+ *
+ * `allow_env` (default `false`) is a narrow, opt-in exception to EXPLICIT
+ * CONFIG ONLY (see `core/otel.ts`'s header): when `true` AND this block is
+ * ALREADY active (`endpoint` set here, in the file), the standard
+ * `OTEL_EXPORTER_OTLP_ENDPOINT`/`OTEL_EXPORTER_OTLP_HEADERS` env vars may
+ * SUPPLEMENT it — e.g. a CI-injected collector token added to `headers`
+ * without checking it into the repo. It can NEVER activate export from
+ * nothing (there is no `endpoint` to fall back to when this block is absent
+ * at all — that case is unaffected by this flag either way) and a
+ * config-declared value always wins over the env on conflict. Defaults to
+ * `false` because this is still a deliberate loosening of an adversarially-
+ * reviewed, test-pinned invariant — an operator opts in per-repo.
  */
 export const OTelConfigSchema = v.object({
     endpoint: v.pipe(v.string(), v.url()),
     headers: v.optional(v.record(v.string(), v.string()), undefined),
     service_name: v.optional(v.string(), "spf"),
+    metrics: v.optional(v.boolean(), true),
+    allow_env: v.optional(v.boolean(), false),
 });
+/**
+ * `allow_env`'s narrow env-supplement path (see `OTelConfigSchema`'s doc
+ * comment above): called ONLY when `cfg.observability.otel` already exists
+ * with a real `endpoint` — this function never activates anything on its
+ * own and is never called when the block is absent. `OTEL_EXPORTER_OTLP_
+ * HEADERS` follows the OTel spec's env-var shape (comma-separated
+ * `key=value` pairs, URL-decoded); config-declared headers win over the env
+ * on a key collision. `OTEL_EXPORTER_OTLP_ENDPOINT`, when set, overrides
+ * `endpoint` itself — the one field this can change, since a CI runner
+ * commonly injects a different collector per job/environment.
+ */
+export function applyOtelEnvSupplement(otel, env = process.env) {
+    if (!otel.allow_env)
+        return otel;
+    const envEndpoint = env["OTEL_EXPORTER_OTLP_ENDPOINT"];
+    const envHeadersRaw = env["OTEL_EXPORTER_OTLP_HEADERS"];
+    const envHeaders = {};
+    if (envHeadersRaw) {
+        for (const pair of envHeadersRaw.split(",")) {
+            const eq = pair.indexOf("=");
+            if (eq <= 0)
+                continue;
+            const key = pair.slice(0, eq).trim();
+            const value = pair.slice(eq + 1).trim();
+            if (key) {
+                try {
+                    envHeaders[key] = decodeURIComponent(value);
+                }
+                catch {
+                    envHeaders[key] = value;
+                }
+            }
+        }
+    }
+    if (!envEndpoint && Object.keys(envHeaders).length === 0)
+        return otel;
+    return {
+        ...otel,
+        endpoint: envEndpoint || otel.endpoint,
+        headers: { ...envHeaders, ...(otel.headers ?? {}) }, // config wins on conflict
+    };
+}
 /**
  * MIGRATION NOTE (BT-issue #66, 3 PRs): `observability.db` used to be ONLY a
  * bare string (a local sqlite path, defaulting to ".spf/data/spf.db"). This

package/dist/core/issues/jira_provider.d.ts

@@ -14,8 +14,13 @@
  *    now is `/rest/api/3/search/jql`.
  *  - Comment/description bodies in API v3 are Atlassian Document Format
  *    (ADF) JSON, not plain strings — `{"body": "text"}` is rejected
- *    outright. `toAdf`/`adfToText` are the minimal round-trip this needs:
- *    one paragraph of plain text, nothing richer.
+ *    outright. Human/LLM-authored content (`comment()`, `createIssue()`)
+ *    goes through `markdownToAdf()`/`adfToMarkdown()` (`./markdown_adf.ts`)
+ *    for real Jira formatting; the local `toAdf()` minimal round-trip (one
+ *    paragraph of plain text, nothing richer) survives ONLY for
+ *    `writeMarker()`'s hidden `[spf-watch-marker]` JSON payload, which must
+ *    never pass through a real Markdown parser — see `toAdf`'s own doc
+ *    comment.
  *
  * State is modeled as Jira labels (`<prefix>:ready`, etc.), mirroring
  * `github_provider.ts` exactly — labels are spf's ACTUAL state machine and

package/dist/core/issues/jira_provider.js

@@ -1,4 +1,5 @@
 import { fetchRetryTransient } from "../utils.js";
+import { adfToMarkdown, markdownToAdf } from "./markdown_adf.js";
 const STATES = [
     "ready",
     "working",
@@ -27,6 +28,19 @@ const STATES = [
  * here because nothing follows the JSON in this format at all.
  */
 const MARKER_RE = /\[spf-watch-marker\]\s*(\{.*\})/s;
+/**
+ * The ONLY remaining caller is `writeMarker()`'s hidden `[spf-watch-marker]`
+ * JSON payload — deliberately kept as this minimal, un-parsed shape (see
+ * this file's module comment) rather than routed through
+ * `markdownToAdf()`, because that payload must round-trip byte-for-byte
+ * through `MARKER_RE` and must never have its JSON characters (underscores,
+ * brackets, backticks) reinterpreted as Markdown syntax. Do not change this
+ * call site or add other callers — human/LLM-authored content
+ * (`comment()`, `createIssue()`) goes through `markdownToAdf()` instead, and
+ * reading ADF back to text goes through `adfToMarkdown()` (both imported
+ * from `./markdown_adf.ts`) — there is exactly one ADF-to-text
+ * implementation in this codebase now, not two divergent ones.
+ */
 function toAdf(text) {
     return {
         type: "doc",
@@ -34,17 +48,6 @@ function toAdf(text) {
         content: [{ type: "paragraph", content: [{ type: "text", text }] }],
     };
 }
-/** Walks an ADF document's `text` nodes and joins them — the minimal inverse of `toAdf`, not a full ADF renderer. */
-function adfToText(adf) {
-    if (!adf || typeof adf !== "object")
-        return "";
-    const node = adf;
-    if (node.type === "text" && typeof node.text === "string")
-        return node.text;
-    if (Array.isArray(node.content))
-        return node.content.map(adfToText).join("");
-    return "";
-}
 export class JiraProvider {
     baseUrl;
     projectKey;
@@ -101,7 +104,7 @@ export class JiraProvider {
         return {
             id: raw.key,
             title: raw.fields.summary,
-            body: raw.fields.description ? adfToText(raw.fields.description) : "",
+            body: raw.fields.description ? adfToMarkdown(raw.fields.description) : "",
             labels: raw.fields.labels,
         };
     }
@@ -163,7 +166,7 @@ export class JiraProvider {
                 fields: {
                     project: { key: this.projectKey },
                     summary: input.title,
-                    description: toAdf(input.body),
+                    description: markdownToAdf(input.body),
                     issuetype: { name: this.issueTypes[input.kind] },
                     labels: input.labels,
                 },
@@ -296,7 +299,7 @@ export class JiraProvider {
             .map(([state, jiraStatus]) => ({ state, jiraStatus, exists: available.has(jiraStatus) }));
     }
     async comment(issue, body) {
-        await this.jira(`/rest/api/3/issue/${issue.id}/comment`, { method: "POST", body: JSON.stringify({ body: toAdf(body) }) });
+        await this.jira(`/rest/api/3/issue/${issue.id}/comment`, { method: "POST", body: JSON.stringify({ body: markdownToAdf(body) }) });
     }
     /** The single fetch every comment-reading method (`findMarkerComment`, `listComments`) builds on. */
     async fetchComments(issueId) {
@@ -307,7 +310,7 @@ export class JiraProvider {
         const comments = await this.fetchComments(issueId);
         let found = null;
         for (const c of comments) {
-            const match = MARKER_RE.exec(adfToText(c.body));
+            const match = MARKER_RE.exec(adfToMarkdown(c.body));
             if (!match)
                 continue;
             try {
@@ -323,8 +326,8 @@ export class JiraProvider {
     async listComments(issue) {
         const comments = await this.fetchComments(issue.id);
         return comments
-            .filter((c) => !MARKER_RE.test(adfToText(c.body)))
-            .map((c) => ({ id: c.id, author: c.author?.displayName ?? "unknown", created_at: c.created, body: adfToText(c.body) }));
+            .filter((c) => !MARKER_RE.test(adfToMarkdown(c.body)))
+            .map((c) => ({ id: c.id, author: c.author?.displayName ?? "unknown", created_at: c.created, body: adfToMarkdown(c.body) }));
     }
     async readMarker(issue) {
         const found = await this.findMarkerComment(issue.id);

package/dist/core/issues/markdown_adf.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A hand-rolled Markdown <-> Atlassian Document Format (ADF) converter for
+ * Jira comment/description bodies — deliberately NOT built on a markdown
+ * parsing library. This project has zero markdown dependencies today and
+ * that's a deliberate choice (see `package.json`): `jira_provider.ts`'s own
+ * `toAdf`/`adfToText` pair is the existing precedent (one paragraph of
+ * plain text, nothing richer), and this module is the same philosophy
+ * extended to a small, explicitly-bounded Markdown subset, not a general
+ * CommonMark implementation.
+ *
+ * SUPPORTED (confirmed scope, see the module's originating task — do not
+ * silently grow this list): ATX headings (`#`..`######`), bold
+ * (`**x**`/`__x__`), italic (`*x*`/`_x_`), strikethrough (`~~x~~`), inline
+ * code (`` `x` ``), fenced code blocks with optional language, bullet
+ * (`-`/`*`/`+`) and ordered (`1.`) lists with ONE level of nesting,
+ * blockquotes (consecutive `>` lines as one block), horizontal rules
+ * (`---`/`***`/`___` alone on a line), links (`[text](url)`), paragraphs
+ * separated by blank lines, and hard line breaks (a line ending in two-plus
+ * trailing spaces, or a lone trailing backslash).
+ *
+ * OUT OF SCOPE (tables, images, @mentions, raw HTML, nested blockquotes-in-
+ * lists, >1 level of list nesting): never crashes and never corrupts
+ * structure on these — `markdownToAdf` falls through to literal text in a
+ * plain paragraph (matching `toAdf`'s existing behavior for "everything"
+ * before this module existed), and `adfToMarkdown` degrades any node/mark
+ * type it doesn't recognize to its nested text content. `markdownToAdf`
+ * must NEVER throw on any input string — a malformed fence, an unmatched
+ * `**`, an empty link target, all degrade to literal text rather than
+ * erroring, because this runs unattended inside `spf watch`.
+ *
+ * ADF node/mark shapes below are taken from Atlassian's published document
+ * structure (developer.atlassian.com/cloud/jira/platform/apis/document/
+ * structure/), not guessed — in particular the strikethrough mark's real
+ * type name is `"strike"`, NOT `"strikethrough"` (an easy guess to get
+ * wrong), and ADF text nodes must never carry an empty `text` string (the
+ * schema requires non-empty), which is why every text-emitting path here
+ * checks for empty content before emitting a node instead of always
+ * emitting one unconditionally the way `jira_provider.ts`'s `toAdf` does
+ * for its single fixed paragraph.
+ */
+/**
+ * Parses the constrained Markdown subset (module comment) into an ADF
+ * document node. Never throws: every unrecognized or malformed construct
+ * degrades to literal text inside a plain paragraph rather than raising,
+ * because this feeds `spf watch`'s unattended comment/description writes.
+ */
+export declare function markdownToAdf(text: string): unknown;
+/**
+ * The inverse of `markdownToAdf`: renders an ADF document back into the
+ * same Markdown subset. NOT required to byte-match the original input
+ * (canonical forms are fine — e.g. always `-` for bullets even if the
+ * source used `*`), only to be semantically recognizable and to converge
+ * after one more round trip through `markdownToAdf`. Handles ADF built by
+ * this module OR hand-built elsewhere (e.g. Jira's own rich-text editor):
+ * any node or mark type it doesn't recognize degrades to its nested text
+ * content via `renderFallbackText` rather than throwing or dropping it.
+ */
+export declare function adfToMarkdown(adf: unknown): string;