@slothmoney/agent-cli 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+- Add the read-only `sloth-agent accounts` command with strict runtime
+  validation for opaque references, ownership, native balances, sources, and
+  freshness metadata.
+- Prepare 0.4.0 by removing the obsolete `joint-budget-settings` command. Shared
+  personal transactions now enter the joint budget through their assignment.
+- Verify each trusted npm release from a fresh temporary directory so the
+  registry smoke test cannot resolve a repository-local CLI executable.
+
+## 0.3.1 - 2026-07-31
+
+- Coordinate transaction reads with the Sloth Budget daily refresh process.
+- Wait up to 45 seconds for fresh persisted data, then return readable cached
+  transactions with structured refresh status when work continues or fails.
+- Validate the additive transaction refresh response contract.
+
 ## 0.3.0 - 2026-07-30
 
 - Add command-specific help for every command and auth subcommand, including

package/README.md

@@ -1,6 +1,6 @@
 # Sloth Agent CLI
 
-Use your own agent to manage goals and categorise transactions through the
+Use your own agent to inspect known accounts, manage goals, 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.3.0 -- sloth-agent --help
+npm exec --yes --package=@slothmoney/agent-cli@0.4.0 -- sloth-agent --help
 ```
 
 ## Authenticate
@@ -96,10 +96,10 @@ options, output, and examples:
 
 ```bash
 sloth-agent auth login --help
+sloth-agent accounts --help
 sloth-agent categories --help
 sloth-agent transactions --help
 sloth-agent assign --help
-sloth-agent joint-budget-settings --help
 sloth-agent goals create --help
 sloth-agent goals update --help
 sloth-agent ask-partner --help
@@ -174,6 +174,20 @@ query. Assignments do not create a separate list.
 
 ### Other workflows
 
+Read the existing Sloth account inventory:
+
+```bash
+sloth-agent accounts
+```
+
+The command is read-only and cache-only: it does not refresh linked banks or
+change account data. Each result contains an opaque `accountRef`, personal or
+joint ownership, connected or manual source, native balance/currency when
+known, `lastBalanceUpdatedAt`, and `connectionState`. Missing values are JSON
+`null`; currencies are never converted or combined. Partner personal accounts
+are excluded, while enabled shared joint accounts follow Sloth's existing
+visibility rules.
+
 List your goals:
 
 ```bash
@@ -221,19 +235,35 @@ Read uncategorised contributions to the joint budget:
 sloth-agent transactions --assignment-scope joint --uncategorized
 ```
 
+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
+fails, or fails globally, readable cached transactions are still returned with
+a structured `refresh` object:
+
+```json
+{
+  "refresh": {
+    "status": "in_progress",
+    "reason": "wait_timeout",
+    "utcDate": "2026-07-31"
+  }
+}
+```
+
+Re-run the transaction query later to observe the completed refresh. A partial
+account failure remains eligible for an automatic retry.
+
 Set `"assignmentScope": "joint"` on an assignment to categorise the eligible
 shared portion for the joint budget.
 
-Set whether the shared portions of personal-account transactions count in the
-linked joint budget. The first command previews; the second applies:
+Transaction reads expose `personalBudgetAmountPence` for the caller's explicit
+personal-only portion and `jointBudgetContribution.amountPence` for the full
+shared portion. The 60/40 settlement ratio does not reduce joint-budget spend.
 
-```bash
-sloth-agent joint-budget-settings \
-  --include-shared-personal-transactions=true
-sloth-agent joint-budget-settings \
-  --include-shared-personal-transactions=true \
-  --apply
-```
+Shared personal-account transactions with a joint assignment are included in
+the joint budget automatically. The settlement ratio remains independent from
+the amount attributed to the joint budget.
 
 Create a partner clarification link:
 
@@ -277,3 +307,15 @@ npm run verify
 
 `npm run test:package` packs the exact npm artifact, installs it into a clean
 temporary project, and runs the installed binary.
+
+## Releasing
+
+Releases are published only through the trusted `Publish npm release` GitHub
+workflow from a reviewed `v*` tag whose version matches `package.json`. The
+workflow runs the full verification suite before publishing.
+
+After npm accepts the package, the workflow verifies the exact published
+version with `npm run test:registry -- VERSION`. That script runs `npm exec`
+from a fresh temporary directory with an isolated npm cache, so a checkout's
+older local `sloth-agent` executable cannot satisfy the registry smoke test.
+The temporary directory is removed after the check.

package/dist/args.js

@@ -411,10 +411,10 @@ function helpTopic(argv) {
             return 'goals-delete';
         return 'goals';
     }
-    if (command === 'categories'
+    if (command === 'accounts'
+        || command === 'categories'
         || command === 'transactions'
         || command === 'assign'
-        || command === 'joint-budget-settings'
         || command === 'ask-partner') {
         return command;
     }
@@ -443,6 +443,12 @@ export function parseArgs(argv) {
         }
         return withBaseUrl({ command }, baseUrl);
     }
+    if (command === 'accounts') {
+        if (args.length > 0) {
+            throw new UsageError(`Unknown accounts option: ${args[0]}`);
+        }
+        return withBaseUrl({ command }, baseUrl);
+    }
     if (command === 'transactions') {
         return withBaseUrl({ command, filters: parseTransactions(args) }, baseUrl);
     }
@@ -471,43 +477,6 @@ export function parseArgs(argv) {
             throw new UsageError('assign requires --input <file>');
         return withBaseUrl({ command, input, apply }, baseUrl);
     }
-    if (command === 'joint-budget-settings') {
-        let includeSharedPersonalTransactions;
-        let apply = false;
-        for (let index = 0; index < args.length; index += 1) {
-            const argument = args[index];
-            if (argument === '--apply') {
-                if (apply)
-                    throw new UsageError('--apply may only be provided once');
-                apply = true;
-                continue;
-            }
-            const optionName = '--include-shared-personal-transactions';
-            if (argument === optionName || argument.startsWith(`${optionName}=`)) {
-                const value = argument === optionName
-                    ? readOptionValue(args, index, optionName)
-                    : argument.slice(`${optionName}=`.length);
-                if (argument === optionName)
-                    index += 1;
-                if (value !== 'true' && value !== 'false') {
-                    throw new UsageError(`${optionName} must be true or false`);
-                }
-                includeSharedPersonalTransactions = setOnce(includeSharedPersonalTransactions, value === 'true', optionName);
-                continue;
-            }
-            throw new UsageError(`Unknown joint-budget-settings option: ${argument}`);
-        }
-        if (apply && includeSharedPersonalTransactions === undefined) {
-            throw new UsageError('--apply requires --include-shared-personal-transactions=true|false');
-        }
-        return withBaseUrl({
-            command,
-            ...(includeSharedPersonalTransactions === undefined
-                ? {}
-                : { includeSharedPersonalTransactions }),
-            apply,
-        }, baseUrl);
-    }
     if (command === 'ask-partner') {
         let transactionRef;
         for (let index = 0; index < args.length; index += 1) {

package/dist/cli.js

@@ -1,10 +1,10 @@
 import fs from 'node:fs';
 import { parseArgs, resolveBaseUrl, } from './args.js';
-import { parseApiResponse, validateAssignmentPayload, validateJointBudgetSettingsResponse, } from './contracts.js';
+import { parseApiResponse, validateAssignmentPayload, } from './contracts.js';
 import { createSystemCredentialStore, secureStorageUnavailableError, } from './credential-store.js';
 import { ApiError, CliError, ConfigError, UsageError, } from './errors.js';
-export const CLI_VERSION = '0.3.0';
-const REQUEST_TIMEOUT_MS = 30_000;
+export const CLI_VERSION = '0.4.0';
+const REQUEST_TIMEOUT_MS = 60_000;
 const API_ORIGIN_HELP_LINES = [
     '',
     'API origin:',
@@ -24,12 +24,12 @@ export function usageText() {
         '  sloth-agent auth login [--token-stdin | --from-env] [--base-url URL]',
         '  sloth-agent auth status [--base-url URL]',
         '  sloth-agent auth logout [--base-url URL]',
+        '  sloth-agent accounts [--base-url URL]',
         '  sloth-agent categories [--base-url URL]',
         '  sloth-agent transactions [--uncategorized[=true|false]] [--limit N]',
         '    [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--q TEXT]',
         '    [--account-id ID] [--category-id ID] [--cursor CURSOR] [--base-url URL]',
         '  sloth-agent assign --input assignments.json [--apply] [--base-url URL]',
-        '  sloth-agent joint-budget-settings [--include-shared-personal-transactions=true|false] [--apply]',
         '  sloth-agent goals [list] [--base-url URL]',
         '  sloth-agent goals create --name NAME [--target-amount AMOUNT]',
         '    [--target-month YYYY-MM] [--apply] [--base-url URL]',
@@ -182,6 +182,31 @@ export function categoriesHelpText() {
         '  jointLineItemsByCategoryId       Joint child line items keyed by category ID',
     ].join('\n');
 }
+export function accountsHelpText() {
+    return [
+        'Sloth Agent CLI — accounts',
+        '',
+        'Read the existing Sloth account inventory known to the authenticated user.',
+        '',
+        'Usage:',
+        '  sloth-agent accounts [--base-url URL]',
+        '',
+        'Options:',
+        '  --base-url URL   Optional. Override the API origin.',
+        '  -h, --help       Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Access:',
+        '  This command is read-only and does not refresh connected accounts.',
+        '',
+        'Output:',
+        '  asOf                   Server response time',
+        '  accounts[].accountRef  Opaque stable account reference',
+        '  accounts[].ownership   personal or joint',
+        '  accounts[].balanceAmount and currency in the native currency when known',
+        '  accounts[].connectionState and lastBalanceUpdatedAt for freshness',
+    ].join('\n');
+}
 export function transactionsHelpText() {
     return [
         'Sloth Agent CLI — transactions',
@@ -208,10 +233,14 @@ export function transactionsHelpText() {
         'Constraints:',
         '  All filters are omitted by default.',
         '  --end-date must not be before --start-date.',
-        '  This command is read-only.',
+        '  The first transaction read each UTC day may refresh linked bank data.',
+        '  Refresh remotely persists booked transactions and account balances.',
+        '  The command waits up to 45 seconds, then returns cached data if refresh continues.',
         '',
         'Output:',
-        '  JSON containing transactions and nextCursor. Use nextCursor with --cursor',
+        '  JSON containing transactions, nextCursor, and structured refresh status.',
+        '  Refresh failures do not hide readable cached transactions.',
+        '  Use nextCursor with --cursor',
         '  to request the next page. A null nextCursor means there are no more pages.',
         '',
         'Examples:',
@@ -284,37 +313,6 @@ export function assignHelpText() {
         '  Assignments do not create a separate list.',
     ].join('\n');
 }
-export function jointBudgetSettingsHelpText() {
-    return [
-        'Sloth Agent CLI — joint-budget-settings',
-        '',
-        'Read or update whether shared personal transactions count in the linked joint budget.',
-        '',
-        'Usage:',
-        '  sloth-agent joint-budget-settings [options]',
-        '',
-        'Options:',
-        '  --include-shared-personal-transactions=true|false',
-        '                      Optional. Preview the linked setting change.',
-        '  --apply             Optional. Apply the previewed setting change.',
-        '  --base-url URL      Optional. Override the API origin.',
-        '  -h, --help          Show this help.',
-        ...API_ORIGIN_HELP_LINES,
-        '',
-        'Safety:',
-        '  With no setting option, the command is read-only.',
-        '  Without --apply, a setting option returns a dry-run preview and does not write.',
-        '  --apply requires an explicit true or false setting value.',
-        '',
-        'Examples:',
-        '  sloth-agent joint-budget-settings',
-        '  sloth-agent joint-budget-settings --include-shared-personal-transactions=true',
-        '  sloth-agent joint-budget-settings --include-shared-personal-transactions=true --apply',
-        '',
-        'Output:',
-        '  JSON containing the linked setting, audit metadata, or a dry-run payload.',
-    ].join('\n');
-}
 export function goalsHelpText() {
     return [
         'Sloth Agent CLI — goals',
@@ -485,10 +483,10 @@ export function commandHelpText(topic) {
         'auth-login': authLoginHelpText,
         'auth-status': authStatusHelpText,
         'auth-logout': authLogoutHelpText,
+        accounts: accountsHelpText,
         categories: categoriesHelpText,
         transactions: transactionsHelpText,
         assign: assignHelpText,
-        'joint-budget-settings': jointBudgetSettingsHelpText,
         goals: goalsHelpText,
         'goals-list': goalsListHelpText,
         'goals-create': goalsCreateHelpText,
@@ -843,36 +841,6 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             writeJson(writeStdout, data);
             return hasFailures(data) ? 1 : 0;
         }
-        if (parsed.command === 'joint-budget-settings') {
-            const endpoint = `${baseUrl}/api/agent/v1/joint-budget-settings`;
-            if (parsed.includeSharedPersonalTransactions !== undefined && !parsed.apply) {
-                writeJson(writeStdout, {
-                    dryRun: true,
-                    endpoint,
-                    payload: {
-                        includeSharedPersonalTransactions: parsed.includeSharedPersonalTransactions,
-                    },
-                });
-                return 0;
-            }
-            const response = await fetchImplementation(endpoint, {
-                method: parsed.apply ? 'PUT' : 'GET',
-                headers: parsed.apply
-                    ? { ...headers, 'Content-Type': 'application/json' }
-                    : headers,
-                ...(parsed.apply
-                    ? {
-                        body: JSON.stringify({
-                            includeSharedPersonalTransactions: parsed.includeSharedPersonalTransactions,
-                        }),
-                    }
-                    : {}),
-                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-            });
-            const data = validateJointBudgetSettingsResponse(await parseHttpResponse(response, token));
-            writeJson(writeStdout, data);
-            return 0;
-        }
         if (parsed.command === 'ask-partner') {
             const response = await fetchImplementation(`${baseUrl}/api/agent/v1/transaction-explanation-requests`, {
                 method: 'POST',
@@ -897,15 +865,19 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             writeJson(writeStdout, data);
             return 0;
         }
-        const path = parsed.command === 'categories'
-            ? '/api/agent/v1/categories'
-            : `/api/agent/v1/transactions${(() => {
-                const query = buildTransactionsQuery(parsed.filters);
-                return query ? `?${query}` : '';
-            })()}`;
+        const path = parsed.command === 'accounts'
+            ? '/api/agent/v1/accounts'
+            : parsed.command === 'categories'
+                ? '/api/agent/v1/categories'
+                : `/api/agent/v1/transactions${(() => {
+                    const query = buildTransactionsQuery(parsed.filters);
+                    return query ? `?${query}` : '';
+                })()}`;
         const response = await fetchImplementation(`${baseUrl}${path}`, {
             method: 'GET',
-            headers,
+            headers: parsed.command === 'transactions'
+                ? { ...headers, Prefer: 'wait=45' }
+                : headers,
             signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
         });
         const data = parseApiResponse(parsed.command, await parseHttpResponse(response, token));

package/dist/contracts.js

@@ -2,6 +2,12 @@ import { ApiError, UsageError, } from './errors.js';
 function isObject(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
+function isIsoDate(value) {
+    if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const parsed = new Date(`${value}T00:00:00.000Z`);
+    return !Number.isNaN(parsed.valueOf()) && parsed.toISOString().slice(0, 10) === value;
+}
 function requireObject(value, label) {
     if (!isObject(value))
         throw new UsageError(`${label} must be an object`);
@@ -139,6 +145,8 @@ function isTransaction(value) {
         && (value.categoryId === null || typeof value.categoryId === 'string')
         && (value.lineItemId === null || typeof value.lineItemId === 'string')
         && Array.isArray(value.categorySplits)
+        && Number.isInteger(value.personalBudgetAmountPence)
+        && Number(value.personalBudgetAmountPence) >= 0
         && (value.jointBudgetContribution === null
             || (isObject(value.jointBudgetContribution)
                 && typeof value.jointBudgetContribution.eligible === 'boolean'
@@ -158,10 +166,27 @@ function isTransaction(value) {
             || value.incomeSubtype === 'interest'));
 }
 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'));
+        && (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));
 }
 function isAssignmentResponse(value) {
     return (isObject(value)
@@ -174,20 +199,6 @@ function isAssignmentResponse(value) {
             && typeof item.error === 'string'
             && (item.transactionRef === undefined || typeof item.transactionRef === 'string'))));
 }
-export function validateJointBudgetSettingsResponse(value) {
-    if (!isObject(value)
-        || Object.keys(value).some((key) => !new Set([
-            'includeSharedPersonalTransactions',
-            'updatedAt',
-            'updatedBy',
-        ]).has(key))
-        || typeof value.includeSharedPersonalTransactions !== 'boolean'
-        || (value.updatedAt !== null && !isIsoDateTime(value.updatedAt))
-        || (value.updatedBy !== null && typeof value.updatedBy !== 'string')) {
-        throw new ApiError('Invalid joint budget settings response from the Agent API');
-    }
-    return value;
-}
 function isHttpUrl(value) {
     if (typeof value !== 'string')
         return false;
@@ -243,6 +254,51 @@ function isGoal(value) {
 function isCurrency(value) {
     return typeof value === 'string' && /^[A-Z]{3}$/.test(value);
 }
+function isNullableNonEmptyString(value) {
+    return value === null || (typeof value === 'string'
+        && value.length > 0
+        && value === value.trim());
+}
+function isAccount(value) {
+    return (isObject(value)
+        && hasOnlyFields(value, [
+            'accountRef',
+            'accountName',
+            'institutionName',
+            'accountType',
+            'ownership',
+            'balanceAmount',
+            'currency',
+            'source',
+            'lastBalanceUpdatedAt',
+            'connectionState',
+        ])
+        && typeof value.accountRef === 'string'
+        && /^sloth_account_v1_[A-Za-z0-9_-]{43}$/.test(value.accountRef)
+        && isNullableNonEmptyString(value.accountName)
+        && isNullableNonEmptyString(value.institutionName)
+        && (value.accountType === 'current'
+            || value.accountType === 'savings'
+            || value.accountType === 'investments')
+        && (value.ownership === 'personal' || value.ownership === 'joint')
+        && (value.balanceAmount === null
+            || (typeof value.balanceAmount === 'number' && Number.isFinite(value.balanceAmount)))
+        && (value.currency === null || isCurrency(value.currency))
+        && (value.source === 'connected' || value.source === 'manual')
+        && (value.lastBalanceUpdatedAt === null
+            || isIsoDateTime(value.lastBalanceUpdatedAt))
+        && (value.connectionState === 'active'
+            || value.connectionState === 'expired'
+            || value.connectionState === 'manual'
+            || value.connectionState === 'unknown'));
+}
+function isAccountsResponse(value) {
+    return (isObject(value)
+        && hasOnlyFields(value, ['asOf', 'accounts'])
+        && isIsoDateTime(value.asOf)
+        && Array.isArray(value.accounts)
+        && value.accounts.every(isAccount));
+}
 function isGoalsResponse(value) {
     return (isObject(value)
         && hasOnlyFields(value, ['currency', 'goals'])
@@ -264,19 +320,21 @@ function isGoalDeleteResponse(value) {
         && value.deletedGoalId.trim().length > 0);
 }
 export function parseApiResponse(command, value) {
-    const valid = command === 'categories'
-        ? isCategoryResponse(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);
+    const valid = command === 'accounts'
+        ? isAccountsResponse(value)
+        : command === 'categories'
+            ? isCategoryResponse(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.3.0",
+  "version": "0.4.0",
   "description": "Command-line access to the Sloth Money Agent API.",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "prepack": "npm run build",
     "test": "vitest run",
     "test:package": "node scripts/test-package.mjs",
+    "test:registry": "node scripts/test-registry-package.mjs",
     "typecheck": "tsc --noEmit",
     "verify": "npm run lint && npm run typecheck && npm test && npm run build && npm run test:package"
   },