@inflexa-ai/harness 0.1.1

package/dist/lib/fs-helpers.js

@@ -0,0 +1,119 @@
+/**
+ * Shared filesystem helpers — deduplicated SHA-256 hashing and file existence checks.
+ */
+import { createHash } from "node:crypto";
+import { constants as fsConstants, createReadStream } from "node:fs";
+import { access, mkdir, open, realpath } from "node:fs/promises";
+import { dirname, resolve, sep } from "node:path";
+/**
+ * Compute SHA-256 hash of in-memory content.
+ * Returns `sha256:<hex>` format.
+ */
+export function computeSha256(content) {
+    return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+/**
+ * Compute SHA-256 hash of a file on disk.
+ * Returns `sha256:<hex>` format.
+ */
+export async function computeSha256File(filePath) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash("sha256");
+        const stream = createReadStream(filePath);
+        stream.on("data", (chunk) => hash.update(chunk));
+        stream.on("end", () => resolve(`sha256:${hash.digest("hex")}`));
+        stream.on("error", reject);
+    });
+}
+/**
+ * True when `hash` is a well-formed `algorithm:hex` content hash. The storage backend
+ * (`ValidateContentHash`) rejects any file row without one — and rolls back the
+ * whole activity transaction on the first bad row — so this gates what reaches
+ * registration. Inputs arrive hashless from the path-only provenance frame and
+ * are filled by `reconcileManifestWithDisk`; an empty hash past that point is
+ * an attestation invariant violation, not something to paper over.
+ */
+export function hasValidContentHash(hash) {
+    return !!hash && /^[a-z0-9]+:[0-9a-f]+$/i.test(hash);
+}
+/**
+ * Check whether a file exists (access-based, no stat overhead).
+ */
+export async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Classify a path against a confinement root, following symlinks — the read-side
+ * companion to {@link writeFileWithinRoot}. The workspace read seam resolves
+ * agent-supplied paths lexically only; without this, a symlink an agent planted
+ * in its writable step dir (`ln -s ~/.ssh/id_rsa leak.txt`) would be read through
+ * by the host process, leaking arbitrary host-file content into the model context.
+ *
+ * Hard links classify as `in`: a hard link has no symlink target for `realpath`
+ * to follow, so it resolves to its own in-tree path — which is exactly why this
+ * blocks the symlink escape without breaking hard-linked staged inputs.
+ */
+export async function classifyWithinRoot(confinementRoot, absPath) {
+    let realRoot;
+    try {
+        realRoot = await realpath(confinementRoot);
+    }
+    catch {
+        // The root itself is unresolvable — there is nothing in-tree to read.
+        return "absent";
+    }
+    let real;
+    try {
+        real = await realpath(absPath);
+    }
+    catch (cause) {
+        const code = cause.code;
+        // A path (or symlink target) that does not resolve leaks nothing; let the
+        // caller's own not-found/fallback path handle it. Genuine faults (e.g.
+        // EACCES traversing a directory) propagate.
+        if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP")
+            return "absent";
+        throw cause;
+    }
+    if (real !== realRoot && !real.startsWith(realRoot + sep))
+        return "escaped";
+    return "in";
+}
+export async function writeFileWithinRoot(workspaceRoot, absPath, data) {
+    // Cheap lexical gate first, before any disk touch — rejects a `../` target
+    // without paying for the mkdir/realpath below. Both sides stay un-canonicalized
+    // so the comparison is consistent (canonicalizing only one would mismatch on a
+    // symlinked temp root like macOS's `/var` → `/private/var`).
+    const lexicalRoot = resolve(workspaceRoot);
+    const target = resolve(absPath);
+    if (target !== lexicalRoot && !target.startsWith(lexicalRoot + sep)) {
+        throw new Error(`writeFileWithinRoot: refusing to write outside the workspace root: ${absPath}`);
+    }
+    const dir = dirname(target);
+    await mkdir(dir, { recursive: true });
+    // Physical gate: canonicalize BOTH sides so a symlinked intermediate dir
+    // (`output -> /elsewhere`) is caught regardless of any symlink on the trusted
+    // root's own path.
+    const realRoot = await realpath(workspaceRoot);
+    const realDir = await realpath(dir);
+    if (realDir !== realRoot && !realDir.startsWith(realRoot + sep)) {
+        throw new Error(`writeFileWithinRoot: parent directory escapes the workspace root via a symlink: ${absPath}`);
+    }
+    // `O_NOFOLLOW ?? 0`: the flag is defined on Linux/macOS (the harness host
+    // platforms); the `?? 0` keeps the open valid on a platform that lacks it
+    // rather than NaN-ing the flag mask.
+    const flags = fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_TRUNC | (fsConstants.O_NOFOLLOW ?? 0);
+    const fh = await open(target, flags, 0o644);
+    try {
+        await fh.writeFile(data);
+    }
+    finally {
+        await fh.close();
+    }
+}

package/dist/lib/fs-result.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Filesystem Result glue for cortex.
+ *
+ * The workspace read seam (`workspace/filesystem.ts`) and the handful of
+ * modules that touch `node:fs` directly (e.g. `memory/card-builders.ts`) model
+ * failure as values. The ONLY `try/catch` against `node:fs` lives here, in
+ * `tryFs` — it turns a genuine I/O throw into an `err(FsError)`; everything
+ * above flows `ResultAsync`.
+ *
+ * House rules realized here (see `lib/result.ts`):
+ *  - Absence is NOT an error. A missing path stays in the OK channel as a data
+ *    variant: the seam returns `ok({ kind: "not_found" })` / `ok({ kind:
+ *    "out_of_scope" })`, never an `err`. The fs-level `ENOENT`/`ENOTDIR` checks
+ *    that distinguish absence map to the absence sentinel the caller supplies
+ *    (`onAbsent`), NOT to an `err`. `FsError` is reserved for a genuine I/O
+ *    failure — a permission denial (`EACCES`/`EPERM`), an `EISDIR` where a file
+ *    was expected, a disk error, a too-many-open-files (`EMFILE`), a presigned
+ *    download fetch failure.
+ *  - Control-flow exceptions (DBOS cancellation, `AbortError`) are NOT failures
+ *    and are never captured as an `FsError`: `tryFs` only ever wraps the single
+ *    `fs` call passed to it. An `AbortError` raised inside a streamed read is a
+ *    control-flow signal — keep it outside the wrapped call (it propagates) or
+ *    re-classify it explicitly; do NOT funnel a whole streaming body through
+ *    `tryFs` such that an `AbortError` becomes an `err`.
+ *
+ * Consumers unwrap per their edge: tool `execute` bodies (`read_file`, `grep`,
+ * `list_files`, `file_stat`, `edit_file`) `unwrapOrThrow` the Result, then
+ * switch on the OK-channel `.kind`; degrade-to-null direct-fs callers
+ * (`card-builders`) `.unwrapOr(null)` / `.match` to preserve their "any failure
+ * → fall back to a chip" behaviour.
+ */
+import { ResultAsync } from "neverthrow";
+/**
+ * A filesystem failure. Absence is deliberately NOT modelled here — a missing
+ * file/dir rides the OK channel as the seam's `not_found` / `out_of_scope` data
+ * variant (or a caller-chosen sentinel via `tryFs(..., { onAbsent })`).
+ * `FsError` is reserved for a genuine, unexpected I/O failure. `op` is a stable
+ * human-readable label (e.g. `"workspace.readFile"`, `"cardBuilders.subdirs"`)
+ * used by `describeFsError` and in logs.
+ */
+export type FsError = {
+    readonly type: "read_failed";
+    readonly op: string;
+    readonly path?: string;
+    readonly cause: unknown;
+} | {
+    readonly type: "write_failed";
+    readonly op: string;
+    readonly path?: string;
+    readonly cause: unknown;
+} | {
+    readonly type: "permission_denied";
+    readonly op: string;
+    readonly path?: string;
+    readonly cause: unknown;
+} | {
+    readonly type: "is_a_directory";
+    readonly op: string;
+    readonly path?: string;
+    readonly cause: unknown;
+} | {
+    readonly type: "fetch_failed";
+    readonly op: string;
+    readonly path?: string;
+    readonly cause: unknown;
+};
+/** True when the throw is a plain "this path isn't here" — `ENOENT`/`ENOTDIR`. */
+export declare function isAbsent(cause: unknown): boolean;
+/** A one-line, user-facing description of an `FsError` for logs and error bodies. */
+export declare function describeFsError(e: FsError): string;
+/**
+ * Wrap a single `fs` read call. A genuine `fs` throw becomes `err(read_failed)`
+ * — or `err(permission_denied)` / `err(is_a_directory)` for the matching errno.
+ * When `onAbsent` is supplied, an `ENOENT`/`ENOTDIR` throw is intercepted and
+ * its return value placed in the OK channel (absence is NOT an error).
+ *
+ * `fn` runs the single `fs` call and returns the already-mapped value (`T`).
+ * Keep `fn` to the one `await fs.X(...)` plus trivial mapping; do NOT embed
+ * control-flow that could throw a non-`fs` error (an `AbortError` raised inside
+ * `fn` would be miscaptured as an `FsError` — keep abortable streaming bodies
+ * out of `tryFs`).
+ */
+export declare function tryFs<T>(op: string, fn: () => Promise<T>, options?: {
+    path?: string;
+    onAbsent?: () => T;
+}): ResultAsync<T, FsError>;
+/** `tryFs` for a write/mkdir/open-for-write call: maps the non-permission
+ *  default to `write_failed`. Absence semantics are identical. */
+export declare function tryFsWrite<T>(op: string, fn: () => Promise<T>, options?: {
+    path?: string;
+    onAbsent?: () => T;
+}): ResultAsync<T, FsError>;
+/**
+ * Wrap a presigned-download fetch (the `PresignedFallback.fetch` seam call) into
+ * the same error channel. A throw becomes `err(fetch_failed)`; a `null` return
+ * (file genuinely not present remotely) stays in the OK channel as `null`.
+ */
+export declare function tryFetch<T>(op: string, fn: () => Promise<T>, path?: string): ResultAsync<T, FsError>;

package/dist/lib/fs-result.js

@@ -0,0 +1,137 @@
+/**
+ * Filesystem Result glue for cortex.
+ *
+ * The workspace read seam (`workspace/filesystem.ts`) and the handful of
+ * modules that touch `node:fs` directly (e.g. `memory/card-builders.ts`) model
+ * failure as values. The ONLY `try/catch` against `node:fs` lives here, in
+ * `tryFs` — it turns a genuine I/O throw into an `err(FsError)`; everything
+ * above flows `ResultAsync`.
+ *
+ * House rules realized here (see `lib/result.ts`):
+ *  - Absence is NOT an error. A missing path stays in the OK channel as a data
+ *    variant: the seam returns `ok({ kind: "not_found" })` / `ok({ kind:
+ *    "out_of_scope" })`, never an `err`. The fs-level `ENOENT`/`ENOTDIR` checks
+ *    that distinguish absence map to the absence sentinel the caller supplies
+ *    (`onAbsent`), NOT to an `err`. `FsError` is reserved for a genuine I/O
+ *    failure — a permission denial (`EACCES`/`EPERM`), an `EISDIR` where a file
+ *    was expected, a disk error, a too-many-open-files (`EMFILE`), a presigned
+ *    download fetch failure.
+ *  - Control-flow exceptions (DBOS cancellation, `AbortError`) are NOT failures
+ *    and are never captured as an `FsError`: `tryFs` only ever wraps the single
+ *    `fs` call passed to it. An `AbortError` raised inside a streamed read is a
+ *    control-flow signal — keep it outside the wrapped call (it propagates) or
+ *    re-classify it explicitly; do NOT funnel a whole streaming body through
+ *    `tryFs` such that an `AbortError` becomes an `err`.
+ *
+ * Consumers unwrap per their edge: tool `execute` bodies (`read_file`, `grep`,
+ * `list_files`, `file_stat`, `edit_file`) `unwrapOrThrow` the Result, then
+ * switch on the OK-channel `.kind`; degrade-to-null direct-fs callers
+ * (`card-builders`) `.unwrapOr(null)` / `.match` to preserve their "any failure
+ * → fall back to a chip" behaviour.
+ */
+import { ResultAsync, err, ok } from "neverthrow";
+const _assertDomainError = true;
+/** errno codes that mean "the path is absent" — the caller's concern, mapped to
+ *  the supplied absence sentinel, NOT to an `err`. */
+const ABSENT_CODES = new Set(["ENOENT", "ENOTDIR"]);
+/** errno codes that mean "permission denied". */
+const PERMISSION_CODES = new Set(["EACCES", "EPERM"]);
+function errnoOf(cause) {
+    if (cause && typeof cause === "object" && "code" in cause) {
+        const code = cause.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    return undefined;
+}
+/** True when the throw is a plain "this path isn't here" — `ENOENT`/`ENOTDIR`. */
+export function isAbsent(cause) {
+    const code = errnoOf(cause);
+    return code !== undefined && ABSENT_CODES.has(code);
+}
+/** Map an `fs` throw to a typed `FsError`. `EACCES`/`EPERM` → permission_denied;
+ *  `EISDIR` → is_a_directory; everything else → read_failed (or write_failed,
+ *  via `tryFsWrite`). Absence (`ENOENT`/`ENOTDIR`) is NOT routed here — `tryFs`
+ *  intercepts it first and yields the absence sentinel. */
+function readError(op, path, cause) {
+    const code = errnoOf(cause);
+    if (code && PERMISSION_CODES.has(code))
+        return { type: "permission_denied", op, path, cause };
+    if (code === "EISDIR")
+        return { type: "is_a_directory", op, path, cause };
+    return { type: "read_failed", op, path, cause };
+}
+function writeError(op, path, cause) {
+    const code = errnoOf(cause);
+    if (code && PERMISSION_CODES.has(code))
+        return { type: "permission_denied", op, path, cause };
+    return { type: "write_failed", op, path, cause };
+}
+/** A one-line, user-facing description of an `FsError` for logs and error bodies. */
+export function describeFsError(e) {
+    const at = e.path ? ` (${e.op}: ${e.path})` : ` (${e.op})`;
+    switch (e.type) {
+        case "read_failed":
+            return `filesystem read failed${at}`;
+        case "write_failed":
+            return `filesystem write failed${at}`;
+        case "permission_denied":
+            return `filesystem permission denied${at}`;
+        case "is_a_directory":
+            return `expected a file but found a directory${at}`;
+        case "fetch_failed":
+            return `remote file fetch failed${at}`;
+    }
+}
+/**
+ * Wrap a single `fs` read call. A genuine `fs` throw becomes `err(read_failed)`
+ * — or `err(permission_denied)` / `err(is_a_directory)` for the matching errno.
+ * When `onAbsent` is supplied, an `ENOENT`/`ENOTDIR` throw is intercepted and
+ * its return value placed in the OK channel (absence is NOT an error).
+ *
+ * `fn` runs the single `fs` call and returns the already-mapped value (`T`).
+ * Keep `fn` to the one `await fs.X(...)` plus trivial mapping; do NOT embed
+ * control-flow that could throw a non-`fs` error (an `AbortError` raised inside
+ * `fn` would be miscaptured as an `FsError` — keep abortable streaming bodies
+ * out of `tryFs`).
+ */
+export function tryFs(op, fn, options = {}) {
+    return new ResultAsync((async () => {
+        try {
+            return ok(await fn());
+        }
+        catch (cause) {
+            if (options.onAbsent && isAbsent(cause))
+                return ok(options.onAbsent());
+            return err(readError(op, options.path, cause));
+        }
+    })());
+}
+/** `tryFs` for a write/mkdir/open-for-write call: maps the non-permission
+ *  default to `write_failed`. Absence semantics are identical. */
+export function tryFsWrite(op, fn, options = {}) {
+    return new ResultAsync((async () => {
+        try {
+            return ok(await fn());
+        }
+        catch (cause) {
+            if (options.onAbsent && isAbsent(cause))
+                return ok(options.onAbsent());
+            return err(writeError(op, options.path, cause));
+        }
+    })());
+}
+/**
+ * Wrap a presigned-download fetch (the `PresignedFallback.fetch` seam call) into
+ * the same error channel. A throw becomes `err(fetch_failed)`; a `null` return
+ * (file genuinely not present remotely) stays in the OK channel as `null`.
+ */
+export function tryFetch(op, fn, path) {
+    return new ResultAsync((async () => {
+        try {
+            return ok(await fn());
+        }
+        catch (cause) {
+            return err({ type: "fetch_failed", op, path, cause });
+        }
+    })());
+}

package/dist/lib/host-concurrency.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Per-source HTTP concurrency cap helper.
+ *
+ * Several Phase-3 fan-outs hit the same upstream (chembl, openfda,
+ * clinicaltrials.gov) from multiple branches. Without a host-level cap, a
+ * single shortlist of 8 modulators × 4 fan-out sub-workflows could open
+ * 32 concurrent requests against ChEMBL — well past polite usage. This
+ * module exposes a tiny semaphore keyed by host so all branches share
+ * one budget per upstream.
+ *
+ * Usage:
+ *   import { withHost } from "../../lib/host-concurrency.js";
+ *   const result = await withHost("chembl", () => chembl.getMechanism(id));
+ */
+/** Acquire a slot, run `body`, release on completion (success or failure). */
+export declare function withHost<T>(host: string, body: () => Promise<T>): Promise<T>;

package/dist/lib/host-concurrency.js

@@ -0,0 +1,60 @@
+/**
+ * Per-source HTTP concurrency cap helper.
+ *
+ * Several Phase-3 fan-outs hit the same upstream (chembl, openfda,
+ * clinicaltrials.gov) from multiple branches. Without a host-level cap, a
+ * single shortlist of 8 modulators × 4 fan-out sub-workflows could open
+ * 32 concurrent requests against ChEMBL — well past polite usage. This
+ * module exposes a tiny semaphore keyed by host so all branches share
+ * one budget per upstream.
+ *
+ * Usage:
+ *   import { withHost } from "../../lib/host-concurrency.js";
+ *   const result = await withHost("chembl", () => chembl.getMechanism(id));
+ */
+const DEFAULT_LIMITS = {
+    chembl: 4,
+    openfda: 4,
+    ctgov: 4,
+    opentargets: 4,
+    ensembl: 6,
+    ncbi: 3,
+    bgee: 4,
+    cbioportal: 3,
+    string: 3,
+    reactome: 4,
+    kegg: 4,
+    hgnc: 6,
+    uniprot: 6,
+    iuphar: 4,
+    ema: 2,
+    pubchem: 4,
+    "annotation-llm": 4,
+    default: 4,
+};
+const budgets = new Map();
+function getBudget(host) {
+    let b = budgets.get(host);
+    if (!b) {
+        b = { limit: DEFAULT_LIMITS[host] ?? DEFAULT_LIMITS.default, inUse: 0, queue: [] };
+        budgets.set(host, b);
+    }
+    return b;
+}
+/** Acquire a slot, run `body`, release on completion (success or failure). */
+export async function withHost(host, body) {
+    const b = getBudget(host);
+    if (b.inUse >= b.limit) {
+        await new Promise((resolve) => b.queue.push(resolve));
+    }
+    b.inUse += 1;
+    try {
+        return await body();
+    }
+    finally {
+        b.inUse -= 1;
+        const next = b.queue.shift();
+        if (next)
+            next();
+    }
+}

package/dist/lib/identifiers.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Identifier validation — safe patterns for path-embedded IDs.
+ */
+/** Pattern for IDs safe to embed in filesystem paths. */
+export declare const SAFE_ID_PATTERN: RegExp;
+/** Zod refinement for safe path identifiers. */
+export declare function isSafePathId(value: string): boolean;
+export declare const SAFE_ID_MESSAGE = "Must be alphanumeric with hyphens/underscores, no path separators";

package/dist/lib/identifiers.js

@@ -0,0 +1,10 @@
+/**
+ * Identifier validation — safe patterns for path-embedded IDs.
+ */
+/** Pattern for IDs safe to embed in filesystem paths. */
+export const SAFE_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+/** Zod refinement for safe path identifiers. */
+export function isSafePathId(value) {
+    return SAFE_ID_PATTERN.test(value) && !value.includes("..");
+}
+export const SAFE_ID_MESSAGE = "Must be alphanumeric with hyphens/underscores, no path separators";

package/dist/lib/metrics.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Custom OTel metrics for Cortex.
+ *
+ * Instruments:
+ *   - cortex.artifact.reconcile.dropped — counter for missing manifest entries
+ */
+export declare const artifactReconcileDropped: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;

package/dist/lib/metrics.js

@@ -0,0 +1,12 @@
+/**
+ * Custom OTel metrics for Cortex.
+ *
+ * Instruments:
+ *   - cortex.artifact.reconcile.dropped — counter for missing manifest entries
+ */
+import { metrics } from "@opentelemetry/api";
+const meter = metrics.getMeter("cortex");
+export const artifactReconcileDropped = meter.createCounter("cortex.artifact.reconcile.dropped", {
+    description: "Manifest entries dropped because their on-disk file was missing at " +
+        "registration time (writes-then-deletes, renames). Tagged by agent_id, step_id.",
+});

package/dist/lib/mime-detect.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Mime-type detection for artifact registration.
+ *
+ * Registration payloads sent to the storage backend carry a `mimeType` per file. The storage backend
+ * persists it on the artifact row and uses it as the S3 object's
+ * `Content-Type` when the artifact is later synced — without it, S3 stores
+ * `application/octet-stream` and downloads serve as opaque binary regardless
+ * of file extension.
+ *
+ * The `mime` package's mime-db backing doesn't include a few science-domain
+ * extensions (`.py`, `.R`, `.Rmd`, `.RData`, `.rds`) that browsers populate
+ * in `File.type` from their bundled tables, so we extend a custom Mime
+ * instance with those cases. Returned types align with the frontend's browser-side
+ * detection so a Python script uploaded directly and one synced from a
+ * sandbox both end up with the same `text/x-python`.
+ */
+export declare function detectMimeType(pathOrFilename: string): string;

package/dist/lib/mime-detect.js

@@ -0,0 +1,29 @@
+/**
+ * Mime-type detection for artifact registration.
+ *
+ * Registration payloads sent to the storage backend carry a `mimeType` per file. The storage backend
+ * persists it on the artifact row and uses it as the S3 object's
+ * `Content-Type` when the artifact is later synced — without it, S3 stores
+ * `application/octet-stream` and downloads serve as opaque binary regardless
+ * of file extension.
+ *
+ * The `mime` package's mime-db backing doesn't include a few science-domain
+ * extensions (`.py`, `.R`, `.Rmd`, `.RData`, `.rds`) that browsers populate
+ * in `File.type` from their bundled tables, so we extend a custom Mime
+ * instance with those cases. Returned types align with the frontend's browser-side
+ * detection so a Python script uploaded directly and one synced from a
+ * sandbox both end up with the same `text/x-python`.
+ */
+import { Mime } from "mime";
+import standard from "mime/types/standard.js";
+import other from "mime/types/other.js";
+const mime = new Mime(standard, other, {
+    "text/x-python": ["py"],
+    "text/x-r-source": ["R", "r"],
+    "text/x-r-markdown": ["Rmd", "rmd"],
+    "application/x-rdata": ["RData", "Rdata", "rds"],
+});
+const FALLBACK = "application/octet-stream";
+export function detectMimeType(pathOrFilename) {
+    return mime.getType(pathOrFilename) ?? FALLBACK;
+}

package/dist/lib/otel.d.ts

@@ -0,0 +1,30 @@
+/**
+ * OpenTelemetry SDK initialization — traces + metrics.
+ *
+ * Exported as `initOtel()` and called explicitly from index.ts to prevent
+ * the bundler from tree-shaking it (side-effect-only imports get dropped).
+ *
+ * Traces: NodeTracerProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT
+ *         is set.
+ *
+ * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT
+ *          is set. Custom Cortex metrics are defined in metrics.ts.
+ *
+ * Note: OTEL's instrumentation-http patches node:http but does not cover
+ *        Hono's request handling or Node 22's undici-based globalThis.fetch,
+ *        so inbound/outbound trace-context propagation across those paths is
+ *        not currently wired.
+ */
+/**
+ * Initialize the OpenTelemetry SDK. Must be called before any code that
+ * calls trace.getTracer() or metrics.getMeter().
+ *
+ * Safe to call multiple times — only the first call has effect.
+ */
+export declare function initOtel(): void;
+/**
+ * Flush and shut down the OTel exporters. Called by the graceful-shutdown
+ * sequence so in-flight batch spans/metrics make it to the collector
+ * before the process exits. Never throws.
+ */
+export declare function shutdownOtel(): Promise<void>;

package/dist/lib/otel.js

@@ -0,0 +1,102 @@
+/**
+ * OpenTelemetry SDK initialization — traces + metrics.
+ *
+ * Exported as `initOtel()` and called explicitly from index.ts to prevent
+ * the bundler from tree-shaking it (side-effect-only imports get dropped).
+ *
+ * Traces: NodeTracerProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT
+ *         is set.
+ *
+ * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT
+ *          is set. Custom Cortex metrics are defined in metrics.ts.
+ *
+ * Note: OTEL's instrumentation-http patches node:http but does not cover
+ *        Hono's request handling or Node 22's undici-based globalThis.fetch,
+ *        so inbound/outbound trace-context propagation across those paths is
+ *        not currently wired.
+ */
+import { propagation, metrics, trace } from "@opentelemetry/api";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+let initialized = false;
+let registeredTracerProvider;
+let registeredMeterProvider;
+/**
+ * Initialize the OpenTelemetry SDK. Must be called before any code that
+ * calls trace.getTracer() or metrics.getMeter().
+ *
+ * Safe to call multiple times — only the first call has effect.
+ */
+export function initOtel() {
+    if (initialized)
+        return;
+    initialized = true;
+    // ── W3C Trace Context propagation ──────────────────────────────────
+    propagation.setGlobalPropagator(new W3CTraceContextPropagator());
+    const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+    // ── Traces ─────────────────────────────────────────────────────────
+    // Always register a TracerProvider so trace.getTracer() returns real spans
+    // with unique IDs. Without this, the OtelBridge gets no-op spans (all zeros)
+    // that collide in its span map, causing "No OTEL span found" warnings.
+    {
+        const spanProcessors = [];
+        if (endpoint) {
+            const base = endpoint.replace(/\/+$/, "");
+            spanProcessors.push(new BatchSpanProcessor(new OTLPTraceExporter({ url: `${base}/v1/traces` })));
+        }
+        const serviceName = process.env.OTEL_SERVICE_NAME || "cortex";
+        const resource = resourceFromAttributes({
+            [ATTR_SERVICE_NAME]: serviceName,
+        });
+        const tracerProvider = new NodeTracerProvider({
+            resource,
+            spanProcessors,
+        });
+        tracerProvider.register();
+        registeredTracerProvider = tracerProvider;
+        // Debug: verify registration actually worked
+        const testTracer = trace.getTracer("otel-init-check");
+        const testSpan = testTracer.startSpan("init-check");
+        const ctx = testSpan.spanContext();
+        const isNoop = ctx.spanId === "0000000000000000";
+        console.log(`[otel] TracerProvider registered: spanId=${ctx.spanId}, noop=${isNoop}, ` +
+            `endpoint=${endpoint ?? "(none)"}, processors=${spanProcessors.length}`);
+        testSpan.end();
+    }
+    // ── Metrics ────────────────────────────────────────────────────────
+    if (endpoint) {
+        const base = endpoint.replace(/\/+$/, "");
+        const metricExporter = new OTLPMetricExporter({
+            url: `${base}/v1/metrics`,
+        });
+        const meterProvider = new MeterProvider({
+            readers: [
+                new PeriodicExportingMetricReader({
+                    exporter: metricExporter,
+                    exportIntervalMillis: 30_000,
+                }),
+            ],
+        });
+        metrics.setGlobalMeterProvider(meterProvider);
+        registeredMeterProvider = meterProvider;
+    }
+}
+/**
+ * Flush and shut down the OTel exporters. Called by the graceful-shutdown
+ * sequence so in-flight batch spans/metrics make it to the collector
+ * before the process exits. Never throws.
+ */
+export async function shutdownOtel() {
+    const tasks = [];
+    if (registeredTracerProvider)
+        tasks.push(registeredTracerProvider.shutdown());
+    if (registeredMeterProvider)
+        tasks.push(registeredMeterProvider.shutdown());
+    await Promise.allSettled(tasks);
+}