@slothmoney/agent-cli 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.18.0 - 2026-08-25
+
+- Add optional `--period YYYY-MM` to `budget status` for current and historical
+  Sloth budget periods.
+- Replace signed spending-only status with clear money-in, money-out, and net
+  activity for Income, Transfer, None, ordinary, custom, and uncategorized
+  transactions.
+- Accept the old current-status response temporarily during the coordinated
+  backend rollout; historical responses use the new strict contract.
+- Add a release preflight that compares local, packed, globally installed, and
+  npm-registry versions and checks every nested help route.
+
+## 0.17.0 - 2026-08-25
+
+- Run applied transaction-assignment batches through resumable server
+  operations while keeping the existing `assign --input ... --apply` command
+  and terminal `succeeded`/`failed` JSON output unchanged.
+- Retry transient submission and status requests with a deterministic
+  request key, so re-running an interrupted command resumes the same operation.
+- Strictly validate operation progress, expiry, counts, and ordered terminal
+  item receipts before printing an assignment result.
+
 ## 0.16.0 - 2026-08-21
 
 - Add receipt image extraction plus read, preview-by-default attach, and remove

package/README.md

@@ -15,7 +15,7 @@ sloth-agent --version
 For a one-off pinned run:
 
 ```bash
-npm exec --yes --package=@slothmoney/agent-cli@0.16.0 -- sloth-agent --help
+npm exec --yes --package=@slothmoney/agent-cli@0.17.0 -- sloth-agent --help
 ```
 
 ## Authenticate
@@ -302,6 +302,10 @@ assignment, set `"assignmentScope": "joint"` in the assignment payload and use
 
 These are placeholders. Do not submit the example values.
 
+Each `transactionRef` may appear only once in an assignment file. Split one
+transaction across categories with `categorySplits` instead of adding the same
+transaction twice.
+
 4. Preview the assignment without writing:
 
 ```bash
@@ -321,7 +325,17 @@ sloth-agent assign --input assignments.json --apply
 
 This step requires a token created with **Allow changes**.
 
-Inspect every item in the returned `succeeded` and `failed` arrays.
+The CLI submits a durable server operation and polls its authenticated status
+until every item has finished. It then prints the same `succeeded` and `failed`
+arrays as before, so existing agent workflows do not need to change. Inspect
+every item in both arrays.
+
+If the command is interrupted or a request times out, re-run the same command
+with the same assignment input. The CLI derives the same request key
+from the validated assignments, so the server resumes the existing operation
+instead of applying the batch again. The server retains operation status and
+item receipts for seven days. Changing the assignments creates a different
+operation.
 
 6. Check the result in the same assignment scope that you changed. Successful
    assignments update the category and optional budget line item on the
@@ -414,20 +428,27 @@ 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:
+Read booked activity for the current or a historical Sloth period:
 
 ```bash
 sloth-agent budget status --scope personal
+sloth-agent budget status --scope personal --period 2026-07
 ```
 
-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.
+The period key names the calendar month containing that Sloth period's start
+boundary. Its end date can fall in the following month.
+
+The current period uses Sloth's normal once-per-UTC-day transaction refresh;
+historical periods are cache-only and return `refresh: null`. Activity contains
+nonnegative `moneyInPence` and `moneyOutPence` plus their difference as
+`netPence`. Income, Transfer, explicit None, budget categories, and observed
+custom categories are normal rows. A transaction with no category at all is
+reported separately under `activity.uncategorized`.
+
+`budget` contains assigned, spent, and available category amounts when a
+trustworthy period plan exists. It is `null` when it does not; activity still
+returns. The response includes only the period budget currency and silently
+ignores rows in other currencies. This command is read-only.
 
 Update selected line-item amounts by creating `budget.json`:
 
@@ -624,9 +645,12 @@ sloth-agent investments --account-ref sloth_account_v1_...
 Investment reads are cache-only and do not refresh a brokerage. Holding
 quantities, unit prices, market values, currencies, and freshness are returned
 in provider-native terms. They are not converted or guaranteed to reconcile
-to an account total reported in another currency. Caller-owned personal and
-joint linked investment accounts are included; partner-owned accounts, manual
-holdings, and investment activities are not.
+to an account total reported in another currency. An investment account total
+and its nested holdings describe the same portfolio, so do not add them
+together. Do not add values in different currencies without an explicit
+conversion. Caller-owned personal and joint linked investment accounts are
+included; partner-owned accounts, manual holdings, and investment activities
+are not.
 
 List your goals:
 
@@ -765,19 +789,26 @@ Command results are JSON on stdout. Diagnostics are written to stderr.
 | `2` | Invalid command, option, URL, date, auth input, goal input, or assignment input |
 | `3` | No credential or native secure storage is unavailable |
 
-Assignment writes are best-effort. A response containing any failed assignment
-returns exit code `1` while preserving the complete API response on stdout.
+Assignment writes run as durable, best-effort operations. The CLI waits for the
+terminal result and returns exit code `1` when any item failed, while preserving
+the complete `succeeded` and `failed` arrays on stdout. Re-running an interrupted
+command with the same input resumes the same server operation.
 
 ## Development
 
 ```bash
 npm ci
 npm run verify
+npm run release:preflight
 ```
 
 `npm run test:package` packs the exact npm artifact, installs it into a clean
 temporary project, and runs the installed binary.
 
+`npm run release:preflight` reports the local, packed, globally installed, and
+npm-registry versions, then exercises every parser command's nested help. It
+fails when a parent help page stops advertising one of its child commands.
+
 ## Releasing
 
 Releases are published only through the trusted `Publish npm release` GitHub

package/dist/args.js

@@ -486,7 +486,7 @@ function parseBudget(args, baseUrl) {
                 ? 'budget move'
                 : 'budget';
     const { values, apply } = parseNamedOptions(args, commandLabel, new Set(status
-        ? ['--scope']
+        ? ['--scope', '--period']
         : update
             ? ['--scope', '--period', '--input']
             : move
@@ -498,17 +498,13 @@ function parseBudget(args, baseUrl) {
     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 (status)
+        return withBaseUrl({ command: 'budget-status', ...common }, baseUrl);
     if (!update && !move)
         return withBaseUrl({ command: 'budget', ...common }, baseUrl);
     if (move) {

package/dist/cli.js

@@ -1,11 +1,12 @@
+import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import nodePath from 'node:path';
 import { parseArgs, resolveBaseUrl, } from './args.js';
 import { ICON_KEYS } from './category-metadata.js';
-import { parseApiResponse, validateAssignmentPayload, validateBudgetMovementResponse, validateBudgetUpdatePayload, validateNotificationRulePayload, validateReceiptConfirmation, } from './contracts.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.16.0';
+export const CLI_VERSION = '0.18.0';
 const REQUEST_TIMEOUT_MS = 60_000;
 const MAX_CONTRACT_PDF_BYTES = 6_000_000;
 const API_ORIGIN_HELP_LINES = [
@@ -16,6 +17,8 @@ const API_ORIGIN_HELP_LINES = [
     '  Use an origin-only URL with no credentials, path, query, or fragment.',
     '  HTTPS is required except for localhost development.',
 ];
+const ASSIGNMENT_REQUEST_ATTEMPTS = 3;
+const ASSIGNMENT_RETRY_DELAY_MS = 500;
 export function usageText() {
     return [
         'Sloth Agent CLI',
@@ -32,7 +35,7 @@ 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 status --scope personal|joint [--period YYYY-MM] [--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]',
@@ -458,7 +461,7 @@ export function budgetHelpText() {
         '',
         'Options:',
         '  --scope personal|joint  Required. Budget ownership scope.',
-        '  --period YYYY-MM        Optional. Defaults to the current Sloth budget period.',
+        '  --period YYYY-MM        Optional. Month containing the period start; defaults to the current Sloth period.',
         '  --base-url URL          Optional. Override the API origin.',
         '  -h, --help              Show this help.',
         ...API_ORIGIN_HELP_LINES,
@@ -477,29 +480,28 @@ export function budgetStatusHelpText() {
     return [
         'Sloth Agent CLI — budget status',
         '',
-        'Read assigned, spent, and available money for the current Sloth budget period.',
+        'Read booked activity and any trustworthy budget for one Sloth budget period.',
         '',
         'Usage:',
-        '  sloth-agent budget status --scope personal|joint [--base-url URL]',
+        '  sloth-agent budget status --scope personal|joint [--period YYYY-MM] [--base-url URL]',
         '',
         'Options:',
         '  --scope personal|joint  Required. Budget ownership scope.',
+        '  --period YYYY-MM        Optional. Month containing the period start; defaults to the current Sloth period.',
         '  --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.',
+        '  Current periods use the normal transaction refresh policy; historical periods are cache-only.',
+        '  A historical response returns refresh as null.',
         '',
         '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.',
+        '  activity.categories includes Income, Transfer, None, and ordinary categories.',
+        '  moneyInPence and moneyOutPence are nonnegative; netPence is money in minus money out.',
+        '  A transaction with no category appears under activity.uncategorized.',
+        '  budget contains the period plan and balances, or budget is null when no trustworthy plan exists.',
     ].join('\n');
 }
 export function budgetUpdateHelpText() {
@@ -654,13 +656,19 @@ export function assignHelpText() {
         '  the payload it would send. It does not contact Sloth Money, verify the',
         '  transactionRef or category values, or write anything.',
         '  A successful preview does not guarantee that applying it will succeed.',
-        '  With --apply, assignments are best-effort; any failed item makes the command',
-        '  exit with code 1 while the complete result remains available on stdout.',
+        '  With --apply, the CLI submits one durable server operation, then polls authenticated status',
+        '  until every item finishes. Transient submission and status failures are retried.',
+        '  Re-run the same command with the same assignment input after an interruption;',
+        '  the CLI resumes the same operation instead of duplicating its work.',
+        '  Operation status and item receipts remain available on the server for seven days.',
+        '  Assignments are best-effort; any failed item makes the command exit with code 1',
+        '  while the complete terminal result remains available on stdout.',
         '  Applying requires a write-enabled token created with Allow changes.',
         '',
         'Input:',
         '  The top-level object must contain an assignments array.',
         '  Each assignment requires transactionRef and at least one category operation or sharing object.',
+        '  Each transactionRef may appear only once in the assignments array.',
         '  sharing.isShared is required. shareRatio is optional from 0 to 1 and is your share.',
         '  userExclusiveAmountPence and partnerExclusiveAmountPence are optional nonnegative integers.',
         '  Omitted split values use saved defaults for a first share and preserve an existing split.',
@@ -702,7 +710,7 @@ export function assignHelpText() {
         '',
         'Output:',
         '  Preview mode returns dryRun, endpoint, and the validated payload.',
-        '  Apply mode returns succeeded and failed assignment arrays.',
+        '  Apply mode waits for the durable operation and returns succeeded and failed arrays.',
         '  Successful assignments update the original transaction. See the result in',
         '  Sloth Money → Transactions or read the transaction again through the CLI.',
         '  Assignments do not create a separate list.',
@@ -953,11 +961,11 @@ export function rulesHelpText() {
         'Rules do not create transactions or recurring predictions.',
         '',
         'Commands:',
-        '  rules list           List every saved notification rule.',
-        '  rules get            Read the rule for one transaction.',
-        '  rules set            Preview or save a rule for one transaction.',
-        '  rules delete         Preview or remove a rule.',
-        '  rules scan-contract  Validate or scan a PDF for its renewal date.',
+        '  sloth-agent rules list           List every saved notification rule.',
+        '  sloth-agent rules get            Read the rule for one transaction.',
+        '  sloth-agent rules set            Preview or save a rule for one transaction.',
+        '  sloth-agent rules delete         Preview or remove a rule.',
+        '  sloth-agent rules scan-contract  Validate or scan a PDF for its renewal date.',
         '',
         'Use the exact transactionRef returned by sloth-agent transactions.',
         ...API_ORIGIN_HELP_LINES,
@@ -1407,6 +1415,99 @@ function requestHeaders(token) {
         'User-Agent': `sloth-agent/${CLI_VERSION}`,
     };
 }
+function assignmentIdempotencyKey(payload) {
+    return createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+}
+function isRetryableAssignmentRequestError(error) {
+    if (error instanceof ApiError) {
+        return error.status !== undefined
+            && [408, 425, 429, 499, 500, 502, 503, 504].includes(error.status);
+    }
+    return error instanceof TypeError
+        || (error instanceof Error && error.name === 'AbortError');
+}
+async function withAssignmentRequestRecovery(request, sleep) {
+    let lastError;
+    for (let attempt = 1; attempt <= ASSIGNMENT_REQUEST_ATTEMPTS; attempt += 1) {
+        try {
+            return await request();
+        }
+        catch (error) {
+            lastError = error;
+            if (!isRetryableAssignmentRequestError(error) || attempt === ASSIGNMENT_REQUEST_ATTEMPTS) {
+                throw error;
+            }
+            await sleep(ASSIGNMENT_RETRY_DELAY_MS * attempt);
+        }
+    }
+    throw lastError;
+}
+async function parseAssignmentOperationHttpResponse(response, token, expectedStatus) {
+    const data = await parseHttpResponse(response, token);
+    if (response.status !== expectedStatus) {
+        throw new ApiError(`Agent API returned status ${response.status}; expected ${expectedStatus}`, response.status);
+    }
+    return parseAssignmentOperationResponse(data);
+}
+function assertAssignmentOperationMatchesPayload(operation, payload, expectedOperationId) {
+    if (operation.itemCount !== payload.assignments.length
+        || (expectedOperationId !== undefined && operation.operationId !== expectedOperationId)
+        || (operation.status === 'completed'
+            && operation.results?.some((result, index) => (result.transactionRef !== payload.assignments[index]?.transactionRef)))) {
+        throw new ApiError('Assignment operation response did not match the submitted assignment order');
+    }
+}
+async function applyAssignments(fetchImplementation, sleep, baseUrl, token, payload) {
+    const endpoint = `${baseUrl}/api/agent/v1/transaction-assignments`;
+    const idempotencyKey = assignmentIdempotencyKey(payload);
+    let operation;
+    try {
+        operation = await withAssignmentRequestRecovery(async () => {
+            const response = await fetchImplementation(endpoint, {
+                method: 'POST',
+                headers: {
+                    ...requestHeaders(token),
+                    'Content-Type': 'application/json',
+                    'Idempotency-Key': idempotencyKey,
+                },
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            return parseAssignmentOperationHttpResponse(response, token, 202);
+        }, sleep);
+    }
+    catch (error) {
+        if (!isRetryableAssignmentRequestError(error))
+            throw error;
+        throw new ApiError('Assignment submission could not be confirmed. '
+            + 'Re-run the same command with the same assignment input to resume it.');
+    }
+    assertAssignmentOperationMatchesPayload(operation, payload);
+    const operationId = operation.operationId;
+    while (operation.status !== 'completed') {
+        await sleep(operation.pollAfterMs);
+        const statusEndpoint = `${endpoint}/${encodeURIComponent(operationId)}`;
+        try {
+            const nextOperation = await withAssignmentRequestRecovery(async () => {
+                const response = await fetchImplementation(statusEndpoint, {
+                    method: 'GET',
+                    headers: requestHeaders(token),
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                });
+                return parseAssignmentOperationHttpResponse(response, token, 200);
+            }, sleep);
+            assertAssignmentOperationMatchesPayload(nextOperation, payload, operationId);
+            operation = nextOperation;
+        }
+        catch (error) {
+            if (!isRetryableAssignmentRequestError(error))
+                throw error;
+            throw new ApiError('Assignment status could not be recovered. '
+                + 'Re-run the same command with the same assignment input to resume it.');
+        }
+    }
+    return toLegacyAssignmentResponse(operation);
+}
 async function validateCredentialRemotely(fetchImplementation, origin, token) {
     const response = await fetchImplementation(`${origin}/api/agent/v1/categories`, {
         method: 'GET',
@@ -1442,6 +1543,9 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
         ?? Boolean(process.stdin.isTTY && process.stderr.isTTY);
     const readSecret = options.readSecret ?? defaultReadSecret;
     const readStdin = options.readStdin ?? defaultReadStdin;
+    const sleep = options.sleep ?? ((milliseconds) => new Promise((resolve) => {
+        setTimeout(resolve, milliseconds);
+    }));
     const writeStdout = options.writeStdout ?? ((value) => process.stdout.write(value));
     const writeStderr = options.writeStderr ?? ((value) => process.stderr.write(value));
     let token;
@@ -1884,17 +1988,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
         }
         if (parsed.command === 'assign') {
             const payload = assignmentPayload;
-            const endpoint = `${baseUrl}/api/agent/v1/transaction-assignments`;
-            const response = await fetchImplementation(endpoint, {
-                method: 'POST',
-                headers: {
-                    ...headers,
-                    'Content-Type': 'application/json',
-                },
-                body: JSON.stringify(payload),
-                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-            });
-            const data = parseApiResponse('assign', await parseHttpResponse(response, token));
+            const data = await applyAssignments(fetchImplementation, sleep, baseUrl, token, payload);
             writeJson(writeStdout, data);
             return hasFailures(data) ? 1 : 0;
         }
@@ -1970,7 +2064,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
         }
         if (parsed.command === 'budget' || parsed.command === 'budget-status') {
             const query = new URLSearchParams({ scope: parsed.scope });
-            if (parsed.command === 'budget' && parsed.periodKey !== undefined) {
+            if (parsed.periodKey !== undefined) {
                 query.set('periodKey', parsed.periodKey);
             }
             const response = await fetchImplementation(`${baseUrl}/api/agent/v1/${parsed.command === 'budget' ? 'budgets' : 'budget-status'}?${query.toString()}`, {

package/dist/contracts.js

@@ -269,7 +269,15 @@ export function validateAssignmentPayload(value) {
     if (payload.assignments.length < 1 || payload.assignments.length > 100) {
         throw new UsageError('assignments must contain between 1 and 100 items');
     }
-    return { assignments: payload.assignments.map(validateAssignment) };
+    const assignments = payload.assignments.map(validateAssignment);
+    const transactionRefs = new Set();
+    for (const assignment of assignments) {
+        if (transactionRefs.has(assignment.transactionRef)) {
+            throw new UsageError('Each assignments[].transactionRef must be unique');
+        }
+        transactionRefs.add(assignment.transactionRef);
+    }
+    return { assignments };
 }
 export function validateBudgetUpdatePayload(value) {
     const payload = requireObject(value, 'budget update payload');
@@ -505,6 +513,73 @@ function isAssignmentResponse(value) {
             && typeof item.error === 'string'
             && (item.transactionRef === undefined || typeof item.transactionRef === 'string'))));
 }
+function isAssignmentOperationResult(value) {
+    if (!isObject(value) || typeof value.transactionRef !== 'string')
+        return false;
+    const { status, ...legacyResult } = value;
+    if (status === 'succeeded') {
+        return isAssignmentResponse({ succeeded: [legacyResult], failed: [] });
+    }
+    if (status === 'failed') {
+        return isAssignmentResponse({ succeeded: [], failed: [legacyResult] });
+    }
+    return false;
+}
+export function parseAssignmentOperationResponse(value) {
+    const validBase = isObject(value)
+        && hasOnlyFields(value, [
+            'operationId', 'status', 'itemCount', 'completedCount', 'failedCount',
+            'expiresAt', 'pollAfterMs', 'results',
+        ])
+        && typeof value.operationId === 'string'
+        && /^[a-f0-9]{64}$/.test(value.operationId)
+        && (value.status === 'pending'
+            || value.status === 'processing'
+            || value.status === 'completed')
+        && Number.isSafeInteger(value.itemCount)
+        && Number(value.itemCount) >= 1
+        && Number(value.itemCount) <= 100
+        && isNonnegativeSafeInteger(value.completedCount)
+        && Number(value.completedCount) <= Number(value.itemCount)
+        && isNonnegativeSafeInteger(value.failedCount)
+        && Number(value.failedCount) <= Number(value.completedCount)
+        && isIsoDateTime(value.expiresAt)
+        && isNonnegativeSafeInteger(value.pollAfterMs)
+        && Number(value.pollAfterMs) >= 100
+        && Number(value.pollAfterMs) <= 10_000;
+    if (!validBase) {
+        throw new ApiError('Invalid assignment operation response from the Agent API');
+    }
+    const isComplete = value.status === 'completed';
+    const resultsAreValid = isComplete
+        ? (Number(value.completedCount) === Number(value.itemCount)
+            && Array.isArray(value.results)
+            && value.results.length === Number(value.itemCount)
+            && value.results.every(isAssignmentOperationResult)
+            && value.results.filter((result) => result.status === 'failed').length
+                === Number(value.failedCount))
+        : value.results === undefined;
+    if (!resultsAreValid) {
+        throw new ApiError('Invalid assignment operation response from the Agent API');
+    }
+    return value;
+}
+export function toLegacyAssignmentResponse(value) {
+    const operation = parseAssignmentOperationResponse(value);
+    if (operation.status !== 'completed' || !operation.results) {
+        throw new ApiError('Assignment operation is not complete');
+    }
+    const succeeded = [];
+    const failed = [];
+    for (const result of operation.results) {
+        const { status, ...legacyResult } = result;
+        if (status === 'succeeded')
+            succeeded.push(legacyResult);
+        else
+            failed.push(legacyResult);
+    }
+    return { succeeded, failed };
+}
 function isHttpUrl(value) {
     if (typeof value !== 'string')
         return false;
@@ -591,6 +666,12 @@ function isBudgetCategory(value) {
         && Array.isArray(value.lineItems)
         && value.lineItems.every(isBudgetLineItem));
 }
+function isBudgetFunding(value) {
+    return value === null || (isObject(value)
+        && hasOnlyFields(value, ['toAssignPence', 'nextPeriodReservePence'])
+        && isSafeInteger(value.toAssignPence)
+        && isSafeInteger(value.nextPeriodReservePence));
+}
 function isBudgetResponse(value) {
     return (isObject(value)
         && hasOnlyFields(value, [
@@ -611,15 +692,11 @@ function isBudgetResponse(value) {
         && 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)))
+        && isBudgetFunding(value.funding)
         && Array.isArray(value.categories)
         && value.categories.every(isBudgetCategory));
 }
-function isBudgetStatusResponse(value) {
+function isLegacyBudgetStatusResponse(value) {
     if (!isObject(value)
         || !hasOnlyFields(value, [
             'scope',
@@ -640,11 +717,7 @@ function isBudgetStatusResponse(value) {
         && 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)))
+        && isBudgetFunding(value.funding)
         && isObject(value.activity)
         && hasOnlyFields(value.activity, [
             'startDate',
@@ -681,6 +754,82 @@ function isBudgetStatusResponse(value) {
             && Number.isSafeInteger(category.assignedPence - category.spentPence)
             && category.availablePence === category.assignedPence - category.spentPence)));
 }
+function isActivityAmounts(value) {
+    return isObject(value)
+        && hasOnlyFields(value, ['moneyInPence', 'moneyOutPence', 'netPence'])
+        && isNonnegativeSafeInteger(value.moneyInPence)
+        && isNonnegativeSafeInteger(value.moneyOutPence)
+        && isSafeInteger(value.netPence)
+        && Number.isSafeInteger(value.moneyInPence - value.moneyOutPence)
+        && value.netPence === value.moneyInPence - value.moneyOutPence;
+}
+function isBudgetActivityStatusResponse(value) {
+    if (!isObject(value) || !hasOnlyFields(value, [
+        'scope', 'periodKey', 'periodStatus', 'currency', 'period', 'refresh', 'activity', 'budget',
+    ]))
+        return false;
+    if (!isObject(value.period) || !hasOnlyFields(value.period, [
+        'startDate', 'endDate', 'dateRangeSource',
+    ]))
+        return false;
+    if (!isObject(value.activity) || !hasOnlyFields(value.activity, [
+        'transactionCount', 'categories', 'uncategorized',
+    ]))
+        return false;
+    const activityCategories = value.activity.categories;
+    if (!Array.isArray(activityCategories) || !activityCategories.every((category) => (isObject(category)
+        && hasOnlyFields(category, ['id', 'name', 'moneyInPence', 'moneyOutPence', 'netPence'])
+        && typeof category.id === 'string'
+        && category.id.trim().length > 0
+        && typeof category.name === 'string'
+        && category.name.trim().length > 0
+        && isActivityAmounts({
+            moneyInPence: category.moneyInPence,
+            moneyOutPence: category.moneyOutPence,
+            netPence: category.netPence,
+        }))))
+        return false;
+    const budget = value.budget;
+    if (budget !== null && (!isObject(budget)
+        || !hasOnlyFields(budget, ['effectiveFromPeriodKey', 'funding', 'categories'])
+        || typeof budget.effectiveFromPeriodKey !== 'string'
+        || !/^\d{4}-(0[1-9]|1[0-2])$/.test(budget.effectiveFromPeriodKey)
+        || !isBudgetFunding(budget.funding)
+        || !Array.isArray(budget.categories)
+        || !budget.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))))
+        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' || value.periodStatus === 'historical')
+        && isCurrency(value.currency)
+        && isIsoDate(value.period.startDate)
+        && isIsoDate(value.period.endDate)
+        && value.period.startDate <= value.period.endDate
+        && (value.period.dateRangeSource === 'stored'
+            || value.period.dateRangeSource === 'legacy_settings_fallback')
+        && isNonnegativeSafeInteger(value.activity.transactionCount)
+        && isActivityAmounts(value.activity.uncategorized)
+        && (value.periodStatus === 'historical'
+            ? value.refresh === null
+            : isRefreshStatus(value.refresh));
+}
+function isBudgetStatusResponse(value) {
+    return isLegacyBudgetStatusResponse(value) || isBudgetActivityStatusResponse(value);
+}
 function isBudgetMovementResponse(value) {
     return (isObject(value)
         && hasOnlyFields(value, [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slothmoney/agent-cli",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Command-line access to the Sloth Money Agent API.",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
     "test": "vitest run",
     "test:package": "node scripts/test-package.mjs",
     "test:registry": "node scripts/test-registry-package.mjs",
+    "release:preflight": "node scripts/release-preflight.mjs",
     "typecheck": "tsc --noEmit",
     "verify": "npm run lint && npm run typecheck && npm test && npm run build && npm run test:package"
   },