@oxygen-agent/cli 1.739.1 → 1.766.0

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

@@ -1,4 +1,4 @@
-export { MANAGED_INBOX_MINIMUM_CLI_VERSION, OXYGEN_MINIMUM_CLI_VERSION, OXYGEN_VERSION, } from "./version.js";
+export { MANAGED_INBOX_MINIMUM_CLI_VERSION, OXYGEN_MINIMUM_CLI_VERSION, OXYGEN_VERSION, SUPPORT_AGENT_REPLY_MINIMUM_CLI_VERSION, } from "./version.js";
 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";
@@ -6,8 +6,11 @@ export * from "./billing-anchors.js";
 export * from "./budget-scopes.js";
 export * from "./capability-discovery.js";
 export * from "./user-capability-routing.js";
+export * from "./plan-capabilities.js";
 export * from "./plan-limits.js";
 export * from "./plain-support-events.js";
+export * from "./provider-funding-errors.js";
+export * from "./publishing-limits.js";
 export * from "./spend-safety.js";
 export * from "./cell-format.js";
 export * from "./cli-envelope.js";
@@ -42,6 +45,7 @@ export * from "./linkedin-sequences.js";
 export * from "./member-columns.js";
 export * from "./microsoft-consent-url.js";
 export * from "./networks.js";
+export * from "./person-name.js";
 export * from "./recipes.js";
 export * from "./sequence-template.js";
 export * from "./sequence-crm-events.js";

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

@@ -1,4 +1,4 @@
-export { MANAGED_INBOX_MINIMUM_CLI_VERSION, OXYGEN_MINIMUM_CLI_VERSION, OXYGEN_VERSION, } from "./version.js";
+export { MANAGED_INBOX_MINIMUM_CLI_VERSION, OXYGEN_MINIMUM_CLI_VERSION, OXYGEN_VERSION, SUPPORT_AGENT_REPLY_MINIMUM_CLI_VERSION, } from "./version.js";
 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";
@@ -6,8 +6,11 @@ export * from "./billing-anchors.js";
 export * from "./budget-scopes.js";
 export * from "./capability-discovery.js";
 export * from "./user-capability-routing.js";
+export * from "./plan-capabilities.js";
 export * from "./plan-limits.js";
 export * from "./plain-support-events.js";
+export * from "./provider-funding-errors.js";
+export * from "./publishing-limits.js";
 export * from "./spend-safety.js";
 export * from "./cell-format.js";
 export * from "./cli-envelope.js";
@@ -42,6 +45,7 @@ export * from "./linkedin-sequences.js";
 export * from "./member-columns.js";
 export * from "./microsoft-consent-url.js";
 export * from "./networks.js";
+export * from "./person-name.js";
 export * from "./recipes.js";
 export * from "./sequence-template.js";
 export * from "./sequence-crm-events.js";

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

@@ -125,6 +125,25 @@ export declare function presignInboxAvatarUpload(input: {
     contentType: string;
     contentLength: number;
 }): Promise<PresignedImportUpload>;
+/**
+ * Store avatar bytes we already hold server-side.
+ *
+ * The presign/PUT/confirm dance exists so a BROWSER can upload without routing
+ * megabytes through a serverless function. When the server is the one holding the
+ * bytes — mirroring a LinkedIn photo so it survives past that URL's expiry — a
+ * presigned round trip back to ourselves buys nothing. `contentType` must come from
+ * a byte sniff, never from the remote's header, for the same reason the confirm hop
+ * re-sniffs: the public route serves this back from our own origin.
+ */
+export declare function putInboxAvatarObject(input: {
+    organizationId: string;
+    body: Uint8Array;
+    contentType: string;
+    fileName: string;
+}): Promise<{
+    storageKey: string;
+    contentLength: number;
+}>;
 /**
  * Read an avatar back, bounded. `maxBytes` is a hard stop rather than a hint:
  * this is called from an unauthenticated route, so an object that somehow grew
@@ -144,8 +163,22 @@ export declare function getInboxAvatarObjectMetadata(input: {
 }): Promise<{
     contentLength: number | null;
 }>;
+/**
+ * Delete a stored avatar.
+ *
+ * The prefix assertion is load-bearing, not defensive dressing. One bucket holds
+ * `imports/<org>/` (customer lead lists), `copilot/<org>/`, `publishing-media/<org>/`
+ * and `inbox-avatars/<org>/`, and this issues a bare DeleteObjectCommand — so any
+ * caller that ever passed a key it did not build itself would be one string away
+ * from deleting another tenant's uploaded CSV. Avatar keys reach durable state
+ * (`sender_profiles.avatar_storage_key`) and come back out again on replace and on
+ * profile delete, which is exactly the round trip where a key stops being obviously
+ * trustworthy. Pass `organizationId` wherever it is known: the prefix check alone
+ * only proves "some org's avatar".
+ */
 export declare function deleteInboxAvatarObject(input: {
     storageKey: string;
+    organizationId?: string;
 }): Promise<void>;
 export declare function deleteImportObject(input: {
     storageKey: string;

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

@@ -8,6 +8,26 @@ import { OxygenError } from "./cli-result.js";
 // it. Configured against Hetzner Object Storage (S3-compatible) via the
 // OXYGEN_IMPORT_S3_* env vars; works with any S3-compatible endpoint.
 const PRESIGN_EXPIRY_SECONDS = 900;
+/**
+ * Sign `Content-Type` on every upload presign.
+ *
+ * `@smithy/signature-v4`'s `prepareRequest` does an unconditional
+ * `unsignableHeaders.add("content-type")`, so by default the header we declare
+ * on the PutObjectCommand is NOT part of the signature and the client may send
+ * anything. A customer hit exactly that: `curl --upload-file` defaults to
+ * `application/x-www-form-urlencoded`, S3 accepted the PUT, and the stored
+ * object's content type silently disagreed with its own bytes — surfacing much
+ * later as a scheduled post whose image would not render.
+ *
+ * `signableHeaders` takes precedence over the unsignable set (see
+ * `getCanonicalHeaders`), so this makes S3 reject the mismatched PUT at upload
+ * time instead. It only binds when we actually declared a ContentType; with no
+ * declared type there is no such header on the request and nothing is enforced.
+ */
+const PRESIGN_UPLOAD_OPTIONS = {
+    expiresIn: PRESIGN_EXPIRY_SECONDS,
+    signableHeaders: new Set(["content-type"]),
+};
 // The Fly worker publishes tenants serially, so a hung S3 GET on one tenant's
 // publishing media would stall every other tenant's publishing tick. Bound the
 // media download the same way the native-provider fetches are bounded
@@ -107,7 +127,7 @@ export async function presignImportUpload(input) {
         ContentLength: input.contentLength,
         ...(input.contentType ? { ContentType: input.contentType } : {}),
     });
-    const uploadUrl = await getSignedUrl(client, command, { expiresIn: PRESIGN_EXPIRY_SECONDS });
+    const uploadUrl = await getSignedUrl(client, command, { ...PRESIGN_UPLOAD_OPTIONS });
     return {
         uploadUrl,
         bucket: config.bucket,
@@ -129,7 +149,7 @@ export async function presignPublishingMediaUpload(input) {
         ContentLength: input.contentLength,
         ...(input.contentType ? { ContentType: input.contentType } : {}),
     });
-    const uploadUrl = await getSignedUrl(client, command, { expiresIn: PRESIGN_EXPIRY_SECONDS });
+    const uploadUrl = await getSignedUrl(client, command, { ...PRESIGN_UPLOAD_OPTIONS });
     return {
         uploadUrl,
         bucket: config.bucket,
@@ -151,7 +171,7 @@ export async function presignCopilotAttachmentUpload(input) {
         ContentLength: input.contentLength,
         ...(input.contentType ? { ContentType: input.contentType } : {}),
     });
-    const uploadUrl = await getSignedUrl(client, command, { expiresIn: PRESIGN_EXPIRY_SECONDS });
+    const uploadUrl = await getSignedUrl(client, command, { ...PRESIGN_UPLOAD_OPTIONS });
     return {
         uploadUrl,
         bucket: config.bucket,
@@ -279,7 +299,7 @@ export async function presignInboxAvatarUpload(input) {
         ContentLength: input.contentLength,
         ContentType: input.contentType,
     });
-    const uploadUrl = await getSignedUrl(client, command, { expiresIn: PRESIGN_EXPIRY_SECONDS });
+    const uploadUrl = await getSignedUrl(client, command, { ...PRESIGN_UPLOAD_OPTIONS });
     return {
         uploadUrl,
         bucket: config.bucket,
@@ -289,6 +309,31 @@ export async function presignInboxAvatarUpload(input) {
         expiresInSeconds: PRESIGN_EXPIRY_SECONDS,
     };
 }
+/**
+ * Store avatar bytes we already hold server-side.
+ *
+ * The presign/PUT/confirm dance exists so a BROWSER can upload without routing
+ * megabytes through a serverless function. When the server is the one holding the
+ * bytes — mirroring a LinkedIn photo so it survives past that URL's expiry — a
+ * presigned round trip back to ourselves buys nothing. `contentType` must come from
+ * a byte sniff, never from the remote's header, for the same reason the confirm hop
+ * re-sniffs: the public route serves this back from our own origin.
+ */
+export async function putInboxAvatarObject(input) {
+    const { client, config } = resolveClient();
+    const storageKey = buildInboxAvatarObjectKey({
+        organizationId: input.organizationId,
+        fileName: input.fileName,
+    });
+    await client.send(new PutObjectCommand({
+        Bucket: config.bucket,
+        Key: storageKey,
+        Body: input.body,
+        ContentLength: input.body.byteLength,
+        ContentType: input.contentType,
+    }));
+    return { storageKey, contentLength: input.body.byteLength };
+}
 /**
  * Read an avatar back, bounded. `maxBytes` is a hard stop rather than a hint:
  * this is called from an unauthenticated route, so an object that somehow grew
@@ -318,7 +363,27 @@ export async function getInboxAvatarObjectMetadata(input) {
         contentLength: typeof result.ContentLength === "number" ? result.ContentLength : null,
     };
 }
+/**
+ * Delete a stored avatar.
+ *
+ * The prefix assertion is load-bearing, not defensive dressing. One bucket holds
+ * `imports/<org>/` (customer lead lists), `copilot/<org>/`, `publishing-media/<org>/`
+ * and `inbox-avatars/<org>/`, and this issues a bare DeleteObjectCommand — so any
+ * caller that ever passed a key it did not build itself would be one string away
+ * from deleting another tenant's uploaded CSV. Avatar keys reach durable state
+ * (`sender_profiles.avatar_storage_key`) and come back out again on replace and on
+ * profile delete, which is exactly the round trip where a key stops being obviously
+ * trustworthy. Pass `organizationId` wherever it is known: the prefix check alone
+ * only proves "some org's avatar".
+ */
 export async function deleteInboxAvatarObject(input) {
+    if (!input.storageKey.startsWith("inbox-avatars/")) {
+        throw new OxygenError("invalid_object_key", "Refusing to delete an object outside the inbox-avatars prefix.", { details: { prefix: input.storageKey.split("/")[0] ?? "" }, exitCode: 1 });
+    }
+    if (input.organizationId
+        && !isInboxAvatarObjectKeyForOrganization(input.storageKey, input.organizationId)) {
+        throw new OxygenError("invalid_object_key", "Refusing to delete an avatar that belongs to another organization.", { exitCode: 1 });
+    }
     const { client, config } = resolveClient();
     await client.send(new DeleteObjectCommand({ Bucket: config.bucket, Key: input.storageKey }));
 }

package/node_modules/@oxygen/shared/dist/person-name.d.ts

@@ -0,0 +1,40 @@
+/**
+ * One split rule for "a person's display name" -> given name + family name.
+ *
+ * This exists because the answer is written to a place that can never be
+ * corrected. The managed-inbox vendor takes `first_name` + `last_name` at ORDER
+ * time and exposes no post-provisioning update, so whatever split runs is stamped
+ * on a paid mailbox forever. Two surfaces derive it — the sender-profile editor
+ * (prefilling the two inputs from an older single-`name` profile) and the order
+ * resolver (falling back when a profile predates those columns) — and if they
+ * disagree, opening and saving an untouched sender silently rewrites the identity
+ * the vendor will be given.
+ *
+ * The rule: split on the FIRST whitespace run. The first token is the given name;
+ * the entire remainder is the family name.
+ *
+ *   "Talia Rosen"        -> { first: "Talia", last: "Rosen" }
+ *   "Anna van der Berg"  -> { first: "Anna",  last: "van der Berg" }
+ *   "Support"            -> { first: "Support", last: "" }
+ *   ""                   -> { first: "", last: "" }
+ *
+ * A last-token split ("Anna van der" / "Berg") is wrong for every particle-carrying
+ * European surname, which is a large slice of the ICP. A single-token name yields
+ * an EMPTY last name on purpose — callers must refuse rather than invent one. The
+ * literal "Team" that the expansion dialog used to synthesize is exactly the
+ * failure mode this returns "" to prevent.
+ *
+ * Mirrored by BACKFILL 1 in tenant migration
+ * 0202_sender_profile_order_identity.sql; keep the two in step.
+ */
+export type PersonNameParts = {
+    first: string;
+    last: string;
+};
+export declare function splitPersonName(name: string | null | undefined): PersonNameParts;
+/**
+ * The inverse: the display name a first/last pair composes to. Used when the
+ * editor writes both halves so `name` stays consistent with them, and when a
+ * caller supplies only the halves.
+ */
+export declare function joinPersonName(first: string | null | undefined, last: string | null | undefined): string;

package/node_modules/@oxygen/shared/dist/person-name.js

@@ -0,0 +1,23 @@
+export function splitPersonName(name) {
+    const normalized = (name ?? "").replace(/\s+/g, " ").trim();
+    if (!normalized)
+        return { first: "", last: "" };
+    const separator = normalized.indexOf(" ");
+    if (separator < 0)
+        return { first: normalized, last: "" };
+    return {
+        first: normalized.slice(0, separator),
+        last: normalized.slice(separator + 1).trim(),
+    };
+}
+/**
+ * The inverse: the display name a first/last pair composes to. Used when the
+ * editor writes both halves so `name` stays consistent with them, and when a
+ * caller supplies only the halves.
+ */
+export function joinPersonName(first, last) {
+    return [first, last]
+        .map((part) => (part ?? "").replace(/\s+/g, " ").trim())
+        .filter(Boolean)
+        .join(" ");
+}

package/node_modules/@oxygen/shared/dist/plan-capabilities.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The free-versus-plan boundary, expressed exactly once (OXP-10.3.1).
+ *
+ * Every wall in the product that means "this needs a paid plan" resolves
+ * through this table. Nothing else may encode the boundary: a second list would
+ * drift, and this one is the customer-visible product surface of the whole
+ * free-tier goal — it is the moment a free user decides whether to pay.
+ *
+ * WHAT BELONGS HERE. Only capabilities the founder walled off on 2026-08-16:
+ * acting on the outside world through OXYGEN's own identity (connecting a
+ * sender, dispatching a sequence, connecting and delivering Publishing, buying
+ * managed email infrastructure) plus BYOK. Nothing else. In particular:
+ *
+ * - Per-call COST never belongs here. Enrichment, AI columns, waterfalls,
+ *   provider signals, Ads intel, Knowledge synthesis, inference, and managed
+ *   phone enrichment at 100 credits on hit are ALL available on free and simply
+ *   draw credits (founder, 2026-08-17). Credits are the meter and top-ups are
+ *   always purchasable; "expensive" is not a reason to add a row here.
+ * - Zero-marginal-cost capabilities never belong here. CRM, Tables, Workflows,
+ *   Knowledge, Recipes, Sequence authoring/preview/enrollment, Agents, Copilot,
+ *   Collaboration, Dashboards, Tags, Observability, seats, and API keys are
+ *   unmetered and permanent on free.
+ *
+ * The exhaustive per-capability verdicts, with the enforcing module for each,
+ * live in docs/free-tier-capability-matrix.md.
+ *
+ * WHY GATES ARE CHECKED BEFORE BALANCE. A connected sender is also a FIXED
+ * monthly credit commitment (1,000 per mailbox, 10,000 per LinkedIn account,
+ * 10,000 per WhatsApp number), and top-ups stay purchasable on free — so a free
+ * workspace could buy 10,000 credits for $12.50 and fund a LinkedIn seat that
+ * Starter prices at $99. Enforcing by balance would therefore price sending at
+ * an eighth of Starter. The capability gate must run BEFORE any balance or
+ * commitment check so the customer is told to upgrade, not to top up.
+ */
+import type { PlanTier } from "./billing.js";
+export declare const PLAN_GATED_CAPABILITIES: readonly ["sender_connect", "sequence_dispatch", "publishing_connect", "publishing_deliver", "managed_email_infrastructure", "byok_provider_keys"];
+export type PlanGatedCapability = (typeof PLAN_GATED_CAPABILITIES)[number];
+/**
+ * Every tier except `free` unblocks every gated capability.
+ *
+ * Deliberately not a per-capability tier list. The founder drew ONE line —
+ * free versus paid — and inventing per-capability tiers here would quietly
+ * create a second pricing axis nobody ratified. Provider tools that genuinely
+ * need a higher tier keep expressing that through their own
+ * `required_plan_tiers` in tool-access, which the resolver consults separately.
+ */
+export declare const PLAN_GATE_QUALIFYING_TIERS: readonly PlanTier[];
+export type PlanGatedCapabilityCopy = {
+    /** Customer language, not the identifier. Reads inside "… needs a paid plan". */
+    label: string;
+    /** What the free tier CAN still do here, so the refusal is not a dead end. */
+    freeAlternative: string;
+    /** Where the customer goes to inspect or change the affected resources. */
+    deepLinkPath: string;
+};
+export declare const PLAN_GATED_CAPABILITY_COPY: Record<PlanGatedCapability, PlanGatedCapabilityCopy>;
+export declare function isPlanGatedCapability(value: unknown): value is PlanGatedCapability;
+/**
+ * The whole boundary, in one expression.
+ *
+ * Note this asks about the TIER, not about entitlement. A churned workspace and
+ * a brand-new one both resolve to `free` and both get the same answer here —
+ * one entitlement, one capability set, differing only in grants and upgrade
+ * copy (founder, 2026-08-17).
+ */
+export declare function planTierAllowsCapability(tier: PlanTier, _capability: PlanGatedCapability): boolean;
+export declare const FREE_TIER_ENTITLEMENT_ENABLED_ENV_VAR = "OXYGEN_FREE_TIER_ENTITLEMENT_ENABLED";
+/**
+ * Fail-closed rollout switch for capability-scoped entitlement.
+ *
+ * UNSET MEANS OFF, and off means today's behaviour exactly: `free` is
+ * unentitled, the binary subscription gate refuses everything except read,
+ * export, and recovery, and these capability gates are moot because nothing
+ * reaches them.
+ *
+ * ONE flag governs both halves on purpose. Arming free-tier entitlement without
+ * the capability gates would hand every churned and never-subscribed workspace
+ * unrestricted sending, publishing, managed-infrastructure purchase, and BYOK.
+ * They must flip together or not at all, so they share a switch rather than
+ * being independently armable.
+ */
+export declare function freeTierEntitlementEnabled(env?: Record<string, string | undefined>): boolean;

package/node_modules/@oxygen/shared/dist/plan-capabilities.js

@@ -0,0 +1,130 @@
+/**
+ * The free-versus-plan boundary, expressed exactly once (OXP-10.3.1).
+ *
+ * Every wall in the product that means "this needs a paid plan" resolves
+ * through this table. Nothing else may encode the boundary: a second list would
+ * drift, and this one is the customer-visible product surface of the whole
+ * free-tier goal — it is the moment a free user decides whether to pay.
+ *
+ * WHAT BELONGS HERE. Only capabilities the founder walled off on 2026-08-16:
+ * acting on the outside world through OXYGEN's own identity (connecting a
+ * sender, dispatching a sequence, connecting and delivering Publishing, buying
+ * managed email infrastructure) plus BYOK. Nothing else. In particular:
+ *
+ * - Per-call COST never belongs here. Enrichment, AI columns, waterfalls,
+ *   provider signals, Ads intel, Knowledge synthesis, inference, and managed
+ *   phone enrichment at 100 credits on hit are ALL available on free and simply
+ *   draw credits (founder, 2026-08-17). Credits are the meter and top-ups are
+ *   always purchasable; "expensive" is not a reason to add a row here.
+ * - Zero-marginal-cost capabilities never belong here. CRM, Tables, Workflows,
+ *   Knowledge, Recipes, Sequence authoring/preview/enrollment, Agents, Copilot,
+ *   Collaboration, Dashboards, Tags, Observability, seats, and API keys are
+ *   unmetered and permanent on free.
+ *
+ * The exhaustive per-capability verdicts, with the enforcing module for each,
+ * live in docs/free-tier-capability-matrix.md.
+ *
+ * WHY GATES ARE CHECKED BEFORE BALANCE. A connected sender is also a FIXED
+ * monthly credit commitment (1,000 per mailbox, 10,000 per LinkedIn account,
+ * 10,000 per WhatsApp number), and top-ups stay purchasable on free — so a free
+ * workspace could buy 10,000 credits for $12.50 and fund a LinkedIn seat that
+ * Starter prices at $99. Enforcing by balance would therefore price sending at
+ * an eighth of Starter. The capability gate must run BEFORE any balance or
+ * commitment check so the customer is told to upgrade, not to top up.
+ */
+export const PLAN_GATED_CAPABILITIES = [
+    "sender_connect",
+    "sequence_dispatch",
+    "publishing_connect",
+    "publishing_deliver",
+    "managed_email_infrastructure",
+    "byok_provider_keys",
+];
+/**
+ * Every tier except `free` unblocks every gated capability.
+ *
+ * Deliberately not a per-capability tier list. The founder drew ONE line —
+ * free versus paid — and inventing per-capability tiers here would quietly
+ * create a second pricing axis nobody ratified. Provider tools that genuinely
+ * need a higher tier keep expressing that through their own
+ * `required_plan_tiers` in tool-access, which the resolver consults separately.
+ */
+export const PLAN_GATE_QUALIFYING_TIERS = [
+    "starter",
+    "pro",
+    "team",
+    "scale",
+    "enterprise",
+];
+export const PLAN_GATED_CAPABILITY_COPY = {
+    sender_connect: {
+        label: "Connecting a sending account",
+        freeAlternative: "You can build and preview the whole motion on Free — sequences, steps, and enrollment all work. Connecting a mailbox, LinkedIn account, or WhatsApp number is what needs a plan.",
+        deepLinkPath: "/settings/connections",
+    },
+    sequence_dispatch: {
+        label: "Sending a sequence",
+        freeAlternative: "Authoring, versioning, enrolling, and previewing a sequence are all free. Dispatching to real recipients is what needs a plan.",
+        deepLinkPath: "/sequencer/sequences",
+    },
+    publishing_connect: {
+        label: "Connecting a publishing account",
+        freeAlternative: "Drafting posts and reviewing analytics stay free. Connecting the account you publish from is what needs a plan.",
+        deepLinkPath: "/settings/connections",
+    },
+    publishing_deliver: {
+        label: "Publishing a post",
+        freeAlternative: "You can draft, review, and approve posts on Free. Delivering them to a live account is what needs a plan.",
+        deepLinkPath: "/publishing",
+    },
+    managed_email_infrastructure: {
+        label: "Buying managed email infrastructure",
+        freeAlternative: "Managed domains, inboxes, warmup, deliverability monitoring, and dedicated egress are purchases OXYGEN makes on your behalf, so they need a plan.",
+        deepLinkPath: "/settings/email-infrastructure",
+    },
+    byok_provider_keys: {
+        label: "Using your own provider keys",
+        freeAlternative: "Every provider in the catalog already works on Free using OXYGEN's managed keys and your credits — including enrichment, AI columns, and phone lookups. Bringing your own key is what needs a plan.",
+        deepLinkPath: "/settings/integrations",
+    },
+};
+export function isPlanGatedCapability(value) {
+    return (typeof value === "string"
+        && PLAN_GATED_CAPABILITIES.includes(value));
+}
+/**
+ * The whole boundary, in one expression.
+ *
+ * Note this asks about the TIER, not about entitlement. A churned workspace and
+ * a brand-new one both resolve to `free` and both get the same answer here —
+ * one entitlement, one capability set, differing only in grants and upgrade
+ * copy (founder, 2026-08-17).
+ */
+export function planTierAllowsCapability(tier, _capability) {
+    return tier !== "free";
+}
+export const FREE_TIER_ENTITLEMENT_ENABLED_ENV_VAR = "OXYGEN_FREE_TIER_ENTITLEMENT_ENABLED";
+/**
+ * Fail-closed rollout switch for capability-scoped entitlement.
+ *
+ * UNSET MEANS OFF, and off means today's behaviour exactly: `free` is
+ * unentitled, the binary subscription gate refuses everything except read,
+ * export, and recovery, and these capability gates are moot because nothing
+ * reaches them.
+ *
+ * ONE flag governs both halves on purpose. Arming free-tier entitlement without
+ * the capability gates would hand every churned and never-subscribed workspace
+ * unrestricted sending, publishing, managed-infrastructure purchase, and BYOK.
+ * They must flip together or not at all, so they share a switch rather than
+ * being independently armable.
+ */
+export function freeTierEntitlementEnabled(env = process.env) {
+    const raw = env[FREE_TIER_ENTITLEMENT_ENABLED_ENV_VAR];
+    if (!raw)
+        return false;
+    const normalized = raw.trim().toLowerCase();
+    return (normalized === "1"
+        || normalized === "true"
+        || normalized === "yes"
+        || normalized === "on");
+}

package/node_modules/@oxygen/shared/dist/plan-limits.d.ts

@@ -170,8 +170,8 @@ export declare const PLAN_LIMITS: {
             readonly maxDirectCsvBodyBytes: 10000000;
         };
         readonly agents: {
-            readonly maxTotalCredits: 10000;
-            readonly maxInferenceCredits: 5000;
+            readonly maxTotalCredits: 2500;
+            readonly maxInferenceCredits: 1500;
             readonly maxUpstreamCostUsd: 10;
             readonly maxUpstreamCostUsdByok: 10;
         };

package/node_modules/@oxygen/shared/dist/plan-limits.js

@@ -48,12 +48,28 @@ export const PLAN_LIMITS = {
             maxFileBytes: 100 * MIB,
             maxDirectCsvBodyBytes: 10_000_000,
         },
+        // Sized against the free tier's actual funding (OXP-10.2.4, 2026-08-17):
+        // 5,000 credits at signup plus 5,000 on CLI/MCP activation, one time each,
+        // with no monthly allowance to refill them. The previous ceilings were
+        // written when `free` meant a churned org that could spend nothing, so they
+        // were harmless at any value; now a single Agent run capped at 10,000 could
+        // consume the ENTIRE lifetime grant, and one capped at 5,000 could consume
+        // the whole signup grant before the customer saw anything work.
+        //
+        // These are runaway guards, not the billing meter — a workspace that tops up
+        // is bounded by its balance, not by these. The intent is only that no single
+        // run can silently eat a first impression.
         agents: {
-            maxTotalCredits: 10_000,
-            maxInferenceCredits: 5_000,
+            maxTotalCredits: 2_500,
+            maxInferenceCredits: 1_500,
             maxUpstreamCostUsd: 10,
             maxUpstreamCostUsdByok: 10,
         },
+        // Left at 5,000/1,500 deliberately. The signup grant is exactly one default
+        // Copilot session, and that is the point: a founder who picks the in-product
+        // path over the CLI must be able to complete one real session on the base
+        // grant alone. Lowering this would re-create the dead-on-arrival Copilot the
+        // split grant exists to prevent.
         copilot: { maxSessionBudgetCredits: 5_000, defaultPerTurnCreditCeiling: 1_500 },
         signals: { maxEvents: 100, maxWindowDays: 30 },
         tableActions: { maxActionsPerRun: 10 },