@oxygen-agent/cli 1.936.1 → 1.948.1

package/dist/ugc-commands.js

@@ -28,20 +28,36 @@ export function registerUgcCommands(program, handle) {
     const ugc = program
         .command("ugc")
         .description("Manage UGC programs and independent creator participations: briefs, voice, posts, approvals, sponsorship and bounded amplification. Requires UGC availability.");
+    const groupDescriptions = {
+        programs: "Programs you operate or joined. Lifecycle: create, update, duplicate (settings + briefs), archive (stops future work, keeps shared history, reversible with restore) and delete (permanent; only while no creator has ever joined).",
+        creators: "Creator participations: invite, revoke an invite, accept in the creator workspace, connect a sender, change approval authority, or revoke.",
+        briefs: "Program briefs with ordered questions for creators.",
+        posts: "Enrolled program posts: enroll existing posts, draft from briefs, edit, schedule, and record creator or brand approval.",
+        analytics: "Stored daily program and creator performance.",
+        knowledge: "Master Knowledge pages shared live with a program.",
+        voice: "Creator voice profiles and imports.",
+        sponsorship: "Seat and credit sponsorship per participation.",
+        amplification: "Bounded, approval-gated amplification of enrolled posts.",
+        calendar: "Bounded enrolled-post calendar reads.",
+    };
     const groups = new Map();
     const group = (name) => {
         let command = groups.get(name);
         if (!command) {
             command = ugc.command(name);
+            const description = groupDescriptions[name];
+            if (description)
+                command.description(description);
             groups.set(name, command);
         }
         return command;
     };
     group("programs")
         .command("list")
-        .description("Read UGC programs in the active workspace. Read-only.")
+        .description("Read UGC programs in the active workspace, archived ones included unless --status filters. Read-only.")
         .option("--program-id <id>", "Program ID.")
         .option("--participation-id <id>", "Creator participation ID.")
+        .option("--status <active|archived>", "Only programs in this status.")
         .option("--json", "Print a JSON envelope.")
         .action((options) => handle("ugc programs list", options, () => {
         const query = new URLSearchParams({ view: "programs" });
@@ -49,6 +65,8 @@ export function registerUgcCommands(program, handle) {
             query.set("program_id", String(options.programId));
         if (options.participationId)
             query.set("participation_id", String(options.participationId));
+        if (options.status)
+            query.set("status", String(options.status));
         return requestOxygen(`/api/cli/ugc?${query}`);
     }));
     group("programs")
@@ -67,7 +85,7 @@ export function registerUgcCommands(program, handle) {
     }));
     group("creators")
         .command("list")
-        .description("Read UGC participations in the active workspace. Read-only.")
+        .description("Read creators and invitations, including persisted email delivery status. Read-only.")
         .option("--program-id <id>", "Program ID.")
         .option("--participation-id <id>", "Creator participation ID.")
         .option("--json", "Print a JSON envelope.")
@@ -119,6 +137,8 @@ export function registerUgcCommands(program, handle) {
         .description("Read UGC analytics in the active workspace. Read-only.")
         .requiredOption("--program-id <id>", "Program ID.")
         .option("--participation-id <id>", "Creator participation ID.")
+        .option("--post-cursor <cursor>", "Next post_performance page from next_post_cursor; totals still cover all enrolled posts.")
+        .option("--limit <count>", "Post performance rows per page, up to 100.")
         .option("--json", "Print a JSON envelope.")
         .action((options) => handle("ugc analytics get", options, () => {
         const query = new URLSearchParams({ view: "analytics" });
@@ -126,6 +146,10 @@ export function registerUgcCommands(program, handle) {
             query.set("program_id", String(options.programId));
         if (options.participationId)
             query.set("participation_id", String(options.participationId));
+        if (options.postCursor)
+            query.set("post_cursor", String(options.postCursor));
+        if (options.limit)
+            query.set("limit", String(options.limit));
         return requestOxygen(`/api/cli/ugc?${query}`);
     }));
     group("knowledge")
@@ -156,9 +180,23 @@ export function registerUgcCommands(program, handle) {
             query.set("participation_id", String(options.participationId));
         return requestOxygen(`/api/cli/ugc?${query}`);
     }));
+    group("posts")
+        .command("draft-status")
+        .description("Read the original paid draft request and saved result without generating again. Creator workspace only, 0 credits.")
+        .requiredOption("--participation-id <id>", "Creator participation ID.")
+        .requiredOption("--request-id <id>", "Original draft request ID.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc posts draft-status", options, () => {
+        const query = new URLSearchParams({
+            view: "draft_run",
+            participation_id: String(options.participationId),
+            request_id: String(options.requestId),
+        });
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
     group("sponsorship")
         .command("get")
-        .description("Read UGC sponsorship in the active workspace. Read-only.")
+        .description("Read sponsorship in the active workspace. Creators see their remaining credits and exact organizer access; masters see program payment status. Read-only.")
         .requiredOption("--program-id <id>", "Program ID.")
         .option("--participation-id <id>", "Creator participation ID.")
         .option("--json", "Print a JSON envelope.")
@@ -170,6 +208,66 @@ export function registerUgcCommands(program, handle) {
             query.set("participation_id", String(options.participationId));
         return requestOxygen(`/api/cli/ugc?${query}`);
     }));
+    for (const spec of [
+        {
+            group: "calendar",
+            command: "list",
+            view: "calendar",
+            description: "Read the program's enrolled post calendar in a bounded UTC date range (up to 42 days). Stored data only, 0 credits.",
+            fields: [
+                ["date_from", "Start ISO instant, inclusive.", true],
+                ["date_to", "End ISO instant, exclusive.", true],
+                [
+                    "calendar_cursor",
+                    "Calendar next_cursor from the previous page.",
+                    false,
+                ],
+                ["participation_id", "Filter to one creator participation.", false],
+            ],
+        },
+        {
+            group: "posts",
+            command: "history",
+            view: "post_history",
+            description: "Read retained public comments, metrics, and publication receipts for one enrolled post. Stored data only, 0 credits.",
+            fields: [
+                ["post_id", "Enrolled source post UUID.", true],
+                ["cursor", "next_comments_cursor from the previous page.", false],
+                ["metric_cursor", "next_metrics_cursor from the previous page.", false],
+                ["action_cursor", "next_actions_cursor from the previous page.", false],
+            ],
+        },
+        {
+            group: "amplification",
+            command: "get",
+            view: "amplification",
+            description: "Read this program's current amplification authority and immutable action history. Master workspace only; 0 credits, no provider call.",
+            fields: [["cursor", "next_cursor from the previous action page.", false]],
+        },
+    ]) {
+        const command = group(spec.group)
+            .command(spec.command)
+            .description(spec.description)
+            .requiredOption("--program-id <id>", "Program ID.")
+            .option("--limit <count>", "Rows per page, up to 100.")
+            .option("--json", "Print a JSON envelope.");
+        for (const [name, description, required] of spec.fields)
+            command[required ? "requiredOption" : "option"](`--${name.replaceAll("_", "-")} <value>`, description);
+        command.action((options) => handle(`ugc ${spec.group} ${spec.command}`, options, () => {
+            const query = new URLSearchParams({
+                view: spec.view,
+                program_id: String(options.programId),
+            });
+            for (const [name] of spec.fields) {
+                const key = name.replace(/_([a-z])/g, (_match, letter) => letter.toUpperCase());
+                if (options[key] !== undefined)
+                    query.set(name, String(options[key]));
+            }
+            if (options.limit)
+                query.set("limit", String(options.limit));
+            return requestOxygen(`/api/cli/ugc?${query}`);
+        }));
+    }
     const writes = [
         {
             action: "program_create",
@@ -252,7 +350,79 @@ export function registerUgcCommands(program, handle) {
                 {
                     name: "status",
                     kind: "string",
-                    description: "Program status, or revoked for a participation.",
+                    description: "active or archived; prefer `programs archive` / `programs restore`.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "program_update",
+            command: "programs archive",
+            description: "Archive a program: stop future access, publishing, tracking and amplification, revoke pending invitations and request cancellation of sponsorship renewals. Shared history is retained; `programs restore` re-activates it.",
+            fixed: { status: "archived" },
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "program_update",
+            command: "programs restore",
+            description: "Restore an archived program. Creators removed earlier stay removed, revoked invitations stay revoked, and cancelled sponsorships need a new preview and confirmation.",
+            fixed: { status: "active" },
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "program_duplicate",
+            command: "programs duplicate",
+            description: "Copy a program's settings, shared knowledge and brand review into a new active program, with its briefs by default. Free: 0 credits. Never copies creators, invitations, posts or sponsorship.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Source program ID.",
+                    required: true,
+                },
+                {
+                    name: "name",
+                    kind: "string",
+                    description: 'Name of the copy; defaults to "<name> (copy)".',
+                    required: false,
+                },
+                {
+                    name: "include_briefs",
+                    kind: "boolean",
+                    description: "Copy the program's briefs (default true).",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "program_delete",
+            command: "programs delete",
+            description: "Permanently delete a program with its briefs and pending invitations. A bare call previews the counts and whether it is deletable; pass --approved to delete. Allowed only while no creator has ever joined; otherwise use `programs archive`.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Confirm the previewed permanent deletion.",
                     required: false,
                 },
             ],
@@ -260,7 +430,7 @@ export function registerUgcCommands(program, handle) {
         {
             action: "invite_create",
             command: "creators invite",
-            description: "Create a shareable invite for an independent creator. No email is sent.",
+            description: "Preview an invitation email (0 credits); send with --approved --preview-token from that preview. Use --link-only to create a link without email.",
             fields: [
                 {
                     name: "program_id",
@@ -271,9 +441,52 @@ export function registerUgcCommands(program, handle) {
                 {
                     name: "email",
                     kind: "string",
-                    description: "Invitee email. Returns a shareable invitation; does not send email.",
+                    description: "Exact creator email to receive the invitation.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Authorize sending the exact previewed invitation email.",
+                    required: false,
+                },
+                {
+                    name: "preview_token",
+                    kind: "string",
+                    description: "Exact token from the invitation email preview.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "invite_send",
+            command: "creators send-invite",
+            description: "Preview email for an existing pending invitation; send or resend with --approved --preview-token. Replaces the old link, keeps its expiry. Sent means provider accepted, not inbox delivery.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "invitation_id",
+                    kind: "string",
+                    description: "Exact pending invitation ID from creators list.",
                     required: true,
                 },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Authorize the exact previewed email send or resend.",
+                    required: false,
+                },
+                {
+                    name: "preview_token",
+                    kind: "string",
+                    description: "Exact token from this invitation email preview.",
+                    required: false,
+                },
             ],
         },
         {
@@ -453,8 +666,14 @@ export function registerUgcCommands(program, handle) {
         {
             action: "draft_create",
             command: "posts draft",
-            description: "Preview AI drafting from brief answers; execute only with approved and a credit ceiling.",
+            description: "Preview AI drafting from brief answers. Execute only in the creator workspace with approved and a credit ceiling; publishing delegation does not grant authority to spend creator credits.",
             fields: [
+                {
+                    name: "request_id",
+                    kind: "string",
+                    description: "Request ID from preview. Reuse it after a timeout; a new ID is a new paid draft.",
+                    required: false,
+                },
                 {
                     name: "participation_id",
                     kind: "string",
@@ -589,7 +808,7 @@ export function registerUgcCommands(program, handle) {
         {
             action: "voice_import",
             command: "voice import",
-            description: "Preview LinkedIn voice import; execute only with approved and a credit ceiling.",
+            description: "Preview all retrievable LinkedIn history and voice inference; approve a total credit ceiling to start. Use --import-id to resume a safely interrupted import with its saved progress and spend.",
             fields: [
                 {
                     name: "participation_id",
@@ -597,6 +816,12 @@ export function registerUgcCommands(program, handle) {
                     description: "Creator participation ID.",
                     required: true,
                 },
+                {
+                    name: "import_id",
+                    kind: "string",
+                    description: "Existing safely interrupted import to resume; max-credits is its total ceiling including credits already used.",
+                    required: false,
+                },
                 {
                     name: "approved",
                     kind: "boolean",
@@ -611,10 +836,66 @@ export function registerUgcCommands(program, handle) {
                 },
             ],
         },
+        {
+            action: "voice_save",
+            command: "voice save",
+            description: "Save your own writing preferences and examples as a private provisional Knowledge voice. Free: 0 credits, no provider call or connected account required. Existing voice edits require its current revision.",
+            fields: [
+                {
+                    name: "participation_id",
+                    kind: "string",
+                    description: "Your creator participation ID.",
+                    required: true,
+                },
+                {
+                    name: "body",
+                    kind: "string",
+                    description: "Your own writing preferences or voice guide (Markdown).",
+                    required: true,
+                },
+                {
+                    name: "writing_examples",
+                    kind: "array",
+                    description: "JSON array of up to five examples you actually wrote; do not invent personal experiences.",
+                    required: false,
+                },
+                {
+                    name: "expected_revision",
+                    kind: "number",
+                    description: "Current profile revision returned by voice get, required when editing it.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "sponsorship_cancel",
+            command: "sponsorship cancel",
+            description: "Preview stopping renewal for one program sponsorship. Confirm with --approved and a signed-in master admin. Participation and credits through the paid period remain available.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Master program ID.",
+                    required: true,
+                },
+                {
+                    name: "participation_id",
+                    kind: "string",
+                    description: "Exact creator participation ID.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Approve the exact cancellation preview. Omit for a free preview.",
+                    required: false,
+                },
+            ],
+        },
         {
             action: "sponsorship_preview",
             command: "sponsorship preview",
-            description: "Preview seat charges and monthly 10,000-credit creator grants for this program.",
+            description: "Preview seat charges and monthly 10,000-credit creator grants as a signed-in master workspace admin. Org API keys cannot create this quote.",
             fields: [
                 {
                     name: "program_id",
@@ -633,7 +914,7 @@ export function registerUgcCommands(program, handle) {
         {
             action: "sponsorship_confirm",
             command: "sponsorship confirm",
-            description: "Approve the exact sponsorship quote; each master program pays separately even for the same account.",
+            description: "Confirm the exact sponsorship quote as the same signed-in master workspace admin. Each program pays separately, even for the same account.",
             fields: [
                 {
                     name: "program_id",
@@ -661,11 +942,54 @@ export function registerUgcCommands(program, handle) {
                 },
             ],
         },
+        {
+            action: "amplification_reconcile",
+            command: "amplification reconcile",
+            description: "Preview recording a provider observation for an uncertain program action. Confirmation needs a signed-in operator and --approved; it never contacts the provider or authorizes a retry.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID in the master workspace.",
+                    required: true,
+                },
+                {
+                    name: "action_id",
+                    kind: "string",
+                    description: "Unresolved effect_unknown action ID.",
+                    required: true,
+                },
+                {
+                    name: "outcome",
+                    kind: "string",
+                    description: "Observed applied or not_applied outcome.",
+                    required: true,
+                },
+                {
+                    name: "evidence",
+                    kind: "object",
+                    description: "JSON object: provider_post_id, evidence_ref, observed_at ISO instant; applied needs provider_object_id and comments/reposts need exact observed_text. Optional note.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Explicitly confirm this immutable observation. No retry is authorized.",
+                    required: false,
+                },
+            ],
+        },
         {
             action: "amplification_save",
             command: "amplification save",
             description: "Save exact opted-in sender scope and bounded post-specific amplification. Enabling needs explicit approval.",
             fields: [
+                {
+                    name: "sender_voice_pages",
+                    kind: "object",
+                    description: "JSON map from each acting sender UUID to its selected active Knowledge voice page UUID. Required for comments or reposts; the exact mapping is approved with the policy.",
+                    required: false,
+                },
                 {
                     name: "program_id",
                     kind: "string",
@@ -733,16 +1057,33 @@ export function registerUgcCommands(program, handle) {
             else
                 command.option(flag, field.description);
         }
+        if (spec.action === "invite_create")
+            command.option("--link-only", "Create a shareable link without sending email.");
         command
             .option("--json", "Print a JSON envelope.")
             .action((options) => handle(`ugc ${spec.command}`, options, () => {
-            const body = { action: spec.action };
+            const body = {
+                action: spec.action,
+                ...(spec.fixed ?? {}),
+            };
             for (const field of spec.fields) {
                 const key = field.name.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
                 if (options[key] !== undefined)
                     body[field.name] = parseField(options[key], field);
             }
-            return requestOxygen("/api/cli/ugc", { method: "POST", body });
+            if (spec.action === "invite_create") {
+                body.send_email = options.linkOnly !== true;
+                if (options.linkOnly && (body.approved || body.preview_token))
+                    throw new Error("--link-only cannot be combined with --approved or --preview-token.");
+            }
+            return requestOxygen("/api/cli/ugc", {
+                method: "POST",
+                body,
+                ...(spec.action === "draft_create" &&
+                    typeof body.request_id === "string"
+                    ? { idempotencyKey: body.request_id }
+                    : {}),
+            });
         }));
     }
 }

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

@@ -4,10 +4,10 @@
  *
  * WHY THIS EXISTS. `native_provider.execution.supports_byok` says a TOOL can run on
  * a customer's own key. It does not say the customer has any way to give us one.
- * Those are two different facts, and 10 of the 42 byok-capable native providers
+ * Those are two different facts, and 9 of the 42 byok-capable native providers
  * have the first without the second:
  *
- *   apify builtwith dropleads lusha openwebninja parallel peopledatalabs
+ *   apify builtwith dropleads lusha openwebninja peopledatalabs
  *   rocketreach theirstack wiza
  *
  * For those, `oxygen integrations connect <id> --api-key` does not reach
@@ -17,11 +17,16 @@
  * tool is native generic-REST and `shouldRouteStaticToolThroughComposio` is false, so
  * `resolveOptionalApiKeyCredentials` finds nothing and the call falls back to the
  * MANAGED key — the very key that was out of credits. The command appears to work,
- * changes nothing, and the customer is back where they started with no error.
+ * changes nothing, and the customer is back where they started with no error. The
+ * connect route now refuses each of those nine with a typed `byok_connect_unavailable`
+ * rather than a silent Composio "success"; they stay OFF this list until one gains a
+ * real native connect form.
  *
- * That is precisely the failure Plain T-104 would have hit: `parallel.search` was one
- * of the refused tools, and a refusal message that told Mentcape to connect their own
- * Parallel key would have sent them down a path that silently does nothing.
+ * That is precisely the failure Plain T-104 hit: `parallel.search` was one of the
+ * refused tools, and a refusal message that told Mentcape to connect their own Parallel
+ * key would once have sent them down a path that silently does nothing. Parallel now has
+ * a native api-key connect (catalog.ts) and IS on this list, so that message is finally
+ * true for it — the nine above are the ones it must still never name.
  *
  * So a message may only offer BYOK when BOTH halves hold, and this list is the second
  * half. It lives in @oxygen/shared because the two sides that need it cannot see each

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

@@ -4,10 +4,10 @@
  *
  * WHY THIS EXISTS. `native_provider.execution.supports_byok` says a TOOL can run on
  * a customer's own key. It does not say the customer has any way to give us one.
- * Those are two different facts, and 10 of the 42 byok-capable native providers
+ * Those are two different facts, and 9 of the 42 byok-capable native providers
  * have the first without the second:
  *
- *   apify builtwith dropleads lusha openwebninja parallel peopledatalabs
+ *   apify builtwith dropleads lusha openwebninja peopledatalabs
  *   rocketreach theirstack wiza
  *
  * For those, `oxygen integrations connect <id> --api-key` does not reach
@@ -17,11 +17,16 @@
  * tool is native generic-REST and `shouldRouteStaticToolThroughComposio` is false, so
  * `resolveOptionalApiKeyCredentials` finds nothing and the call falls back to the
  * MANAGED key — the very key that was out of credits. The command appears to work,
- * changes nothing, and the customer is back where they started with no error.
+ * changes nothing, and the customer is back where they started with no error. The
+ * connect route now refuses each of those nine with a typed `byok_connect_unavailable`
+ * rather than a silent Composio "success"; they stay OFF this list until one gains a
+ * real native connect form.
  *
- * That is precisely the failure Plain T-104 would have hit: `parallel.search` was one
- * of the refused tools, and a refusal message that told Mentcape to connect their own
- * Parallel key would have sent them down a path that silently does nothing.
+ * That is precisely the failure Plain T-104 hit: `parallel.search` was one of the
+ * refused tools, and a refusal message that told Mentcape to connect their own Parallel
+ * key would once have sent them down a path that silently does nothing. Parallel now has
+ * a native api-key connect (catalog.ts) and IS on this list, so that message is finally
+ * true for it — the nine above are the ones it must still never name.
  *
  * So a message may only offer BYOK when BOTH halves hold, and this list is the second
  * half. It lives in @oxygen/shared because the two sides that need it cannot see each
@@ -64,6 +69,9 @@ export const NATIVE_API_KEY_CONNECT_INTEGRATION_IDS = new Set([
     // rest — so the native runner does find the key.
     "moltsets",
     "ocean",
+    // Native api-key connect added in catalog.ts (2026-09-10): connect writes an
+    // integration_secrets api_key row the native parallel.* runner reads. T-104.
+    "parallel",
     "predictleads",
     "prospeo",
     "scalelist",