@oxygen-agent/cli 1.1014.1763 → 1.1014.1874

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.1014.1763
37
+ Version: 1.1014.1874
@@ -329,7 +329,7 @@ function renderProvider(row, now, binary, allowSpendHalt = true) {
329
329
  : traffic.instrumented === false
330
330
  ? `7d ${count(traffic.calls)} calls (NOT instrumented — this provider spent money but wrote no request ledger rows)`
331
331
  : `7d ${count(traffic.calls)} calls · ${count(traffic.failures)} fail · ${count(traffic.not_found)} no-match(404) · ` +
332
- `${count(traffic.vendor_rate_limited)} vendor-429 · ${count(traffic.self_paced_blocks)} self-paced · ` +
332
+ `${count(traffic.vendor_rate_limited)} vendor-429${(num(traffic.vendor_rate_limited_upstream) ?? 0) > 0 ? ` (${count(traffic.vendor_rate_limited_upstream)} upstream)` : ""} · ${count(traffic.self_paced_blocks)} self-paced · ` +
333
333
  `${count(traffic.payment_failures)} 402 · ${count(traffic.credit_refusals)} credit-refused · ` +
334
334
  `${count(traffic.workspaces)} ws · p95 ${num(traffic.duration_p95_ms) === null ? "—" : `${count(traffic.duration_p95_ms)} ms`} · ` +
335
335
  `${count(traffic.credits_estimate)} cr (${scope.replace(/_/g, " ")})`;
@@ -337,6 +337,8 @@ function renderProvider(row, now, binary, allowSpendHalt = true) {
337
337
  lines.push(` ${balancePhrase(obj(row.balance), now)} | ${costPhrase(cost)}`);
338
338
  const policies = arr(limits.rate_policies).map((policy) => obj(policy)).filter((p) => p !== null);
339
339
  const firstPolicy = policies[0];
340
+ // Older servers omit the key; an absent list renders nothing.
341
+ const unpacedRoutes = arr(limits.unpaced_routes).map((route) => obj(route)).filter((r) => r !== null);
340
342
  const ceilings = arr(limits.ceilings).map((ceiling) => obj(ceiling)).filter((c) => c !== null);
341
343
  const worstCeiling = [...ceilings].sort((a, b) => (num(b.utilization) ?? -1) - (num(a.utilization) ?? -1))[0];
342
344
  const breaker = obj(limits.breaker);
@@ -345,7 +347,10 @@ function renderProvider(row, now, binary, allowSpendHalt = true) {
345
347
  `${num(firstPolicy.max_in_flight) === null ? "" : ` · ${count(firstPolicy.max_in_flight)} in flight`}` +
346
348
  ` · ${firstPolicy.window_expired === true ? "idle" : `${count(firstPolicy.current)} this window`}` +
347
349
  `${(num(firstPolicy.rate_limited_hits_24h) ?? 0) > 0 ? ` · ${count(firstPolicy.rate_limited_hits_24h)} 429s/24h` : ""}` +
348
- `${policies.length > 1 ? ` · +${policies.length - 1} more` : ""}`
350
+ `${policies.length > 1 ? ` · +${policies.length - 1} more` : ""}` +
351
+ unpacedRoutes.map((route) => ` · ${arr(route.operations).map(String).join(", ")} ${num(route.limit) !== null
352
+ ? `capped ${count(route.limit)}/s (rollback)`
353
+ : route.rollback_cap_state === "invalid" ? "unlimited (rollback cap invalid)" : "unlimited"}`).join("")
349
354
  : "NONE — unpaced"} | ceiling ${worstCeiling
350
355
  ? `${pct(worstCeiling.utilization)} of ${ceilingLimit(worstCeiling)} (${str(worstCeiling.action) ?? "?"})${ceilings.length > 1 ? ` · +${ceilings.length - 1} more` : ""}`
351
356
  : "none (global + category only)"} | breaker ${str(breaker?.manual_override) ?? str(breaker?.state) ?? "closed"}`);
@@ -1,3 +1,4 @@
1
+ import { MAX_TABLE_ACTION_RUN_MAX_CONCURRENCY } from "@oxygen/shared/table-limits";
1
2
  import { emitCliFailure, emitSuccess } from "../../cli-output.js";
2
3
  import { readPositiveInt } from "../../cli-values.js";
3
4
  import { requestOxygen } from "../../http-client.js";
@@ -131,7 +132,7 @@ export function registerRelations({ tablesCommand, handleAsyncAction }) {
131
132
  .option("--on <column>", "Pin one table's column by name or key. Oxygen must still find a compatible column on the other table: generic text needs a strongly similar label, while domains, emails, LinkedIn URLs, and external IDs pair by semantic role.")
132
133
  .option("--approved", "Queue the bulk link after inspecting the preview; then wait with `oxygen table-runs wait <run_id>`.")
133
134
  .option("--create-missing", "Also create target rows for unmatched source keys (CRM records when filling an existing CRM relationship). Free.")
134
- .option("--max-concurrency <n>", "Maximum concurrent row items for the run (1-1000; a ceiling shared with worker and provider capacity). Defaults to 250; native --create-missing runs serialize target-row creation safely.")
135
+ .option("--max-concurrency <n>", `Maximum concurrent row items for the run (1-${MAX_TABLE_ACTION_RUN_MAX_CONCURRENCY}; a ceiling shared with worker and provider capacity). Defaults to 250; native --create-missing runs serialize target-row creation safely.`)
135
136
  .option("--undo <run_id>", "Undo a previous link run, archiving only the links that run created.")
136
137
  .option("--relation <slug>", "Row form: relation slug defined on the source table, such as client.")
137
138
  .option("--target-row-id <row_id>", "Row form: target row id in the related table.")
@@ -218,7 +219,7 @@ export function registerRelations({ tablesCommand, handleAsyncAction }) {
218
219
  .option("--row-id <id...>", "Promote only these row ids. Defaults to every bound row.")
219
220
  .option("--dry-run", "Preview per-field would_fill/would_overwrite/conflicts without writing (the default when --approved is absent).")
220
221
  .option("--approved", "Confirm the truth write onto CRM records after inspecting the preview.")
221
- .option("--max-concurrency <n>", "Maximum concurrent row items for the run (1-1000; a ceiling shared with worker and provider capacity). Defaults to 50.")
222
+ .option("--max-concurrency <n>", `Maximum concurrent row items for the run (1-${MAX_TABLE_ACTION_RUN_MAX_CONCURRENCY}; a ceiling shared with worker and provider capacity). Defaults to 50.`)
222
223
  .option("--json", "Print a JSON envelope.")
223
224
  .action(async (table, options) => {
224
225
  if (options.dryRun && options.approved) {
@@ -1,3 +1,4 @@
1
+ import { MAX_TABLE_ACTION_RUN_MAX_CONCURRENCY } from "@oxygen/shared/table-limits";
1
2
  import { parseKeyValuePairs, parseJsonObject, readNonNegativeInt, readPositiveInt, readRecordString } from "../cli-values.js";
2
3
  import { readColumnDecisionFlags } from "../column-decision-options.js";
3
4
  import { formatAiPromptPreviewNotice, formatColumnReferenceNotices, formatEnrichmentInputMappingNotice } from "../column-run-notices.js";
@@ -1150,7 +1151,7 @@ export function registerColumnsFamily(program, handleAsyncAction) {
1150
1151
  .option("--approved", "Confirm a paid durable run, or a bind create-mode run (onNoMatch=create), after inspecting a dry run or preview.")
1151
1152
  .option("--approved-effect-unknown", "With --row-id, allow rerunning a cell whose previous external write was dispatched but never confirmed. Verify the destination first: this can apply the same external effect twice.")
1152
1153
  .option("--max-credits <n>", "Maximum OXYGEN credits for this run, including managed calls, web grounding and own-key provider platform fees. Vendor charges on your own key are outside this ceiling. BYOK model inference is free; managed grounding still counts.")
1153
- .option("--max-concurrency <n>", "Maximum concurrent row items for a background run (1-1000; a ceiling shared with worker and provider capacity). Defaults to 250 for AI columns and 50 otherwise (160 for Firecrawl scrape columns).")
1154
+ .option("--max-concurrency <n>", `Maximum concurrent row items for a background run (1-${MAX_TABLE_ACTION_RUN_MAX_CONCURRENCY}; a ceiling shared with worker and provider capacity). Defaults to 250 for AI columns and 50 otherwise (160 for Firecrawl scrape columns).`)
1154
1155
  .option("--local", "Run a custom HTTP column in this CLI process, where {env:...} secrets read your own machine's environment. Without it the column runs in the background on Oxygen and the same reference resolves from this workspace's registered custom integration.")
1155
1156
  .option("--local-concurrency <n>", "Maximum concurrent custom HTTP requests for --local. Defaults to 3.")
1156
1157
  .option("--dry-run", "Preview the model tier, credit estimate, run-condition posture, and — for an AI column — the prompt rendered with one real row's values, without spending any credits.")
@@ -1,3 +1,4 @@
1
+ import { MAX_TABLE_ACTION_RUN_MAX_CONCURRENCY } from "@oxygen/shared/table-limits";
1
2
  import { readJsonObjectOption, readPositiveInt } from "../cli-values.js";
2
3
  import { readCsvOption, readFilterSelectionOption, readPositiveNumber } from "../command-support.js";
3
4
  import { requestOxygen } from "../http-client.js";
@@ -130,7 +131,7 @@ export function registerEnrichColumnFamily(program, handleAsyncAction) {
130
131
  .option("--selection-json <json>", "Full row selection object for server-side row selection.")
131
132
  .option("--only-missing", "Queue rows missing the capability's normalized output when no explicit selection is passed.")
132
133
  .option("--force", "Re-run rows with an existing target enrichment value.")
133
- .option("--max-concurrency <n>", "Maximum concurrent row items for this enrichment run (1-1000; a ceiling shared with worker and provider capacity). Defaults to 20.")
134
+ .option("--max-concurrency <n>", `Maximum concurrent row items for this enrichment run (1-${MAX_TABLE_ACTION_RUN_MAX_CONCURRENCY}; a ceiling shared with worker and provider capacity). Defaults to 20.`)
134
135
  .option("--json", "Print a JSON envelope.")
135
136
  .option("--approved", "Approve THIS run after inspecting `enrich-column preview` (free). Paid enrichment runs fail with approval_required (exit 7) without it.")
136
137
  .action(async (table, options) => {
@@ -117,7 +117,7 @@ export function registerManagedInboxesFamily(program, handleAsyncAction) {
117
117
  .description("Buy managed monthly inboxes on a new domain or your existing Cloudflare domain. Use --existing-domain for Cloudflare: the read-only preview shows ownership, occupancy, DNS scope and blockers, with zero registration charge. --max-per-domain saves a stricter limit with the approved order, including existing addresses; later additions honor it. Preview does not save the limit or change workspace data. WITHOUT --approved this prints a priced PREVIEW with a quote_id (nothing ordered, nothing charged); re-run with --approved --quote <id> to place the order. OXYGEN Warm-up defaults on for Google, Microsoft, and Azure when available: preview and approved responses carry `warmup_activation` with the exact `mailboxes` and `scope=warmup_only`; it is null when warmup is disabled or unavailable. For InboxKit, Google carries `transport=inboxkit_managed_google_handoff`; Microsoft/Azure carries `transport=inboxkit_sequencer_export`. Both carry `mailbox_credentials_required=false` and `native_send_oauth_separate=true`, so managed warm-up needs no customer-supplied OAuth or mailbox password. Google retrieves the existing managed credential only during activation and never persists or returns it; Microsoft/Azure uses native export. Native sending authorization is separate and may still be required before OXYGEN can send. Verify each exact address with `mailboxes oauth-health --json`; InboxKit's unattended Google domain approval usually lands within minutes and the worker keeps retrying, so a waiting row is not a reason to ask the customer to sign in. This order authorizes automatic OXYGEN Warm-up activation after provisioning, so no second `mailboxes warmup enable` approval is needed. The preview shows the price in force: from the 2026-09 repricing date a Google Workspace or Microsoft 365 inbox is one flat mailbox line plus the 100-credit mailbox connection, warm-up included, which `connection_monthly_credits` shows and your balance reserves once the inbox connects (400 credits a month all-in at the committed price), and an Azure/Entra tenant is one flat hosting charge for its domain (4,000 credits/$40 a month) plus each inbox's 25-credit ($0.25) Sequencer connection with warm-up included: 6,500 credits/$65 monthly for 100 inboxes; `managed-inboxes list --json` reports the prices in force under `prices`. Domains are priced from the vendor's LIVE domain price, and any price below vendor cost is refused. A domain you bought on its own through Oxygen (`domains buy`) takes its first inboxes here too: the preview says `domain_source: owned`, nothing is registered again and `one_off_credits` is 0 (Google, Microsoft or Azure; omit --years). To add mailboxes to a domain that already has inboxes use `managed-inboxes add-inboxes`.")
118
118
  .argument("[domain]", "Sending domain to register + host the mailboxes (e.g. send.acme.com), or one you already bought through Oxygen. May also be passed as --domain.")
119
119
  .option("--domain <domain>", "Sending domain (alternative to the positional argument).")
120
- .requiredOption("--provider <provider>", "Mailbox PLATFORM: google, microsoft, or azure. (google/microsoft cap at 5 mailboxes per domain; azure allows 100.)")
120
+ .option("--provider <provider>", "Mailbox PLATFORM: google, microsoft, or azure. (google/microsoft cap at 5 mailboxes per domain; azure allows 100.) Required unless --connect-only.")
121
121
  .option("--vendor <vendor>", "Pin the vendor: inboxkit. Omit to let OXYGEN choose. A named vendor with no credential FAILS rather than falling back to another.")
122
122
  .option("--sender <id>", "Sender profile id (from `oxygen senders profiles list`) that OWNS every mailbox in this order: its first name, last name, and profile picture are stamped on each one, so you never retype them. A sender profile is one person's sending identity — their LinkedIn/WhatsApp accounts and email inboxes under one name and photo. One sender can own several natural addresses on the same domain (see --locals); do not invent people or pad a requested count with numbered aliases. Any first_name/last_name/profile_picture_url in --mailboxes/--file is dropped for the sender's own values.")
123
123
  .option("--locals <list>", "Natural local parts for the real sender; avoid numbered suffixes unless explicitly requested, e.g. `--locals talia,talia.rosen,t.rosen` on send.acme.com orders talia@, talia.rosen@, and t.rosen@ — all owned by that one person. Requires --sender, because a bare local part carries no name and the vendor's stamp is permanent.")
@@ -129,6 +129,9 @@ export function registerManagedInboxesFamily(program, handleAsyncAction) {
129
129
  .option("--dns-cleanup-records <ids>", "Optional standalone cleanup: preview deletion of these comma-separated email DNS record IDs; buys nothing. An approved existing-domain order already removes the records its preview lists.")
130
130
  .addOption(new Option("--dns-cleanup-approved", "Delete only the reviewed email records without buying; requires --dns-cleanup-records and --dns-cleanup-hash. Request a fresh purchase quote afterward.").conflicts("approved"))
131
131
  .option("--dns-cleanup-hash <hash>", "The plan_hash from the exact DNS cleanup preview, required to delete records.")
132
+ .addOption(new Option("--connect-only", "With --existing-domain: connect the domain to your existing inbox-provider workspace WITHOUT buying mailboxes, for 0 credits. Without --connect-approved it is a read-only preview listing the email DNS records approval removes and a signature.").conflicts(["approved", "dnsCleanupRecords"]))
133
+ .option("--connect-approved", "Apply the reviewed connect-only preview: remove exactly its listed email DNS records and connect the domain with no mailboxes. Requires --connect-only and --connect-signature.")
134
+ .option("--connect-signature <signature>", "The signature from the exact connect-only preview, required with --connect-approved.")
132
135
  .option("--years <n>", "Years to register a new domain for (1-10). Omit for existing domains.")
133
136
  .option("--redirect-url <url>", "Where the domain's web root redirects. Defaults to your workspace's company website; editable later with `oxygen domains forwarding set`.")
134
137
  .option("--billing <path>", "Path to a JSON file with the registrant/WHOIS contact (first_name, last_name, phone, country, city, state, address_line_one, postal_code). Required on your FIRST order; later orders reuse the registrant already on file.")
@@ -146,6 +149,28 @@ export function registerManagedInboxesFamily(program, handleAsyncAction) {
146
149
  const provider = readOption(options.provider);
147
150
  if (!domain)
148
151
  throw new Error("--domain is required.");
152
+ const connectSignature = readOption(options.connectSignature);
153
+ if ((options.connectApproved || connectSignature) && !options.connectOnly) {
154
+ throw new OxygenError("invalid_request", "--connect-approved and --connect-signature require --connect-only.", { exitCode: 2 });
155
+ }
156
+ if (options.connectOnly) {
157
+ if (!options.existingDomain || (options.connectApproved && !connectSignature)) {
158
+ throw new OxygenError("invalid_request", "--connect-only requires --existing-domain; --connect-approved also requires the preview's --connect-signature.", { exitCode: 2 });
159
+ }
160
+ const vendor = readOption(options.vendor);
161
+ return requestOxygen("/api/cli/managed-inboxes/subscribe", {
162
+ method: "POST",
163
+ body: {
164
+ domain,
165
+ existing_domain: true,
166
+ ...(vendor ? { vendor } : {}),
167
+ connect_only: {
168
+ approved: options.connectApproved === true,
169
+ ...(connectSignature ? { signature: connectSignature } : {}),
170
+ },
171
+ },
172
+ });
173
+ }
149
174
  if (!provider)
150
175
  throw new Error("--provider is required (google, microsoft, or azure).");
151
176
  // No --count/--prefix here, deliberately: that shorthand can only
@@ -1,3 +1,4 @@
1
+ import { MAX_TABLE_ACTION_RUN_MAX_CONCURRENCY } from "@oxygen/shared/table-limits";
1
2
  import { parseJsonObject, readPositiveInt } from "../cli-values.js";
2
3
  import { formatRows, normalizeExportRowsFormat, parseJsonArray, readCsvOption, readFilterSelectionOption, readFormulaValuesOption, readPositiveNumber, tableRunsListPath, waitForTableActionRun } from "../command-support.js";
3
4
  import { requestOxygen } from "../http-client.js";
@@ -117,7 +118,7 @@ export function registerTableRunsFamily(program, handleAsyncAction) {
117
118
  .option("--connection-id <connection_id>", "Optional provider integration connection id.")
118
119
  .option("--approved", "Confirm the paid table action run after inspecting a dry run or preview.")
119
120
  .option("--max-credits <n>", "Maximum OXYGEN credits for this run, including managed calls and own-key provider platform fees. Vendor charges on your own key are outside this ceiling.")
120
- .option("--max-concurrency <n>", "Maximum concurrent row items for this run (1-1000; a ceiling shared with worker and provider capacity). Defaults to 50 (160 for Firecrawl scrape columns).")
121
+ .option("--max-concurrency <n>", `Maximum concurrent row items for this run (1-${MAX_TABLE_ACTION_RUN_MAX_CONCURRENCY}; a ceiling shared with worker and provider capacity). Defaults to 50 (160 for Firecrawl scrape columns).`)
121
122
  .option("--metadata-json <json>", "Optional metadata object to attach to the run.")
122
123
  .option("--idempotency-key <key>", "Reuse the same scoped run when retrying this exact request.")
123
124
  .option("--then-json <json>", "JSON array of sequential follow-up steps. Each step runs after the previous terminates with completed or completed_with_errors. Paid steps require selection and max_credits. Shape: [{actions:[{type:'tool_column',column}],selection,force,max_concurrency,max_credits,metadata,run_on_failure}].")
@@ -1,5 +1,5 @@
1
1
  import { randomUUID } from "node:crypto";
2
- import { mkdir, open, readFile, readdir, rename, stat, unlink, utimes } from "node:fs/promises";
2
+ import { mkdir, open, readFile, readdir, rename, stat, unlink, utimes, writeFile } from "node:fs/promises";
3
3
  import { join } from "node:path";
4
4
  import { DIAGNOSTIC_MAX_BYTES, diagnosticId } from "./diagnostics.js";
5
5
  import { acquireDiagnosticStorageLock } from "./diagnostic-storage-lock.js";
@@ -8,6 +8,10 @@ import { log } from "./log.js";
8
8
  import { recordTelemetryCounter } from "./telemetry.js";
9
9
  const admissions = new Map();
10
10
  const RECEIPT_MAX_BYTES = 512;
11
+ /** A full scan bounds ledger drift (a crashed owner, a pre-ledger writer) and enforces expiry. */
12
+ const LEDGER_MAX_AGE_MS = 15_000;
13
+ /** This process's last full listing supplies retry candidates between scans. */
14
+ const inspections = new Map();
11
15
  /** Admit durable content plus bounded receipt bytes; acknowledge only after publication. */
12
16
  export async function admitDiagnosticSpool(directory, record, compressed) {
13
17
  await storageStage("mkdir", () => mkdir(directory, { recursive: true, mode: 0o700 }));
@@ -52,6 +56,7 @@ async function drainAdmissions(directory, queue) {
52
56
  while (queue.pending.length) {
53
57
  const batch = queue.pending.splice(0, 32);
54
58
  let release = null;
59
+ let published;
55
60
  try {
56
61
  // Bound actual cross-process contention, not local queue/inspection time (#5810).
57
62
  release = await storageStage("lock", () => acquireDiagnosticStorageLock(join(directory, ".admission.lock"), 5_000));
@@ -60,25 +65,47 @@ async function drainAdmissions(directory, queue) {
60
65
  const started = performance.now();
61
66
  const reservedOnly = batch.every(admission => admission.progress && admission.reservation);
62
67
  let files = queue.files ?? [];
68
+ let scanned = false;
63
69
  if (!reservedOnly) {
64
- const inspected = await storageStage("inspect", () => inspectDiagnosticSpool(directory));
65
- queue.used = inspected.used;
66
- queue.files = files = inspected.files;
70
+ // A fresh shared ledger stands in for the full scan, which held this
71
+ // cross-process mutex ~1 s per batch at 24k retained files (2026-10-23).
72
+ const ledger = await readAdmissionLedger(directory, batch.reduce((sum, admission) => sum + admissionBytes(admission), 0));
73
+ if (ledger) {
74
+ queue.used = ledger.used;
75
+ queue.scannedAt = ledger.scanned_at;
76
+ queue.files = files = ledger.files;
77
+ }
78
+ else {
79
+ const inspected = await storageStage("inspect", () => inspectDiagnosticSpool(directory));
80
+ queue.used = inspected.used;
81
+ queue.files = files = inspected.files;
82
+ queue.scannedAt = Date.now();
83
+ scanned = true;
84
+ }
67
85
  }
68
86
  const scanMs = performance.now() - started;
69
87
  // Captures arriving during inspection share its protected byte count,
70
88
  // avoiding another scan while keeping the 32-record batch bound.
71
- if (!reservedOnly)
89
+ if (scanned)
72
90
  batch.push(...queue.pending.splice(0, 32 - batch.length));
91
+ const refused = new Set();
92
+ for (const admission of batch) {
93
+ const required = admissionBytes(admission);
94
+ if (required && (queue.used === undefined || queue.used + required > DIAGNOSTIC_MAX_BYTES)) {
95
+ refused.add(admission);
96
+ continue;
97
+ }
98
+ // Reserve conservatively even if cleanup of a failed partial write fails.
99
+ if (queue.used !== undefined)
100
+ queue.used += required;
101
+ }
102
+ // Publish before writing: a crash mid-batch leaves the ledger above the spool, never below.
103
+ if (queue.used !== undefined && queue.scannedAt !== undefined)
104
+ await writeAdmissionLedger(directory, published = queue.used, queue.scannedAt);
73
105
  for (const admission of batch) {
74
106
  try {
75
- // Include an upload receipt and its atomic replacement in admission.
76
- const required = admission.reservation ? 0 : admission.progress ? RECEIPT_MAX_BYTES : admission.encoded.compressed.length + 2 * RECEIPT_MAX_BYTES;
77
- if (required && (queue.used === undefined || queue.used + required > DIAGNOSTIC_MAX_BYTES))
107
+ if (refused.has(admission))
78
108
  throw new StorageFailure("capacity", { code: "spool_full" });
79
- // Reserve conservatively even if cleanup of a failed partial write fails.
80
- if (queue.used !== undefined)
81
- queue.used += required;
82
109
  if (admission.progress) {
83
110
  await writeUploadProgress(directory, admission.record, admission.progress, admission.reservation);
84
111
  admission.resolve(join(directory, `${admission.record.id}.receipt.json`));
@@ -90,17 +117,23 @@ async function drainAdmissions(directory, queue) {
90
117
  admission.reject(error);
91
118
  }
92
119
  }
93
- if (!reservedOnly)
120
+ // Ledger batches are about one per capture; log them only when they waited.
121
+ const waitMs = performance.now() - batch[0].enqueuedAt;
122
+ if (!reservedOnly && (scanned || waitMs >= 1_000))
94
123
  log("info", "diagnostics.spool_admitted", { queue_role: diagnosticRole(), batch_records: batch.length, spool_files: files.length,
95
- spool_bytes: queue.used, scan_ms: scanMs, admission_wait_ms: performance.now() - batch[0].enqueuedAt });
124
+ spool_bytes: queue.used, scan_ms: scanMs, admission_wait_ms: waitMs, inspection: scanned ? "scan" : "ledger" });
96
125
  }
97
126
  catch (error) {
98
127
  for (const admission of batch)
99
128
  admission.reject(error);
100
129
  }
101
130
  finally {
131
+ const used = queue.used;
102
132
  delete queue.used;
103
133
  await Promise.allSettled([...queue.progressWrites]);
134
+ // Receipts reserved beside the batch are published before the mutex is released.
135
+ if (used !== undefined && used !== published && queue.scannedAt !== undefined)
136
+ await writeAdmissionLedger(directory, used, queue.scannedAt);
104
137
  await release?.();
105
138
  }
106
139
  }
@@ -113,6 +146,43 @@ async function drainAdmissions(directory, queue) {
113
146
  admissions.delete(directory);
114
147
  }
115
148
  }
149
+ /** Include an upload receipt and its atomic replacement in admission. */
150
+ function admissionBytes(admission) {
151
+ return admission.reservation ? 0 : admission.progress ? RECEIPT_MAX_BYTES : admission.encoded.compressed.length + 2 * RECEIPT_MAX_BYTES;
152
+ }
153
+ /**
154
+ * Caller owns the admission mutex. Every ledger-aware owner publishes its
155
+ * reservations before writing them, and unlinks outside the mutex only shrink
156
+ * the spool, so the ledger never undercounts those owners. It replaces a scan
157
+ * only while recent and within half the budget, so a pre-ledger writer during
158
+ * a rollout cannot carry the spool past its limit unseen.
159
+ */
160
+ async function readAdmissionLedger(directory, required) {
161
+ const local = inspections.get(directory);
162
+ if (!local || Date.now() - local.at >= 4 * LEDGER_MAX_AGE_MS)
163
+ return null;
164
+ try {
165
+ const value = JSON.parse(await readFile(join(directory, ".admission.ledger"), "utf8"));
166
+ const age = Date.now() - value.scanned_at;
167
+ if (!Number.isSafeInteger(value.used) || value.used < 0 || !(age >= 0 && age < LEDGER_MAX_AGE_MS))
168
+ return null;
169
+ return value.used + required <= DIAGNOSTIC_MAX_BYTES / 2 ? { used: value.used, scanned_at: value.scanned_at, files: local.files } : null;
170
+ }
171
+ catch {
172
+ return null;
173
+ }
174
+ }
175
+ /** Only the admission mutex owner reads or writes; a torn write parses as absent and forces a scan. */
176
+ async function writeAdmissionLedger(directory, used, scannedAt) {
177
+ const path = join(directory, ".admission.ledger");
178
+ try {
179
+ await writeFile(path, JSON.stringify({ used, scanned_at: scannedAt }), { mode: 0o600 });
180
+ }
181
+ catch {
182
+ // A ledger that may now undercount must not admit; the next owner scans.
183
+ await unlink(path).catch(() => undefined);
184
+ }
185
+ }
116
186
  async function writeDiagnosticSpool(directory, id, compressed) {
117
187
  const path = join(directory, `${id}.json.gz`);
118
188
  const temporary = join(directory, `${id}.${randomUUID()}.tmp`);
@@ -305,8 +375,12 @@ export async function retryDiagnosticSpool(directory, storeFingerprint, upload)
305
375
  if (!admission)
306
376
  return;
307
377
  try {
378
+ const scannedAt = Date.now();
308
379
  const inspected = await storageStage("inspect", () => inspectDiagnosticSpool(directory));
309
380
  ({ files, reservation } = await reserveRetryBatch(directory, inspected.files.slice(0, 20), inspected.used));
381
+ // Unreserved, any existing ledger still covers the spool; skip the extra mutex hold.
382
+ if (reservation)
383
+ await writeAdmissionLedger(directory, inspected.used + files.length * 2 * RECEIPT_MAX_BYTES, scannedAt);
310
384
  }
311
385
  finally {
312
386
  await admission();
@@ -374,5 +448,7 @@ async function inspectDiagnosticSpool(directory) {
374
448
  }
375
449
  }
376
450
  }
377
- return { used, files: retained.sort((a, b) => a.mtimeMs - b.mtimeMs || a.name.localeCompare(b.name)).map(file => file.name) };
451
+ const files = retained.sort((a, b) => a.mtimeMs - b.mtimeMs || a.name.localeCompare(b.name)).map(file => file.name);
452
+ inspections.set(directory, { files, at: Date.now() });
453
+ return { used, files };
378
454
  }
@@ -64,5 +64,9 @@ export function assertExternalWritesAllowed(action, env = process.env) {
64
64
  if (resolveExternalWritePolicy(env) !== "deny")
65
65
  return;
66
66
  log("warn", "external_writes.denied", { action });
67
- throw new OxygenError(EXTERNAL_WRITES_DENIED_CODE, `External writes are denied in this environment (${EXTERNAL_WRITES_ENV_VAR}=deny), so "${action}" cannot run.`, { details: { action, env_var: EXTERNAL_WRITES_ENV_VAR } });
67
+ throw new OxygenError(EXTERNAL_WRITES_DENIED_CODE, `External writes are denied in this environment (${EXTERNAL_WRITES_ENV_VAR}=deny), so "${action}" cannot run.`,
68
+ // Thrown before any client exists, so it is proof that nothing was sent:
69
+ // the worker settles the item as not_applied and releases its credit hold
70
+ // instead of fencing a retry as an effect of unknown outcome.
71
+ { details: { action, env_var: EXTERNAL_WRITES_ENV_VAR, effect_outcome: "not_applied", provider_call: false } });
68
72
  }
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Group commit for independent, append-only ledger rows.
3
+ *
4
+ * Every caller still awaits its own durable write: its promise settles only
5
+ * after the statement that carried its row acknowledged. Rows that arrive
6
+ * while earlier writes are in flight share the next statement, so an idle
7
+ * process adds one microtask and a loaded one writes up to `maxBatch`
8
+ * rows per round trip instead of one.
9
+ *
10
+ * A failed batch may already be durable (its COMMIT reply can be lost), so
11
+ * both repair writes must be idempotent. A data-class refusal (SQLSTATE 22xxx
12
+ * or 23xxx) names one bad row: the batch is split and its rows are written
13
+ * alone, at most `maxInFlight` at a time, so only the bad row's caller fails.
14
+ * Any other failure is presumed transient and the whole batch is retried once
15
+ * through `retryBatch`; only a data-class refusal of that retry splits it.
16
+ * Above `maxPending` queued rows callers write directly, so a stalled database
17
+ * cannot grow this queue.
18
+ */
19
+ export type GroupCommitWriter<T> = {
20
+ writeOne: (row: T) => Promise<void>;
21
+ writeBatch: (rows: readonly T[]) => Promise<void>;
22
+ /** Idempotent whole-batch retry (e.g. ON CONFLICT DO NOTHING). */
23
+ retryBatch: (rows: readonly T[]) => Promise<void>;
24
+ /** Idempotent single-row write used after a data-class refusal. */
25
+ repairOne: (row: T) => Promise<void>;
26
+ };
27
+ /** SQLSTATE classes 22 (data exception) and 23 (integrity constraint violation). */
28
+ export declare function isRowDataSqlError(error: unknown): boolean;
29
+ export type GroupCommitOptions = {
30
+ maxBatch?: number;
31
+ maxPending?: number;
32
+ maxInFlight?: number;
33
+ };
34
+ export declare function createGroupCommitQueue<T>(writer: GroupCommitWriter<T>, options?: GroupCommitOptions): (row: T) => Promise<void>;
@@ -0,0 +1,103 @@
1
+ import { sqlErrorFields } from "./sql-error.js";
2
+ /** SQLSTATE classes 22 (data exception) and 23 (integrity constraint violation). */
3
+ export function isRowDataSqlError(error) {
4
+ const code = sqlErrorFields(error).sql_error_pg_code;
5
+ return typeof code === "string" && /^2[23]/.test(code);
6
+ }
7
+ export function createGroupCommitQueue(writer, options = {}) {
8
+ const maxBatch = options.maxBatch ?? 64;
9
+ const maxPending = options.maxPending ?? 1024;
10
+ const maxInFlight = options.maxInFlight ?? 2;
11
+ let queue = [];
12
+ let pending = 0;
13
+ let inFlight = 0;
14
+ let scheduled = false;
15
+ async function repairRows(rows) {
16
+ let next = 0;
17
+ const worker = async () => {
18
+ while (next < rows.length) {
19
+ const entry = rows[next++];
20
+ try {
21
+ await writer.repairOne(entry.row);
22
+ entry.resolve();
23
+ }
24
+ catch (error) {
25
+ entry.reject(error);
26
+ }
27
+ }
28
+ };
29
+ await Promise.all(Array.from({ length: Math.min(maxInFlight, rows.length) }, worker));
30
+ }
31
+ async function settle(rows) {
32
+ if (rows.length === 1) {
33
+ const only = rows[0];
34
+ try {
35
+ await writer.writeOne(only.row);
36
+ only.resolve();
37
+ }
38
+ catch (error) {
39
+ only.reject(error);
40
+ }
41
+ return;
42
+ }
43
+ const batch = rows.map((entry) => entry.row);
44
+ let failure;
45
+ try {
46
+ await writer.writeBatch(batch);
47
+ for (const entry of rows)
48
+ entry.resolve();
49
+ return;
50
+ }
51
+ catch (error) {
52
+ failure = error;
53
+ }
54
+ if (!isRowDataSqlError(failure)) {
55
+ try {
56
+ await writer.retryBatch(batch);
57
+ for (const entry of rows)
58
+ entry.resolve();
59
+ return;
60
+ }
61
+ catch (error) {
62
+ failure = error;
63
+ }
64
+ }
65
+ if (isRowDataSqlError(failure)) {
66
+ await repairRows(rows);
67
+ return;
68
+ }
69
+ for (const entry of rows)
70
+ entry.reject(failure);
71
+ }
72
+ function drain() {
73
+ scheduled = false;
74
+ while (inFlight < maxInFlight && queue.length > 0) {
75
+ const rows = queue.length <= maxBatch ? queue : queue.slice(0, maxBatch);
76
+ queue = queue.length <= maxBatch ? [] : queue.slice(maxBatch);
77
+ inFlight += 1;
78
+ void settle(rows).finally(() => {
79
+ inFlight -= 1;
80
+ pending -= rows.length;
81
+ schedule();
82
+ });
83
+ }
84
+ }
85
+ function schedule() {
86
+ if (scheduled || inFlight >= maxInFlight || queue.length === 0)
87
+ return;
88
+ scheduled = true;
89
+ // A microtask, not a timer: fake-timer harnesses never stall a durable
90
+ // write, and rows queued while statements are in flight still share the
91
+ // next one.
92
+ queueMicrotask(drain);
93
+ }
94
+ return (row) => {
95
+ if (pending >= maxPending)
96
+ return writer.writeOne(row);
97
+ pending += 1;
98
+ return new Promise((resolve, reject) => {
99
+ queue.push({ row, resolve, reject });
100
+ schedule();
101
+ });
102
+ };
103
+ }
@@ -0,0 +1,2 @@
1
+ /** True when a lowercase bare host is a listing platform (or its subdomain) or a freemail host. */
2
+ export declare function isListedWebsitePlatform(host: string): boolean;
@@ -0,0 +1,26 @@
1
+ import { isFreemailDomain } from "./freemail-domains.js";
2
+ /**
3
+ * Hosts that list a company without being its website: social profiles, link-in-bio
4
+ * pages, shorteners, maps, calendars, chat links, code hosts, marketplaces, and
5
+ * company directories and review sites (an encyclopedia entry, an employer-review
6
+ * page, a B2B database profile). A
7
+ * company page whose "website" is one of these has no site of its own, and reading
8
+ * it would research the platform (`site:facebook.com`) and write the platform's domain
9
+ * into the company profile. A tenant subdomain of a site builder (`acme.wixsite.com`,
10
+ * `acme.github.io`) is the company's own site, so builders are deliberately absent.
11
+ */
12
+ const LISTED_WEBSITE_PLATFORM_HOSTS = [
13
+ "linkedin.com", "lnkd.in", "facebook.com", "fb.com", "fb.me", "instagram.com", "twitter.com", "x.com",
14
+ "threads.net", "tiktok.com", "youtube.com", "youtu.be", "pinterest.com", "snapchat.com", "reddit.com",
15
+ "medium.com", "linktr.ee", "linktree.com", "beacons.ai", "bio.link", "lnk.bio", "taplink.cc",
16
+ "campsite.bio", "bit.ly", "t.co", "tinyurl.com", "goo.gl", "g.page", "ow.ly", "buff.ly", "rebrand.ly",
17
+ "google.com", "calendly.com", "cal.com", "wa.me", "whatsapp.com", "t.me", "telegram.me", "discord.gg",
18
+ "discord.com", "github.com", "gitlab.com", "crunchbase.com", "wellfound.com", "angel.co", "yelp.com",
19
+ "tripadvisor.com", "amazon.com", "etsy.com", "ebay.com",
20
+ "wikipedia.org", "glassdoor.com", "zoominfo.com", "g2.com",
21
+ ];
22
+ /** True when a lowercase bare host is a listing platform (or its subdomain) or a freemail host. */
23
+ export function isListedWebsitePlatform(host) {
24
+ return LISTED_WEBSITE_PLATFORM_HOSTS.some((platform) => host === platform || host.endsWith(`.${platform}`))
25
+ || isFreemailDomain(host);
26
+ }
@@ -90,6 +90,13 @@ export const MANAGED_BALANCE_FLOORS = {
90
90
  // 2026-09-07: it has ranged 1,002 -> 670 over 30 days, so 150 is ~15% of the plan
91
91
  // and still several days of head-room.
92
92
  firecrawl: 150,
93
+ // 2026-10-22, first managed reads since May: Hunter Starter grants 2,000 credits a
94
+ // month (1,648.7 left, 351.3 used in the 11 days since the 2026-10-11 reset, ~32/day).
95
+ // The default would read low through the second half of every month; 250 is ~8 days
96
+ // of that burn. ZeroBounce is a prepaid 1,541-credit wallet with one managed call in
97
+ // 7 days; 100 still leaves days of head-room at any plausible verification burst.
98
+ hunter: 250,
99
+ zerobounce: 100,
93
100
  // Unit is REQUESTS, not credits, and the managed key has reported a null balance on
94
101
  // every row for 30 days (see `unknown` above). The floor is a guess until the
95
102
  // fetcher returns a number; it costs nothing while the balance stays unreadable.
@@ -6,8 +6,10 @@ export declare const MAX_WORKSPACE_ROW_DELETE_ROWS = 50000;
6
6
  export declare const MAX_ROW_LOOP_WRITE_ROWS = 500;
7
7
  /**
8
8
  * Maximum requested row concurrency for one table action run. Native BullMQ
9
- * persists at most this many slot heads. Actual execution also shares worker
10
- * slots, tenant admission and provider permits, so this is not an allocation
11
- * or a rows-per-second guarantee. Defaults stay unchanged.
9
+ * persists at most this many slot heads (tenant migration 0566 bounds
10
+ * worker_slot_count, slot and max_concurrency to match). Actual execution also
11
+ * shares worker slots, tenant admission (MAX_TENANT_IN_FLIGHT, also 4,000) and
12
+ * provider permits, so this is not an allocation or a rows-per-second
13
+ * guarantee. Defaults stay unchanged.
12
14
  */
13
- export declare const MAX_TABLE_ACTION_RUN_MAX_CONCURRENCY = 1000;
15
+ export declare const MAX_TABLE_ACTION_RUN_MAX_CONCURRENCY = 4000;
@@ -13,8 +13,10 @@ export const MAX_WORKSPACE_ROW_DELETE_ROWS = 50_000;
13
13
  export const MAX_ROW_LOOP_WRITE_ROWS = 500;
14
14
  /**
15
15
  * Maximum requested row concurrency for one table action run. Native BullMQ
16
- * persists at most this many slot heads. Actual execution also shares worker
17
- * slots, tenant admission and provider permits, so this is not an allocation
18
- * or a rows-per-second guarantee. Defaults stay unchanged.
16
+ * persists at most this many slot heads (tenant migration 0566 bounds
17
+ * worker_slot_count, slot and max_concurrency to match). Actual execution also
18
+ * shares worker slots, tenant admission (MAX_TENANT_IN_FLIGHT, also 4,000) and
19
+ * provider permits, so this is not an allocation or a rows-per-second
20
+ * guarantee. Defaults stay unchanged.
19
21
  */
20
- export const MAX_TABLE_ACTION_RUN_MAX_CONCURRENCY = 1000;
22
+ export const MAX_TABLE_ACTION_RUN_MAX_CONCURRENCY = 4000;
@@ -1 +1 @@
1
- export declare const OXYGEN_BUILD_VERSION = "1.1014.1763";
1
+ export declare const OXYGEN_BUILD_VERSION = "1.1014.1874";
@@ -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.1014.1763";
2
+ export const OXYGEN_BUILD_VERSION = "1.1014.1874";
@@ -116,6 +116,11 @@
116
116
  "import": "./dist/suppression-entries.js",
117
117
  "default": "./dist/suppression-entries.js"
118
118
  },
119
+ "./listed-website-platforms": {
120
+ "types": "./dist/listed-website-platforms.d.ts",
121
+ "import": "./dist/listed-website-platforms.js",
122
+ "default": "./dist/listed-website-platforms.js"
123
+ },
119
124
  "./dnc-identities": {
120
125
  "types": "./dist/dnc-identities.d.ts",
121
126
  "import": "./dist/dnc-identities.js",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oxygen-agent/cli",
3
- "version": "1.1014.1763",
3
+ "version": "1.1014.1874",
4
4
  "private": false,
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",