@slothmoney/agent-cli 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 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
@@ -765,8 +779,10 @@ 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
 

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.17.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',
@@ -654,13 +657,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 +711,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.',
@@ -1407,6 +1416,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 +1544,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 +1989,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;
         }

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;

package/package.json

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