@oxygen-agent/cli 1.982.3 → 1.1003.12

package/node_modules/@oxygen/shared/dist/langfuse.d.ts

@@ -38,6 +38,8 @@ export type LlmSpanBody = {
     userId?: string | null;
 };
 export type LlmGenerationBody = LlmSpanBody & {
+    /** Persist this physical id when a later annotation must target this attempt. */
+    observationId?: string;
     model?: string | null;
     modelParameters?: Record<string, unknown>;
     completionStartTime?: Date | null;
@@ -63,9 +65,11 @@ export type LlmEventBody = {
  * because that variant requires a *string* value. Widening later stays additive.
  */
 export type LlmScoreBody = {
-    /** Deterministic id upserts; omit for a new score each call. */
+    /** Retry-safe scores need the same id, name AND timestamp on every attempt. */
     id?: string;
     traceId: string;
+    observationId?: string;
+    timestamp?: Date;
     name: string;
     value: number;
     dataType?: "BOOLEAN" | "NUMERIC";
@@ -103,6 +107,13 @@ export type LlmTracingClient = {
  */
 export declare function isLlmTracingEnabled(env?: EnvMap): boolean;
 export declare function resolveLlmTracingEnvironment(env?: EnvMap): string;
+/**
+ * The private Langfuse provider must identify its own runtime rather than
+ * inherit the process-wide OTel resource. Fly identity wins because it is
+ * injected per machine and cannot drift; a local CLI/test process is neither
+ * the web app nor the worker.
+ */
+export declare function resolveLlmTracingServiceName(env?: EnvMap): string;
 /**
  * Deterministic Langfuse trace id for an external seed (copilot turn id, agent
  * run id, AI-column run id).

package/node_modules/@oxygen/shared/dist/langfuse.js

@@ -32,7 +32,7 @@
 //   * Trace-level input/output is deprecated in v5. Overall IO goes on the ROOT
 //     observation instead; setTraceIO()/setActiveTraceIO() are deliberately not
 //     used here.
-import { createHash, randomBytes } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { OXYGEN_VERSION } from "./version.js";
 import { prepareLlmPayload } from "./llm-payload.js";
 import { log } from "./log.js";
@@ -73,6 +73,15 @@ export function resolveLlmTracingEnvironment(env = process.env) {
     const explicit = env.LANGFUSE_TRACING_ENVIRONMENT?.trim().toLowerCase();
     if (explicit)
         return explicit.replace(/[^a-z0-9_-]/g, "-");
+    // Self-hosted first: those processes carry neither VERCEL_ENV nor a Fly app
+    // name, so without this every self-hosted tier would report "development".
+    // selfhost-shadow stays "development" deliberately — production-shaped data,
+    // not production traffic.
+    const deployEnv = env.OXYGEN_DEPLOY_ENV?.trim().toLowerCase();
+    if (deployEnv === "selfhost-prod")
+        return "production";
+    if (deployEnv === "selfhost-shadow" || deployEnv === "selfhost-dev")
+        return "development";
     if (env.VERCEL_ENV)
         return env.VERCEL_ENV === "production" ? "production" : "development";
     const flyApp = env.FLY_APP_NAME ?? env.FLY_APP;
@@ -83,6 +92,23 @@ export function resolveLlmTracingEnvironment(env = process.env) {
         return flyEnv === "production" ? "production" : "development";
     return "development";
 }
+/**
+ * The private Langfuse provider must identify its own runtime rather than
+ * inherit the process-wide OTel resource. Fly identity wins because it is
+ * injected per machine and cannot drift; a local CLI/test process is neither
+ * the web app nor the worker.
+ */
+export function resolveLlmTracingServiceName(env = process.env) {
+    const flyApp = env.FLY_APP_NAME?.trim() || env.FLY_APP?.trim();
+    if (flyApp)
+        return flyApp.includes("-dev") ? "oxygen-worker-dev" : "oxygen-worker";
+    const flyEnvironment = env.FLY_ENVIRONMENT?.trim().toLowerCase();
+    if (flyEnvironment)
+        return flyEnvironment === "production" ? "oxygen-worker" : "oxygen-worker-dev";
+    if (env.VERCEL?.trim() || env.VERCEL_ENV?.trim())
+        return "oxygen-web";
+    return "oxygen-local";
+}
 /**
  * Deterministic Langfuse trace id for an external seed (copilot turn id, agent
  * run id, AI-column run id).
@@ -140,8 +166,9 @@ function createOtelEmitter(env, warn) {
     const init = () => {
         handle ??= (async () => {
             try {
-                const [{ LangfuseSpanProcessor }, { BasicTracerProvider, AlwaysOnSampler }, tracing, otel, core] = await Promise.all([
+                const [{ LangfuseSpanProcessor }, { BasicTracerProvider, AlwaysOnSampler }, { resourceFromAttributes }, tracing, otel, core] = await Promise.all([
                     import("@langfuse/otel"), import("@opentelemetry/sdk-trace-base"),
+                    import("@opentelemetry/resources"),
                     import("@langfuse/tracing"), import("@opentelemetry/api"), import("@langfuse/core"),
                 ]);
                 const processor = new LangfuseSpanProcessor({
@@ -160,6 +187,11 @@ function createOtelEmitter(env, warn) {
                 });
                 let identity;
                 const provider = new BasicTracerProvider({
+                    // This provider is deliberately isolated from the application's
+                    // global OTel pipeline, so it also needs its own explicit resource.
+                    // Never trust OTEL_SERVICE_NAME here: a cross-environment Doppler
+                    // value must not relabel prompt-bearing Langfuse observations.
+                    resource: resourceFromAttributes({ "service.name": resolveLlmTracingServiceName(env) }),
                     spanProcessors: [{
                             onStart: (span) => {
                                 // Directly pass the private parent claim to the processor. A
@@ -266,7 +298,7 @@ function createApiScorer(env, warn) {
                     username: env.LANGFUSE_PUBLIC_KEY,
                     password: env.LANGFUSE_SECRET_KEY,
                 });
-                return client.scores;
+                return client;
             }
             catch (error) {
                 warn(error, { stage: "score_init" });
@@ -281,15 +313,31 @@ function createApiScorer(env, warn) {
                 const api = await init();
                 if (!api)
                     return false;
-                await api.create(compact({
-                    id: body.id,
+                const payload = {
+                    ...(body.id ? { id: body.id } : {}),
                     traceId: body.traceId,
+                    ...(body.observationId ? { observationId: body.observationId } : {}),
                     name: body.name,
                     value: body.value,
-                    dataType: body.dataType,
-                    comment: typeof body.comment === "string" ? boundComment(body.comment) : undefined,
+                    ...(body.dataType ? { dataType: body.dataType } : {}),
+                    ...(typeof body.comment === "string" ? { comment: boundComment(body.comment) } : {}),
                     environment: resolveLlmTracingEnvironment(env),
-                }));
+                };
+                const requestOptions = { timeoutInSeconds: 5, maxRetries: 0 };
+                if (body.timestamp) {
+                    // POST /scores cannot carry a timestamp. Score ingestion remains
+                    // supported in v4 (unlike trace/observation ingestion) and preserves
+                    // the date component of the score's deduplication identity.
+                    if (!body.id || !Number.isFinite(body.timestamp.getTime()))
+                        return false;
+                    const eventId = randomUUID();
+                    const result = await api.ingestion.batch({ batch: [{
+                                type: "score-create", id: eventId, timestamp: body.timestamp.toISOString(), body: payload,
+                            }] }, requestOptions);
+                    // A 207 is transport success even if the event was rejected.
+                    return result.errors.length === 0 && result.successes.some((event) => event.id === eventId && event.status >= 200 && event.status < 300);
+                }
+                await api.scores.create(payload, requestOptions);
                 return true;
             }
             catch (error) {
@@ -398,6 +446,7 @@ export function createLlmTracingClient(env = process.env, options) {
         emitter.emit({
             kind,
             traceSeed: body.traceId,
+            ...(body.observationId ? { observationId: body.observationId } : {}),
             name: body.name,
             attributes: compact({
                 input: body.input,

package/node_modules/@oxygen/shared/dist/linkedin-countries.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The country vocabulary behind the CRM's "Primary Location — Country" column.
+ *
+ * WHY A CHECKED-IN TABLE AND NOT `Intl.DisplayNames` AT RUNTIME: these strings
+ * are persisted. They become `definition.options[].value` on the column and the
+ * literal text stored in every cell, so deriving them from ICU would let a Node
+ * upgrade silently rename an option and orphan every row that already carried
+ * the old spelling. The table was GENERATED from CLDR English region names once
+ * (the 249 officially assigned ISO 3166-1 alpha-2 codes, plus XK/Kosovo, which
+ * LinkedIn lists and ISO does not), then frozen here with the overrides below.
+ *
+ * NAMING: LinkedIn spells a handful differently from CLDR's English short name
+ * — those are the entries carrying a trailing comment. Everything else is the
+ * CLDR name verbatim, which is what LinkedIn uses. This is a faithful
+ * reproduction of LinkedIn's vocabulary, not a scrape of its dropdown: the
+ * RESOLVER below is what makes that safe, because it accepts the alpha-2 code,
+ * any spelling in this table, and the aliases in COUNTRY_ALIASES. A scrape that
+ * returns "US", "United States", "USA" or "Congo - Kinshasa" all land on the
+ * one canonical option rather than on an empty cell.
+ */
+/** Canonical LinkedIn country name for each ISO 3166-1 alpha-2 code, A→Z by name. */
+export declare const LINKEDIN_COUNTRIES: ReadonlyArray<readonly [code: string, name: string]>;
+/**
+ * Resolve a provider value — an alpha-2 code, a canonical name, or a known
+ * alias — to its canonical LinkedIn country name.
+ *
+ * Returns null for anything unrecognized, which is deliberate: the column is a
+ * select, so writing a value that is not one of its options would produce a
+ * cell no filter can match and no dropdown can show. An empty cell is the
+ * honest outcome, and the raw payload is still on the record.
+ */
+export declare function resolveLinkedInCountry(value: unknown): string | null;

package/node_modules/@oxygen/shared/dist/linkedin-countries.js

@@ -0,0 +1,359 @@
+/**
+ * The country vocabulary behind the CRM's "Primary Location — Country" column.
+ *
+ * WHY A CHECKED-IN TABLE AND NOT `Intl.DisplayNames` AT RUNTIME: these strings
+ * are persisted. They become `definition.options[].value` on the column and the
+ * literal text stored in every cell, so deriving them from ICU would let a Node
+ * upgrade silently rename an option and orphan every row that already carried
+ * the old spelling. The table was GENERATED from CLDR English region names once
+ * (the 249 officially assigned ISO 3166-1 alpha-2 codes, plus XK/Kosovo, which
+ * LinkedIn lists and ISO does not), then frozen here with the overrides below.
+ *
+ * NAMING: LinkedIn spells a handful differently from CLDR's English short name
+ * — those are the entries carrying a trailing comment. Everything else is the
+ * CLDR name verbatim, which is what LinkedIn uses. This is a faithful
+ * reproduction of LinkedIn's vocabulary, not a scrape of its dropdown: the
+ * RESOLVER below is what makes that safe, because it accepts the alpha-2 code,
+ * any spelling in this table, and the aliases in COUNTRY_ALIASES. A scrape that
+ * returns "US", "United States", "USA" or "Congo - Kinshasa" all land on the
+ * one canonical option rather than on an empty cell.
+ */
+/** Canonical LinkedIn country name for each ISO 3166-1 alpha-2 code, A→Z by name. */
+export const LINKEDIN_COUNTRIES = [
+    ["AF", "Afghanistan"],
+    ["AX", "Åland Islands"],
+    ["AL", "Albania"],
+    ["DZ", "Algeria"],
+    ["AS", "American Samoa"],
+    ["AD", "Andorra"],
+    ["AO", "Angola"],
+    ["AI", "Anguilla"],
+    ["AQ", "Antarctica"],
+    ["AG", "Antigua & Barbuda"],
+    ["AR", "Argentina"],
+    ["AM", "Armenia"],
+    ["AW", "Aruba"],
+    ["AU", "Australia"],
+    ["AT", "Austria"],
+    ["AZ", "Azerbaijan"],
+    ["BS", "Bahamas"],
+    ["BH", "Bahrain"],
+    ["BD", "Bangladesh"],
+    ["BB", "Barbados"],
+    ["BY", "Belarus"],
+    ["BE", "Belgium"],
+    ["BZ", "Belize"],
+    ["BJ", "Benin"],
+    ["BM", "Bermuda"],
+    ["BT", "Bhutan"],
+    ["BO", "Bolivia"],
+    ["BA", "Bosnia & Herzegovina"],
+    ["BW", "Botswana"],
+    ["BV", "Bouvet Island"],
+    ["BR", "Brazil"],
+    ["IO", "British Indian Ocean Territory"],
+    ["VG", "British Virgin Islands"],
+    ["BN", "Brunei"],
+    ["BG", "Bulgaria"],
+    ["BF", "Burkina Faso"],
+    ["BI", "Burundi"],
+    ["KH", "Cambodia"],
+    ["CM", "Cameroon"],
+    ["CA", "Canada"],
+    ["CV", "Cape Verde"],
+    ["BQ", "Caribbean Netherlands"],
+    ["KY", "Cayman Islands"],
+    ["CF", "Central African Republic"],
+    ["TD", "Chad"],
+    ["CL", "Chile"],
+    ["CN", "China"],
+    ["CX", "Christmas Island"],
+    ["CC", "Cocos (Keeling) Islands"],
+    ["CO", "Colombia"],
+    ["KM", "Comoros"],
+    ["CD", "Congo (DRC)"],
+    ["CG", "Congo (Republic)"],
+    ["CK", "Cook Islands"],
+    ["CR", "Costa Rica"],
+    ["CI", "Côte d'Ivoire"],
+    ["HR", "Croatia"],
+    ["CU", "Cuba"],
+    ["CW", "Curaçao"],
+    ["CY", "Cyprus"],
+    ["CZ", "Czechia"],
+    ["DK", "Denmark"],
+    ["DJ", "Djibouti"],
+    ["DM", "Dominica"],
+    ["DO", "Dominican Republic"],
+    ["EC", "Ecuador"],
+    ["EG", "Egypt"],
+    ["SV", "El Salvador"],
+    ["GQ", "Equatorial Guinea"],
+    ["ER", "Eritrea"],
+    ["EE", "Estonia"],
+    ["SZ", "Eswatini"],
+    ["ET", "Ethiopia"],
+    ["FK", "Falkland Islands"],
+    ["FO", "Faroe Islands"],
+    ["FJ", "Fiji"],
+    ["FI", "Finland"],
+    ["FR", "France"],
+    ["GF", "French Guiana"],
+    ["PF", "French Polynesia"],
+    ["TF", "French Southern Territories"],
+    ["GA", "Gabon"],
+    ["GM", "Gambia"],
+    ["GE", "Georgia"],
+    ["DE", "Germany"],
+    ["GH", "Ghana"],
+    ["GI", "Gibraltar"],
+    ["GR", "Greece"],
+    ["GL", "Greenland"],
+    ["GD", "Grenada"],
+    ["GP", "Guadeloupe"],
+    ["GU", "Guam"],
+    ["GT", "Guatemala"],
+    ["GG", "Guernsey"],
+    ["GN", "Guinea"],
+    ["GW", "Guinea-Bissau"],
+    ["GY", "Guyana"],
+    ["HT", "Haiti"],
+    ["HM", "Heard & McDonald Islands"],
+    ["HN", "Honduras"],
+    ["HK", "Hong Kong SAR"],
+    ["HU", "Hungary"],
+    ["IS", "Iceland"],
+    ["IN", "India"],
+    ["ID", "Indonesia"],
+    ["IR", "Iran"],
+    ["IQ", "Iraq"],
+    ["IE", "Ireland"],
+    ["IM", "Isle of Man"],
+    ["IL", "Israel"],
+    ["IT", "Italy"],
+    ["JM", "Jamaica"],
+    ["JP", "Japan"],
+    ["JE", "Jersey"],
+    ["JO", "Jordan"],
+    ["KZ", "Kazakhstan"],
+    ["KE", "Kenya"],
+    ["KI", "Kiribati"],
+    ["XK", "Kosovo"],
+    ["KW", "Kuwait"],
+    ["KG", "Kyrgyzstan"],
+    ["LA", "Laos"],
+    ["LV", "Latvia"],
+    ["LB", "Lebanon"],
+    ["LS", "Lesotho"],
+    ["LR", "Liberia"],
+    ["LY", "Libya"],
+    ["LI", "Liechtenstein"],
+    ["LT", "Lithuania"],
+    ["LU", "Luxembourg"],
+    ["MO", "Macao SAR"],
+    ["MG", "Madagascar"],
+    ["MW", "Malawi"],
+    ["MY", "Malaysia"],
+    ["MV", "Maldives"],
+    ["ML", "Mali"],
+    ["MT", "Malta"],
+    ["MH", "Marshall Islands"],
+    ["MQ", "Martinique"],
+    ["MR", "Mauritania"],
+    ["MU", "Mauritius"],
+    ["YT", "Mayotte"],
+    ["MX", "Mexico"],
+    ["FM", "Micronesia"],
+    ["MD", "Moldova"],
+    ["MC", "Monaco"],
+    ["MN", "Mongolia"],
+    ["ME", "Montenegro"],
+    ["MS", "Montserrat"],
+    ["MA", "Morocco"],
+    ["MZ", "Mozambique"],
+    ["MM", "Myanmar"],
+    ["NA", "Namibia"],
+    ["NR", "Nauru"],
+    ["NP", "Nepal"],
+    ["NL", "Netherlands"],
+    ["NC", "New Caledonia"],
+    ["NZ", "New Zealand"],
+    ["NI", "Nicaragua"],
+    ["NE", "Niger"],
+    ["NG", "Nigeria"],
+    ["NU", "Niue"],
+    ["NF", "Norfolk Island"],
+    ["KP", "North Korea"],
+    ["MK", "North Macedonia"],
+    ["MP", "Northern Mariana Islands"],
+    ["NO", "Norway"],
+    ["OM", "Oman"],
+    ["PK", "Pakistan"],
+    ["PW", "Palau"],
+    ["PS", "Palestinian Territories"],
+    ["PA", "Panama"],
+    ["PG", "Papua New Guinea"],
+    ["PY", "Paraguay"],
+    ["PE", "Peru"],
+    ["PH", "Philippines"],
+    ["PN", "Pitcairn Islands"],
+    ["PL", "Poland"],
+    ["PT", "Portugal"],
+    ["PR", "Puerto Rico"],
+    ["QA", "Qatar"],
+    ["RE", "Réunion"],
+    ["RO", "Romania"],
+    ["RU", "Russia"],
+    ["RW", "Rwanda"],
+    ["WS", "Samoa"],
+    ["SM", "San Marino"],
+    ["ST", "São Tomé & Príncipe"],
+    ["SA", "Saudi Arabia"],
+    ["SN", "Senegal"],
+    ["RS", "Serbia"],
+    ["SC", "Seychelles"],
+    ["SL", "Sierra Leone"],
+    ["SG", "Singapore"],
+    ["SX", "Sint Maarten"],
+    ["SK", "Slovakia"],
+    ["SI", "Slovenia"],
+    ["SB", "Solomon Islands"],
+    ["SO", "Somalia"],
+    ["ZA", "South Africa"],
+    ["GS", "South Georgia & South Sandwich Islands"],
+    ["KR", "South Korea"],
+    ["SS", "South Sudan"],
+    ["ES", "Spain"],
+    ["LK", "Sri Lanka"],
+    ["BL", "St. Barthélemy"],
+    ["SH", "St. Helena"],
+    ["KN", "St. Kitts & Nevis"],
+    ["LC", "St. Lucia"],
+    ["MF", "St. Martin"],
+    ["PM", "St. Pierre & Miquelon"],
+    ["VC", "St. Vincent & Grenadines"],
+    ["SD", "Sudan"],
+    ["SR", "Suriname"],
+    ["SJ", "Svalbard & Jan Mayen"],
+    ["SE", "Sweden"],
+    ["CH", "Switzerland"],
+    ["SY", "Syria"],
+    ["TW", "Taiwan"],
+    ["TJ", "Tajikistan"],
+    ["TZ", "Tanzania"],
+    ["TH", "Thailand"],
+    ["TL", "Timor-Leste"],
+    ["TG", "Togo"],
+    ["TK", "Tokelau"],
+    ["TO", "Tonga"],
+    ["TT", "Trinidad & Tobago"],
+    ["TN", "Tunisia"],
+    ["TR", "Türkiye"],
+    ["TM", "Turkmenistan"],
+    ["TC", "Turks & Caicos Islands"],
+    ["TV", "Tuvalu"],
+    ["UM", "U.S. Outlying Islands"],
+    ["VI", "U.S. Virgin Islands"],
+    ["UG", "Uganda"],
+    ["UA", "Ukraine"],
+    ["AE", "United Arab Emirates"],
+    ["GB", "United Kingdom"],
+    ["US", "United States"],
+    ["UY", "Uruguay"],
+    ["UZ", "Uzbekistan"],
+    ["VU", "Vanuatu"],
+    ["VA", "Vatican City"],
+    ["VE", "Venezuela"],
+    ["VN", "Vietnam"],
+    ["WF", "Wallis & Futuna"],
+    ["EH", "Western Sahara"],
+    ["YE", "Yemen"],
+    ["ZM", "Zambia"],
+    ["ZW", "Zimbabwe"],
+];
+/**
+ * Spellings a provider may return that are not the canonical name. Lowercased
+ * keys; the resolver lowercases its input before the lookup. Kept deliberately
+ * short — it covers the CLDR spellings this table overrides (so a payload
+ * carrying the un-overridden name still resolves), the common colloquial forms,
+ * and the alpha-3 codes, because Up2Data's `hq.country` is not contractually
+ * alpha-2 and has been observed carrying a display name.
+ */
+const COUNTRY_ALIASES = {
+    // CLDR spellings this table overrides.
+    "hong kong sar china": "HK",
+    "macao sar china": "MO",
+    "macau sar china": "MO",
+    "myanmar (burma)": "MM",
+    "congo - kinshasa": "CD",
+    "congo - brazzaville": "CG",
+    "côte d’ivoire": "CI",
+    "st. helena": "SH",
+    // Colloquial and legacy forms.
+    usa: "US",
+    "u.s.": "US",
+    "u.s.a.": "US",
+    "united states of america": "US",
+    uk: "GB",
+    "u.k.": "GB",
+    "great britain": "GB",
+    england: "GB",
+    scotland: "GB",
+    wales: "GB",
+    "northern ireland": "GB",
+    "czech republic": "CZ",
+    turkey: "TR",
+    "ivory coast": "CI",
+    burma: "MM",
+    swaziland: "SZ",
+    macedonia: "MK",
+    holland: "NL",
+    "the netherlands": "NL",
+    "south korea": "KR",
+    "korea, republic of": "KR",
+    "republic of korea": "KR",
+    "north korea": "KP",
+    "russian federation": "RU",
+    vatican: "VA",
+    "holy see": "VA",
+    palestine: "PS",
+    laos: "LA",
+    "cape verde": "CV",
+    "east timor": "TL",
+    uae: "AE",
+    "democratic republic of the congo": "CD",
+    "republic of the congo": "CG",
+    "hong kong": "HK",
+    macao: "MO",
+    macau: "MO",
+};
+const BY_CODE = new Map(LINKEDIN_COUNTRIES.map(([code, name]) => [code, name]));
+const BY_LOWER_NAME = new Map(LINKEDIN_COUNTRIES.map(([code, name]) => [name.toLowerCase(), code]));
+/**
+ * Resolve a provider value — an alpha-2 code, a canonical name, or a known
+ * alias — to its canonical LinkedIn country name.
+ *
+ * Returns null for anything unrecognized, which is deliberate: the column is a
+ * select, so writing a value that is not one of its options would produce a
+ * cell no filter can match and no dropdown can show. An empty cell is the
+ * honest outcome, and the raw payload is still on the record.
+ */
+export function resolveLinkedInCountry(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    const upper = trimmed.toUpperCase();
+    if (upper.length === 2) {
+        const direct = BY_CODE.get(upper);
+        if (direct)
+            return direct;
+    }
+    const lower = trimmed.toLowerCase();
+    const byName = BY_LOWER_NAME.get(lower);
+    if (byName)
+        return BY_CODE.get(byName) ?? null;
+    const aliased = COUNTRY_ALIASES[lower];
+    return aliased ? BY_CODE.get(aliased) ?? null : null;
+}

package/node_modules/@oxygen/shared/dist/log-sink-selector.d.ts

@@ -0,0 +1,39 @@
+import type { LogSink } from "./log.js";
+/**
+ * Which transport(s) `log()` records leave the process on.
+ *
+ * Portability selector (`.agents/skills/oxygen-platform-portability/SKILL.md`):
+ * one concern, one variable, and **unset means managed**. An environment that
+ * sets nothing keeps today's behaviour exactly — the Axiom shipper alone, with
+ * the same handle and the same drain — so this can land on `dev` and flow to
+ * managed production with no flag day. Self-hosted opts in with `otlp` (an
+ * OTLP/HTTP collector instead of Axiom) or `both` (during a cutover window,
+ * when the two stores must be comparable before Axiom is switched off).
+ *
+ * An unrecognised value resolves to `axiom` rather than throwing: a typo in a
+ * telemetry variable must not decide whether a process boots.
+ */
+export type LogSinkSelector = "axiom" | "otlp" | "both";
+export declare function resolveLogSinkSelector(env?: NodeJS.ProcessEnv): LogSinkSelector;
+export declare function logSinkSelectorIncludesAxiom(selector: LogSinkSelector): boolean;
+export declare function logSinkSelectorIncludesOtlp(selector: LogSinkSelector): boolean;
+/**
+ * Failed sink invocations swallowed by a composed sink since process start.
+ *
+ * A composed sink cannot report its own failure through `log()` — it IS what
+ * `log()` calls, so logging from it would recurse. The count is the honest
+ * alternative to silence: readable from a diagnostic surface without the
+ * failing transport ever getting a second chance to throw.
+ */
+export declare function composedLogSinkFailureCount(): number;
+/**
+ * Fans one record out to several transports.
+ *
+ * Every sink is called, in order, and each is wrapped: `both` exists precisely
+ * for the window where one of the two stores is not trusted yet, so a throwing
+ * Axiom sink must not stop the OTLP one from receiving the record (or the
+ * reverse). Nulls are dropped, so a caller can pass an adapter that declined to
+ * start without branching; all-null composes to `null`, which `setLogSink`
+ * reads as "no sink" and which keeps `log()` on its plain stdout path.
+ */
+export declare function composeLogSinks(...sinks: Array<LogSink | null | undefined>): LogSink | null;

package/node_modules/@oxygen/shared/dist/log-sink-selector.js

@@ -0,0 +1,56 @@
+export function resolveLogSinkSelector(env = process.env) {
+    const configured = env.OXYGEN_LOG_SINK?.trim().toLowerCase();
+    if (configured === "otlp")
+        return "otlp";
+    if (configured === "both")
+        return "both";
+    return "axiom";
+}
+export function logSinkSelectorIncludesAxiom(selector) {
+    return selector === "axiom" || selector === "both";
+}
+export function logSinkSelectorIncludesOtlp(selector) {
+    return selector === "otlp" || selector === "both";
+}
+let composedSinkFailures = 0;
+/**
+ * Failed sink invocations swallowed by a composed sink since process start.
+ *
+ * A composed sink cannot report its own failure through `log()` — it IS what
+ * `log()` calls, so logging from it would recurse. The count is the honest
+ * alternative to silence: readable from a diagnostic surface without the
+ * failing transport ever getting a second chance to throw.
+ */
+export function composedLogSinkFailureCount() {
+    return composedSinkFailures;
+}
+/**
+ * Fans one record out to several transports.
+ *
+ * Every sink is called, in order, and each is wrapped: `both` exists precisely
+ * for the window where one of the two stores is not trusted yet, so a throwing
+ * Axiom sink must not stop the OTLP one from receiving the record (or the
+ * reverse). Nulls are dropped, so a caller can pass an adapter that declined to
+ * start without branching; all-null composes to `null`, which `setLogSink`
+ * reads as "no sink" and which keeps `log()` on its plain stdout path.
+ */
+export function composeLogSinks(...sinks) {
+    const active = sinks.filter((sink) => typeof sink === "function");
+    if (active.length === 0)
+        return null;
+    const only = active[0];
+    if (active.length === 1 && only)
+        return only;
+    return (record) => {
+        for (const sink of active) {
+            try {
+                sink(record);
+            }
+            catch {
+                // Telemetry must never break the code it observes, and this is the one
+                // place that cannot say so out loud (see composedLogSinkFailureCount).
+                composedSinkFailures += 1;
+            }
+        }
+    };
+}

package/node_modules/@oxygen/shared/dist/log.d.ts

@@ -19,6 +19,7 @@ export declare function enterLogContext(ctx: LogContext): void;
 export declare function logLevelForHttpStatus(status: number): LogLevel;
 export type LogSink = (record: Record<string, unknown>) => void;
 export declare function setLogSink(sink: LogSink | null): void;
+export declare function getLogSink(): LogSink | null;
 export declare function log(level: LogLevel, msg: string, fields?: Record<string, unknown>): void;
 export declare function errorId(err: unknown): string;
 export declare function errorFields(err: unknown): Record<string, unknown>;

package/node_modules/@oxygen/shared/dist/log.js

@@ -118,7 +118,12 @@ const LOG_SINK_SLOT = Symbol.for("oxygen.log.sink");
 export function setLogSink(sink) {
     globalThis[LOG_SINK_SLOT] = sink;
 }
-function getLogSink() {
+// Exported so a second transport can COMPOSE with the sink already registered
+// rather than replacing it: under `OXYGEN_LOG_SINK=both` the OTLP adapter starts
+// after the Axiom shipper has claimed the slot, and reading the slot back is what
+// lets it fan out to both (`log-sink-selector.ts`). Reading through this function,
+// not the raw Symbol, keeps the slot's location owned by exactly one module.
+export function getLogSink() {
     return globalThis[LOG_SINK_SLOT] ?? null;
 }
 const LEVEL_RANK = { debug: 10, info: 20, warn: 30, error: 40 };