@oxygen-agent/cli 1.987.20 → 1.1010.1

package/node_modules/@oxygen/shared/dist/llm-prompts.js

@@ -0,0 +1,161 @@
+// Prompt identity for LLM tracing (ADR 0014). Prompts stay in code or in the
+// tenant database; nothing here is fetched at runtime to BUILD a prompt, so a
+// Langfuse outage can never leave a model call without its instructions.
+//
+// Every traced model call carries a prompt reference: a stable name plus a
+// content hash of the template it was rendered from. Code-owned templates are
+// declared once with `defineLlmPrompt` and are REGISTERED — the deploy-time sync
+// (`scripts/ops/langfuse-prompts-sync.mjs`) publishes each one to Langfuse
+// Prompt Management under the label `oxygen-<hash>`, which lets the tracing
+// client link generations to the native prompt version. Customer-authored
+// templates (table AI columns, Agent instructions, message templates) get an
+// unregistered reference: name + hash as metadata only, never published.
+import { createHash } from "node:crypto";
+const NAME_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z0-9_]+)+$/;
+const registry = new Map();
+const conflicts = new Set();
+function canonical(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${typeof entry === "string" ? JSON.stringify(entry) : canonical(entry)}`).join(",")}}`;
+    }
+    return JSON.stringify(value ?? null);
+}
+/** Deterministic content hash; object key order never changes it. */
+export function llmPromptHash(template) {
+    return createHash("sha256").update(canonical(template), "utf8").digest("hex").slice(0, 12);
+}
+/** The Langfuse label that identifies one exact template version. */
+export function llmPromptLabel(hash) {
+    return `oxygen-${hash}`;
+}
+/**
+ * Declare a code-owned prompt template. Call once at module scope with the
+ * template the call site renders from. Placeholders stay literal (`{{name}}`)
+ * so the hash moves only when the instructions do, not per request.
+ */
+export function defineLlmPrompt(name, template) {
+    // Never throws: this runs at module scope in production code. The catalog
+    // test (llm-prompt-catalog.test.ts) enforces valid, unique, non-empty names.
+    const definition = { name, hash: llmPromptHash(template), registered: true, template };
+    const existing = registry.get(name);
+    if (existing && existing.hash !== definition.hash)
+        conflicts.add(name);
+    registry.set(name, definition);
+    return definition;
+}
+/** Names declared twice with different templates (a catalog defect). */
+export function conflictingLlmPromptNames() {
+    return [...conflicts].sort();
+}
+/** The Langfuse-safe name shape code prompts must use. */
+export function isValidLlmPromptName(name) {
+    return NAME_PATTERN.test(name);
+}
+/**
+ * An AI column's prompt as the text Langfuse stores: the instruction template
+ * (placeholders unresolved) plus its output schema, so a schema change is a new
+ * prompt version too. Customer columns and code-owned helpers share it.
+ */
+export function aiColumnPromptTemplate(definition) {
+    const prompt = typeof definition.prompt === "string" ? definition.prompt : JSON.stringify(definition.prompt ?? null);
+    return definition.outputSchema == null
+        ? prompt
+        : `${prompt}\n\nOUTPUT SCHEMA\n${JSON.stringify(definition.outputSchema, null, 2)}`;
+}
+/** Declare a code-owned AI helper prompt (knowledge synthesis, drafts, ...). */
+export function defineAiColumnPrompt(name, definition) {
+    return defineLlmPrompt(name, aiColumnPromptTemplate(definition));
+}
+/**
+ * Resolve a lazy prompt getter on a product path. Prompt identity is telemetry:
+ * a template renderer that throws must degrade to an unlinked trace, never
+ * fail the model call it describes.
+ */
+export function safeLlmPrompt(getter) {
+    try {
+        return getter();
+    }
+    catch {
+        return null;
+    }
+}
+/** Reference a customer-authored or per-request template: metadata only. */
+export function llmPromptRef(name, template) {
+    return { name, hash: llmPromptHash(template), registered: false };
+}
+/**
+ * The registered code prompt whose template is exactly this text, if any: lets
+ * a tracer that only sees the rendered system message recognise a static
+ * template (compaction, sub-agent instructions) without importing its owner.
+ */
+export function findLlmPromptByTemplate(template) {
+    const hash = llmPromptHash(template);
+    for (const definition of registry.values())
+        if (definition.hash === hash)
+            return definition;
+    return undefined;
+}
+/**
+ * The declared code prompt behind a reference, only when its template still
+ * hashes to that reference: lets the tracing client publish the exact text a
+ * generation was rendered from, and never a same-named neighbour.
+ */
+export function registeredLlmPrompt(ref) {
+    if (!ref.registered)
+        return undefined;
+    const definition = registry.get(ref.name);
+    return definition?.hash === ref.hash ? definition : undefined;
+}
+/** Every code prompt declared by the modules imported so far, sorted by name. */
+export function listLlmPrompts() {
+    return [...registry.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+function systemTexts(messages) {
+    if (!Array.isArray(messages))
+        return [];
+    const texts = [];
+    for (const message of messages) {
+        if (!message || typeof message !== "object" || message.role !== "system")
+            continue;
+        const content = message.content;
+        if (typeof content === "string")
+            texts.push(content);
+        else if (Array.isArray(content)) {
+            const text = content
+                .map((part) => (part && typeof part === "object" && typeof part.text === "string" ? part.text : ""))
+                .join("");
+            if (text)
+                texts.push(text);
+        }
+    }
+    return texts;
+}
+/**
+ * The prompt a Copilot/Agent model call ran on, from the exact messages sent.
+ * A main-loop call (`kind` "turn") uses the surface's versioned system
+ * template; compaction and sub-agent calls match a registered static template
+ * by the content of one of their system messages; anything else is traced by
+ * content hash only.
+ */
+export function llmPromptForModelCall(input) {
+    if (input.kind === "turn" && input.turnPrompt)
+        return input.turnPrompt;
+    const texts = systemTexts(input.messages);
+    if (texts.length === 0)
+        return input.turnPrompt ?? null;
+    if (input.kind !== "turn") {
+        for (const text of texts) {
+            const registered = findLlmPromptByTemplate(text);
+            if (registered)
+                return registered;
+        }
+    }
+    return llmPromptRef(`${input.surface}.${input.kind === "turn" ? "system" : input.kind}`, texts.join("\n\n"));
+}

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 };

package/node_modules/@oxygen/shared/dist/mailbox-egress-ownership.d.ts

@@ -0,0 +1,90 @@
+export declare const MAILBOX_EGRESS_MODE_ENV = "OXYGEN_MAILBOX_EGRESS_MODE";
+export type MailboxEgressMode = "direct" | "proxy";
+/** `proxy` only when explicitly selected; anything else keeps today's transport. */
+export declare function readMailboxEgressMode(env?: NodeJS.ProcessEnv): MailboxEgressMode;
+export type DedicatedEgressInventoryRow = {
+    id: string;
+    organizationId: string | null;
+    status: string;
+    createdAt: Date | null;
+    vendorVerifiedAt: Date | null;
+    metadata: Record<string, unknown> | null;
+};
+export type DedicatedEgressReadinessInput = {
+    createdAt: Date | null;
+    environment: "dev" | "prod";
+    metadata: Record<string, unknown> | null;
+    vendorVerifiedAt: Date | null;
+};
+export type DedicatedEgressOwnershipSnapshot = {
+    activeOrganizationIds: ReadonlySet<string>;
+    /** Every recent retirement marker is re-evaluated on every read. */
+    retiredMetadataByOrganization: ReadonlyMap<string, readonly Record<string, unknown>[]>;
+    /** Present only when exactly one active, entitled row exists for the organization. */
+    readinessInputByOrganization: ReadonlyMap<string, DedicatedEgressReadinessInput>;
+};
+export type DedicatedEgressClassification = DedicatedEgressOwnershipSnapshot & {
+    /** Two active apps could race the same org through different IPs. */
+    conflicts: {
+        organizationId: string;
+        activeIds: string[];
+    }[];
+    /** Active inventory whose add-on entitlement is not live. */
+    entitlementMissing: {
+        organizationId: string;
+        activeId: string;
+    }[];
+};
+export type DedicatedEgressOwnership = {
+    /** Active or still-cooling dedicated inventory: never the shared IP. */
+    ownedOrganizationIds: ReadonlySet<string>;
+    /** Exact active and ready Fly app for each org; org identity alone is insufficient. */
+    readyAppNameByOrganization: ReadonlyMap<string, string>;
+};
+/**
+ * Classify `status in (active, retired)` dedicated Fly rows for one environment
+ * plus the orgs holding a live `dedicated_egress_ip` add-on. Entitlement is
+ * conservative ownership evidence: a paying org whose inventory row is missing
+ * still stays off the shared IP while its dedicated transport also blocks.
+ */
+export declare function classifyDedicatedEgressInventory(input: {
+    rows: readonly DedicatedEgressInventoryRow[];
+    entitledOrganizationIds: ReadonlySet<string>;
+    environment: "dev" | "prod";
+    now: number;
+}): DedicatedEgressClassification;
+/**
+ * Ownership at `now`. Re-evaluated on every read of a cached snapshot, because
+ * caching a readiness boolean would extend a liveness grant past its expiry.
+ */
+export declare function evaluateDedicatedEgressOwnership(snapshot: DedicatedEgressOwnershipSnapshot, now: number): DedicatedEgressOwnership;
+export type MailboxEgressRoute = 
+/** Leave from this process's own address (direct mode only). */
+{
+    kind: "direct";
+}
+/** Tunnel through the proxy Machine of this Fly app, which owns the IP. */
+ | {
+    kind: "proxy";
+    appName: string;
+    tier: "shared" | "dedicated";
+}
+/** No transport may carry this org right now. Fail closed: never fall back. */
+ | {
+    kind: "blocked";
+    reason: "dedicated_egress_not_ready" | "ownership_unreadable";
+};
+export declare const MAILBOX_EGRESS_SHARED_APP_ENV = "OXYGEN_MAILBOX_EGRESS_SHARED_APP";
+/**
+ * The Fly app whose static egress IP carries every non-dedicated org. Dev sets
+ * OXYGEN_MAILBOX_EGRESS_SHARED_APP=oxygen-table-worker-prod and tunnels through
+ * the production shared proxy (founder decision 2026-09-25: Fly holds only
+ * production proxies). Web and worker read the same value, so they agree.
+ */
+export declare function sharedMailboxEgressAppName(environment: "dev" | "prod", env?: NodeJS.ProcessEnv): string;
+/**
+ * The proxy-mode route for one org. A dedicated org uses its own app once ready
+ * and is blocked until then: routing it through the shared IP, even briefly,
+ * would show its mailboxes a second, shared source address.
+ */
+export declare function mailboxEgressRouteFor(organizationId: string, ownership: DedicatedEgressOwnership | null, environment: "dev" | "prod"): MailboxEgressRoute;

package/node_modules/@oxygen/shared/dist/mailbox-egress-ownership.js

@@ -0,0 +1,130 @@
+/**
+ * Which static egress IP may carry an organization's mailbox traffic, as pure
+ * functions over control-plane rows. The worker (every org, cached) and the web
+ * app (one org, per request) must reach the same answer from the same rows, so
+ * the classification lives here rather than in either process.
+ *
+ * Two transports read it. In `direct` mode the process's own IP carries shared
+ * orgs and a dedicated org's own Fly drain carries it. In `proxy` mode every
+ * process tunnels through the one Fly proxy Machine that owns the right IP:
+ * `oxygen-table-worker-<env>` for shared orgs, the org's own dedicated app
+ * otherwise (ADR 0029 amendment 2026-09-25).
+ */
+import { dedicatedEgressRetirementStillCooling, evaluateFlyDedicatedEgressTransportReadiness, } from "./egress-transport-readiness.js";
+export const MAILBOX_EGRESS_MODE_ENV = "OXYGEN_MAILBOX_EGRESS_MODE";
+/** `proxy` only when explicitly selected; anything else keeps today's transport. */
+export function readMailboxEgressMode(env = process.env) {
+    return env[MAILBOX_EGRESS_MODE_ENV]?.trim().toLowerCase() === "proxy" ? "proxy" : "direct";
+}
+/**
+ * Classify `status in (active, retired)` dedicated Fly rows for one environment
+ * plus the orgs holding a live `dedicated_egress_ip` add-on. Entitlement is
+ * conservative ownership evidence: a paying org whose inventory row is missing
+ * still stays off the shared IP while its dedicated transport also blocks.
+ */
+export function classifyDedicatedEgressInventory(input) {
+    const rowsByOrganization = new Map();
+    for (const row of input.rows) {
+        if (!row.organizationId)
+            continue;
+        const current = rowsByOrganization.get(row.organizationId) ?? [];
+        current.push(row);
+        rowsByOrganization.set(row.organizationId, current);
+    }
+    const activeOrganizationIds = new Set(input.entitledOrganizationIds);
+    const retiredMetadataByOrganization = new Map();
+    const readinessInputByOrganization = new Map();
+    const conflicts = [];
+    const entitlementMissing = [];
+    for (const [organizationId, organizationRows] of rowsByOrganization) {
+        const activeRows = organizationRows.filter((row) => row.status === "active");
+        const coolingRetiredRows = organizationRows.filter((row) => row.status === "retired" && dedicatedEgressRetirementStillCooling(row.metadata, input.now));
+        // Shared must keep excluding the org, but no dedicated transport may carry it
+        // while two active apps could race its jobs through different source IPs. A
+        // just-retired row also keeps shared away for one handoff window.
+        if (activeRows.length > 0)
+            activeOrganizationIds.add(organizationId);
+        if (coolingRetiredRows.length > 0) {
+            // Preserve every marker: picking one unordered row could choose an older
+            // retirement and hand the org back while a newer app's cache is alive.
+            retiredMetadataByOrganization.set(organizationId, coolingRetiredRows.map((row) => row.metadata ?? {}));
+        }
+        if (activeRows.length !== 1) {
+            if (activeRows.length > 1) {
+                conflicts.push({ organizationId, activeIds: activeRows.map((row) => row.id) });
+            }
+            continue;
+        }
+        const row = activeRows[0];
+        if (!input.entitledOrganizationIds.has(organizationId)) {
+            entitlementMissing.push({ organizationId, activeId: row.id });
+            continue;
+        }
+        readinessInputByOrganization.set(organizationId, {
+            createdAt: row.createdAt,
+            environment: input.environment,
+            metadata: row.metadata,
+            vendorVerifiedAt: row.vendorVerifiedAt,
+        });
+    }
+    return {
+        activeOrganizationIds,
+        retiredMetadataByOrganization,
+        readinessInputByOrganization,
+        conflicts,
+        entitlementMissing,
+    };
+}
+/**
+ * Ownership at `now`. Re-evaluated on every read of a cached snapshot, because
+ * caching a readiness boolean would extend a liveness grant past its expiry.
+ */
+export function evaluateDedicatedEgressOwnership(snapshot, now) {
+    const ownedOrganizationIds = new Set(snapshot.activeOrganizationIds);
+    for (const [organizationId, metadataRows] of snapshot.retiredMetadataByOrganization) {
+        if (metadataRows.some((metadata) => dedicatedEgressRetirementStillCooling(metadata, now))) {
+            ownedOrganizationIds.add(organizationId);
+        }
+    }
+    const readyAppNameByOrganization = new Map();
+    for (const [organizationId, readinessInput] of snapshot.readinessInputByOrganization) {
+        const readiness = evaluateFlyDedicatedEgressTransportReadiness(readinessInput, now);
+        if (readiness.ready)
+            readyAppNameByOrganization.set(organizationId, readiness.appName);
+    }
+    return { ownedOrganizationIds, readyAppNameByOrganization };
+}
+export const MAILBOX_EGRESS_SHARED_APP_ENV = "OXYGEN_MAILBOX_EGRESS_SHARED_APP";
+const FLY_APP_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{1,62}$/;
+/**
+ * The Fly app whose static egress IP carries every non-dedicated org. Dev sets
+ * OXYGEN_MAILBOX_EGRESS_SHARED_APP=oxygen-table-worker-prod and tunnels through
+ * the production shared proxy (founder decision 2026-09-25: Fly holds only
+ * production proxies). Web and worker read the same value, so they agree.
+ */
+export function sharedMailboxEgressAppName(environment, env = process.env) {
+    const override = env[MAILBOX_EGRESS_SHARED_APP_ENV]?.trim();
+    if (override) {
+        if (!FLY_APP_NAME_PATTERN.test(override)) {
+            throw new Error(`${MAILBOX_EGRESS_SHARED_APP_ENV} is not a Fly app name`);
+        }
+        return override;
+    }
+    return `oxygen-table-worker-${environment}`;
+}
+/**
+ * The proxy-mode route for one org. A dedicated org uses its own app once ready
+ * and is blocked until then: routing it through the shared IP, even briefly,
+ * would show its mailboxes a second, shared source address.
+ */
+export function mailboxEgressRouteFor(organizationId, ownership, environment) {
+    if (!ownership)
+        return { kind: "blocked", reason: "ownership_unreadable" };
+    const dedicatedApp = ownership.readyAppNameByOrganization.get(organizationId);
+    if (dedicatedApp)
+        return { kind: "proxy", appName: dedicatedApp, tier: "dedicated" };
+    if (ownership.ownedOrganizationIds.has(organizationId)) {
+        return { kind: "blocked", reason: "dedicated_egress_not_ready" };
+    }
+    return { kind: "proxy", appName: sharedMailboxEgressAppName(environment), tier: "shared" };
+}

package/node_modules/@oxygen/shared/dist/object-storage.d.ts

@@ -5,6 +5,23 @@ export declare function resolveObjectStorageClient(): {
     client: S3Client;
     bucket: string;
 };
+/**
+ * The same endpoint and credentials, aimed at a DIFFERENT bucket.
+ *
+ * Every namespace above shares one private bucket because they share one access
+ * story: org-scoped keys, no anonymous reads. Public blobs (agency-directory
+ * logos; Payload media reaches the same bucket through its own plugin) are the
+ * opposite — their bytes are fetched by browsers with no credential at all — so
+ * on a self-hosted deploy they belong in a bucket whose read policy is public,
+ * never in the one holding customer lead lists.
+ * Same S3 account, different bucket: hence the client is reused and only the
+ * bucket is overridden. Empty is refused rather than silently falling back to
+ * the import bucket, which is exactly the mix-up this split exists to prevent.
+ */
+export declare function resolveObjectStorageClientForBucket(bucket: string): {
+    client: S3Client;
+    bucket: string;
+};
 export declare function buildImportObjectKey(input: {
     organizationId: string;
     fileName?: string | null;

package/node_modules/@oxygen/shared/dist/object-storage.js

@@ -82,6 +82,27 @@ export function resolveObjectStorageClient() {
     const { client, config } = resolveClient();
     return { client, bucket: config.bucket };
 }
+/**
+ * The same endpoint and credentials, aimed at a DIFFERENT bucket.
+ *
+ * Every namespace above shares one private bucket because they share one access
+ * story: org-scoped keys, no anonymous reads. Public blobs (agency-directory
+ * logos; Payload media reaches the same bucket through its own plugin) are the
+ * opposite — their bytes are fetched by browsers with no credential at all — so
+ * on a self-hosted deploy they belong in a bucket whose read policy is public,
+ * never in the one holding customer lead lists.
+ * Same S3 account, different bucket: hence the client is reused and only the
+ * bucket is overridden. Empty is refused rather than silently falling back to
+ * the import bucket, which is exactly the mix-up this split exists to prevent.
+ */
+export function resolveObjectStorageClientForBucket(bucket) {
+    const target = bucket.trim();
+    if (!target) {
+        throw new OxygenError("object_storage_bucket_missing", "No object-storage bucket was resolved for this operation.", { exitCode: 1 });
+    }
+    const { client } = resolveClient();
+    return { client, bucket: target };
+}
 export function buildImportObjectKey(input) {
     const safeName = sanitizeFileName(input.fileName) || "import";
     return `imports/${input.organizationId}/${randomUUID()}/${safeName}`;

package/node_modules/@oxygen/shared/dist/operational-telemetry.d.ts

@@ -0,0 +1,24 @@
+type AttributeContainer = {
+    attributes?: Record<string, unknown>;
+    name?: string;
+};
+/** Sink-local copy; the managed logger retains its original record. */
+export declare function operationalLogSnapshot(record: Record<string, unknown>): Record<string, unknown>;
+/** Export a sanitized copy; never mutate the span another destination reads. */
+export declare function operationalSpanSnapshot<T extends {
+    name: string;
+    attributes: Record<string, unknown>;
+    status: {
+        code: number;
+        message?: string;
+    };
+    events: ReadonlyArray<{
+        name: string;
+        attributes?: Record<string, unknown>;
+    }>;
+    links?: ReadonlyArray<AttributeContainer>;
+    resource?: AttributeContainer;
+    instrumentationScope?: AttributeContainer;
+    spanContext(): unknown;
+}>(span: T): T;
+export {};

package/node_modules/@oxygen/shared/dist/operational-telemetry.js

@@ -0,0 +1,73 @@
+import { normalizeTelemetryAttributes, redactSecretsInString } from "./redaction.js";
+// Namespaced semantic-convention fields evade the generic exact-key log policy.
+// Numeric usage remains operational data, subject to the shared secret policy.
+const PAYLOAD_KEY = /(?:^|[._-])(?:prompts?|completions?|inputs?|outputs?|payloads?|rows?|messages?|content|body|customer_data)(?:$|[._-])|^(?:request|response)$/i;
+const EXCEPTION_CONTENT = /^exception\.(?:message|stacktrace)$/i;
+const QUERY_CONTENT = /^(?:db\.(?:statement|query\.text)(?:[._].*)?|(?:http|url)\.(?:query|query_string|request\.query)|process\.command(?:_args|_line)?)$/i;
+// Addresses keep their domain (the operational signal) and drop the person.
+const EMAIL_ADDRESS = /[A-Za-z0-9._%+-]+@((?:[A-Za-z0-9-]+\.)+[A-Za-z]{2,})/g;
+function maskEmails(value) {
+    return value.replace(EMAIL_ADDRESS, "***@$1");
+}
+function operationalText(value) {
+    return maskEmails(redactSecretsInString(value).replace(/(?:https?:\/\/|\/)[^\s"'<>]+/gi, stripOperationalUrl));
+}
+function operationalValue(value, key, depth = 0) {
+    if (PAYLOAD_KEY.test(key) && typeof value !== "number" && typeof value !== "boolean")
+        return "[omitted]";
+    if (typeof value === "string")
+        return /(?:^|[._-])(?:url|path|target|href)(?:$|[._-])/i.test(key)
+            ? maskEmails(stripOperationalUrl(redactSecretsInString(value))) : operationalText(value);
+    if (!value || typeof value !== "object")
+        return value;
+    if (depth >= 5)
+        return "[truncated]";
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.slice(0, 20).map((entry) => operationalValue(entry, key, depth + 1));
+    return Object.fromEntries(Object.entries(value).slice(0, 40)
+        .filter(([child]) => !EXCEPTION_CONTENT.test(child) && !QUERY_CONTENT.test(child))
+        .map(([child, entry]) => [child, operationalValue(entry, child, depth + 1)]));
+}
+function operationalAttributes(attributes) {
+    return normalizeTelemetryAttributes(Object.fromEntries(Object.entries(attributes ?? {}).slice(0, 40)
+        .filter(([key]) => !EXCEPTION_CONTENT.test(key) && !QUERY_CONTENT.test(key))
+        .map(([key, value]) => [key, operationalValue(value, key)])));
+}
+/** Sink-local copy; the managed logger retains its original record. */
+export function operationalLogSnapshot(record) {
+    return operationalAttributes(record);
+}
+function containerSnapshot(container) {
+    return { ...container, attributes: operationalAttributes(container.attributes) };
+}
+/** Export a sanitized copy; never mutate the span another destination reads. */
+export function operationalSpanSnapshot(span) {
+    const attributes = operationalAttributes(span.attributes);
+    // Exception messages/stacks can contain arbitrary customer payloads. Error
+    // classification lives on the span's structured attributes and correlated log.
+    return {
+        ...span,
+        spanContext: () => span.spanContext(),
+        name: operationalText(span.name),
+        attributes,
+        status: { code: span.status.code },
+        events: span.events.map((event) => ({
+            ...containerSnapshot(event),
+            name: operationalText(event.name),
+        })),
+        ...(span.links ? { links: span.links.map(containerSnapshot) } : {}),
+        ...(span.resource ? { resource: containerSnapshot(span.resource) } : {}),
+        ...(span.instrumentationScope ? { instrumentationScope: containerSnapshot(span.instrumentationScope) } : {}),
+    };
+}
+function stripOperationalUrl(value) {
+    try {
+        const url = new URL(value);
+        return `${url.origin}${url.pathname}`;
+    }
+    catch {
+        return value.split(/[?#]/, 1)[0] ?? "";
+    }
+}