@oxygen-agent/cli 1.922.12 → 1.936.1

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

@@ -0,0 +1,158 @@
+/**
+ * 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 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 const PROVIDER_BALANCE_EXHAUSTED_MSG = "provider_balance.exhausted";
+/** The statuses the P1 balance monitor alerts on. Anything else is informational. */
+export const ALERTING_PROVIDER_BALANCE_STATUSES = [
+    "low",
+    "exhausted",
+];
+/**
+ * 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 const DEFAULT_MANAGED_BALANCE_FLOOR = 1_000;
+/**
+ * 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 const MANAGED_BALANCE_FLOORS = {
+    // A 1,000-credit/month plan. The default floor would mark it low on the first day
+    // of every billing period, forever — the classic alert nobody reads. Measured
+    // 2026-09-07: it has ranged 1,002 -> 670 over 30 days, so 150 is ~15% of the plan
+    // and still several days of head-room.
+    firecrawl: 150,
+    // Unit is REQUESTS, not credits, and the managed key has reported a null balance on
+    // every row for 30 days (see `unknown` above). The floor is a guess until the
+    // fetcher returns a number; it costs nothing while the balance stays unreadable.
+    contactout: 250,
+    // USD, not credits. Measured 2026-09-07: $23.29 -> $7.98 over 30 days, and an empty
+    // OpenRouter balance stops every AI column in the product.
+    openrouter: 5,
+    // NOT a spendable balance. Stripe's /v1/balance is the PAYOUT balance — money owed
+    // to us, which sits at 0.00 in the normal case (it did on 2026-09-07) and goes
+    // negative after a refund. A floor here would page daily about nothing.
+    stripe: null,
+    // Reachability probes with no balance concept at all: both fetchers return
+    // `balanceRemaining: null` by construction.
+    vercel: null,
+    neon: null,
+};
+/** `OXYGEN_MANAGED_BALANCE_FLOOR_FIRECRAWL`, `..._AI_ARK`, ... */
+export function managedBalanceFloorEnvVar(provider) {
+    return `OXYGEN_MANAGED_BALANCE_FLOOR_${provider.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
+}
+/**
+ * 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 function managedBalanceFloor(provider, env = process.env) {
+    const raw = env[managedBalanceFloorEnvVar(provider)]?.trim();
+    if (raw) {
+        const lowered = raw.toLowerCase();
+        if (lowered === "off" || lowered === "none" || lowered === "disabled")
+            return null;
+        const parsed = Number(raw);
+        if (Number.isFinite(parsed) && parsed >= 0)
+            return parsed;
+    }
+    const configured = MANAGED_BALANCE_FLOORS[provider];
+    if (configured === null)
+        return null;
+    return configured ?? DEFAULT_MANAGED_BALANCE_FLOOR;
+}
+/**
+ * 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 function classifyManagedBalance(input) {
+    const floor = managedBalanceFloor(input.provider, input.env ?? process.env);
+    if (input.fetchStatus !== "ok") {
+        // We could not read the balance. That is a monitoring outage, not a funding
+        // outage, so it must NOT enter the balance monitor: a rotated key would
+        // otherwise page as "the account is empty" and send ops to top up an account
+        // that is full. It is still a warn, because a fetcher that has been blind for a
+        // week is how a dry account stays invisible.
+        return { status: input.fetchStatus, balanceLow: false, floor, level: "warn" };
+    }
+    // "Not monitored" is decided BEFORE "no number", because for these providers the
+    // absent number is the design, not a symptom. Vercel and Neon have no balance concept
+    // at all and their fetchers return null by construction as reachability probes; the
+    // other order filed them under `unknown`, the status that means "we asked and got no
+    // number" and exists so a fetcher that has gone blind is visible. Two permanent rows
+    // in that bucket is how a real blind fetcher stops standing out.
+    if (floor === null) {
+        return { status: "not_monitored", balanceLow: false, floor: null, level: "info" };
+    }
+    if (input.balanceRemaining === null) {
+        return { status: "unknown", balanceLow: false, floor, level: "info" };
+    }
+    if (input.balanceRemaining <= 0) {
+        return { status: "exhausted", balanceLow: true, floor, level: "error" };
+    }
+    if (input.balanceRemaining <= floor) {
+        return { status: "low", balanceLow: true, floor, level: "warn" };
+    }
+    return { status: "ok", balanceLow: false, floor, level: "info" };
+}

package/node_modules/@oxygen/shared/dist/sequence-failures.d.ts

@@ -39,6 +39,18 @@ export type SequenceFailureOverrides = {
  * retries, defers, fails, consumes credits, or advances an enrollment.
  */
 export declare function serializeSequenceFailure(error: unknown, overrides?: SequenceFailureOverrides): Record<string, unknown> & SequenceFailureEnvelope;
+/**
+ * Does this stored `error` value describe a FAILURE at all? A Sequence action's
+ * `error` column is also where deferrals stamp their diagnostic context
+ * (`native_email_defer_log`, `defer_count`, sender status …), and readSequenceFailure
+ * will happily classify that context as an `unknown` failure because it is
+ * built to never lose a historical error. Grasp (2026-09-09): every action parked
+ * on mailbox_spacing therefore surfaced as `failure:unknown` in `sequences
+ * status`, mirroring the deferral count 1:1 while nothing had failed. A failure
+ * carries at least one of the failure fields below; a deferral record carries
+ * none of them.
+ */
+export declare function hasSequenceFailureSignal(error: unknown): boolean;
 /**
  * Read both the versioned envelope and historical Sequence error shapes. A
  * missing fact stays missing: in particular, this reader never manufactures a

package/node_modules/@oxygen/shared/dist/sequence-failures.js

@@ -55,6 +55,30 @@ export function serializeSequenceFailure(error, overrides = {}) {
     Object.assign(output, failure, { error_message: failure.message });
     return output;
 }
+/**
+ * Does this stored `error` value describe a FAILURE at all? A Sequence action's
+ * `error` column is also where deferrals stamp their diagnostic context
+ * (`native_email_defer_log`, `defer_count`, sender status …), and readSequenceFailure
+ * will happily classify that context as an `unknown` failure because it is
+ * built to never lose a historical error. Grasp (2026-09-09): every action parked
+ * on mailbox_spacing therefore surfaced as `failure:unknown` in `sequences
+ * status`, mirroring the deferral count 1:1 while nothing had failed. A failure
+ * carries at least one of the failure fields below; a deferral record carries
+ * none of them.
+ */
+export function hasSequenceFailureSignal(error) {
+    if (error === null || error === undefined)
+        return false;
+    if (typeof error === "string")
+        return error.trim().length > 0;
+    if (error instanceof Error)
+        return true;
+    const records = failureRecords(error);
+    if (records.length === 0)
+        return false;
+    return (firstString(records, ["failure_class", "code", "error_code", "errorCode"]) !== null
+        || firstString(records, ["message", "error_message", "errorMessage"]) !== null);
+}
 /**
  * Read both the versioned envelope and historical Sequence error shapes. A
  * missing fact stays missing: in particular, this reader never manufactures a

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

@@ -1010,4 +1010,20 @@ export declare function resolveSendWindowTimezone(window: SequenceSendWindow, ro
  * start>end wraps past midnight.
  */
 export declare function isWithinSendWindow(window: SequenceSendWindow, now: Date, timezone?: string): boolean;
+/**
+ * Seconds until today's send window closes, evaluated like isWithinSendWindow
+ * (same timezone resolution, same wrap-past-midnight rule). Returns null when
+ * `now` is outside the window, the window is malformed, or the timezone cannot be
+ * resolved — every case where "remaining window" has no meaning and the caller
+ * must fall back to the plain cap-over-window spacing. Minute granularity, like
+ * the window itself.
+ */
+export declare function secondsUntilSendWindowEnd(window: SequenceSendWindow, now: Date, timezone?: string): number | null;
+/**
+ * Seconds since today's send window opened, with the same rules and null cases
+ * as secondsUntilSendWindowEnd. Together the two locate the window's opening
+ * instant, which is what lets a caller tell whether a day-keyed counter still
+ * describes this window's sends.
+ */
+export declare function secondsSinceSendWindowStart(window: SequenceSendWindow, now: Date, timezone?: string): number | null;
 export {};

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

@@ -2300,6 +2300,60 @@ export function isWithinSendWindow(window, now, timezone) {
     const minutes = parts.hour * 60 + parts.minute;
     return startM < endM ? minutes >= startM && minutes < endM : minutes >= startM || minutes < endM;
 }
+/**
+ * Seconds until today's send window closes, evaluated like isWithinSendWindow
+ * (same timezone resolution, same wrap-past-midnight rule). Returns null when
+ * `now` is outside the window, the window is malformed, or the timezone cannot be
+ * resolved — every case where "remaining window" has no meaning and the caller
+ * must fall back to the plain cap-over-window spacing. Minute granularity, like
+ * the window itself.
+ */
+export function secondsUntilSendWindowEnd(window, now, timezone) {
+    if (!isWithinSendWindow(window, now, timezone))
+        return null;
+    const tz = timezone?.trim() ? timezone.trim() : window.timezone;
+    const parts = tzParts(now, tz) ?? tzParts(now, window.timezone) ?? tzParts(now, "UTC");
+    if (!parts)
+        return null;
+    const startM = hhmmToMinutes(window.start);
+    const endM = hhmmToMinutes(window.end);
+    if (startM === null || endM === null || startM === endM)
+        return null;
+    const minutes = parts.hour * 60 + parts.minute;
+    let remainingMinutes;
+    if (startM < endM) {
+        remainingMinutes = endM - minutes;
+    }
+    else {
+        // Wraps past midnight: before the wrap the window runs to midnight and on
+        // through to `end`; after the wrap only `end - now` is left.
+        remainingMinutes = minutes >= startM ? (24 * 60 - minutes) + endM : endM - minutes;
+    }
+    return remainingMinutes > 0 ? remainingMinutes * 60 : null;
+}
+/**
+ * Seconds since today's send window opened, with the same rules and null cases
+ * as secondsUntilSendWindowEnd. Together the two locate the window's opening
+ * instant, which is what lets a caller tell whether a day-keyed counter still
+ * describes this window's sends.
+ */
+export function secondsSinceSendWindowStart(window, now, timezone) {
+    if (!isWithinSendWindow(window, now, timezone))
+        return null;
+    const tz = timezone?.trim() ? timezone.trim() : window.timezone;
+    const parts = tzParts(now, tz) ?? tzParts(now, window.timezone) ?? tzParts(now, "UTC");
+    if (!parts)
+        return null;
+    const startM = hhmmToMinutes(window.start);
+    const endM = hhmmToMinutes(window.end);
+    if (startM === null || endM === null || startM === endM)
+        return null;
+    const minutes = parts.hour * 60 + parts.minute;
+    const elapsedMinutes = startM < endM || minutes >= startM
+        ? minutes - startM
+        : minutes + 24 * 60 - startM; // wrapped past midnight: opened yesterday evening
+    return elapsedMinutes >= 0 ? elapsedMinutes * 60 : null;
+}
 function tzParts(now, tz) {
     try {
         const formatted = new Intl.DateTimeFormat("en-US", {

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

@@ -0,0 +1,113 @@
+/** UGC is a Publishing capability. These are projections, never a second Posts store. */
+export type UgcApprovalMode = "creator" | "delegated";
+export type UgcProgram = {
+    id: string;
+    name: string;
+    productUrl: string;
+    description: string;
+    knowledgePageSlugs: string[];
+    brandApprovalRequired: boolean;
+    status: "active" | "archived";
+    createdAt: Date;
+    updatedAt: Date;
+};
+export type UgcBrief = {
+    id: string;
+    programId: string;
+    title: string;
+    prompt: string;
+    questions: string[];
+    cycle: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+};
+export type UgcPostProjection = {
+    title?: string | null;
+    contentText: string;
+    status: string;
+    scheduledAt?: string | null;
+    publishedAt?: string | null;
+    publishedUrl?: string | null;
+    providerPostId?: string | null;
+    metrics?: Record<string, number | null>;
+    metricsSyncedAt?: string | null;
+    projectedAt?: string;
+    commentsSyncedAt?: string | null;
+    publicComments?: {
+        id: string;
+        parentId: string | null;
+        body: string;
+        authorName: string | null;
+        authorProfileUrl: string | null;
+        createdAt: string | null;
+    }[];
+    commentCoverage?: {
+        totalKnown: number;
+        projected: number;
+        truncated: boolean;
+        status: string;
+    };
+    metricsHistory?: {
+        date: string;
+        reactions: number | null;
+        comments: number | null;
+        shares: number | null;
+        impressions: number | null;
+    }[];
+};
+export type UgcPostLink = {
+    id: string;
+    programId: string;
+    participationId: string;
+    creatorOrgId: string;
+    masterOrgId: string;
+    brandApprovalRequired: boolean;
+    sourcePostId: string;
+    briefId: string | null;
+    attribution: Record<string, unknown>;
+    projection: UgcPostProjection;
+    sourceRevision: string;
+    creatorApprovedRevision: string | null;
+    brandApprovedRevision: string | null;
+    grantVersion: number;
+    createdAt: Date;
+    updatedAt: Date;
+};
+export type UgcVoiceImport = {
+    id: string;
+    senderId: string;
+    linkedinUrl: string;
+    programId: string;
+    participationId: string;
+    grantVersion: number;
+    status: "queued" | "running" | "completed" | "failed" | "cancelled";
+    cursor: string | null;
+    importedCount: number;
+    scannedCount: number;
+    maxPosts: number;
+    creditCap: number;
+    creditsUsed: number;
+    receiptIds: string[];
+    error: string | null;
+    approvedByUserId: string | null;
+    approvedAt: Date;
+    leaseToken: string | null;
+    leaseExpiresAt: Date | null;
+    phase: "pending" | "scraping" | "synthesizing" | "ready" | "effect_unknown";
+    importedPostIds: string[];
+    pageNumber: number;
+    backfillComplete: boolean;
+    synthesizedCount: number;
+    voicePageId: string | null;
+    samples: {
+        providerPostId: string;
+        contentText: string;
+        providerPublishedAt: string | null;
+        providerUrl: string;
+    }[];
+    pendingPage: Record<string, unknown> | null;
+    createdAt: Date;
+    updatedAt: Date;
+};
+export declare const UGC_MONTHLY_CREATOR_CREDITS = 10000;
+export declare const UGC_SPONSORED_LINKEDIN_SEATS = 1;

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

@@ -0,0 +1,2 @@
+export const UGC_MONTHLY_CREATOR_CREDITS = 10_000;
+export const UGC_SPONSORED_LINKEDIN_SEATS = 1;

package/node_modules/@oxygen/shared/dist/vercel-sandbox-fetch.d.ts

@@ -0,0 +1,9 @@
+/** The Sandbox SDK retries transport failures and 429/5xx responses even for
+ * POSTs. Visual execution cannot replay an ambiguously accepted mutation.
+ * The SDK recognizes AbortError as non-retryable; outcomeUnknown deliberately
+ * distinguishes this transport fence from ordinary caller cancellation. */
+export declare class SandboxMutationOutcomeUnknownError extends Error {
+    readonly outcomeUnknown = true;
+    constructor(options?: ErrorOptions);
+}
+export declare function createSandboxNonReplayFetch(rawFetch?: typeof globalThis.fetch): typeof globalThis.fetch;

package/node_modules/@oxygen/shared/dist/vercel-sandbox-fetch.js

@@ -0,0 +1,33 @@
+/** The Sandbox SDK retries transport failures and 429/5xx responses even for
+ * POSTs. Visual execution cannot replay an ambiguously accepted mutation.
+ * The SDK recognizes AbortError as non-retryable; outcomeUnknown deliberately
+ * distinguishes this transport fence from ordinary caller cancellation. */
+export class SandboxMutationOutcomeUnknownError extends Error {
+    outcomeUnknown = true;
+    constructor(options) {
+        super("Sandbox mutation acceptance requires reconciliation.", options);
+        this.name = "AbortError";
+    }
+}
+export function createSandboxNonReplayFetch(rawFetch = globalThis.fetch) {
+    return async (input, init) => {
+        const method = (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
+        if (["GET", "HEAD", "OPTIONS"].includes(method))
+            return rawFetch(input, init);
+        try {
+            // Redirects must not resubmit a mutation either. No request URL, body or
+            // authentication header is copied into the error or telemetry.
+            const response = await rawFetch(input, { ...init, redirect: "error" });
+            if (response.status === 429 || response.status >= 500) {
+                void response.body?.cancel().catch(() => { });
+                throw new SandboxMutationOutcomeUnknownError();
+            }
+            return response;
+        }
+        catch (error) {
+            if (error instanceof SandboxMutationOutcomeUnknownError)
+                throw error;
+            throw new SandboxMutationOutcomeUnknownError({ cause: error });
+        }
+    };
+}

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

@@ -1,4 +1,4 @@
-export declare const OXYGEN_VERSION = "1.922.12";
+export declare const OXYGEN_VERSION = "1.936.1";
 export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.181.0";
 export declare const MANAGED_INBOX_MINIMUM_CLI_VERSION = "1.326.2";
 export declare const SUPPORT_AGENT_REPLY_MINIMUM_CLI_VERSION = "1.747.0";

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

@@ -1,4 +1,4 @@
-export const OXYGEN_VERSION = "1.922.12";
+export const OXYGEN_VERSION = "1.936.1";
 // The GLOBAL CLI compatibility floor: the oldest CLI allowed to call any
 // operational route. Raising it hard-rejects every older CLI from the entire
 // product, so it obeys one law, enforced by scripts/ci/cli-min-version-gate.mjs:

package/node_modules/@oxygen/shared/dist/visual-render.d.ts

@@ -0,0 +1,30 @@
+export declare const VISUAL_RENDER_PROFILE: "oxygen-static-v1";
+export declare const VISUAL_RENDER_LIMITS: Readonly<{
+    maxPages: 12;
+    maxSide: 4096;
+    maxPixels: 32000000;
+    maxSourceBytes: number;
+    maxOutputBytes: number;
+    timeoutMs: 120000;
+}>;
+export type VisualRenderRequest = {
+    source_file_ids: string[];
+    width: number;
+    height: number;
+    scale: 1 | 2;
+    formats: ("png" | "pdf")[];
+};
+export type VisualRenderProfile = {
+    version: typeof VISUAL_RENDER_PROFILE;
+    renderSnapshotId: string;
+    validatorSnapshotId: string;
+    rendererDigest: string;
+    expiresAt: string;
+    credits: number;
+    maxCostMicros: number;
+};
+export declare function visualRenderProfilesMatch(a: VisualRenderProfile, b: VisualRenderProfile): boolean;
+export declare function validateVisualFileId(value: unknown): string;
+export declare function parseVisualRenderRequest(value: Record<string, unknown>): VisualRenderRequest;
+/** No default snapshot or tariff: enabling this profile is an explicit deployment operation. */
+export declare function resolveVisualRenderProfile(env: Record<string, string | undefined>, now?: number): VisualRenderProfile | null;

package/node_modules/@oxygen/shared/dist/visual-render.js

@@ -0,0 +1,55 @@
+import { OxygenError } from "./cli-result.js";
+export const VISUAL_RENDER_PROFILE = "oxygen-static-v1";
+export const VISUAL_RENDER_LIMITS = Object.freeze({
+    maxPages: 12, maxSide: 4096, maxPixels: 32_000_000,
+    maxSourceBytes: 2 * 1024 * 1024, maxOutputBytes: 50 * 1024 * 1024,
+    timeoutMs: 120_000,
+});
+export function visualRenderProfilesMatch(a, b) {
+    return a.version === b.version && a.renderSnapshotId === b.renderSnapshotId
+        && a.validatorSnapshotId === b.validatorSnapshotId && a.rendererDigest === b.rendererDigest
+        && a.expiresAt === b.expiresAt && a.credits === b.credits && a.maxCostMicros === b.maxCostMicros;
+}
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export function validateVisualFileId(value) {
+    if (typeof value !== "string" || !uuid.test(value))
+        throw new OxygenError("invalid_input", "A workspace file UUID is required.");
+    return value;
+}
+export function parseVisualRenderRequest(value) {
+    const ids = value.source_file_ids;
+    if (!Array.isArray(ids) || ids.length < 1 || ids.length > VISUAL_RENDER_LIMITS.maxPages) {
+        throw new OxygenError("invalid_input", "Choose between 1 and 12 HTML source files in page order.");
+    }
+    const source_file_ids = ids.map(validateVisualFileId);
+    const width = value.width ?? 1080, height = value.height ?? 1350, scale = value.scale ?? 1;
+    if (typeof width !== "number" || !Number.isInteger(width) || width < 1
+        || typeof height !== "number" || !Number.isInteger(height) || height < 1
+        || (scale !== 1 && scale !== 2)
+        || width * scale > VISUAL_RENDER_LIMITS.maxSide || height * scale > VISUAL_RENDER_LIMITS.maxSide
+        || width * height * scale * scale * ids.length > VISUAL_RENDER_LIMITS.maxPixels) {
+        throw new OxygenError("visual_render_limit", "Use scale 1 or 2, at most 4096 pixels per output side, and at most 32 million pixels across all pages.");
+    }
+    const formats = value.formats ?? ["png"];
+    if (!Array.isArray(formats) || formats.length < 1 || formats.length > 2
+        || formats.some((f) => f !== "png" && f !== "pdf") || new Set(formats).size !== formats.length) {
+        throw new OxygenError("invalid_input", "Formats must be png, pdf, or both.");
+    }
+    return { source_file_ids, width, height, scale, formats: formats };
+}
+/** No default snapshot or tariff: enabling this profile is an explicit deployment operation. */
+export function resolveVisualRenderProfile(env, now = Date.now()) {
+    const renderSnapshotId = env.OXYGEN_VISUAL_RENDER_SNAPSHOT_ID?.trim();
+    const validatorSnapshotId = env.OXYGEN_VISUAL_VALIDATOR_SNAPSHOT_ID?.trim();
+    const rendererDigest = env.OXYGEN_VISUAL_RENDERER_DIGEST?.trim();
+    const expiresAt = env.OXYGEN_VISUAL_PROFILE_EXPIRES_AT?.trim();
+    const credits = Number(env.OXYGEN_VISUAL_RENDER_CREDITS);
+    const maxCostMicros = Number(env.OXYGEN_VISUAL_RENDER_MAX_COST_MICROS);
+    if (env.OXYGEN_VISUAL_RENDER_ENABLED !== "1" || !renderSnapshotId || !validatorSnapshotId
+        || renderSnapshotId === validatorSnapshotId || !rendererDigest || !/^[a-f0-9]{64}$/.test(rendererDigest)
+        || !expiresAt || !Number.isFinite(Date.parse(expiresAt)) || Date.parse(expiresAt) <= now + 180_000
+        || !Number.isFinite(credits) || credits <= 0 || credits > 1000
+        || !Number.isSafeInteger(maxCostMicros) || maxCostMicros < 50_000 || maxCostMicros > 1_000_000)
+        return null;
+    return { version: VISUAL_RENDER_PROFILE, renderSnapshotId, validatorSnapshotId, rendererDigest, expiresAt, credits, maxCostMicros };
+}

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

@@ -0,0 +1,43 @@
+export declare const WORKSPACE_VISUAL_SOURCE_MAX_BYTES = 1500000;
+export declare const WORKSPACE_VISUAL_BINARY_MAX_BYTES: number;
+/** Platform abuse guard shared by every plan, not a storage entitlement. */
+export declare const WORKSPACE_RETAINED_FILES_MAX_BYTES: number;
+export type WorkspaceVisualBinaryMimeType = "image/png" | "application/pdf";
+export declare function assertWorkspaceFileId(id: string): void;
+export declare function normalizeWorkspaceVisualFileName(name: string): string;
+export declare function buildWorkspaceFileObjectKey(input: {
+    organizationId: string;
+    fileId: string;
+    fileName: string;
+}): string;
+export declare function isWorkspaceFileObjectKeyForOrganization(key: string, organizationId: string, fileId?: string): boolean;
+export declare function assertWorkspaceFileObjectKey(input: {
+    storageKey: string;
+    organizationId: string;
+    fileId?: string;
+}): void;
+/** Framing check only. Full media validation belongs in the isolated renderer validator. */
+export declare function assertWorkspaceVisualBinary(bytes: Uint8Array, mimeType: WorkspaceVisualBinaryMimeType): void;
+export declare function workspaceFileSha256(bytes: Uint8Array): string;
+export declare function readWorkspaceFileObject(input: {
+    organizationId: string;
+    fileId: string;
+    storageKey: string;
+    sizeBytes: number;
+    sha256: string;
+    mimeType: WorkspaceVisualBinaryMimeType;
+    signal?: AbortSignal;
+}): Promise<Uint8Array>;
+/** Immutable PUT followed by bounded readback. A matching existing object is a safe retry. */
+export declare function putWorkspaceFileObject(input: {
+    organizationId: string;
+    fileId: string;
+    fileName: string;
+    bytes: Uint8Array;
+    mimeType: WorkspaceVisualBinaryMimeType;
+    signal?: AbortSignal;
+}): Promise<{
+    storageKey: string;
+    sizeBytes: number;
+    sha256: string;
+}>;