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

package/README.md

@@ -15,7 +15,7 @@ This is the 1.0.0 line, in development on the `clean-slate` branch. It replaces
 - Flags are the schema's fields, in kebab or snake case: `--price-list` and `--price_list` are the same.
 - On `list`, `--<field> <value>` filters by equality and `--<field>.<op> <value>` by another operator: `--placed-at.gte 2026-11-01`, `--status.in placed,approved`. `--waiting` lists what needs a decision now.
 - A ref flag, or one the schema marks `nullable`, given `null` or an empty value sends `null` and takes it off: `c11r customers update ada@example.com --customer-group null` sends `customer_group: null`, `c11r orders update 1001 --coupon-code null` sends `coupon_code: null`. A ref the schema marks `nullable: false`, and any other field, sends the text.
-- A dotted flag sets part of an object: `--customer.email ada@example.com`. An `in` filter takes several values as the flag repeated or a JSON array; on enums, numbers and dates also separated by commas, while a name or text is one value even with a comma in it (`--tax-calculator.in "UK VAT, manual"`), and a list that has one is sent as a JSON array. Any other array takes the flag repeated or a JSON array, and the same rule holds: enums, numbers and dates also separated by commas, a name or text one value per flag (`--payment-settings "Invoice, 60 days"`); an array of objects takes `key=value` pairs, one object per flag: `--items sku=COFFEE,quantity=2 --items sku=TEA,quantity=1`. Each array flag's help has a `repeat` line with its own form. `--data` takes the fields as one JSON object, or `@` and a file name.
+- A dotted flag sets part of an object: `--customer.email ada@example.com`. An `in` filter takes several values as the flag repeated or a JSON array; on enums, numbers and dates also separated by commas, while a name or text is one value even with a comma in it (`--tax-calculator.in "UK VAT, manual"`), and a list that has one is sent as a JSON array. Any other array takes the flag repeated or a JSON array, and the same rule holds: enums, numbers and dates also separated by commas, a name or text one value per flag (`--payment-settings "Invoice, 60 days"`). On `markets update` and `stores update` the payment settings are the whole list: `markets update eu --payment-settings "Wire transfer" --payment-settings Stripe` replaces the market's settings with those two, so adding one means naming the ones it has too; an array of objects takes `key=value` pairs, one object per flag: `--items sku=COFFEE,quantity=2 --items sku=TEA,quantity=1`. Each array flag's help has a `repeat` line with its own form. `--data` takes the fields as one JSON object, or `@` and a file name.
 - Amounts are in major units: `--amount 12.50`.
 - A secret field the schema marks `secret_input` (provider credentials) has no flag of its own: `--credentials-file <file>` reads it, as JSON or `KEY=value` lines, from a plain file only its owner can read (mode 600). Without the file, a terminal asks for it without echo; with neither, the command stops with `secret_required`. It is refused as a flag value or in `--data`, and never printed.
 - A field with documented values the API does not enforce (`known`: webhook topics) takes any value. One outside them is sent anyway, with the warning `unknown_value` and `did_you_mean`. Help lists up to 20 of them, and past that says how many and that `c11r schema <noun>` has them all.
@@ -53,7 +53,7 @@ Two kinds of bearer. An **organization token** (`sbx_...` from `sandbox create`,
 
 Never from a flag or the environment. c11r exchanges the pair for a two hour token at Commerce Layer and sends only that token to the c11r API; the client secret never leaves this machine. Both are kept in `credentials.json`, mode 600, and never printed. `c11r status` shows the stored login as `cli.login`, `{ client_id, email, stored_at }`, or null: read on this machine, never the secret. `auth logout` forgets the login; its last token ends by itself within two hours. Organization tokens stay.
 
-`organizations create` and `organizations connect <slug>` answer an organization token once: it is stored like a sandbox token. `connect --revoke-others` also ends every other token of that organization, and asks for confirmation. With a login and no organization token for the organization named, an organization noun stops with `no_credentials` and the next step `c11r organizations connect <slug>`. `members` and `roles` with an organization token and no login are sent with that token, and the API says what is needed: a claim for a sandbox, a login for a claimed organization. `organizations` with no login stops here with `login_required`.
+`organizations create` and `organizations connect <slug>` answer an organization token once: it is stored like a sandbox token. `connect --revoke-others` also ends every other token of that organization, and asks for confirmation. On an organization c11r does not know (one of the human's own, made outside c11r), `connect` gives commercelayer.ai admin access to it in test mode: the API answers `428 confirmation_required` with the sentence naming that access until the command runs with `--yes` (the schema marks it `confirm_when: ["unknown_organization"]`); `--dry-run` answers the same sentence. The answer carries `connected: true`, `access`, `mode: test` and `payments.flow`, and `auth login` keeps `connected_with_c11r` beside `claimed_with_c11r` and `created_with_c11r` for each organization. With a login and no organization token for the organization named, an organization noun stops with `no_credentials` and the next step `c11r organizations connect <slug>`. `members` and `roles` with an organization token and no login are sent with that token, and the API says what is needed: a claim for a sandbox, a login for a claimed organization. `organizations` with no login stops here with `login_required`.
 
 `credentials create` and `credentials token` answer a secret once. c11r writes it to a file with mode 600 and prints the file, the format and a hint, never the value: by default `~/.config/c11r/secrets/<org>/<name>.env` (`<id>-token.env` for a token; a record with no name, such as a gift card, `gift-card-<id>.env` after the id it is given), or `--out <path>`, as `KEY=value` lines or with `--format json` one JSON object. The file is checked before the request is sent; one there already is replaced only with `--yes`. A file inside a git repository that git does not ignore gets the warning `secret_not_ignored`. With `--dry-run` nothing is written and `secret_file` says where it would go. Each file records the record it belongs to. A `delete` of a record whose noun answers secrets (`credentials`, `webhooks`) removes the files c11r wrote for it in `~/.config/c11r/secrets/<org>/` (a credential's secret and tokens, a webhook's shared secret), found by the id, name or code given, and lists them in `removed_files`; `sandbox destroy` removes the whole folder of that organization and names it in `forgotten.secrets`. A file written with `--out` is not tracked and stays: the warning `out_files_not_tracked` says so on the delete of the record whose secret went to `--out` on this machine, and on `sandbox destroy` of an organization that had one. Any other delete has no such warning. A token file carries `CL_BASE_ENDPOINT` beside the token. `sales-calls book` answers a cancel token once: it is kept in `credentials.json` and `sales-calls cancel <booking>` sends it.
 
@@ -77,7 +77,7 @@ Destructive verbs (deletes, `orders cancel`, `payments void` and `refund`, `sand
 - Without a login, nothing is checked on this machine: the request goes with the organization token this machine holds for the organization named, or with no token when it holds none (never `C11R_TOKEN`), and the API's answer (`login_required`, or `state_required` for an organization not claimed) comes through as it is. So do `live_unavailable` (a plan without live), `forbidden` (the login is not an active admin of it) and `not_supported` for a verb that comes with a later step of go-live.
 - A verb that never runs live (sandbox, plans, sales calls, `auth login`, `auth switch`, `shop`) stops on this machine with `state_required`.
 - `c11r events writes --live --org <slug>` (`--since 2026-11-12T00:00:00Z`, an ISO time, `--noun`, `--cursor`, `--limit`) is the audit of live writes, and runs only in live: without `--live` it is `missing_value` with the full command, before any call.
-- `c11r status --live --org <slug>` is the organization's live status, with `live_credential` and the warning `live_credential_held` while the API holds one.
+- `c11r status --live --org <slug>` is the organization's live status, with `live_credential` and the warning `live_credential_held` while the API holds one. On a connected organization the first live call answers `428 confirmation_required` before the live credential is made; `c11r status --live --org <slug> --yes` is the yes, sent as `confirm=true` on that read. A write's `--yes` never stands for it.
 - `c11r auth logout --live --org <slug>` revokes that credential in Commerce Layer (`DELETE /v1/auth/live`): `{ org, revoked, credential }`. The login stays on this machine. `--dry-run` says what it would revoke.
 - A verb that needs a yes is confirmed by the API in live, with a sentence naming the action, the amount and the mode (`Refunds EUR 1.00 on order N, in LIVE mode, real money.`): the CLI sends it without `confirm=true` and shows that `confirmation_required` as it is, with the API's next command, or asks it with those words in a terminal. `--yes` sends `confirm=true` on every live write, `payments capture` included.
 - A verb that answers a secret (`credentials create`) writes it in live only to the file the human chose with `--out`: without it, `missing_value` with the command and `--out FILE`. Never to c11r's secrets folder, never printed. A live delete leaves the test mode's secret files of the same organization alone.
@@ -90,7 +90,9 @@ Destructive verbs (deletes, `orders cancel`, `payments void` and `refund`, `sand
 `--org`, then `C11R_ORG`, then `.c11r.json` in the project folder (found by walking up, like `.git`), then the default set by `auth switch --global`, then the stored organization when exactly one is stored (never for a login noun's `?org=`). With several stored and nothing naming one, the command stops with `org_required` and lists them.
 
 - Tokens are only in `~/.config/c11r/credentials.json` (or under `XDG_CONFIG_HOME`), mode 600. The CLI never prints one, only its hint. Each token records the host that issued it: organization and cancel tokens the API base, the login the auth endpoint. One is used, listed and forgotten only while that host is the one in effect (`C11R_API_URL`, `C11R_AUTH_URL`), so a token never goes to another host. An entry that records no host is not used, and goes at the next write.
-- `.c11r.json` holds only `{ "org": "<slug>" }`: no secret, safe to commit. `sandbox create`, `organizations create` and `auth switch` write it, and `organizations connect` when the folder has no link; `reset` follows the new slug; `destroy` removes it when it names the destroyed organization.
+- `.c11r.json` holds only `{ "org": "<slug>" }`: no secret, safe to commit. `sandbox create` and `organizations create` write it in the current folder: a link found above is another project's, stays as it is (warning `parent_link_kept`), and its token is not sent. `auth switch` writes it too, and `organizations connect` when the folder has no link; `reset` follows the new slug; `destroy` removes it when it names the destroyed organization.
+- `c11r status` shows the link in `cli.link`, with `here`: true when the `.c11r.json` is in the current folder, false when it was found above.
+- `sandbox create` sends a token only when this folder's own link, `--org`, `C11R_ORG` or `C11R_TOKEN` names the sandbox: the API then finishes a failed seed there, or refuses a second sandbox with `409 conflict`. The default of `auth switch --global` and the one stored token are not sent.
 - The project folder is the one with `.c11r.json`, else the nearest with `store.yml` or `loops.yml`, else the current one. `loops.yml` goes there.
 
 ## The store's setup in files
@@ -172,7 +174,10 @@ The CLI's own answers (help, loops.yml) have the same shape, with `state` null.
 - `profile`, `search`, `get` and `ask` only read. `get` and `ask` take the variant or the question as the bare value after the store.
 - `checkout` opens a checkout with `--item ID=QTY` (repeated) and the buyer's `--email`, `--first-name`, `--last-name`, `--phone` and `--address.street`, `--address.line-2`, `--address.locality`, `--address.postal-code`, `--address.region`, `--address.country`, all but the line 2 and the region required. Each is the human's, never invented: a missing one is `missing_value` with a human step. Before any of them is sent, `confirmation_required` shows every value and the host (`Sharing with shop.example.com: Ada Lovelace, ada@example.com, ...`); the agent asks the human and, on their yes, runs it again with `--yes`. `checkout <store> <checkout>` changes one (items, the buyer, the address, `--shipping <option>`), or with nothing to change reads it again. The answer has the totals with shipping and, when it is ready, `next` is the order.
 - `order <store> <checkout>` shows the total and asks the same way, then pays with the sandbox test handler (`ai.commercelayer.sandbox`), where no money moves, and answers the order. On a checkout already paid it answers the order and pays nothing. A checkout that is not ready is `invalid_transition`: when the store's messages name the fields it still needs, `next_step` is the command with their flags (`--phone PHONE`), and when they do not, it is a human step at the store's checkout page; a declined payment is `store_refused` with the store's words.
-- The CLI has no flag for card data. A store without the sandbox handler is `payment_handler_unsupported` before anything of the human's is sent, with the store's URL for the human to buy there in person.
+- The CLI has no flag for card data. A store without the sandbox handler is `payment_handler_unsupported` before anything of the human's is sent, with the store's URL for the human to buy on the shop's site. That includes a live shop taking Stripe's `com.stripe.payments`: Stripe wallet tokens come from agents Stripe has enrolled, and this CLI is not one yet. A shop that offers no UCP checkout (a live shop without Stripe ready keeps its catalog) is `not_supported` for checkout; `shop profile` says either with `can_pay: false` and the warning `cannot_pay_here`, not an error.
+- A checkout the store marks `payment_unavailable` (its market takes no payment from agents) answers with the warning `cannot_pay_here` and no next step, and `shop order` refuses it with `payment_handler_unsupported` before anything is completed.
+- Each checkout's own `ucp.payment_handlers`, the handlers its market takes, decides over the profile's union: without the sandbox handler there, `shop order` refuses before anything is completed. A checkout paid whose order the store could not place (`order_not_placed`) is refused with a human step every time it is run, and nothing offers to pay it again until the human has reviewed it: the store keeps the checkout `incomplete` with that note until an update, the buyer's review, clears it.
+- A payment the store has taken and not yet confirmed (`complete_in_progress`) answers `payment_in_progress`, exit 7, with `retry_later` and the same `shop order` command. Run again, it reads the checkout first and never completes it a second time: it answers the order once the store has settled it. While a payment is under way, `shop checkout` takes no changes to it (`payment_in_progress`, nothing sent). Two runs at once are safe too: the store answers a second complete with the first payment's state, and the CLI says `payment_in_progress` again.
 - With `--dry-run`, checkout answers what it would send and order the total it would pay: nothing is sent.
 
 ## Skills

package/dist/builtins/auth.js

@@ -70,6 +70,9 @@ export const auth = {
         return undefined;
     },
 };
+/** How the organization came to c11r, as the API marks it: at most one of the three is true. */
+const MARKERS = ['claimed_with_c11r', 'created_with_c11r', 'connected_with_c11r'];
+const markers = (o) => Object.fromEntries(MARKERS.filter((k) => o[k] !== undefined).map((k) => [k, o[k]]));
 async function login(run) {
     const v = run.parsed.values;
     const prompter = run.prompter ?? terminal;
@@ -114,7 +117,7 @@ async function login(run) {
             token: minted.token,
             expires_at: minted.expires_at,
             user: who.data?.user ?? null,
-            organizations: items.map((o) => ({ slug: o.slug, name: o.name, plan: o.plan ?? null, ...(o.claimed_with_c11r !== undefined ? { claimed_with_c11r: o.claimed_with_c11r } : {}) })),
+            organizations: items.map((o) => ({ slug: o.slug, name: o.name, plan: o.plan ?? null, ...markers(o) })),
             created_at: new Date().toISOString(),
         });
     }
@@ -168,7 +171,7 @@ async function switchOrg(run) {
         reached = items.map((o) => o.slug);
         const l = storedLogin();
         if (l)
-            storeLogin({ ...l, organizations: items.map((o) => ({ slug: o.slug, name: o.name, plan: o.plan ?? null })) });
+            storeLogin({ ...l, organizations: items.map((o) => ({ slug: o.slug, name: o.name, plan: o.plan ?? null, ...markers(o) })) });
     }
     if (!tokens[slug] && !reached.includes(slug)) {
         const known = [...new Set([...Object.keys(tokens), ...reached])];

package/dist/builtins/extensions.js

@@ -11,7 +11,7 @@ import crypto from 'node:crypto';
 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 { credentialsFile, forgetOrg, forgetOutWritten, hintOf, projectDir, readLink, removeLink, parentLinkKept, 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';
@@ -64,15 +64,20 @@ export const organizations = {
         })();
         let linked = null;
         if (run.verb.name === 'create' || !existing || existing.org === org) {
-            const link = writeLink(org);
+            // A create links this folder; a link found above stays as it is.
+            const create = run.verb.name === 'create';
+            const link = writeLink(org, { here: create });
             linked = link.file;
+            if (create && existing && !existing.here)
+                warnings.push(parentLinkKept(existing));
             if (link.previous)
                 warnings.push({ code: 'relinked', message: `${link.file} named ${link.previous}; it now names ${org}. The token of ${link.previous} stays stored.` });
         }
         else {
             warnings.push({ code: 'not_linked', message: `${existing.file} names ${existing.org}, so this folder stays linked to it. --org ${org}, or c11r auth switch ${org}, acts on ${org}.` });
         }
-        if (typeof data.revoked === 'number') {
+        // Only when --revoke-others asked: a first connect answers revoked: 0 as well.
+        if (typeof data.revoked === 'number' && run.parsed.values.revoke_others) {
             warnings.push({ code: 'tokens_revoked', message: data.revoked ? `${data.revoked} other organization token${data.revoked === 1 ? '' : 's'} of ${org} no longer work${data.revoked === 1 ? 's' : ''}, on whatever machine held them.` : `No other organization token of ${org} was in use.` });
         }
         return { ...r, data: { ...data, org, token_hint: hint, credentials: credentialsFile(), linked }, warnings };

package/dist/builtins/sandbox.js

@@ -4,7 +4,7 @@
 // reset moves both to the new organization; destroy forgets them. The token is printed never,
 // not even by create: only its hint.
 import crypto from 'node:crypto';
-import { credentialsFile, defaultOrg, forgetOutWritten, storedLogin, forgetOrg, LINK_FILE, readLink, removeLink, renameOrg, storedOrgs, storeOrg, writeLink, hintOf } from '../config.js';
+import { credentialsFile, defaultOrg, forgetOutWritten, storedLogin, forgetOrg, LINK_FILE, readLink, removeLink, renameOrg, parentLinkKept, storedOrgs, storeOrg, writeLink, hintOf } from '../config.js';
 import { CliError, fail } from '../errors.js';
 import { apiUrl, envelope, request } from '../http.js';
 import { parseSchema } from '../schema.js';
@@ -44,7 +44,7 @@ export const sandbox = {
                     SEED,
                     CATALOGUE,
                 ],
-                effect: 'Creates a sandbox, stores its token on this machine (never printed) and links this folder to it with .c11r.json. With --seed it answers once the seed and its storefront are in place, in about 20 seconds, with the shop link.',
+                effect: 'Creates a sandbox, stores its token on this machine (never printed) and links this folder to it with .c11r.json, in this folder: a link in a folder above is another project\'s and stays as it is. With --seed it answers once the seed and its storefront are in place, in about 20 seconds, with the shop link.',
             },
             { verb: 'get', method: 'GET', path: '/v1/sandbox', live: false, effect: 'Returns the sandbox: organization, expiry, whether it is seeded, the token hint and the claim status.' },
             {
@@ -92,10 +92,12 @@ async function create(run, values) {
     }
     const { seed, catalogue } = seedBody(values);
     const test = process.env.C11R_TEST === '1' || Boolean(name?.startsWith('zztest'));
-    // The token goes only when this folder, --org or C11R_ORG names a sandbox: the API then
-    // finishes a failed seed there, or answers 409 conflict naming it, rather than make a second
-    // one for the same folder. A token picked only because it is the one stored stays home.
-    const named = run.org.source === 'link' || run.org.source === 'flag' || run.org.source === 'env' || run.org.source === 'token_env';
+    // The token goes only when this folder's own link, --org, C11R_ORG or C11R_TOKEN names a
+    // sandbox: the API then finishes a failed seed there, or answers 409 conflict naming it, rather
+    // than make a second one for the same folder. A link found above is another project's, and a
+    // token picked as the default or as the only one stored stays home: the create makes a new one.
+    const above = readLink();
+    const named = (run.org.source === 'link' && above?.here === true) || run.org.source === 'flag' || run.org.source === 'env' || run.org.source === 'token_env';
     // A fresh key per create: after a 5xx or a lost connection the same create is repeated with it,
     // and the API answers the sandbox (and token) it made, rather than leave one with a lost token.
     const idempotencyKey = `c11r-${crypto.randomBytes(16).toString('base64url')}`;
@@ -107,9 +109,11 @@ async function create(run, values) {
         fail('invalid_response', 'The API created a sandbox without returning its org and token.', { next_step: { action: 'none' } });
     const hint = typeof data.token_hint === 'string' ? data.token_hint : hintOf(token);
     storeOrg(data.org, { token, token_hint: hint, expires_at: data.expires_at ?? null, created_at: new Date().toISOString(), api_url: apiUrl() });
-    const link = writeLink(data.org);
+    const link = writeLink(data.org, { here: true });
     // The API says to store the token: the CLI has, and printed none of it.
     const warnings = r.warnings.filter((w) => w.code !== 'token_shown_once');
+    if (above && !above.here)
+        warnings.push(parentLinkKept(above));
     if (link.previous)
         warnings.push({ code: 'relinked', message: `${link.file} named ${link.previous}; it now names ${data.org}. The token of ${link.previous} stays stored.` });
     return withShop({ ...r, data: { ...data, token_hint: hint, credentials: credentialsFile(), linked: link.file }, warnings }, data.store);
@@ -178,12 +182,14 @@ export const status = {
         noun: 'status',
         kind: 'task',
         description: 'c11r status: where this machine and folder stand. The organization picked and from where, its lifecycle state, plan, mode, limits, usage and what is waiting.',
-        verbs: [{ verb: 'get', method: 'GET', path: '/v1/status', state: 'none', effect: 'Returns the status. c11r status is the same as c11r status get.' }],
+        verbs: [{ verb: 'get', method: 'GET', path: '/v1/status', state: 'none', effect: 'Returns the status. c11r status is the same as c11r status get. With --live --yes it sends confirm=true: on an organization connected to c11r, the first live call asks for it once, before the live credential is made.' }],
     }),
     defaultVerb: 'get',
     async run(run) {
         // Status works at every state: an unresolved organization is shown, not raised.
-        const r = await run.send({ method: 'GET', path: '/status' });
+        // In live, --yes is the human's yes to the live credential of a connected organization
+        // (contract 49.4): only this read, confirmed, makes it, never a write's --yes.
+        const r = await run.send({ method: 'GET', path: '/status', ...(run.globals.live && run.globals.yes && !run.globals.dryRun ? { confirm: true } : {}) });
         const link = (() => {
             try {
                 return readLink();
@@ -198,7 +204,7 @@ export const status = {
             api_url: apiUrl(),
             org: run.org.org ? { slug: run.org.org, from: run.org.source } : null,
             ...(run.org.problem ? { org_problem: { code: run.org.problem.code, message: run.org.problem.message } } : {}),
-            link: link ? { file: link.file, org: link.org } : { file: null, name: LINK_FILE },
+            link: link ? { file: link.file, org: link.org, here: link.here } : { file: null, name: LINK_FILE, here: false },
             credentials: credentialsFile(),
             stored,
             login: (() => {

package/dist/builtins/shop.js

@@ -13,7 +13,7 @@ import { confirm } from '../confirm.js';
 import { fail } from '../errors.js';
 import { envelope } from '../http.js';
 import { parseSchema } from '../schema.js';
-import { call, discover, handlersOf, minorOf, money, mustPay, originOf, sandboxPayment } from '../ucp.js';
+import { call, cannotPay, discover, SANDBOX_HANDLER, handlersOf, minorOf, money, mustPay, originOf, sandboxPayment } from '../ucp.js';
 const ADDRESS = [
     { name: 'street', type: 'string', description: 'Street and number: Via Roma 1.' },
     { name: 'line_2', type: 'string', description: 'Apartment, floor, care of.' },
@@ -151,7 +151,7 @@ function profile(store) {
         signed: store.keys.length > 0,
     }, {
         next: [{ command: cmd(store, 'search', '--query WORDS'), why: 'what the store sells' }],
-        warnings: can_pay ? [] : [{ code: 'cannot_pay_here', message: `This CLI pays only with the sandbox test handler; ${store.host} ${handlers.length ? `takes ${handlers.join(', ')}` : 'takes no payment over UCP'}. The human buys there in person.` }],
+        warnings: can_pay ? [] : [{ code: 'cannot_pay_here', message: cannotPay(store).message }],
     });
 }
 // ---------- reading
@@ -352,7 +352,31 @@ function checkoutView(ck, store) {
         expires_at: ck.expires_at,
     });
 }
+const hasCode = (ck, code) => (ck.messages ?? []).some((x) => x.code === code);
+/**
+ * Why this checkout takes no payment from this CLI: the store's payment_unavailable (its market
+ * takes no payment from agents), or its own handler list, the authority over the profile's union,
+ * without the sandbox handler.
+ */
+function unpayable(ck, store) {
+    const m = (ck.messages ?? []).find((x) => x.code === 'payment_unavailable');
+    if (m)
+        return `${store.host} can't take a payment from agents for checkout ${ck.id}${m.content ? `: ${m.content}` : '.'} The human buys on the shop's site.`;
+    const own = ck.ucp?.payment_handlers;
+    if (own && typeof own === 'object' && !Object.keys(own).includes(SANDBOX_HANDLER)) {
+        return cannotPay(store, { id: ck.id, handlers: Object.keys(own) })?.message ?? null;
+    }
+    return null;
+}
+/** The store took the payment and Commerce Layer would not place the order: nothing is paid again until the human has reviewed the checkout. */
+function notPlaced(store, ck) {
+    const m = (ck.messages ?? []).find((x) => x.code === 'order_not_placed');
+    fail('order_not_placed', `${store.host} took the payment for checkout ${ck.id}, but could not place the order${m?.content ? `: ${m.content}` : '.'} Don't pay again until the human has reviewed the checkout, at its page.`, { details: { status: ck.status, messages: ck.messages ?? [] }, next_step: { action: 'human_step', url: ck.continue_url ?? store.origin } }, 'rejected');
+}
 function nextOf(ck, store) {
+    // Nothing to pay here, or paid already with the order not placed: no command offers to pay.
+    if (unpayable(ck, store) || hasCode(ck, 'order_not_placed'))
+        return [];
     if (ck.status === 'ready_for_complete')
         return [{ command: cmd(store, 'order', ck.id), why: `pay ${ck.totals ? money(ck.totals.find((t) => t.type === 'total')?.amount ?? 0, ck.currency).display : 'the total'} with the sandbox test handler, after the human's yes on it` }];
     if (ck.status === 'completed' && ck.order?.id)
@@ -368,6 +392,9 @@ async function checkout(run, store) {
     const lines = items(v.item);
     const { buyer, address } = given(v);
     const current = id ? (await call(store, 'GET', `${store.endpoint}/checkout-sessions/${encodeURIComponent(id)}`, undefined, `checkout ${id}`)).body : null;
+    // A payment under way takes no changes (the store answers not_allowed): read it again with order.
+    if (current?.status === 'complete_in_progress' && (lines.length || Object.keys(buyer).length || Object.keys(address).length || v.shipping))
+        inProgress(store, id);
     if (current && (current.status === 'completed' || current.status === 'canceled')) {
         if (lines.length || Object.keys(buyer).length || Object.keys(address).length || v.shipping) {
             fail('invalid_transition', `Checkout ${id} is ${current.status}: it takes no changes.`, { details: { status: current.status }, next_step: current.status === 'completed' ? { action: 'fix_request', command: cmd(store, 'order', id) } : { action: 'fix_request', command: cmd(store, 'checkout', `--item VARIANT=QTY ${HUMAN_FLAGS}`) } }, 'rejected');
@@ -450,7 +477,8 @@ async function checkout(run, store) {
         c = await call(store, 'PUT', `${store.endpoint}/checkout-sessions/${encodeURIComponent(c.body.id)}`, again, `checkout ${c.body.id}`);
     }
     const ck = c.body;
-    return answer(checkoutView(ck, store), c, { next: nextOf(ck, store) });
+    const why = unpayable(ck, store);
+    return answer(checkoutView(ck, store), c, { next: nextOf(ck, store), warnings: why ? [{ code: 'cannot_pay_here', message: why }] : [] });
 }
 // ---------- order
 function orderView(o, store, checkoutId) {
@@ -482,7 +510,16 @@ async function order(run, store) {
         return placed(store, ck, false);
     if (ck.status === 'canceled')
         fail('invalid_transition', `Checkout ${id} was canceled: it cannot be paid.`, { details: { status: ck.status }, next_step: { action: 'fix_request', command: cmd(store, 'checkout', `--item VARIANT=QTY ${HUMAN_FLAGS}`) } }, 'rejected');
+    // A payment under way is read again, never completed a second time.
+    if (ck.status === 'complete_in_progress')
+        inProgress(store, id);
+    // Paid, and the order not placed: not paid again until the human's review (an update) clears the store's note.
+    if (hasCode(ck, 'order_not_placed'))
+        notPlaced(store, ck);
     mustPay(store, { continue_url: ck.continue_url ?? null });
+    const why = unpayable(ck, store);
+    if (why)
+        fail('payment_handler_unsupported', why, { details: { status: ck.status, messages: ck.messages ?? [] }, next_step: { action: 'human_step', url: ck.continue_url ?? store.origin } }, 'rejected');
     if (ck.status !== 'ready_for_complete') {
         const said = (ck.messages ?? []).map((m) => m.content).filter(Boolean).join(' ');
         fail('invalid_transition', `Checkout ${id} is ${ck.status}, not ready to pay${said ? `: ${said}` : '.'}`, { details: { status: ck.status, messages: ck.messages ?? [] }, next_step: stillNeeds(ck, store) ? { action: 'fix_request', command: stillNeeds(ck, store) } : { action: 'human_step', url: ck.continue_url ?? null } }, 'rejected');
@@ -495,10 +532,18 @@ async function order(run, store) {
     await confirm(`Pay checkout ${id}`, run.line, { yes: run.globals.yes, prompter: run.prompter, sentence, details: { store: store.host, checkout: id, total } });
     const c = await call(store, 'POST', `${store.endpoint}/checkout-sessions/${encodeURIComponent(id)}/complete`, sandboxBody(), `checkout ${id}`);
     const done = c.body;
+    if (done.status === 'complete_in_progress')
+        inProgress(store, id);
+    if (hasCode(done, 'order_not_placed'))
+        notPlaced(store, done);
     if (done.status !== 'completed' || !done.order?.id) {
         const said = (done.messages ?? []).map((m) => m.content).filter(Boolean).join(' ');
         fail('store_refused', `${store.host} did not take the payment for checkout ${id}${said ? `: ${said}` : '.'}`, { details: { status: done.status, messages: done.messages ?? [] }, next_step: { action: 'human_step', url: done.continue_url ?? null } }, 'rejected');
     }
     return placed(store, done, true);
 }
+/** The store took the payment and has not finished it: the agent reads it again, and pays nothing more. */
+function inProgress(store, id) {
+    fail('payment_in_progress', `${store.host} is still taking the payment for checkout ${id}: it is not confirmed yet. Run the same command again in a moment: it reads the checkout first and never pays twice. Until it answers the order, don't tell the human it is paid.`, { details: { status: 'complete_in_progress' }, next_step: { action: 'retry_later', command: cmd(store, 'order', id) } });
+}
 const sandboxBody = () => ({ ...sandboxPayment(), signals: { 'dev.ucp.user_agent': 'c11r' } });

package/dist/config.js

@@ -6,6 +6,8 @@
 // A project folder links to its organization with .c11r.json, { "org": "<slug>" }: no secret,
 // safe to commit, found by walking up from the current folder like .git. The project folder is
 // the one with .c11r.json, else the nearest with store.yml or loops.yml, else the current one.
+// A link found above is the folder's for every command but a create: sandbox create and
+// organizations create link the current folder, and leave the link above as it is.
 //
 // The organization: --org, then C11R_ORG, then .c11r.json, then the stored one when exactly one
 // is stored. With several stored and nothing naming one, the command stops and names them.
@@ -191,15 +193,23 @@ export function readLink() {
     const org = raw?.org;
     if (typeof org !== 'string' || !org)
         fail('invalid_config', `${file} has no org.`, { path: `${LINK_FILE}.org` });
-    return { file, org };
+    return { file, org, here: dir === path.resolve(process.cwd()) };
 }
-/** Links the project folder to the organization; returns the file and the org it linked before. */
-export function writeLink(org) {
-    const existing = readLink();
+/**
+ * Links the project folder to the organization; returns the file and the org it linked before.
+ * With here, the current folder, whatever a folder above links: a create makes a new project.
+ */
+export function writeLink(org, opts = {}) {
+    const found = readLink();
+    const existing = opts.here && !found?.here ? null : found;
     const file = existing?.file ?? path.join(process.cwd(), LINK_FILE);
     fs.writeFileSync(file, JSON.stringify({ org }, null, 2) + '\n');
     return { file, previous: existing && existing.org !== org ? existing.org : null };
 }
+/** The warning of a create that linked this folder and left the link of a folder above as it is. */
+export function parentLinkKept(above) {
+    return { code: 'parent_link_kept', message: `The folder above links ${above.org} (${above.file}); it stays as it is, and this folder now has its own link. Tell the human only that the shop in the folder above stays as it is.` };
+}
 /** Removes the link, only when it names this organization. */
 export function removeLink(org) {
     const link = readLink();

package/dist/engine.js

@@ -132,8 +132,10 @@ async function executeOnce(argv, opts) {
     // amount and the mode ("Refunds EUR 1.00 on order N, in LIVE mode, real money."): the CLI sends
     // without confirm=true and shows that 428 as it is, or asks it in a terminal. --yes sends
     // confirm=true on every live write, payments capture included.
-    // So does a login verb (organizations disconnect), whose sentence names what stops answering.
-    const apiAsks = (live || verb.credential === 'login') && (verb.confirm || confirmFlags.length > 0);
+    // So does a login verb (organizations disconnect), whose sentence names what stops answering,
+    // and one the schema marks confirm_when: the API asks only in that state of the target
+    // (connect on an organization c11r does not know), with a sentence naming the access given.
+    const apiAsks = (live || verb.credential === 'login') && (verb.confirm || confirmFlags.length > 0 || verb.confirmWhen.length > 0);
     if (apiAsks && cmd.globals.yes && !cmd.globals.dryRun)
         confirmed = true;
     if (live && cmd.globals.yes && verb.method !== 'GET')

package/dist/errors.js

@@ -66,6 +66,10 @@ const KIND = {
     store_unavailable: 'unavailable',
     store_refused: 'rejected',
     payment_handler_unsupported: 'rejected',
+    // The store took the payment and has not confirmed it: read again, never paid twice.
+    payment_in_progress: 'unavailable',
+    // Paid at the store, and the order not placed: the human reviews it; never paid again.
+    order_not_placed: 'rejected',
     // The site that publishes the skills (c11r skills sync).
     site_unavailable: 'unavailable',
 };

package/dist/schema.js

@@ -63,6 +63,7 @@ export function parseSchema(raw, expected) {
             secret: Boolean(v.secret),
             idAlternative: Array.isArray(v.id_alternative) ? v.id_alternative.filter((x) => typeof x === 'string' && flags[x]) : [],
             confirmIf: Array.isArray(v.confirm_if) ? v.confirm_if.filter((x) => typeof x === 'string') : [],
+            confirmWhen: Array.isArray(v.confirm_when) ? v.confirm_when.filter((x) => typeof x === 'string') : [],
             refused: v.served === false ? { by: v.refused_by ?? 'the API' } : null,
             path: v.path ? v.path.replace(/^\/v\d+(?=\/)/, '') : null,
             flags,

package/dist/ucp.js

@@ -55,20 +55,41 @@ export async function discover(origin) {
             capabilities.add(name);
     return { origin, host, profile, endpoint, commonEndpoint: rest('dev.ucp.common'), capabilities, keys: Array.isArray(profile.keys) ? profile.keys : [] };
 }
+/** Stripe's UCP handler: agents pay with a Stripe wallet token (spt_), which this CLI does not hold. */
+export const STRIPE_HANDLER = 'com.stripe.payments';
 /** The payment handlers the store offers, by name, and whether this CLI can pay there. */
 export function handlersOf(store) {
     const handlers = Object.keys(store.profile.ucp?.payment_handlers ?? {});
     return { handlers, can_pay: handlers.includes(SANDBOX_HANDLER) && store.capabilities.has('dev.ucp.shopping.checkout') };
 }
-/** Before anything of the human's is sent: a store this CLI cannot pay at is refused. */
-export function mustPay(store, extra = {}) {
+/** Why this CLI cannot pay at the store, in words for the human; null when it can. */
+export function cannotPay(store, checkout) {
+    const handlers = checkout?.handlers ?? handlersOf(store).handlers;
+    if (handlers.includes(SANDBOX_HANDLER) && store.capabilities.has('dev.ucp.shopping.checkout'))
+        return null;
+    // A checkout's own list, the authority over the profile's union: named, so the human knows which.
+    const who = checkout ? `${store.host}, for checkout ${checkout.id},` : store.host;
+    const elsewhere = `The human buys on the shop's site.`;
     if (!store.capabilities.has('dev.ucp.shopping.checkout')) {
-        fail('not_supported', `${store.host} offers no UCP checkout: an agent can browse it, not buy there.`, { next_step: { action: 'human_step', url: store.origin } });
+        return { code: 'not_supported', message: `${who} doesn't take orders from agents yet: an agent can show its products, not buy them. ${elsewhere}` };
     }
-    const { handlers } = handlersOf(store);
-    if (!handlers.includes(SANDBOX_HANDLER)) {
-        fail('payment_handler_unsupported', `${store.host} takes ${handlers.length ? handlers.join(', ') : 'no payment handler'}; this CLI pays only with the ${SANDBOX_HANDLER} test handler, where no money moves. The human buys there in person.`, { details: { handlers }, next_step: { action: 'human_step', url: extra.continue_url ?? store.origin } }, 'rejected');
+    if (!handlers.length)
+        return { code: 'payment_handler_unsupported', message: `${who} takes no payment from agents yet. ${elsewhere}` };
+    const only = 'This CLI pays only in test shops, with the sandbox test handler, where no money moves.';
+    if (handlers.includes(STRIPE_HANDLER)) {
+        return { code: 'payment_handler_unsupported', message: `${who} takes agent payments through Stripe, from agents Stripe has enrolled, and this CLI is not one of them yet. ${only} ${elsewhere}` };
     }
+    return { code: 'payment_handler_unsupported', message: `${who} takes ${handlers.join(', ')}, which this CLI can't pay with. ${only} ${elsewhere}` };
+}
+/** Before anything of the human's is sent: a store this CLI cannot pay at is refused. */
+export function mustPay(store, extra = {}) {
+    const why = cannotPay(store);
+    if (!why)
+        return;
+    const { handlers } = handlersOf(store);
+    if (why.code === 'not_supported')
+        fail('not_supported', why.message, { details: { handlers }, next_step: { action: 'human_step', url: store.origin } });
+    fail(why.code, why.message, { details: { handlers }, next_step: { action: 'human_step', url: extra.continue_url ?? store.origin } }, 'rejected');
 }
 export const sandboxPayment = () => ({ payment: { instruments: [{ id: 'pi_1', handler_id: SANDBOX_HANDLER_ID, type: 'card', selected: true, credential: { type: SANDBOX_CREDENTIAL_TYPE, token: SANDBOX_TOKEN_SUCCESS } }] } });
 /** A UCP call. The answer's digest and signature are checked; an error is a CliError. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "1.0.0-dev.21",
+  "version": "1.0.0-dev.23",
   "description": "c11r: the Commerce Layer CLI for coding agents. One grammar, c11r <noun> <verb>, from a sandbox to a running organization.",
   "homepage": "https://commercelayer.ai",
   "keywords": [