@oxygen-agent/cli 1.1014.136 → 1.1014.619

package/dist/commands/feedback.js

@@ -0,0 +1,96 @@
+import { readCsvOption, readSelectedTranscriptExcerpt } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { captureCurrentTranscript, collectFeedbackEnvironment, TranscriptCaptureError } from "../transcript.js";
+import { readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { OXYGEN_VERSION } from "@oxygen/shared/version";
+// Assemble the POST body for `oxygen feedback`. A transcript leaves the machine
+// only after an explicit --include-transcript, --session-id, or --file choice;
+// --no-transcript remains a backward-compatible veto. The local capture applies
+// bounded, best-effort secret redaction, but the user still owns the decision to
+// share broader session content. The environment snapshot never includes env
+// variables or credential values.
+function buildFeedbackBody(options) {
+    const message = readOption(options.message);
+    if (!message) {
+        throw new OxygenError("invalid_input", 'Provide your feedback with --message "...".', { exitCode: 1 });
+    }
+    const body = {
+        message,
+        category: readOption(options.category) ?? "feedback",
+        context: {
+            cli_version: OXYGEN_VERSION,
+            environment: collectFeedbackEnvironment(),
+            ...(readCsvOption(options.deepLinks).length ? { deep_links: readCsvOption(options.deepLinks) } : {}),
+            ...(readOption(options.operation) ? { operation: readOption(options.operation) } : {}),
+            ...(readOption(options.errorCode) ? { error_code: readOption(options.errorCode) } : {}),
+            ...(readCsvOption(options.runIds).length ? { run_ids: readCsvOption(options.runIds) } : {}),
+            ...(readCsvOption(options.tableIds).length ? { table_ids: readCsvOption(options.tableIds) } : {}),
+            ...(readOption(options.slackPermalink) ? { slack_permalink: readOption(options.slackPermalink) } : {}),
+            ...(readOption(options.slackChannelId) ? { slack_channel_id: readOption(options.slackChannelId) } : {}),
+            ...(readOption(options.customerWorkspace) ? { customer_workspace: readOption(options.customerWorkspace) } : {}),
+        },
+    };
+    if (readOption(options.severity))
+        body.severity = readOption(options.severity);
+    const sessionId = readOption(options.sessionId);
+    const file = readOption(options.file);
+    if (options.transcript !== false && options.transcriptText !== undefined) {
+        if (sessionId || file || options.includeTranscript) {
+            throw new OxygenError("invalid_input", "Choose --transcript-text or one local transcript option.", { exitCode: 1 });
+        }
+        body.transcript_text = readSelectedTranscriptExcerpt(options.transcriptText);
+    }
+    const includeTranscript = options.transcript !== false &&
+        (options.includeTranscript === true || Boolean(sessionId) || Boolean(file));
+    if (includeTranscript) {
+        try {
+            const captured = captureCurrentTranscript({
+                sessionId,
+                file,
+            });
+            if (captured) {
+                const { path: _path, ...payload } = captured;
+                body.transcript = payload;
+            }
+            else {
+                process.stderr.write("note: no local chat transcript found; sending your note without one.\n");
+            }
+        }
+        catch (error) {
+            if (error instanceof TranscriptCaptureError) {
+                throw new OxygenError("transcript_not_found", error.message, { exitCode: 1 });
+            }
+            throw error;
+        }
+    }
+    return body;
+}
+export function registerFeedbackFamily(program, handleAsyncAction) {
+    program
+        .command("feedback")
+        .description("Send feedback or a bug report to the OXYGEN team. This is the same immediate, zero-credit canonical Plain conversation write as `support chat`; transcripts are never attached unless explicitly requested.")
+        .option("-m, --message <message>", "Your feedback or bug report.")
+        .option("--severity <severity>", "low | normal | high. Defaults to normal.")
+        .option("--category <category>", "Optional category label. Defaults to 'feedback'.")
+        .option("--deep-links <urls>", "Comma-separated workspace links to include in the report context.")
+        .option("--operation <operation>", "The operation that failed.")
+        .option("--error-code <code>", "Error envelope code from the failed operation.")
+        .option("--run-ids <ids>", "Comma-separated affected run ids.")
+        .option("--table-ids <ids>", "Comma-separated affected table ids.")
+        .option("--slack-permalink <url>", "Customer-selected Slack message permalink for a forwarded report.")
+        .option("--slack-channel-id <id>", "Slack channel associated with the forwarded report.")
+        .option("--customer-workspace <label>", "Workspace name or slug associated with a forwarded report.")
+        .option("--transcript-text <text>", "Explicitly attach a selected excerpt (1-200,000 bytes) after best-effort secret redaction; exclusive with local transcript options.")
+        .option("--session-id <id>", "Explicitly attach a specific local session transcript by id.")
+        .option("--file <path>", "Explicitly attach a specific local transcript file.")
+        .option("--include-transcript", "Explicitly attach the most recently active local session after best-effort secret redaction. Review it for sensitive customer data first.")
+        .option("--no-transcript", "Deprecated safety override: send the note without a transcript.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("feedback send", options, () => requestOxygen("/api/cli/feedback", {
+            method: "POST",
+            body: buildFeedbackBody(options),
+        }));
+    });
+}

package/dist/commands/feeds.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerFeedsFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/feeds.js

@@ -0,0 +1,486 @@
+import { parseJsonObject, readPositiveInt, readRecordString } from "../cli-values.js";
+import { CADENCE_FLAG_DESCRIPTION, readCsvOption, readFileIfPresent, readPositiveNumber, tableWebhookDeliveriesPath } from "../command-support.js";
+import { addContractFlags, readContractFlags } from "../contract-flags.js";
+import { addFeedReadFlags, feedReadWindowParams } from "../feed-read-flags.js";
+import { requestOxygen } from "../http-client.js";
+import { isRecord, readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { TABLE_FEED_UPDATE_CONTRACT, tableFeedUpdateIssues } from "@oxygen/shared/contracts/table-feed-update";
+import { Command } from "commander";
+function feedsListPath(options, tableArgument) {
+    const params = feedReadWindowParams(options);
+    const table = readOption(tableArgument) ?? readOption(options.table);
+    const transport = readOption(options.transport);
+    const status = readOption(options.status);
+    const state = readOption(options.state);
+    const limit = readPositiveInt(options.limit);
+    if (table)
+        params.set("table", table);
+    if (transport)
+        params.set("transport", transport);
+    if (status)
+        params.set("status", status);
+    if (state)
+        params.set("state", state);
+    if (limit)
+        params.set("limit", String(limit));
+    if (options.includeCursor)
+        params.set("include", "cursor");
+    const query = params.toString();
+    return `/api/cli/tables/feeds${query ? `?${query}` : ""}`;
+}
+function feedsGetPath(feed, options) {
+    const params = feedReadWindowParams(options, true);
+    params.set("feed", feed);
+    const include = [options.includeCursor ? "cursor" : null, options.includeRoute ? "route" : null].filter(Boolean);
+    if (include.length)
+        params.set("include", include.join(","));
+    return `/api/cli/tables/feeds?${params.toString()}`;
+}
+// The bind body mirrors the route's reader: everything the provider is asked for
+// lives under `route`, everything about the cadence under `sync`. The two stay
+// separated because the route re-derives every spend-relevant number (credits per
+// page, incremental mode) from route.tool_id and never from what we send.
+function readFeedBindBody(table, options) {
+    const toolIds = readCsvOption(options.toolIds);
+    const maxPages = readPositiveInt(options.maxPages);
+    const every = readOption(options.every);
+    const maxCreditsPerCycle = readPositiveNumber(options.maxCredits);
+    const maxRowsPerCycle = readPositiveInt(options.maxRows);
+    const filters = options.filtersJson ? parseJsonObject(readFileIfPresent(options.filtersJson)) : null;
+    return {
+        table,
+        transport: "pull",
+        feed_kind: options.kind,
+        route: {
+            tool_id: options.toolId,
+            // assertPullFeedBindArguments guarantees --request-json before this reader runs.
+            request: parseJsonObject(readFileIfPresent(options.requestJson)),
+            ...(toolIds.length > 0 ? { tool_ids: toolIds } : {}),
+            ...(readOption(options.rowsPath) ? { rows_path: readOption(options.rowsPath) } : {}),
+            ...(options.rowMappingJson ? { row_mapping: parseJsonObject(readFileIfPresent(options.rowMappingJson)) } : {}),
+            ...(readOption(options.cursorPath) ? { cursor_path: readOption(options.cursorPath) } : {}),
+            ...(readOption(options.cursorRequestKey) ? { cursor_request_key: readOption(options.cursorRequestKey) } : {}),
+            ...(maxPages !== undefined ? { max_pages: maxPages } : {}),
+            ...(readOption(options.upsertKey) ? { upsert_key: readOption(options.upsertKey) } : {}),
+        },
+        sync: {
+            ...(every ? { every } : {}),
+            ...(maxCreditsPerCycle !== undefined ? { max_credits_per_cycle: maxCreditsPerCycle } : {}),
+            ...(maxRowsPerCycle !== undefined ? { max_rows_per_cycle: maxRowsPerCycle } : {}),
+        },
+        ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+        ...(filters ? { filters } : {}),
+        ...(readOption(options.intentId) ? { intent_id: readOption(options.intentId) } : {}),
+        ...(readOption(options.inputShape) ? { input_shape: readOption(options.inputShape) } : {}),
+        ...(readOption(options.routeId) ? { route_id: readOption(options.routeId) } : {}),
+        ...(readOption(options.registryVersion) ? { registry_version: readOption(options.registryVersion) } : {}),
+        ...(options.sourcePrompt ? { source_prompt: readFileIfPresent(options.sourcePrompt) } : {}),
+        ...(options.approved ? { approved: true } : {}),
+    };
+}
+// `feeds bind` is one verb over two transports, told apart by --schema-json. Each
+// list names the flags that only mean something on one side, in help order, so a
+// flag from the other transport is refused by name instead of silently dropped.
+const FEED_BIND_PULL_ONLY_FLAGS = [
+    ["kind", "--kind"],
+    ["toolId", "--tool-id"],
+    ["toolIds", "--tool-ids"],
+    ["requestJson", "--request-json"],
+    ["rowsPath", "--rows-path"],
+    ["rowMappingJson", "--row-mapping-json"],
+    ["cursorPath", "--cursor-path"],
+    ["cursorRequestKey", "--cursor-request-key"],
+    ["maxPages", "--max-pages"],
+    ["every", "--every"],
+    ["maxCredits", "--max-credits"],
+    ["maxRows", "--max-rows"],
+    ["filtersJson", "--filters-json"],
+    ["intentId", "--intent-id"],
+    ["inputShape", "--input-shape"],
+    ["routeId", "--route-id"],
+    ["registryVersion", "--registry-version"],
+    ["sourcePrompt", "--source-prompt"],
+    ["approved", "--approved"],
+];
+const FEED_BIND_PUSH_ONLY_FLAGS = [
+    ["create", "--create"],
+    ["project", "--project"],
+    ["itemsPath", "--items-path"],
+    ["eventIdPath", "--event-id-path"],
+    ["eventTypePath", "--event-type-path"],
+    ["occurredAtPath", "--occurred-at-path"],
+    ["authMode", "--auth-mode"],
+];
+// The third mode: a WEB INTENT feed, named by source instead of configured.
+// OXYGEN's own receiver normalizes every reveal, so there is nothing to declare —
+// which is also why this list is the accepted values rather than a free string.
+const FEED_BIND_WEB_INTENT_SOURCES = ["rb2b"];
+// Everything a web-intent feed cannot carry, in help order. --create, --name and
+// --upsert-key are its only companions, so a flag belonging to either other mode
+// is refused here by name, one round trip before the server would refuse it.
+const FEED_BIND_WEB_INTENT_REFUSED_FLAGS = [
+    ["schemaJson", "--schema-json"],
+    ...FEED_BIND_PULL_ONLY_FLAGS,
+    ...FEED_BIND_PUSH_ONLY_FLAGS.filter(([key]) => key !== "create" && key !== "project"),
+];
+// Pull mode keeps the contract commander enforced when --kind/--tool-id/
+// --request-json were requiredOptions and <table> was required: same messages, same
+// order (mandatory options before the argument), same stderr + exit 1 path. They
+// stopped being commander-required only because a push feed must not carry them.
+function assertPullFeedBindArguments(table, options, command) {
+    for (const [key, flag] of FEED_BIND_PUSH_ONLY_FLAGS) {
+        if (options[key] !== undefined) {
+            command.error(`error: ${flag} belongs to a push feed; add --schema-json <json-or-file> to bind one, or drop ${flag} to bind a pull feed.`);
+        }
+    }
+    const required = [
+        ["kind", "--kind <kind>"],
+        ["toolId", "--tool-id <tool>"],
+        ["requestJson", "--request-json <json-or-file>"],
+    ];
+    for (const [key, flags] of required) {
+        if (options[key] === undefined) {
+            command.error(`error: required option '${flags}' not specified`, { code: "commander.missingMandatoryOptionValue" });
+        }
+    }
+    if (table === undefined) {
+        command.error("error: missing required argument 'table'", { code: "commander.missingArgument" });
+    }
+}
+// The push bind body mirrors the route's declared-schema reader: transport push, the
+// schema as an OBJECT (the server validates it against the table's real columns),
+// and exactly one of an existing table or create_table. Pull fields are refused here
+// by flag name, before any request, because the server would 400 on them anyway.
+function readFeedPushBindBody(table, options) {
+    for (const [key, flag] of FEED_BIND_PULL_ONLY_FLAGS) {
+        if (options[key] !== undefined) {
+            throw new OxygenError("invalid_table_feed", `${flag} belongs to a pull feed; a push feed is filled by whatever posts to its endpoint. Drop ${flag}, or drop --schema-json to bind a pull feed.`, { details: { flag }, exitCode: 1 });
+        }
+    }
+    const schemaSource = readOption(options.schemaJson);
+    if (!schemaSource) {
+        throw new OxygenError("invalid_json", "--schema-json needs a JSON Schema object, inline or a path to a JSON file.", { exitCode: 1 });
+    }
+    const rowSchema = parseJsonObject(readFileIfPresent(schemaSource));
+    const tableRef = readOption(table);
+    const create = readOption(options.create);
+    if (readOption(options.project) && !create)
+        throw new OxygenError("invalid_request", "--project requires --create; the existing table keeps its project.", { exitCode: 2 });
+    if (tableRef && create) {
+        throw new OxygenError("invalid_request", "Pass a table or --create <name>, not both.", { exitCode: 1 });
+    }
+    if (!tableRef && !create) {
+        throw new OxygenError("invalid_request", "Pass the table id or slug that receives the rows, or --create <name> to create the table from the schema.", { exitCode: 1 });
+    }
+    const authMode = readOption(options.authMode);
+    if (authMode && authMode !== "secret" && authMode !== "none") {
+        throw new OxygenError("invalid_request", "--auth-mode must be secret or none.", { details: { auth_mode: authMode }, exitCode: 1 });
+    }
+    return {
+        transport: "push",
+        row_schema: rowSchema,
+        ...(tableRef ? { table: tableRef } : { create_table: { name: create, ...(readOption(options.project) ? { project: readOption(options.project) } : {}) } }),
+        ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+        ...(readOption(options.upsertKey) ? { upsert_key: readOption(options.upsertKey) } : {}),
+        ...(readOption(options.itemsPath) ? { items_path: readOption(options.itemsPath) } : {}),
+        ...(readOption(options.eventIdPath) ? { event_id_path: readOption(options.eventIdPath) } : {}),
+        ...(readOption(options.eventTypePath) ? { event_type_path: readOption(options.eventTypePath) } : {}),
+        ...(readOption(options.occurredAtPath) ? { occurred_at_path: readOption(options.occurredAtPath) } : {}),
+        ...(authMode ? { auth_mode: authMode } : {}),
+    };
+}
+// The web-intent bind body: transport push plus the source as the feed kind, and
+// exactly one of an existing table or create_table. Nothing else is accepted —
+// the reveal shape, the address, and the (zero) cost are all fixed by OXYGEN's own
+// receiver — so every other flag is refused here by name, before any request.
+function readFeedWebIntentBindBody(table, options) {
+    const source = readOption(options.source);
+    if (!source || !FEED_BIND_WEB_INTENT_SOURCES.includes(source)) {
+        throw new OxygenError("invalid_request", `--source must be one of: ${FEED_BIND_WEB_INTENT_SOURCES.join(", ")}.`, { details: { source: source ?? null, accepted: [...FEED_BIND_WEB_INTENT_SOURCES] }, exitCode: 1 });
+    }
+    for (const [key, flag] of FEED_BIND_WEB_INTENT_REFUSED_FLAGS) {
+        if (options[key] !== undefined) {
+            throw new OxygenError("invalid_table_feed", `${flag} does not apply to a --source ${source} feed: its rows come from OXYGEN's own website-visit receiver with a fixed shape. Drop ${flag}, or drop --source to bind a pull or --schema-json feed.`, { details: { flag, source }, exitCode: 1 });
+        }
+    }
+    const tableRef = readOption(table);
+    const create = readOption(options.create);
+    if (readOption(options.project) && !create)
+        throw new OxygenError("invalid_request", "--project requires --create; the existing table keeps its project.", { exitCode: 2 });
+    if (tableRef && create) {
+        throw new OxygenError("invalid_request", "Pass a table or --create <name>, not both.", { exitCode: 1 });
+    }
+    if (!tableRef && !create) {
+        throw new OxygenError("invalid_request", "Pass the table id or slug that receives the reveals, or --create <name> to create the table with the fixed reveal columns.", { exitCode: 1 });
+    }
+    return {
+        transport: "push",
+        feed_kind: source,
+        ...(tableRef ? { table: tableRef } : { create_table: { name: create, ...(readOption(options.project) ? { project: readOption(options.project) } : {}) } }),
+        ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+        ...(readOption(options.upsertKey) ? { upsert_key: readOption(options.upsertKey) } : {}),
+    };
+}
+// Human receipt for a web-intent bind. There is no secret and no webhook URL to
+// print — this feed has no address — so what a reader needs instead is the table
+// the reveals land in, that they cost nothing, and the one precondition that
+// decides whether any row ever appears.
+function writeFeedWebIntentBindReceipt(data) {
+    if (!isRecord(data))
+        return;
+    const feed = isRecord(data.feed) ? data.feed : {};
+    const table = isRecord(feed.table) ? feed.table : {};
+    const lines = [];
+    const feedId = readRecordString(feed, "id");
+    lines.push(`Web intent feed "${readRecordString(feed, "name") ?? "unnamed"}"${feedId ? ` (${feedId})` : ""} bound: RB2B website-visit reveals now land as rows.`);
+    const tableName = readRecordString(table, "display_name");
+    const tableSlug = readRecordString(table, "slug") ?? readRecordString(table, "id");
+    if (tableName || tableSlug) {
+        lines.push(`  Table: ${tableName ?? tableSlug}${tableName && tableSlug ? ` (${tableSlug})` : ""}`);
+    }
+    const upsertKey = readRecordString(feed, "upsert_key");
+    if (upsertKey)
+        lines.push(`  Upserted on: ${upsertKey}`);
+    lines.push("  Cost: 0 credits per reveal. Every reveal also stays a website_visit Signal.");
+    lines.push("  Rows only start once RB2B is connected to this workspace; there is no self-serve connect step yet.");
+    const nextStep = readRecordString(data, "next_step");
+    if (nextStep)
+        lines.push(`  Next: ${nextStep}`);
+    const webUrl = readRecordString(data, "web_url") ?? readRecordString(data, "deepLink");
+    if (webUrl)
+        lines.push(`  ${webUrl}`);
+    process.stderr.write(`${lines.join("\n")}\n`);
+}
+// Human receipt for a push-feed bind, on stderr ahead of the payload (stdout stays
+// the machine JSON, like every other command). The secret is returned exactly once —
+// only its hash is stored — so it is printed with the warning right next to it.
+function writeFeedPushBindReceipt(data) {
+    if (!isRecord(data))
+        return;
+    const feed = isRecord(data.feed) ? data.feed : {};
+    const table = isRecord(feed.table) ? feed.table : {};
+    const lines = [];
+    const feedId = readRecordString(feed, "id");
+    lines.push(`Push feed "${readRecordString(feed, "name") ?? "unnamed"}"${feedId ? ` (${feedId})` : ""} bound: typed or rejected.`);
+    const tableName = readRecordString(table, "display_name");
+    const tableSlug = readRecordString(table, "slug") ?? readRecordString(table, "id");
+    if (tableName || tableSlug) {
+        lines.push(`  Table: ${tableName ?? tableSlug}${tableName && tableSlug ? ` (${tableSlug})` : ""}`);
+    }
+    const webhookUrl = readRecordString(data, "webhookUrl") ?? readRecordString(feed, "endpoint_url");
+    if (webhookUrl)
+        lines.push(`  Webhook URL: ${webhookUrl}`);
+    const secret = readRecordString(data, "secret");
+    if (secret) {
+        lines.push(`  Secret: ${secret}`);
+        lines.push("  This secret is shown once and never again: store it now. Senders pass it in the x-oxygen-table-webhook-secret header.");
+    }
+    else {
+        lines.push("  No secret (auth mode none): anyone holding the webhook URL can post.");
+    }
+    const schema = isRecord(data.row_schema) ? data.row_schema : isRecord(feed.row_schema) ? feed.row_schema : null;
+    const properties = schema && isRecord(schema.properties) ? schema.properties : {};
+    const required = new Set(schema && Array.isArray(schema.required) ? schema.required.filter((entry) => typeof entry === "string") : []);
+    const names = Object.keys(properties);
+    lines.push(`  Row schema (${names.length} propert${names.length === 1 ? "y" : "ies"}; a delivery that does not match is refused with 422):`);
+    for (const name of names) {
+        const property = properties[name];
+        const type = isRecord(property)
+            ? Array.isArray(property.type)
+                ? property.type.filter((entry) => typeof entry === "string").join("|")
+                : typeof property.type === "string" ? property.type : "any"
+            : "any";
+        lines.push(`    ${name}: ${type || "any"}${required.has(name) ? " (required)" : ""}`);
+    }
+    if (schema?.additionalProperties === false)
+        lines.push("    no other properties allowed");
+    lines.push("  Cost: 0 credits per delivery.");
+    const nextStep = readRecordString(data, "next_step");
+    if (nextStep)
+        lines.push(`  Next: ${nextStep}`);
+    const webUrl = readRecordString(data, "web_url") ?? readRecordString(data, "deepLink");
+    if (webUrl)
+        lines.push(`  ${webUrl}`);
+    process.stderr.write(`${lines.join("\n")}\n`);
+}
+export function registerFeedsFamily(program, handleAsyncAction) {
+    program
+        .command("feeds")
+        .description("Live tables: bind a scheduled provider harvest (a FEED) to a table so it keeps filling itself on a cadence, then inspect, pause, resume, run, or unbind it. A feed is part of Tables, not a new primitive — `oxygen tables webhook` is the inbound (push) half of the same ledger.")
+        .addCommand(addFeedReadFlags(new Command("list")
+        .description("List table feeds for the workspace, newest first. Optional summary/full windows resume with next-offset; exact settings use feeds get --projection value. Read-only.")
+        .argument("[table]", "Optional table id or slug to filter by.")
+        .option("--table <table>", "Table id or slug. Equivalent to the positional argument.")
+        .option("--transport <transport>", "pull (scheduled provider harvest) or push (inbound webhook).")
+        .option("--status <status>", "Filter by active or disabled.")
+        .option("--state <state>", "Filter by run state: idle, running, error, or exhausted.")
+        .option("--limit <n>", "Maximum feeds to return (1-200). Defaults to 50.")
+        .option("--include-cursor", "Include the opaque provider page token in the cursor block.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => handleAsyncAction("feeds list", options, () => requestOxygen(feedsListPath(options, table))))))
+        .addCommand(addFeedReadFlags(new Command("get")
+        .description("Get one table feed. Optional summary or lossless value JSON windows recover every public setting; resume value-cursor with the same feed/path/include-cursor. Read-only.")
+        .argument("<feed>", "Feed id or endpoint id.")
+        .option("--include-route", "Include the complete frozen request and fallback lanes for an in-place update.")
+        .option("--include-cursor", "Include the opaque provider page token in the cursor block.")
+        .option("--json", "Print a JSON envelope.")
+        .action((feed, options) => handleAsyncAction("feeds get", options, () => requestOxygen(feedsGetPath(feed, options)))), true))
+        .addCommand(new Command("bind")
+        .description("Bind a feed to a table: a scheduled provider harvest (pull), with --schema-json a typed-or-rejected push feed, or with --source rb2b the web-intent feed landing RB2B website-visit reveals as rows. A pull feed freezes the provider request into an existing table, then optionally arms a cadence so the table refills itself; arming a cadence on a paid provider is a STANDING spend grant — it requires --every, --max-credits, and --approved together, and without --every the feed is stored disarmed until you set one. A push feed is free: it returns a webhook URL and a secret shown once, refuses a delivery that does not match the schema with HTTP 422 (recorded in `oxygen feeds deliveries`, nothing written), and can create its table from the schema with --create <name>. `--source rb2b` is the web intent feed: OXYGEN already receives your RB2B website-visit reveals and records each one as a website_visit Signal, and this feed ALSO lands them as rows you can enrich, score, and sequence. It has no address, no schema, and no cadence to configure — the reveal shape is fixed — so binding is free and each reveal costs 0 credits on arrival. If RB2B is not connected to this workspace yet, rows only start once it is; there is no self-serve connect step yet.")
+        .argument("[table]", "Table id or slug that receives the rows. Required for a pull feed; a push or web-intent feed takes it or --create <name>.")
+        .option("--kind <kind>", "Pull feed, required. Feed kind: company_search or signal_search.")
+        .option("--tool-id <tool>", "Pull feed, required. Provider tool id the cycle calls, e.g. blitzapi.job_search.")
+        .option("--request-json <json-or-file>", "Pull feed, required. Provider request JSON for the tool, inline or a path to a JSON file. Take it from the plan route's `request`.")
+        .option("--schema-json <json-or-file>", "Bind a PUSH feed instead: the JSON Schema (an object with type, properties, required, additionalProperties) every delivered row must match, inline or a path to a JSON file.")
+        .option("--source <source>", `Bind a WEB INTENT push feed instead: ${FEED_BIND_WEB_INTENT_SOURCES.join(", ")} (rb2b = the website-visit reveals OXYGEN already receives for this workspace, also kept as website_visit Signals). Fixed row shape, no schema, no cadence, 0 credits per reveal. Takes a table or --create <name>, plus --name and --upsert-key.`)
+        .option("--create <name>", "Push or web-intent feed only. Create a new table with this name — its columns derived from --schema-json, or the fixed reveal columns for --source rb2b — instead of binding an existing table.")
+        .option("--project <project>", "Workspace project id or slug for the new --create table.")
+        .option("--items-path <path>", "Push feed only. Dot path to an array of row objects in the delivered payload.")
+        .option("--event-id-path <path>", "Push feed only. Dot path to the event id. Defaults to event_id, eventId, id, or a payload hash.")
+        .option("--event-type-path <path>", "Push feed only. Dot path to the event type. Defaults to type or event.")
+        .option("--occurred-at-path <path>", "Push feed only. Dot path to the event timestamp.")
+        .option("--auth-mode <mode>", "Push feed only. secret (default: senders include the returned secret in x-oxygen-table-webhook-secret) or none.")
+        .option("--tool-ids <csv>", "Comma-separated cascade of tool ids to try in order. Defaults to just --tool-id.")
+        .option("--rows-path <path>", "Dot path to the row array in the provider response.")
+        .option("--row-mapping-json <json-or-file>", "Row mapping JSON: table column key -> provider field path.")
+        .option("--cursor-path <path>", "Dot path to the next-page cursor in the provider response.")
+        .option("--cursor-request-key <key>", "Request key that receives the next cursor.")
+        .option("--max-pages <n>", "Maximum provider pages per cycle. Defaults to 1.")
+        .option("--upsert-key <key>", "Column key rows are upserted on, so a cycle or a repeated delivery updates instead of duplicating.")
+        .option("--name <name>", "Display name for the feed.")
+        .option("--every <sugar>", CADENCE_FLAG_DESCRIPTION)
+        .option("--max-credits <n>", "Credit ceiling PER sync cycle. Required with --approved to arm a cadence on a paid provider.")
+        .option("--max-rows <n>", "Advisory row ceiling per cycle, recorded on every cycle's run provenance.")
+        .option("--filters-json <json-or-file>", "Typed filters JSON recorded on the feed for provenance and re-planning.")
+        .option("--intent-id <id>", "Routing-registry intent id from the plan.")
+        .option("--input-shape <shape>", "Routing-registry input shape from the plan, e.g. market or watch_list.")
+        .option("--route-id <id>", "Route id from the plan this feed was bound from.")
+        .option("--registry-version <version>", "Routing-registry revision from the plan, retained with the frozen feed provenance.")
+        .option("--source-prompt <text-or-file>", "The prompt this feed was planned from, or a path to a prompt file.")
+        .option("--approved", "Approve the recurring paid pull. Required with --every and --max-credits on a paid provider.")
+        .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", `
+Examples:
+  oxygen feeds bind signal-events --kind signal_search --tool-id blitzapi.job_search --request-json ./request.json --every daily@9 --max-credits 25 --approved
+  oxygen feeds bind --create "Inbound leads" --schema-json '{"type":"object","properties":{"email":{"type":"string"},"score":{"type":"number"}},"required":["email"],"additionalProperties":false}' --upsert-key email
+  oxygen feeds bind --source rb2b --create "Website visitors"
+`)
+        .action((table, options, command) => {
+        const webIntent = options.source !== undefined;
+        const push = options.schemaJson !== undefined;
+        // Pull usage errors keep commander's exact wording and path (stderr, exit 1),
+        // raised before any request exactly as the former requiredOption/<table> did.
+        if (!push && !webIntent)
+            assertPullFeedBindArguments(table, options, command);
+        return handleAsyncAction("feeds bind", options, async () => {
+            if (webIntent) {
+                const data = await requestOxygen("/api/cli/tables/feeds", {
+                    method: "POST",
+                    body: readFeedWebIntentBindBody(table, options),
+                });
+                // Nothing is withheld from stdout here (a web-intent feed has no
+                // secret and no address); the receipt exists so a human reads the
+                // table, the 0-credit cost, and what has to be true for rows to land.
+                if (!options.json)
+                    writeFeedWebIntentBindReceipt(data);
+                return data;
+            }
+            if (!push) {
+                return requestOxygen("/api/cli/tables/feeds", {
+                    method: "POST",
+                    body: readFeedBindBody(table, options),
+                });
+            }
+            const data = await requestOxygen("/api/cli/tables/feeds", {
+                method: "POST",
+                body: readFeedPushBindBody(table, options),
+            });
+            // Ahead of the payload, and only for a human: the secret is shown once,
+            // so it must not scroll away inside the JSON. A machine caller reads it
+            // off the envelope.
+            if (!options.json)
+                writeFeedPushBindReceipt(data);
+            return data;
+        });
+    }))
+        .addCommand(addContractFlags(new Command("update")
+        .description("Update an existing feed in place. Inspect feeds get --include-route first. Source replacement resets its cursor; cadence, cap and source changes keep native standing authorization and budget checks. Configuration spends nothing.")
+        .argument("<feed>", "Feed id or endpoint id.")
+        .option("--json", "Print a JSON envelope."), TABLE_FEED_UPDATE_CONTRACT, {
+        feed: { omit: true }, sync: { flatten: true },
+        "sync.max_credits_per_cycle": { flag: "max-credits" },
+        "sync.max_rows_per_cycle": { flag: "max-rows" },
+        approved: { noNegate: true },
+    })
+        .action((feed, options) => handleAsyncAction("feeds update", options, () => {
+        const body = { ...readContractFlags(options, TABLE_FEED_UPDATE_CONTRACT, {
+                feed: { omit: true }, sync: { flatten: true },
+                "sync.max_credits_per_cycle": { flag: "max-credits" },
+                "sync.max_rows_per_cycle": { flag: "max-rows" }, approved: { noNegate: true },
+            }), feed };
+        const errors = tableFeedUpdateIssues(body);
+        if (errors.length)
+            throw new OxygenError("invalid_request", errors.join(" "), { exitCode: 1 });
+        return requestOxygen("/api/cli/tables/feeds", { method: "PATCH", body });
+    })))
+        .addCommand(new Command("pause")
+        .description("Pause a feed: the cron stays armed but every cycle it fires is refused, so nothing is fetched and nothing is billed until you resume. Free.")
+        .argument("<feed>", "Feed id or endpoint id.")
+        .option("--json", "Print a JSON envelope.")
+        .action((feed, options) => handleAsyncAction("feeds pause", options, () => requestOxygen("/api/cli/tables/feeds", {
+        method: "PATCH",
+        body: { feed, status: "disabled" },
+    }))))
+        .addCommand(new Command("resume")
+        .description("Resume a feed: re-activates it AND clears an error/exhausted stop, so the next cron tick can claim it again. Re-uses the cadence and spend cap already approved at bind time. Free.")
+        .argument("<feed>", "Feed id or endpoint id.")
+        .option("--json", "Print a JSON envelope.")
+        .action((feed, options) => handleAsyncAction("feeds resume", options, () => requestOxygen("/api/cli/tables/feeds", {
+        method: "PATCH",
+        // A feed that stopped itself (run_state error/exhausted) is
+        // deliberately unclaimable by the cron. Clearing the state here is
+        // the only way back, so `resume` does both or it is not a resume.
+        body: { feed, status: "active", run_state: "idle" },
+    }))))
+        .addCommand(new Command("run")
+        .description("Run one sync cycle now through the feed's own cron workflow (one harvest path, one cursor). --mode dry_run (default) renders the exact next-cycle provider request with the cursor or watermark already injected, for free. --mode live spends credits and requires --approved and --max-credits.")
+        .argument("<feed>", "Feed id or endpoint id.")
+        .option("--mode <mode>", "dry_run or live. Defaults to dry_run.")
+        .option("--max-credits <n>", "Required credit ceiling for a live cycle.")
+        .option("--approved", "Required for a live cycle after inspecting the dry run.")
+        .option("--json", "Print a JSON envelope.")
+        .action((feed, options) => {
+        const maxCredits = readPositiveNumber(options.maxCredits);
+        return handleAsyncAction("feeds run", options, () => requestOxygen("/api/cli/tables/feeds/run", {
+            method: "POST",
+            body: {
+                feed,
+                ...(readOption(options.mode) ? { mode: readOption(options.mode) } : {}),
+                ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                ...(options.approved ? { approved: true } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("deliveries")
+        .description("List the shared table delivery ledger: pull-feed sync cycles and inbound webhook deliveries land in the same place. Filter by --table (the identifier `feeds list` gives you) or by a webhook endpoint id. Read-only.")
+        .argument("[endpoint_id]", "Optional webhook endpoint id, such as tw_...")
+        .option("--table <table>", "Table id or slug whose ledger to read.")
+        .option("--status <status>", "Filter by received, completed, failed, or rejected (rejected = arrived while the feed was paused and was turned away; no rows written). A delivery refused with HTTP 429 for exceeding the plan's rate is not recorded here: the sender redelivers it.")
+        .option("--limit <n>", "Maximum deliveries to return. Defaults to 50.")
+        .option("--json", "Print a JSON envelope.")
+        .action((endpointId, options) => handleAsyncAction("feeds deliveries", options, () => requestOxygen(tableWebhookDeliveriesPath({
+        endpointId,
+        table: options.table,
+        status: options.status,
+        limit: options.limit,
+    })))))
+        .addCommand(new Command("unbind")
+        .description("Delete a feed: removes its cron FIRST, then the feed row. The table and every row it already wrote are kept.")
+        .argument("<feed>", "Feed id or endpoint id.")
+        .option("--json", "Print a JSON envelope.")
+        .action((feed, options) => handleAsyncAction("feeds unbind", options, () => requestOxygen("/api/cli/tables/feeds", {
+        method: "DELETE",
+        body: { feed },
+    }))));
+}

package/dist/commands/find.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerFindFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;