@oxygen-agent/cli 1.861.0 → 1.879.0

package/node_modules/@oxygen/shared/dist/cell-format.js

@@ -14,6 +14,7 @@
  *     version strings, phone numbers, URLs): {@link rescueNumericText} returns
  *     null for those.
  */
+import { columnOutputPrimaryField } from "./column-output-fields.js";
 import { isMarkdownColumnSemantic } from "./select-options.js";
 const DEFAULT_LOCALE = "en-US";
 const INTEGER_RE = /^-?\d{1,15}$/;
@@ -33,6 +34,10 @@ const WRAPPER_COLUMN_KINDS = new Set([
     "tool",
     "tool_enrichment",
     "ai",
+    // A research cell is the {answer, found, confidence, sources} envelope. It was
+    // missing here, so every research cell rendered as raw JSON in the CLI, in MCP
+    // payloads and in the grid.
+    "research",
     "action",
     "formula",
     "relation",
@@ -72,7 +77,7 @@ export function formatCellForDisplay(value, column, options) {
         return markdownToPlainText(typeof value === "string" ? value : String(value));
     }
     if (isEnrichmentPayload(value) && columnHasWrapperKind(column)) {
-        const wrapped = readEnrichmentValue(value);
+        const wrapped = readWrappedValue(value, column);
         if (wrapped !== undefined) {
             return formatCellForDisplay(wrapped, column, options);
         }
@@ -287,7 +292,23 @@ function formatTimestamp(value, surface) {
 function isEnrichmentPayload(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-function readEnrichmentValue(payload) {
+/**
+ * Pull the carried value out of a wrapper cell.
+ *
+ * The DECLARED primary field wins: an enrichment cell says its value lives under
+ * `value`, a research cell says `answer`. That is the column telling us, not a
+ * key-name guess — which matters because the fallback below is a guess, and a
+ * manual jsonb cell a user typed themselves is deliberately left alone (it is
+ * not a wrapper kind, so it never reaches here at all).
+ *
+ * The key list stays as the fallback for wrapper kinds that declare no primary
+ * field — `tool`, `action`, `formula`, `relation` — whose payload shape comes
+ * from a provider rather than from us.
+ */
+function readWrappedValue(payload, column) {
+    const declared = column ? columnOutputPrimaryField(column) : null;
+    if (declared && declared in payload)
+        return payload[declared];
     for (const key of ENRICHMENT_VALUE_KEYS) {
         if (key in payload)
             return payload[key];

package/node_modules/@oxygen/shared/dist/column-output-fields.d.ts

@@ -0,0 +1,122 @@
+export type ColumnOutputFieldSource = "ai_schema" | "research_contract" | "tool_schema" | "waterfall_fields" | "enrichment_envelope" | "bind_envelope" | "lookup_return";
+/** The logical cell types a table column can hold. Mirrors WorkspaceDataType. */
+export type ColumnOutputDataType = "text" | "numeric" | "boolean" | "jsonb" | "timestamptz";
+export type ColumnOutputField = {
+    /** Dotted path from the CELL ROOT. Lossy when a segment contains a dot. */
+    path: string;
+    /** Pre-parsed path. Authoritative. */
+    segments: string[];
+    /** Stable identifier, unique within the column. */
+    key: string;
+    label: string;
+    /** The table data type this field would have if it were its own column. */
+    dataType: ColumnOutputDataType | null;
+    /** The raw JSON-Schema `type`, when the field came from a schema. */
+    jsonType: string | null;
+    description: string | null;
+    /** Can this be written as a `{{column.path}}` token? */
+    referenceable: boolean;
+    /** Materialize target column key, when the config names one. */
+    targetColumn: string | null;
+    source: ColumnOutputFieldSource;
+};
+export type ColumnOutputContract = {
+    /** The schema the fields were derived from, when there was one. */
+    schema: Record<string, unknown> | null;
+    fields: ColumnOutputField[];
+    /**
+     * The field a BARE reference to this column resolves to.
+     *
+     * An enrichment cell is `{value, source, confidence, …}`; a user writing
+     * `{{work_email}}` means the email, not the envelope. Declared per kind rather
+     * than guessed from key names, so a manual jsonb cell that happens to have a
+     * `value` key is never silently unwrapped.
+     */
+    primaryField: string | null;
+    /** True when the shape is re-derived from config rather than authored. */
+    serverManaged: boolean;
+};
+export type ColumnOutputColumnLike = {
+    key?: string | null;
+    label?: string | null;
+    kind?: string | null;
+    dataType?: string | null;
+    data_type?: string | null;
+    definition?: Record<string, unknown> | null;
+};
+export type ResolveColumnOutputOptions = {
+    /**
+     * Look up a native/composio tool's declared output schema. Server-only — the
+     * tool catalog must not reach a browser bundle — so this is injected rather
+     * than imported. Absent means tool columns resolve to no declared fields and
+     * fall back to sampling, never to an error.
+     */
+    toolOutputSchema?: (toolId: string) => Record<string, unknown> | null;
+    /** Resolve another workspace table's columns, for `lookup` return columns. */
+    lookupSourceColumns?: (sourceTable: string) => Array<{
+        key: string;
+        label?: string;
+        dataType?: string | null;
+    }> | null;
+};
+export declare function humanizeFieldSegment(segment: string): string;
+/**
+ * Map a JSON-Schema `type` onto the table data type the field would take as its
+ * own column. A union like `["string","null"]` is its non-null member — the
+ * nullability is the cell being empty, not a different type.
+ */
+export declare function dataTypeForJsonType(jsonType: unknown): ColumnOutputDataType | null;
+type RawField = {
+    segments: string[];
+    jsonType: string | null;
+    description?: string | null;
+    label?: string;
+    dataType?: ColumnOutputDataType | null;
+    targetColumn?: string | null;
+};
+/**
+ * Enumerate the leaf and branch paths a JSON Schema declares.
+ *
+ * Object properties recurse. An array's item schema contributes index `0` as the
+ * representative element, which is what makes `sources.0.url` referenceable.
+ *
+ * Note this does NOT drop keys that are not dot-safe. An earlier version did,
+ * which silently hid every field of a research column whose prompt named its
+ * sections in plain English — while filters accepted those exact paths. The
+ * field is emitted and `referenceable` tells the caller what it can be used for.
+ */
+export declare function collectJsonSchemaFields(schema: unknown, prefix?: readonly string[], depth?: number): RawField[];
+/**
+ * Follow a tool column's `outputPath` into its provider schema, so the declared
+ * fields describe what the CELL holds rather than what the provider returned.
+ *
+ * Returns null when the path leaves the schema — better no declared fields (and
+ * a sampling fallback) than fields pointing at a level the cell does not have.
+ */
+export declare function narrowSchemaAtOutputPath(schema: Record<string, unknown>, outputPath: string | null): Record<string, unknown> | null;
+/**
+ * The declared output contract for one column.
+ *
+ * Never throws and never partially fails: a kind with nothing to declare, a tool
+ * whose catalog entry is missing, a lookup whose source table cannot be
+ * resolved — all return an empty contract, and the caller falls back to
+ * sampling or to showing the whole cell.
+ */
+export declare function resolveColumnOutputContract(column: ColumnOutputColumnLike, options?: ResolveColumnOutputOptions): ColumnOutputContract;
+/** Just the fields. */
+export declare function columnOutputFields(column: ColumnOutputColumnLike, options?: ResolveColumnOutputOptions): ColumnOutputField[];
+/** The field a bare `{{column}}` reference resolves to, if the kind declares one. */
+export declare function columnOutputPrimaryField(column: ColumnOutputColumnLike, options?: ResolveColumnOutputOptions): string | null;
+/** Full `column.path` tokens this column exposes to a template. */
+export declare function columnOutputReferenceKeys(column: ColumnOutputColumnLike, options?: ResolveColumnOutputOptions): string[];
+/**
+ * Read one declared field out of a cell value.
+ *
+ * `parseJsonStrings` is on because a structured AI column stored as `text` holds
+ * its validated JSON as a string; without it every field of such a column reads
+ * blank.
+ */
+export declare function readColumnOutputField(cellValue: unknown, field: ColumnOutputField): unknown;
+/** Does this column's cell type allow a JSON path to be pushed into SQL? */
+export declare function columnOutputFieldsAreQueryable(column: ColumnOutputColumnLike): boolean;
+export {};

package/node_modules/@oxygen/shared/dist/column-output-fields.js

@@ -0,0 +1,459 @@
+/**
+ * What fields does an output-producing column expose?
+ *
+ * A table column that runs — AI, research, tool, enrichment, bind, lookup —
+ * writes a structured value into one cell. Everything downstream then wants ONE
+ * field out of it: a prompt referencing `{{icp_fit.score}}`, a filter on
+ * `answer.confidence`, a sub-column in the grid, a CSV export of just the email.
+ *
+ * Until now each of those discovered fields its own way, and the most common way
+ * was to guess from whatever happened to be in a loaded row. That means a column
+ * that has never run exposes nothing, the field set changes as rows load, and
+ * two surfaces looking at the same column can disagree about what is in it.
+ *
+ * This module is the one answer, DECLARED rather than sampled: per kind, derive
+ * the fields from the column's own configuration — its output schema, its
+ * provider descriptor, its waterfall field list, its lookup return columns, or
+ * the fixed envelope its runtime writes. Sampling stays as a fallback for
+ * undeclared tool payloads; it is no longer the primary source.
+ *
+ * Two encodings of the same path travel together on purpose. `path` is the
+ * dotted string that filters, sorts and `{{mention}}` tokens already speak;
+ * `segments` is the pre-parsed array the value readers want. They are one
+ * producer with two encodings, not two sources of truth — but `segments` is
+ * AUTHORITATIVE, because `path` is lossy for exactly one real case: a research
+ * column names its output sections after free-text prompt labels, and a label
+ * may contain a dot or a space. Such a field carries `referenceable: false` and
+ * is display-only.
+ */
+import { buildResearchCellSchema, deriveResearchOutputContract, usesServerManagedResearchSchema, } from "./research-output-contract.js";
+import { isTemplateSafePath, parseJsonPath, readJsonPath } from "./json-path.js";
+const MAX_FIELDS = 40;
+const MAX_SCHEMA_DEPTH = 5;
+const EMPTY_CONTRACT = {
+    schema: null,
+    fields: [],
+    primaryField: null,
+    serverManaged: false,
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+export function humanizeFieldSegment(segment) {
+    const titled = segment
+        .split(/[_\s-]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+    return titled || segment;
+}
+/**
+ * The label a field is rendered with: its LAST segment, humanized.
+ *
+ * Deliberately not the whole path. Every surface that shows a field already
+ * shows its parent beside it — the grid puts sub-columns under a band carrying
+ * the column name, the reference picker nests them under the column node, a
+ * filter chip renders "Column / Field". A full-path label there reads as
+ * "Company / Name" nested under "Company", which is the parent said twice.
+ * `path` carries the rest for anything that needs it flat.
+ */
+function defaultFieldLabel(segments) {
+    const last = segments[segments.length - 1];
+    return last ? humanizeFieldSegment(last) : "";
+}
+/**
+ * Map a JSON-Schema `type` onto the table data type the field would take as its
+ * own column. A union like `["string","null"]` is its non-null member — the
+ * nullability is the cell being empty, not a different type.
+ */
+export function dataTypeForJsonType(jsonType) {
+    const type = Array.isArray(jsonType)
+        ? jsonType.find((entry) => typeof entry === "string" && entry !== "null")
+        : jsonType;
+    switch (type) {
+        case "string":
+            return "text";
+        case "number":
+        case "integer":
+            return "numeric";
+        case "boolean":
+            return "boolean";
+        case "object":
+        case "array":
+            return "jsonb";
+        default:
+            return null;
+    }
+}
+function toField(raw, source) {
+    const path = raw.segments.join(".");
+    // A path round-trips only when no segment contains a dot. Research section
+    // labels are free text, so this is a real case rather than a defensive one.
+    const parsed = parseJsonPath(path, { emptySegment: "reject" });
+    const roundTrips = parsed.ok
+        && parsed.segments.length === raw.segments.length
+        && parsed.segments.every((segment, index) => segment === raw.segments[index]);
+    return {
+        path,
+        segments: raw.segments,
+        key: path,
+        label: raw.label ?? defaultFieldLabel(raw.segments),
+        dataType: raw.dataType ?? dataTypeForJsonType(raw.jsonType),
+        jsonType: raw.jsonType,
+        description: raw.description ?? null,
+        referenceable: roundTrips && isTemplateSafePath(path),
+        targetColumn: raw.targetColumn ?? null,
+        source,
+    };
+}
+/**
+ * Enumerate the leaf and branch paths a JSON Schema declares.
+ *
+ * Object properties recurse. An array's item schema contributes index `0` as the
+ * representative element, which is what makes `sources.0.url` referenceable.
+ *
+ * Note this does NOT drop keys that are not dot-safe. An earlier version did,
+ * which silently hid every field of a research column whose prompt named its
+ * sections in plain English — while filters accepted those exact paths. The
+ * field is emitted and `referenceable` tells the caller what it can be used for.
+ */
+export function collectJsonSchemaFields(schema, prefix = [], depth = 0) {
+    if (!isRecord(schema) || depth > MAX_SCHEMA_DEPTH)
+        return [];
+    const fields = [];
+    const properties = isRecord(schema.properties) ? schema.properties : null;
+    if (properties) {
+        for (const key of orderedPropertyKeys(schema, properties)) {
+            const segments = [...prefix, key];
+            const rawProperty = properties[key];
+            const property = isRecord(rawProperty) ? rawProperty : {};
+            fields.push({
+                segments,
+                // Kept RAW, including a nullable union like ["string","null"]:
+                // `dataTypeForJsonType` reads the non-null member, and collapsing the
+                // union to null here would lose the type of every derived field, since
+                // every one of them is nullable.
+                jsonType: normalizeJsonType(property.type),
+                description: readString(property.description),
+            });
+            fields.push(...collectJsonSchemaFields(property, segments, depth + 1));
+        }
+    }
+    if (schema.type === "array" && isRecord(schema.items)) {
+        const segments = [...prefix, "0"];
+        fields.push({
+            segments,
+            jsonType: normalizeJsonType(schema.items.type),
+            description: readString(schema.items.description),
+        });
+        fields.push(...collectJsonSchemaFields(schema.items, segments, depth + 1));
+    }
+    return fields;
+}
+/**
+ * The schema's `required` array is the author's field order; `properties` is not.
+ *
+ * A definition round-trips through a jsonb column, and Postgres normalizes jsonb
+ * object keys by length then bytewise — so a prompt asking for Score, Reasoning,
+ * Risks comes back as Risks, Score, Reasoning. `required` is a JSON *array*, so
+ * it survives, and it is the order the model was asked to produce the fields in,
+ * which is the order a reader expects to see them.
+ *
+ * Falls back to property order when `required` does not cover the object, and
+ * appends anything it misses so a field can never be dropped by this.
+ */
+function orderedPropertyKeys(schema, properties) {
+    const keys = Object.keys(properties);
+    const required = Array.isArray(schema.required)
+        ? schema.required.filter((entry) => typeof entry === "string")
+        : [];
+    if (required.length === 0)
+        return keys;
+    const seen = new Set();
+    const ordered = [];
+    for (const key of required) {
+        if (!Object.hasOwn(properties, key) || seen.has(key))
+            continue;
+        seen.add(key);
+        ordered.push(key);
+    }
+    for (const key of keys) {
+        if (seen.has(key))
+            continue;
+        ordered.push(key);
+    }
+    return ordered;
+}
+/** A JSON-Schema `type`, keeping a nullable union intact. */
+function normalizeJsonType(value) {
+    if (typeof value === "string")
+        return value;
+    if (!Array.isArray(value))
+        return null;
+    const named = value.find((entry) => typeof entry === "string" && entry !== "null");
+    return typeof named === "string" ? named : null;
+}
+// --- per-kind envelopes ----------------------------------------------------
+/**
+ * The shape an enrichment cell is written with — see the cell assembly in the
+ * inline executor and its worker twin. `line_type` / `carrier` are deliberately
+ * absent: the runner surfaces those as companion COLUMNS, not as cell fields.
+ */
+const ENRICHMENT_CELL_SCHEMA = {
+    type: "object",
+    additionalProperties: true,
+    properties: {
+        value: { type: ["string", "null"], description: "The enriched value, when one was found." },
+        source: { type: ["string", "null"], description: "Provider that produced the winning value." },
+        confidence: { type: ["string", "null"], description: "Provider-reported confidence." },
+        status: { type: ["string", "null"], description: "Outcome of the waterfall." },
+        attempts: {
+            type: "array",
+            description: "Every provider leg tried, in order.",
+            items: {
+                type: "object",
+                additionalProperties: true,
+                properties: {
+                    provider: { type: ["string", "null"], description: "Provider id." },
+                    operation: { type: ["string", "null"], description: "Provider operation." },
+                    status: { type: ["string", "null"], description: "Leg outcome." },
+                },
+            },
+        },
+        cache_hit: { type: "boolean", description: "The winning leg was reused from cache and billed 0." },
+        credits_saved: { type: ["number", "null"], description: "Credits a live call would have cost." },
+        reused_from: { type: ["string", "null"], description: "When the reused value was enriched." },
+    },
+};
+/** The shape a `bind` cell is written with. */
+const BIND_CELL_SCHEMA = {
+    type: "object",
+    additionalProperties: true,
+    properties: {
+        status: { type: "string", description: "matched, created, no_match, or ambiguous." },
+        record_id: { type: ["string", "null"], description: "The CRM record this row resolved to." },
+        object: { type: ["string", "null"], description: "CRM object the row was bound against." },
+        confidence: { type: ["number", "null"], description: "Match confidence." },
+        bound_at: { type: ["string", "null"], description: "When the binding was written." },
+    },
+};
+// --- per-kind resolution ---------------------------------------------------
+function readDefinition(column) {
+    return isRecord(column.definition) ? column.definition : {};
+}
+function readColumnDataType(column) {
+    return readString(column.dataType) ?? readString(column.data_type);
+}
+function aiContract(definition) {
+    const schema = isRecord(definition.outputSchema) ? definition.outputSchema : null;
+    if (!schema)
+        return EMPTY_CONTRACT;
+    return {
+        schema,
+        fields: collectJsonSchemaFields(schema).map((raw) => toField(raw, "ai_schema")),
+        primaryField: readString(isRecord(definition.aiOutput) ? definition.aiOutput.primaryField : null),
+        serverManaged: isRecord(definition.aiOutput),
+    };
+}
+function researchContract(definition) {
+    const serverManaged = usesServerManagedResearchSchema(definition);
+    const prompt = readString(definition.prompt) ?? "";
+    const webSearch = isRecord(definition.webSearch) ? definition.webSearch : null;
+    const contract = deriveResearchOutputContract(prompt, {
+        evidenceRequired: webSearch?.evidenceMode === "strict",
+    });
+    // The STORED shape, not the model-facing one: a research cell carries
+    // `sources`, never the `citations` the model answered with.
+    const schema = serverManaged
+        ? buildResearchCellSchema(contract)
+        : (isRecord(definition.outputSchema) ? definition.outputSchema : null);
+    if (!schema)
+        return EMPTY_CONTRACT;
+    return {
+        schema,
+        fields: collectJsonSchemaFields(schema).map((raw) => toField(raw, "research_contract")),
+        // A sectioned answer has no single primary field; an unsectioned one is
+        // just its answer.
+        primaryField: contract === null ? "answer" : null,
+        serverManaged,
+    };
+}
+function waterfallContract(definition) {
+    const declared = Array.isArray(definition.fields) ? definition.fields : [];
+    const targets = isRecord(definition.targetColumns) ? definition.targetColumns : {};
+    const fields = declared
+        .filter((entry) => typeof entry === "string" && entry.length > 0)
+        .map((field) => toField({
+        // A waterfall cell normalizes to { fields: { <name>: { value, provider } } },
+        // so the value lives one level below the field name. Expressing it as a
+        // real root path is what makes these filterable and sortable at all.
+        segments: ["fields", field, "value"],
+        jsonType: null,
+        label: humanizeFieldSegment(field),
+        targetColumn: typeof targets[field] === "string" ? targets[field] : null,
+    }, "waterfall_fields"));
+    return { schema: null, fields, primaryField: null, serverManaged: true };
+}
+function toolContract(definition, options) {
+    const mode = readString(definition.mode) ?? "native";
+    if (mode === "company_enrichment_waterfall")
+        return waterfallContract(definition);
+    if (mode === "callable_table") {
+        const mapping = isRecord(definition.outputMapping) ? definition.outputMapping : {};
+        const fields = Object.entries(mapping).map(([outputKey, target]) => toField({
+            segments: [outputKey],
+            jsonType: null,
+            targetColumn: typeof target === "string" ? target : null,
+        }, "tool_schema"));
+        return { schema: null, fields, primaryField: null, serverManaged: true };
+    }
+    const toolId = readString(definition.toolId);
+    const schema = toolId ? options.toolOutputSchema?.(toolId) ?? null : null;
+    if (!schema)
+        return EMPTY_CONTRACT;
+    // `applyToolColumnOutputPath` already projected `outputPath` before the cell
+    // was written, so the declared paths are relative to that projection, not to
+    // the provider's whole response.
+    const narrowed = narrowSchemaAtOutputPath(schema, readString(definition.outputPath));
+    if (!narrowed)
+        return EMPTY_CONTRACT;
+    return {
+        schema: narrowed,
+        fields: collectJsonSchemaFields(narrowed).map((raw) => toField(raw, "tool_schema")),
+        primaryField: null,
+        serverManaged: true,
+    };
+}
+/**
+ * Follow a tool column's `outputPath` into its provider schema, so the declared
+ * fields describe what the CELL holds rather than what the provider returned.
+ *
+ * Returns null when the path leaves the schema — better no declared fields (and
+ * a sampling fallback) than fields pointing at a level the cell does not have.
+ */
+export function narrowSchemaAtOutputPath(schema, outputPath) {
+    if (!outputPath)
+        return schema;
+    const parsed = parseJsonPath(outputPath, { emptySegment: "reject" });
+    if (!parsed.ok)
+        return null;
+    let current = schema;
+    for (const segment of parsed.segments) {
+        if (!current)
+            return null;
+        if (current.type === "array" && isRecord(current.items) && /^\d+$/.test(segment)) {
+            current = current.items;
+            continue;
+        }
+        const properties = isRecord(current.properties)
+            ? current.properties
+            : null;
+        const next = properties?.[segment];
+        current = isRecord(next) ? next : null;
+    }
+    return current;
+}
+function lookupContract(definition, options) {
+    if (definition.mode !== "first_match")
+        return EMPTY_CONTRACT;
+    const returnColumns = Array.isArray(definition.returnColumns)
+        ? definition.returnColumns.filter((entry) => typeof entry === "string")
+        : [];
+    // A single return column IS the cell — a scalar, with nothing to decompose.
+    if (returnColumns.length < 2)
+        return EMPTY_CONTRACT;
+    const sourceTable = readString(definition.sourceTable);
+    const sourceColumns = sourceTable ? options.lookupSourceColumns?.(sourceTable) ?? null : null;
+    const byKey = new Map((sourceColumns ?? []).map((column) => [column.key, column]));
+    const fields = returnColumns.map((key) => {
+        const source = byKey.get(key);
+        return toField({
+            segments: [key],
+            jsonType: null,
+            label: source?.label ?? humanizeFieldSegment(key),
+            dataType: source?.dataType ?? null,
+        }, "lookup_return");
+    });
+    return { schema: null, fields, primaryField: null, serverManaged: true };
+}
+/**
+ * The declared output contract for one column.
+ *
+ * Never throws and never partially fails: a kind with nothing to declare, a tool
+ * whose catalog entry is missing, a lookup whose source table cannot be
+ * resolved — all return an empty contract, and the caller falls back to
+ * sampling or to showing the whole cell.
+ */
+export function resolveColumnOutputContract(column, options = {}) {
+    const definition = readDefinition(column);
+    const contract = resolveByKind(column, definition, options);
+    if (contract.fields.length <= MAX_FIELDS)
+        return contract;
+    return { ...contract, fields: contract.fields.slice(0, MAX_FIELDS) };
+}
+function resolveByKind(column, definition, options) {
+    switch (column.kind) {
+        case "ai":
+            return aiContract(definition);
+        case "research":
+            return researchContract(definition);
+        case "tool":
+            return toolContract(definition, options);
+        case "enrichment":
+            return {
+                schema: ENRICHMENT_CELL_SCHEMA,
+                fields: collectJsonSchemaFields(ENRICHMENT_CELL_SCHEMA).map((raw) => toField(raw, "enrichment_envelope")),
+                // `{{work_email}}` means the email, not the envelope around it.
+                primaryField: "value",
+                serverManaged: true,
+            };
+        case "bind":
+            return {
+                schema: BIND_CELL_SCHEMA,
+                fields: collectJsonSchemaFields(BIND_CELL_SCHEMA).map((raw) => toField(raw, "bind_envelope")),
+                // Deliberately none: promoting `status` to the bare reference would
+                // change how every existing bind cell renders, which is its own opt-in
+                // decision rather than a side effect of declaring fields.
+                primaryField: null,
+                serverManaged: true,
+            };
+        case "lookup":
+            return lookupContract(definition, options);
+        default:
+            return EMPTY_CONTRACT;
+    }
+}
+/** Just the fields. */
+export function columnOutputFields(column, options = {}) {
+    return resolveColumnOutputContract(column, options).fields;
+}
+/** The field a bare `{{column}}` reference resolves to, if the kind declares one. */
+export function columnOutputPrimaryField(column, options = {}) {
+    return resolveColumnOutputContract(column, options).primaryField;
+}
+/** Full `column.path` tokens this column exposes to a template. */
+export function columnOutputReferenceKeys(column, options = {}) {
+    const key = readString(column.key);
+    if (!key)
+        return [];
+    return columnOutputFields(column, options)
+        .filter((field) => field.referenceable)
+        .map((field) => `${key}.${field.path}`);
+}
+/**
+ * Read one declared field out of a cell value.
+ *
+ * `parseJsonStrings` is on because a structured AI column stored as `text` holds
+ * its validated JSON as a string; without it every field of such a column reads
+ * blank.
+ */
+export function readColumnOutputField(cellValue, field) {
+    return readJsonPath(cellValue, field.segments, { parseJsonStrings: true });
+}
+/** Does this column's cell type allow a JSON path to be pushed into SQL? */
+export function columnOutputFieldsAreQueryable(column) {
+    return readColumnDataType(column) === "jsonb";
+}

package/node_modules/@oxygen/shared/dist/index.d.ts

@@ -51,6 +51,7 @@ export * from "./person-name.js";
 export * from "./recipes.js";
 export * from "./sequence-template.js";
 export * from "./sequence-crm-events.js";
+export * from "./sequence-failures.js";
 export * from "./sequence-hubspot-sync.js";
 export * from "./sequence-terminal-events.js";
 export * from "./call-outcomes.js";

package/node_modules/@oxygen/shared/dist/index.js

@@ -51,6 +51,7 @@ export * from "./person-name.js";
 export * from "./recipes.js";
 export * from "./sequence-template.js";
 export * from "./sequence-crm-events.js";
+export * from "./sequence-failures.js";
 export * from "./sequence-hubspot-sync.js";
 export * from "./sequence-terminal-events.js";
 export * from "./call-outcomes.js";