List cash scope by account type
well_list_cash_scopeList the account types a reader can count as cash, each with what it holds. This is what the cash-scope card offers; it measures nothing well_list_account_balances did not already read.
Each entry in groups is one account type: account_type, account_count, and subtotals — one native amount per currency, never converted and never blended. Sorted with the largest holdings first, so the biggest decision reads first. A type with no accounts is NOT listed: counting it would change nothing, so it is not a choice.
Only accounts the workspace owns are folded here. Ownership is settled by a fact about the account, not by a preference, so it is never offered as a choice on this card. excluded_not_owned counts what that removed, and unsettled_ownership counts accounts whose owner is unanswered — those are NOT in any group, and a non-zero count means the reader has a repair to do before any total is trustworthy. Say it rather than presenting the groups as the whole picture.
unreadable_balances counts owned accounts whose stored balance could not be read at all; unreadable_currency counts those carrying an amount with no currency code anywhere. Both are in no subtotal, so state them beside any figure rather than presenting one that silently skipped them — and keep them apart, because they are different repairs: a balance that did not arrive against a row that arrived incomplete.
folded_duplicates counts rows left out because they are a second copy of an account already listed, synced once per connector. They are in no group and no count, since the account they copy is counted once. unlinked_accounts counts rows left out for the same reason by judgment rather than by duplicate collapse: a proven cross-source mirror or a bound alias of an account whose balance is already counted.
partial: true means the underlying read was cut short before it returned anything, so groups is empty and nothing is known about what the workspace holds. Say the read was cut short and offer to try again, rather than presenting an empty list as a decision.
offered_account_types lists every type this card offers now. stored_choice is an answer a board block stored for this card: pass the block's binding.scope when it carries both counted_account_types and offered_account_types, and omit it otherwise. reuse_stored_choice: true means no type is new since that answer: apply the stored counted_account_types as they stand, and wait for nothing, because the card asks nothing. reuse_stored_choice: false beside a stored choice means new_options names a type the reader never judged: the card shows the stored answer ticked and gives each new type the card's own default, and the answer is awaited as on a first run.
The card records the reader's answer in this session, so wait for it unless the stored choice was reused: call well_wait_for_selection({ kind: "cash_scope" }) in the SAME turn, and read selection.counted_account_types. An EMPTY array there is the answer "nothing is cash" — a resolution that ends the run, never a zero total. Do not settle the scope yourself: on a workspace holding more than one type that is the figure decided on the reader's behalf. A card listing no type at all asks nothing and carries no wait. Once the answer is in, YOU apply it when you total the balances, then call well_render_cash_position with the types you counted in scope.account_types.
When the token authorizes one workspace, call this directly — no workspace call is needed first. When it authorizes several, this read will not guess which one you mean: pass workspace_id on the call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which. | |
| stored_choice | No | The answer a board block stored for this card: the block's `binding.scope`. Omit it outside a board run. | |
| conversation_id | No | The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation. | |
| workspace_scope | No | Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| groups | Yes | ||
| partial | Yes | ||
| success | Yes | ||
| next_step | No | What to do with the card this result renders. Added by the dispatcher when the card asks for a click. | |
| pre_ticked | Yes | The options the card starts with ticked. | |
| new_options | Yes | Options listed now that the stored choice did not offer. Empty when no stored choice was passed. Name each one when the card is shown for it. | |
| conversation_id | No | The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation. | |
| newly_connected | No | Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later. | |
| folded_duplicates | Yes | ||
| unlinked_accounts | Yes | ||
| excluded_not_owned | Yes | ||
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| reuse_stored_choice | Yes | True when a stored choice was passed, the read completed, and no option is new. Apply the stored choice as it stands: the card asks nothing and no wait is owed on it. | |
| unreadable_balances | Yes | ||
| unreadable_currency | Yes | ||
| unsettled_ownership | Yes | ||
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| offered_account_types | Yes | Every account type this card offers now, in the order it lists them. The card records it beside the reader's answer, so a board block can store the two together. | |
| conversation_id_source | No | Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened. |