@slothmoney/agent-cli 0.21.1 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.22.0 - 2026-08-29
+
+- Add read-only `partner status` output for the current settlement balance and
+  paginated recorded partner payments.
+- Add opt-in `transactions --include-pending` output from the latest complete
+  observation in the command's normal refresh flow, with explicit availability
+  and non-writable pending rows.
+- Strictly validate both new response contracts and cover their nested help in
+  packed-binary and release-preflight checks.
+- Accept the existing completed-refresh `checkpointId` while continuing to
+  reject it from non-completed refresh states.
+
 ## 0.21.1 - 2026-08-29
 
 - Clarify in portfolio, current budget status, and transaction help that a

package/README.md

@@ -1,6 +1,6 @@
 # Sloth Agent CLI
 
-Use your own agent to inspect personal and household accounts, investments, and budgets, manage goals and forecast scenarios, move assigned budget money, update planned amounts, categorise transactions, and configure payment notifications through the
+Use your own agent to inspect personal and household accounts, investments, budgets, pending card activity, and partner settlement context; manage goals and forecast scenarios; move assigned budget money; update planned amounts; categorise booked transactions; and configure payment notifications through the
 [Sloth Money Agent API](https://slothmoney.app/developers/).
 
 ## Install
@@ -15,7 +15,7 @@ sloth-agent --version
 For a one-off pinned run:
 
 ```bash
-npm exec --yes --package=@slothmoney/agent-cli@0.21.1 -- sloth-agent --help
+npm exec --yes --package=@slothmoney/agent-cli@0.22.0 -- sloth-agent --help
 ```
 
 ## Authenticate
@@ -25,7 +25,7 @@ Create a personal access token in Sloth Money under
 where the CLI runs.
 
 New tokens are view-only. That is enough for `auth status`, `accounts`, `investments`, `portfolio`,
-`budget`, `categories`, `transactions`, `goals`, and `scenarios` list. Enable **Allow changes** when
+`budget`, `categories`, `transactions`, `partner status`, `goals`, and `scenarios` list. Enable **Allow changes** when
 creating the token only if the CLI must apply assignments, manage categories
 or line items, move assigned budget money, update planned budgets, manage accounts, ask a partner for an explanation, or manage goals and scenarios. Token
 permissions cannot be changed later - revoke and reissue the token instead.
@@ -113,6 +113,8 @@ sloth-agent categories create --help
 sloth-agent line-items --help
 sloth-agent line-items create --help
 sloth-agent transactions --help
+sloth-agent partner --help
+sloth-agent partner status --help
 sloth-agent rules --help
 sloth-agent assign --help
 sloth-agent receipts --help
@@ -810,6 +812,23 @@ Read uncategorised contributions to the joint budget:
 sloth-agent transactions --assignment-scope joint --uncategorized
 ```
 
+Include the current pending snapshot while reviewing transactions:
+
+```bash
+sloth-agent transactions --include-pending
+```
+
+This option reuses the transaction command's normal linked-bank refresh. It
+does not force a second refresh. Sloth Money keeps the latest complete pending
+observation until the next fully successful refresh, including an empty result.
+Booked rows remain in `transactions`; pending
+rows appear in `pending.transactions` with `writable: false` and
+`writeBlockReason: "pending"`, so they cannot be passed to `assign`. A current
+empty list means the latest complete observation had no matching pending rows.
+`unavailable` means no valid complete snapshot is available and must not be interpreted as
+proof that there are no pending payments. Date, text, and account filters apply
+to pending rows; categorisation and pagination filters remain booked-only.
+
 The first transaction read after the UTC day changes may refresh linked bank
 data. The CLI waits up to 45 seconds for that refresh to persist, then returns
 the requested booked transactions. If the refresh is still running, partially
@@ -833,6 +852,18 @@ add another audit checkpoint.
 Re-run the transaction query later to observe the completed refresh. A partial
 account failure remains eligible for an automatic retry.
 
+Read partner settlement context when an incoming payment may be a recorded
+partner payment:
+
+```bash
+sloth-agent partner status
+```
+
+The read-only response reports whether a mutual partner is connected, the
+current settlement direction and amount in pence, and recent sent or received
+payments. It uses opaque payment references and paginates with `nextCursor`.
+The command does not refresh bank accounts or change partner records.
+
 Set `"assignmentScope": "joint"` on an assignment to categorise the eligible
 shared portion for the joint budget.
 

package/dist/args.js

@@ -241,6 +241,10 @@ function parseTransactions(args) {
     const filters = {};
     for (let index = 0; index < args.length; index += 1) {
         const argument = args[index];
+        if (argument === '--include-pending') {
+            filters.includePending = setOnce(filters.includePending, true, '--include-pending');
+            continue;
+        }
         if (argument === '--uncategorized') {
             filters.uncategorized = setOnce(filters.uncategorized, true, '--uncategorized');
             continue;
@@ -332,6 +336,41 @@ function parseTransactions(args) {
     }
     return filters;
 }
+function parsePartner(args, baseUrl) {
+    const subcommand = args.shift();
+    if (subcommand !== 'status') {
+        throw new UsageError('partner requires the status subcommand');
+    }
+    let limit;
+    let cursor;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        const [name, inlineValue] = argument.includes('=')
+            ? argument.split(/=(.*)/s, 2)
+            : [argument, undefined];
+        if (name !== '--limit' && name !== '--cursor') {
+            throw new UsageError(`Unknown partner status option: ${argument}`);
+        }
+        const value = requireNonEmpty(inlineValue ?? readOptionValue(args, index, name), name);
+        if (inlineValue === undefined)
+            index += 1;
+        if (name === '--limit') {
+            const parsedLimit = Number(value);
+            if (!Number.isInteger(parsedLimit) || parsedLimit < 1 || parsedLimit > 200) {
+                throw new UsageError('--limit must be an integer between 1 and 200');
+            }
+            limit = setOnce(limit, parsedLimit, '--limit');
+        }
+        else {
+            cursor = setOnce(cursor, value, '--cursor');
+        }
+    }
+    return withBaseUrl({
+        command: 'partner-status',
+        ...(limit === undefined ? {} : { limit }),
+        ...(cursor === undefined ? {} : { cursor }),
+    }, baseUrl);
+}
 function parseNamedOptions(args, commandLabel, allowed) {
     const values = new Map();
     let apply = false;
@@ -1233,6 +1272,11 @@ function helpTopic(argv) {
             return 'receipts-remove';
         return 'receipts';
     }
+    if (command === 'partner') {
+        if (subcommand === 'status')
+            return 'partner-status';
+        return 'partner';
+    }
     if (command === 'accounts'
         || command === 'transactions'
         || command === 'assign'
@@ -1294,6 +1338,9 @@ export function parseArgs(argv) {
     if (command === 'transactions') {
         return withBaseUrl({ command, filters: parseTransactions(args) }, baseUrl);
     }
+    if (command === 'partner') {
+        return parsePartner(args, baseUrl);
+    }
     if (command === 'assign') {
         let input;
         let apply = false;

package/dist/cli.js

@@ -6,7 +6,7 @@ import { ICON_KEYS } from './category-metadata.js';
 import { parseApiResponse, parseAssignmentOperationResponse, toLegacyAssignmentResponse, validateAssignmentPayload, validateBudgetMovementResponse, validateBudgetUpdatePayload, validateNotificationRulePayload, validateReceiptConfirmation, } from './contracts.js';
 import { createSystemCredentialStore, secureStorageUnavailableError, } from './credential-store.js';
 import { ApiError, CliError, ConfigError, UsageError, } from './errors.js';
-export const CLI_VERSION = '0.21.1';
+export const CLI_VERSION = '0.22.0';
 const REQUEST_TIMEOUT_MS = 60_000;
 const MAX_CONTRACT_PDF_BYTES = 6_000_000;
 const API_ORIGIN_HELP_LINES = [
@@ -49,7 +49,8 @@ export function usageText() {
         '  sloth-agent transactions [--uncategorized[=true|false]] [--shared[=true|false]] [--limit N]',
         '    [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--q TEXT]',
         '    [--account-ref REF] [--category-id ID] [--line-item-id ID]',
-        '    [--cursor CURSOR] [--base-url URL]',
+        '    [--cursor CURSOR] [--include-pending] [--base-url URL]',
+        '  sloth-agent partner status [--limit N] [--cursor CURSOR] [--base-url URL]',
         '  sloth-agent assign --input assignments.json [--apply] [--base-url URL]',
         '  sloth-agent rules [list] [--base-url URL]',
         '  sloth-agent rules get --transaction-ref REF [--base-url URL]',
@@ -649,6 +650,8 @@ export function transactionsHelpText() {
         '  --assignment-scope SCOPE        Optional. Filter assignments by personal or joint.',
         '                                  The transaction\'s native scope is used when omitted.',
         '  --cursor CURSOR                Optional. Continue from a previous nextCursor.',
+        '  --include-pending               Optional. Include the latest complete pending observation',
+        '                                  from the normal linked-bank refresh flow.',
         '  --base-url URL                 Optional. Override the API origin.',
         '  -h, --help                     Show this help.',
         ...API_ORIGIN_HELP_LINES,
@@ -661,9 +664,17 @@ export function transactionsHelpText() {
         '  A completed refresh updates the Budget balance audit for configured backing accounts.',
         '  A same-day cached read does not add another audit checkpoint.',
         '  The command waits up to 45 seconds, then returns cached data if refresh continues.',
+        '  --include-pending does not force an extra refresh or make pending rows writable.',
+        '  Date, text, and account filters apply to pending rows. Assignment, sharing, category,',
+        '  line-item, limit, and cursor filters apply only to booked transactions.',
         '',
         'Output:',
         '  JSON containing transactions, nextCursor, and structured refresh status.',
+        '  With --include-pending, pending reports availability current or unavailable.',
+        '  A current empty list means the latest complete observation had no matching pending rows.',
+        '  Unavailable means no pending snapshot was returned; it does not mean there are none.',
+        '  Pending rows have opaque pendingRef and accountRef values plus writable: false and',
+        '  writeBlockReason: "pending". They cannot be passed to assign or other write commands.',
         '  Every transaction includes accountRef for its originating account.',
         '  Refresh failures do not hide readable cached transactions.',
         '  Personal assignments use the top-level categoryId, lineItemId, and categorySplits.',
@@ -676,9 +687,57 @@ export function transactionsHelpText() {
         'Examples:',
         '  sloth-agent transactions --uncategorized --limit 50',
         '  sloth-agent transactions --assignment-scope joint --uncategorized',
+        '  sloth-agent transactions --include-pending --start-date 2026-08-27',
         '  sloth-agent transactions --q "tesco" --start-date 2026-05-01 --end-date 2026-05-31',
     ].join('\n');
 }
+export function partnerHelpText() {
+    return [
+        'Sloth Agent CLI — partner',
+        '',
+        'Read partner settlement context and recorded partner payments.',
+        '',
+        'Commands:',
+        '  sloth-agent partner status   Read the current settlement balance and payment activity',
+        '',
+        'Help:',
+        '  Run sloth-agent partner status --help for inputs, output, and examples.',
+        ...API_ORIGIN_HELP_LINES,
+    ].join('\n');
+}
+export function partnerStatusHelpText() {
+    return [
+        'Sloth Agent CLI — partner status',
+        '',
+        'Read the current partner settlement balance and recorded partner payments.',
+        '',
+        'Usage:',
+        '  sloth-agent partner status [--limit N] [--cursor CURSOR] [--base-url URL]',
+        '',
+        'Options:',
+        '  --limit N        Optional. Return 1 to 200 payment records; defaults to 50.',
+        '  --cursor CURSOR  Optional. Continue payment activity from a previous nextCursor.',
+        '  --base-url URL   Optional. Override the API origin.',
+        '  -h, --help       Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Read behavior:',
+        '  Requires agent:read. This command does not refresh bank accounts or change Sloth Money.',
+        '  It calculates settlement from shared booked transactions and recorded partner payments.',
+        '',
+        'Output:',
+        '  JSON containing asOf, partnerStatus, settlement, payments, and nextCursor.',
+        '  settlement is null when no partner is connected. Otherwise balance.direction is',
+        '  settled when amountPence is 0. The you_owe and partner_owes_you directions have',
+        '  a positive amountPence.',
+        '  Each payment has an opaque paymentRef, sent or received direction, amountPence,',
+        '  currency, and occurredAt. A null nextCursor means there are no more payments.',
+        '',
+        'Examples:',
+        '  sloth-agent partner status',
+        '  sloth-agent partner status --limit 100',
+    ].join('\n');
+}
 export function assignHelpText() {
     return [
         'Sloth Agent CLI — assign',
@@ -1414,6 +1473,8 @@ export function commandHelpText(topic) {
         'line-items-create': lineItemsCreateHelpText,
         'line-items-rename': lineItemsRenameHelpText,
         transactions: transactionsHelpText,
+        partner: partnerHelpText,
+        'partner-status': partnerStatusHelpText,
         assign: assignHelpText,
         rules: rulesHelpText,
         'rules-get': rulesGetHelpText,
@@ -1583,6 +1644,9 @@ function buildTransactionsQuery(filters) {
     if (filters.uncategorized !== undefined) {
         params.set('uncategorized', String(filters.uncategorized));
     }
+    if (filters.includePending !== undefined) {
+        params.set('includePending', String(filters.includePending));
+    }
     if (filters.shared !== undefined)
         params.set('shared', String(filters.shared));
     if (filters.limit !== undefined)
@@ -2393,6 +2457,22 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             writeJson(writeStdout, data);
             return 0;
         }
+        if (parsed.command === 'partner-status') {
+            const query = new URLSearchParams();
+            if (parsed.limit !== undefined)
+                query.set('limit', String(parsed.limit));
+            if (parsed.cursor !== undefined)
+                query.set('cursor', parsed.cursor);
+            const suffix = query.size > 0 ? `?${query.toString()}` : '';
+            const response = await fetchImplementation(`${baseUrl}/api/agent/v1/partner-status${suffix}`, {
+                method: 'GET',
+                headers,
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const data = parseApiResponse('partner-status', await parseHttpResponse(response, token));
+            writeJson(writeStdout, data);
+            return 0;
+        }
         const path = parsed.command === 'accounts'
             ? '/api/agent/v1/accounts'
             : parsed.command === 'portfolio'

package/dist/contracts.js

@@ -436,20 +436,101 @@ const REFRESH_REASONS = new Set([
     'refresh_error',
 ]);
 function isRefreshStatus(value) {
-    return (isObject(value)
-        && hasOnlyFields(value, ['status', 'reason', 'utcDate'])
-        && typeof value.status === 'string'
-        && REFRESH_STATUSES.has(value.status)
-        && typeof value.reason === 'string'
-        && REFRESH_REASONS.has(value.reason)
-        && isIsoDate(value.utcDate));
+    if (!isObject(value)
+        || typeof value.status !== 'string'
+        || !REFRESH_STATUSES.has(value.status)
+        || typeof value.reason !== 'string'
+        || !REFRESH_REASONS.has(value.reason)
+        || !isIsoDate(value.utcDate))
+        return false;
+    return value.status === 'completed'
+        ? hasOnlyFields(value, ['status', 'reason', 'utcDate', 'checkpointId'])
+            && typeof value.checkpointId === 'string'
+            && value.checkpointId.length > 0
+        : hasOnlyFields(value, ['status', 'reason', 'utcDate']);
 }
 function isTransactionsResponse(value) {
+    const isPendingTransaction = (transaction) => (isObject(transaction)
+        && hasOnlyFields(transaction, [
+            'pendingRef', 'name', 'amount', 'currency', 'date', 'status',
+            'accountRef', 'scope', 'writable', 'writeBlockReason',
+        ])
+        && typeof transaction.pendingRef === 'string'
+        && /^sloth_pending_v1_[A-Za-z0-9_-]{43}$/.test(transaction.pendingRef)
+        && typeof transaction.name === 'string'
+        && typeof transaction.amount === 'number'
+        && Number.isFinite(transaction.amount)
+        && isCurrency(transaction.currency)
+        && isIsoDate(transaction.date)
+        && transaction.status === 'pending'
+        && isAccountRef(transaction.accountRef)
+        && (transaction.scope === 'personal' || transaction.scope === 'joint')
+        && transaction.writable === false
+        && transaction.writeBlockReason === 'pending');
+    const isPendingSnapshot = (snapshot) => {
+        if (!isObject(snapshot))
+            return false;
+        if (snapshot.availability === 'current') {
+            return hasOnlyFields(snapshot, ['availability', 'observedAt', 'transactions', 'truncated'])
+                && isIsoDateTime(snapshot.observedAt)
+                && Array.isArray(snapshot.transactions)
+                && snapshot.transactions.length <= 200
+                && snapshot.transactions.every(isPendingTransaction)
+                && typeof snapshot.truncated === 'boolean';
+        }
+        return snapshot.availability === 'unavailable'
+            && hasOnlyFields(snapshot, ['availability', 'observedAt', 'transactions', 'truncated'])
+            && snapshot.observedAt === null
+            && Array.isArray(snapshot.transactions)
+            && snapshot.transactions.length === 0
+            && snapshot.truncated === false;
+    };
     return (isObject(value)
+        && hasOnlyFields(value, ['transactions', 'nextCursor', 'refresh', 'pending'])
         && Array.isArray(value.transactions)
         && value.transactions.every(isTransaction)
         && (value.nextCursor === null || typeof value.nextCursor === 'string')
-        && isRefreshStatus(value.refresh));
+        && isRefreshStatus(value.refresh)
+        && (value.pending === undefined || isPendingSnapshot(value.pending)));
+}
+function isPartnerStatusResponse(value) {
+    if (!isObject(value)
+        || !hasOnlyFields(value, ['asOf', 'partnerStatus', 'settlement', 'payments', 'nextCursor'])
+        || !isIsoDateTime(value.asOf)
+        || (value.partnerStatus !== 'connected' && value.partnerStatus !== 'not_connected')
+        || (value.nextCursor !== null && typeof value.nextCursor !== 'string')
+        || !Array.isArray(value.payments)
+        || value.payments.length > 200)
+        return false;
+    const settlementIsValid = isObject(value.settlement)
+        && hasOnlyFields(value.settlement, ['currency', 'balance'])
+        && isCurrency(value.settlement.currency)
+        && isObject(value.settlement.balance)
+        && hasOnlyFields(value.settlement.balance, ['direction', 'amountPence'])
+        && (value.settlement.balance.direction === 'you_owe'
+            || value.settlement.balance.direction === 'partner_owes_you'
+            || value.settlement.balance.direction === 'settled')
+        && isNonnegativeSafeInteger(value.settlement.balance.amountPence)
+        && ((value.settlement.balance.direction === 'settled'
+            && value.settlement.balance.amountPence === 0)
+            || (value.settlement.balance.direction !== 'settled'
+                && value.settlement.balance.amountPence > 0));
+    if ((value.partnerStatus === 'connected' && !settlementIsValid)
+        || (value.partnerStatus === 'not_connected' && value.settlement !== null)
+        || (value.partnerStatus === 'not_connected' && value.payments.length > 0)
+        || (value.partnerStatus === 'not_connected' && value.nextCursor !== null))
+        return false;
+    return value.payments.every((payment) => (isObject(payment)
+        && hasOnlyFields(payment, [
+            'paymentRef', 'direction', 'amountPence', 'currency', 'occurredAt',
+        ])
+        && typeof payment.paymentRef === 'string'
+        && /^sloth_partner_payment_v1_[A-Za-z0-9_-]{43}$/.test(payment.paymentRef)
+        && (payment.direction === 'sent' || payment.direction === 'received')
+        && isNonnegativeSafeInteger(payment.amountPence)
+        && payment.amountPence > 0
+        && isCurrency(payment.currency)
+        && (payment.occurredAt === null || isIsoDateTime(payment.occurredAt))));
 }
 function isAssignmentResponse(value) {
     const isResponseSplit = (split) => (isObject(split)
@@ -1223,37 +1304,39 @@ export function parseApiResponse(command, value) {
                                                 ? isLineItemMutationResponse(value)
                                                 : command === 'transactions'
                                                     ? isTransactionsResponse(value)
-                                                    : command === 'rules-list'
-                                                        ? isNotificationRuleListResponse(value)
-                                                        : command === 'rules-get' || command === 'rules-set'
-                                                            ? isNotificationRuleResponse(value)
-                                                            : command === 'rules-delete'
-                                                                ? isNotificationRuleDeleteResponse(value)
-                                                                : command === 'rules-scan-contract'
-                                                                    ? isRenewalExtractionResponse(value)
-                                                                    : command === 'receipts-extract'
-                                                                        ? isReceiptExtractResponse(value)
-                                                                        : command === 'receipts-get'
-                                                                            ? isReceiptLookupResponse(value)
-                                                                            : command === 'receipts-attach'
-                                                                                ? isReceiptMutationResponse(value)
-                                                                                : command === 'receipts-remove'
-                                                                                    ? isReceiptDeleteResponse(value)
-                                                                                    : command === 'assign'
-                                                                                        ? isAssignmentResponse(value)
-                                                                                        : command === 'ask-partner'
-                                                                                            ? isPartnerResponse(value)
-                                                                                            : command === 'goals-list'
-                                                                                                ? isGoalsResponse(value)
-                                                                                                : command === 'scenarios-list'
-                                                                                                    ? isScenariosResponse(value)
-                                                                                                    : command === 'scenarios-mutation'
-                                                                                                        ? isScenarioMutationResponse(value)
-                                                                                                        : command === 'goals-preview'
-                                                                                                            ? isGoalPreviewResponse(value)
-                                                                                                            : command === 'goals-delete'
-                                                                                                                ? isGoalDeleteResponse(value)
-                                                                                                                : isGoalMutationResponse(value);
+                                                    : command === 'partner-status'
+                                                        ? isPartnerStatusResponse(value)
+                                                        : command === 'rules-list'
+                                                            ? isNotificationRuleListResponse(value)
+                                                            : command === 'rules-get' || command === 'rules-set'
+                                                                ? isNotificationRuleResponse(value)
+                                                                : command === 'rules-delete'
+                                                                    ? isNotificationRuleDeleteResponse(value)
+                                                                    : command === 'rules-scan-contract'
+                                                                        ? isRenewalExtractionResponse(value)
+                                                                        : command === 'receipts-extract'
+                                                                            ? isReceiptExtractResponse(value)
+                                                                            : command === 'receipts-get'
+                                                                                ? isReceiptLookupResponse(value)
+                                                                                : command === 'receipts-attach'
+                                                                                    ? isReceiptMutationResponse(value)
+                                                                                    : command === 'receipts-remove'
+                                                                                        ? isReceiptDeleteResponse(value)
+                                                                                        : command === 'assign'
+                                                                                            ? isAssignmentResponse(value)
+                                                                                            : command === 'ask-partner'
+                                                                                                ? isPartnerResponse(value)
+                                                                                                : command === 'goals-list'
+                                                                                                    ? isGoalsResponse(value)
+                                                                                                    : command === 'scenarios-list'
+                                                                                                        ? isScenariosResponse(value)
+                                                                                                        : command === 'scenarios-mutation'
+                                                                                                            ? isScenarioMutationResponse(value)
+                                                                                                            : command === 'goals-preview'
+                                                                                                                ? isGoalPreviewResponse(value)
+                                                                                                                : command === 'goals-delete'
+                                                                                                                    ? isGoalDeleteResponse(value)
+                                                                                                                    : isGoalMutationResponse(value);
     if (!valid) {
         const label = command === 'assign' ? 'assignment' : command;
         throw new ApiError(`Invalid ${label} response from the Agent API`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slothmoney/agent-cli",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "Command-line access to the Sloth Money Agent API.",
   "type": "module",
   "bin": {