@oxygen-agent/cli 1.948.1 → 1.987.20

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

@@ -176,8 +176,11 @@ export function isEspMatchingMode(value) {
     return typeof value === "string" && ESP_MATCHING_MODES.includes(value);
 }
 /**
- * Validate settings.esp_matching before persistence. Absent/null is valid (means
- * DEFAULT_ESP_MATCHING_MODE "off"); any other value must be one of the three
+ * Validate settings.esp_matching before persistence. Absent/null is valid and
+ * means DEFAULT_ESP_MATCHING_MODE, which is "prefer" — an unset sequence still
+ * biases rotation toward a same-provider sender, so a workspace whose senders on
+ * one provider are in bad standing concentrates that provider's recipients on
+ * them until an operator sets "off". Any other value must be one of the three
  * modes. Pure; throws OxygenError("invalid_sequence_settings") on a bad value so
  * the CLI / MCP / API report an identical error. Called from the tenant-db
  * settings validator alongside the budget/prioritization checks.
@@ -185,8 +188,88 @@ export function isEspMatchingMode(value) {
 export function validateEspMatchingSetting(value) {
     if (value === undefined || value === null)
         return;
-    if (!isEspMatchingMode(value)) {
-        throw new OxygenError("invalid_sequence_settings", `settings.esp_matching must be one of: ${ESP_MATCHING_MODES.join(", ")}.`, { details: { field: "esp_matching", value }, exitCode: 1 });
+    if (typeof value === "string" || typeof value !== "object" || Array.isArray(value)) {
+        if (!isEspMatchingMode(value)) {
+            throw new OxygenError("invalid_sequence_settings", `settings.esp_matching must be one of: ${ESP_MATCHING_MODES.join(", ")}.`, { details: { field: "esp_matching", value }, exitCode: 1 });
+        }
+        return;
+    }
+    validateEspRoutingPolicy(value);
+}
+/** Throw with the exact jsonb path that failed, so a typo is nameable rather than mysterious. */
+function espSettingError(path, message, value) {
+    return new OxygenError("invalid_sequence_settings", `settings.${path} ${message}`, {
+        details: { field: "esp_matching", path: `esp_matching.${path.replace(/^esp_matching\.?/, "")}`, ...(value === undefined ? {} : { value }) },
+        exitCode: 1,
+    });
+}
+/**
+ * Strict validation of the object form, the write-path counterpart to the
+ * lenient espPolicyFromSetting. Deliberately rejects UNKNOWN TOP-LEVEL KEYS by
+ * name: this setting's failure mode is invisible — a policy that silently did
+ * nothing because someone wrote "routs" would be discovered only as a month of
+ * mail sent from the wrong fleet.
+ */
+function validateEspRoutingPolicy(record) {
+    const allowed = new Set(["mode", "routes", "exclude"]);
+    for (const key of Object.keys(record)) {
+        if (!allowed.has(key)) {
+            throw espSettingError("esp_matching", `has an unknown key "${key}"; expected mode, routes or exclude.`);
+        }
+    }
+    if (record.mode !== undefined && record.mode !== null && !isEspMatchingMode(record.mode)) {
+        throw espSettingError("esp_matching.mode", `must be one of: ${ESP_MATCHING_MODES.join(", ")}.`, record.mode);
+    }
+    if (record.routes !== undefined && record.routes !== null) {
+        if (typeof record.routes !== "object" || Array.isArray(record.routes)) {
+            throw espSettingError("esp_matching.routes", "must be an object keyed by recipient provider.");
+        }
+        for (const [bucket, weights] of Object.entries(record.routes)) {
+            if (!isEspRouteBucket(bucket)) {
+                throw espSettingError("esp_matching.routes", `has an unknown recipient "${bucket}"; expected one of: ${ESP_ROUTE_BUCKETS.join(", ")}.`);
+            }
+            if (typeof weights !== "object" || weights === null || Array.isArray(weights)) {
+                throw espSettingError(`esp_matching.routes.${bucket}`, "must be an object of sender weights.");
+            }
+            for (const [provider, weight] of Object.entries(weights)) {
+                if (!RECIPIENT_ESPS.includes(provider)) {
+                    throw espSettingError(`esp_matching.routes.${bucket}`, `has an unknown sender "${provider}"; expected one of: ${RECIPIENT_ESPS.join(", ")}.`);
+                }
+                if (typeof weight !== "number" || !Number.isFinite(weight) || weight < 0 || weight > MAX_ESP_ROUTE_WEIGHT) {
+                    throw espSettingError(`esp_matching.routes.${bucket}.${provider}`, `must be a number between 0 and ${MAX_ESP_ROUTE_WEIGHT}.`, weight);
+                }
+            }
+        }
+    }
+    if (record.exclude !== undefined && record.exclude !== null) {
+        if (!Array.isArray(record.exclude)) {
+            throw espSettingError("esp_matching.exclude", "must be an array of sender-domain exclusions.");
+        }
+        if (record.exclude.length > MAX_ESP_SENDER_EXCLUSIONS) {
+            throw espSettingError("esp_matching.exclude", `must hold at most ${MAX_ESP_SENDER_EXCLUSIONS} entries; it is a routing policy, not a suppression list.`);
+        }
+        record.exclude.forEach((entry, index) => {
+            if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+                throw espSettingError(`esp_matching.exclude[${index}]`, "must be an object with a domain.");
+            }
+            const item = entry;
+            for (const key of Object.keys(item)) {
+                if (key !== "domain" && key !== "from_recipients") {
+                    throw espSettingError(`esp_matching.exclude[${index}]`, `has an unknown key "${key}".`);
+                }
+            }
+            if (typeof item.domain !== "string" || !normalizeEspSenderDomain(item.domain)) {
+                throw espSettingError(`esp_matching.exclude[${index}].domain`, "must be a non-empty sending domain.", item.domain);
+            }
+            if (normalizeEspSenderDomain(item.domain).length > 253) {
+                throw espSettingError(`esp_matching.exclude[${index}].domain`, "must be at most 253 characters.");
+            }
+            if (item.from_recipients !== undefined && item.from_recipients !== null) {
+                if (!Array.isArray(item.from_recipients) || !item.from_recipients.every(isEspRouteBucket)) {
+                    throw espSettingError(`esp_matching.exclude[${index}].from_recipients`, `must be an array of: ${ESP_ROUTE_BUCKETS.join(", ")}.`);
+                }
+            }
+        });
     }
 }
 /**
@@ -201,6 +284,199 @@ export function validateEspMatchingSetting(value) {
  * as "microsoft" — see resolveEspFamily.
  */
 export const RECIPIENT_ESPS = ["google", "microsoft"];
+/**
+ * WEIGHTED SENDER ROUTING — the object form of settings.esp_matching.
+ *
+ * The three scalar modes above answer one question ("bias toward the recipient's
+ * own provider, yes or no"), and they bake in the assumption that same-provider
+ * is always better. That assumption fails whenever one provider's senders are in
+ * bad standing: a workspace whose Google-hosted domains are refused by Gmail
+ * wants its Google-hosted RECIPIENTS served from Microsoft senders, which no
+ * scalar mode can express. "off" does not express it either, because free
+ * rotation still hands Google recipients a Google sender in proportion to the
+ * pool.
+ *
+ * So the object form states the routing directly, as SEND SHARES per recipient
+ * provider:
+ *
+ *   { mode: "prefer",
+ *     routes: { google: { microsoft: 100 }, microsoft: { microsoft: 100 } },
+ *     exclude: [{ domain: "burned.example", from_recipients: ["google"] }] }
+ *
+ * `routes` is keyed by the RECIPIENT's resolved provider; the inner map is the
+ * SENDER provider. Weights are relative shares, so { google: 3, microsoft: 1 }
+ * and { google: 75, microsoft: 25 } are the same policy and nothing has to sum
+ * to 100. An omitted weight is zero. A bucket whose entry is explicitly present
+ * but carries no positive weight means "no opinion, rotate freely for this
+ * recipient class"; a bucket the operator never mentioned keeps the historical
+ * same-provider default, so editing Google routing cannot silently change how
+ * Microsoft recipients are served.
+ *
+ * `exclude` is a hard never, not a preference: a sender domain listed here is
+ * removed from the candidate pool for the named recipient buckets (all buckets
+ * when `from_recipients` is absent) in EVERY mode, including "off", and it
+ * survives the prefer-fallback. A deliverability guard that a matching toggle
+ * could disarm would not be a guard.
+ *
+ * The scalar modes remain valid values and are read as policies, so there is one
+ * routing code path rather than two: "prefer" becomes { mode: "prefer" } with no
+ * routes, which resolves to the same-provider default and behaves exactly as it
+ * did before.
+ */
+export const ESP_ROUTE_BUCKETS = ["google", "microsoft", "unknown"];
+/** Cap on settings.esp_matching.exclude — a routing policy, not a suppression list. */
+export const MAX_ESP_SENDER_EXCLUSIONS = 50;
+/** Upper bound on a single route weight; relative shares never need more. */
+export const MAX_ESP_ROUTE_WEIGHT = 1_000_000;
+export function isEspRouteBucket(value) {
+    return typeof value === "string" && ESP_ROUTE_BUCKETS.includes(value);
+}
+function isRecipientEspValue(value) {
+    return typeof value === "string" && RECIPIENT_ESPS.includes(value);
+}
+/**
+ * A sending domain as the mailbox table stores it: lowercase, no leading "@".
+ * Mirrors lower(split_part(email_address, '@', 2)) in pickEmailMailbox so an
+ * exclusion the operator typed as "@Burned.Example " still matches.
+ */
+export function normalizeEspSenderDomain(value) {
+    return value.trim().toLowerCase().replace(/^@+/, "");
+}
+/**
+ * LENIENT read of a persisted settings.esp_matching (never throws — a read must
+ * not break a send). Absent, null, or malformed reads as the default policy, and
+ * a malformed FIELD bails the WHOLE object rather than half-applying a routing
+ * policy, which is the readMailboxRampConfig convention in tenant-db. The strict
+ * counterpart that guards the write path is validateEspMatchingSetting.
+ */
+export function espPolicyFromSetting(value) {
+    const fallback = { mode: DEFAULT_ESP_MATCHING_MODE, routes: {}, exclude: [] };
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value === "string") {
+        return isEspMatchingMode(value) ? { mode: value, routes: {}, exclude: [] } : fallback;
+    }
+    if (typeof value !== "object" || Array.isArray(value))
+        return fallback;
+    const record = value;
+    const mode = record.mode === undefined || record.mode === null ? DEFAULT_ESP_MATCHING_MODE : record.mode;
+    if (!isEspMatchingMode(mode))
+        return fallback;
+    const routes = {};
+    if (record.routes !== undefined && record.routes !== null) {
+        if (typeof record.routes !== "object" || Array.isArray(record.routes))
+            return fallback;
+        for (const [bucket, raw] of Object.entries(record.routes)) {
+            if (!isEspRouteBucket(bucket))
+                return fallback;
+            if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+                return fallback;
+            const weights = {};
+            for (const [provider, weight] of Object.entries(raw)) {
+                if (!isRecipientEspValue(provider))
+                    return fallback;
+                if (typeof weight !== "number" || !Number.isFinite(weight) || weight < 0)
+                    return fallback;
+                weights[provider] = weight;
+            }
+            routes[bucket] = weights;
+        }
+    }
+    const exclude = [];
+    if (record.exclude !== undefined && record.exclude !== null) {
+        if (!Array.isArray(record.exclude))
+            return fallback;
+        for (const entry of record.exclude) {
+            if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+                return fallback;
+            const item = entry;
+            if (typeof item.domain !== "string")
+                return fallback;
+            const domain = normalizeEspSenderDomain(item.domain);
+            if (!domain)
+                return fallback;
+            let buckets = ESP_ROUTE_BUCKETS;
+            if (item.from_recipients !== undefined && item.from_recipients !== null) {
+                if (!Array.isArray(item.from_recipients))
+                    return fallback;
+                if (item.from_recipients.length > 0) {
+                    if (!item.from_recipients.every(isEspRouteBucket))
+                        return fallback;
+                    buckets = item.from_recipients;
+                }
+            }
+            exclude.push({ domain, buckets });
+        }
+    }
+    return { mode, routes, exclude };
+}
+/**
+ * The effective send shares for one recipient bucket. An explicitly-present
+ * entry wins even when it is empty or all-zero (that is the operator saying
+ * "rotate freely here"); a bucket that was never mentioned keeps the historical
+ * same-provider default, and "unknown" has no same-provider to default to.
+ */
+export function espRouteWeightsFor(policy, bucket) {
+    const configured = policy.routes[bucket];
+    if (configured)
+        return configured;
+    return bucket === "unknown" ? {} : { [bucket]: 1 };
+}
+/**
+ * The sender providers to try, best first, for one recipient bucket — a
+ * deterministic weighted shuffle WITHOUT replacement.
+ *
+ * Returning an ORDER rather than a single draw is what makes "prefer" correct:
+ * a 90/10 Google policy over a pool holding no Google mailbox must send 100%
+ * from Microsoft, not defer and not fall through to provider-blind rotation.
+ * An empty result means "no opinion" and the caller rotates freely.
+ *
+ * Deterministic by construction: the seed carries the enrollment and step, never
+ * a clock or Math.random, so a dry-run preview and the later live send choose
+ * the same provider, and a replan after a defer re-derives the same route.
+ * Candidates are enumerated in RECIPIENT_ESPS order rather than object-key
+ * order, because jsonb does not preserve key order and a policy that round-trips
+ * through the database must not reroute the fleet.
+ */
+export function espRouteCandidates(input) {
+    const weights = espRouteWeightsFor(input.policy, input.recipient);
+    let pool = RECIPIENT_ESPS.map((provider) => ({ provider, weight: weights[provider] ?? 0 })).filter((entry) => Number.isFinite(entry.weight) && entry.weight > 0);
+    const order = [];
+    let draw = 0;
+    while (pool.length > 0) {
+        const total = pool.reduce((sum, entry) => sum + entry.weight, 0);
+        // Re-hash per draw rather than reusing the residue: a second draw derived
+        // from the first would correlate the tail of the order with its head.
+        const seed = draw === 0 ? input.seed : `${input.seed}:${draw + 1}`;
+        const target = ((hashVariantKey(seed) % 1_000_000) / 1_000_000) * total;
+        let cumulative = 0;
+        let chosen = pool[pool.length - 1].provider;
+        for (const entry of pool) {
+            cumulative += entry.weight;
+            if (target < cumulative) {
+                chosen = entry.provider;
+                break;
+            }
+        }
+        order.push(chosen);
+        pool = pool.filter((entry) => entry.provider !== chosen);
+        draw += 1;
+    }
+    return order;
+}
+/**
+ * Sending domains that must not serve this recipient bucket, normalized and
+ * de-duplicated for pickEmailMailbox. Applies in every mode and survives the
+ * prefer-fallback — see the exclude contract above.
+ */
+export function espExcludedSenderDomains(policy, bucket) {
+    const domains = new Set();
+    for (const entry of policy.exclude) {
+        if (entry.buckets.includes(bucket))
+            domains.add(entry.domain);
+    }
+    return [...domains];
+}
 /**
  * The DISPLAY taxonomy: the mail-infrastructure family a recipient domain sits
  * on. Wider than RecipientEsp because "everything that isn't Google or Microsoft"
@@ -900,6 +1176,22 @@ export function validateSequenceDefinition(input, options = {}) {
     return { steps: normalized };
 }
 /** Non-throwing variant for lint surfaces. */
+/**
+ * The non-blocking notices normalizing this definition would raise, for a
+ * response `warnings` array. Never throws: an invalid definition yields whatever
+ * notices were collected before validation gave up (the caller's own validate
+ * call reports the failure), so this is safe to run beside a persist.
+ */
+export function sequenceDefinitionNotices(input, options = {}) {
+    const notices = [];
+    try {
+        validateSequenceDefinition(input, { ...options, notices });
+    }
+    catch {
+        // Reported by the caller's own validation; the notices gathered so far stand.
+    }
+    return notices;
+}
 export function lintSequenceDefinition(input, options = {}) {
     try {
         validateSequenceDefinition(input, options);
@@ -1102,6 +1394,14 @@ raw, index, options, issues) {
             const cc = optionalEmailList(raw.cc, `${path}.cc`, issues);
             const bcc = optionalEmailList(raw.bcc, `${path}.bcc`, issues);
             const sendWindow = normalizeSendWindow(raw.send_window, `${path}.send_window`, issues);
+            // Say so. The rewrite is deliberate compatibility, but a definition read back
+            // with a different `kind` than was written, and nothing in the response to
+            // explain it, reads as data loss to the author.
+            options.notices?.push({
+                path: `${path}.kind`,
+                code: "email_reply_rewritten",
+                message: `step '${id}': kind 'email_reply' is retired and was stored as 'email_send' with no subject_template — the threaded follow-up. It goes out as "Re: <the previous email's subject>" inside the lead's previous thread; give it a subject_template of its own to start a new email instead.`,
+            });
             return {
                 id, channel: "email", kind: "email_send", body_template: body ?? "",
                 ...(bodyHtml !== undefined ? { body_html_template: bodyHtml } : {}),

package/node_modules/@oxygen/shared/dist/ugc-amplification-identity.d.ts

@@ -0,0 +1,2 @@
+/** Provider aliases for the same public post must share one deduplication key. */
+export declare function normalizeLinkedInAmplificationTargetId(value: string): string | null;

package/node_modules/@oxygen/shared/dist/ugc-amplification-identity.js

@@ -0,0 +1,24 @@
+import { linkedinPostIdFromUrl, looksLikeUrlIdentifier } from "./linkedin-url.js";
+/** Provider aliases for the same public post must share one deduplication key. */
+export function normalizeLinkedInAmplificationTargetId(value) {
+    const raw = value.trim();
+    if (!raw || raw.length > 2048)
+        return null;
+    const activity = /^(?:urn:li:(?:activity|share):|linkedin:activity:)?(\d+)$/.exec(raw)?.[1];
+    if (activity)
+        return `linkedin:activity:${activity}`;
+    if (looksLikeUrlIdentifier(raw)) {
+        let url;
+        try {
+            url = new URL(/^https?:\/\//i.test(raw) ? raw : `https://${raw}`);
+        }
+        catch {
+            return null;
+        }
+        if (!/^(?:www\.)?linkedin\.com$/i.test(url.hostname) || url.username || url.password)
+            return null;
+        const id = linkedinPostIdFromUrl(raw);
+        return id ? `linkedin:activity:${id}` : null;
+    }
+    return raw.startsWith("linkedin:opaque:") ? raw : `linkedin:opaque:${raw}`;
+}

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

@@ -7,6 +7,9 @@ export type UgcProgram = {
     description: string;
     knowledgePageSlugs: string[];
     brandApprovalRequired: boolean;
+    peerEngagementEnabled?: boolean;
+    peerEngagementVersion?: number;
+    peerEngagementEffectiveAt?: Date | null;
     status: "active" | "archived";
     createdAt: Date;
     updatedAt: Date;
@@ -22,6 +25,8 @@ export type UgcBrief = {
     updatedAt: Date;
 };
 export type UgcPostProjection = {
+    /** Public author identity from the exact participation, never a private profile corpus. */
+    authorLinkedinUrl?: string;
     title?: string | null;
     contentText: string;
     status: string;
@@ -86,6 +91,9 @@ export type UgcPostLink = {
     creatorApprovedRevision: string | null;
     brandApprovedRevision: string | null;
     grantVersion: number;
+    removedAt?: Date | null;
+    enrollmentVersion?: number;
+    projectionVersion?: number;
     createdAt: Date;
     updatedAt: Date;
 };

package/node_modules/@oxygen/shared/dist/user-capability-routing.js

@@ -8,9 +8,16 @@ export function inferUserCapabilityRoute(query) {
     const route = inferCapabilityRoute(query);
     const providerConnectionIntent = isSimpleProviderConnectionIntent(query);
     if (!providerConnectionIntent
-        || (route?.card.id !== "tables" && route?.card.id !== "workspace-access")) {
+        || (route != null && route.card.id !== "tables" && route.card.id !== "workspace-access")) {
         return route;
     }
+    // `route == null` is corrected too, and that case used to be unreachable for the
+    // wrong reason: "reconnect my Salesforce account" only entered this branch
+    // because the scorer matched Tables' `connect` term INSIDE "re-connect". Once
+    // the scorer anchors terms to word boundaries the base router correctly has no
+    // opinion, and a wrapper that only corrected an existing Tables answer would
+    // have handed the user nothing at all. An unrouted simple provider-connection
+    // intent is exactly what this wrapper exists to answer.
     return getCapabilityRouteMatch("connected-integrations") ?? route;
 }
 // The words that mean "this is Tables work, not a provider connection". Hand-typing

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

@@ -1,4 +1,4 @@
-export declare const OXYGEN_VERSION = "1.948.1";
+export declare const OXYGEN_VERSION: string;
 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,6 @@
-export const OXYGEN_VERSION = "1.948.1";
+// Release metadata is a string API: a new version must not change the exported
+// declaration type and invalidate every dependent package's compiler state.
+export const OXYGEN_VERSION = "1.987.20";
 // 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/workspace-file-storage.d.ts

@@ -1,8 +1,10 @@
 export declare const WORKSPACE_VISUAL_SOURCE_MAX_BYTES = 1500000;
 export declare const WORKSPACE_VISUAL_BINARY_MAX_BYTES: number;
+export declare const WORKSPACE_OPAQUE_FILE_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 type WorkspaceStoredFileMimeType = WorkspaceVisualBinaryMimeType | "application/octet-stream";
 export declare function assertWorkspaceFileId(id: string): void;
 export declare function normalizeWorkspaceVisualFileName(name: string): string;
 export declare function buildWorkspaceFileObjectKey(input: {
@@ -19,13 +21,15 @@ export declare function assertWorkspaceFileObjectKey(input: {
 /** 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;
+/** Opaque vault attachments are downloaded as bytes, never rendered as active content. */
+export declare function assertWorkspaceStoredFile(bytes: Uint8Array, mimeType: WorkspaceStoredFileMimeType): void;
 export declare function readWorkspaceFileObject(input: {
     organizationId: string;
     fileId: string;
     storageKey: string;
     sizeBytes: number;
     sha256: string;
-    mimeType: WorkspaceVisualBinaryMimeType;
+    mimeType: WorkspaceStoredFileMimeType;
     signal?: AbortSignal;
 }): Promise<Uint8Array>;
 /** Immutable PUT followed by bounded readback. A matching existing object is a safe retry. */
@@ -34,7 +38,7 @@ export declare function putWorkspaceFileObject(input: {
     fileId: string;
     fileName: string;
     bytes: Uint8Array;
-    mimeType: WorkspaceVisualBinaryMimeType;
+    mimeType: WorkspaceStoredFileMimeType;
     signal?: AbortSignal;
 }): Promise<{
     storageKey: string;

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

@@ -5,6 +5,7 @@ import { OxygenError } from "./cli-result.js";
 import { resolveObjectStorageClient } from "./object-storage.js";
 export const WORKSPACE_VISUAL_SOURCE_MAX_BYTES = 1_500_000;
 export const WORKSPACE_VISUAL_BINARY_MAX_BYTES = 50 * 1024 * 1024;
+export const WORKSPACE_OPAQUE_FILE_MAX_BYTES = 100 * 1024 * 1024;
 /** Platform abuse guard shared by every plan, not a storage entitlement. */
 export const WORKSPACE_RETAINED_FILES_MAX_BYTES = 1024 * 1024 * 1024;
 const STORAGE_TIMEOUT_MS = 60_000;
@@ -57,16 +58,26 @@ export function assertWorkspaceVisualBinary(bytes, mimeType) {
 export function workspaceFileSha256(bytes) {
     return createHash("sha256").update(bytes).digest("hex");
 }
+/** Opaque vault attachments are downloaded as bytes, never rendered as active content. */
+export function assertWorkspaceStoredFile(bytes, mimeType) {
+    if (mimeType === "application/octet-stream") {
+        if (bytes.byteLength > WORKSPACE_OPAQUE_FILE_MAX_BYTES)
+            throw new OxygenError("workspace_file_too_large", "File exceeds 100 MiB.");
+        return;
+    }
+    assertWorkspaceVisualBinary(bytes, mimeType);
+}
 export async function readWorkspaceFileObject(input) {
     input.signal?.throwIfAborted();
     assertWorkspaceFileObjectKey(input);
-    if (!Number.isSafeInteger(input.sizeBytes) || input.sizeBytes < 1 || input.sizeBytes > WORKSPACE_VISUAL_BINARY_MAX_BYTES || !/^[a-f0-9]{64}$/.test(input.sha256)) {
+    const maximumBytes = input.mimeType === "application/octet-stream" ? WORKSPACE_OPAQUE_FILE_MAX_BYTES : WORKSPACE_VISUAL_BINARY_MAX_BYTES;
+    if (!Number.isSafeInteger(input.sizeBytes) || input.sizeBytes < (input.mimeType === "application/octet-stream" ? 0 : 1) || input.sizeBytes > maximumBytes || !/^[a-f0-9]{64}$/.test(input.sha256)) {
         throw new OxygenError("workspace_file_integrity_failed", "File metadata failed integrity validation.");
     }
     const { client, bucket } = resolveObjectStorageClient();
     const signal = input.signal ? AbortSignal.any([input.signal, AbortSignal.timeout(STORAGE_TIMEOUT_MS)]) : AbortSignal.timeout(STORAGE_TIMEOUT_MS);
     const result = await client.send(new GetObjectCommand({
-        Bucket: bucket, Key: input.storageKey, Range: `bytes=0-${input.sizeBytes}`,
+        Bucket: bucket, Key: input.storageKey, ...(input.sizeBytes > 0 ? { Range: `bytes=0-${input.sizeBytes}` } : {}),
     }), { abortSignal: signal });
     const body = result.Body;
     if (!body)
@@ -93,7 +104,7 @@ export async function readWorkspaceFileObject(input) {
         if (size !== input.sizeBytes || workspaceFileSha256(bytes) !== input.sha256 || result.ContentType?.split(";", 1)[0]?.trim().toLowerCase() !== input.mimeType) {
             throw new OxygenError("workspace_file_integrity_failed", "Stored file failed size, format or digest verification.");
         }
-        assertWorkspaceVisualBinary(bytes, input.mimeType);
+        assertWorkspaceStoredFile(bytes, input.mimeType);
         return bytes;
     }
     finally {
@@ -104,7 +115,7 @@ export async function readWorkspaceFileObject(input) {
 /** Immutable PUT followed by bounded readback. A matching existing object is a safe retry. */
 export async function putWorkspaceFileObject(input) {
     input.signal?.throwIfAborted();
-    assertWorkspaceVisualBinary(input.bytes, input.mimeType);
+    assertWorkspaceStoredFile(input.bytes, input.mimeType);
     const storageKey = buildWorkspaceFileObjectKey(input);
     const bytes = Buffer.from(input.bytes);
     const sha256 = workspaceFileSha256(bytes);

package/node_modules/@oxygen/shared/package.json

@@ -6,6 +6,11 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
+    "./knowledge-vault-markdown": {
+      "types": "./dist/knowledge-vault-markdown.d.ts",
+      "import": "./dist/knowledge-vault-markdown.js",
+      "default": "./dist/knowledge-vault-markdown.js"
+    },
     "./vercel-sandbox-fetch": {
       "types": "./dist/vercel-sandbox-fetch.d.ts",
       "import": "./dist/vercel-sandbox-fetch.js",
@@ -31,6 +36,11 @@
       "import": "./dist/import-limits.js",
       "default": "./dist/import-limits.js"
     },
+    "./inbox-avatar-url": {
+      "types": "./dist/inbox-avatar-url.d.ts",
+      "import": "./dist/inbox-avatar-url.js",
+      "default": "./dist/inbox-avatar-url.js"
+    },
     "./image-sniff": {
       "types": "./dist/image-sniff.d.ts",
       "import": "./dist/image-sniff.js",
@@ -136,6 +146,11 @@
       "import": "./dist/knowledge-constants.js",
       "default": "./dist/knowledge-constants.js"
     },
+    "./knowledge-bases": {
+      "types": "./dist/knowledge-bases.d.ts",
+      "import": "./dist/knowledge-bases.js",
+      "default": "./dist/knowledge-bases.js"
+    },
     "./workflow-status-change": {
       "types": "./dist/workflow-status-change.d.ts",
       "import": "./dist/workflow-status-change.js",
@@ -161,6 +176,16 @@
       "import": "./dist/copilot-journeys.js",
       "default": "./dist/copilot-journeys.js"
     },
+    "./copilot-playbooks": {
+      "types": "./dist/copilot-playbooks.d.ts",
+      "import": "./dist/copilot-playbooks.js",
+      "default": "./dist/copilot-playbooks.js"
+    },
+    "./copilot-skills": {
+      "types": "./dist/copilot-skills.d.ts",
+      "import": "./dist/copilot-skills.js",
+      "default": "./dist/copilot-skills.js"
+    },
     "./hosted-ai": {
       "types": "./dist/hosted-ai.d.ts",
       "import": "./dist/hosted-ai.js",