@commercelayer/agent-cli 1.0.0-dev.2 → 1.0.0-dev.21

package/dist/builtins/extensions.js

@@ -8,14 +8,22 @@
 // sales-calls book answers a cancel token once (section 20): stored the same way, by booking id,
 // and sent by sales-calls cancel <booking> without the agent ever holding it.
 import crypto from 'node:crypto';
-import { credentialsFile, hintOf, readLink, storeBooking, storedBooking, storeOrg, writeLink } from '../config.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { credentialsFile, forgetOrg, forgetOutWritten, hintOf, projectDir, readLink, removeLink, storeBooking, storedBooking, storedOrgs, storeOrg, writeLink } from '../config.js';
+import { OUT_NOT_TRACKED, removeOrgSecrets } from '../secrets.js';
 import { confirm, terminal } from '../confirm.js';
 import { fail } from '../errors.js';
 import { apiUrl } from '../http.js';
+import { clearDrift, driftWarning, readDrift, readStoreFiles, storeFileIs, writeStoreFiles } from '../project.js';
 import { resourceRequest } from '../resources.js';
+import { CALL_MAX, kb, lookImage, lookProblem, withShop } from '../storefront.js';
 const NAME_MAX = 25;
 export const organizations = {
     async run(run) {
+        if (run.verb.name === 'disconnect')
+            return disconnect(run);
         if (run.verb.name !== 'create' && run.verb.name !== 'connect')
             return undefined;
         const name = run.parsed.values.name;
@@ -25,9 +33,10 @@ export const organizations = {
         const req = resourceRequest('organizations', run.verb, run.parsed.id, run.parsed.values);
         // Ending every other token of the organization is confirmed: by the schema's confirm_if, or
         // here for a schema without it.
-        if (run.verb.name === 'connect' && run.parsed.values.revoke_others && !run.globals.dryRun) {
-            if (!run.verb.confirmIf.includes('revoke_others'))
-                await confirm(`Connect ${run.parsed.id} and end every other organization token of it`, run.line, { yes: run.globals.yes, prompter: run.prompter ?? terminal });
+        // With confirm_if the engine has it confirmed, by the human here or by the API's 428 with its
+        // sentence; only a schema without it is confirmed here, and then sends confirm=true itself.
+        if (run.verb.name === 'connect' && run.parsed.values.revoke_others && !run.globals.dryRun && !run.verb.confirmIf.includes('revoke_others')) {
+            await confirm(`Connect ${run.parsed.id} and end every other organization token of it`, run.line, { yes: run.globals.yes, prompter: run.prompter ?? terminal });
             req.confirm = true;
             req.body = { ...req.body, confirm: true };
         }
@@ -69,6 +78,23 @@ export const organizations = {
         return { ...r, data: { ...data, org, token_hint: hint, credentials: credentialsFile(), linked }, warnings };
     },
 };
+/**
+ * organizations disconnect: the API revokes its own credentials and the organization tokens, so
+ * this machine forgets them too, as sandbox destroy does: the token, its secret files, a link
+ * naming it.
+ */
+async function disconnect(run) {
+    const r = await run.send(resourceRequest('organizations', run.verb, run.parsed.id, run.parsed.values));
+    if (run.globals.dryRun || r.data?.disconnected !== true)
+        return r;
+    const org = r.data.org ?? run.parsed.id;
+    const out = forgetOutWritten(org);
+    const credentials = Boolean(storedOrgs()[org]);
+    forgetOrg(org);
+    const link = removeLink(org);
+    const secrets = removeOrgSecrets(org);
+    return { ...r, data: { ...r.data, forgotten: { credentials, link, secrets } }, warnings: [...r.warnings, ...(out ? [OUT_NOT_TRACKED] : [])] };
+}
 export const salesCalls = {
     positional: { book: 'slot' },
     prepare(verb, parsed) {
@@ -104,4 +130,302 @@ export const salesCalls = {
         return undefined;
     },
 };
-export const extensions = { organizations, 'sales-calls': salesCalls };
+// config (contract section 45.2): the API answers and applies documents; the files are the CLI's.
+//   export  writes store.yml and price_lists/<code>.csv, never over a file changed since the last
+//           export without --yes, and clears the drift note.
+//   plan    sends the folder's files and says what apply would change, and since when the
+//           folder is behind when Configure writes were made here.
+//   apply   sends them; while imports run (202, running) it shows each noun's state, and with
+//           --wait applies again until done or failed. prune is confirmed by the schema.
+const WAIT_MAX_MS = 15 * 60_000;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const waitMs = (data) => {
+    const s = Number(data?.retry_after);
+    const test = process.env.C11R_WAIT_MS;
+    if (test !== undefined)
+        return Number(test);
+    return (Number.isFinite(s) && s > 0 ? Math.min(s, 60) : 5) * 1000;
+};
+export const config = {
+    flags: {
+        apply: { wait: { type: 'boolean', to: 'local', description: 'While imports run, apply again every retry_after seconds until done or failed (15 minutes at most).' } },
+    },
+    prepare(verb, parsed) {
+        if (verb.name !== 'plan' && verb.name !== 'apply')
+            return;
+        if (parsed.values.store !== undefined)
+            return;
+        const files = readStoreFiles();
+        parsed.values.store = files.store;
+        parsed.values.price_lists = files.price_lists;
+    },
+    async run(run) {
+        const name = run.verb.name;
+        if (name === 'export') {
+            const r = await run.send(resourceRequest('config', run.verb, undefined, run.parsed.values));
+            if (run.globals.dryRun)
+                return r;
+            const data = r.data ?? {};
+            if (!data.store || typeof data.store !== 'object')
+                fail('invalid_response', 'config export answered without store.', { next_step: { action: 'none' } });
+            const out = writeStoreFiles({ store: data.store, price_lists: data.price_lists ?? {}, meta: { org: data.meta?.org ?? run.org.org ?? undefined, exported_at: data.meta?.exported_at } }, { overwrite: run.globals.yes, mode: run.globals.live ? 'live' : 'test' });
+            const ambiguous = Array.isArray(data.ambiguous) ? data.ambiguous : [];
+            const counts = Object.fromEntries(Object.entries(data.store).map(([k, v]) => [k, Array.isArray(v) ? v.length : 0]));
+            return {
+                ...r,
+                data: {
+                    org: data.meta?.org ?? run.org.org,
+                    exported_at: data.meta?.exported_at ?? null,
+                    folder: out.dir,
+                    files: out.written,
+                    removed: out.removed,
+                    records: counts,
+                    price_lists: Object.keys(data.price_lists ?? {}),
+                    // Keys several records share (45.9): apply refuses them until they differ.
+                    ambiguous,
+                },
+                next: [
+                    ...(ambiguous[0]?.command ? [{ command: String(ambiguous[0].command), why: 'records share a key: plan and apply cannot match them until it differs' }] : []),
+                    { command: 'c11r config plan', why: 'what the files would change in an organization, after you edit them or for another one (--org)' },
+                ],
+            };
+        }
+        if (name === 'plan' || name === 'apply') {
+            const values = run.parsed.values;
+            let r = await run.send(resourceRequest('config', run.verb, undefined, values));
+            const started = Date.now();
+            while (name === 'apply' && values.wait && r.data?.status === 'running' && Date.now() - started < WAIT_MAX_MS) {
+                const ms = waitMs(r.data);
+                process.stderr.write(JSON.stringify({ running: { nouns: states(r.data), next_in_ms: ms } }) + '\n');
+                await sleep(ms);
+                // The same run carries on (45.9): its token goes back with the same files, so done counts
+                // everything the run wrote.
+                if (typeof r.data?.run === 'string')
+                    values.run = r.data.run;
+                r = await run.send(resourceRequest('config', run.verb, undefined, values));
+            }
+            const warnings = [...r.warnings];
+            const here = storeFileIs(run.org.org, run.globals.live ? 'live' : 'test');
+            const drift = readDrift();
+            if (name === 'plan' && drift.length && here)
+                warnings.push(driftWarning(drift));
+            // The organization now matches the files: the folder is no longer behind.
+            if (name === 'apply' && !run.globals.dryRun && r.data?.status === 'done' && here)
+                clearDrift();
+            const data = r.data ?? {};
+            const running = name === 'apply' && data.status === 'running';
+            return {
+                ...r,
+                data: running ? { ...data, retry_after: waitMs(data) / 1000, states: states(data) } : data,
+                warnings,
+                next: running ? [{ command: carryOn(run.line, run.verb.flags.run ? data.run : undefined), why: 'carry on with the same files, and wait until every noun is done or failed' }, ...r.next] : r.next,
+            };
+        }
+        return undefined;
+    },
+};
+/**
+ * The apply that carries this run on: the same line with its --run token and --wait. Without --yes:
+ * a yes covers the run the human saw, so carrying on a prune is confirmed again.
+ */
+function carryOn(line, token) {
+    let out = line
+        .replace(/\s--run(=|\s+)("[^"]*"|'[^']*'|\S+)/g, '')
+        .replace(/\s--wait\b/g, '')
+        .replace(/\s(--yes|-y)(?=\s|$)/g, '');
+    if (typeof token === 'string' && token)
+        out += ` --run ${/^[\w.~:+\/=-]+$/.test(token) ? token : `'${token.replace(/'/g, `'\\''`)}'`}`;
+    return `${out} --wait`;
+}
+/** Each noun's state while apply runs: done, running (with its import), waiting, failed or unchanged. */
+function states(data) {
+    const out = {};
+    for (const n of Array.isArray(data?.nouns) ? data.nouns : [])
+        out[n.noun] = n.import?.id && n.status === 'running' ? `running (import ${n.import.id})` : String(n.status);
+    return out;
+}
+// exports (45.3): get --out downloads the file while its link is good (5 minutes), unzipped unless
+// the name ends in .gz; --wait polls a job not completed yet.
+export const exports = {
+    flags: {
+        get: {
+            out: { type: 'string', to: 'local', description: 'Download the export to this file once completed (its link lasts 5 minutes). Unzipped, unless the name ends in .gz.' },
+            wait: { type: 'boolean', to: 'local', description: 'Until the export is completed, failed or interrupted, read it again every few seconds (15 minutes at most).' },
+        },
+    },
+    async run(run) {
+        if (run.verb.name !== 'get' || (!run.parsed.values.out && !run.parsed.values.wait))
+            return undefined;
+        const req = resourceRequest('exports', run.verb, run.parsed.id, run.parsed.values);
+        let r = await run.send(req);
+        const started = Date.now();
+        const busy = (s) => s === 'pending' || s === 'in_progress';
+        while (run.parsed.values.wait && busy(r.data?.status) && Date.now() - started < WAIT_MAX_MS) {
+            const ms = waitMs(null);
+            process.stderr.write(JSON.stringify({ waiting: { export: run.parsed.id, status: r.data?.status, next_in_ms: ms } }) + '\n');
+            await sleep(ms);
+            r = await run.send(req);
+        }
+        const out = run.parsed.values.out;
+        if (!out)
+            return r;
+        const data = r.data ?? {};
+        if (data.status !== 'completed' || typeof data.url !== 'string') {
+            fail('conflict', `Export ${run.parsed.id} is ${data.status ?? 'not completed'}: there is no file to download yet.`, { path: 'out', details: { status: data.status ?? null }, next_step: { action: 'fix_request', command: `${run.line} --wait` } }, 'rejected');
+        }
+        const file = path.resolve(out);
+        let res;
+        try {
+            res = await fetch(data.url, { signal: AbortSignal.timeout(120_000) });
+        }
+        catch (e) {
+            fail('api_unreachable', `The export's file could not be downloaded: ${e.message}.`, { path: 'out', next_step: { action: 'fix_request', command: run.line } });
+        }
+        // An expired link: get the export again for a new one.
+        if (!res.ok)
+            fail('expired', `The export's link answered ${res.status}: it lasts 5 minutes. Get the export again for a new one.`, { path: 'out', next_step: { action: 'fix_request', command: run.line } }, 'rejected');
+        let bytes = Buffer.from(await res.arrayBuffer());
+        const zipped = bytes[0] === 0x1f && bytes[1] === 0x8b;
+        if (zipped && !file.endsWith('.gz'))
+            bytes = zlib.gunzipSync(bytes);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, bytes);
+        const { url: _url, ...rest } = data;
+        return { ...r, data: { ...rest, file, bytes: bytes.length, unzipped: zipped && !file.endsWith('.gz') } };
+    },
+};
+/** Where a path really lands: symlinks followed, dangling ones too, and the missing rest as written. */
+function realPath(p, hops = 0) {
+    let st = null;
+    try {
+        st = fs.lstatSync(p);
+    }
+    catch {
+        st = null;
+    }
+    if (st?.isSymbolicLink() && hops < 40)
+        return realPath(path.resolve(realPath(path.dirname(p), hops + 1), fs.readlinkSync(p)), hops + 1);
+    if (st)
+        return fs.realpathSync(p);
+    const parent = path.dirname(p);
+    return parent === p ? p : path.join(realPath(parent, hops), path.basename(p));
+}
+/**
+ * --out resolved from here, refused (invalid_value on out) when it lands outside the project folder:
+ * by .., by an absolute path, or by a symlink on the way (the file itself or a folder above it).
+ */
+function insideProject(out) {
+    const file = path.resolve(out);
+    const root = fs.realpathSync(projectDir());
+    const target = realPath(file);
+    const rel = path.relative(root, target);
+    if (rel === '' || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+        fail('invalid_value', `--out ${out} is outside the project folder ${root}: c11r writes only inside it.`, { path: 'out', details: { project: root, resolved: target } });
+    }
+    return file;
+}
+// scaffold (46): drop-in --out writes the snippet as one HTML file, its head part and its body part
+// each under a comment saying where it goes. It never replaces a different file without --yes.
+export const scaffold = {
+    flags: {
+        'drop-in': {
+            out: { type: 'string', to: 'local', description: 'Write the snippet to this HTML file: the part for the page\'s <head>, then the part for its <body>, each under a comment saying where it goes. It must be inside the project folder. A different file there is replaced only with --yes.' },
+        },
+        storefront: {
+            product_image: {
+                type: 'array',
+                items: 'string',
+                to: 'local',
+                repeat: '--product-image SKU=FILE --product-image SKU=FILE, once per sku: a local svg, png, jpg or webp file, or an https URL; SKU=null takes the image off.',
+                description: 'The image of one sku in the shop, as SKU=FILE or SKU=https://...: a local file is read here and sent with its sha256. At most 512 KB a file and 2 MB a call.',
+            },
+        },
+    },
+    async run(run) {
+        if (run.verb.name === 'storefront')
+            return storefront(run);
+        const out = run.parsed.values.out;
+        if (run.verb.name !== 'drop-in' || !out)
+            return undefined;
+        const file = insideProject(out);
+        // Before anything is sent: a different file there stays without --yes.
+        const before = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+        const r = await run.send(resourceRequest('scaffold', run.verb, undefined, run.parsed.values));
+        if (run.globals.dryRun)
+            return r;
+        const data = r.data ?? {};
+        const snippet = data.snippet;
+        if (!snippet || typeof snippet.head !== 'string' || typeof snippet.body !== 'string')
+            fail('invalid_response', 'scaffold drop-in answered without snippet.head and snippet.body.', { next_step: { action: 'none' } });
+        const html = [
+            `<!-- c11r scaffold drop-in${run.org.org ? ` (${run.org.org})` : ''}: this part goes in the page's <head>. -->`,
+            snippet.head.trimEnd(),
+            '',
+            `<!-- This part goes in the page's <body>, where the products show. -->`,
+            snippet.body.trimEnd(),
+            '',
+        ].join('\n');
+        if (before !== null && before !== html && !run.globals.yes) {
+            fail('conflict', `${file} is there already, and differs from this snippet. c11r replaces it only with --yes.`, { path: 'out', details: { files: [file] }, next_step: { action: 'fix_request', command: null } }, 'rejected');
+        }
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        if (before !== html)
+            fs.writeFileSync(file, html);
+        const { snippet: _snippet, ...rest } = data;
+        return { ...r, data: { ...rest, file, replaced: before !== null && before !== html } };
+    },
+};
+/**
+ * scaffold storefront (48.3): the look checked here, the image files read into { type,
+ * content_base64, sha256 }, then one call; the answer carries the shop link.
+ */
+async function storefront(run) {
+    const v = { ...run.parsed.values };
+    for (const key of ['name', 'color', 'background', 'font', 'corners', 'tagline', 'badge']) {
+        if (v[key] === undefined)
+            continue;
+        const why = lookProblem(key, v[key]);
+        if (why)
+            fail('invalid_value', `--${key} ${JSON.stringify(v[key])} ${why}. Nothing was sent.`, { path: key, next_step: { action: 'fix_request', command: null } });
+    }
+    const pairs = v.product_image ?? [];
+    delete v.product_image;
+    if (pairs.length) {
+        const images = { ...(v.product_images ?? {}) };
+        for (const pair of pairs) {
+            const eq = pair.indexOf('=');
+            if (eq < 1)
+                fail('invalid_value', `--product-image ${JSON.stringify(pair)} is not SKU=FILE: the sku code, then = and a file or an https URL.`, { path: 'product_image', next_step: { action: 'fix_request', command: null } });
+            const sku = pair.slice(0, eq).trim();
+            const value = pair.slice(eq + 1).trim();
+            if (sku in images)
+                fail('invalid_value', `--product-image names ${sku} twice.`, { path: `product_images.${sku}` });
+            images[sku] = value === 'null' || value === '' ? null : value;
+        }
+        v.product_images = images;
+    }
+    let bytes = 0;
+    for (const key of ['logo', 'hero']) {
+        if (v[key] === undefined)
+            continue;
+        const r = lookImage(key, `--${key}`, v[key]);
+        v[key] = r.value;
+        bytes += r.bytes;
+    }
+    if (v.product_images && typeof v.product_images === 'object') {
+        const images = v.product_images;
+        for (const [sku, x] of Object.entries(images)) {
+            const r = lookImage(`product_images.${sku}`, `--product-image ${sku}=`, x);
+            images[sku] = r.value;
+            bytes += r.bytes;
+        }
+    }
+    if (bytes > CALL_MAX) {
+        fail('invalid_value', `The images of this call add up to ${kb(bytes)}: one call carries at most 2 MB. Send them in more than one c11r scaffold storefront. Nothing was sent.`, { path: 'product_images', details: { bytes, max: CALL_MAX }, next_step: { action: 'fix_request', command: null } });
+    }
+    const r = await run.send(resourceRequest('scaffold', run.verb, undefined, v));
+    if (run.globals.dryRun)
+        return r;
+    return withShop(r, r.data?.store);
+}
+export const extensions = { organizations, 'sales-calls': salesCalls, config, exports, scaffold };

package/dist/builtins/index.js

@@ -1,8 +1,10 @@
 // The nouns with code of their own. Each brings a schema document in the API's format, so help,
 // validation and confirmation are the engine's. report is a plain noun: the API's schema drives
-// it. skills (c11r skills sync) comes with deliverable 4.
+// it.
 import { auth } from './auth.js';
 import { loops } from './loops.js';
 import { sandbox, status } from './sandbox.js';
-export const builtins = { sandbox, status, loops, auth };
+import { shop } from './shop.js';
+import { skills } from './skills.js';
+export const builtins = { sandbox, status, loops, auth, shop, skills };
 export { extensions } from './extensions.js';

package/dist/builtins/loops.js

@@ -4,8 +4,9 @@
 // schedules the agent repeats it every `every`.
 //
 // A policy allows verbs: a bare verb is the skill's own noun (approve), <noun>.<verb> another
-// Manage noun's verb on the same item (payments.capture). Each must be in the noun's schema
-// loop.verbs; the API checks again on every pass.
+// Manage noun's verb on the same item (payments.capture). The skill must be one a Manage or Report
+// noun's schema names in loop.skill or loop.skills, and each verb in that loop.verbs; the API checks
+// again on every pass.
 import fs from 'node:fs';
 import path from 'node:path';
 import YAML from 'yaml';
@@ -13,15 +14,15 @@ import { projectDir } from '../config.js';
 import { CliError, closest, fail, fixWith } from '../errors.js';
 import { envelope } from '../http.js';
 import { parseSchema } from '../schema.js';
-import { apiSchema } from '../schemas.js';
+import { apiNouns, apiSchema } from '../schemas.js';
 const NAME = /^[a-z0-9][a-z0-9-]{0,62}$/;
 const EVERY = /^[1-9]\d*(m|h|d)$/;
 const policyFlags = (required) => [
-    { name: 'skill', type: 'string', required, description: 'The Manage skill or playbook the loop runs, as in manage-orders.' },
+    { name: 'skill', type: 'string', required, description: 'The skill the loop runs, as in manage-orders or report-sales: one a noun\'s schema names in loop.skill or loop.skills.' },
     { name: 'every', type: 'string', required, description: 'How often a pass should run, as in 15m, 2h or 1d. The scheduler reads it; the CLI does not wait.' },
-    { name: 'allow', type: 'array', required, description: 'A verb the policy allows, repeated: approve, payments.capture. Only verbs the noun\'s schema lists in loop.verbs.' },
-    { name: 'max_total', type: 'array', description: 'The largest order total acted on, in major units: 500 for every currency, or EUR=500, repeated per currency. Above it, the item waits for the human.' },
-    { name: 'market', type: 'array', description: 'A market code the loop acts in, repeated. Items in other markets wait. Without it, every market.' },
+    { name: 'allow', type: 'array', description: 'A verb the policy allows, repeated: approve, payments.capture. Only verbs the noun\'s schema lists in loop.verbs. Without it the loop only reports what is waiting.', repeat: '--allow VERB --allow VERB, one verb per flag, or one JSON array.' },
+    { name: 'max_total', type: 'array', description: 'The largest order total acted on, in major units: 500 for every currency, or EUR=500 per currency, the flag repeated or separated by commas. Above it, the item waits for the human.', repeat: '--max-total AMOUNT for every currency, or --max-total CURRENCY=AMOUNT once per currency (also separated by commas: EUR=500,USD=550), or one JSON array.' },
+    { name: 'market', type: 'array', description: 'A market code the loop acts in, repeated. Items in other markets wait. Without it, every market.', repeat: '--market CODE --market CODE, one market code per flag, or one JSON array.' },
 ];
 export const loops = {
     schema: parseSchema({
@@ -32,12 +33,12 @@ export const loops = {
         description: 'Loops: a skill on a schedule, under a policy written in advance. Definitions are in loops.yml in the project folder; each pass is one c11r loops run.',
         id: { accepts: ['name'], example: 'orders-15m' },
         verbs: [
-            { verb: 'list', method: 'GET', state: 'none', effect: 'Lists the loops of loops.yml.' },
-            { verb: 'get', method: 'GET', path: '/v1/loops/{id}', state: 'none', effect: 'Returns a loop from loops.yml, with its last pass when the organization has run it.' },
-            { verb: 'create', method: 'POST', path: '/v1/loops/{id}', state: 'none', body: policyFlags(true), effect: 'Adds a loop to loops.yml, after checking its policy against the skill noun\'s schema. Nothing runs until a pass.' },
-            { verb: 'update', method: 'PATCH', path: '/v1/loops/{id}', state: 'none', body: policyFlags(false), effect: 'Changes a loop in loops.yml. A flag given replaces what is there: --allow replaces the whole list.' },
-            { verb: 'delete', method: 'DELETE', path: '/v1/loops/{id}', state: 'none', destructive: true, deletes: true, effect: 'Removes a loop from loops.yml, and its cursor from the organization.' },
-            { verb: 'run', method: 'POST', path: '/v1/loops/{id}/run', effect: 'One pass: what is waiting since the last pass, and the actions the policy allows. Answers done, waiting (new: true for what appeared since the last pass) and failed. With --dry-run nothing changes and the last pass time stays.' },
+            { verb: 'list', live: false, method: 'GET', state: 'none', effect: 'Lists the loops of loops.yml.' },
+            { verb: 'get', live: false, method: 'GET', path: '/v1/loops/{id}', state: 'none', effect: 'Returns a loop from loops.yml, with its last pass when the organization has run it.' },
+            { verb: 'create', live: false, method: 'POST', path: '/v1/loops/{id}', state: 'none', body: policyFlags(true), effect: 'Adds a loop to loops.yml, after checking its policy against the skill noun\'s schema. Nothing runs until a pass.' },
+            { verb: 'update', live: false, method: 'PATCH', path: '/v1/loops/{id}', state: 'none', body: policyFlags(false), effect: 'Changes a loop in loops.yml. A flag given replaces what is there: --allow replaces the whole list.' },
+            { verb: 'delete', live: false, method: 'DELETE', path: '/v1/loops/{id}', state: 'none', destructive: true, deletes: true, effect: 'Removes a loop from loops.yml, and its cursor from the organization.' },
+            { verb: 'run', live: false, method: 'POST', path: '/v1/loops/{id}/run', effect: 'One pass: what is waiting since the last pass, and the actions the policy allows. Answers done, waiting (new: true for what appeared since the last pass) and failed. With --dry-run nothing changes and the last pass time stays.' },
         ],
     }),
     async run(run) {
@@ -77,9 +78,11 @@ export function readLoops(file) {
     const out = {};
     for (const [name, d] of Object.entries(raw.loops ?? {})) {
         const def = d;
-        if (!def || typeof def.skill !== 'string' || !Array.isArray(def.policy?.allow))
-            fail('invalid_config', `${file}: loop ${name} needs a skill and a policy with allow.`, { path: `loops.${name}` });
-        out[name] = def;
+        // allow may be left out, or empty: the loop only reports.
+        const allow = def?.policy?.allow ?? [];
+        if (!def || typeof def.skill !== 'string' || !Array.isArray(allow))
+            fail('invalid_config', `${file}: loop ${name} needs a skill, and its policy.allow is a list of verbs.`, { path: `loops.${name}` });
+        out[name] = { ...def, policy: { ...(def.policy ?? {}), allow } };
     }
     return out;
 }
@@ -118,7 +121,7 @@ async function write(run, name, file) {
         skill: v.skill ?? existing.skill,
         every: v.every ?? existing.every,
         policy: {
-            allow: v.allow ?? existing.policy.allow,
+            allow: v.allow ?? existing?.policy.allow ?? [],
             ...(v.max_total !== undefined ? { max_total: maxTotal(v.max_total) } : existing?.policy.max_total !== undefined ? { max_total: existing.policy.max_total } : {}),
             ...(v.market !== undefined ? { markets: v.market } : existing?.policy.markets ? { markets: existing.policy.markets } : {}),
         },
@@ -144,7 +147,9 @@ async function write(run, name, file) {
     });
 }
 /** 500, or EUR=500 per currency. */
-function maxTotal(items) {
+function maxTotal(given) {
+    // Amounts and currency codes hold no comma: EUR=500,USD=550 is two, as is the flag repeated.
+    const items = given.flatMap((i) => i.split(',')).map((i) => i.trim()).filter(Boolean);
     const plain = items.filter((i) => !i.includes('='));
     if (plain.length && plain.length !== items.length)
         fail('invalid_value', '--max-total takes one amount, or one CURRENCY=amount per currency, not both.', { path: 'max_total' });
@@ -166,23 +171,55 @@ function maxTotal(items) {
         return [ccy, amount(n)];
     }));
 }
-/** The policy's verbs against the skill noun's schema; a playbook is checked by the API at the first pass. */
+/**
+ * The skill and the policy's verbs against the same source loops run uses: each noun schema's loop,
+ * { skill, verbs }. A skill no schema's loop names is refused with the ones that are, and so is a
+ * verb its loop does not list.
+ */
 async function checkPolicy(def) {
-    if (!def.policy.allow.length)
-        fail('missing_argument', 'A loop needs at least one --allow.', { path: 'allow' });
-    if (!def.skill.startsWith('manage-'))
-        return [{ code: 'policy_unchecked', message: `${def.skill} is not a Manage skill: the API checks its policy at the first pass.` }];
-    const noun = def.skill.slice('manage-'.length);
-    const schema = await apiSchema(noun, []);
-    const allowed = schema.loop?.verbs ?? [];
-    if (!allowed.length)
-        fail('policy_forbidden', `No loop acts on ${noun}: its schema has no loop.`, { path: 'skill' });
+    const skills = await loopSkills();
+    const allowed = skills.get(def.skill);
+    if (!allowed) {
+        const names = [...skills.keys()].sort();
+        fail('invalid_value', `--skill ${def.skill} runs no loop. A loop runs ${names.length ? names.join(', ') : 'no skill yet'}.`, {
+            path: 'skill',
+            did_you_mean: closest(def.skill, names),
+            details: { values: names },
+            next_step: fixWith('c11r loops create --help'),
+        });
+    }
     for (const verb of def.policy.allow) {
-        if (!allowed.includes(verb)) {
-            fail('policy_forbidden', `A ${def.skill} loop may not allow ${verb}. It may allow ${allowed.join(', ')}.`, { path: 'allow', did_you_mean: closest(verb, allowed), details: { loopable: allowed }, next_step: fixWith(`c11r schema ${noun}`) });
+        if (!allowed.verbs.includes(verb)) {
+            fail('policy_forbidden', `A ${def.skill} loop may not allow ${verb}. ${allowed.verbs.length ? `It may allow ${allowed.verbs.join(', ')}.` : 'It allows no verb: it only reports what is waiting, so it takes no --allow.'}`, { path: 'allow', did_you_mean: closest(verb, allowed.verbs), details: { loopable: allowed.verbs }, next_step: fixWith(`c11r schema ${allowed.noun}`) });
         }
     }
-    return [];
+    // Allowed and bounded by nothing: kept, and said, so the agent tells the human.
+    const open = [];
+    if (def.policy.allow.length && def.policy.max_total === undefined)
+        open.push('any order total (no --max-total)');
+    if (def.policy.allow.length && !def.policy.markets?.length)
+        open.push('every market (no --market)');
+    return open.length ? [{ code: 'no_limit', message: `This loop may ${def.policy.allow.join(', ')} for ${open.join(' and in ')}. Tell the human in one line.` }] : [];
+}
+/**
+ * The skills a loop can run, from the schemas of the nouns that have a loop (Manage and Report):
+ * each skill to its noun and the verbs its policy may allow. loop.skills, when given, lists every
+ * skill of the noun's loop (a report loop per report); else loop.skill is the one.
+ */
+async function loopSkills() {
+    const nouns = (await apiNouns()).filter((n) => (n.group === 'manage' || n.group === 'report') && n.served !== false);
+    const schemas = await Promise.all(nouns.map((n) => apiSchema(n.noun, []).catch(() => null)));
+    const out = new Map();
+    for (const s of schemas) {
+        if (!s?.loop)
+            continue;
+        const names = Array.isArray(s.loop.skills) && s.loop.skills.length ? s.loop.skills : s.loop.skill ? [s.loop.skill] : [];
+        for (const skill of names) {
+            const seen = out.get(skill);
+            out.set(skill, { noun: seen?.noun ?? s.noun, verbs: [...new Set([...(seen?.verbs ?? []), ...(s.loop.verbs ?? [])])] });
+        }
+    }
+    return out;
 }
 async function remove(run, name, file) {
     one(file, name);