@slothmoney/agent-cli 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.12.0 - 2026-08-16
+
+- Add read-only `budget status` for current-period assigned, spent, and
+  available category amounts, including refresh and unallocated-activity
+  signals for safer automated budget review.
+
+## 0.11.0 - 2026-08-16
+
+- Add preview-by-default `budget move` for atomically moving current assigned
+  money between categories or To Assign without changing planned budgets.
+- Accept human-readable currency amounts at the CLI boundary, send integer
+  pence to the Agent API, and validate the returned affected balances.
+
 ## 0.10.0 - 2026-08-15
 
 - Require every goal create to specify a positive target amount and Keep or

package/README.md

@@ -1,6 +1,6 @@
 # Sloth Agent CLI
 
-Use your own agent to inspect accounts, investments, and budgets, manage goals, update planned amounts, and categorise transactions through the
+Use your own agent to inspect accounts, investments, and budgets, manage goals, move assigned budget money, update planned amounts, and categorise transactions 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.10.0 -- sloth-agent --help
+npm exec --yes --package=@slothmoney/agent-cli@0.12.0 -- sloth-agent --help
 ```
 
 ## Authenticate
@@ -27,7 +27,7 @@ where the CLI runs.
 New tokens are view-only. That is enough for `auth status`, `accounts`, `investments`,
 `budget`, `categories`, `transactions`, and `goals` list. Enable **Allow changes** when
 creating the token only if the CLI must apply assignments, manage categories
-or line items, update planned budgets, manage accounts, ask a partner for an explanation, or manage goals. Token
+or line items, move assigned budget money, update planned budgets, manage accounts, ask a partner for an explanation, or manage goals. Token
 permissions cannot be changed later - revoke and reissue the token instead.
 
 ### Local computer
@@ -104,7 +104,9 @@ options, output, and examples:
 sloth-agent auth login --help
 sloth-agent accounts --help
 sloth-agent budget --help
+sloth-agent budget status --help
 sloth-agent budget update --help
+sloth-agent budget move --help
 sloth-agent categories --help
 sloth-agent categories create --help
 sloth-agent line-items create --help
@@ -248,6 +250,21 @@ The result includes the budget period and status, currency, the effective plan,
 stored funding amounts when available, categories, line items, and planned
 amounts in pence.
 
+Read current assigned, spent, and available money without aggregating
+transactions yourself:
+
+```bash
+sloth-agent budget status --scope personal
+```
+
+The server applies its normal once-per-UTC-day automatic transaction refresh
+policy before returning the current Sloth period dates and signed booked
+activity. For each category, `availablePence` is
+`assignedPence - spentPence`; a negative value is over budget, and refunds
+reduce `spentPence`. Check `refresh`,
+`activity.uncategorizedSpentPence`, and `activity.unmappedSpentPence` before
+using the result to suggest a reallocation. This command is read-only.
+
 Update selected line-item amounts by creating `budget.json`:
 
 ```json
@@ -285,6 +302,37 @@ period and everything after it. Earlier and historical periods remain unchanged.
 Without `--apply`, the CLI validates the file locally and does not load a token
 or contact Sloth Money. Applying requires a write-enabled token.
 
+Move current assigned money between two categories, or use the reserved
+`to-assign` ID to move money to or from To Assign:
+
+```bash
+sloth-agent budget move \
+  --scope personal \
+  --from-category-id activities \
+  --to-category-id groceries \
+  --amount 52.95
+
+sloth-agent budget move \
+  --scope personal \
+  --from-category-id activities \
+  --to-category-id groceries \
+  --amount 52.95 \
+  --apply
+```
+
+Copy category IDs from `sloth-agent budget` output. `--amount` is expressed in
+the budget currency and accepts up to two decimal places; the CLI converts the
+decimal digits exactly and sends a positive safe-integer number of pence to the
+API. Without `--apply`, the command validates and prints the exact request
+without loading credentials or contacting Sloth Money.
+
+Applying subtracts and adds the amount atomically, records the movement in the
+budget history, and returns the affected assigned balances. It does not change
+planned line-item amounts or future budget plans. Like the UI, it permits a
+source category or To Assign to become negative; an automated workflow should
+choose donors from its own available-balance policy. Historical periods cannot
+be changed, and applying requires a write-enabled token.
+
 Create or rename a custom category. Writes are previews until `--apply` is
 present:
 

package/dist/args.js

@@ -49,16 +49,33 @@ function requireNonEmpty(value, name) {
         throw new UsageError(`${name} requires a value`);
     return value;
 }
-function parseGoalAmount(value, name) {
+function validatePositiveDecimalAmount(value, name) {
     if (!/^\d+(?:\.\d{1,2})?$/.test(value)) {
         throw new UsageError(`${name} must be a positive amount with at most two decimal places`);
     }
+    const digits = value.replace('.', '');
+    if (!/[1-9]/.test(digits)) {
+        throw new UsageError(`${name} must be a positive amount with at most two decimal places`);
+    }
+}
+function parsePositiveDecimalAmount(value, name) {
+    validatePositiveDecimalAmount(value, name);
     const amount = Number(value);
     if (!Number.isFinite(amount) || amount <= 0) {
         throw new UsageError(`${name} must be a positive amount with at most two decimal places`);
     }
     return amount;
 }
+function parsePositiveAmountPence(value, name) {
+    validatePositiveDecimalAmount(value, name);
+    const [wholePounds, fractionalPounds = ''] = value.split('.');
+    const amountPence = BigInt(wholePounds) * 100n
+        + BigInt(fractionalPounds.padEnd(2, '0'));
+    if (amountPence > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new UsageError(`${name} must be a positive amount with at most two decimal places`);
+    }
+    return Number(amountPence);
+}
 function parseGoalMonthKey(value, name) {
     if (!/^\d{4}-(0[1-9]|1[0-2])$/.test(value)) {
         throw new UsageError(`${name} must be a valid YYYY-MM month`);
@@ -109,7 +126,7 @@ function parseResourceId(value, option) {
             const codePoint = character.codePointAt(0);
             return codePoint !== undefined && (codePoint < 32 || codePoint === 127);
         })) {
-        const resource = option === '--category-id' ? 'category' : 'line-item';
+        const resource = option === '--line-item-id' ? 'line-item' : 'category';
         throw new UsageError(`${option} must be a valid ${resource} document ID`);
     }
     return id;
@@ -355,23 +372,60 @@ function parseInvestments(args, baseUrl) {
     return withBaseUrl({ command: 'investments', ...(accountRef ? { accountRef } : {}) }, baseUrl);
 }
 function parseBudget(args, baseUrl) {
-    const update = args[0] === 'update';
-    if (update)
-        args.shift();
-    const { values, apply } = parseNamedOptions(args, update ? 'budget update' : 'budget', new Set(update ? ['--scope', '--period', '--input'] : ['--scope', '--period']));
-    if (!update && apply)
-        throw new UsageError('Unknown budget option: --apply');
-    const scope = requiredOption(values, '--scope', update ? 'budget update' : 'budget');
+    const subcommand = args[0] === 'status' || args[0] === 'update' || args[0] === 'move'
+        ? args.shift()
+        : undefined;
+    const status = subcommand === 'status';
+    const update = subcommand === 'update';
+    const move = subcommand === 'move';
+    const commandLabel = status
+        ? 'budget status'
+        : update
+            ? 'budget update'
+            : move
+                ? 'budget move'
+                : 'budget';
+    const { values, apply } = parseNamedOptions(args, commandLabel, new Set(status
+        ? ['--scope']
+        : update
+            ? ['--scope', '--period', '--input']
+            : move
+                ? ['--scope', '--period', '--from-category-id', '--to-category-id', '--amount']
+                : ['--scope', '--period']));
+    if (!update && !move && apply)
+        throw new UsageError(`Unknown ${commandLabel} option: --apply`);
+    const scope = requiredOption(values, '--scope', commandLabel);
     if (scope !== 'personal' && scope !== 'joint') {
         throw new UsageError('--scope must be personal or joint');
     }
+    if (status) {
+        return withBaseUrl({
+            command: 'budget-status',
+            scope: scope,
+        }, baseUrl);
+    }
     const period = values.get('--period');
     const common = {
         scope: scope,
         ...(period === undefined ? {} : { periodKey: parseGoalMonthKey(period, '--period') }),
     };
-    if (!update)
+    if (!update && !move)
         return withBaseUrl({ command: 'budget', ...common }, baseUrl);
+    if (move) {
+        const fromCategoryId = parseResourceId(requiredOption(values, '--from-category-id', commandLabel), '--from-category-id');
+        const toCategoryId = parseResourceId(requiredOption(values, '--to-category-id', commandLabel), '--to-category-id');
+        if (fromCategoryId === toCategoryId) {
+            throw new UsageError('--from-category-id and --to-category-id must differ');
+        }
+        return withBaseUrl({
+            command: 'budget-move',
+            ...common,
+            fromCategoryId,
+            toCategoryId,
+            amountPence: parsePositiveAmountPence(requiredOption(values, '--amount', commandLabel), '--amount'),
+            apply,
+        }, baseUrl);
+    }
     return withBaseUrl({
         command: 'budget-update',
         ...common,
@@ -527,7 +581,7 @@ function parseGoals(args, baseUrl) {
                 name = setOnce(name, parseGoalName(value), option);
             }
             else if (option === '--target-amount') {
-                targetAmount = setOnce(targetAmount, parseGoalAmount(value, option), option);
+                targetAmount = setOnce(targetAmount, parsePositiveDecimalAmount(value, option), option);
             }
             else if (option === '--target-month') {
                 targetMonthKey = setOnce(targetMonthKey, parseGoalMonthKey(value, option), option);
@@ -597,7 +651,7 @@ function parseGoals(args, baseUrl) {
                 name = setOnce(name, parseGoalName(value), option);
             }
             else if (option === '--target-amount') {
-                targetAmount = setOnce(targetAmount, parseGoalAmount(value, option), option);
+                targetAmount = setOnce(targetAmount, parsePositiveDecimalAmount(value, option), option);
             }
             else if (option === '--target-month') {
                 if (targetMonthKey !== undefined) {
@@ -732,7 +786,13 @@ function helpTopic(argv) {
         return undefined;
     }
     if (command === 'budget') {
-        return subcommand === 'update' ? 'budget-update' : 'budget';
+        if (subcommand === 'status')
+            return 'budget-status';
+        if (subcommand === 'update')
+            return 'budget-update';
+        if (subcommand === 'move')
+            return 'budget-move';
+        return 'budget';
     }
     if (command === 'accounts'
         || command === 'transactions'

package/dist/cli.js

@@ -1,10 +1,10 @@
 import fs from 'node:fs';
 import { parseArgs, resolveBaseUrl, } from './args.js';
 import { ICON_KEYS } from './category-metadata.js';
-import { parseApiResponse, validateAssignmentPayload, validateBudgetUpdatePayload, } from './contracts.js';
+import { parseApiResponse, validateAssignmentPayload, validateBudgetMovementResponse, validateBudgetUpdatePayload, } from './contracts.js';
 import { createSystemCredentialStore, secureStorageUnavailableError, } from './credential-store.js';
 import { ApiError, CliError, ConfigError, UsageError, } from './errors.js';
-export const CLI_VERSION = '0.10.0';
+export const CLI_VERSION = '0.12.0';
 const REQUEST_TIMEOUT_MS = 60_000;
 const API_ORIGIN_HELP_LINES = [
     '',
@@ -30,8 +30,11 @@ export function usageText() {
         '  sloth-agent accounts remove --account-ref REF [--apply]',
         '  sloth-agent investments [--account-ref REF] [--base-url URL]',
         '  sloth-agent budget --scope personal|joint [--period YYYY-MM] [--base-url URL]',
+        '  sloth-agent budget status --scope personal|joint [--base-url URL]',
         '  sloth-agent budget update --scope personal|joint [--period YYYY-MM]',
         '    --input budget.json [--apply] [--base-url URL]',
+        '  sloth-agent budget move --scope personal|joint [--period YYYY-MM]',
+        '    --from-category-id ID --to-category-id ID --amount AMOUNT [--apply]',
         '  sloth-agent categories [list] [--base-url URL]',
         '  sloth-agent categories create --name NAME --icon-key KEY --type TYPE [--apply]',
         '  sloth-agent categories rename --category-id ID --name NAME [--apply]',
@@ -419,6 +422,35 @@ export function budgetHelpText() {
         '  Categories also include plannedPence and assignedPence.',
     ].join('\n');
 }
+export function budgetStatusHelpText() {
+    return [
+        'Sloth Agent CLI — budget status',
+        '',
+        'Read assigned, spent, and available money for the current Sloth budget period.',
+        '',
+        'Usage:',
+        '  sloth-agent budget status --scope personal|joint [--base-url URL]',
+        '',
+        'Options:',
+        '  --scope personal|joint  Required. Budget ownership scope.',
+        '  --base-url URL          Optional. Override the API origin.',
+        '  -h, --help              Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Access and freshness:',
+        '  This command is read-only, requires agent:read, and never changes the budget.',
+        '  The server applies its normal once-per-UTC-day automatic transaction refresh policy.',
+        '  Inspect refresh.status and refresh.reason before relying on the result.',
+        '',
+        'Output:',
+        '  categories[].assignedPence is the money assigned to the category.',
+        '  categories[].spentPence is signed booked activity; refunds reduce it.',
+        '  categories[].availablePence equals assignedPence minus spentPence.',
+        '  Negative availablePence means the category is over budget.',
+        '  activity contains the period dates, transaction count, uncategorizedSpentPence,',
+        '  and unmappedSpentPence. Review either nonzero value before moving money.',
+    ].join('\n');
+}
 export function budgetUpdateHelpText() {
     return [
         'Sloth Agent CLI — budget update',
@@ -457,6 +489,47 @@ export function budgetUpdateHelpText() {
         '  Apply mode returns the complete persisted budget response.',
     ].join('\n');
 }
+export function budgetMoveHelpText() {
+    return [
+        'Sloth Agent CLI — budget move',
+        '',
+        'Preview or move assigned money between categories or To Assign.',
+        '',
+        'Usage:',
+        '  sloth-agent budget move --scope personal|joint [--period YYYY-MM] --from-category-id ID --to-category-id ID --amount AMOUNT [--apply] [--base-url URL]',
+        '',
+        'Required inputs:',
+        '  --scope personal|joint  Budget ownership scope.',
+        '  --from-category-id ID   Source category ID, or to-assign.',
+        '  --to-category-id ID     Destination category ID, or to-assign.',
+        '  --amount AMOUNT         Positive amount in the budget currency, with up to two decimals.',
+        '                          The integer-pence value must be at most 9,007,199,254,740,991.',
+        '',
+        'Optional inputs:',
+        '  --period YYYY-MM        Defaults to the current Sloth budget period.',
+        '  --apply                 Send the movement. Without it, only validate and preview.',
+        '  --base-url URL          Override the API origin.',
+        '  -h, --help              Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Write behavior:',
+        '  Without --apply, returns JSON locally without loading credentials or contacting Sloth Money.',
+        '  With --apply, atomically subtracts from the source and adds to the destination.',
+        '  Use the reserved ID to-assign to move money to or from To Assign.',
+        '  The move changes current assigned balances and records budget movement history.',
+        '  The source category or To Assign may become negative, so choose the source deliberately.',
+        '  It does not change planned amounts or future budget plans.',
+        '  Historical periods cannot be changed. Applying requires agent:write.',
+        '',
+        'Output:',
+        '  Preview mode returns dryRun, endpoint, method, and the amountPence payload.',
+        '  Apply mode returns the period, currency, movement, To Assign balance, and affected category balances.',
+        '',
+        'Examples:',
+        '  sloth-agent budget move --scope personal --from-category-id activities --to-category-id groceries --amount 52.95',
+        '  sloth-agent budget move --scope personal --from-category-id activities --to-category-id groceries --amount 52.95 --apply',
+    ].join('\n');
+}
 export function transactionsHelpText() {
     return [
         'Sloth Agent CLI — transactions',
@@ -824,6 +897,8 @@ export function commandHelpText(topic) {
         'accounts-remove': accountsRemoveHelpText,
         investments: investmentsHelpText,
         budget: budgetHelpText,
+        'budget-status': budgetStatusHelpText,
+        'budget-move': budgetMoveHelpText,
         'budget-update': budgetUpdateHelpText,
         categories: categoriesHelpText,
         'categories-create': categoriesCreateHelpText,
@@ -1140,6 +1215,24 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             });
             return 0;
         }
+        const budgetMovementPayload = parsed.command === 'budget-move'
+            ? {
+                scope: parsed.scope,
+                ...(parsed.periodKey === undefined ? {} : { periodKey: parsed.periodKey }),
+                fromCategoryId: parsed.fromCategoryId,
+                toCategoryId: parsed.toCategoryId,
+                amountPence: parsed.amountPence,
+            }
+            : undefined;
+        if (parsed.command === 'budget-move' && !parsed.apply) {
+            writeJson(writeStdout, {
+                dryRun: true,
+                endpoint: `${baseUrl}/api/agent/v1/budget-movements`,
+                method: 'POST',
+                payload: budgetMovementPayload,
+            });
+            return 0;
+        }
         const credential = await resolveCredential(environment, baseUrl, getCredentialStore);
         token = credential.token;
         const headers = requestHeaders(token);
@@ -1182,6 +1275,17 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             writeJson(writeStdout, data);
             return 0;
         }
+        if (parsed.command === 'budget-move') {
+            const response = await fetchImplementation(`${baseUrl}/api/agent/v1/budget-movements`, {
+                method: 'POST',
+                headers: { ...headers, 'Content-Type': 'application/json' },
+                body: JSON.stringify(budgetMovementPayload),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const data = validateBudgetMovementResponse(await parseHttpResponse(response, token), budgetMovementPayload);
+            writeJson(writeStdout, data);
+            return 0;
+        }
         if (parsed.command === 'categories-create'
             || parsed.command === 'categories-rename'
             || parsed.command === 'line-items-create'
@@ -1356,16 +1460,19 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             writeJson(writeStdout, withListedGoalPriorities(data));
             return 0;
         }
-        if (parsed.command === 'budget') {
+        if (parsed.command === 'budget' || parsed.command === 'budget-status') {
             const query = new URLSearchParams({ scope: parsed.scope });
-            if (parsed.periodKey !== undefined)
+            if (parsed.command === 'budget' && parsed.periodKey !== undefined) {
                 query.set('periodKey', parsed.periodKey);
-            const response = await fetchImplementation(`${baseUrl}/api/agent/v1/budgets?${query.toString()}`, {
+            }
+            const response = await fetchImplementation(`${baseUrl}/api/agent/v1/${parsed.command === 'budget' ? 'budgets' : 'budget-status'}?${query.toString()}`, {
                 method: 'GET',
-                headers,
+                headers: parsed.command === 'budget-status'
+                    ? { ...headers, Prefer: 'wait=45' }
+                    : headers,
                 signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
             });
-            const data = parseApiResponse('budget', await parseHttpResponse(response, token));
+            const data = parseApiResponse(parsed.command, await parseHttpResponse(response, token));
             writeJson(writeStdout, data);
             return 0;
         }

package/dist/contracts.js

@@ -227,28 +227,32 @@ function isTransaction(value) {
             || value.incomeSubtype === 'pay'
             || value.incomeSubtype === 'interest'));
 }
+const REFRESH_STATUSES = new Set(['skipped', 'completed', 'in_progress', 'partial', 'failed']);
+const REFRESH_REASONS = new Set([
+    'all_fetched_today',
+    'no_api_connections',
+    'no_selected_accounts',
+    'refreshed',
+    'wait_timeout',
+    'account_failures',
+    'partial_already_attempted',
+    '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));
+}
 function isTransactionsResponse(value) {
-    const validStatuses = new Set(['skipped', 'completed', 'in_progress', 'partial', 'failed']);
-    const validReasons = new Set([
-        'all_fetched_today',
-        'no_api_connections',
-        'no_selected_accounts',
-        'refreshed',
-        'wait_timeout',
-        'account_failures',
-        'refresh_error',
-    ]);
-    const refresh = isObject(value) ? value.refresh : undefined;
     return (isObject(value)
         && Array.isArray(value.transactions)
         && value.transactions.every(isTransaction)
         && (value.nextCursor === null || typeof value.nextCursor === 'string')
-        && isObject(refresh)
-        && typeof refresh.status === 'string'
-        && validStatuses.has(refresh.status)
-        && typeof refresh.reason === 'string'
-        && validReasons.has(refresh.reason)
-        && isIsoDate(refresh.utcDate));
+        && isRefreshStatus(value.refresh));
 }
 function isAssignmentResponse(value) {
     return (isObject(value)
@@ -375,6 +379,125 @@ function isBudgetResponse(value) {
         && Array.isArray(value.categories)
         && value.categories.every(isBudgetCategory));
 }
+function isBudgetStatusResponse(value) {
+    if (!isObject(value)
+        || !hasOnlyFields(value, [
+            'scope',
+            'periodKey',
+            'periodStatus',
+            'currency',
+            'effectiveFromPeriodKey',
+            'funding',
+            'activity',
+            'refresh',
+            'categories',
+        ]))
+        return false;
+    return ((value.scope === 'personal' || value.scope === 'joint')
+        && typeof value.periodKey === 'string'
+        && /^\d{4}-(0[1-9]|1[0-2])$/.test(value.periodKey)
+        && value.periodStatus === 'current'
+        && isCurrency(value.currency)
+        && typeof value.effectiveFromPeriodKey === 'string'
+        && /^\d{4}-(0[1-9]|1[0-2])$/.test(value.effectiveFromPeriodKey)
+        && (value.funding === null
+            || (isObject(value.funding)
+                && hasOnlyFields(value.funding, ['toAssignPence', 'nextPeriodReservePence'])
+                && isSafeInteger(value.funding.toAssignPence)
+                && isSafeInteger(value.funding.nextPeriodReservePence)))
+        && isObject(value.activity)
+        && hasOnlyFields(value.activity, [
+            'startDate',
+            'endDate',
+            'transactionCount',
+            'uncategorizedSpentPence',
+            'unmappedSpentPence',
+        ])
+        && isIsoDate(value.activity.startDate)
+        && isIsoDate(value.activity.endDate)
+        && value.activity.startDate <= value.activity.endDate
+        && isNonnegativeSafeInteger(value.activity.transactionCount)
+        && isSafeInteger(value.activity.uncategorizedSpentPence)
+        && isSafeInteger(value.activity.unmappedSpentPence)
+        && isRefreshStatus(value.refresh)
+        && Array.isArray(value.categories)
+        && value.categories.every((category) => (isObject(category)
+            && hasOnlyFields(category, [
+                'id',
+                'name',
+                'plannedPence',
+                'assignedPence',
+                'spentPence',
+                'availablePence',
+            ])
+            && typeof category.id === 'string'
+            && category.id.trim().length > 0
+            && typeof category.name === 'string'
+            && category.name.trim().length > 0
+            && isNonnegativeSafeInteger(category.plannedPence)
+            && isSafeInteger(category.assignedPence)
+            && isSafeInteger(category.spentPence)
+            && isSafeInteger(category.availablePence)
+            && Number.isSafeInteger(category.assignedPence - category.spentPence)
+            && category.availablePence === category.assignedPence - category.spentPence)));
+}
+function isBudgetMovementResponse(value) {
+    return (isObject(value)
+        && hasOnlyFields(value, [
+            'moved',
+            'scope',
+            'periodKey',
+            'currency',
+            'fromCategoryId',
+            'toCategoryId',
+            'amountPence',
+            'toAssignPence',
+            'categoryBalances',
+        ])
+        && value.moved === true
+        && (value.scope === 'personal' || value.scope === 'joint')
+        && typeof value.periodKey === 'string'
+        && /^\d{4}-(0[1-9]|1[0-2])$/.test(value.periodKey)
+        && isCurrency(value.currency)
+        && typeof value.fromCategoryId === 'string'
+        && value.fromCategoryId.trim().length > 0
+        && typeof value.toCategoryId === 'string'
+        && value.toCategoryId.trim().length > 0
+        && value.fromCategoryId !== value.toCategoryId
+        && isNonnegativeSafeInteger(value.amountPence)
+        && value.amountPence > 0
+        && isSafeInteger(value.toAssignPence)
+        && Array.isArray(value.categoryBalances)
+        && value.categoryBalances.length >= 1
+        && value.categoryBalances.length <= 2
+        && value.categoryBalances.every((balance) => (isObject(balance)
+            && hasOnlyFields(balance, ['categoryId', 'assignedPence'])
+            && typeof balance.categoryId === 'string'
+            && balance.categoryId.trim().length > 0
+            && isSafeInteger(balance.assignedPence))));
+}
+export function validateBudgetMovementResponse(value, expected) {
+    if (!isBudgetMovementResponse(value)) {
+        throw new ApiError('Invalid budget-move response from the Agent API');
+    }
+    const expectedCategoryIds = [expected.fromCategoryId, expected.toCategoryId]
+        .filter(categoryId => categoryId !== 'to-assign')
+        .sort();
+    const actualCategoryIds = value.categoryBalances
+        .map(balance => balance.categoryId)
+        .sort();
+    const matchesRequest = value.scope === expected.scope
+        && (expected.periodKey === undefined || value.periodKey === expected.periodKey)
+        && value.fromCategoryId === expected.fromCategoryId
+        && value.toCategoryId === expected.toCategoryId
+        && value.amountPence === expected.amountPence;
+    const matchesAffectedCategories = actualCategoryIds.length === expectedCategoryIds.length
+        && actualCategoryIds.every((categoryId, index) => categoryId === expectedCategoryIds[index]);
+    if (!matchesRequest || !matchesAffectedCategories) {
+        throw new ApiError('Invalid budget-move response from the Agent API');
+    }
+    return value;
+}
 function isNullableNonEmptyString(value) {
     return value === null || (typeof value === 'string'
         && value.length > 0
@@ -511,23 +634,27 @@ export function parseApiResponse(command, value) {
                     ? isInvestmentsResponse(value)
                     : command === 'budget' || command === 'budget-update'
                         ? isBudgetResponse(value)
-                        : command === 'categories'
-                            ? isCategoryResponse(value)
-                            : command === 'categories-create' || command === 'categories-rename'
-                                ? isCategoryMutationResponse(value)
-                                : command === 'line-items-create' || command === 'line-items-rename'
-                                    ? isLineItemMutationResponse(value)
-                                    : command === 'transactions'
-                                        ? isTransactionsResponse(value)
-                                        : command === 'assign'
-                                            ? isAssignmentResponse(value)
-                                            : command === 'ask-partner'
-                                                ? isPartnerResponse(value)
-                                                : command === 'goals-list'
-                                                    ? isGoalsResponse(value)
-                                                    : command === 'goals-delete'
-                                                        ? isGoalDeleteResponse(value)
-                                                        : isGoalMutationResponse(value);
+                        : command === 'budget-status'
+                            ? isBudgetStatusResponse(value)
+                            : command === 'budget-move'
+                                ? isBudgetMovementResponse(value)
+                                : command === 'categories'
+                                    ? isCategoryResponse(value)
+                                    : command === 'categories-create' || command === 'categories-rename'
+                                        ? isCategoryMutationResponse(value)
+                                        : command === 'line-items-create' || command === 'line-items-rename'
+                                            ? isLineItemMutationResponse(value)
+                                            : command === 'transactions'
+                                                ? isTransactionsResponse(value)
+                                                : command === 'assign'
+                                                    ? isAssignmentResponse(value)
+                                                    : command === 'ask-partner'
+                                                        ? isPartnerResponse(value)
+                                                        : command === 'goals-list'
+                                                            ? isGoalsResponse(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.10.0",
+  "version": "0.12.0",
   "description": "Command-line access to the Sloth Money Agent API.",
   "type": "module",
   "bin": {