@oxygen-agent/cli 1.1041.21 → 1.1042.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -34,4 +34,4 @@ oxygen update
34
34
 
35
35
  For product documentation, visit https://oxygen-agent.com/docs. For support, visit https://oxygen-agent.com.
36
36
 
37
- Version: 1.1041.21
37
+ Version: 1.1042.29
@@ -2,6 +2,7 @@ import { readPositiveInt } from "../../cli-values.js";
2
2
  import { readPositiveNumber, readCsvOption, CADENCE_FLAG_DESCRIPTION } from "../../command-support.js";
3
3
  import { requestOxygen } from "../../http-client.js";
4
4
  import { readOption } from "../../util.js";
5
+ import { TABLE_SCHEDULE_ACCEPTED_KIND_LIST, TABLE_SCHEDULE_COLUMN_KINDS } from "@oxygen/shared/tables/schedule-kinds";
5
6
  import { Command } from "commander";
6
7
  import { buildTablesAutoDedupeSetBody } from "./automation.js";
7
8
  export function registerAutomation({ tablesCommand, handleAsyncAction }) {
@@ -83,9 +84,9 @@ export function registerAutomation({ tablesCommand, handleAsyncAction }) {
83
84
  tablesCommand.addCommand(new Command("schedule")
84
85
  .description("Scheduled column refresh: a cron workflow re-runs one column on a schedule (only empty/failed cells unless --force). One schedule per column.")
85
86
  .addCommand(new Command("set")
86
- .description("Create or replace a column's scheduled refresh (a cron-triggered hosted workflow; visible via `oxygen workflows list`). Paid columns (tool, AI, enrichment) require --max-credits AND --approved; formula columns are free.")
87
+ .description(`Create or replace a column's scheduled refresh (a cron-triggered hosted workflow; visible via \`oxygen workflows list\`). Paid columns (${TABLE_SCHEDULE_COLUMN_KINDS.paid.join(", ")}) require --max-credits AND --approved; ${TABLE_SCHEDULE_COLUMN_KINDS.free.join(", ")} columns are free.`)
87
88
  .argument("<table>", "Table id or slug.")
88
- .argument("<column>", "Column key or id (tool, AI, formula, or enrichment kind).")
89
+ .argument("<column>", `Column key or id. Only a ${TABLE_SCHEDULE_ACCEPTED_KIND_LIST} column can be scheduled.`)
89
90
  .option("--cron <expr>", 'Cron expression in UTC, e.g. "0 9 * * *".')
90
91
  .option("--every <sugar>", CADENCE_FLAG_DESCRIPTION)
91
92
  .option("--max-credits <n>", "Credit ceiling PER scheduled refresh; required with --approved for paid columns.")
@@ -106,9 +106,6 @@ const MUTATING_VERBS = new Set([
106
106
  // someone else can take it within minutes. It is the only `release` leaf.
107
107
  "release",
108
108
  ]);
109
- // Exact commands that must not inherit a read-only discovery label. Warmup
110
- // status persists state and can pause the provider; reconnect replaces its
111
- // connection and can restart provider history. Other status commands are reads.
112
109
  // Exact paid leaves with no approval flag: a newsletter test send emails up to
113
110
  // five member addresses at send.bulk_email each.
114
111
  const SPENDING_WITHOUT_APPROVAL_COMMANDS = new Set([
@@ -167,7 +164,8 @@ const MUTATING_COMMANDS = new Set([
167
164
  "managed-inboxes exit",
168
165
  // A default preview is free; approval restores provider seats and billing.
169
166
  "managed-inboxes recover",
170
- "mailboxes warmup status",
167
+ // Replaces the provider connection and can restart provider history. `warmup
168
+ // status` left this set when it became a pure read (Plain T-317).
171
169
  "mailboxes warmup reconnect",
172
170
  // Approval creates a provider consent link; status can attach its receipt.
173
171
  "mailboxes warmup google",
@@ -198,7 +198,6 @@ export type OrgsSelectResponse = {
198
198
  };
199
199
  export declare const TABLE_INGESTION_WAIT_DEFAULT_TIMEOUT_SECONDS = 600;
200
200
  export declare const TABLE_INGESTION_WAIT_DEFAULT_INTERVAL_SECONDS = 5;
201
- export declare function formatDisabledWorkflowNotices(data: unknown): string[];
202
201
  export declare function writeListCapNotice(data: unknown, noun: string, hint?: string): void;
203
202
  export declare function parseJsonArray(value: string): unknown[];
204
203
  /**
@@ -13,7 +13,6 @@ import { OxygenError, success } from "@oxygen/shared/cli-result";
13
13
  import { WORKSPACE_ROLES } from "@oxygen/shared/access/roles";
14
14
  import { COLLAB_SUBJECT_KINDS, SUBJECT_PATH_FORMS_PROSE, formatSubjectPath, parseSubjectPath, parseSubjectRef } from "@oxygen/shared/collab";
15
15
  import { tableRunSummary } from "@oxygen/shared/tables/run-summary";
16
- import { describeWorkflowStatusChange, parseWorkflowStatusChange } from "@oxygen/shared/workflows/status-change";
17
16
  import { createHash } from "node:crypto";
18
17
  import { readFileSync } from "node:fs";
19
18
  import { readFile } from "node:fs/promises";
@@ -84,36 +83,6 @@ const TABLE_ACTION_RUN_WAIT_DEFAULT_TIMEOUT_SECONDS = 600;
84
83
  const TABLE_ACTION_RUN_WAIT_DEFAULT_INTERVAL_SECONDS = 5;
85
84
  export const TABLE_INGESTION_WAIT_DEFAULT_TIMEOUT_SECONDS = 600;
86
85
  export const TABLE_INGESTION_WAIT_DEFAULT_INTERVAL_SECONDS = 5;
87
- // A disabled workflow is a customer's automation at zero, and `status:
88
- // "disabled"` alone never said who did that or why (OXY-4124). Mirror the
89
- // recorded transition as one stderr line per disabled workflow, so `workflows
90
- // list` / `workflows get` answer "who turned this off?" in the terminal without
91
- // polluting the machine-read stdout envelope (which carries `statusChange` in
92
- // full). Sourced from the same shared sentence the web banner renders.
93
- export function formatDisabledWorkflowNotices(data) {
94
- if (!data || typeof data !== "object" || Array.isArray(data))
95
- return [];
96
- const block = data;
97
- const candidates = Array.isArray(block.workflows)
98
- ? block.workflows
99
- : [block.workflow];
100
- const notices = [];
101
- for (const candidate of candidates) {
102
- if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
103
- continue;
104
- const workflow = candidate;
105
- if (workflow.status !== "disabled")
106
- continue;
107
- const slug = typeof workflow.slug === "string" ? workflow.slug : "workflow";
108
- const change = parseWorkflowStatusChange(workflow.statusChange);
109
- // A workflow disabled before the record shipped has no actor to name. Say
110
- // that plainly rather than inventing one.
111
- notices.push(change
112
- ? `${slug}: ${describeWorkflowStatusChange(change)}`
113
- : `${slug}: disabled — no actor was recorded (disabled before Oxygen tracked this).`);
114
- }
115
- return notices;
116
- }
117
86
  // Discovery lists are windowed by default (200 rows, max 1000) so the cost of
118
87
  // asking "what is in this workspace?" does not scale with how much the customer
119
88
  // has built. A window nobody can see is indistinguishable from a complete
@@ -488,7 +457,7 @@ export function pausedTableRunWaitDetails(runId, latestRun, status) {
488
457
  ...(userMessage ? { user_message: userMessage } : {}),
489
458
  ...(forCredits ? { recommended_action: "top_up_then_resume" } : {}),
490
459
  next_step: forCredits
491
- ? `${heldForAccounts ? "Top up credits or disconnect an account" : "Top up credits"} in Billing, then run \`${resume}\`.`
460
+ ? `${heldForAccounts ? "Top up credits in Billing or disconnect an account you no longer need (`oxygen billing commitments` lists what holds credits)" : "Top up credits in Billing"}, then run \`${resume}\`.`
492
461
  : `Run \`${resume}\` to continue it.`,
493
462
  };
494
463
  }
@@ -876,7 +876,7 @@ export function registerColumnsFamily(program, handleAsyncAction) {
876
876
  .addOption(new Option("--yes-no <question>", "Classification column: answer this yes/no question per row (reference columns as {{column_key}}). Filter on the answer with `tables query --filter-tree-json` and a path leaf, e.g. '{\"type\":\"group\",\"conjunction\":\"and\",\"children\":[{\"type\":\"leaf\",\"columnKey\":\"<column>\",\"path\":\"answer\",\"operator\":\"is\",\"value\":true}]}'."))
877
877
  .addOption(new Option("--score <levels>", "Classification column: rate each row on these comma-separated levels, lowest first (2-10), answering --prompt."))
878
878
  .addOption(new Option("--min-confidence <0-1>", "Classification columns: below this the answer is marked uncertain. Default 0.85 (0.7 for --yes-no)."))
879
- .addOption(new Option("--grounding <mode>", "Classification columns: none (default) judges only the row and your question; workspace also sends the Knowledge pages that match it (ICP, positioning) where Knowledge retrieval is on, which is off for AI columns in production today."))
879
+ .addOption(new Option("--grounding <mode>", "Classification columns: none (default) judges only the row and your question; workspace also sends the Knowledge pages that match it (ICP, positioning) unless the workspace turned Knowledge retrieval off."))
880
880
  .option("--bind-object <slug>", "Bind column CRM object slug (companies, people, deals, ...). Sets kind=bind and resolves rows to CRM records by identity.")
881
881
  .option("--bind-map <pairs>", "Bind identity mapping as identity=column pairs, e.g. domain=website,linkedin_url=li.")
882
882
  .option("--bind-create", "Bind columns: assert a new CRM record for unmatched rows (onNoMatch=create; a truth write, needs --approved on run).")
@@ -1259,7 +1259,7 @@ export function registerMailboxesFamily(program, handleAsyncAction) {
1259
1259
  });
1260
1260
  }))
1261
1261
  .addCommand(new Command("resume")
1262
- .description("Resume paused warmup at each mailbox's recorded rail (OXYGEN Warm-up, or TrulyInbox for inboxes still warming there). 0 Oxygen credits; the existing subscription is unchanged. This changes warmup state and uses the last stored analytics snapshot; run warmup status afterward for fresh provider data. Running status alone does not prove a new successful send. A mailbox on a rail Oxygen no longer drives reports unsupported instead of being retargeted. Targets the whole pool unless --mailboxes is given.")
1262
+ .description("Resume paused warmup at each mailbox's recorded rail (OXYGEN Warm-up, or TrulyInbox for inboxes still warming there). 0 Oxygen credits; the existing subscription is unchanged. This changes warmup state and uses the last stored analytics snapshot; run warmup sync afterward for fresh provider data. A sync alone does not prove a new successful send. A mailbox on a rail Oxygen no longer drives reports unsupported instead of being retargeted. Targets the whole pool unless --mailboxes is given.")
1263
1263
  .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses. Omit for the whole pool.")
1264
1264
  .option("--json", "Print a JSON envelope.")
1265
1265
  .action(async (options) => {
@@ -1287,7 +1287,7 @@ export function registerMailboxesFamily(program, handleAsyncAction) {
1287
1287
  });
1288
1288
  }))
1289
1289
  .addCommand(new Command("reactivate")
1290
- .description("Manual reactivation of an existing live paid seat: ask the warm-up provider to re-run the connection check on an inbox it has DISABLED and, once it passes, restart a warm-up the provider stopped, without touching the credential or subscription. When worker recovery is enforcing, OXYGEN first re-checks a Microsoft OAuth or tenant-consent seat automatically, without a password or new browser consent; only this command restarts a stopped warm-up. Use it while recovery is staged in shadow/off, or if `warmup status` still asks you to reactivate after bounded attempts; `warmup reconnect` cannot re-push a password for that consent seat. 0 credits: the subscription and its renewal date stay exactly as they are, so it is the free alternative to disable + re-enable (which bills another warm-up month). A restarted warm-up ramps up again from day 1, and a restart needs an active subscription that renews. If a tenant policy blocks sign-in (for example SMTP AUTH switched off), the tenant admin lifts it first. Only inboxes with a live warm-up subscription are eligible. IMPORTANT: this forces the provider to re-check; a forced pass is NOT proof the connection works. Confirm recovery from a rising send count with `oxygen mailboxes warmup status` after the provider's next batch, which is hours away, not minutes. Targets the whole pool unless --mailboxes is given.")
1290
+ .description("Manual reactivation of an existing live paid seat: ask the warm-up provider to re-run the connection check on an inbox it has DISABLED and, once it passes, restart a warm-up the provider stopped, without touching the credential or subscription. When worker recovery is enforcing, OXYGEN first re-checks a Microsoft OAuth or tenant-consent seat automatically, without a password or new browser consent; only this command restarts a stopped warm-up. Use it while recovery is staged in shadow/off, or if `warmup status` still asks you to reactivate after bounded attempts; `warmup reconnect` cannot re-push a password for that consent seat. 0 credits: the subscription and its renewal date stay exactly as they are, so it is the free alternative to disable + re-enable (which bills another warm-up month). A restarted warm-up ramps up again from day 1, and a restart needs an active subscription that renews. If a tenant policy blocks sign-in (for example SMTP AUTH switched off), the tenant admin lifts it first. Only inboxes with a live warm-up subscription are eligible. IMPORTANT: this forces the provider to re-check; a forced pass is NOT proof the connection works. Confirm recovery from a rising send count with `oxygen mailboxes warmup sync` after the provider's next batch, which is hours away, not minutes. Targets the whole pool unless --mailboxes is given.")
1291
1291
  .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses. Omit for the whole pool.")
1292
1292
  .option("--json", "Print a JSON envelope.")
1293
1293
  .action(async (options) => {
@@ -1315,10 +1315,13 @@ export function registerMailboxesFamily(program, handleAsyncAction) {
1315
1315
  });
1316
1316
  }))
1317
1317
  .addCommand(new Command("status")
1318
- .description("Read warmup analytics back from the rail each mailbox is enrolled on and refresh each mailbox's warmupTruth (state, last send, pause reason, dispatch counters, next_action). A read: 0 Oxygen credits, no campaign sends, no change to your configuration; the one write OXYGEN may make is its own breaker pausing a mailbox proven to be dispatching far above its ramp. Targets the whole pool unless --mailboxes is given. For a per-mailbox read without a rail sync, use `oxygen mailboxes get <address> --json`.")
1319
- .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses to sync. Omit to sync the whole pool.")
1320
- .option("--provider <name>", "Optional machine routing filter. Omit it for OXYGEN Warm-up; pass trulyinbox only to read inboxes still warming on the retired rail.")
1321
- .option("--dry-run", "Skip the provider call (mailboxes marked pending).")
1318
+ .description("Read each mailbox's stored warm-up state: warmupTruth (state, last send, pause reason, dispatch counters, next_action), renewal and billing. A pure read: no provider call and no change. OXYGEN re-reads warming and error mailboxes on its own; run `warmup sync` for a fresh provider read now. Targets the whole pool unless --mailboxes is given.")
1319
+ .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses. Omit for the whole pool.")
1320
+ // Retired when status became a pure read (Plain T-317). Hidden, not
1321
+ // removed: an old script passing them gets the server's refusal,
1322
+ // which names `warmup sync`, instead of an unknown-option error.
1323
+ .addOption(new Option("--provider <name>", "Retired: use `warmup sync --provider`.").hideHelp())
1324
+ .addOption(new Option("--dry-run", "Retired: use `warmup sync --dry-run`.").hideHelp())
1322
1325
  .option("--json", "Print a JSON envelope.")
1323
1326
  .action(async (options) => {
1324
1327
  await handleAsyncAction("mailboxes warmup status", options, () => {
@@ -1326,12 +1329,6 @@ export function registerMailboxesFamily(program, handleAsyncAction) {
1326
1329
  const mailboxes = readCsvOption(options.mailboxes);
1327
1330
  if (mailboxes.length > 0)
1328
1331
  params.set("mailboxes", mailboxes.join(","));
1329
- const connection = readOption(options.connection);
1330
- if (connection)
1331
- params.set("connection_id", connection);
1332
- const billingMode = readOption(options.billingMode);
1333
- if (billingMode)
1334
- params.set("billing_mode", billingMode);
1335
1332
  const provider = readOption(options.provider);
1336
1333
  if (provider)
1337
1334
  params.set("provider", provider);
@@ -1340,6 +1337,33 @@ export function registerMailboxesFamily(program, handleAsyncAction) {
1340
1337
  const suffix = params.toString();
1341
1338
  return requestOxygen(`/api/cli/mailboxes/warmup/status${suffix ? `?${suffix}` : ""}`);
1342
1339
  });
1340
+ }))
1341
+ .addCommand(new Command("sync")
1342
+ .description("Read warmup analytics back from the rail each mailbox is enrolled on and save them, refreshing each mailbox's warmupTruth. 0 Oxygen credits, no campaign sends, no change to your configuration; OXYGEN's breaker may pause a mailbox proven to be dispatching far above its ramp. Targets the whole pool unless --mailboxes is given. `warmup status` reads the saved result without a provider call.")
1343
+ .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses to sync. Omit to sync the whole pool.")
1344
+ .option("--provider <name>", "Optional machine routing filter. Omit it for OXYGEN Warm-up; pass trulyinbox only to sync inboxes still warming on the retired rail.")
1345
+ .option("--dry-run", "Call no provider and save nothing (covered mailboxes show pending).")
1346
+ .option("--json", "Print a JSON envelope.")
1347
+ .action(async (options) => {
1348
+ await handleAsyncAction("mailboxes warmup sync", options, () => {
1349
+ const mailboxes = readCsvOption(options.mailboxes);
1350
+ // No --connection/--billing-mode flag since the BYOK rails were
1351
+ // retired (v1.433.1), as on `warmup enable`; the route's legacy
1352
+ // fields stay in the body grammar and fail closed there.
1353
+ const connection = readOption(options.connection);
1354
+ const billingMode = readOption(options.billingMode);
1355
+ const provider = readOption(options.provider);
1356
+ return requestOxygen("/api/cli/mailboxes/warmup/sync", {
1357
+ method: "POST",
1358
+ body: {
1359
+ ...(mailboxes.length > 0 ? { mailboxes } : {}),
1360
+ ...(connection ? { connection_id: connection } : {}),
1361
+ ...(billingMode ? { billing_mode: billingMode } : {}),
1362
+ ...(provider ? { provider } : {}),
1363
+ ...(options.dryRun ? { dry_run: true } : {}),
1364
+ },
1365
+ });
1366
+ });
1343
1367
  })))
1344
1368
  .addCommand(new Command("order")
1345
1369
  .description("RETIRED — managed mailboxes are now purchased as monthly subscriptions via `oxygen managed-inboxes subscribe` (InboxKit-backed). This legacy Zapmail order path was never enabled anywhere and now always fails with code `gone`.")
@@ -2,8 +2,9 @@ import { addCompactListReadFlags, appendCompactListReadQuery } from "../compact-
2
2
  import { emitCliFailure, writeJson } from "../cli-output.js";
3
3
  import { CLI_MODULE_DIR } from "../cli-paths.js";
4
4
  import { parseJsonObject, readPositiveInt, readRecordString } from "../cli-values.js";
5
- import { collectMultiple, formatDisabledWorkflowNotices, parseJsonValue, readCsvOption, readPositiveNumber, writeListCapNotice } from "../command-support.js";
5
+ import { collectMultiple, parseJsonValue, readCsvOption, readPositiveNumber, writeListCapNotice } from "../command-support.js";
6
6
  import { addContractFlags } from "../contract-flags.js";
7
+ import { formatDisabledWorkflowNotices } from "../disabled-workflow-notices.js";
7
8
  import { requestOxygen } from "../http-client.js";
8
9
  import { importJavaScriptWorkflowModule, importTranspiledWorkflowModule, loadRecipeFromBundle } from "../local-module-loader.js";
9
10
  import { waitForCliRun } from "../run-wait.js";
@@ -0,0 +1 @@
1
+ export declare function formatDisabledWorkflowNotices(data: unknown): string[];
@@ -0,0 +1,34 @@
1
+ import { WORKFLOW_SWITCH_OFF_UNRECORDED, currentWorkflowStatusChange, describeWorkflowStatusChange, } from "@oxygen/shared/workflows/status-change";
2
+ // A disabled workflow is a customer's automation at zero, and `status:
3
+ // "disabled"` alone never said who did that or why (OXY-4124). Mirror the
4
+ // recorded transition as one stderr line per disabled workflow, so `workflows
5
+ // list` / `workflows get` answer "who turned this off?" in the terminal without
6
+ // polluting the machine-read stdout envelope (which carries `statusChange` in
7
+ // full). Sourced from the same shared sentence the web banner renders.
8
+ export function formatDisabledWorkflowNotices(data) {
9
+ if (!data || typeof data !== "object" || Array.isArray(data))
10
+ return [];
11
+ const block = data;
12
+ const candidates = Array.isArray(block.workflows)
13
+ ? block.workflows
14
+ : [block.workflow];
15
+ const notices = [];
16
+ for (const candidate of candidates) {
17
+ if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
18
+ continue;
19
+ const workflow = candidate;
20
+ if (workflow.status !== "disabled")
21
+ continue;
22
+ const slug = typeof workflow.slug === "string" ? workflow.slug : "workflow";
23
+ // Only a record of the switch-off explains a disabled workflow. A publish
24
+ // before OXP-3.4.304 could leave the record of an older change ("Enabled by
25
+ // ..."), and a workflow created disabled has none; say which cases remain
26
+ // rather than inventing an actor (OXP-3.4.316). Checked here too, so the
27
+ // line stays true against a server that still sends such a record.
28
+ const change = currentWorkflowStatusChange(workflow.status, workflow.statusChange);
29
+ notices.push(change
30
+ ? `${slug}: ${describeWorkflowStatusChange(change)}`
31
+ : `${slug}: disabled. ${WORKFLOW_SWITCH_OFF_UNRECORDED}`);
32
+ }
33
+ return notices;
34
+ }
package/dist/index.d.ts CHANGED
@@ -1,2 +1,2 @@
1
1
  export { createProgram } from "./command-families/program.js";
2
- export { formatDisabledWorkflowNotices } from "./command-support.js";
2
+ export { formatDisabledWorkflowNotices } from "./disabled-workflow-notices.js";
package/dist/index.js CHANGED
@@ -133,4 +133,4 @@ function installCommanderExitOverride(command) {
133
133
  for (const child of command.commands)
134
134
  installCommanderExitOverride(child);
135
135
  }
136
- export { formatDisabledWorkflowNotices } from "./command-support.js";
136
+ export { formatDisabledWorkflowNotices } from "./disabled-workflow-notices.js";
@@ -8,8 +8,9 @@ export type McpCatalogEventName = Extract<McpEventName, "reply.classified" | "en
8
8
  /**
9
9
  * How OXYGEN classified a reply. The first six are the Inbox labels the
10
10
  * classifier sets, and `bounced` is set when the bounce arrives. A label the
11
- * workspace defined is `other`, because its key is workspace-authored text; a
12
- * one-click email unsubscribe, which has no reply, is `unsubscribed`.
11
+ * workspace defined is `other`, because its key is workspace-authored text; an
12
+ * unsubscribe through the unsubscribe link or one-click unsubscribe OXYGEN adds
13
+ * to a cold email, which has no reply, is `unsubscribed`.
13
14
  */
14
15
  export declare const MCP_REPLY_CLASSIFICATIONS: readonly ["interested", "neutral", "not_now", "not_interested", "out_of_office", "wrong_person", "bounced", "unsubscribed", "other"];
15
16
  export type McpReplyClassification = (typeof MCP_REPLY_CLASSIFICATIONS)[number];
@@ -33,8 +33,9 @@ export const MCP_EVENT_NAMES = [
33
33
  /**
34
34
  * How OXYGEN classified a reply. The first six are the Inbox labels the
35
35
  * classifier sets, and `bounced` is set when the bounce arrives. A label the
36
- * workspace defined is `other`, because its key is workspace-authored text; a
37
- * one-click email unsubscribe, which has no reply, is `unsubscribed`.
36
+ * workspace defined is `other`, because its key is workspace-authored text; an
37
+ * unsubscribe through the unsubscribe link or one-click unsubscribe OXYGEN adds
38
+ * to a cold email, which has no reply, is `unsubscribed`.
38
39
  */
39
40
  export const MCP_REPLY_CLASSIFICATIONS = [
40
41
  "interested",
@@ -100,15 +101,15 @@ function payloadObject(properties) {
100
101
  return obj(properties, { required: Object.keys(properties) });
101
102
  }
102
103
  const REPLY_CLASSIFIED_INPUT = obj({
103
- sequence_id: id("Only replies from leads enrolled in this Sequence."),
104
+ sequence_id: id("Only replies from leads enrolled in this Sequence, and unsubscribes from its emails."),
104
105
  classification: enumOf(MCP_REPLY_CLASSIFICATIONS, { description: "Only replies with this classification." }),
105
106
  });
106
107
  const REPLY_CLASSIFIED_PAYLOAD = payloadObject({
107
108
  classification: enumOf(MCP_REPLY_CLASSIFICATIONS, {
108
- description: "How OXYGEN classified the reply. `bounced` is a bounce, `unsubscribed` a one-click email unsubscribe, `other` a label your workspace defined.",
109
+ description: "How OXYGEN classified the reply. `bounced` is a bounce, `unsubscribed` an unsubscribe through the unsubscribe link or one-click unsubscribe OXYGEN adds to a cold email, `other` a label your workspace defined.",
109
110
  }),
110
111
  channel: enumOf(MCP_REPLY_CHANNELS, { description: "Where the reply arrived." }),
111
- conversation_id: nullable(id("The Inbox conversation; null for a one-click unsubscribe, which has none.")),
112
+ conversation_id: nullable(id("The Inbox conversation; null for `unsubscribed`, which has none.")),
112
113
  record_id: nullable(id("The lead's CRM person record; null when OXYGEN has not matched one.")),
113
114
  sequence_id: nullable(id("The Sequence the lead was enrolled in; null outside Sequences.")),
114
115
  enrollment_id: nullable(id("The lead's enrollment in that Sequence; null outside Sequences.")),
@@ -191,7 +192,7 @@ function eventDefinition(name, description, inputSchema, payloadSchema) {
191
192
  }
192
193
  /** What `events/list` answers, in this order. Plain JSON: nothing internal rides along. Read-only. */
193
194
  export const MCP_EVENT_DEFINITIONS = [
194
- eventDefinition("reply.classified", "A lead replied to your outreach by email, LinkedIn or WhatsApp and OXYGEN classified the reply in its Inbox. A one-click email unsubscribe, which has no reply, arrives as `unsubscribed`. Ids only: message text and contact details stay in OXYGEN.", REPLY_CLASSIFIED_INPUT, REPLY_CLASSIFIED_PAYLOAD),
195
+ eventDefinition("reply.classified", "A lead replied to your outreach by email, LinkedIn or WhatsApp and OXYGEN classified the reply in its Inbox. It also arrives when a lead unsubscribes through the unsubscribe link or one-click unsubscribe OXYGEN adds to a cold email: there is no reply, so it comes as `unsubscribed` with a null `conversation_id`. Subscribe with a `classification` other than `unsubscribed` to receive only that classification and skip unsubscribes, or drop `unsubscribed` deliveries in your handler. Ids only: message text and contact details stay in OXYGEN.", REPLY_CLASSIFIED_INPUT, REPLY_CLASSIFIED_PAYLOAD),
195
196
  eventDefinition("enrollment.ended", "A lead's enrollment in an OXYGEN Sequence ended: the lead replied, every step was sent, the enrollment was stopped or excluded, or sending failed.", ENROLLMENT_ENDED_INPUT, ENROLLMENT_ENDED_PAYLOAD),
196
197
  eventDefinition("meeting.completed", "OXYGEN's Meeting Notetaker finished processing a recorded meeting; its transcript and meeting note are ready in OXYGEN.", MEETING_COMPLETED_INPUT, MEETING_COMPLETED_PAYLOAD),
197
198
  eventDefinition("record.stage_changed", "A CRM record's stage changed in OXYGEN, such as a person's lead stage, a company's account stage or a deal's pipeline stage.", RECORD_STAGE_CHANGED_INPUT, RECORD_STAGE_CHANGED_PAYLOAD),
@@ -600,7 +601,7 @@ function replyClassification(payload) {
600
601
  const label = readTrimmedString(payload.status);
601
602
  if (label)
602
603
  return REPLY_LABELS_DELIVERED_AS_IS.has(label) ? label : "other";
603
- // The one-click unsubscribe route records an opt-out with no reply to classify.
604
+ // The unsubscribe link and one-click unsubscribe record an opt-out with no reply to classify.
604
605
  if (payload.opt_out === true)
605
606
  return "unsubscribed";
606
607
  throw sourceError("reply.classified", "carries neither a classification nor an opt-out");
@@ -0,0 +1,27 @@
1
+ /**
2
+ * LinkedIn keeps one InMail credit pool per product: Classic Premium, Sales
3
+ * Navigator and Recruiter. A credit in one pool cannot pay for an InMail sent
4
+ * through another, so a sender can hold 150 Sales Navigator credits and still be
5
+ * refused "Not enough InMail credits" on a Classic send (production 2026-11-13).
6
+ * Report the pools separately; never add them up.
7
+ */
8
+ export declare const LINKEDIN_INMAIL_POOLS: readonly ["classic", "sales_navigator", "recruiter"];
9
+ export type LinkedInInMailPool = (typeof LINKEDIN_INMAIL_POOLS)[number];
10
+ /** Credits per pool. A pool the account does not subscribe to is absent. */
11
+ export type LinkedInInMailCredits = Partial<Record<LinkedInInMailPool, number>>;
12
+ /** The pools a sequence InMail step can send from. Recruiter needs a signature and a hiring project. */
13
+ export type LinkedInSequenceInMailPool = Extract<LinkedInInMailPool, "classic" | "sales_navigator">;
14
+ /**
15
+ * Read the per-pool credits from a Unipile v2 `inmail-credits` body
16
+ * (`{ object: "InmailCredits", credits: { classic?, sales_navigator?, recruiter? } }`).
17
+ * Null when the body has no credits object, so an unexpected shape reads as
18
+ * unknown rather than as zero.
19
+ */
20
+ export declare function readLinkedInInMailCredits(body: unknown): LinkedInInMailCredits | null;
21
+ /**
22
+ * The pool a sequence InMail is sent from: Classic while it has credits (the
23
+ * path every existing InMail campaign uses), else Sales Navigator while it has
24
+ * credits. Null when neither has any: the send then goes out through Classic,
25
+ * which LinkedIn still accepts for free when the lead is an Open Profile.
26
+ */
27
+ export declare function chooseLinkedInSequenceInMailPool(credits: LinkedInInMailCredits | null): LinkedInSequenceInMailPool | null;
@@ -0,0 +1,43 @@
1
+ /**
2
+ * LinkedIn keeps one InMail credit pool per product: Classic Premium, Sales
3
+ * Navigator and Recruiter. A credit in one pool cannot pay for an InMail sent
4
+ * through another, so a sender can hold 150 Sales Navigator credits and still be
5
+ * refused "Not enough InMail credits" on a Classic send (production 2026-11-13).
6
+ * Report the pools separately; never add them up.
7
+ */
8
+ export const LINKEDIN_INMAIL_POOLS = ["classic", "sales_navigator", "recruiter"];
9
+ /**
10
+ * Read the per-pool credits from a Unipile v2 `inmail-credits` body
11
+ * (`{ object: "InmailCredits", credits: { classic?, sales_navigator?, recruiter? } }`).
12
+ * Null when the body has no credits object, so an unexpected shape reads as
13
+ * unknown rather than as zero.
14
+ */
15
+ export function readLinkedInInMailCredits(body) {
16
+ if (!body || typeof body !== "object" || Array.isArray(body))
17
+ return null;
18
+ const credits = body.credits;
19
+ if (!credits || typeof credits !== "object" || Array.isArray(credits))
20
+ return null;
21
+ const out = {};
22
+ for (const pool of LINKEDIN_INMAIL_POOLS) {
23
+ const value = credits[pool];
24
+ if (typeof value === "number" && Number.isFinite(value))
25
+ out[pool] = value;
26
+ }
27
+ return out;
28
+ }
29
+ /**
30
+ * The pool a sequence InMail is sent from: Classic while it has credits (the
31
+ * path every existing InMail campaign uses), else Sales Navigator while it has
32
+ * credits. Null when neither has any: the send then goes out through Classic,
33
+ * which LinkedIn still accepts for free when the lead is an Open Profile.
34
+ */
35
+ export function chooseLinkedInSequenceInMailPool(credits) {
36
+ if (!credits)
37
+ return null;
38
+ if ((credits.classic ?? 0) > 0)
39
+ return "classic";
40
+ if ((credits.sales_navigator ?? 0) > 0)
41
+ return "sales_navigator";
42
+ return null;
43
+ }
@@ -0,0 +1,23 @@
1
+ /**
2
+ * The column kinds a Table schedule takes (`oxygen tables schedule set`, MCP
3
+ * `oxygen_tables_schedule`, POST /api/cli/tables/schedule), split by whether a
4
+ * scheduled refresh spends on the column (OXP-3.4.345). The route refuses every
5
+ * other kind with `unsupported_column_schedule`, and CLI help and the MCP
6
+ * description name these lists, so no surface offers a kind another refuses.
7
+ *
8
+ * - `paid`: a schedule needs max_credits and approved.
9
+ * - `free`: a schedule arms without approval, pinned to its kind.
10
+ *
11
+ * A table action run also executes research, bind and lookup. No one has decided
12
+ * that a schedule should take them: schedules shipped (v1.321) while the enqueue
13
+ * step could not run bind or lookup, before research existed.
14
+ */
15
+ export declare const TABLE_SCHEDULE_COLUMN_KINDS: {
16
+ readonly paid: readonly ["tool", "ai", "enrichment"];
17
+ readonly free: readonly ["formula"];
18
+ };
19
+ export type TableScheduleColumnKind = (typeof TABLE_SCHEDULE_COLUMN_KINDS.paid)[number] | (typeof TABLE_SCHEDULE_COLUMN_KINDS.free)[number];
20
+ /** Every kind a schedule takes, paid first. */
21
+ export declare const TABLE_SCHEDULE_ACCEPTED_COLUMN_KINDS: readonly TableScheduleColumnKind[];
22
+ /** "tool, ai, enrichment or formula": the list the refusal and CLI help print. */
23
+ export declare const TABLE_SCHEDULE_ACCEPTED_KIND_LIST: string;
@@ -0,0 +1,27 @@
1
+ /**
2
+ * The column kinds a Table schedule takes (`oxygen tables schedule set`, MCP
3
+ * `oxygen_tables_schedule`, POST /api/cli/tables/schedule), split by whether a
4
+ * scheduled refresh spends on the column (OXP-3.4.345). The route refuses every
5
+ * other kind with `unsupported_column_schedule`, and CLI help and the MCP
6
+ * description name these lists, so no surface offers a kind another refuses.
7
+ *
8
+ * - `paid`: a schedule needs max_credits and approved.
9
+ * - `free`: a schedule arms without approval, pinned to its kind.
10
+ *
11
+ * A table action run also executes research, bind and lookup. No one has decided
12
+ * that a schedule should take them: schedules shipped (v1.321) while the enqueue
13
+ * step could not run bind or lookup, before research existed.
14
+ */
15
+ export const TABLE_SCHEDULE_COLUMN_KINDS = {
16
+ paid: ["tool", "ai", "enrichment"],
17
+ free: ["formula"],
18
+ };
19
+ /** Every kind a schedule takes, paid first. */
20
+ export const TABLE_SCHEDULE_ACCEPTED_COLUMN_KINDS = [
21
+ ...TABLE_SCHEDULE_COLUMN_KINDS.paid,
22
+ ...TABLE_SCHEDULE_COLUMN_KINDS.free,
23
+ ];
24
+ /** "tool, ai, enrichment or formula": the list the refusal and CLI help print. */
25
+ export const TABLE_SCHEDULE_ACCEPTED_KIND_LIST = TABLE_SCHEDULE_ACCEPTED_COLUMN_KINDS.length > 1
26
+ ? `${TABLE_SCHEDULE_ACCEPTED_COLUMN_KINDS.slice(0, -1).join(", ")} or ${TABLE_SCHEDULE_ACCEPTED_COLUMN_KINDS[TABLE_SCHEDULE_ACCEPTED_COLUMN_KINDS.length - 1]}`
27
+ : TABLE_SCHEDULE_ACCEPTED_COLUMN_KINDS.join("");
@@ -1,3 +1,3 @@
1
1
  export declare const OXYGEN_VERSION: string;
2
- export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.1014.134";
2
+ export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.1014.136";
3
3
  export declare const GEO_EXPORT_MINIMUM_CLI_VERSION = "1.1013.0";
@@ -1 +1 @@
1
- export declare const OXYGEN_BUILD_VERSION = "1.1041.21";
1
+ export declare const OXYGEN_BUILD_VERSION = "1.1042.29";
@@ -1,2 +1,2 @@
1
1
  // GENERATED by scripts/ci/version-stamp.mjs from VERSION + git history. Do not edit; do not commit.
2
- export const OXYGEN_BUILD_VERSION = "1.1041.21";
2
+ export const OXYGEN_BUILD_VERSION = "1.1042.29";
@@ -49,7 +49,7 @@ export const OXYGEN_VERSION = OXYGEN_BUILD_VERSION;
49
49
  // Since 2026-09-28 the release-preparation step advances this literal to the
50
50
  // highest CLI version published on npm for at least 30 days. It never lowers
51
51
  // the floor. The source change lands on dev before the next production release.
52
- export const OXYGEN_MINIMUM_CLI_VERSION = "1.1014.134";
52
+ export const OXYGEN_MINIMUM_CLI_VERSION = "1.1014.136";
53
53
  // The internal GEO export first gains required pagination in this dev version.
54
54
  // Earlier pilot clients would save a partial file without its continuation.
55
55
  export const GEO_EXPORT_MINIMUM_CLI_VERSION = "1.1013.0";
@@ -16,7 +16,9 @@
16
16
  *
17
17
  * Every surface (web, CLI, MCP) renders the same sentence from
18
18
  * `describeWorkflowStatusChange` so "Disabled by X on Y" reads identically
19
- * wherever a customer meets it.
19
+ * wherever a customer meets it, for a record of the workflow's current status
20
+ * only (`currentWorkflowStatusChange`). For a disabled workflow without one, the
21
+ * CLI and MCP say the same `WORKFLOW_SWITCH_OFF_UNRECORDED`.
20
22
  */
21
23
  export declare const WORKFLOW_STATUS_CHANGE_METADATA_KEY = "last_status_change";
22
24
  /** The surface the transition came through. `auto_pause` is the worker health sweep. */
@@ -51,6 +53,32 @@ export declare function readWorkflowStatusChange(metadata: Record<string, unknow
51
53
  * the API's JSON envelope, where it arrives as `unknown`).
52
54
  */
53
55
  export declare function parseWorkflowStatusChange(raw: unknown): WorkflowStatusChange | null;
56
+ /**
57
+ * The newest status-change record, only while its status is the workflow's
58
+ * CURRENT one; otherwise null. The status flip, and since OXP-3.4.304 a publish
59
+ * that moves the status, write the record in the UPDATE that sets the status,
60
+ * so the two agree. A publish made before then moved the status without one
61
+ * and left the record of the change before it: "Enabled by ..." on a disabled
62
+ * workflow. That record does not explain the status a reader sees, so
63
+ * `workflows get` and `list`, the CLI notice and the MCP summary show none
64
+ * (OXP-3.4.316). A matching record can still predate unrecorded publishes that
65
+ * switched the workflow on and back off; nothing on the row tells. Such rows
66
+ * are not rewritten; their next status change writes a current record. The
67
+ * reply router's arming check reads the raw record and guards it itself
68
+ * (crm/standing-automation.ts).
69
+ */
70
+ export declare function currentWorkflowStatusChange(status: unknown, raw: unknown): WorkflowStatusChange | null;
71
+ /**
72
+ * What the CLI and MCP say about a disabled workflow with no record of being
73
+ * switched off. Creating a workflow changes no status, so a draft, `workflows
74
+ * import` (always), `workflows duplicate` (by default) and a publish whose
75
+ * manifest says disabled create one disabled without a record (a CRM
76
+ * automation disarm records the switch-off of a workflow it creates). A
77
+ * switch-off from before Oxygen recorded every one has none either: before
78
+ * OXY-4124 nothing recorded one, and before OXP-3.4.304 a publish that
79
+ * switched a workflow off did not (OXP-3.4.316).
80
+ */
81
+ export declare const WORKFLOW_SWITCH_OFF_UNRECORDED = "No switch-off is on record: the workflow was created disabled, or switched off before Oxygen recorded every switch-off.";
54
82
  /** Deterministic UTC stamp ("10 Jul 2026 15:40 UTC") — no locale dependence. */
55
83
  export declare function formatWorkflowStatusChangeTimestamp(at: string): string;
56
84
  /**
@@ -16,7 +16,9 @@
16
16
  *
17
17
  * Every surface (web, CLI, MCP) renders the same sentence from
18
18
  * `describeWorkflowStatusChange` so "Disabled by X on Y" reads identically
19
- * wherever a customer meets it.
19
+ * wherever a customer meets it, for a record of the workflow's current status
20
+ * only (`currentWorkflowStatusChange`). For a disabled workflow without one, the
21
+ * CLI and MCP say the same `WORKFLOW_SWITCH_OFF_UNRECORDED`.
20
22
  */
21
23
  export const WORKFLOW_STATUS_CHANGE_METADATA_KEY = "last_status_change";
22
24
  const SOURCES = new Set([
@@ -93,6 +95,35 @@ export function parseWorkflowStatusChange(raw) {
93
95
  }
94
96
  return change;
95
97
  }
98
+ /**
99
+ * The newest status-change record, only while its status is the workflow's
100
+ * CURRENT one; otherwise null. The status flip, and since OXP-3.4.304 a publish
101
+ * that moves the status, write the record in the UPDATE that sets the status,
102
+ * so the two agree. A publish made before then moved the status without one
103
+ * and left the record of the change before it: "Enabled by ..." on a disabled
104
+ * workflow. That record does not explain the status a reader sees, so
105
+ * `workflows get` and `list`, the CLI notice and the MCP summary show none
106
+ * (OXP-3.4.316). A matching record can still predate unrecorded publishes that
107
+ * switched the workflow on and back off; nothing on the row tells. Such rows
108
+ * are not rewritten; their next status change writes a current record. The
109
+ * reply router's arming check reads the raw record and guards it itself
110
+ * (crm/standing-automation.ts).
111
+ */
112
+ export function currentWorkflowStatusChange(status, raw) {
113
+ const change = parseWorkflowStatusChange(raw);
114
+ return change !== null && change.status === status ? change : null;
115
+ }
116
+ /**
117
+ * What the CLI and MCP say about a disabled workflow with no record of being
118
+ * switched off. Creating a workflow changes no status, so a draft, `workflows
119
+ * import` (always), `workflows duplicate` (by default) and a publish whose
120
+ * manifest says disabled create one disabled without a record (a CRM
121
+ * automation disarm records the switch-off of a workflow it creates). A
122
+ * switch-off from before Oxygen recorded every one has none either: before
123
+ * OXY-4124 nothing recorded one, and before OXP-3.4.304 a publish that
124
+ * switched a workflow off did not (OXP-3.4.316).
125
+ */
126
+ export const WORKFLOW_SWITCH_OFF_UNRECORDED = "No switch-off is on record: the workflow was created disabled, or switched off before Oxygen recorded every switch-off.";
96
127
  /** Deterministic UTC stamp ("10 Jul 2026 15:40 UTC") — no locale dependence. */
97
128
  export function formatWorkflowStatusChangeTimestamp(at) {
98
129
  const date = new Date(at);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oxygen-agent/cli",
3
- "version": "1.1041.21",
3
+ "version": "1.1042.29",
4
4
  "private": false,
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",