@oxygen-agent/cli 1.861.0 → 1.879.0

package/README.md

@@ -34,4 +34,4 @@ oxygen update
 
 For product documentation, visit https://oxygen-agent.com/docs. For support, visit https://oxygen-agent.com.
 
-Version: 1.861.0
+Version: 1.879.0

package/dist/column-run-notices.d.ts

@@ -9,3 +9,13 @@
  * live run, or a preview the server could not produce).
  */
 export declare function formatAiPromptPreviewNotice(data: unknown): string | null;
+/**
+ * Advisory reference findings from `columns add` / `update` / `rename`.
+ *
+ * An unresolvable reference is a hard rejection, so anything here is something
+ * the author should see but does not have to act on: an input the prompt never
+ * writes down (the value still reaches the model, but nothing links the two),
+ * a column named in prose and never read, or a rename that just orphaned a
+ * sibling's reference. Printed to stderr so `--json` piping stays clean.
+ */
+export declare function formatColumnReferenceNotices(data: unknown): string[];

package/dist/column-run-notices.js

@@ -35,3 +35,25 @@ export function formatAiPromptPreviewNotice(data) {
         shown,
     ].join("\n");
 }
+/**
+ * Advisory reference findings from `columns add` / `update` / `rename`.
+ *
+ * An unresolvable reference is a hard rejection, so anything here is something
+ * the author should see but does not have to act on: an input the prompt never
+ * writes down (the value still reaches the model, but nothing links the two),
+ * a column named in prose and never read, or a rename that just orphaned a
+ * sibling's reference. Printed to stderr so `--json` piping stays clean.
+ */
+export function formatColumnReferenceNotices(data) {
+    if (!isRecord(data) || !Array.isArray(data.reference_warnings))
+        return [];
+    const notices = [];
+    for (const entry of data.reference_warnings) {
+        if (!isRecord(entry))
+            continue;
+        const message = readRecordString(entry, "message");
+        if (message)
+            notices.push(`warning: ${message}`);
+    }
+    return notices;
+}

package/dist/command-manifest.js

@@ -32,6 +32,9 @@ const MUTATING_VERBS = new Set([
     // default (mutates:false) would advertise the most consequential write in the
     // activation play as a read.
     "autoenroll",
+    // Exact hyphenated leaf: EmailGuard auto-enrolment arms or revokes a standing
+    // recurring write, and --run can connect newly eligible mailboxes immediately.
+    "auto-enroll",
     "backfill",
     // Exact leaves, not the `billing` prefix — `orgs billing-owners` is a read.
     // Both move a workspace's billing owner, so an agent must treat them as writes.
@@ -84,6 +87,7 @@ const PREVIEW_BY_DEFAULT_COMMANDS = new Set([
     // audience and caps and writes nothing. Without this entry discovery would tell
     // an agent that previewing the play arms it, and the preview would go unrun.
     "linkedin intent autoenroll",
+    "mailboxes emailguard auto-enroll",
     "mailboxes delete",
     "support admin done",
     "support admin reply",

package/dist/index.js

@@ -21,7 +21,7 @@ import { ensureFreshCliForApiUrl, requestOxygen } from "./http-client.js";
 import { acquireMirrorLock, clearConflictFiles, deletePageFile, emptyMirrorState, findMirrorSlugByPageId, isFileDirty, listConflictFiles, listLocalMirrors, localPageSha256, markMirrorStale, mirrorExists, pageFilePath, planMirrorPush, purgeMirror, resetMirrorForFullResync, quarantineDirtyFile, readMirrorState, releaseMirrorLock, resolveDefaultConfigDir, resolveMirrorDir, writeGeneratedIndexFile, writeGeneratedLogFile, writeMirrorState, writePageFile, } from "./knowledge-mirror.js";
 import { waitForCliRun } from "./run-wait.js";
 import { assertModeFlagsExclusive, parseKeyValuePairs, parseJsonObject, readJsonObjectOption, readPositiveInt, readRecordString, resolveLiveDryRunMode, } from "./cli-values.js";
-import { formatAiPromptPreviewNotice } from "./column-run-notices.js";
+import { formatAiPromptPreviewNotice, formatColumnReferenceNotices, } from "./column-run-notices.js";
 import { runLocalCustomHttpColumn } from "./local-custom-http-column.js";
 import { captureCurrentTranscript, collectFeedbackEnvironment, TranscriptCaptureError, } from "./transcript.js";
 import { addSessionOutput, addSessionStatus, getSessionUsage, startSession, updateSessionStep, } from "./session.js";
@@ -536,6 +536,11 @@ function writeAiPromptPreviewNotice(data) {
     if (notice)
         process.stderr.write(`${notice}\n`);
 }
+function writeColumnReferenceNotices(data) {
+    for (const notice of formatColumnReferenceNotices(data)) {
+        process.stderr.write(`${notice}\n`);
+    }
+}
 function writeDisabledWorkflowNotices(data) {
     for (const notice of formatDisabledWorkflowNotices(data)) {
         process.stderr.write(`${notice}\n`);
@@ -7116,7 +7121,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--kind <kind>", "Column kind: manual, research, ai, formula, enrichment, tool, bind, or lookup. Defaults to manual. Use research for anything you would look up on the web. `lookup` reads a value out of another table; to LINK two tables row-to-row use `oxygen tables relate` instead \u2014 relation columns are two-sided and cannot be added here.")
         .option("--semantic-type <type>", "Optional semantic type such as company_domain.")
         .option("--definition-json <json>", "Optional JSON object with column definition metadata.")
-        .option("--prompt <text-or-file>", "AI or research column prompt, or a path to a prompt file — a value that resolves to a readable file is read as one, matching --prompt everywhere else in this CLI. On its own it sets kind=ai and picks the data type (text, or jsonb with an output schema); pair it with --kind research to search the web per row instead. Reference other columns inline as {{column_key}} — no --input-mapping needed; unknown keys are rejected here instead of failing per row. Merges into --definition-json (the escape hatch for everything else); a `prompt` in both is an error.")
+        .option("--prompt <text-or-file>", "AI or research column prompt, or a path to a prompt file — a value that resolves to a readable file is read as one, matching --prompt everywhere else in this CLI. On its own it sets kind=ai; pair it with --kind research to search the web per row instead. If the prompt names its output sections — a line reading 'Return the following sections:' followed by 'Score: ...', 'Reasoning: ...' — the column answers in exactly that shape and each section becomes a referenceable sub-column; otherwise it answers in plain text. Use --no-structured-output to keep it plain text either way. Reference other columns inline as {{column_key}} — no --input-mapping needed; unknown keys are rejected here instead of failing per row. Merges into --definition-json (the escape hatch for everything else); a `prompt` in both is an error.")
         .option("--research-query <template>", "Research columns: the per-row web search query, templated like the prompt (e.g. \"{{company_name}} pricing page\"). Omit to derive the query from the row's values and the prompt.")
         .option("--research-domains <csv>", "Research columns: comma-separated domains to search within, e.g. techcrunch.com,sec.gov. Omit to search the whole web.")
         .option("--research-exclude-domains <csv>", "Research columns: comma-separated domains to exclude from results.")
@@ -7127,8 +7132,10 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--input-mapping <json>", "Required with --prompt-key. JSON object mapping prompt input names to column or literal refs. Copy templates (email_draft_v1, subject_line_variants_v1, ...) reject mappings built only from manual name/title/company columns — ground them on a research or enrichment column, or write a freeform prompt with --prompt instead.")
         .option("--model <id>", "AI column model id (e.g. claude-sonnet-4-5). Explicit models require credentialMode byok unless allow-listed managed.")
         .option("--reasoning-level <level>", "AI column reasoning level: low, medium, or high (shown in the web UI as Oxygen Fast, Oxygen Balanced, and Oxygen Max).")
-        .option("--run-condition <formula>", "Formula expression gating whether the AI column runs per row.")
+        .option("--run-condition <formula>", "Formula expression gating whether the AI column runs per row. A formula over bare column keys (eu_israel = true), not {{tokens}}.")
         .option("--run-condition-columns <csv>", "Comma-separated column keys referenced by --run-condition.")
+        .option("--no-structured-output", "Keep an AI column answering in plain text even when its prompt names output sections. Use this for copy — an email body is one answer, not a set of fields.")
+        .option("--structured-output", "Undo --no-structured-output: let the prompt's named sections shape the answer again.")
         .option("--output-schema-json <json>", "AI column output JSON schema as inline JSON.")
         .option("--output-schema-file <path>", "AI column output JSON schema read from a file path.")
         .option("--bind-object <slug>", "Bind column CRM object slug (companies, people, deals, ...). Sets kind=bind and resolves rows to CRM records by identity.")
@@ -7274,12 +7281,16 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                 body.prompt_key = options.promptKey;
             if (options.inputMapping)
                 body.input_mapping = parseJsonObject(options.inputMapping);
-            if (prompt !== null)
-                await assertPromptColumnReferences(table, prompt);
-            return requestOxygen("/api/cli/tables/columns", {
+            // Every authoring path, not just --prompt: a definition pasted into
+            // --definition-json used to skip this entirely and fail once per row.
+            await assertColumnDefinitionReferences(table, column.definition);
+            const created = await requestOxygen("/api/cli/tables/columns", {
                 method: "POST",
                 body,
             });
+            if (!options.json)
+                writeColumnReferenceNotices(created);
+            return created;
         });
     }))
         .addCommand(new Command("run")
@@ -7421,25 +7432,30 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     }))
         .addCommand(new Command("rename")
-        .description("Rename a workspace column key and optionally label.")
+        .description("Rename a workspace column key and optionally label. Warns when another column reads the old key — a rename does not rewrite the references pointing at it.")
         .argument("<table>", "Table id or slug.")
         .argument("<column>", "Column id or key.")
         .requiredOption("--key <key>", "New stable column key.")
         .option("--label <label>", "Optional new display label.")
         .option("--json", "Print a JSON envelope.")
         .action(async (table, column, options) => {
-        await handleAsyncAction("columns rename", options, () => requestOxygen("/api/cli/tables/columns/rename", {
-            method: "POST",
-            body: {
-                table,
-                column,
-                key: options.key,
-                ...(readOption(options.label) ? { label: readOption(options.label) } : {}),
-            },
-        }));
+        await handleAsyncAction("columns rename", options, async () => {
+            const renamed = await requestOxygen("/api/cli/tables/columns/rename", {
+                method: "POST",
+                body: {
+                    table,
+                    column,
+                    key: options.key,
+                    ...(readOption(options.label) ? { label: readOption(options.label) } : {}),
+                },
+            });
+            if (!options.json)
+                writeColumnReferenceNotices(renamed);
+            return renamed;
+        });
     }))
         .addCommand(new Command("update")
-        .description("Update workspace column display metadata.")
+        .description("Update a workspace column: label and visibility, and for AI/research columns the prompt, named inputs, model, reasoning level, run condition, output schema, and web-research settings.")
         .argument("<table>", "Table id or slug.")
         .argument("<column>", "Column id or key.")
         .option("--label <label>", "New display label.")
@@ -7448,10 +7464,13 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--definition-unset <keys>", "Comma-separated definition keys to REMOVE after the merge (e.g. outputSchema,model) — a merge can only add or overwrite. Lifecycle and provenance keys are rejected.")
         .option("--data-type <type>", "New output data type for a lookup column (text, numeric, boolean, jsonb, timestamptz). Discards the cached cells; other column kinds use `oxygen columns retype`.")
         .option("--prompt <text-or-file>", "Replacement AI column prompt, or a path to a prompt file. Reference other columns inline as {{column_key}}; unknown keys are rejected here instead of failing per row. Merges into --definition-json; a `prompt` in both is an error.")
+        .option("--input-mapping <json>", "Replace the column's named inputs wholesale. Row columns belong in the prompt as {{column_key}}; use this for the inputs a prompt cannot name on its own — literals and workspace context ({\"icp\":{\"type\":\"context_profile\",\"path\":\"icp\"}}), which the prompt then reads as {{icp}}. Pass {} to clear it; --definition-json can only add mapping keys, never remove one.")
         .option("--model <id>", "AI column model id (e.g. claude-sonnet-4-5). Explicit models require credentialMode byok unless allow-listed managed.")
         .option("--reasoning-level <level>", "AI column reasoning level: low, medium, or high (shown in the web UI as Oxygen Fast, Oxygen Balanced, and Oxygen Max).")
-        .option("--run-condition <formula>", "Formula expression gating whether the AI column runs per row.")
+        .option("--run-condition <formula>", "Formula expression gating whether the AI column runs per row. A formula over bare column keys (eu_israel = true), not {{tokens}}.")
         .option("--run-condition-columns <csv>", "Comma-separated column keys referenced by --run-condition.")
+        .option("--no-structured-output", "Keep an AI column answering in plain text even when its prompt names output sections. Use this for copy — an email body is one answer, not a set of fields.")
+        .option("--structured-output", "Undo --no-structured-output: let the prompt's named sections shape the answer again.")
         .option("--output-schema-json <json>", "AI column output JSON schema as inline JSON.")
         .option("--output-schema-file <path>", "AI column output JSON schema read from a file path.")
         .option("--research-query <template>", "Research columns: replace the per-row web search query template, e.g. \"{{company_name}} pricing page\".")
@@ -7499,9 +7518,16 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                     definition = applyResearchColumnConfig(definition, options);
             }
             const definitionUnset = readCsvOption(options.definitionUnset);
-            if (prompt !== null)
-                await assertPromptColumnReferences(table, prompt);
-            return requestOxygen("/api/cli/tables/columns/update", {
+            // --input-mapping is the only way to repair a bad mapping in place:
+            // the server SHALLOW-merges `definition`, so a nested inputMapping
+            // sent through --definition-json adds keys and can never remove one.
+            // This replaces the object wholesale.
+            const inputMapping = readOption(options.inputMapping);
+            if (inputMapping) {
+                definition = { ...(definition ?? {}), inputMapping: parseJsonObject(inputMapping) };
+            }
+            await assertColumnDefinitionReferences(table, definition);
+            const updated = await requestOxygen("/api/cli/tables/columns/update", {
                 method: "POST",
                 body: {
                     table,
@@ -7518,6 +7544,9 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                     ...(options.dryRun ? { dry_run: true } : {}),
                 },
             });
+            if (!options.json)
+                writeColumnReferenceNotices(updated);
+            return updated;
         });
     }))
         .addCommand(new Command("retype")
@@ -7627,6 +7656,17 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                 params.set("column", column);
             return requestOxygen(`/api/cli/tables/columns/deps?${params.toString()}`, { method: "GET" });
         });
+    }))
+        .addCommand(new Command("fields")
+        .description("List what a column's output exposes: every field you can reference as {{column.field}}, filter on, sort by, or promote to its own column with `columns materialize`. Works before the column has ever run. Read-only and free.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<column>", "Column key or id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, column, options) => {
+        await handleAsyncAction("columns fields", options, () => {
+            const params = new URLSearchParams({ table, column });
+            return requestOxygen(`/api/cli/tables/columns/fields?${params.toString()}`, { method: "GET" });
+        });
     }));
     program
         .command("action-column")
@@ -9948,7 +9988,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--company-domain-column <column>", "Column key or id containing the company domain for work_email. Pair with full-name/first+last for name+company providers.")
         .option("--company-name-column <column>", "Column key or id containing the company name for work_email when no domain is available.")
         .option("--company-linkedin-url-column <column>", "Column key or id containing the company's LinkedIn URL for company identity fallback.")
-        .option("--capability <capability>", "Capability to enrich: mobile_phone or work_email. Defaults to mobile_phone.")
+        .option("--capability <capability>", "What to run: mobile_phone, work_email, linkedin_url (find a missing value), or verify_email (grade an email the row already has). Defaults to mobile_phone.")
         .option("--target-column <column>", "Target enrichment column key. Defaults to the capability payload column.")
         .option("--on-existing-manual-column <mode>", "How to handle an existing manual target: error, write_if_empty, or create_enrichment_column.")
         .option("--provider-order <providers>", "Comma-separated provider order. Overrides the default cost-aware waterfall profile.")
@@ -9983,7 +10023,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--company-name-column <column>", "Column key or id containing the company name for work_email when no domain is available.")
         .option("--company-linkedin-url-column <column>", "Column key or id containing the company's LinkedIn URL for company identity fallback.")
         .requiredOption("--max-credits <credits>", "Required credit ceiling for the queued run.")
-        .option("--capability <capability>", "Capability to enrich: mobile_phone or work_email. Defaults to mobile_phone.")
+        .option("--capability <capability>", "What to run: mobile_phone, work_email, linkedin_url (find a missing value), or verify_email (grade an email the row already has). Defaults to mobile_phone.")
         .option("--target-column <column>", "Target enrichment column key. Defaults to the capability payload column.")
         .option("--on-existing-manual-column <mode>", "How to handle an existing manual target: error, write_if_empty, or create_enrichment_column.")
         .option("--provider-order <providers>", "Comma-separated provider order. Overrides the default cost-aware waterfall profile.")
@@ -12285,7 +12325,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     })))
         .addCommand(new Command("analytics")
-        .description("Show organization-level sequencer analytics, per-sequence funnels, and native email attribution under analytics.emailAttribution: byMailbox, byDomain, and explicit unattributed facts. With --sequence, analytics.senderPerformance groups channel-conditional counts and rates by sending person across their campaign accounts. Provider-owned campaigns appear only after their telemetry is normalized into Oxygen's native Sequence ledgers. Also reports whether the reply → CRM automation is armed, with a link to the workflow.")
+        .description("Show organization-level sequencer analytics, per-sequence funnels, and native email attribution under analytics.emailAttribution: byMailbox, byDomain, and explicit unattributed facts. With --sequence, analytics.senderPerformance groups channel-conditional counts and rates by sending person; analytics.messagePerformance reports each copy-bearing deterministic step variant, target/actual distribution, contacted recipients, and type-specific accepted/reply/positive outcomes (absent for note-less connect-only campaigns). Message-level reply outcomes require preserved step/variant provenance, so older unattributed replies remain in campaign totals without being guessed into a message row. Provider-owned campaigns appear only after their telemetry is normalized into Oxygen's native Sequence ledgers. Also reports whether the reply → CRM automation is armed, with a link to the workflow.")
         .option("--range <range>", "Preset range: 7d, 14d, 28d, 30d, 90d, 180d, 365d, or all. Defaults to 14d. `all` starts at the oldest campaign in scope.")
         .option("--from <date>", "Custom start date (YYYY-MM-DD). Windows up to five years are accepted.")
         .option("--to <date>", "Custom end date (YYYY-MM-DD).")
@@ -12655,16 +12695,16 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("contacts")
-        .description("List a launched campaign's table-backed contacts with full source variables and durable contacted/not-contacted status. Contacts removed from this campaign are hidden; source rows remain intact.")
+        .description("List a launched campaign's table-backed contacts with full source variables, durable engagement stage, and factual or assigned sender. Contacts removed from this campaign are hidden; source rows remain intact.")
         .argument("<sequence>", "Sequence id or slug.")
-        .option("--contact-state <state>", "Filter: all, contacted, or not_contacted.", "all")
+        .option("--contact-state <state>", "Filter: all, not_contacted, contacted, connected, replied, or positive_reply.", "all")
         .option("--limit <n>", "Maximum contacts to return (1-500).", "100")
         .option("--json", "Print a JSON envelope.")
         .action(async (sequence, options) => {
         await handleAsyncAction("sequences contacts", options, () => {
             const contactState = readOption(options.contactState) ?? "all";
-            if (!["all", "contacted", "not_contacted"].includes(contactState)) {
-                throw new Error("--contact-state must be all, contacted, or not_contacted.");
+            if (!["all", "not_contacted", "contacted", "connected", "replied", "positive_reply"].includes(contactState)) {
+                throw new Error("--contact-state must be all, not_contacted, contacted, connected, replied, or positive_reply.");
             }
             const limit = readPositiveInt(options.limit);
             if (limit === undefined || limit > 500) {
@@ -12764,7 +12804,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         await handleSequenceEventsAction(sequence, options);
     }))
         .addCommand(new Command("variants")
-        .description("A/B scoreboard for one sequence: per-step/per-variant results plus native email by_mailbox, by_domain, reply types, rates, and explicit unattributed facts. Provider-owned campaigns appear only after normalization into Oxygen's native Sequence ledgers. Also returns reversible auto-winner state (paused variants + evidence); flags run or override/reset that state.")
+        .description("Generic per-step action/base-variant scoreboard for one sequence, plus native email by_mailbox, by_domain, reply types, rates, and explicit unattributed facts. This rollup is not the copy-only analytics.messagePerformance view; base rows can represent non-message actions, and campaign replies may lack step/variant provenance. Provider-owned campaigns appear only after normalization into Oxygen's native Sequence ledgers. Also returns reversible auto-winner state (paused variants + evidence); flags run or override/reset that state.")
         .argument("<sequence>", "Sequence id or slug.")
         .option("--auto-optimize", "Run the auto-winner now: pause the statistically-losing variant(s) of any step carrying an auto_optimize config, once every variant clears its thresholds, on that step's configured metric — reply (the recommended default), click, or open (click/open need native open/click tracking; opens are soft signals under Apple Mail Privacy Protection). Reversible.")
         .option("--pause <variant>", "Manually pause one variant (requires --step). Overrides the auto-winner.")
@@ -14630,26 +14670,6 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--json", "Print a JSON envelope.")
         .action(async (domain, options) => {
         await handleAsyncAction("domains tracking status", options, () => requestOxygen(`/api/cli/domains/${encodeURIComponent(domain)}/tracking`));
-    })))
-        .addCommand(new Command("postmaster")
-        .description("Google Postmaster Tools onboarding for a sending domain: register it with Postmaster, publish the DNS verification TXT via its Cloudflare zone, and check verification status. FREE — 0 Oxygen credits.")
-        .addCommand(new Command("onboard")
-        .description("Register the domain with Google Postmaster Tools and publish the DNS verification TXT automatically via the domain's Cloudflare zone (or return the record for manual DNS); verification then completes automatically in the background. Without --approve, returns a preview. FREE — 0 Oxygen credits.")
-        .argument("<domain>", "Sending domain, such as acme.com.")
-        .option("--approve", "Perform the onboarding. Without this flag, returns a preview only.")
-        .option("--json", "Print a JSON envelope.")
-        .action(async (domain, options) => {
-        await handleAsyncAction("domains postmaster onboard", options, () => requestOxygen(`/api/cli/domains/${encodeURIComponent(domain)}/postmaster`, {
-            method: "POST",
-            body: { ...(options.approve ? { approved: true } : {}) },
-        }));
-    }))
-        .addCommand(new Command("status")
-        .description("Show the Google Postmaster Tools onboarding status for a domain: registration, DNS verification state, and whether reputation data is available. Read-only — 0 Oxygen credits.")
-        .argument("<domain>", "Sending domain, such as acme.com.")
-        .option("--json", "Print a JSON envelope.")
-        .action(async (domain, options) => {
-        await handleAsyncAction("domains postmaster status", options, () => requestOxygen(`/api/cli/domains/${encodeURIComponent(domain)}/postmaster`));
     })))
         .addCommand(new Command("add")
         .description("BYOK CLOUDFLARE: onboard a domain registered elsewhere by creating a zone in your connected Cloudflare account. For managed domain + inbox provisioning use `managed-inboxes subscribe`.")
@@ -16813,19 +16833,62 @@ const AI_PROMPT_TEMPLATE_TOKEN = /{{\s*([^{}]+?)\s*}}/g;
 // in packages/tenant-db), so a prompt may legitimately reference them.
 const AI_PROMPT_SYSTEM_ROW_KEYS = ["_row_id", "_created_at", "_updated_at"];
 const AI_PROMPT_AVAILABLE_COLUMNS_SHOWN = 20;
-// A prompt's `{{tokens}}` resolve straight off the row at run time
-// (resolveWorkspaceTemplateString, packages/integrations/src/workspace-column-inputs.ts)
-// — independently of inputMapping, which is why --prompt needs no mapping at all.
-// The first dot-segment is the column key; the rest is a JSON path into that cell,
-// so `{{research.summary}}` only requires a `research` column to exist.
-function readAiPromptColumnRefs(prompt) {
-    const refs = [];
+function readAiPromptTemplateTokens(prompt) {
+    const tokens = [];
+    const seen = new Set();
     for (const match of prompt.matchAll(AI_PROMPT_TEMPLATE_TOKEN)) {
-        const columnKey = (match[1] ?? "").split(".")[0]?.trim();
-        if (columnKey && !refs.includes(columnKey))
-            refs.push(columnKey);
+        const raw = (match[1] ?? "").trim();
+        if (!raw || seen.has(raw))
+            continue;
+        seen.add(raw);
+        const segments = raw.split(".").map((segment) => segment.trim()).filter(Boolean);
+        const root = segments.shift();
+        if (!root)
+            continue;
+        tokens.push({ raw, root, path: segments.length > 0 ? segments.join(".") : null });
+    }
+    return tokens;
+}
+/**
+ * The first `{{column.path}}` whose column declares fields but not that one.
+ *
+ * Author-time rather than per-row, and deliberately narrow: only a column that
+ * actually publishes `output_fields` is checked. An undeclared jsonb payload can
+ * hold anything, so rejecting a path into one would refuse references that work.
+ */
+function findUnknownColumnFieldReference(tokens, columns) {
+    for (const token of tokens) {
+        if (!token.path)
+            continue;
+        const column = (columns ?? []).find((entry) => entry.key === token.root);
+        const fields = column?.output_fields ?? null;
+        if (!fields || fields.length === 0)
+            continue;
+        const paths = fields.map((field) => field.path);
+        if (paths.includes(token.path))
+            continue;
+        // A path INTO a declared object field is fine — the declaration stops at the
+        // depth the schema described, not at the depth the payload goes.
+        if (paths.some((path) => token.path?.startsWith(`${path}.`)))
+            continue;
+        const nearMisses = nearMissColumnKeys(token.path, paths);
+        return new OxygenError("invalid_prompt_column", [
+            `Prompt references {{${token.raw}}}, but "${token.root}" has no field "${token.path}".`,
+            nearMisses.length > 0
+                ? ` Did you mean {{${token.root}.${nearMisses[0]}}}?`
+                : "",
+            ` Fields on "${token.root}": ${paths.slice(0, AI_PROMPT_AVAILABLE_COLUMNS_SHOWN).join(", ")}.`,
+        ].join(""), {
+            details: {
+                column: token.root,
+                unknown_field: token.path,
+                near_misses: nearMisses,
+                available_fields: paths,
+            },
+            exitCode: 1,
+        });
     }
-    return refs;
+    return null;
 }
 // Plain Levenshtein distance, capped at the short keys this is used on — enough to
 // catch the single-character and transposition typos ({{frist_name}}) the near-miss
@@ -16853,21 +16916,64 @@ function nearMissColumnKeys(reference, columnKeys) {
         .slice(0, 3)
         .map((candidate) => candidate.key);
 }
-// Nothing validates an AI column's prompt at write time: normalizeAiColumnDefinition
-// (packages/tenant-db/src/tables.ts) reads `prompt` as an opaque string, so a
-// `{{typo}}` is accepted and then fails per row with `invalid_column_run` — one
-// wasted run per typo. `--prompt` names a table, so resolve it here against the
-// table's live columns and fail before the write instead.
-async function assertPromptColumnReferences(table, prompt) {
-    const refs = readAiPromptColumnRefs(prompt);
-    if (refs.length === 0)
+/**
+ * Resolve a column definition's `{{tokens}}` against the table's live columns
+ * BEFORE the write, so a typo is one typed error instead of one failed row per
+ * row. `analyzeColumnReferences` (packages/tenant-db) is the authority and the
+ * server now rejects the same thing on every surface; this is the local
+ * pre-flight that saves a round trip and prints the near-miss hint.
+ *
+ * Scans the whole definition, not just `--prompt`: the prompt, the research
+ * query template, and every `type: "template"` input all share one grammar, and
+ * a definition pasted into `--definition-json` used to skip the check entirely.
+ * A token naming one of the column's OWN inputs resolves at run time, so those
+ * names count as known.
+ */
+async function assertColumnDefinitionReferences(table, definition) {
+    if (!isRecord(definition))
         return;
-    const describe = await requestOxygen("/api/cli/tables/describe", { method: "POST", body: { table } });
-    const columnKeys = (describe.columns ?? []).map((column) => column.key).filter(Boolean);
-    const known = new Set([...columnKeys, ...AI_PROMPT_SYSTEM_ROW_KEYS]);
+    const inputMapping = isRecord(definition.inputMapping) ? definition.inputMapping : {};
+    const templates = [];
+    if (typeof definition.prompt === "string")
+        templates.push(definition.prompt);
+    const webSearch = isRecord(definition.webSearch) ? definition.webSearch : {};
+    if (typeof webSearch.queryTemplate === "string")
+        templates.push(webSearch.queryTemplate);
+    for (const ref of Object.values(inputMapping)) {
+        if (isRecord(ref) && ref.type === "template" && typeof ref.value === "string") {
+            templates.push(ref.value);
+        }
+    }
+    if (templates.length === 0)
+        return;
+    await assertPromptColumnReferences(table, templates.join("\n"), Object.keys(inputMapping));
+}
+// The core of the check above. The server is authoritative — this is the local
+// pre-flight that fails before the round trip and names the near miss.
+async function assertPromptColumnReferences(table, prompt, inputNames = []) {
+    const tokens = readAiPromptTemplateTokens(prompt);
+    if (tokens.length === 0)
+        return;
+    // include_archived: an archived column is a metadata flag over a physical
+    // column that still exists, so `{{archived_key}}` still resolves at run time.
+    // Leaving them out would reject here what the server accepts — the one
+    // divergence a local pre-flight must never have.
+    const describe = await requestOxygen("/api/cli/tables/describe", { method: "POST", body: { table, include_archived: true } });
+    const columns = describe.columns ?? [];
+    const columnKeys = columns.map((column) => column.key).filter(Boolean);
+    const known = new Set([...columnKeys, ...AI_PROMPT_SYSTEM_ROW_KEYS, ...inputNames]);
+    const refs = [...new Set(tokens.map((token) => token.root))];
     const unknown = refs.filter((ref) => !known.has(ref));
-    if (unknown.length === 0)
+    // A path into a column that DOES exist is checked against what that column
+    // declares it exposes, so `{{icp_fit.scoer}}` fails here rather than resolving
+    // to null on every row of a paid run. Only checked when the column actually
+    // declares fields — an undeclared jsonb payload can hold anything.
+    if (unknown.length === 0) {
+        const badPath = findUnknownColumnFieldReference(tokens, columns);
+        if (badPath)
+            throw badPath;
         return;
+    }
     const nearMisses = nearMissColumnKeys(unknown[0], columnKeys);
     const shown = columnKeys.slice(0, AI_PROMPT_AVAILABLE_COLUMNS_SHOWN);
     const overflow = columnKeys.length - shown.length;
@@ -16875,7 +16981,7 @@ async function assertPromptColumnReferences(table, prompt) {
     // invalid_* so exitCodeForOxygenError classifies this as a validation
     // failure (exit 2) alongside the server's invalid_column_definition.
     "invalid_prompt_column", [
-        `Prompt references {{${unknown[0]}}}, which is not a column on table "${table}".`,
+        `Prompt references {{${unknown[0]}}}, which is not a column on table "${table}" and not one of this column's inputs.`,
         nearMisses.length > 0
             ? ` Did you mean ${nearMisses.map((key) => `{{${key}}}`).join(", ")}?`
             : "",
@@ -16916,6 +17022,14 @@ function applyAiColumnConfig(definition, options) {
     else if (outputSchemaFile) {
         definition.outputSchema = readJsonFileValue(resolve(outputSchemaFile), "--output-schema-file");
     }
+    // Only written when the flag was actually passed. Absent must stay absent: on
+    // `columns update` the definition is merged, so writing `true` by default
+    // would re-enable structure on a column the author had deliberately set to
+    // prose without ever mentioning it.
+    if (options.structuredOutput === false)
+        definition.structuredOutput = false;
+    else if (options.structuredOutput === true)
+        definition.structuredOutput = true;
     return definition;
 }
 const RESEARCH_ENGINES = new Set(["exa", "parallel", "firecrawl"]);

package/dist/local-custom-http-column.js

@@ -1,5 +1,6 @@
 import { Buffer } from "node:buffer";
 import { OxygenError } from "@oxygen/shared";
+import { readJsonPath, walkJsonPath } from "@oxygen/shared/json-path";
 import { CustomHttpUrlSafetyError, assertCustomHttpPublicUrlSyntax, assertCustomHttpResolvedHostAllowed, } from "@oxygen/shared/custom-http-safety";
 import { requestOxygen } from "./http-client.js";
 import { isRecord } from "./util.js";
@@ -668,49 +669,23 @@ function resolveLocalTemplateRowRoot(root, segments, row, inputName, rawPath) {
     return { current: row[root], segments };
 }
 function resolveLocalTemplateSegments(current, segments) {
-    let value = current;
-    for (const segment of segments) {
-        value = resolveLocalTemplateSegment(value, segment);
-        if (value === null)
-            return null;
-    }
-    return value ?? null;
-}
-function resolveLocalTemplateSegment(current, segment) {
-    if (current === null || current === undefined)
-        return null;
-    if (Array.isArray(current) && /^\d+$/.test(segment))
-        return current[Number(segment)] ?? null;
-    if (isRecord(current) && Object.hasOwn(current, segment))
-        return current[segment];
-    return null;
+    return readJsonPath(current, segments);
 }
 function applyLocalOutputPath(value, outputPath) {
     const path = typeof outputPath === "string" ? outputPath.trim() : "";
     if (!path)
         return value;
-    let current = value;
-    for (const rawSegment of path.split(".")) {
-        const segment = rawSegment.trim();
-        if (!segment) {
-            throw new OxygenError("invalid_output_path", "Custom HTTP outputPath is invalid.", {
-                details: { output_path: outputPath },
-                exitCode: 1,
-            });
-        }
-        if (current === null || current === undefined)
-            return null;
-        if (Array.isArray(current) && /^\d+$/.test(segment)) {
-            current = current[Number(segment)] ?? null;
-            continue;
-        }
-        if (isRecord(current) && Object.hasOwn(current, segment)) {
-            current = current[segment];
-            continue;
-        }
-        return null;
+    // Must stay byte-identical to `applyOutputPath` in @oxygen/integrations —
+    // `--local` runs the same column config in-process, and a divergence here is a
+    // cell that changes value depending on where it ran.
+    const walked = walkJsonPath(value, path);
+    if (!walked.ok) {
+        throw new OxygenError("invalid_output_path", "Custom HTTP outputPath is invalid.", {
+            details: { output_path: outputPath },
+            exitCode: 1,
+        });
     }
-    return current ?? null;
+    return walked.value;
 }
 function redactLocalSecrets(value, secretValues) {
     if (typeof value === "string") {

package/node_modules/@oxygen/formula/dist/formula-functions.js

@@ -1,5 +1,5 @@
 import { OxygenError } from "@oxygen/shared/cli-result";
-import { isRecord } from "./coerce.js";
+import { walkJsonPath } from "@oxygen/shared/json-path";
 import { normalizeDomain, normalizeEmail, normalizeLinkedinUrl, } from "./value-normalizers.js";
 export const MAX_FORMULA_REGEX_PATTERN_LENGTH = 256;
 export const MAX_FORMULA_REGEX_INPUT_LENGTH = 20_000;
@@ -70,30 +70,16 @@ export function formulaValuesEqual(left, right) {
     return left === right;
 }
 export function readFormulaJsonPath(value, rawPath) {
-    const path = rawPath.trim();
-    if (!path)
-        return value ?? null;
-    let current = value;
-    for (const rawSegment of path.split(".")) {
-        const segment = rawSegment.trim();
-        if (!segment) {
-            throw formulaExpressionError("JSON path contains an empty segment.", {
-                path: rawPath,
-            });
-        }
-        if (current === null || current === undefined)
-            return null;
-        if (Array.isArray(current) && /^\d+$/.test(segment)) {
-            current = current[Number(segment)] ?? null;
-            continue;
-        }
-        if (isRecord(current) && Object.hasOwn(current, segment)) {
-            current = current[segment];
-            continue;
-        }
-        return null;
+    // Lazy validation, deliberately: a formula is evaluated per row, and an empty
+    // segment only surfaces on a row whose value actually reaches it. Switching to
+    // up-front validation would start failing rows that used to return blank.
+    const walked = walkJsonPath(value, rawPath);
+    if (!walked.ok) {
+        throw formulaExpressionError("JSON path contains an empty segment.", {
+            path: rawPath,
+        });
     }
-    return current ?? null;
+    return walked.value;
 }
 export function checkFormulaFunctionArity(spec, received) {
     const withinMin = received >= spec.minArgs;