bkper 5.6.0 → 5.7.0

package/lib/docs/ai/decision-models.md

@@ -37,7 +37,7 @@ Confidence is high when the model's probability concentrates on one answer. For
 
 2. **Let code gather the facts.**
 
-    Code fetches the item and the context a person would need, such as nearby Transactions, how an Account is usually described, or Book and Account properties. Pass them as named fields, such as `bank_line` and `existing_transaction`. Decision models read text only, so convert files and images to text first.
+    Code fetches the item and the context a person would need, such as nearby Transactions, how an Account is usually described, or Book and Account properties. Pass them as named fields, such as `bank_line` and `existing_transaction`. Facts can also be images, such as a receipt photo. Convert PDFs and other files to text or images first.
 
 3. **Ask narrow questions.**
 
@@ -141,7 +141,8 @@ For more designs, see TypeSafe's [Patterns](https://docs.typesafe.ai/patterns) a
 [Jev](https://docs.typesafe.ai/introduction) is TypeSafe's flagship model and the first System One model. Its Bkper model ID is `jev`.
 
 - **Versions.** `jev-latest` and versioned IDs are accepted but always select the current Jev; you cannot pin a version. Log the revision each answer reports, and re-check tuned thresholds when it changes.
-- **Input.** Text only. English is Jev's primary training language; other languages work with lower accuracy.
+- **Input.** Text and images. English is Jev's primary training language; other languages work with lower accuracy.
+- **Images.** An experimental TypeSafe feature, so accuracy and limits can change. Send PNG or JPEG images between 280 and 1568 pixels per side as base64 `assets` in a JSON request; TypeSafe's SDKs upload images in a form Bkper AI does not accept. Image tokens count as input. See TypeSafe's [Images](https://docs.typesafe.ai/images) guide.
 - **Known weak spots.** Literal reading, arithmetic, date comparison, and large states full of irrelevant detail. See [Jev 1.13 jaggedness](https://docs.typesafe.ai/model-jaggedness/jev-1.13).
 
 Requests count against your Bkper AI allowance at Jev's [usage rates](https://bkper.com/docs/ai/models.md#usage-rates).

package/lib/docs/api/ai-gateway.md

@@ -262,6 +262,7 @@ Decision models come from TypeSafe's [System One](https://docs.typesafe.ai/conce
 - **SDKs.** TypeSafe SDKs work with base URL `https://ai.bkper.app`, without `/v1`, and a Bkper access token. See [Add Bkper AI to an App](https://bkper.com/docs/platform/apps/ai#ask-a-decision-model).
 - **Errors.** Bkper returns `400` where TypeSafe returns `422`, and `503` with `provider_overloaded` where TypeSafe returns `529`. A `429` can also mean the Bkper AI allowance is exhausted.
 - **Usage.** Requests count against the Bkper AI allowance, not a TypeSafe account.
+- **Images.** Send images as base64 `assets` in a JSON request, as in TypeSafe's [Images](https://docs.typesafe.ai/images) guide. TypeSafe SDKs upload images as multipart, which Bkper does not accept, so send image requests over HTTP. Bkper turns on TypeSafe's experimental image input for you. Box questions are not supported. Image tokens count as input tokens.
 - **Coding agents.** TypeSafe's [agent skill](https://docs.typesafe.ai/agent-skill) teaches questions and patterns. For a Bkper integration, also point the agent to this guide, `https://bkper.com/docs/api/ai-gateway.md`, for the endpoint, authentication, model IDs, and errors.
 
 ## Stream a response

package/lib/docs/api/managed-agent.md

@@ -7,14 +7,14 @@ The Managed Agent API lets you build intelligent apps on Bkper's agent: a privat
 Build, for example:
 
 - a Bkper platform app with its own chat, in a Book or on its own page;
-- a chat bot for Slack, Teams, or Discord, with one session per thread;
+- a chat bot for Slack, Teams, or Discord, with one session per thread and each message's sender in its `attributes`;
 - a scheduled script that asks for a monthly report and saves the file.
 
-Sessions belong to the user, not the app: work started in one app continues in any other, including [Bkper Agent](https://bkper.com/docs/ai/bkper-agent), the agent in Bkper's Books. Bkper Agent is built only on this API and is its reference implementation. Usage counts against the user's Bkper AI allowance; see [Models and Usage](https://bkper.com/docs/ai/models). To call models directly, without an agent or workspace, use the [AI Gateway API](https://bkper.com/docs/api/ai-gateway). Building a Bkper app? Start with [Add Bkper AI to an App](https://bkper.com/docs/platform/apps/ai).
+Each app has its own workspace for each user: its sessions, files, and sandbox stay apart from that user's other apps and from [Bkper Agent](https://bkper.com/docs/ai/bkper-agent), the agent in Bkper's Books. Calls with a plain Bkper token, such as from a script, work in the user's own workspace, which Bkper Agent shows. Bkper Agent is built only on this API and is its reference implementation. Usage counts against the user's Bkper AI allowance; see [Models and Usage](https://bkper.com/docs/ai/models). To call models directly, without an agent or workspace, use the [AI Gateway API](https://bkper.com/docs/api/ai-gateway). Building a Bkper app? Start with [Add Bkper AI to an App](https://bkper.com/docs/platform/apps/ai).
 
 ## Requirements
 
-- A Bkper account with an email address. Accounts not admitted to the beta get 403 `agent_beta_required`.
+- A Bkper account with an email address.
 - A Bkper OAuth access token for the user the agent acts as. [Bkper platform apps](https://bkper.com/docs/platform/apps/overview) need none: call the API from the app's server, and the platform adds the user's credentials, as it does for Bkper AI.
 - A server, bot, or script to call the API. Browsers on other websites are refused: the API sends no CORS headers and rejects cross-origin writes with 403 `origin_forbidden`.
 
@@ -80,7 +80,7 @@ The agent receives, in order:
 
 1. **Bkper's base**: the workspace, Bkper's accounting model, and rules no interface can relax.
 2. **Your `instructions`.**
-3. **Each message**, with its optional `bookContext` as labeled information, never as instructions or permission.
+3. **Each message**, with its optional `bookContext` and `attributes` as labeled information, never as instructions or permission.
 4. **Each message's attached files**, copied into the workspace and listed with their paths as labeled information.
 
 There is no default. Without `instructions`, the agent follows only Bkper's base, which does not ask anyone before acting. Bkper Agent sends its own instructions, so it asks questions and makes only the changes it is asked for; your interface decides its own.
@@ -109,7 +109,17 @@ the totals you checked.
 
 ## Who the agent acts as
 
-Every request acts as the user whose token you send. That user's Book permissions, sessions, files, and Bkper AI allowance apply. Their sessions appear in their Bkper Agent too.
+Every request acts as the user whose token you send. That user's Book permissions and Bkper AI allowance apply.
+
+The workspace (sessions, files, and sandbox) depends on who calls. Bkper sets the app from the platform side, never from the request:
+
+| Caller | Workspace |
+| --- | --- |
+| Bkper Agent, or a script or CLI with a plain Bkper token | The user's own |
+| A [Bkper platform app](https://bkper.com/docs/platform/apps/overview) calling from its server | The user's, for that app |
+| A Bkper channel bot, such as a Slack bot | The bot's account, for that bot |
+
+Book changes made in an app's workspace are attributed to that app, with its name and logo.
 
 - **Personal tools**: use each person's own token, so each person sees only their Books.
 - **Shared channel bots**: everyone in the channel acts with the bot's account. Use a dedicated Bkper account, shared only on the Books the channel needs, with the lowest permission that does the job.
@@ -145,6 +155,23 @@ Every create, input, and upload request needs an `Idempotency-Key` of 1–128 le
 
 Send `bookContext: { "bookId": "…", "query": "…" }` with an input when the message is about a Book. Bkper checks the user's access when the agent opens the Book.
 
+### Message attributes
+
+Send `attributes` with an input for what the agent should know about the message but the person did not type: who sent it, from which channel, or the thread messages before it. They are strings by name:
+
+```json
+{
+  "content": [{ "type": "text", "text": "suggest an answer here" }],
+  "attributes": {
+    "sender": "Alice (U0123)",
+    "channel": "#finance",
+    "thread": "Bob: can we pay the March invoice from Acme?"
+  }
+}
+```
+
+The agent receives them after the message as labeled information, never as instructions or permission: identity comes only from the token. The input and the user's entry keep the text as sent, with `attributes` beside it. Send per-message context here rather than in `instructions`, which stay the same for every message.
+
 ### Forks
 
 Create a session with `parent` to continue from a point in another session:
@@ -263,10 +290,14 @@ async function agent(path: string, body?: unknown, key?: string) {
     return result;
 }
 
-type SlackEvent = { event_id: string; thread_ts: string; text: string };
+type SlackEvent = { event_id: string; thread_ts: string; text: string; user: string };
 
 export async function reply(event: SlackEvent): Promise<string> {
-    const input = { content: [{ type: 'text', text: event.text }] };
+    const input = {
+        content: [{ type: 'text', text: event.text }],
+        // Who wrote it, as information for the agent: everyone acts as the bot.
+        attributes: { sender: event.user },
+    };
     // The event ID is the key: a redelivered event arrives once.
     const key = event.event_id;
     let id = sessions.get(event.thread_ts);
@@ -313,6 +344,7 @@ Acknowledge each Slack event at once and post the reply when `reply` returns: Sl
 | File retention | 30 days after creation |
 | `instructions` | 16,000 characters |
 | `bookContext.query` | 4,000 characters |
+| `attributes` | 16 names, 16000 characters in total |
 | List page | 50 sessions, entries, or files |
 
 ## Errors
@@ -323,7 +355,7 @@ Errors are `{ "error": { "code", "type", "message" } }`. Branch on `code`.
 | --- | --- | --- |
 | 400 | `invalid_request`, `unknown_model`, `unknown_thinking_level` | A field is invalid or unknown |
 | 401 | `unauthorized`, `authentication_failed` | The token is missing, invalid, or expired |
-| 403 | `agent_beta_required` | The account is not admitted to the beta |
+| 403 | `agent_beta_required` | The account cannot use the agent, such as one without an email address |
 | 403 | `origin_forbidden` | A browser on another website sent a write |
 | 404 | `not_found`, `parent_not_found`, `file_not_found` | No such resource for this user |
 | 405 | `method_not_allowed` | The path does not support the method |

package/lib/docs/apps/ai.md

@@ -183,6 +183,7 @@ Map these errors to your route's typed error response. Keep the code and message
 
 - **Passing your own `fetch`.** The TypeSafe SDK calls `fetch` as its own method, which the Workers runtime rejects with `Illegal invocation`. Wrap it: `fetch: (input, init) => myFetch(input, init)`. Without the option, the SDK's default works.
 - **No `null` values.** The TypeSafe SDK's types accept `null` for state, instructions, and some criteria. Bkper AI rejects them with `400`.
+- **No SDK image uploads.** The TypeSafe SDK uploads images as multipart, which Bkper AI rejects with `400`. Send image requests with `fetch` as JSON, with base64 `assets`. See [Decision Models](https://bkper.com/docs/ai/decision-models.md#jev-by-typesafe).
 - **No `client.models.list()`.** It expects TypeSafe's catalog shape. Use the [`GET /v1/models`](https://ai.bkper.app/v1/models) catalog.
 - **Other System One clients** take `https://ai.bkper.app/v1` as their base URL.
 - **Flexible JSON schemas.** Open Responses always requests `strict: true`. For a schema that needs `strict: false`, such as a typed dynamic map, use `@ai-sdk/openai` with base URL `https://ai.bkper.app/v1`, its `.responses()` model, and `strictJsonSchema: false`.

package/lib/docs/apps/context-menu.md

@@ -92,15 +92,12 @@ window.addEventListener('message', event => {
         return;
     }
 
-    // Keep the iframe URL in sync without reloading it.
-    window.history.replaceState(window.history.state, '', nextUrl);
-
     // Apply the validated context update.
     handleAppUrlChange(nextUrl);
 });
 ```
 
-`handleAppUrlChange` is App logic. The App can update internal state, notify components, refresh data, change its UI, or ignore the message. Bkper only communicates the new URL; it does not reload the iframe or apply the context inside the App.
+`handleAppUrlChange` is App logic, best in the module that [owns the URL](https://bkper.com/docs/platform/apps/quality.md#client-state): it takes the Book's context, keeps the App's own state, such as its selection, and replaces the URL without reloading. The App can update internal state, notify components, refresh data, change its UI, or ignore the message. Bkper only communicates the new URL; it does not reload the iframe or apply the context inside the App.
 
 Apps opened with `NEW_TAB` do not receive this message. Their context is set only by the URL used to open the tab.
 

package/lib/docs/apps/quality.md

@@ -61,10 +61,10 @@ Split a module when unrelated behavior changes for different reasons or when mix
 Start every client with this structure, so it grows by adding pieces instead of restructuring:
 
 - **Stores hold shared state.** Anything another component or the URL could care about, such as loaded data, the selection, or errors, lives in a store under `client/src/state/`, one per concern. A store holds its data and the actions that change it, announces changes, and never touches the DOM.
-- **Components render and report intent.** A component watches the stores it shows and changes them only through their actions. Only its own presentation, such as an open menu or hover, stays in the component. Each component owns its CSS.
+- **Components render and report intent.** A component watches only the stores it shows and changes them only through their actions, in response to the person, never while rendering. Only its own presentation, such as an open menu or hover, stays in the component. Each component owns its CSS.
 - **Stores ask the interface through events.** When a store needs the interface to act, such as focusing an input or scrolling to new content, it fires an event the component listens to. Stores never call components.
-- **One module wires the stores.** It creates them and gives each the stores it depends on. Dependencies point one way. A store changes another store only through that store's actions, and reactions that span stores live in this module.
-- **One module owns the URL.** Only it reads or writes the URL's path, query, and `history`, mapping the URL to state. Put in the URL what a person would reload or share, such as the selected item. Standalone, add a history entry per selection so Back works. Embedded in a Book, replace the URL so Back stays the Book's. Pass it the window so it can be tested.
+- **One module wires the stores.** It creates them and gives each the stores it depends on. Dependencies point one way. A store changes another store only through that store's actions, and reactions that span stores live in this module. Components get only the stores and actions they use; services stay inside this module.
+- **One module owns the URL.** Only it reads or writes the URL's path, query, and `history`, mapping the URL to state. Put in the URL what a person would reload or share, such as the selected item. Standalone, add a history entry for each place the person goes, so Back works; when a place becomes another, such as a new item once saved, replace its entry. Embedded in a Book, replace the URL so Back stays the Book's. Pass it the window so it can be tested.
 - **Split by concern, not by screen region.** Split a store or component when its parts change for different reasons.
 
 ## Security

package/lib/docs/cli/data-management.md

@@ -264,9 +264,6 @@ bkper transaction list -b abc123 -q 'on:2025' --limit 100
 # Fetch the next transaction page
 bkper transaction list -b abc123 -q 'on:2025' --limit 100 --cursor cursor_123
 
-# Count transactions without listing them
-bkper transaction count -b abc123 -q "account:'Capital' on:2025"
-
 # Update a transaction
 bkper transaction update tx_456 -b abc123 --amount 120.00 --description "Printer paper (corrected)"
 
@@ -289,6 +286,19 @@ bkper transaction untrash tx_456 -b abc123
 bkper transaction merge tx_123 tx_456 -b abc123
 ```
 
+### Counting transactions
+
+To answer how many transactions match, use `transaction count` (one call per account, group, or period), never `transaction list`. Queries include drafts: add `is:posted` for posted only. Trashed transactions are excluded unless `is:trashed`.
+
+```bash
+bkper transaction count -b abc123 -q "account:'Capital' on:2025 is:posted"  # {"count":N}
+bkper transaction count -b abc123 -q "group:'Equity' on:2025 is:posted"
+
+# Accounts directly in a group, to count per account
+GROUP_ID=$(bkper group get 'Equity' -b abc123 | jq -r '.id')
+bkper account list -b abc123 | jq -r --arg g "$GROUP_ID" '.items[] | select(any(.groups[]?; .id == $g)) | .name'
+```
+
 <details>
 <summary>Command reference</summary>
 
@@ -296,7 +306,7 @@ bkper transaction merge tx_123 tx_456 -b abc123
 -   `transaction list -b <bookId> -q <query>` - List transactions matching a query (auto-paginates through all results unless `--limit` or `--cursor` is provided)
     -   `--limit <number>` - Fetch one page with up to this many transactions
     -   `--cursor <cursor>` - Cursor for fetching the next page
--   `transaction count -b <bookId> [-q <query>]` - Count transactions matching a query, returning `{"count":N}`; counts all transactions when `-q` is omitted. Use this instead of `transaction list` whenever only the number of transactions is needed — one call per account/group/period is fast, while listing fetches every transaction
+-   `transaction count -b <bookId> [-q <query>]` - Count transactions matching a query, returning `{"count":N}`; counts all transactions when `-q` is omitted
 -   `transaction create -b <bookId>` - Create a transaction
     -   `--date <date>` - Transaction date
     -   `--amount <amount>` - Transaction amount

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bkper",
-    "version": "5.6.0",
+    "version": "5.7.0",
     "description": "Official Bkper CLI for accounting data, automation, apps, and AI agents",
     "bin": {
         "bkper": "lib/cli.js"
@@ -64,13 +64,13 @@
         "upgrade:api": "bun update @bkper/bkper-api-types --latest && bun update bkper-js --latest"
     },
     "dependencies": {
-        "@earendil-works/pi-agent-core": "1.2.0",
-        "@earendil-works/pi-ai": "1.2.0",
-        "@earendil-works/pi-codemode": "1.2.0",
-        "@earendil-works/pi-coding-agent": "1.2.0",
-        "@earendil-works/pi-mcp": "1.2.0",
-        "@earendil-works/pi-telemetry": "1.2.0",
-        "@earendil-works/pi-tui": "1.2.0",
+        "@earendil-works/pi-agent-core": "1.4.0",
+        "@earendil-works/pi-ai": "1.4.0",
+        "@earendil-works/pi-codemode": "1.4.0",
+        "@earendil-works/pi-coding-agent": "1.4.0",
+        "@earendil-works/pi-mcp": "1.4.0",
+        "@earendil-works/pi-telemetry": "1.4.0",
+        "@earendil-works/pi-tui": "1.4.0",
         "@silvia-odwyer/photon-node": "0.3.4",
         "bkper-js": "^2.45.1",
         "commander": "^13.1.0",