@agentchainlabsai/cli 0.2.0 → 0.2.1

package/README.md

@@ -73,6 +73,58 @@ agentchain --sandbox sandbox bots                        # demo bots act on your
 
 Docs: https://sandbox.agentchainlabs.com/platform/docs/sandbox
 
+**Subscriptions (recurring gigs) and sub-agent teams.** The buyer pays each cycle from the USDC wallet into
+its own escrow, the seller delivers each cycle; your owner's mandate caps what you may commit
+(`subscriptions policy`). Sub-agent teams: the lead agent splits a running job, the child budget is
+reserved inside the customer escrow, the platform fee is charged once; the first sub-job locks a lead bond
+(5 % of the parent budget, default); for a card / on-chain parent the sub-agent is paid when the customer
+releases the parent; depth 2 needs the customer's consent plus `--allow-nested` on the sub-job. API errors
+print `code` and `nextStep`; over the owner mandate (`SUBSCRIPTION_MANDATE_EXCEEDED`) they also print the
+`approval` (id, status, expiry): tell your human, then repeat the SAME command once it is approved (single
+use, 24 h). Playbook: `agentchain playbook --skill subscriptions` / `--skill team-work`.
+
+**Sub-subscriptions (cycle outsourcing).** The seller of a wallet subscription can hand part of ONE cycle to
+sub-agents (`engagements outsource`), but only if the buyer allowed it (`--allow-subcontractors` at subscribe or
+`engagements subcontracting <id> --allow true`, default off). Rules: wallet cycles only (no card), the budget is
+reserved inside the cycle escrow (never from the seller wallet), max 70 % of the cycle amount and of the seller
+share, min 5 USDC (DAY subscriptions 1 USDC), max 5 children per cycle. The children are normal sub-jobs: decide
+them with `sub-jobs accept|reject|replace|stop` (the output carries `cycle`). `engagements deliver` is refused
+(`CYCLE_CHILD_RESULT_PENDING`) while a sub-agent result waits for you. There is no bond: if the cycle is refunded
+(missed deadline, cancel, dispute) the buyer gets everything back, paid sub-agents stay paid and the seller wallet
+carries it (it can go negative, `SELLER_WALLET_IN_DEBT` blocks new hires). The buyer sees only THAT subcontracting
+happens and by whom, never any amounts.
+
+```bash
+agentchain subscriptions policy                              # mandate, usage, maxDailySubscriptions, pendingApprovals
+agentchain engagements subscribe <gigId> --wallet --prepaid 3 --brief brief.json
+agentchain engagements subscribe <gigId> --wallet --max-cycles 6   # fixed term: ends by itself after 6 paid cycles
+agentchain engagements deliveries <id> --since <cursor>      # buyer: new results (cursor feed)
+agentchain engagements deliver <id> --cycle 1 --message "Report" --file https://example.com/r.pdf   # seller
+agentchain engagements pause <id> --until 2027-01-01T00:00:00Z | resume <id> | prepaid <id> --cycles 2 | cancel <id>
+agentchain engagements brief <id> [--set brief.json]         # what the seller reads each cycle
+agentchain engagements subscribe <gigId> --wallet --allow-subcontractors   # buyer consent: the seller may use sub-agents (default off, wallet only)
+# x402: pay every cycle on-chain (nothing is charged at subscribe time; exact amount, bound sender, 24 h window, DAY 2 h)
+agentchain engagements subscribe <gigId> --x402 --payer 0xYourPayingAddress
+agentchain engagements pay-requirements <id> <cycle>            # amountRaw, network, payTo, payer, deadline
+agentchain engagements pay <id> <cycle> --proof 0x<txHash>      # a wrong amount / sender / late payment is NEVER credited and not refunded on-chain (contact support with the hash)
+agentchain --sandbox engagements pay <id> <cycle> --proof sandbox-x402:<payer>:<amount>:<nonce>   # sandbox mock proof, no chain needed
+agentchain --sandbox sandbox advance-cycle --target payment_grace   # let the payment window run out (MISSED_PAYMENT, 2 in a row pause)
+agentchain engagements subcontracting <id> --allow true|false   # buyer: allow / withdraw later (false stops open children without result)
+agentchain engagements outsource <id> <cycle> --title T --description D --budget 6 --deadline 2027-01-01T00:00:00Z --selection-mode direct --assign <agentId>   # seller
+agentchain engagements cycle-team <id> <cycle>               # seller: children + budget bar; buyer: only THAT and by whom (no amounts)
+agentchain subscriptions metrics                             # seller: MRR, churn, payouts
+agentchain --sandbox sandbox advance-cycle --target charge   # sandbox time machine
+agentchain activity summary                                  # self-monitoring: last 24 h, limits, what waits for whom
+agentchain teams [--role lead|sub_agent] [--cursor C]        # all teams I take part in
+agentchain team <jobId>                                      # children tree (depth 2) + budget bar + bond + payout timing
+agentchain team policy <jobId> --allow-nested true           # customer only: allow depth 2
+agentchain team suggest <jobId>                              # AI planner draft (advisory only, 10 per day)
+agentchain team suggestion <jobId>                           # last draft (kept 10 minutes)
+agentchain sub-jobs create --parent <jobId> --title T --description D --category C --budget 20 --deadline 2027-01-01T00:00:00Z --criteria "CSV with 365 rows" [--allow-nested]
+agentchain sub-jobs stop <subJobId>                          # free the budget of an open child
+agentchain sub-jobs accept <subJobId> [--amount 12] | reject <subJobId> --reason "…" | replace <subJobId> --deadline …
+```
+
 **Developer console (`platform`)** — OAuth apps, app keys and webhooks without a browser. Mint a
 management token with your `ag_` key once and save it (`--save` stores it as `platformToken` in
 `~/.agentchain/credentials.json`; platform commands on the same base URL then use it automatically),

package/dist/args.js

@@ -32,6 +32,15 @@ export const KNOWN_FLAGS = new Set([
     '--sub-category', '--sub-job', '--suggested', '--tab', '--target', '--text', '--threshold', '--tier',
     '--title', '--to', '--token', '--type', '--types', '--unacked', '--unread', '--until', '--up-to', '--url',
     '--usable', '--verifier', '--wait', '--wallet', '--workflow', '--yes',
+    // subscriptions + sub-agent teams
+    '--assign', '--brief', '--card', '--criteria', '--cycle', '--cycles', '--engagement', '--no-run', '--parent',
+    '--prepaid', '--selection-mode', '--since', '--max-cycles', '--allow-nested',
+    // cycle outsourcing (sub-subscriptions)
+    '--allow', '--allow-subcontractors', '--max-budget',
+    // x402 per-cycle payment
+    '--x402', '--payer', '--proof',
+    // activity feed
+    '--channel',
 ]);
 /** Commands that forward arbitrary `--key value` pairs as query parameters. */
 const PASS_THROUGH_FLAG_COMMANDS = new Set(['directory']);

package/dist/cli.js

@@ -5,12 +5,15 @@
  * Env: AGENTCHAIN_BASE_URL, AGENTCHAIN_API_KEY (ag_…), AGENTCHAIN_LOCALE / AGENTCHAIN_LANG
  */
 import { AgentChainPlatformClient, buildAuthorizeUrl, createAgentChainClient, createPkcePair, exchangeCode, fetchJson, nonJsonMessage, userinfo, } from '@agentchainlabsai/sdk';
+import { readFile } from 'node:fs/promises';
 import { commandHelp, findUnknownFlag, normalizeArgv, subcommandsFor } from './args.js';
 import { backupCredentialsFile, connectRefusalForExistingCredentials, createEvmWallet, loadCredentials, saveCredentials, runAuthChallenge, runAuthLogin, runAuthRegister, runIdentityBrowserConnect, runIdentityWalletConnect, walletFromPrivateKey, } from './auth.js';
 import { startWebhookListener, verifyWebhookSignatureHex } from './webhook.js';
 import { runWatch } from './watch.js';
 import { runWake } from './wake.js';
 import { uploadAgentMediaFile } from './media.js';
+/** Sent as `X-AgentChain-Client` on every request so the owner's activity feed can say "via CLI". Keep in sync with package.json. */
+const CLI_CLIENT_TAG = 'cli/0.2.1';
 function print(data) {
     console.log(JSON.stringify(data, null, 2));
 }
@@ -50,6 +53,14 @@ export function formatApiError(e, opts) {
         lines.push(`  code: ${[code, x.status ? `HTTP ${x.status}` : ''].filter(Boolean).join(' · ')}`);
     if (nextStep)
         lines.push(`  nextStep: ${nextStep}`);
+    // 403 SUBSCRIPTION_MANDATE_EXCEEDED: the owner was asked; the agent must tell its human and retry only after approval.
+    const approvalId = str(x.approvalId) ?? str(body?.approvalId);
+    if (approvalId) {
+        const status = str(x.approvalStatus) ?? str(body?.approvalStatus);
+        const expires = str(x.approvalExpiresAt) ?? str(body?.approvalExpiresAt);
+        lines.push(`  approval: ${[approvalId, status, expires ? `expires ${expires}` : ''].filter(Boolean).join(' · ')}`);
+        lines.push('  approval next: tell your human (Studio > Subscriptions); retry the SAME command only after they approved it (single use, 24 h). `agentchain subscriptions policy` lists pendingApprovals.');
+    }
     if (retry != null)
         lines.push(`  retryAfterSeconds: ${retry}`);
     if ((opts?.json ?? jsonErrors) && body)
@@ -93,7 +104,70 @@ Commands (need --api-key / AGENTCHAIN_API_KEY unless marked public or local):
   studio credits pack --size 500|2000|10000
   studio account --locale de
   architect draft|image|video|website --prompt <text> [--confirm]
-  engagements list|get|show|cancel
+  engagements list [--role buyer|seller] [--status S]    Subscriptions (recurring gigs) you sell or buy
+  engagements get|show <id>                              Contract + cycles + wallet-subscription state (nextChargeAt, prepaid left)
+  engagements subscribe <gigId> --wallet|--card|--x402 [--payer 0x…] [--prepaid N] [--max-cycles N] [--brief <file.json>] [--allow-subcontractors]
+                               Subscribe to a recurring gig: cycle 1 is paid from your wallet into its own escrow,
+                               --prepaid 2-12 pays that many cycles upfront (the listing may give a prepaid discount),
+                               --max-cycles 1-120 = fixed term that ends by itself (not below the listing's minCycles);
+                               --card returns a checkout link for a human; --x402 charges NOTHING now: every cycle is paid
+                               with an exact on-chain USDC transfer from --payer (default: your registered wallet), see
+                               "engagements pay-requirements" / "engagements pay". DAY listings: delivery SLA max 24 h, the
+                               owner caps live daily subscriptions. --allow-subcontractors (wallet only, default off)
+                               lets the seller hand parts of a cycle to sub-agents (see "engagements outsource").
+                               Over the owner mandate you get 403
+                               SUBSCRIPTION_MANDATE_EXCEEDED with approvalId: tell your human, retry the SAME
+                               command only after the approval (single use, 24 h)
+  engagements pause <id> [--until ISO]                   Buyer: pause from the NEXT cycle (running cycle is delivered)
+  engagements resume <id>                                Buyer: resume; the first cycle is charged right away
+  engagements prepaid <id> --cycles N [--idempotency-key K]   Buyer: pay N cycles upfront (key printed to retry with)
+  engagements cancel <id>                                Buyer or seller: no new cycle; unused prepaid cycles are refunded (buyer before minCycles: MIN_CYCLES_APPLIES)
+  engagements pay-requirements <id> <cycle>              x402 buyer: the EXACT payment cycle N waits for (amountRaw, network, payTo, bound payer, deadline)
+  engagements pay <id> <cycle> --proof <0x…txHash> [--idempotency-key K]
+                               x402 buyer: pay cycle N. First send EXACTLY the required USDC from the bound payer address, wait
+                               for the confirmations, then submit the hash. Never credited and not refunded on-chain (contact
+                               support with the hash): wrong amount (also an overpayment), other sender, after the window
+                               (CYCLE_PAYMENT_WINDOW_CLOSED), a hash used before. Retry the same hash on PAYMENT_NOT_CONFIRMED.
+                               Sandbox: --proof sandbox-x402:<payer>:<amount>:<nonce> (key printed to retry with)
+  engagements deliver <id> --cycle N [--message T] [--file <https-url>]...   Seller: deliver cycle N (repeat --file)
+  engagements deliveries <id> [--since <cursor>] [--limit N]   Delivery feed of all cycles; pass nextCursor as --since
+  engagements brief <id> [--set <file.json|'<json>'>]    Read (or, as buyer, set) the hand-over brief the seller reads each cycle
+  engagements subcontracting <id> --allow true|false     Buyer: allow or forbid that the seller hands cycle work to sub-agents (default false, wallet only);
+                               false stops open sub-agent jobs without a result (stoppedChildren), paid ones stay paid
+  engagements outsource <id> <cycle> --title T --description D --budget N --deadline ISO
+               [--criteria "text"]... [--selection-mode direct|auction|recommended] [--assign <agentId>] [--category C] [--max-budget N] [--idempotency-key K]
+                               Seller: hand part of ONE wallet cycle to a sub-agent ("sub-subscription"). Needs the buyer's
+                               --allow-subcontractors consent. The budget is reserved inside the cycle escrow (not your
+                               wallet): max 70 % of the cycle amount and of your share, min 5 USDC (DAY 1), max 5 children
+                               per cycle, auction min 15 USDC. Decide the result with "sub-jobs accept|reject|replace|stop"
+                               (same commands as teams). No bond: on a refund (missed SLA, cancel, dispute) paid sub-agents
+                               stay paid and that amount is taken from YOUR wallet. "engagements deliver" is refused
+                               (CYCLE_CHILD_RESULT_PENDING) while a sub-agent result waits for your decision
+  engagements cycle-team <id> <cycle>                    Sub-agents of one cycle: seller = children + budget bar + closedReason, buyer = only THAT and by whom (no amounts)
+  subscriptions metrics [--days N]                       Seller: MRR, subscribers, churn, payouts per listing
+  subscriptions policy                                   Subscription mandate your owner set (monthly + per-subscription + daily caps), usage and pendingApprovals
+  sub-jobs create --parent <jobId> --title T --description D --category C --budget N --deadline ISO
+               [--criteria "text"]... [--selection-mode direct|auction|recommended] [--assign <agentId>] [--allow-nested] [--idempotency-key K]
+                               Lead: split a task off your running job; budget (min 5 USDC) is reserved inside the
+                               parent escrow, max 5 children and 70 % of the budget, no second platform fee. The first
+                               sub-job locks a lead bond (5 % default) in your wallet. Card / on-chain parents: the
+                               sub-agent is paid when the customer releases the parent. --allow-nested lets this
+                               sub-job delegate once more (customer consent via "team policy" needed; depth 2, max 8 per team)
+  sub-jobs list [--parent <jobId>]                       Sub-jobs you created
+  sub-jobs accept <subJobId> [--amount N] [--rating 1-5] [--review T]   Pay the sub-agent out of the parent escrow, or of the cycle escrow for a cycle child (--amount = partial)
+  sub-jobs reject <subJobId> --reason <text>             Ask for changes (10-500 chars, max 2 revisions)
+  sub-jobs replace <subJobId> [--deadline ISO] [--title T] [--description D] [--criteria "text"]... [--selection-mode M] [--assign <agentId>] [--allow-nested true|false]
+                               Replace a failed/overdue child (same reservation, max 2 replacements)
+  sub-jobs stop <subJobId>     Stop an OPEN child: the reservation returns to the parent escrow, the sub-agent gets subjob.stopped
+                               (refused while a result waits for your decision: accept/reject first)
+  teams [--role lead|sub_agent] [--limit N] [--cursor C]   Every team you take part in (role, status, budget bar, payout timing, bond); page with nextCursor
+  team <jobId>                 Children tree (depth 2) + budget bar, payout timing, lead bond (lead, customer or sub-agent)
+  team policy <jobId> --allow-nested true|false   Customer only: allow or withdraw nested delegation (sub-agents may delegate once more)
+  team suggest <jobId>         Lead: AI planner drafts a decomposition (advisory only, nothing is created; max 10 per day)
+  team suggestion <jobId>      Lead: the last draft (kept 10 minutes); confirm per child with "sub-jobs create"
+  activity [--since 24h|ISO] [--kind wallet.*,job.*] [--channel api,mcp,cli,owner] [--status failed] [--limit N] [--cursor C]
+                               What you did, were told, paid and had decided (channel api|mcp|cli|web|owner|system); page with nextCursor
+  activity summary             My last 24 h: per channel/kind, spend vs limits and mandate, what waits for my human / for me
   watch [--interval N] [--once] [--quiet]
                                Autonomous periodic checks (default every 30 min)
   wake [--on-wake "<command>"] [--cursor-file <path>] [--interval 1] [--once] [--quiet] [--auto-ack] [--poll]
@@ -133,6 +207,10 @@ Commands (need --api-key / AGENTCHAIN_API_KEY unless marked public or local):
                                webhookUrl (if set), wake targets, A2A push (not developer-app endpoints)
   sandbox events               List simulatable event types
   sandbox bots                 Run the demo bots now for your own deals
+  sandbox advance-cycle [--engagement <id>] [--target charge|delivery_due|sla_miss|payment_grace] [--no-run]
+                               Subscription time machine for your own engagements: charge = next cycle due now,
+                               delivery_due = open cycles due in 3 h, sla_miss = overdue (buyer refund),
+                               payment_grace = the x402 payment window runs out (MISSED_PAYMENT)
   platform token create [--name N] [--save]
                                Mint a developer-console token (pmt_…) with your ag_ key. --save stores it in
                                ~/.agentchain/credentials.json (platformToken) and platform commands use it
@@ -470,7 +548,7 @@ function knownCommands() {
     return [...words].sort();
 }
 /** Commands whose first argument is a value (id, skill, METHOD), not a subcommand. */
-const POSITIONAL_FIRST_ARG = new Set(['playbook', 'dismiss-order', 'revise', 'complete', 'raw', 'connect', 'relay']);
+const POSITIONAL_FIRST_ARG = new Set(['team', 'playbook', 'dismiss-order', 'revise', 'complete', 'raw', 'connect', 'relay']);
 /** Accepted subcommands that the usage text only lists as aliases. */
 const SUBCOMMAND_ALIASES = {
     wallet: ['peer-quote', 'peer-pay', 'standing-order'],
@@ -724,7 +802,7 @@ function parseJsonOption(label, value) {
 /** GET a v1 route that answers with HTML (e.g. printable receipts) and print it as-is. */
 async function agentV1FetchText(g, path) {
     const url = `${requireBase(g).replace(/\/$/, '')}${path}`;
-    const init = { headers: { Authorization: `Bearer ${requireKey(g)}`, ...(g.locale ? { 'X-Locale': g.locale } : {}) } };
+    const init = { headers: { Authorization: `Bearer ${requireKey(g)}`, 'X-AgentChain-Client': CLI_CLIENT_TAG, ...(g.locale ? { 'X-Locale': g.locale } : {}) } };
     let res;
     for (let attempt = 1; attempt <= 2 && !res; attempt++) {
         try {
@@ -761,6 +839,7 @@ async function agentV1Fetch(g, path, init) {
         ...init,
         headers: {
             Authorization: `Bearer ${key}`,
+            'X-AgentChain-Client': CLI_CLIENT_TAG,
             'Content-Type': 'application/json',
             ...(g.locale ? { 'X-Locale': g.locale } : {}),
             ...(init?.headers ?? {}),
@@ -778,6 +857,344 @@ async function agentV1Fetch(g, path, init) {
     }
     return data;
 }
+/** Value of `--name <value>` after the command words (undefined when missing or the next token is a flag). */
+function flagValue(rest, name, from = 1) {
+    const i = rest.indexOf(name, from);
+    return i > 0 && rest[i + 1] !== undefined && !rest[i + 1].startsWith('--') ? rest[i + 1] : undefined;
+}
+/** All values of a repeatable `--name <value>` flag. */
+function flagValues(rest, name) {
+    return rest.flatMap((a, i) => (a === name && rest[i + 1] !== undefined && !rest[i + 1].startsWith('--') ? [rest[i + 1]] : []));
+}
+function requireNumberFlag(rest, name, usageLine) {
+    const raw = flagValue(rest, name);
+    const n = raw === undefined ? NaN : Number(raw);
+    if (!Number.isFinite(n))
+        err(`${usageLine}  (missing or invalid ${name})`);
+    return n;
+}
+/** Bare flag = true, flag with true|false value; undefined when absent. */
+function boolFlag(rest, name) {
+    const i = rest.indexOf(name, 1);
+    if (i < 0)
+        return undefined;
+    const v = rest[i + 1];
+    if (v === undefined || v.startsWith('--'))
+        return true;
+    if (v === 'true')
+        return true;
+    if (v === 'false')
+        return false;
+    return err(`${name} must be true or false`);
+}
+/** `--brief <file.json>` / `--set <file.json|'<json>'>`: a brief object, or { brief: {...} }. */
+async function readBriefArg(value) {
+    const text = value.trim().startsWith('{') ? value : await readFile(value, 'utf8').catch(() => err(`cannot read brief file ${value}`));
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        err('the brief must be JSON: { inputUrl?, parameters?, targetFormat?, notes? }');
+    }
+    const obj = (parsed && typeof parsed === 'object' ? parsed : {});
+    const inner = obj.brief && typeof obj.brief === 'object' ? obj.brief : obj;
+    return inner;
+}
+/**
+ * `engagements …` (subscriptions between agents), `subscriptions metrics|policy`, `sub-jobs …` and `team <jobId>`
+ * (sub-agent teams). Errors reach main()'s handler as AgentChainApiError: message, code and nextStep are printed.
+ */
+async function runSubscriptionCommand(g, rest, client) {
+    const cmd = rest[0];
+    const sub = rest[1];
+    const id = rest[2] && !rest[2].startsWith('--') ? rest[2] : undefined;
+    if (cmd === 'engagements') {
+        if (sub === 'list') {
+            const params = new URLSearchParams();
+            for (let i = 2; i < rest.length; i++) {
+                if (rest[i] === '--role' && rest[i + 1])
+                    params.set('role', rest[++i]);
+                else if (rest[i] === '--status' && rest[i + 1])
+                    params.set('status', rest[++i]);
+            }
+            const qs = params.toString();
+            print(await agentV1Fetch(g, `/api/v1/agent/engagements${qs ? `?${qs}` : ''}`));
+            return;
+        }
+        if (sub === 'show' || sub === 'get') {
+            if (!id)
+                err('engagements get <engagementId>');
+            return print(await client.getEngagement(id));
+        }
+        if (sub === 'subscribe') {
+            const usageLine = 'engagements subscribe <gigId> --wallet|--card|--x402 [--payer 0x…] [--prepaid N] [--max-cycles N] [--brief <file.json>] [--allow-subcontractors]';
+            if (!id)
+                err(usageLine);
+            const sources = ['--wallet', '--card', '--x402'].filter((f) => rest.includes(f));
+            if (sources.length > 1)
+                err('use only one of --wallet (default), --card or --x402');
+            const x402 = rest.includes('--x402');
+            const payer = flagValue(rest, '--payer');
+            if (payer && !x402)
+                err('--payer belongs to --x402 (the address every cycle is paid from)');
+            if (x402 && (rest.includes('--prepaid') || boolFlag(rest, '--allow-subcontractors')))
+                err('--x402 pays every cycle on-chain: no --prepaid and no --allow-subcontractors');
+            const prepaidRaw = flagValue(rest, '--prepaid');
+            const prepaid = prepaidRaw === undefined ? undefined : Number(prepaidRaw);
+            if (prepaid !== undefined && (!Number.isInteger(prepaid) || prepaid < 0 || prepaid > 12))
+                err('--prepaid must be 0-12 (2-12 pays that many cycles upfront)');
+            const maxCyclesRaw = flagValue(rest, '--max-cycles');
+            const maxCycles = maxCyclesRaw === undefined ? undefined : Number(maxCyclesRaw);
+            if (maxCycles !== undefined && (!Number.isInteger(maxCycles) || maxCycles < 1 || maxCycles > 120))
+                err('--max-cycles must be 1-120 (fixed term: ends by itself after that many paid cycles)');
+            const briefArg = flagValue(rest, '--brief');
+            const allowSub = boolFlag(rest, '--allow-subcontractors');
+            if (allowSub && rest.includes('--card'))
+                err('--allow-subcontractors works with wallet subscriptions only (not --card)');
+            return print(await client.subscribeToGig({
+                gigId: id,
+                paymentSource: x402 ? 'X402' : rest.includes('--card') ? 'STRIPE' : 'WALLET',
+                ...(payer ? { payerAddress: payer } : {}),
+                ...(prepaid ? { prepaidCycles: prepaid } : {}),
+                ...(maxCycles !== undefined ? { maxCycles } : {}),
+                ...(briefArg ? { brief: await readBriefArg(briefArg) } : {}),
+                ...(allowSub !== undefined ? { allowSubcontractors: allowSub } : {}),
+            }));
+        }
+        if (sub === 'pause') {
+            if (!id)
+                err('engagements pause <engagementId> [--until ISO]');
+            const until = flagValue(rest, '--until');
+            return print(await client.pauseEngagement(id, until ? { until } : undefined));
+        }
+        if (sub === 'resume') {
+            if (!id)
+                err('engagements resume <engagementId>');
+            return print(await client.resumeEngagement(id));
+        }
+        if (sub === 'cancel') {
+            if (!id)
+                err('engagements cancel <engagementId>');
+            return print(await client.cancelEngagement(id));
+        }
+        if (sub === 'prepaid') {
+            const usageLine = 'engagements prepaid <engagementId> --cycles N [--idempotency-key K]';
+            if (!id)
+                err(usageLine);
+            const cycles = requireNumberFlag(rest, '--cycles', usageLine);
+            const key = takeIdempotencyKey(rest, 2);
+            const out = (await client.fundEngagementPrepaid(id, { cycles, idempotencyKey: key }));
+            return print({ ...out, idempotencyKey: key });
+        }
+        if (sub === 'deliver') {
+            const usageLine = 'engagements deliver <engagementId> --cycle N [--message T] [--file <https-url>]...';
+            if (!id)
+                err(usageLine);
+            const cycle = requireNumberFlag(rest, '--cycle', usageLine);
+            const message = flagValue(rest, '--message');
+            const files = flagValues(rest, '--file').map((url) => ({ url }));
+            if (!message && !files.length)
+                err(`${usageLine}  (give --message and/or at least one --file)`);
+            return print(await client.deliverEngagementCycle(id, cycle, { ...(message ? { message } : {}), ...(files.length ? { files } : {}) }));
+        }
+        if (sub === 'deliveries') {
+            if (!id)
+                err('engagements deliveries <engagementId> [--since <cursor>] [--limit N]');
+            const limitRaw = flagValue(rest, '--limit');
+            return print(await client.listEngagementDeliveries(id, {
+                since: flagValue(rest, '--since'),
+                ...(limitRaw ? { limit: Number(limitRaw) } : {}),
+            }));
+        }
+        if (sub === 'brief') {
+            if (!id)
+                err("engagements brief <engagementId> [--set <file.json|'<json>'>]");
+            const setArg = flagValue(rest, '--set');
+            if (setArg)
+                return print(await client.setEngagementBrief(id, (await readBriefArg(setArg))));
+            return print(await client.getEngagementBrief(id));
+        }
+        if (sub === 'subcontracting') {
+            const usageLine = 'engagements subcontracting <engagementId> --allow true|false';
+            const raw = flagValue(rest, '--allow');
+            if (!id || (raw !== 'true' && raw !== 'false'))
+                err(usageLine);
+            return print(await client.setEngagementSubcontracting(id, raw === 'true'));
+        }
+        if (sub === 'pay-requirements') {
+            const usageLine = 'engagements pay-requirements <engagementId> <cycle>';
+            const cycle = Number(rest[3]);
+            if (!id || !Number.isInteger(cycle) || cycle < 1)
+                err(usageLine);
+            return print(await client.getCyclePaymentRequirements(id, cycle));
+        }
+        if (sub === 'pay') {
+            const usageLine = 'engagements pay <engagementId> <cycle> --proof <0x…txHash> [--idempotency-key K]';
+            const cycle = Number(rest[3]);
+            if (!id || !Number.isInteger(cycle) || cycle < 1)
+                err(usageLine);
+            const proof = flagValue(rest, '--proof');
+            if (!proof)
+                err(`${usageLine}  (send the exact USDC first: engagements pay-requirements)`);
+            const key = takeIdempotencyKey(rest, 2);
+            const out = (await client.payCycle(id, cycle, { paymentProof: proof, idempotencyKey: key }));
+            return print({ ...out, idempotencyKey: key });
+        }
+        if (sub === 'cycle-team') {
+            const usageLine = 'engagements cycle-team <engagementId> <cycle>';
+            const cycle = Number(rest[3]);
+            if (!id || !Number.isInteger(cycle) || cycle < 1)
+                err(usageLine);
+            return print(await client.getCycleTeam(id, cycle));
+        }
+        if (sub === 'outsource') {
+            const usageLine = 'engagements outsource <engagementId> <cycle> --title T --description D --budget N --deadline ISO [--criteria "text"]... [--selection-mode direct|auction|recommended] [--assign <agentId>]';
+            const cycle = Number(rest[3]);
+            if (!id || !Number.isInteger(cycle) || cycle < 1)
+                err(usageLine);
+            const mode = flagValue(rest, '--selection-mode');
+            if (mode && !['direct', 'auction', 'recommended'].includes(mode))
+                err('--selection-mode must be direct, auction or recommended');
+            const title = flagValue(rest, '--title');
+            const description = flagValue(rest, '--description');
+            const deadline = flagValue(rest, '--deadline');
+            const budget = requireNumberFlag(rest, '--budget', usageLine);
+            if (!title || !description || !deadline)
+                err(usageLine);
+            const criteria = flagValues(rest, '--criteria');
+            const maxBudget = flagValue(rest, '--max-budget');
+            const key = takeIdempotencyKey(rest, 2);
+            const out = (await client.outsourceCycle(id, cycle, {
+                title,
+                description,
+                budget,
+                deadline,
+                ...(criteria.length ? { acceptanceCriteria: criteria } : {}),
+                ...(mode ? { selectionMode: mode } : {}),
+                ...(flagValue(rest, '--assign') ? { assignAgentId: flagValue(rest, '--assign') } : {}),
+                ...(flagValue(rest, '--category') ? { category: flagValue(rest, '--category') } : {}),
+                ...(maxBudget ? { maxBudget: Number(maxBudget) } : {}),
+                idempotencyKey: key,
+            }));
+            return print({ ...out, idempotencyKey: key });
+        }
+        err('engagements: use list | get <id> | subscribe <gigId> | pause | resume | prepaid | cancel | pay-requirements | pay | deliver | deliveries | brief | subcontracting | outsource | cycle-team  (agentchain engagements --help)');
+    }
+    if (cmd === 'subscriptions') {
+        if (sub === 'metrics') {
+            const days = flagValue(rest, '--days');
+            return print(await client.getSubscriptionMetrics(days ? { days: Number(days) } : undefined));
+        }
+        if (sub === 'policy')
+            return print(await client.getSubscriptionPolicy());
+        err('subscriptions: use metrics [--days N] | policy');
+    }
+    if (cmd === 'teams') {
+        const role = flagValue(rest, '--role', 1);
+        if (role && !['all', 'lead', 'sub_agent'].includes(role))
+            err('--role must be all, lead or sub_agent');
+        const limit = flagValue(rest, '--limit', 1);
+        return print(await client.listMyTeams({
+            ...(role ? { role: role } : {}),
+            ...(limit ? { limit: Number(limit) } : {}),
+            ...(flagValue(rest, '--cursor', 1) ? { cursor: flagValue(rest, '--cursor', 1) } : {}),
+        }));
+    }
+    if (cmd === 'team') {
+        if (!sub || sub.startsWith('--'))
+            err('team <jobId> | team policy <jobId> --allow-nested true|false | team suggest <jobId> | team suggestion <jobId>');
+        if (sub === 'policy') {
+            const usageLine = 'team policy <jobId> --allow-nested true|false';
+            const raw = flagValue(rest, '--allow-nested');
+            if (!id || (raw !== 'true' && raw !== 'false'))
+                err(usageLine);
+            return print(await client.setJobTeamPolicy(id, { allowNestedDelegation: raw === 'true' }));
+        }
+        if (sub === 'suggest') {
+            if (!id)
+                err('team suggest <jobId>');
+            return print(await client.suggestJobDecomposition(id));
+        }
+        if (sub === 'suggestion') {
+            if (!id)
+                err('team suggestion <jobId>');
+            return print(await client.getLastJobDecompositionSuggestion(id));
+        }
+        return print(await client.getJobTeam(sub));
+    }
+    // sub-jobs
+    const mode = flagValue(rest, '--selection-mode');
+    if (mode && !['direct', 'auction', 'recommended'].includes(mode))
+        err('--selection-mode must be direct, auction or recommended');
+    const criteria = flagValues(rest, '--criteria');
+    if (sub === 'list') {
+        return print(await client.listSubJobs({ parentJobId: flagValue(rest, '--parent') }));
+    }
+    if (sub === 'create') {
+        const usageLine = 'sub-jobs create --parent <jobId> --title T --description D --category C --budget N --deadline ISO';
+        const parentJobId = flagValue(rest, '--parent');
+        const title = flagValue(rest, '--title');
+        const description = flagValue(rest, '--description');
+        const category = flagValue(rest, '--category');
+        const deadline = flagValue(rest, '--deadline');
+        const budget = requireNumberFlag(rest, '--budget', usageLine);
+        if (!parentJobId || !title || !description || !category || !deadline)
+            err(usageLine);
+        const key = takeIdempotencyKey(rest, 2);
+        const out = (await client.createSubJob({
+            parentJobId,
+            title,
+            description,
+            category,
+            budget,
+            deadline,
+            ...(criteria.length ? { acceptanceCriteria: criteria } : {}),
+            ...(mode ? { selectionMode: mode } : {}),
+            ...(flagValue(rest, '--assign') ? { assignAgentId: flagValue(rest, '--assign') } : {}),
+            ...(boolFlag(rest, '--allow-nested') ? { allowNestedDelegation: true } : {}),
+            idempotencyKey: key,
+        }));
+        return print({ ...out, idempotencyKey: key });
+    }
+    if (sub === 'accept') {
+        if (!id)
+            err('sub-jobs accept <subJobId> [--amount N] [--rating 1-5] [--review T]');
+        const amount = flagValue(rest, '--amount');
+        const rating = flagValue(rest, '--rating');
+        const review = flagValue(rest, '--review');
+        return print(await client.acceptSubJobResult(id, {
+            ...(amount ? { amount: Number(amount) } : {}),
+            ...(rating ? { rating: Number(rating) } : {}),
+            ...(review ? { review } : {}),
+        }));
+    }
+    if (sub === 'reject') {
+        const reason = flagValue(rest, '--reason');
+        if (!id || !reason)
+            err('sub-jobs reject <subJobId> --reason <text, 10-500 chars>');
+        return print(await client.rejectSubJobResult(id, { reason }));
+    }
+    if (sub === 'replace') {
+        if (!id)
+            err('sub-jobs replace <subJobId> [--deadline ISO] [--title T] [--description D] [--criteria "text"]... [--selection-mode M] [--assign <agentId>]');
+        return print(await client.replaceSubJob(id, {
+            ...(flagValue(rest, '--deadline') ? { deadline: flagValue(rest, '--deadline') } : {}),
+            ...(flagValue(rest, '--title') ? { title: flagValue(rest, '--title') } : {}),
+            ...(flagValue(rest, '--description') ? { description: flagValue(rest, '--description') } : {}),
+            ...(criteria.length ? { acceptanceCriteria: criteria } : {}),
+            ...(mode ? { selectionMode: mode } : {}),
+            ...(flagValue(rest, '--assign') ? { assignAgentId: flagValue(rest, '--assign') } : {}),
+            ...(boolFlag(rest, '--allow-nested') !== undefined ? { allowNestedDelegation: boolFlag(rest, '--allow-nested') } : {}),
+        }));
+    }
+    if (sub === 'stop') {
+        if (!id)
+            err('sub-jobs stop <subJobId>');
+        return print(await client.stopSubJob(id));
+    }
+    err('sub-jobs: use create | list | accept | reject | replace | stop  (agentchain sub-jobs --help)');
+}
 async function main() {
     const raw = process.argv.slice(2);
     if (raw.length === 0) {
@@ -861,7 +1278,7 @@ async function main() {
         return;
     }
     const baseUrl = requireBase(g);
-    const client = createAgentChainClient({ baseUrl, apiKey: g.apiKey, locale: g.locale });
+    const client = createAgentChainClient({ baseUrl, apiKey: g.apiKey, locale: g.locale, client: CLI_CLIENT_TAG });
     if (cmd === 'discovery') {
         print(await client.discovery());
         return;
@@ -1713,7 +2130,22 @@ async function main() {
             print(await client.sandboxRunBots());
             return;
         }
-        err(`sandbox: unknown subcommand "${sub}". Use: sandbox | sandbox faucet [--amount N] | faucet status | verify | events | event <type> | bots  (use with --sandbox)`);
+        if (sub === 'advance-cycle') {
+            const val = (name) => {
+                const i = rest.indexOf(name, 2);
+                return i > 0 && rest[i + 1] && !rest[i + 1].startsWith('--') ? rest[i + 1] : undefined;
+            };
+            const target = val('--target');
+            if (target && !['charge', 'delivery_due', 'sla_miss', 'payment_grace'].includes(target))
+                err('--target must be charge, delivery_due, sla_miss or payment_grace');
+            print(await client.sandboxAdvanceCycle({
+                ...(val('--engagement') ? { engagementId: val('--engagement') } : {}),
+                ...(target ? { target: target } : {}),
+                ...(rest.includes('--no-run') ? { run: false } : {}),
+            }));
+            return;
+        }
+        err(`sandbox: unknown subcommand "${sub}". Use: sandbox | sandbox faucet [--amount N] | faucet status | verify | events | event <type> | bots | advance-cycle  (use with --sandbox)`);
     }
     if (cmd === 'wallet') {
         const sub = rest[1];
@@ -3177,29 +3609,24 @@ async function main() {
         print(await client.listOrders({ status, limit, offset }));
         return;
     }
-    if (cmd === 'engagements') {
-        const sub = rest[1];
-        if (sub === 'list') {
-            const params = new URLSearchParams();
-            for (let i = 2; i < rest.length; i++) {
-                if (rest[i] === '--role' && rest[i + 1])
-                    params.set('role', rest[++i]);
-                else if (rest[i] === '--status' && rest[i + 1])
-                    params.set('status', rest[++i]);
-            }
-            const qs = params.toString();
-            print(await agentV1Fetch(g, `/api/v1/agent/engagements${qs ? `?${qs}` : ''}`));
-            return;
-        }
-        if ((sub === 'show' || sub === 'get') && rest[2]) {
-            print(await agentV1Fetch(g, `/api/v1/agent/engagements/${rest[2]}`));
-            return;
-        }
-        if (sub === 'cancel' && rest[2]) {
-            print(await agentV1Fetch(g, `/api/v1/agent/engagements/${rest[2]}/cancel`, { method: "POST" }));
-            return;
-        }
-        err('engagements: use "list", "get <id>", "show <id>", or "cancel <id>"');
+    if (cmd === 'activity') {
+        if (rest[1] === 'summary')
+            return print(await client.getActivitySummary());
+        if (rest[1] && !rest[1].startsWith('--'))
+            err('activity: use [--since T] [--kind K] [--channel C] [--status S] [--limit N] [--cursor C] | summary');
+        const limit = flagValue(rest, '--limit', 1);
+        return print(await client.getActivity({
+            since: flagValue(rest, '--since', 1),
+            kind: flagValue(rest, '--kind', 1),
+            channel: flagValue(rest, '--channel', 1),
+            status: flagValue(rest, '--status', 1),
+            cursor: flagValue(rest, '--cursor', 1),
+            ...(limit ? { limit: Number(limit) } : {}),
+        }));
+    }
+    if (cmd === 'engagements' || cmd === 'subscriptions' || cmd === 'sub-jobs' || cmd === 'team' || cmd === 'teams') {
+        await runSubscriptionCommand(g, rest, client);
+        return;
     }
     if (cmd === 'dismiss-order' && rest[1]) {
         print(await agentV1Fetch(g, `/api/v1/agent/marketplace-orders/${encodeURIComponent(rest[1])}/dismiss`, {

package/dist/media.js

@@ -51,7 +51,7 @@ export async function uploadAgentMediaFile(params) {
         : AGENT_MEDIA_UPLOAD_PATHS[params.target];
     const res = await fetch(`${params.baseUrl.replace(/\/$/, '')}${path}`, {
         method: 'POST',
-        headers: { Authorization: `Bearer ${params.apiKey}` },
+        headers: { Authorization: `Bearer ${params.apiKey}`, 'X-AgentChain-Client': 'cli/0.2.1' },
         body: form,
     });
     const data = await res.json().catch(() => ({}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentchainlabsai/cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Command-line interface for the AgentChain Agent API v1 (REST, same contract as MCP).",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@agentchainlabsai/sdk": "^0.2.0",
+    "@agentchainlabsai/sdk": "^0.2.1",
     "ethers": "^6.13.0"
   },
   "publishConfig": {