@oxygen-agent/cli 1.922.14 → 1.936.1

package/dist/visual-commands.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "commander";
+type JsonOptions = {
+    json?: boolean;
+};
+export declare function registerVisualCommands(program: Command, handle: (command: string, options: JsonOptions, action: () => Promise<unknown>) => Promise<void>): void;
+export {};

package/dist/visual-commands.js

@@ -0,0 +1,57 @@
+import { createHash } from "node:crypto";
+import { readFileSync, statSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { OxygenError } from "@oxygen/shared";
+import { requestOxygen } from "./http-client.js";
+import { waitForVisualRender } from "./visual-render-wait.js";
+export function registerVisualCommands(program, handle) {
+    const visuals = program.command("visuals").description("Author, render, inspect and download GTM infographics using tenant workspace files and governed render jobs.");
+    visuals.command("source-create").description("Save an immutable HTML/CSS/SVG source revision; no code executes.")
+        .requiredOption("--name <name>", "Workspace filename.")
+        .requiredOption("--file <path>", "Local HTML source file (max 1.5 MB).")
+        .option("--parent-file-id <id>", "Previous source revision UUID.").option("--json", "Print a JSON envelope.")
+        .action((options) => handle("visuals source create", options, async () => {
+        if (statSync(options.file).size > 1_500_000)
+            throw new OxygenError("visual_source_limit", "HTML source must fit within 1.5 MB.");
+        const bytes = readFileSync(options.file);
+        if (bytes.length > 1_500_000)
+            throw new OxygenError("visual_source_limit", "HTML source must fit within 1.5 MB.");
+        return requestOxygen("/api/cli/visuals/sources", { method: "POST", body: { name: options.name, html: bytes.toString("utf8"), ...(options.parentFileId ? { parent_file_id: options.parentFileId } : {}) } });
+    }));
+    visuals.command("file-get <file-id>").description("Read source, file metadata, provenance and web/download links.").option("--json", "Print a JSON envelope.")
+        .action((id, options) => handle("visuals file get", options, () => requestOxygen(`/api/cli/visuals/files/${encodeURIComponent(id)}`)));
+    visuals.command("download <file-id>").description("Download a file with SHA-256 verification; refuses to overwrite existing local files.")
+        .requiredOption("--out <path>", "New local destination filename.").option("--json", "Print a JSON envelope.")
+        .action((id, options) => handle("visuals download", options, async () => {
+        const path = `/api/cli/visuals/files/${encodeURIComponent(id)}`;
+        const data = await requestOxygen(path);
+        const bytes = await requestOxygen(`${path}/download`, { binaryMaxBytes: Math.max(1, data.file.size_bytes) });
+        if (bytes.length !== data.file.size_bytes || createHash("sha256").update(bytes).digest("hex") !== data.file.sha256)
+            throw new OxygenError("file_integrity", "Downloaded bytes do not match the workspace file hash.");
+        writeFileSync(options.out, bytes, { flag: "wx", mode: 0o600 });
+        return { path: resolve(options.out), ...data.file };
+    }));
+    visuals.command("render-preview").description("Preview rendering without starting paid compute.")
+        .requiredOption("--source-file-ids <ids>", "Comma-separated HTML file UUIDs in page order.")
+        .option("--width <pixels>", "CSS pixel width.", "1080").option("--height <pixels>", "CSS pixel height.", "1350")
+        .option("--scale <1|2>", "PNG scale.", "1").option("--formats <png,pdf>", "Output formats.", "png")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("visuals render preview", options, () => requestOxygen("/api/cli/visuals/renders", { method: "POST", body: { source_file_ids: options.sourceFileIds.split(",").map((s) => s.trim()), width: Number(options.width), height: Number(options.height), scale: Number(options.scale), formats: options.formats.split(",") } })));
+    visuals.command("render-start <render-id>").description("Approve an exact preview and enqueue one idempotent render job.")
+        .requiredOption("--scope-hash <hash>", "Exact preview scope hash.").requiredOption("--max-credits <credits>", "Approved ceiling from preview.")
+        .requiredOption("--approved", "Authorize this exact render.").option("--json", "Print a JSON envelope.")
+        .action((id, options) => handle("visuals render start", options, () => requestOxygen(`/api/cli/visuals/renders/${encodeURIComponent(id)}`, { method: "POST", body: { scope_hash: options.scopeHash, max_credits: Number(options.maxCredits), approved: options.approved } })));
+    visuals.command("render-get <render-id>").description("Read render state and output downloads; optionally wait for a terminal state.")
+        .option("--wait", "Poll every 2 seconds until completed, failed, cancelled or effect_unknown; starts no render.")
+        .option("--timeout-seconds <n>", "Maximum wait with --wait, from 1 to 600 seconds. Defaults to 180.")
+        .option("--json", "Print a JSON envelope.")
+        .action((id, options) => handle("visuals render get", options, async () => {
+        if (options.wait)
+            return waitForVisualRender(id, options.timeoutSeconds);
+        if (options.timeoutSeconds !== undefined)
+            throw new OxygenError("invalid_request", "Pass --wait with --timeout-seconds.");
+        return requestOxygen(`/api/cli/visuals/renders/${encodeURIComponent(id)}`);
+    }));
+    visuals.command("render-cancel <render-id>").description("Request cancellation; read state to verify it stopped.")
+        .option("--json", "Print a JSON envelope.").action((id, options) => handle("visuals render cancel", options, () => requestOxygen(`/api/cli/visuals/renders/${encodeURIComponent(id)}`, { method: "DELETE" })));
+}

package/dist/visual-render-wait.d.ts

@@ -0,0 +1,3 @@
+/** Poll only the existing job. Neither terminal failure nor timeout authorizes
+ * a start, retry, cancellation, or a new credit reservation. */
+export declare function waitForVisualRender(id: string, requestedTimeoutSeconds?: string): Promise<Record<string, unknown>>;

package/dist/visual-render-wait.js

@@ -0,0 +1,56 @@
+import { OxygenError } from "@oxygen/shared";
+import { readPositiveInt, readRecordString } from "./cli-values.js";
+import { requestOxygen } from "./http-client.js";
+import { waitForCliRun } from "./run-wait.js";
+const TERMINAL = new Set(["completed", "failed", "cancelled", "effect_unknown"]);
+const DEFAULT_TIMEOUT_SECONDS = 180;
+const MAX_TIMEOUT_SECONDS = 600;
+/** Poll only the existing job. Neither terminal failure nor timeout authorizes
+ * a start, retry, cancellation, or a new credit reservation. */
+export async function waitForVisualRender(id, requestedTimeoutSeconds) {
+    const timeoutSeconds = readPositiveInt(requestedTimeoutSeconds) ?? DEFAULT_TIMEOUT_SECONDS;
+    if (timeoutSeconds > MAX_TIMEOUT_SECONDS)
+        throw new OxygenError("invalid_number", "Visual render wait timeout must be between 1 and 600 seconds.");
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    const controller = new AbortController();
+    let polls = 0;
+    let latestStatus = null;
+    const timedOut = () => new OxygenError("visual_render_wait_timeout", "Timed out waiting for the visual render. Read the same render ID again to continue checking.", {
+        details: { render_id: id, status: latestStatus, timeout_seconds: timeoutSeconds, polls }, exitCode: 1,
+    });
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => { controller.abort(); reject(timedOut()); }, timeoutSeconds * 1000);
+    });
+    try {
+        return await Promise.race([waitForCliRun({
+                runId: id, requestedTimeoutSeconds: String(timeoutSeconds),
+                defaultTimeoutSeconds: DEFAULT_TIMEOUT_SECONDS, defaultIntervalSeconds: 2,
+                fetchRun: async () => {
+                    const remainingMs = deadline - Date.now();
+                    if (controller.signal.aborted || remainingMs <= 0)
+                        throw timedOut();
+                    polls += 1;
+                    const data = await requestOxygen(`/api/cli/visuals/renders/${encodeURIComponent(id)}`, {
+                        method: "GET", timeoutMs: remainingMs, signal: controller.signal,
+                    });
+                    latestStatus = readRecordString(data.render, "status");
+                    if (latestStatus === "preview")
+                        throw new OxygenError("visual_render_not_started", "This render is still a preview. Start the approved render before waiting.", {
+                            details: { render_id: id, status: latestStatus },
+                        });
+                    if (!latestStatus || !(TERMINAL.has(latestStatus) || latestStatus === "queued" || latestStatus === "running")) {
+                        throw new OxygenError("invalid_response", "The render returned an unrecognized status.", { details: { render_id: id, status: latestStatus } });
+                    }
+                    return { ...data, status: latestStatus };
+                },
+                isTerminal: (status) => status !== null && TERMINAL.has(status),
+                shapeTerminal: (data, status, count, elapsedMs) => ({ ...data, status, terminal: true, polls: count, elapsedMs }),
+                timeoutCode: "visual_render_wait_timeout", timeoutMessage: "Timed out waiting for the visual render.", timeoutDetailIdKey: "render_id",
+            }), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+        controller.abort();
+    }
+}

package/node_modules/@oxygen/shared/dist/byok-connect.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Which providers `oxygen integrations connect <id> --api-key <key>` ACTUALLY
+ * connects for native execution.
+ *
+ * WHY THIS EXISTS. `native_provider.execution.supports_byok` says a TOOL can run on
+ * a customer's own key. It does not say the customer has any way to give us one.
+ * Those are two different facts, and 10 of the 42 byok-capable native providers
+ * have the first without the second:
+ *
+ *   apify builtwith dropleads lusha openwebninja parallel peopledatalabs
+ *   rocketreach theirstack wiza
+ *
+ * For those, `oxygen integrations connect <id> --api-key` does not reach
+ * `connectViaApiKey` at all. With no native catalog definition,
+ * `shouldConnectIntegrationViaComposio` is true, so the key is stored WITH COMPOSIO
+ * and no `integration_secrets` row of kind `api_key` is written. On the run path the
+ * tool is native generic-REST and `shouldRouteStaticToolThroughComposio` is false, so
+ * `resolveOptionalApiKeyCredentials` finds nothing and the call falls back to the
+ * MANAGED key — the very key that was out of credits. The command appears to work,
+ * changes nothing, and the customer is back where they started with no error.
+ *
+ * That is precisely the failure Plain T-104 would have hit: `parallel.search` was one
+ * of the refused tools, and a refusal message that told Mentcape to connect their own
+ * Parallel key would have sent them down a path that silently does nothing.
+ *
+ * So a message may only offer BYOK when BOTH halves hold, and this list is the second
+ * half. It lives in @oxygen/shared because the two sides that need it cannot see each
+ * other: `packages/integrations` writes the message, the catalog it would have to
+ * consult lives in `apps/web/src/lib/integrations/catalog.ts`, and packages never
+ * import from apps. `catalog.byok-connect.test.ts` in apps/web binds the two together
+ * so this list cannot drift from the connect forms it claims exist.
+ *
+ * ALLOWLIST, NOT DENYLIST, on purpose. A new provider that arrives without a connect
+ * form gets the alternatives-only message until someone adds it here — quieter than
+ * correct. A denylist would fail the other way: silently promising a connect form
+ * nobody built, which is the bug this fixes.
+ */
+export declare const NATIVE_API_KEY_CONNECT_INTEGRATION_IDS: ReadonlySet<string>;
+/**
+ * True when a customer can hand Oxygen their own key for this provider AND the
+ * native runner will use it. Never infer this from `supports_byok` alone.
+ */
+export declare function hasNativeApiKeyConnect(integrationId: string | null | undefined): boolean;

package/node_modules/@oxygen/shared/dist/byok-connect.js

@@ -0,0 +1,84 @@
+/**
+ * Which providers `oxygen integrations connect <id> --api-key <key>` ACTUALLY
+ * connects for native execution.
+ *
+ * WHY THIS EXISTS. `native_provider.execution.supports_byok` says a TOOL can run on
+ * a customer's own key. It does not say the customer has any way to give us one.
+ * Those are two different facts, and 10 of the 42 byok-capable native providers
+ * have the first without the second:
+ *
+ *   apify builtwith dropleads lusha openwebninja parallel peopledatalabs
+ *   rocketreach theirstack wiza
+ *
+ * For those, `oxygen integrations connect <id> --api-key` does not reach
+ * `connectViaApiKey` at all. With no native catalog definition,
+ * `shouldConnectIntegrationViaComposio` is true, so the key is stored WITH COMPOSIO
+ * and no `integration_secrets` row of kind `api_key` is written. On the run path the
+ * tool is native generic-REST and `shouldRouteStaticToolThroughComposio` is false, so
+ * `resolveOptionalApiKeyCredentials` finds nothing and the call falls back to the
+ * MANAGED key — the very key that was out of credits. The command appears to work,
+ * changes nothing, and the customer is back where they started with no error.
+ *
+ * That is precisely the failure Plain T-104 would have hit: `parallel.search` was one
+ * of the refused tools, and a refusal message that told Mentcape to connect their own
+ * Parallel key would have sent them down a path that silently does nothing.
+ *
+ * So a message may only offer BYOK when BOTH halves hold, and this list is the second
+ * half. It lives in @oxygen/shared because the two sides that need it cannot see each
+ * other: `packages/integrations` writes the message, the catalog it would have to
+ * consult lives in `apps/web/src/lib/integrations/catalog.ts`, and packages never
+ * import from apps. `catalog.byok-connect.test.ts` in apps/web binds the two together
+ * so this list cannot drift from the connect forms it claims exist.
+ *
+ * ALLOWLIST, NOT DENYLIST, on purpose. A new provider that arrives without a connect
+ * form gets the alternatives-only message until someone adds it here — quieter than
+ * correct. A denylist would fail the other way: silently promising a connect form
+ * nobody built, which is the bug this fixes.
+ */
+export const NATIVE_API_KEY_CONNECT_INTEGRATION_IDS = new Set([
+    "adyntel",
+    "ai_ark",
+    "apollo",
+    "bettercontact",
+    "blitzapi",
+    "bounceban",
+    "breakcold",
+    "brightdata",
+    "clearoutphone",
+    "contactout",
+    "crustdata",
+    "discolike",
+    "exa",
+    "findymail",
+    "firecrawl",
+    "forager",
+    "fullenrich",
+    "getsales",
+    "hunter",
+    "icypeas",
+    "leadmagic",
+    "linkup",
+    "millionverifier",
+    // Connects through saveMoltsetsConnection rather than the generic save, but that
+    // service calls saveApiKeyIntegrationConnection with secretKind "api_key" like the
+    // rest — so the native runner does find the key.
+    "moltsets",
+    "ocean",
+    "predictleads",
+    "prospeo",
+    "scalelist",
+    // scraper: dev v1.920.2 added the HarvestAPI workspace-key connect (native api-key form).
+    "scraper",
+    "serper",
+    "signalbase",
+    "zapmail",
+    "zerobounce",
+]);
+/**
+ * True when a customer can hand Oxygen their own key for this provider AND the
+ * native runner will use it. Never infer this from `supports_byok` alone.
+ */
+export function hasNativeApiKeyConnect(integrationId) {
+    return typeof integrationId === "string"
+        && NATIVE_API_KEY_CONNECT_INTEGRATION_IDS.has(integrationId);
+}

package/node_modules/@oxygen/shared/dist/capability-discovery.js

@@ -3,6 +3,20 @@ import { RECIPE_PRIMITIVES } from "./recipes.js";
 // It is navigation, never execution: live schemas, prices, readiness, and
 // approval enforcement remain on the exact command/tool selected from here.
 export const OXYGEN_CAPABILITY_ROUTES = [
+    {
+        id: "visual-rendering",
+        layer: "Action",
+        primitive: null,
+        owns: "Agent-authored GTM infographics and carousel pages: editable HTML/CSS/SVG sources, isolated PNG/PDF rendering, actual visual inspection, revisions and downloads.",
+        notFor: "A separate product primitive, arbitrary package execution, image generation providers, motion/video, or publishing.",
+        execution: "Save source in workspace files; preview exact rendering scope and price; approve, poll the durable job, inspect its PNG pixels, revise and export. Renderer availability is checked by preview.",
+        posture: "mixed",
+        gatewayTools: ["oxygen_visual_source_create", "oxygen_visual_render_preview", "oxygen_visual_render_get", "oxygen_visual_image_view"],
+        gatewayCommands: ["visuals source-create", "visuals render-preview", "visuals render-get", "visuals download"],
+        skills: ["oxygen-visual-design", "oxygen-knowledge"],
+        endpointSections: ["visuals"],
+        intentTerms: ["infographic", "gtm flow image", "render html", "visual design", "carousel pages", "svg", "png", "pdf export", "graphic designer"],
+    },
     {
         id: "workspace-access",
         layer: "Control",
@@ -194,20 +208,20 @@ export const OXYGEN_CAPABILITY_ROUTES = [
         id: "tables",
         layer: "Data",
         primitive: "tables",
-        owns: "Typed working datasets, rows, formulas, AI/tool/waterfall columns, cell state, projects, and run provenance.",
+        owns: "Typed working datasets, rows, formulas, AI/tool/waterfall columns, reusable Functions with isolated drafts and published versions, cell state, projects, and run provenance.",
         notFor: "Canonical CRM truth, message cadence, or an off-platform spreadsheet runtime.",
         execution: "Create and run work in hosted OXYGEN Tables; validate a small sample before bounded paid runs.",
         posture: "mixed",
-        gatewayTools: ["oxygen_tables_create", "oxygen_columns_add", "oxygen_enrich_column_preview", "oxygen_tables_link_bulk"],
-        gatewayCommands: ["tables create", "columns add", "enrich-column preview", "tables link"],
+        gatewayTools: ["oxygen_tables_create", "oxygen_columns_add", "oxygen_enrich_column_preview", "oxygen_tables_link_bulk", "oxygen_callables_manage"],
+        gatewayCommands: ["tables create", "columns add", "enrich-column preview", "tables link", "functions list", "functions draft"],
         skills: ["oxygen-gtm", "oxygen-table-tidy", "oxygen-diagnostics", "oxygen-clay-migration"],
-        endpointSections: ["action-columns", "callables", "columns", "company-enrichment", "enrich-column", "enrichment", "projects", "table-action-items", "table-action-runs", "table-ingestion-runs", "tables"],
+        endpointSections: ["action-columns", "callables", "functions", "columns", "company-enrichment", "enrich-column", "enrichment", "projects", "table-action-items", "table-action-runs", "table-ingestion-runs", "tables"],
         // "link"/"join"/"connect"/"relate" route here for `tables link`. Added after a
         // blind user eval asked for exactly "link two tables" and was routed to
         // `tables create` / `columns add` / `enrich-column preview` — none of which
         // do it. The agent only found the right command by grepping the raw 25k-line
         // command manifest, which is not a discovery path a customer has.
-        intentTerms: ["table", "rows", "column", "columns", "dataset", "csv", "import", "enrich", "enrichment", "waterfall", "score", "formula", "ai column", "lookup", "link", "link tables", "join", "connect", "relate", "relationship"],
+        intentTerms: ["table", "rows", "column", "columns", "dataset", "csv", "import", "enrich", "enrichment", "waterfall", "score", "formula", "ai column", "lookup", "link", "link tables", "join", "connect", "relate", "relationship", "function", "functions", "reusable function", "function draft", "function version", "callable"],
     },
     {
         id: "messages",
@@ -320,11 +334,11 @@ export const OXYGEN_CAPABILITY_ROUTES = [
         notFor: "One-to-one messaging, outreach campaigns, or general automation.",
         execution: "Create and schedule on OXYGEN; explicit approval releases the hosted publisher.",
         posture: "external_write",
-        gatewayTools: ["oxygen_publishing_posts_create", "oxygen_publishing_posts_list", "oxygen_publishing_posts_approve"],
-        gatewayCommands: ["publishing posts create", "publishing posts list", "publishing posts approve"],
-        skills: ["oxygen-linkedin-marketing"],
-        endpointSections: ["publishing"],
-        intentTerms: ["publish", "publishing", "schedule post", "content calendar", "posting calendar", "approve post", "social publishing"],
+        gatewayTools: ["oxygen_publishing_posts_create", "oxygen_publishing_posts_list", "oxygen_publishing_posts_approve", "oxygen_ugc_get"],
+        gatewayCommands: ["publishing posts create", "publishing posts list", "publishing posts approve", "ugc programs list"],
+        skills: ["oxygen-linkedin-marketing", "oxygen-ugc"],
+        endpointSections: ["publishing", "ugc"],
+        intentTerms: ["publish", "publishing", "schedule post", "content calendar", "posting calendar", "approve post", "social publishing", "ugc", "creator program", "user generated content", "creator voice", "sponsored creator"],
     },
     {
         id: "workflows",
@@ -542,6 +556,8 @@ function normalizeIntent(query) {
     return query.toLowerCase().replace(/[_-]+/g, " ").replace(/\s+/g, " ").trim();
 }
 function explicitCapabilityIntent(query) {
+    if (/\b(infographic|graphic designer|render html|carousel pages|visual design|gtm flow image)\b/.test(query))
+        return ROUTE_BY_ID.get("visual-rendering") ?? null;
     // A unified sender profile is an owned Sequence identity, even when the ask
     // names every attached channel (LinkedIn + WhatsApp + email). Resolve this
     // before public LinkedIn research, whose generic "profile" wording would

package/node_modules/@oxygen/shared/dist/feature-gates.d.ts

@@ -61,6 +61,8 @@ export type FeatureGateResolution = {
  * - OXYGEN_PUBLISHING_ENABLED — (b). Fail-closed production switch for posting
  *   to real provider accounts (`apps/web/src/app/(app)/(dashboard)/publishing/
  *   data.ts`). Wrong "on" = public posts from customer accounts.
+ * - OXYGEN_UGC_ENABLED — (b). Cross-workspace public posting and sponsored
+ *   paid jobs use a local fail-closed switch independent of flag services.
  * - OXYGEN_WORKER_AUTOSCALE — (b). Arms the worker fleet autoscaler, which STOPS
  *   production Machines (`apps/worker/src/fleet-autoscaler.ts`). Its worst wrong
  *   value takes the fleet down while work is queued, so it must never depend on a

package/node_modules/@oxygen/shared/dist/feature-gates.js

@@ -52,6 +52,8 @@
  * - OXYGEN_PUBLISHING_ENABLED — (b). Fail-closed production switch for posting
  *   to real provider accounts (`apps/web/src/app/(app)/(dashboard)/publishing/
  *   data.ts`). Wrong "on" = public posts from customer accounts.
+ * - OXYGEN_UGC_ENABLED — (b). Cross-workspace public posting and sponsored
+ *   paid jobs use a local fail-closed switch independent of flag services.
  * - OXYGEN_WORKER_AUTOSCALE — (b). Arms the worker fleet autoscaler, which STOPS
  *   production Machines (`apps/worker/src/fleet-autoscaler.ts`). Its worst wrong
  *   value takes the fleet down while work is queued, so it must never depend on a
@@ -67,6 +69,7 @@
 export const NEVER_FLAGGABLE = [
     "OXYGEN_WORKER_AUTOSCALE",
     "OXYGEN_PUBLISHING_ENABLED",
+    "OXYGEN_UGC_ENABLED",
     "OXYGEN_AGENTS_ENABLED",
     "OXYGEN_TELEMETRY_ENABLED",
     "OXYGEN_LOG_SHIPPING_ENABLED",

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

@@ -2,8 +2,10 @@ export { MANAGED_INBOX_MINIMUM_CLI_VERSION, OXYGEN_MINIMUM_CLI_VERSION, OXYGEN_V
 export { WORKFLOW_TRIGGER_AUTO_PAUSE_METADATA_KEYS, clearWorkflowTriggerAutoPauseMetadata, } from "./workflow-trigger-metadata.js";
 export { WORKFLOW_STATUS_CHANGE_METADATA_KEY, type WorkflowStatusChange, type WorkflowStatusChangeActor, type WorkflowStatusChangeSource, describeWorkflowStatusChange, formatWorkflowStatusChangeTimestamp, parseWorkflowStatusChange, readWorkflowStatusChange, } from "./workflow-status-change.js";
 export * from "./billing.js";
+export * from "./visual-render.js";
 export * from "./billing-anchors.js";
 export * from "./budget-scopes.js";
+export * from "./byok-connect.js";
 export * from "./capability-discovery.js";
 export * from "./user-capability-routing.js";
 export * from "./plan-capabilities.js";
@@ -11,6 +13,7 @@ export * from "./plan-limits.js";
 export * from "./sending-seats.js";
 export * from "./sending-seat-capacity.js";
 export * from "./plain-support-events.js";
+export * from "./provider-balance-signal.js";
 export * from "./provider-funding-errors.js";
 export * from "./publishing-limits.js";
 export * from "./spend-safety.js";
@@ -109,3 +112,4 @@ export declare function compareSemver(a: string, b: string): -1 | 0 | 1;
 export declare function isVersionGreater(a: string, b: string): boolean;
 /** True when `a` is a strictly lesser semantic version than `b`. */
 export declare function isVersionLess(a: string, b: string): boolean;
+export * from "./ugc.js";

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

@@ -2,8 +2,10 @@ export { MANAGED_INBOX_MINIMUM_CLI_VERSION, OXYGEN_MINIMUM_CLI_VERSION, OXYGEN_V
 export { WORKFLOW_TRIGGER_AUTO_PAUSE_METADATA_KEYS, clearWorkflowTriggerAutoPauseMetadata, } from "./workflow-trigger-metadata.js";
 export { WORKFLOW_STATUS_CHANGE_METADATA_KEY, describeWorkflowStatusChange, formatWorkflowStatusChangeTimestamp, parseWorkflowStatusChange, readWorkflowStatusChange, } from "./workflow-status-change.js";
 export * from "./billing.js";
+export * from "./visual-render.js";
 export * from "./billing-anchors.js";
 export * from "./budget-scopes.js";
+export * from "./byok-connect.js";
 export * from "./capability-discovery.js";
 export * from "./user-capability-routing.js";
 export * from "./plan-capabilities.js";
@@ -11,6 +13,7 @@ export * from "./plan-limits.js";
 export * from "./sending-seats.js";
 export * from "./sending-seat-capacity.js";
 export * from "./plain-support-events.js";
+export * from "./provider-balance-signal.js";
 export * from "./provider-funding-errors.js";
 export * from "./publishing-limits.js";
 export * from "./spend-safety.js";
@@ -145,3 +148,4 @@ export function isVersionGreater(a, b) {
 export function isVersionLess(a, b) {
     return compareSemver(a, b) < 0;
 }
+export * from "./ugc.js";

package/node_modules/@oxygen/shared/dist/knowledge-constants.d.ts

@@ -3,7 +3,7 @@ export type KnowledgePageType = typeof KNOWLEDGE_PAGE_TYPES[number];
 export declare const KNOWLEDGE_META_PAGE_TYPES: readonly ["schema", "source_summary", "report"];
 export declare const KNOWLEDGE_PAGE_STATUSES: readonly ["draft", "active", "archived"];
 export type KnowledgePageStatus = typeof KNOWLEDGE_PAGE_STATUSES[number];
-export declare const RESERVED_KNOWLEDGE_SLUGS: readonly ["index", "log", "schema", "company-profile", "readme"];
+export declare const RESERVED_KNOWLEDGE_SLUGS: readonly ["index", "log", "schema", "company-profile", "readme", "new"];
 export declare const KNOWLEDGE_SLUG_MAX_LENGTH = 120;
 export declare const KNOWLEDGE_SLUG_PATTERN: RegExp;
 export declare function isValidKnowledgeSlug(value: string): boolean;

package/node_modules/@oxygen/shared/dist/knowledge-constants.js

@@ -32,17 +32,18 @@ export const KNOWLEDGE_PAGE_TYPES = [
 export const KNOWLEDGE_META_PAGE_TYPES = ["schema", "source_summary", "report"];
 export const KNOWLEDGE_PAGE_STATUSES = ["draft", "active", "archived"];
 // Slugs the write path refuses (the scaffold seeder may create `schema`): they are
-// computed projections or virtual pages, never ordinary rows.
+// computed projections, virtual pages, or static UI routes, never ordinary rows.
 export const RESERVED_KNOWLEDGE_SLUGS = [
     "index",
     "log",
     "schema",
     "company-profile",
     "readme",
+    "new",
 ];
 export const KNOWLEDGE_SLUG_MAX_LENGTH = 120;
 // Flat kebab grammar: lowercase alphanumeric + dashes, no leading/trailing dash,
-// no slashes (pages are a flat namespace; the graph, tags, and types organize).
+// no slashes (slugs are a flat namespace; folders, the graph, tags, and types organize).
 export const KNOWLEDGE_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,119}$/;
 export function isValidKnowledgeSlug(value) {
     return KNOWLEDGE_SLUG_PATTERN.test(value);

package/node_modules/@oxygen/shared/dist/knowledge-seed-content.js

@@ -84,7 +84,7 @@ Index-first → open only relevant pages → answer citing slugs → file durabl
 | \`schema\` | describes the wiki itself (this page) |
 
 ## Slugs
-Flat kebab: lowercase alphanumerics + dashes, no slashes, ≤120 chars. **Immutable once created** — choose the durable name (\`competitor-clay\`, not \`clay-notes-july\`). No folders; types, tags, and wikilinks organize. Reserved (never create): \`index\`, \`log\`, \`schema\`, \`company-profile\`, \`readme\`.
+Flat kebab: lowercase alphanumerics + dashes, no slashes, ≤120 chars. **Immutable once created** — choose the durable name (\`competitor-clay\`, not \`clay-notes-july\`). Nested folders organize pages in the explorer without changing slugs or wikilinks; types and tags provide additional organization. Reserved (never create): \`index\`, \`log\`, \`schema\`, \`company-profile\`, \`readme\`, \`new\`.
 
 ## Wikilinks
 Wrap a slug in double square brackets to link it. Three forms all resolve to the same page — bare (\`slug\`), aliased (\`slug|display text\`), and heading-anchored (\`slug#heading\`) — because the alias and the heading are stripped before lookup. **Linking to a page that doesn't exist yet is good** — the dashed node is a visible to-do. Every page should link out (avoid dead-ends) and be linked to (avoid orphans).

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

@@ -38,6 +38,13 @@ import { createHash } from "node:crypto";
 import { log } from "./log.js";
 const FLUSH_TIMEOUT_MS = 5_000;
 const WARN_THROTTLE_MS = 30_000;
+/**
+ * The OTLP exporter's own deadline, in SECONDS (the @langfuse/otel option's
+ * unit). Deliberately ABOVE FLUSH_TIMEOUT_MS: our bound protects the caller,
+ * this one protects the batch, and making them equal — the SDK's 5s default —
+ * meant every flush that ran long lost its spans instead of finishing late.
+ */
+const LANGFUSE_EXPORT_TIMEOUT_SECONDS = 10;
 // Defensive per-field bound, well under Langfuse's ~1 MB event cap. Copilot
 // transcripts max out around 150 KB; anything larger is truncated with an
 // explicit marker rather than risking a rejected ingestion batch.
@@ -179,6 +186,16 @@ function createOtelEmitter(env, warn) {
                     secretKey: env.LANGFUSE_SECRET_KEY,
                     ...(env.LANGFUSE_BASE_URL?.trim() ? { baseUrl: env.LANGFUSE_BASE_URL.trim() } : {}),
                     environment: resolveLlmTracingEnvironment(env),
+                    // SECONDS, and the OTLP POST's own deadline. The SDK default is 5,
+                    // which is exactly FLUSH_TIMEOUT_MS — zero headroom, so a batch that
+                    // needed 6s was guaranteed to die on the transport and be dropped:
+                    // 37 `llm_tracing.ingest_failed` warns over 30 days to 2026-09-09,
+                    // every one stage='flush' / 'Request timed out', against 275,970
+                    // traces Langfuse accepted in the same window. 10s gives the POST
+                    // room without touching FLUSH_TIMEOUT_MS — boundedNever still
+                    // releases the caller at 5s, so a slow Langfuse can never hold a
+                    // worker tick.
+                    timeout: LANGFUSE_EXPORT_TIMEOUT_SECONDS,
                 });
                 // PRIVATE provider. Deliberately NOT .register()ed — see the file
                 // header: the global provider carries the Axiom OTLP exporters, and a

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

@@ -1,4 +1,10 @@
+import { S3Client } from "@aws-sdk/client-s3";
 export declare function isObjectStorageConfigured(): boolean;
+/** Server-only storage adapter seam. Callers own tenant and object-policy checks. */
+export declare function resolveObjectStorageClient(): {
+    client: S3Client;
+    bucket: string;
+};
 export declare function buildImportObjectKey(input: {
     organizationId: string;
     fileName?: string | null;

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

@@ -77,6 +77,11 @@ function resolveClient() {
 }
 // Keys are namespaced by org so a tenant can only ever be handed (and the
 // enqueue route only accepts) keys under its own prefix.
+/** Server-only storage adapter seam. Callers own tenant and object-policy checks. */
+export function resolveObjectStorageClient() {
+    const { client, config } = resolveClient();
+    return { client, bucket: config.bucket };
+}
 export function buildImportObjectKey(input) {
     const safeName = sanitizeFileName(input.fileName) || "import";
     return `imports/${input.organizationId}/${randomUUID()}/${safeName}`;

package/node_modules/@oxygen/shared/dist/provider-balance-signal.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The managed-provider BALANCE signal — one contract shared by the two producers
+ * that can observe it and the one Axiom monitor that alerts on it.
+ *
+ * WHY THIS EXISTS. Until now the only way OXYGEN learned that one of its POOLED
+ * provider accounts had run out of money was a customer's call being refused.
+ * `provider.managed_credits_exhausted` fires at that moment — after the failure,
+ * never before it. Plain T-104 (Mentcape, 2026-08-24 and again 2026-08-31) is what
+ * that costs: `serper.places`, `serper.maps` and `parallel.search` refused live
+ * calls for a workspace holding 75,347 Oxygen credits, because OUR balance with
+ * those vendors was empty. Prod Axiom over the 16 days to 2026-09-05 shows the same
+ * refusal reaching >=6 orgs on serper, >=3 on parallel and >=5 on exa.
+ *
+ * The balance snapshot cron already read most of those balances every two hours and
+ * wrote them to `provider_balance_snapshots`. It emitted no per-provider log line at
+ * all, so a balance sliding toward zero was visible only to a human who opened
+ * /admin/costs. This module is the missing signal: one structured line per managed
+ * provider per snapshot, carrying the number AND the verdict.
+ *
+ * TWO PRODUCERS, ONE VOCABULARY.
+ *
+ *  - `provider_balance.snapshot` — the cron, for every provider whose balance we can
+ *    actually read. Proactive: it fires while there is still money left.
+ *  - `provider_balance.exhausted` — the tool runner, when a managed account actually
+ *    refuses a paid call. That is the ONLY balance evidence available for a provider
+ *    with no usable balance API, which is exactly the T-104 three (see
+ *    PROVIDERS_WITHOUT_BALANCE_API in @oxygen/providers). Without it the new monitor
+ *    would be structurally blind to the providers that caused the incident.
+ *
+ * Both carry the same `status` vocabulary so ONE monitor query covers both, and both
+ * put `status` and `provider` in flat fields because those are the two dimensions the
+ * monitor filters and groups on. Every other field rides in the `worker_fields` map
+ * at zero column cost — see AXIOM_STABLE_FIELDS in ./axiom-field-budget.ts, which is
+ * load-bearing in both directions.
+ */
+/** The proactive line, emitted per managed provider by the balance-snapshot cron. */
+export declare const PROVIDER_BALANCE_SNAPSHOT_MSG = "provider_balance.snapshot";
+/**
+ * The reactive line, emitted by the tool runner when a managed account refuses a paid
+ * call. Deliberately a SEPARATE msg from `provider.managed_credits_exhausted`: that
+ * one is the refusal event (a customer call failed), this one is the balance fact (our
+ * account is empty). The refusal monitor counts the former; conflating them would make
+ * one query mean two different things.
+ */
+export declare const PROVIDER_BALANCE_EXHAUSTED_MSG = "provider_balance.exhausted";
+/**
+ * The verdict on one managed balance.
+ *
+ * `unknown` is not a synonym for `ok`, and the distinction is the whole point: the
+ * pre-existing snapshot recorded status `ok` with `balance_remaining = null` for
+ * blitzapi and contactout on all 353 rows of the last 30 days, and would have
+ * recorded `ok` at a balance of 0 too. "We asked and got no number" must never read
+ * as "there is money".
+ */
+export type ProviderBalanceStatus = "ok" | "low" | "exhausted" | "unknown" | "not_monitored" | "auth_error" | "rate_limited" | "error";
+/** The statuses the P1 balance monitor alerts on. Anything else is informational. */
+export declare const ALERTING_PROVIDER_BALANCE_STATUSES: readonly ProviderBalanceStatus[];
+/**
+ * Default low-balance floor, in the provider's OWN unit (almost always provider
+ * credits). 1,000 is not a round number chosen for looking tidy — it is roughly
+ * three to eight days of measured burn for the credit providers OXYGEN funds,
+ * taken from `provider_balance_snapshots` in the prod control DB on 2026-09-07
+ * over the preceding 30 days:
+ *
+ *   bettercontact   10,130 -> 364    (~325/day)  ~3 days of head-room at 1,000
+ *   leadmagic        7,702 -> 903    (~227/day)  ~4 days
+ *   millionverifier 41,357 -> 37,695 (~122/day)  ~8 days
+ *   ai_ark          10,000 -> 9,813  (~6/day)    months
+ *
+ * A floor is a claim about how the account behaved when it was measured, nothing
+ * more. Re-measure it rather than nudging it when it turns out to be noisy — the
+ * monitor changelog exists for exactly that conversation.
+ */
+export declare const DEFAULT_MANAGED_BALANCE_FLOOR = 1000;
+/**
+ * Per-provider floors, and the providers that are deliberately NOT balance-monitored
+ * (`null`). Only entries that the default gets wrong are listed; everything else
+ * inherits DEFAULT_MANAGED_BALANCE_FLOOR.
+ */
+export declare const MANAGED_BALANCE_FLOORS: Readonly<Record<string, number | null>>;
+/** `OXYGEN_MANAGED_BALANCE_FLOOR_FIRECRAWL`, `..._AI_ARK`, ... */
+export declare function managedBalanceFloorEnvVar(provider: string): string;
+/**
+ * The floor in force for one provider. `null` means "do not judge this balance".
+ *
+ * The env override is the operator's escape hatch between deploys: a top-up that
+ * changes the plan size, or a provider that turns out to be noisy at the default,
+ * is one Doppler value away from being right. `off`/`none`/`disabled` switches the
+ * provider off the monitor entirely; an unparseable or negative value is IGNORED
+ * rather than obeyed, because a typo must not silently disarm an alert.
+ */
+export declare function managedBalanceFloor(provider: string, env?: Record<string, string | undefined>): number | null;
+export type ProviderBalanceVerdict = {
+    status: ProviderBalanceStatus;
+    /** The single boolean the monitor's description tells a responder to read. */
+    balanceLow: boolean;
+    /** The floor actually applied, after the env override. `null` = not monitored. */
+    floor: number | null;
+    level: "info" | "warn" | "error";
+};
+/**
+ * Turn one balance reading into the verdict both producers log.
+ *
+ * Pure on purpose: the thresholds are the alerting policy, so they are unit-testable
+ * without a provider, a cron, or a network.
+ */
+export declare function classifyManagedBalance(input: {
+    provider: string;
+    /** The balance fetcher's own status. Anything but "ok" means we are blind. */
+    fetchStatus: "ok" | "auth_error" | "rate_limited" | "error";
+    balanceRemaining: number | null;
+    env?: Record<string, string | undefined>;
+}): ProviderBalanceVerdict;