@wrangled/cli 0.3.23 → 0.3.25

package/dist/api.js

@@ -16,6 +16,11 @@ export class UnreadableCredentialsError extends CliError {
         super(`The saved credentials at ${path} are unreadable. Run \`${brand.slug} login\` again.`, exitCodes.auth);
     }
 }
+/**
+ * The grammar fields library entries are tagged with, and the CLI flag for each; the server's list is entryTagFields
+ * in src/lib/knowledge/tags.ts. format's flag is --ad-format, because --format picks the output.
+ */
+export const entryTagFlags = { angle: "angle", hook_kind: "hook-kind", format: "ad-format", awareness: "awareness" };
 /** Copies of the server's IMPORT_LIMITS and import name rule; src/lib/cli-consistency.test.ts keeps them in step. */
 export const IMPORT_LIMITS = { bytes: 50 * 1024 * 1024, rows: 1_000_000, columns: 500 };
 export const IMPORT_NAME_PATTERN = /^[a-z][a-z0-9_]{0,40}$/;

package/dist/guide.js

@@ -20,6 +20,10 @@ Run \`${cli} guide\` first. It says, in plain words, what this workspace has. It
 
 Before writing new ads or a campaign plan, run \`${cli} brief\`. In one read it gives the offer (from the confirmed offers and funnels map, else the brand notes and landing pages, or it says the offer is unknown), the brand voice, the best ads by spend and by results with their words and a piece of their video transcript, the ads to avoid repeating, the pages those ads send people to, the funnel and top campaigns, who the top Facebook campaigns were aimed at, and what is missing. \`--from\` and \`--to\` pick the dates (default: the last 30 days), \`--channel\` or \`--campaign <id>\` narrow it, and \`--top <n>\` sets how many of each list it shows (default 5, at most 20). It prints plain Markdown to paste into a prompt; \`--format json\` gives the same brief as data. It says what it cut to stay short.
 
+## Which Facebook ads won: winners and flops
+
+\`${cli} winners\` says which Facebook ads won and which flopped, for one Monday-to-Sunday week and for the 30 days ending that Sunday, judged on real sales: each sale goes to the Facebook ad that first brought the buyer in, and payments typed into GoHighLevel by hand never count toward an ad. An ad with no sales that has spent less than twice the account's cost per sale is too new to judge on sales, so it is judged on cost per sign-up and listed apart. Each ad says in a sentence why it is on its list. \`--week <YYYY-MM-DD>\` picks any day of the week (default: the latest complete week), \`--top <n>\` how many ads each list shows (default 5, at most 20), and \`--format json\` gives the report as data.
+
 ## Content: search before SQL
 
 To find content, such as "the 10 emails with the best click rate", "our 5 best videos by return on ad spend" or "every landing page that mentions the guarantee", use \`${cli} content search\` before writing SQL on the \`content_\` tables.
@@ -40,6 +44,8 @@ For what has worked for others, such as "how do members test new hooks" or "what
 - The question is 1 to 4000 characters. \`--limit\` is 1 to 12 (default 5). \`--kind\` (message, transcript, document, note) keeps one kind of source. \`--library <slug>\` keeps one library.
 - \`--library meta-policy\` searches Meta's own advertising standards, copied from Meta's site every Monday. Before you write or judge an ad, check its claims there, such as income, health or before-and-after claims: \`${cli} knowledge search --library meta-policy "income claims"\`. Its evidence is \`meta_published_policy\`, Meta's published rule; Meta's reviewers still decide each ad.
 - \`knowledge_not_synced\` means the library has not been copied into this server yet, so nothing was searched; the weekly sync fills it.
+- Library entries carry the marketing grammar's tags: \`--angle\`, \`--hook-kind\`, \`--ad-format\` and \`--awareness\` (the ad tag fields angle, hook_kind, format and awareness, with the same values). Give any of them to keep to entries tagged that way; the question is then optional, and without one the entries come surest tags first. With a tag filter the answer also lists this workspace's own Meta ads whose live tags hold the same values, with their lifetime spend and results, biggest spend first (at most 20): what the library says next to how it went for this client.
+- Each result shows its entry id and tags. Tag an entry you read with \`${cli} knowledge tag <entry-id> --hook-kind big_win --confidence medium\` (several flags at once is fine), take a wrong tag off with \`--remove\`, or tag a batch with \`${cli} knowledge tag --file tags.json\`, where the file is \`{"tags": [{"entry_id", "field", "value", "confidence"}]}\` (up to 500; \`"remove": true\` in place of confidence takes one off). Values off the grammar's list are refused.
 
 ## Query workflow: schema first
 
@@ -240,9 +246,11 @@ A scheduled hand's run acts as its skill's agent, the way the Facebook ads agent
 ${cli} login                        validate a key (prompted, piped, or ${envPrefix}_API_KEY) and save it
 ${cli} logout                       delete saved credentials
 ${cli} whoami                       show the current workspace and library access
-${cli} knowledge search "<question>" [--limit <n>] [--kind <kind>]   short, cited snippets from the Creative Cartel know-how library (keys with library access)
+${cli} knowledge search "<question>" [--limit <n>] [--kind <kind>] [--hook-kind <v> ...]   short, cited snippets from the know-how libraries (keys with library access)
+${cli} knowledge tag <entry-id> --hook-kind <v> --confidence <c>   tag a library entry with the marketing grammar (or --file tags.json)
 ${cli} guide                        what this workspace's data holds, how fresh it is, and what is missing: read it first
 ${cli} brief [--from <date>] [--to <date>] [--channel <channel>] [--campaign <id>] [--top <n>]   the offer, voice, best and worst ads, pages, results and audience: start here before writing ads
+${cli} winners [--week <date>] [--top <n>]   which Facebook ads won and flopped this week and over 30 days, judged on first-touch sales
 ${cli} warehouse schema [--summary] [--table <name> ...] [--search <words>]   list tables and columns; --summary for one row per table
 ${cli} warehouse query "<sql>"      run one read-only query (or --file <path>, or stdin); --out <file.csv | file.ndjson | file.json> saves the rows; add --all for every row
 ${cli} funnel [--from <date>] [--to <date>] [--grain day|week|month]   spend, leads, calls and sales per period, with totals

package/dist/main.js

@@ -4,12 +4,13 @@ import { mkdir, readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { api, ApiError, apiDownload, apiText, apiUpload, CliError, exitCodes, getSigned, IMPORT_LIMITS, IMPORT_NAME_PATTERN, putSigned, readCredentials, removeCredentials, resolveApiUrl, resolveConnection, UnreadableCredentialsError, writeCredentials, streamSigned, } from "./api.js";
+import { api, ApiError, apiDownload, apiText, apiUpload, CliError, exitCodes, getSigned, IMPORT_LIMITS, IMPORT_NAME_PATTERN, putSigned, readCredentials, removeCredentials, resolveApiUrl, resolveConnection, UnreadableCredentialsError, writeCredentials, entryTagFlags, streamSigned, } from "./api.js";
 import { brand, envPrefix } from "./brand.js";
 import { firstSymlink, inRunFolder, writeFileAtomic } from "./files.js";
 import { guide, skill } from "./guide.js";
 import { PULL_STATE_FILE, pullContent } from "./pull.js";
 import { AGENTS_MD_MARKER, metaAdsAgentsMd, PLAYBOOK_CHOICES, playbooks } from "./playbooks.js";
+import { OPENROUTER_KEY_ENV } from "./runner/codex.js";
 import { AGENT_ENV, HARNESS_COMMAND_ENV, RUNNER_TOKEN_ENV, runLoop, runOnce } from "./runner/run.js";
 import { SKILL_NAME_PATTERN } from "./skill-zip.js";
 import { installSkillFolder, operatorConnection, packSkill, parseSkillRef, readSkillFolder, unpackSkill, } from "./skills.js";
@@ -56,23 +57,55 @@ const commands = {
         },
     },
     "knowledge search": {
-        usage: 'knowledge search "<question>" [--limit <n>] [--kind message|transcript|document|note] [--library <slug>]',
+        usage: 'knowledge search ["<question>"] [--limit <n>] [--kind message|transcript|document|note] [--library <slug>] [--angle <v>] [--hook-kind <v>] [--ad-format <v>] [--awareness <v>]',
         async run(args, options) {
-            if (args.length !== 1)
-                throw new CliError('Usage: knowledge search "<question>" [--limit <n>] [--kind <kind>] [--library <slug>]; put the question in quotes', exitCodes.usage);
-            const query = new URLSearchParams({ q: args[0] });
+            const filters = Object.entries(options.entryTags);
+            if (args.length > 1 || (args.length === 0 && filters.length === 0)) {
+                throw new CliError('Usage: knowledge search "<question>" [--limit <n>] [--kind <kind>] [--library <slug>] [--angle <v>] [--hook-kind <v>] [--ad-format <v>] [--awareness <v>]; put the question in quotes, or give a tag filter', exitCodes.usage);
+            }
+            const query = new URLSearchParams(args[0] === undefined ? {} : { q: args[0] });
             if (options.limit !== undefined)
                 query.set("limit", options.limit);
             if (options.kind !== undefined)
                 query.set("kind", options.kind);
             if (options.library !== undefined)
                 query.set("library", options.library);
-            const { results } = await api(await resolveConnection(options.apiUrl), `/api/v1/knowledge/search?${query}`);
+            for (const [field, value] of filters)
+                query.set(field, value);
+            const answer = await api(await resolveConnection(options.apiUrl), `/api/v1/knowledge/search?${query}`);
             if (options.format === "json")
-                return printJson({ results });
-            if (results.length === 0)
-                return console.log("Nothing in the library matched.");
-            console.log(results.map(knowledgeBlock).join("\n\n"));
+                return printJson(answer);
+            console.log(answer.results.length === 0 ? "Nothing in the library matched." : answer.results.map(knowledgeBlock).join("\n\n"));
+            if (answer.yourAds === undefined)
+                return;
+            const tagged = filters.map(([field, value]) => `${field} ${value}`).join(", ");
+            if (answer.yourAds.length === 0)
+                return console.log(`\nNone of your ads is tagged ${tagged}.`);
+            console.log(`\nYour ads tagged ${tagged}, biggest spend first:`);
+            console.log(renderTable(["ad", "name", "tags", "spend", "results"], answer.yourAds.map(yourAdRow)));
+        },
+    },
+    "knowledge tag": {
+        usage: "knowledge tag <entry-id> [--angle <v>] [--hook-kind <v>] [--ad-format <v>] [--awareness <v>] --confidence high|medium|low [--remove] | --file <tags.json>   tag library entries with the marketing grammar",
+        async run(args, options) {
+            const usage = "Usage: knowledge tag <entry-id> [--angle <v>] [--hook-kind <v>] [--ad-format <v>] [--awareness <v>] --confidence high|medium|low [--remove], or knowledge tag --file <tags.json>";
+            const filters = Object.entries(options.entryTags);
+            if (args.length > 1 || (args.length === 1 && filters.length === 0))
+                throw new CliError(usage, exitCodes.usage);
+            const body = args.length === 1
+                ? {
+                    tags: filters.map(([field, value]) => ({
+                        entry_id: args[0],
+                        field,
+                        value,
+                        ...(options.remove ? { remove: true } : { confidence: options.confidence }),
+                    })),
+                }
+                : await readToolInput(options);
+            const result = await api(await resolveConnection(options.apiUrl), KNOWLEDGE_TAGS_PATH, body);
+            if (options.format === "json")
+                return printJson(result);
+            console.log(`Tagged ${result.tagged}, took off ${result.removed}.`);
         },
     },
     "warehouse schema": {
@@ -609,6 +642,21 @@ const commands = {
             process.stdout.write(brief.text);
         },
     },
+    winners: {
+        usage: "winners [--week <YYYY-MM-DD>] [--top <n>]   (which Facebook ads won and flopped, judged on real first-touch sales)",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: winners [--week <date>] [--top <n>]", exitCodes.usage);
+            const query = new URLSearchParams();
+            for (const [name, value] of Object.entries({ week: options.week, top: options.top }))
+                if (value !== undefined)
+                    query.set(name, value);
+            const report = await api(await resolveConnection(options.apiUrl), `/api/v1/winners${query.size ? `?${query}` : ""}`);
+            if (options.format === "json")
+                return printJson(report);
+            process.stdout.write(winnersText(report));
+        },
+    },
     examples: {
         usage: "examples   (plain questions with SQL that answers them, for the tables this workspace has)",
         async run(args, options) {
@@ -1209,6 +1257,8 @@ const commands = {
                 console.log(`Failed for ${failure.adIds.join(", ")}: ${failure.error}`);
             if (result.stopped === "tool_cap")
                 console.log("Stopped early: the run's tool spending cap was reached.");
+            if (result.nothingToRead > 0)
+                console.log(`Left out ${plural(result.nothingToRead)} with nothing to read: no copy, headline, transcript or picture description.`);
         },
     },
     "content tags": {
@@ -1693,6 +1743,7 @@ async function withRunner(options, work) {
             apiUrl: resolveApiUrl(options.apiUrl, null),
             token,
             harnessCommand: process.env[HARNESS_COMMAND_ENV] || undefined,
+            openRouterKey: process.env[OPENROUTER_KEY_ENV] || undefined,
             maxSeconds: options.maxSeconds,
             signal: stop.signal,
             say: (line) => console.log(line),
@@ -1769,6 +1820,59 @@ const CAMPAIGN_NUMBERS = [
     "roas_first_touch",
     "roas_last_touch",
 ];
+function money(value, currency) {
+    try {
+        return new Intl.NumberFormat("en-US", { style: "currency", currency }).format(value);
+    }
+    catch {
+        return `${value.toFixed(2)} ${currency}`;
+    }
+}
+const counted = (n, one) => `${n} ${n === 1 ? one : `${one}s`}`;
+/** An ad's line: name, SKU and campaign, its numbers, its tags, then why it is on the list. */
+function winnersAdLines(ad, currency) {
+    const n = ad.numbers;
+    const onSales = ad.judgedOn === "sales";
+    const cost = onSales
+        ? n.costPerSale === null ? "no sales" : `${money(n.costPerSale, currency)} per sale`
+        : n.costPerSignup === null ? "no sign-ups" : `${money(n.costPerSignup, currency)} per sign-up`;
+    const name = [ad.name ?? `Ad ${ad.adId}`, ad.sku && `[${ad.sku}]`, ad.campaignName && `(${ad.campaignName})`].filter(Boolean).join(" ");
+    const tags = Object.entries(ad.tags).map(([field, value]) => `${field}: ${value}`).join(", ");
+    const count = onSales ? n.sales !== null && counted(n.sales, "sale") : n.signups !== null && counted(n.signups, "sign-up");
+    return `- ${name}: spent ${money(n.spend, currency)}, ${count ? `${count}, ` : ""}${cost}${tags ? `. Tags: ${tags}` : ""}\n  ${ad.pickedBecause}\n`;
+}
+function winnersWindowText(title, window) {
+    const head = `\n## ${title}, ${window.from} to ${window.to}\n`;
+    if (window.sections.length === 0)
+        return `${head}\nNo Facebook ad spent in these dates.\n`;
+    return (head +
+        window.sections
+            .map((s) => {
+            const list = (heading, ads) => `\n${heading}\n${ads.length === 0 ? "- none\n" : ads.map((ad) => winnersAdLines(ad, s.currency)).join("")}`;
+            const account = s.salesSource === "not_connected"
+                ? "sales are not connected"
+                : s.accountCostPerSale === null
+                    ? "no sale credited to a Facebook ad in these dates"
+                    : `the account paid ${money(s.accountCostPerSale, s.currency)} per sale`;
+            const tests = s.tests.map((t) => `- Test ${t.testId}${t.hypothesisId ? ` (idea ${t.hypothesisId})` : ""}: ${counted(t.ads.length, "ad")}, spent ${money(t.spend, s.currency)}, ${counted(t.sales, "sale")}` +
+                `${t.costPerSale === null ? "" : `, ${money(t.costPerSale, s.currency)} per sale`}\n`);
+            return (`\nIn ${s.currency}: ${account}. ${s.adsJudgedOnSales} judged on sales, ${s.adsJudgedOnSignups} judged on sign-ups.\n` +
+                s.notes.map((note) => `${note}\n`).join("") +
+                list("Winners", s.winners) +
+                list("Flops", s.flops) +
+                list(`${s.onSignups.title}: best`, s.onSignups.best) +
+                list(`${s.onSignups.title}: worst`, s.onSignups.worst) +
+                (tests.length > 0 ? `\nAdzara tests\n${tests.join("")}` : ""));
+        })
+            .join(""));
+}
+/** The winners report as plain Markdown: what a sale means, then this week and the last 30 days, each currency apart. */
+function winnersText(report) {
+    return (`# Winners and flops for ${report.workspace}\n\n` +
+        `A sale means ${report.saleMeans}. Each sale goes to the Facebook ad that first brought the buyer in; payments typed into GoHighLevel by hand never count toward an ad.\n` +
+        winnersWindowText("This week", report.week) +
+        winnersWindowText("Last 30 days", report.last30Days));
+}
 function reportQuery(options, extra) {
     const query = new URLSearchParams();
     for (const [name, value] of Object.entries({ from: options.from, to: options.to, ...extra }))
@@ -1795,6 +1899,7 @@ function printReport(title, report, labels, numbers) {
 const agentPath = (options) => `/api/v1/agents/${encodeURIComponent(options.agent)}`;
 const FACTS_PATH = "/api/v1/facts";
 const AD_TAGS_PATH = "/api/v1/ad-tags";
+const KNOWLEDGE_TAGS_PATH = "/api/v1/knowledge/tags";
 const AD_AUTOTAG_PATH = "/api/v1/ad-tags/autotag";
 const SKIP_REASONS = { not_marketing: "Not marketing, so only that answer was saved", gate_unclear: "Could not tell whether it is marketing, so only that was saved", no_content: "Nothing to read", not_found: "No such ad" };
 const AD_TAG_COLUMNS = ["id", "ad", "status", "confidence", "offer", "persona", "angle", "hook", "format", "author"];
@@ -1816,8 +1921,16 @@ function knowledgeBlock(r, i) {
     lines.push(`   ${r.snippet}`);
     if (r.caveat)
         lines.push(`   Caveat: ${r.caveat}`);
+    if (r.entryId) {
+        const tags = Object.entries(r.tags ?? {}).flatMap(([field, values]) => values.map((value) => `${field} ${value}`));
+        lines.push(`   Entry ${r.entryId}${tags.length > 0 ? `, tagged ${tags.join(", ")}` : ""}`);
+    }
     return lines.join("\n");
 }
+function yourAdRow(a) {
+    const results = a.results === null ? null : `${a.results} ${a.resultType ?? ""}`.trim();
+    return { ad: a.adId, name: a.adName, tags: `${a.tagStatus}, ${a.tagConfidence}`, spend: a.spend === null ? null : `${a.spend.toFixed(2)} ${a.currency ?? ""}`.trim(), results };
+}
 function adTagRow(t) {
     const { offer_key, persona, angle, hook_kind, hook_spot, format, style } = t.tags;
     return { id: t.id, ad: t.adId, status: t.status, confidence: t.confidence, offer: offer_key, persona, angle, hook: [hook_kind, hook_spot].filter(Boolean).join(" in ") || null, format: [format, style].filter(Boolean).join(", ") || null, author: t.author };
@@ -1915,7 +2028,8 @@ Options:
   --channel <channel>   only this channel's campaigns (and, with brief, its ads): meta, google, affiliate, a utm_source, unknown or recorded_in_crm;
                         for content track-link, where the link goes: facebook, email, sms or web (default)
   --campaign <id>       the campaign content track-link puts in utm_campaign; with brief, the one campaign it covers
-  --top <n>             how many best ads, worst ads, pages and campaigns brief shows (default: 5, at most 20)
+  --top <n>             how many best ads, worst ads, pages and campaigns brief shows, or ads in each winners list (default: 5, at most 20)
+  --week <YYYY-MM-DD>   any day of the week winners covers, Monday to Sunday (default: the latest complete week)
   --body, --html <text | @file>   the words, or the full HTML, content create, capture and edit save
   --file <path>         an image, video or audio file, up to 50 MB, content create, capture and edit save; repeat for several
   --transcript <text | @file>   what is said in the first video or audio file content capture saves, so none is paid for
@@ -1949,6 +2063,10 @@ Options:
   --limit <n>           how many results content search, creatives list, campaigns, voice, ads tags, content tags and content to-check
                         return, or how many ads ads autotag tags and how many items content autotag tags
   --library <slug>      with knowledge search, only this library: creative-cartel, exodus or meta-policy
+  --angle, --hook-kind, --ad-format, --awareness <value>   with knowledge search, only library entries tagged that way, and
+                        your own ads tagged the same way with their results; with knowledge tag, the tags to put on an entry
+  --confidence high|medium|low   with knowledge tag, how sure you are of the tags
+  --remove              with knowledge tag, take the tags off instead
   --ad <id>             with ads tags, only this Meta ad's tags; with ads autotag, only this ad
   --kind email|text|page   with content tags and content autotag, only that kind (content autotag takes a comma list)
   --max-seconds <n>     stop a runner's run after this many seconds, if that comes before its deadline
@@ -2007,6 +2125,7 @@ function parseOptions(argv) {
             channel: { type: "string" },
             campaign: { type: "string" },
             top: { type: "string" },
+            week: { type: "string" },
             name: { type: "string" },
             subject: { type: "string" },
             preview: { type: "string" },
@@ -2048,6 +2167,12 @@ function parseOptions(argv) {
             step: { type: "string" },
             workspace: { type: "string" },
             "max-seconds": { type: "string" },
+            angle: { type: "string" },
+            "hook-kind": { type: "string" },
+            "ad-format": { type: "string" },
+            awareness: { type: "string" },
+            confidence: { type: "string" },
+            remove: { type: "boolean", default: false },
             help: { type: "boolean", short: "h", default: false },
         },
     });
@@ -2103,6 +2228,7 @@ function parseOptions(argv) {
             channel: values.channel,
             campaign: values.campaign,
             top: values.top,
+            week: values.week,
             name: values.name,
             subject: values.subject,
             preview: values.preview,
@@ -2144,6 +2270,9 @@ function parseOptions(argv) {
             step: values.step,
             workspace: values.workspace,
             maxSeconds,
+            entryTags: Object.fromEntries(Object.entries(entryTagFlags).flatMap(([field, flag]) => (values[flag] === undefined ? [] : [[field, values[flag]]]))),
+            confidence: values.confidence,
+            remove: values.remove,
         },
     };
 }

package/dist/playbooks.js

@@ -864,11 +864,11 @@ ${cli} ads autotag --limit ${BACK_TAG_BATCH} --json > batch.json
 
 Each call takes the ${BACK_TAG_BATCH} biggest-spending ads with no tags yet, so the next call moves on to the next ones. Open \`batch.json\` after each one. An ad Jev says is not marketing (\`not_marketing\`), or can't tell about (\`gate_unclear\`), is listed under \`skipped\` but was saved with only that answer, so it counts as progress. Run it again until one of these happens:
 
-- A batch saved nothing new: \`proposed\` is empty, and every ad under \`skipped\` is \`no_content\` (nothing to read: no copy, transcript or picture description) or \`not_found\`, with the rest under \`failed\`. The same ads would come back next time, so asking again won't help.
+- A batch saved nothing new: \`proposed\` is empty, and every ad under \`skipped\` is \`no_content\` (nothing to read: no copy, transcript or picture description) or \`not_found\`, with the rest under \`failed\`. Asking again won't help.
 - You have run ${BACK_TAG_MAX_BATCHES} batches, or the person's spending limit would be passed.
 - \`stopped\` is \`tool_cap\`: the run's tool spending cap was reached.
 
-Keep a running count of ads proposed, ads skipped (and why), failures and \`costUsd\` from each batch.
+Keep a running count of ads proposed, ads skipped (and why), failures and \`costUsd\` from each batch. \`nothingToRead\` counts the untagged ads the tagger left out because they have nothing to read; keep the last batch's number.
 
 ## 3. Report
 
@@ -876,7 +876,7 @@ Run the coverage query from step 1 again, then finish with a short report in pla
 
 - How many ads you tagged this run and what it cost.
 - How many ads that spent anything now have tags, and what share of the spend that is (\`pct_spend_tagged\`); what share of spend a person has confirmed (\`pct_spend_confirmed\`). Give each currency's shares on their own; never add them together.
-- How many ads are still untagged and why, if the batches said (nothing to read, failures).
+- How many ads are still untagged and why, if the batches said: \`nothingToRead\` ads have nothing to read (no copy, headline, transcript or picture description), plus any failures.
 - What to do next: open the Ad tags page in the ${brand.name} web app, press Make the list (or Make a new list) under Check these first, and confirm, fix or skip the ads that carry the top 20% of spend. Everything else stays as the tagger's best guess, marked not yet confirmed.
 
 ## Commands

package/dist/runner/claim.js

@@ -1,6 +1,7 @@
 import { CliError, exitCodes } from "../api.js";
 import { SKILL_NAME_PATTERN } from "../skill-zip.js";
 export const harnessNames = ["claude", "codex"];
+const aiBillings = ["run_key", "shared_key", "subscription"];
 const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** The claim response as the runner uses it. Never echoes the body: it holds the run key. */
 export function parseClaim(body) {
@@ -28,6 +29,12 @@ export function parseClaim(body) {
         throw bad("deadline");
     if (body.openRouterKey !== undefined && (typeof body.openRouterKey !== "string" || body.openRouterKey.length === 0))
         throw bad("openRouterKey");
+    // A server from before `aiBilling` says run_key only by sending a key.
+    const aiBilling = body.aiBilling ?? (body.openRouterKey === undefined ? "subscription" : "run_key");
+    if (!aiBillings.includes(aiBilling))
+        throw bad("aiBilling");
+    if ((aiBilling === "run_key") !== (typeof body.openRouterKey === "string"))
+        throw bad("openRouterKey");
     return {
         runId: run.id,
         runKey: body.runKey,
@@ -37,6 +44,6 @@ export function parseClaim(body) {
         prompt: body.prompt,
         aiCapUsd: caps.aiCents / 100,
         deadline,
-        billing: typeof body.openRouterKey === "string" ? { kind: "openrouter", key: body.openRouterKey } : { kind: "subscription" },
+        billing: typeof body.openRouterKey === "string" ? { kind: "openrouter", key: body.openRouterKey } : { kind: aiBilling },
     };
 }

package/dist/runner/run.js

@@ -8,6 +8,7 @@ import { brand, envPrefix } from "../brand.js";
 import { RUN_ROOT_ENV } from "../files.js";
 import { installSkillFolder, unpackSkill } from "../skills.js";
 import { parseClaim } from "./claim.js";
+import { OPENROUTER_KEY_ENV } from "./codex.js";
 import { MAX_TURNS } from "./harness.js";
 import { commandHarness, harnesses } from "./harnesses.js";
 import { LogTail, redact, RUN_ERROR_MAX_BYTES, tailBytes } from "./redact.js";
@@ -68,7 +69,7 @@ export async function runOnce(options) {
     if (answer === "")
         return { kind: "idle" };
     const claim = parseClaim(JSON.parse(answer));
-    const secrets = [claim.runKey, options.token, ...(claim.billing.kind === "openrouter" ? [claim.billing.key] : [])];
+    const secrets = [claim.runKey, options.token, ...(claim.billing.kind === "openrouter" ? [claim.billing.key] : []), ...(options.openRouterKey ? [options.openRouterKey] : [])];
     const say = (line) => options.say(redact(line, secrets));
     say(`Claimed run ${claim.runId}: ${claim.skill.name} version ${claim.skill.version} with ${claim.harness}.`);
     const stop = new AbortController();
@@ -90,6 +91,9 @@ export async function runOnce(options) {
         dir = await mkdtemp(join(tmpdir(), `${brand.slug}-run-`));
         const result = await execute(claim, dir, options, stop.signal, (text) => log.append(text));
         report = finishReport(result, stop.signal.reason);
+        const aiCents = reportedAiCents(claim.billing, result.tokens);
+        if (aiCents !== undefined)
+            report.aiCents = aiCents;
     }
     catch (error) {
         report = { status: "failed", error: stop.signal.aborted ? stopMessages[stop.signal.reason] : `The runner failed: ${error.message}` };
@@ -143,6 +147,7 @@ function finishReport(result, stopped) {
 }
 /** Puts the skill, the run key's login and a `wr` in `dir`, then runs the harness there. */
 async function execute(claim, dir, options, signal, log) {
+    const billing = harnessBilling(claim, options.openRouterKey);
     const skillsDir = join(dir, claim.harness === "claude" ? ".claude" : ".codex", "skills");
     await installSkillFolder(skillsDir, claim.skill.name, unpackSkill(claim.skill, await getSigned(claim.skill.url)), []);
     const configHome = join(dir, ".config");
@@ -158,7 +163,7 @@ async function execute(claim, dir, options, signal, log) {
         skill: claim.skill.name,
         prompt: runPrompt(claim.prompt),
         model: claim.model,
-        billing: claim.billing,
+        billing,
         aiCapUsd: claim.aiCapUsd,
         maxTurns: MAX_TURNS,
         env: harnessEnv(process.env, { dir, binDir, configHome, apiUrl: options.apiUrl }),
@@ -166,6 +171,30 @@ async function execute(claim, dir, options, signal, log) {
         log,
     });
 }
+/**
+ * How the harness pays. A shared_key run pays OpenRouter with the runner's own key, and only Claude Code, whose budget
+ * stops it at the AI cap, may run that way: nothing would hold a Codex run to its cap on a key shared by every run.
+ */
+export function harnessBilling(claim, openRouterKey) {
+    if (claim.billing.kind !== "shared_key")
+        return claim.billing;
+    if (!openRouterKey) {
+        throw new Error(`This run pays for AI with the runner's own OpenRouter key, but ${OPENROUTER_KEY_ENV} is not set on this runner. Set it, or set OPENROUTER_PROVISIONING_KEY on the server to an OpenRouter management key so each run gets its own key.`);
+    }
+    if (claim.harness === "codex") {
+        throw new Error(`A Codex run cannot keep to its AI cap on the runner's shared OpenRouter key. Set OPENROUTER_PROVISIONING_KEY on the server to an OpenRouter management key so each run gets its own capped key.`);
+    }
+    return { kind: "openrouter", key: openRouterKey };
+}
+/**
+ * The AI spend a finish report carries: only a shared_key run's, whose spend the server cannot read from OpenRouter
+ * itself, from the harness's own estimate. A zero estimate may mean the harness could not price the model, so it is not
+ * sent; a run without a report counts at its full cap.
+ */
+export function reportedAiCents(billing, tokens) {
+    const costUsd = tokens?.costUsd;
+    return billing.kind === "shared_key" && costUsd !== undefined && costUsd > 0 ? Math.ceil(costUsd * 100) : undefined;
+}
 /** Beats now (moving the run to running) and every minute; a cancel, or a server that no longer knows the run, stops it. */
 function startHeartbeat(connection, runId, cancel, say) {
     const beat = async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrangled/cli",
-  "version": "0.3.23",
+  "version": "0.3.25",
   "description": "Command-line access to your marketing data warehouse, for people and coding agents",
   "type": "module",
   "bin": {