@oxygen-agent/cli 1.1011.405 → 1.1011.446

package/node_modules/@oxygen/shared/dist/contracts/linkedin-invites-list.js

@@ -0,0 +1,8 @@
+/** Exact selectors for one native/provider sent-invitation page. */
+import { int, obj, str } from "./schema.js";
+export const LINKEDIN_SENT_INVITES_MAX_LIMIT = 200;
+export const LINKEDIN_SENT_INVITES_QUERY_CONTRACT = obj({
+    account: str({ description: "Sender id, connection id, or Unipile account id." }),
+    limit: int({ minimum: 1, description: "Maximum invitations to return." }),
+    cursor: str({ description: "Pagination cursor from a previous response." }),
+});

package/node_modules/@oxygen/shared/dist/contracts/operations.d.ts

@@ -1,13 +1,41 @@
-import type { ContractObject } from "./schema.js";
+import { type ContractObject } from "./schema.js";
 export type OperationSpec<C extends ContractObject = ContractObject> = {
     /** Stable id, `<resource>.<verb>`. */
     id: string;
     /** Route template; `{name}` segments are path parameters. */
     route: string;
-    method: "POST" | "PATCH";
+    method: "GET" | "POST" | "PATCH" | "DELETE";
     /** When set, the contract describes `body[bodyKey]` rather than the whole body. */
     bodyKey?: string;
     contract: C;
+    /** Named route parameters, exposed as exact flags/properties by generated surfaces. */
+    parameters?: readonly string[];
+    /** Fields sent in the query rather than the JSON body (all fields for GET). */
+    queryFields?: readonly string[];
+    /** Array fields encoded as repeated query keys rather than a JSON string. */
+    repeatedQueryFields?: readonly string[];
+    /** Fixed discriminator fields owned by this operation, never supplied by a caller. */
+    defaults?: Readonly<Record<string, unknown>>;
+    /** A side already has a manual, domain-native implementation. */
+    generated?: {
+        cli: boolean;
+        mcp: boolean;
+    };
+    /** Multipart transport for an operation whose API takes one uploaded file. */
+    multipart?: {
+        contentField: string;
+        nameField: string;
+        typeField: string;
+        fileField: string;
+    };
+    /** Download bytes through the same authenticated route; never follow redirects. */
+    binary?: {
+        maxBytes: number;
+        stream?: never;
+    } | {
+        stream: true;
+        resourceParameter: string;
+    };
     cli: {
         /** Command words after `oxygen`, e.g. `["senders", "limits", "set"]`. */
         path: readonly string[];
@@ -24,10 +52,28 @@ export type OperationSpec<C extends ContractObject = ContractObject> = {
         description: string;
         /** The MCP toolset domain (pack) the tool registers under. */
         pack: string;
+        /** Source-reviewed effect hints; never an authorization bypass. */
+        annotations?: {
+            destructiveHint?: boolean;
+            openWorldHint?: boolean;
+            idempotentHint?: boolean;
+        };
     };
     mutates: boolean;
     spends: boolean;
 };
 /** The route with its `{param}` segments filled in, each URL-encoded. */
 export declare function operationPath(spec: Pick<OperationSpec, "route">, params: Readonly<Record<string, string>>): string;
+/** The exact public grammar, including the operation's scoped route parameters. */
+export declare function operationInputContract(spec: OperationSpec): ContractObject;
+/** Preserve absent, false, null and empty values while assigning each field to its transport. */
+export declare function operationRequest(spec: OperationSpec, args: Record<string, unknown>): {
+    path: string;
+    method: OperationSpec["method"];
+    body?: Record<string, unknown>;
+};
+/** Decode the explicit file property and keep the native multipart API contract. */
+export declare function operationFormData(spec: OperationSpec, body: Record<string, unknown>): FormData;
 export declare const OPERATION_SPECS: readonly OperationSpec[];
+export declare const CLI_OPERATIONS: OperationSpec[];
+export declare const MCP_OPERATIONS: OperationSpec[];

package/node_modules/@oxygen/shared/dist/contracts/operations.js

@@ -5,8 +5,11 @@
  * cannot disagree on which fields exist. Leaf and browser-safe.
  */
 import { CONNECTOR_EVENTS_REVOKE_OPERATION, CONNECTOR_UPDATE_OPERATION } from "./connectors.js";
+import { str } from "./schema.js";
 import { SENDER_LIMITS_SET_OPERATION } from "./sender-limits.js";
-import { WORKSPACE_PAGES_UPDATE_OPERATION } from "./workspace-pages.js";
+import { WORKSPACE_PAGES_GET_OPERATION, WORKSPACE_PAGES_UPDATE_OPERATION } from "./workspace-pages.js";
+import { BROWSER_OPERATIONS } from "./browser-operations.js";
+import { CUSTOMER_OPERATIONS } from "./customer-operations.js";
 /** The route with its `{param}` segments filled in, each URL-encoded. */
 export function operationPath(spec, params) {
     return spec.route.replace(/\{(\w+)\}/g, (_match, name) => {
@@ -16,9 +19,66 @@ export function operationPath(spec, params) {
         return encodeURIComponent(value);
     });
 }
-export const OPERATION_SPECS = [
-    SENDER_LIMITS_SET_OPERATION,
-    CONNECTOR_UPDATE_OPERATION,
-    CONNECTOR_EVENTS_REVOKE_OPERATION,
-    WORKSPACE_PAGES_UPDATE_OPERATION,
-];
+/** The exact public grammar, including the operation's scoped route parameters. */
+export function operationInputContract(spec) {
+    const parameters = spec.parameters ?? [];
+    for (const name of parameters) {
+        if (Object.hasOwn(spec.contract.properties, name))
+            throw new Error(`Operation ${spec.id} uses ${name} for both a route parameter and a body field.`);
+    }
+    return {
+        ...spec.contract,
+        properties: {
+            ...Object.fromEntries(parameters.map((name) => [name, str({ minLength: 1 })])),
+            ...spec.contract.properties,
+        },
+        required: [...parameters, ...(spec.contract.required ?? [])],
+    };
+}
+/** Preserve absent, false, null and empty values while assigning each field to its transport. */
+export function operationRequest(spec, args) {
+    const params = Object.fromEntries((spec.parameters ?? []).map((name) => [name, String(args[name] ?? "")]));
+    let path = operationPath(spec, params);
+    const body = { ...spec.defaults };
+    const query = new URLSearchParams();
+    for (const name of Object.keys(spec.contract.properties)) {
+        const value = args[name];
+        if (value === undefined)
+            continue;
+        if (spec.method === "GET" || spec.queryFields?.includes(name)) {
+            if (spec.repeatedQueryFields?.includes(name) && Array.isArray(value)) {
+                for (const entry of value)
+                    query.append(name, String(entry));
+            }
+            else if (value !== null)
+                query.set(name, typeof value === "object" ? JSON.stringify(value) : String(value));
+        }
+        else
+            body[name] = value;
+    }
+    if (query.size)
+        path += `?${query}`;
+    return { path, method: spec.method, ...(spec.method !== "GET" && Object.keys(body).length > 0 ? { body: spec.bodyKey ? { [spec.bodyKey]: body } : body } : {}) };
+}
+/** Decode the explicit file property and keep the native multipart API contract. */
+export function operationFormData(spec, body) {
+    const fields = spec.multipart;
+    if (!fields)
+        throw new Error("This operation does not accept a file.");
+    const encoded = body[fields.contentField];
+    if (typeof encoded !== "string" || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded) || !encoded) {
+        throw new Error(`${fields.contentField} must contain valid non-empty base64 file bytes.`);
+    }
+    const bytes = Uint8Array.from(atob(encoded), (character) => character.charCodeAt(0));
+    const form = new FormData();
+    form.set(fields.fileField, new Blob([bytes], { type: String(body[fields.typeField] ?? "application/octet-stream") }), String(body[fields.nameField] ?? "upload"));
+    for (const [key, value] of Object.entries(body)) {
+        if ([fields.contentField, fields.nameField, fields.typeField].includes(key) || value === undefined)
+            continue;
+        form.set(key, typeof value === "object" ? JSON.stringify(value) : String(value));
+    }
+    return form;
+}
+export const OPERATION_SPECS = [SENDER_LIMITS_SET_OPERATION, CONNECTOR_UPDATE_OPERATION, CONNECTOR_EVENTS_REVOKE_OPERATION, WORKSPACE_PAGES_GET_OPERATION, WORKSPACE_PAGES_UPDATE_OPERATION, ...CUSTOMER_OPERATIONS, ...BROWSER_OPERATIONS];
+export const CLI_OPERATIONS = [...CUSTOMER_OPERATIONS, ...BROWSER_OPERATIONS].filter((spec) => spec.generated?.cli !== false);
+export const MCP_OPERATIONS = [...CUSTOMER_OPERATIONS, ...BROWSER_OPERATIONS].filter((spec) => spec.generated?.mcp !== false);

package/node_modules/@oxygen/shared/dist/contracts/table-grid-query.d.ts

@@ -0,0 +1,4 @@
+export declare const TABLE_GRID_QUERY_OPTIONS_CONTRACT: import("./schema.js").ContractObject<{
+    readonly include_stats: import("./schema.js").BooleanProperty;
+    readonly include_fill: import("./schema.js").BooleanProperty;
+}, never>;

package/node_modules/@oxygen/shared/dist/contracts/table-grid-query.js

@@ -0,0 +1,6 @@
+/** Optional first-page metadata on the shared Table grid query. */
+import { bool, obj } from "./schema.js";
+export const TABLE_GRID_QUERY_OPTIONS_CONTRACT = obj({
+    include_stats: bool({ description: "With --format grid, include column fill statistics and their table row count when available; 0 credits." }),
+    include_fill: bool({ description: "With --format grid, include fill progress on an empty first page when available; ignored on cursor pages. 0 credits." }),
+});

package/node_modules/@oxygen/shared/dist/contracts/table-query-grid.d.ts

@@ -0,0 +1,21 @@
+/** Optional representation of Query; canonical raw rows remain the default. */
+export declare const TABLE_QUERY_GRID_CONTRACT: import("./schema.js").ContractObject<{
+    readonly format: {
+        type: "string";
+        enum: readonly "grid"[];
+        description?: string;
+    };
+    readonly include_stats: import("./schema.js").BooleanProperty;
+    readonly include_fill: import("./schema.js").BooleanProperty;
+    readonly max_chars: {
+        type: "integer";
+        description?: string;
+        minimum?: number;
+        maximum?: number;
+        "x-clamp"?: true;
+    };
+}, never>;
+export declare const TABLE_QUERY_GRID_NATIVE_WINDOW = 10000;
+export declare const TABLE_QUERY_GRID_BUILTIN_WINDOW = 4000;
+/** Measure the complete native receipt and the escaped built-in host receipt. */
+export declare function tableQueryGridResultFits(data: Record<string, unknown>, maxChars: number | undefined, surface: string | null): boolean;

package/node_modules/@oxygen/shared/dist/contracts/table-query-grid.js

@@ -0,0 +1,27 @@
+import { success } from "../cli-result.js";
+import { OXYGEN_VERSION } from "../version.js";
+import { bool, enumOf, int, obj } from "./schema.js";
+/** Optional representation of Query; canonical raw rows remain the default. */
+export const TABLE_QUERY_GRID_CONTRACT = obj({
+    format: enumOf(["grid"], { description: "Grid cell previews." }),
+    include_stats: bool({ description: "Optional column stats." }),
+    include_fill: bool({ description: "Empty first-page fill state." }),
+    max_chars: int({ minimum: 1_000, maximum: 100_000, description: "Complete grid envelope chars." }),
+});
+export const TABLE_QUERY_GRID_NATIVE_WINDOW = 10_000;
+// Deliberately below Strands' shipped 6000 default; counts the complete host
+// object rather than only its text. This changes no adapter's outer ceiling.
+export const TABLE_QUERY_GRID_BUILTIN_WINDOW = 4_000;
+/** Measure the complete native receipt and the escaped built-in host receipt. */
+export function tableQueryGridResultFits(data, maxChars, surface) {
+    if (maxChars === undefined)
+        return true;
+    if (JSON.stringify(success("tables query", data)).length > maxChars)
+        return false;
+    if (surface === "agent" || surface === "copilot") {
+        return JSON.stringify({
+            ok: true, text: JSON.stringify(data), structured: { ...data, oxygen_version: OXYGEN_VERSION },
+        }).length <= TABLE_QUERY_GRID_BUILTIN_WINDOW;
+    }
+    return true;
+}

package/node_modules/@oxygen/shared/dist/contracts/tool-catalog-detail.d.ts

@@ -0,0 +1,19 @@
+import { type Infer } from "./schema.js";
+/** Explicit metadata projections; omitted native HTTP/CLI options retain full detail. */
+export declare const toolCatalogDetailQueryContract: import("./schema.js").ContractObject<{
+    readonly view: {
+        type: "string";
+        enum: readonly ("access" | "examples" | "field_names" | "full" | "guidance" | "input_schema" | "native_fields" | "output_schema" | "pricing" | "summary")[];
+        description?: string;
+    };
+    readonly field_keys: import("./schema.js").ArrayProperty<import("./schema.js").StringProperty>;
+    readonly field_query: import("./schema.js").StringProperty;
+    readonly max_chars: {
+        type: "integer";
+        description?: string;
+        minimum?: number;
+        maximum?: number;
+        "x-clamp"?: true;
+    };
+}, never>;
+export type ToolCatalogDetailQuery = Infer<typeof toolCatalogDetailQueryContract>;

package/node_modules/@oxygen/shared/dist/contracts/tool-catalog-detail.js

@@ -0,0 +1,10 @@
+import { arr, enumOf, int, obj, str } from "./schema.js";
+/** Explicit metadata projections; omitted native HTTP/CLI options retain full detail. */
+export const toolCatalogDetailQueryContract = obj({
+    view: enumOf(["summary", "pricing", "access", "guidance", "field_names", "native_fields", "examples", "input_schema", "output_schema", "full"], {
+        description: "Summary defaults on MCP; full defaults on HTTP/CLI. Schema views stay exact.",
+    }),
+    field_keys: arr(str({ minLength: 1, maxLength: 200 }), { minItems: 1, maxItems: 20, description: "Exact native field keys; field_names/native_fields only." }),
+    field_query: str({ minLength: 1, maxLength: 200, description: "Substring of native field keys; not with field_keys." }),
+    max_chars: int({ minimum: 2_000, maximum: 40_000, description: "Native receipt window; the calling surface may enforce a lower cap." }),
+});

package/node_modules/@oxygen/shared/dist/contracts/tool-catalog-search-window.d.ts

@@ -0,0 +1,12 @@
+/** Existing native filters plus an optional window; omission retains full HTTP/CLI defaults. */
+export declare const toolCatalogSearchWindowContract: import("./schema.js").ContractObject<{
+    readonly max_chars: {
+        type: "integer";
+        description?: string;
+        minimum?: number;
+        maximum?: number;
+        "x-clamp"?: true;
+    };
+    readonly include_native: import("./schema.js").BooleanProperty;
+    readonly workflow_eligible: import("./schema.js").BooleanProperty;
+}, never>;

package/node_modules/@oxygen/shared/dist/contracts/tool-catalog-search-window.js

@@ -0,0 +1,7 @@
+import { bool, int, obj } from "./schema.js";
+/** Existing native filters plus an optional window; omission retains full HTTP/CLI defaults. */
+export const toolCatalogSearchWindowContract = obj({
+    max_chars: int({ minimum: 2_000, maximum: 40_000, description: "Native window; surface cap applies." }),
+    include_native: bool({ description: "Include native column metadata (default true)." }),
+    workflow_eligible: bool({ description: "Only hosted-workflow tools; includes canonical workflow_effect." }),
+});

package/node_modules/@oxygen/shared/dist/contracts/workspace-pages.d.ts

@@ -13,4 +13,5 @@ export declare const WORKSPACE_PAGES_UPDATE_CONTRACT: import("./schema.js").Cont
     readonly show_all: import("./schema.js").BooleanProperty;
 }, never>;
 export type WorkspacePagesUpdate = Infer<typeof WORKSPACE_PAGES_UPDATE_CONTRACT>;
+export declare const WORKSPACE_PAGES_GET_OPERATION: OperationSpec;
 export declare const WORKSPACE_PAGES_UPDATE_OPERATION: OperationSpec<typeof WORKSPACE_PAGES_UPDATE_CONTRACT>;

package/node_modules/@oxygen/shared/dist/contracts/workspace-pages.js

@@ -17,11 +17,23 @@ export const WORKSPACE_PAGES_UPDATE_CONTRACT = obj({
 });
 const inferMatchesRoute = true;
 void inferMatchesRoute;
+export const WORKSPACE_PAGES_GET_OPERATION = {
+    id: "workspace_pages.get",
+    route: "/api/cli/settings/pages",
+    method: "GET",
+    contract: obj({}),
+    generated: { cli: false, mcp: false },
+    cli: { path: ["settings", "pages", "list"], summary: "Page visibility in the web app's sidebar navigation menu (Settings → Customise): hidden_pages, whether you may customize it (can_change: admins and owners), then every page (path, name, section, parent) with hidden (hidden itself) and visible (shown in the sidebar; false under a hidden section). Read-only, 0 credits." },
+    mcp: { name: "oxygen_settings_pages_get", title: "Oxygen: List Sidebar Pages", description: "Lists the OXYGEN web app's sidebar navigation pages (Settings → Customise) with whether this workspace hides each one for everyone, and can_change (admins and owners). Free. Change with oxygen_settings_pages_update.", pack: "workspace" },
+    mutates: false,
+    spends: false,
+};
 export const WORKSPACE_PAGES_UPDATE_OPERATION = {
     id: "workspace_pages.update",
     route: "/api/cli/settings/pages",
     method: "POST",
     contract: WORKSPACE_PAGES_UPDATE_CONTRACT,
+    generated: { cli: false, mcp: false },
     cli: {
         path: ["settings", "pages", "set"],
         summary: "Hide or show pages in the web app's sidebar navigation menu for everyone in this workspace (Settings → Customise): --hide Unibox,Publishing, --show Unibox, --show-all. Name pages by path or name from `settings pages list`; hiding a section hides its sub-pages. Nothing is deleted and hidden pages stay reachable by URL. Admins and owners only; free.",

package/node_modules/@oxygen/shared/dist/email-campaign-ramp.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The standard ramp, by completed sending days: 5 a day through 2, 10 through 5,
+ * 20 through 8, then the configured cap. `maxAgeDays` keeps its historical name;
+ * its input is completed sending days, not mailbox age.
+ */
+export declare const WARMUP_RAMP_DAILY_CAPS: readonly [{
+    readonly maxAgeDays: 2;
+    readonly cap: 5;
+}, {
+    readonly maxAgeDays: 5;
+    readonly cap: 10;
+}, {
+    readonly maxAgeDays: 8;
+    readonly cap: 20;
+}];
+/**
+ * A custom ramp. `cap`, when present, is a permanent ceiling for this inbox (it
+ * never climbs past it, even when the daily cap is higher); absent, the ramp
+ * climbs until it reaches the inbox's configured daily cap.
+ */
+export type MailboxCustomRampConfig = {
+    start_per_day: number;
+    increase_every_days: number;
+    step: number;
+    cap?: number;
+};
+/** The ramp switched off: the configured daily cap applies from the first sending day. */
+export type MailboxRampOffConfig = {
+    enabled: false;
+};
+export type MailboxRampConfig = MailboxCustomRampConfig | MailboxRampOffConfig;
+export declare const MAILBOX_RAMP_MODES: readonly ["standard", "custom", "off"];
+export type MailboxRampMode = (typeof MAILBOX_RAMP_MODES)[number];
+export declare function isMailboxRampOff(config: MailboxRampConfig | null | undefined): config is MailboxRampOffConfig;
+export declare function mailboxRampMode(config: MailboxRampConfig | null | undefined): MailboxRampMode;
+/** The custom knobs, or null for the standard ramp and for a ramp switched off. */
+export declare function customMailboxRamp(config: MailboxRampConfig | null | undefined): MailboxCustomRampConfig | null;
+export type MailboxRampConfigParse = {
+    ok: true;
+    config: MailboxRampConfig | null;
+} | {
+    ok: false;
+    field: string | null;
+    message: string;
+};
+/**
+ * The one validator for a ramp_config write, shared by the API route (400) and
+ * the tenant write (OxygenError). null/undefined selects the standard ramp.
+ * `{enabled: false}` turns the ramp off and takes no other field. Otherwise
+ * start_per_day, increase_every_days (>= 1) and step are required non-negative
+ * integers, and cap is an optional non-negative integer.
+ */
+export declare function parseMailboxRampConfig(value: unknown): MailboxRampConfigParse;
+/**
+ * Encode a validated public config for rolling web/worker deployments. The
+ * snapshot is the configured cap in force, taken under the mailbox's row lock.
+ * New readers discard it; it is never a permanent custom ceiling. Cap edits
+ * must refresh it, including Off's fixed start, so old warm-up targets cannot
+ * retain a higher value after the mailbox's daily cap is lowered.
+ */
+export declare function serializeMailboxRampConfig(config: MailboxRampConfig | null, configuredDailyCap: number): Record<string, unknown> | null;
+/** Non-throwing read of stored ramp_config; private compatibility fields never reach public readbacks. */
+export declare function readMailboxRampConfig(value: unknown): MailboxRampConfig | null;
+/** Refresh only a synthetic compatibility ceiling; explicit caps and malformed legacy rows stay intact. */
+export declare function refreshMailboxRampConfigDailyCap(value: unknown, configuredDailyCap: number): unknown;
+/** The standard ramp's ceiling after `sendingDays` completed sending days; null once past its tiers. */
+export declare function warmupRampDailyCap(sendingDays: number): number | null;
+/**
+ * A custom ramp's ceiling after `sendingDays` completed sending days: start_per_day
+ * plus one `step` per completed `increase_every_days` window, held to `cap` when
+ * one is set. A (defensively) zero interval never climbs instead of dividing by zero.
+ */
+export declare function rampConfigDailyCap(config: MailboxCustomRampConfig, sendingDays: number): number;
+/** The campaign ramp's ceiling in any mode; null when the ramp does not hold the inbox back. */
+export declare function campaignRampDailyCap(config: MailboxRampConfig | null | undefined, sendingDays: number): number | null;
+/** One level of the schedule: from this 1-based sending day the inbox may send `perDay`. */
+export type CampaignRampStep = {
+    fromSendingDay: number;
+    perDay: number;
+};
+export type CampaignRampSchedule = {
+    mode: MailboxRampMode;
+    /** Every level the inbox passes through, ending at the most it will ever send a day. */
+    steps: CampaignRampStep[];
+    /** The 1-based sending day on which the inbox first sends its full daily cap; null if it never does. */
+    fullCapOnSendingDay: number | null;
+    /** True when `steps` stopped early at `maxSteps`. */
+    truncated: boolean;
+};
+/**
+ * The 1-based sending day on which the ramp first lets the inbox send its full
+ * daily cap: 1 when the ramp is off or already at the cap, null when it never
+ * gets there (a custom cap below the daily cap, or no increase).
+ */
+export declare function campaignRampFullCapSendingDay(config: MailboxRampConfig | null | undefined, dailyCap: number): number | null;
+/**
+ * The day-by-day plan a ramp produces against a daily cap, as distinct levels.
+ * Standard against 25: 5 (day 1), 10 (day 4), 20 (day 7), 25 (day 10). A custom
+ * ramp whose own cap sits below the daily cap ends at that cap and never reports
+ * a full-cap day. `maxSteps` bounds a very gentle custom ramp (1 a day, +1 a day).
+ */
+export declare function campaignRampSchedule(config: MailboxRampConfig | null | undefined, dailyCap: number, options?: {
+    maxSteps?: number;
+}): CampaignRampSchedule;