bkper 4.18.4 → 4.19.0

package/lib/commands/events/list.js

@@ -0,0 +1,160 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { getBkperInstance } from '../../bkper-factory.js';
+import { quoteShellArg } from '../../utils/shell-quote.js';
+export const DEFAULT_EVENT_LIST_LIMIT = 50;
+const PREVIEW_MAX_LENGTH = 80;
+/**
+ * Lists one page of events from a book.
+ *
+ * @param bookId - The book ID to query
+ * @param options - Filter and pagination options
+ * @returns Event page items and optional next cursor
+ */
+export function listEvents(bookId_1) {
+    return __awaiter(this, arguments, void 0, function* (bookId, options = {}) {
+        const bkper = getBkperInstance();
+        const book = yield bkper.getBook(bookId);
+        const listOptions = toListEventsOptions(options);
+        const result = yield book.listEvents(listOptions);
+        const page = {
+            items: result.getItems(),
+        };
+        const nextCursor = result.getCursor();
+        if (nextCursor) {
+            page.cursor = nextCursor;
+        }
+        return page;
+    });
+}
+/**
+ * Lists events and returns a ListResult ready for rendering.
+ * JSON includes full event payloads with botResponses for LLM debugging.
+ */
+export function listEventsFormatted(bookId, options, format) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const result = yield listEvents(bookId, options);
+        if (format === 'json') {
+            const jsonResult = {
+                kind: 'json',
+                items: result.items.map(event => event.json()),
+            };
+            if (result.cursor) {
+                jsonResult.cursor = result.cursor;
+            }
+            return jsonResult;
+        }
+        return {
+            kind: 'matrix',
+            matrix: buildEventsMatrix(result.items),
+            footer: buildEventListFooter(bookId, options, result.cursor),
+        };
+    });
+}
+function toListEventsOptions(options) {
+    var _a;
+    const listOptions = {
+        limit: (_a = options.limit) !== null && _a !== void 0 ? _a : DEFAULT_EVENT_LIST_LIMIT,
+    };
+    if (options.afterDate !== undefined) {
+        listOptions.afterDate = options.afterDate;
+    }
+    if (options.beforeDate !== undefined) {
+        listOptions.beforeDate = options.beforeDate;
+    }
+    if (options.resourceId !== undefined) {
+        listOptions.resourceId = options.resourceId;
+    }
+    if (options.onError === true) {
+        listOptions.onError = true;
+    }
+    if (options.type !== undefined) {
+        listOptions.type = options.type;
+    }
+    if (options.cursor !== undefined) {
+        listOptions.cursor = options.cursor;
+    }
+    return listOptions;
+}
+function buildEventsMatrix(events) {
+    const matrix = [
+        ['ID', 'Type', 'Created', 'Resource', 'User', 'Agent', 'Responses', 'Errors', 'Preview'],
+    ];
+    for (const event of events) {
+        const json = event.json();
+        const botResponses = json.botResponses || [];
+        const errorResponses = botResponses.filter(response => response.type === 'ERROR');
+        matrix.push([
+            json.id || '',
+            json.type || '',
+            json.createdOn || json.createdAt || '',
+            json.resource || '',
+            formatUser(json.user),
+            formatAgent(json.agent),
+            botResponses.length,
+            errorResponses.length,
+            formatBotResponsePreview(botResponses),
+        ]);
+    }
+    return matrix;
+}
+function formatUser(user) {
+    if (!user) {
+        return '';
+    }
+    return user.email || user.name || user.id || '';
+}
+function formatAgent(agent) {
+    if (!agent) {
+        return '';
+    }
+    return agent.name || agent.id || '';
+}
+function formatBotResponsePreview(botResponses) {
+    const preferred = botResponses.find(response => response.type === 'ERROR' && response.message) ||
+        botResponses.find(response => response.message);
+    if (!(preferred === null || preferred === void 0 ? void 0 : preferred.message)) {
+        return '';
+    }
+    return truncate(preferred.message, PREVIEW_MAX_LENGTH);
+}
+function truncate(value, maxLength) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, maxLength - 1)}…`;
+}
+function buildEventListFooter(bookId, options, cursor) {
+    var _a;
+    if (!cursor) {
+        return undefined;
+    }
+    const limit = (_a = options.limit) !== null && _a !== void 0 ? _a : DEFAULT_EVENT_LIST_LIMIT;
+    const parts = [`bkper event list -b ${quoteShellArg(bookId)}`];
+    if (options.afterDate) {
+        parts.push(`--after ${quoteShellArg(options.afterDate)}`);
+    }
+    if (options.beforeDate) {
+        parts.push(`--before ${quoteShellArg(options.beforeDate)}`);
+    }
+    if (options.resourceId) {
+        parts.push(`--resource ${quoteShellArg(options.resourceId)}`);
+    }
+    if (options.onError) {
+        parts.push('--error');
+    }
+    if (options.type) {
+        parts.push(`--type ${quoteShellArg(options.type)}`);
+    }
+    parts.push(`--limit ${limit}`);
+    parts.push(`--cursor ${quoteShellArg(cursor)}`);
+    return [`Next cursor: ${cursor}`, `Next page: ${parts.join(' ')}`].join('\n');
+}
+//# sourceMappingURL=list.js.map

package/lib/commands/events/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../src/commands/events/list.ts"],"names":[],"mappings":"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"}

package/lib/commands/events/register.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from 'commander';
+import { EventType } from 'bkper-js';
+/**
+ * Commander parser for EventType values.
+ */
+export declare function parseEventType(value: string): EventType;
+export declare function registerEventCommands(program: Command): void;
+//# sourceMappingURL=register.d.ts.map

package/lib/commands/events/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/commands/events/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AASrC;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAOvD;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuD5D"}

package/lib/commands/events/register.js

@@ -0,0 +1,66 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { EventType } from 'bkper-js';
+import { withAction } from '../action.js';
+import { parsePositiveInteger } from '../cli-helpers.js';
+import { renderItem, renderListResult } from '../../render/index.js';
+import { validateRequiredOptions, throwIfErrors } from '../../utils/validation.js';
+import { listEventsFormatted, replayEventBotResponse } from './index.js';
+const EVENT_TYPE_VALUES = new Set(Object.values(EventType));
+/**
+ * Commander parser for EventType values.
+ */
+export function parseEventType(value) {
+    if (!EVENT_TYPE_VALUES.has(value)) {
+        throw new Error(`Invalid event type '${value}'. Valid types: ${Object.values(EventType).join(', ')}`);
+    }
+    return value;
+}
+export function registerEventCommands(program) {
+    const eventCommand = program.command('event').description('Inspect book events and bot responses');
+    eventCommand
+        .command('list')
+        .description('List events in a book (includes bot responses)')
+        .option('-b, --book <bookId>', 'Book ID')
+        .option('--after <date>', 'Start date inclusive (RFC3339)')
+        .option('--before <date>', 'End date exclusive (RFC3339)')
+        .option('--resource <resourceId>', 'Filter by resource ID (Transaction, Account, or Group)')
+        .option('--error', 'Only events with at least one error bot response')
+        .option('--type <type>', 'Filter by event type', parseEventType)
+        .option('--limit <limit>', 'Fetch one page with up to this many events (default 50, max 200)', parsePositiveInteger)
+        .option('--cursor <cursor>', 'Cursor for fetching the next page')
+        .action(options => withAction('listing events', (format) => __awaiter(this, void 0, void 0, function* () {
+        throwIfErrors(validateRequiredOptions(options, [{ name: 'book', flag: '--book' }]));
+        const result = yield listEventsFormatted(options.book, {
+            afterDate: options.after,
+            beforeDate: options.before,
+            resourceId: options.resource,
+            onError: options.error === true ? true : undefined,
+            type: options.type,
+            limit: options.limit,
+            cursor: options.cursor,
+        }, format);
+        renderListResult(result, format);
+    }))());
+    eventCommand
+        .command('replay <eventId>')
+        .description('Replay one bot response for an event')
+        .option('-b, --book <bookId>', 'Book ID')
+        .option('--agent-id <agentId>', 'Bot/agent ID to replay')
+        .action((eventId, options) => withAction('replaying event bot response', (format) => __awaiter(this, void 0, void 0, function* () {
+        throwIfErrors(validateRequiredOptions(options, [
+            { name: 'book', flag: '--book' },
+            { name: 'agentId', flag: '--agent-id' },
+        ]));
+        const event = yield replayEventBotResponse(options.book, eventId, options.agentId);
+        renderItem(event.json(), format);
+    }))());
+}
+//# sourceMappingURL=register.js.map

package/lib/commands/events/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../../src/commands/events/register.ts"],"names":[],"mappings":"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"}

package/lib/commands/events/replay.d.ts

@@ -0,0 +1,11 @@
+import { Event } from 'bkper-js';
+/**
+ * Replays one bot response for an event.
+ *
+ * @param bookId - The book ID containing the event
+ * @param eventId - The event ID to replay
+ * @param agentId - The bot/agent ID whose response should be replayed
+ * @returns The updated event payload after replay
+ */
+export declare function replayEventBotResponse(bookId: string, eventId: string, agentId: string): Promise<Event>;
+//# sourceMappingURL=replay.d.ts.map

package/lib/commands/events/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../../src/commands/events/replay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,EAAE,MAAM,UAAU,CAAC;AAG9C;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CACxC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GAChB,OAAO,CAAC,KAAK,CAAC,CAOhB"}

package/lib/commands/events/replay.js

@@ -0,0 +1,30 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { BotResponse, Event } from 'bkper-js';
+import { getBkperInstance } from '../../bkper-factory.js';
+/**
+ * Replays one bot response for an event.
+ *
+ * @param bookId - The book ID containing the event
+ * @param eventId - The event ID to replay
+ * @param agentId - The bot/agent ID whose response should be replayed
+ * @returns The updated event payload after replay
+ */
+export function replayEventBotResponse(bookId, eventId, agentId) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const bkper = getBkperInstance();
+        const book = yield bkper.getBook(bookId);
+        const event = new Event(book, { id: eventId });
+        const botResponse = new BotResponse(event, { agentId });
+        yield botResponse.replay();
+        return event;
+    });
+}
+//# sourceMappingURL=replay.js.map

package/lib/commands/events/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../../../src/commands/events/replay.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,UAAgB,sBAAsB,CACxC,MAAc,EACd,OAAe,EACf,OAAe;;QAEf,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACzC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAC/C,MAAM,WAAW,GAAG,IAAI,WAAW,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QACxD,MAAM,WAAW,CAAC,MAAM,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC;IACjB,CAAC;CAAA"}

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

@@ -416,7 +416,12 @@ deployment:
 -   `agent` - Start the interactive Bkper Agent
 -   `agent <pi-args...>` - Run Pi CLI with Bkper defaults (system prompt/resources)
 
-Inside the interactive agent, `/login` connects an AI model provider; it is separate from `bkper auth login`, which connects the CLI to your Bkper account.
+Inside the interactive agent:
+
+-   `/login` connects to Bkper and enables the included Bkper AI models. It uses the same local credentials as `bkper auth login`.
+-   `/logout` revokes and clears Bkper authentication.
+-   `/connect [provider]` connects an external model provider through a subscription or API key.
+-   `/disconnect [provider]` removes credentials stored by `/connect`. Environment variables and model configuration remain unchanged.
 
 ### App Lifecycle
 

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

@@ -1,6 +1,6 @@
 # Data Management
 
-Interact with books, files, accounts, transactions, and balances using the `bkper` CLI.
+Interact with books, files, accounts, transactions, events, and balances using the `bkper` CLI.
 
 All commands that operate within a book use `-b, --book <bookId>` to specify the book context.
 
@@ -296,6 +296,49 @@ bkper transaction merge tx_123 tx_456 -b abc123
 </details>
 
 
+---
+
+## Events
+
+Inspect book events and bot responses — useful for debugging automations and recovering from intermittent bot errors.
+
+```bash
+# List recent events (one page, default limit 50)
+bkper event list -b abc123
+
+# List only events with error bot responses, as JSON (includes full botResponses)
+bkper event list -b abc123 --error --json
+
+# Filter by resource (transaction, account, or group id)
+bkper event list -b abc123 --resource tx_456 --json
+
+# Filter by event type and date range
+bkper event list -b abc123 --type TRANSACTION_POSTED --after 2026-01-01T00:00:00Z
+
+# Fetch the next page
+bkper event list -b abc123 --limit 50 --cursor cursor_123
+
+# Replay one bot response after inspecting an error
+bkper event replay evt_789 -b abc123 --agent-id tax-bot --json
+```
+
+<details>
+<summary>Command reference</summary>
+
+-   `event list -b <bookId>` - List one page of events in a book (includes bot responses in JSON)
+    -   `--after <date>` - Start date inclusive (RFC3339)
+    -   `--before <date>` - End date exclusive (RFC3339)
+    -   `--resource <resourceId>` - Filter by resource ID (Transaction, Account, or Group). When set, `--error` and `--type` are ignored by the API
+    -   `--error` - Only events with at least one error bot response. When set, `--type` is ignored by the API
+    -   `--type <type>` - Filter by event type (e.g. `TRANSACTION_POSTED`, `ACCOUNT_CREATED`)
+    -   `--limit <number>` - Fetch one page with up to this many events (default `50`, max `200`)
+    -   `--cursor <cursor>` - Cursor for fetching the next page
+-   `event replay <eventId> -b <bookId> --agent-id <agentId>` - Replay one bot response for an event (returns the updated event with bot responses)
+
+JSON output includes the full event payload, including nested `botResponses` (`agentId`, `type`, `message`, `createdAt`), for LLM-assisted debugging.
+
+</details>
+
 ---
 
 ## Balances

package/lib/docs/sdk/bkper-api-types.md

@@ -244,6 +244,7 @@ More information at the [Bkper Developer Documentation](https://bkper.com/docs/#
 **Properties:**
 
 - `agentId?`: `string` — The id of agent that created the resource
+- `avatarUrl?`: `string` — The Collaborator public avatar url
 - `createdAt?`: `string` — The creation timestamp, in milliseconds
 - `email?`: `string` — The email of the Collaborator
 - `id?`: `string` — The unique id that identifies the Collaborator in the Book
@@ -534,6 +535,7 @@ More information at the [Bkper Developer Documentation](https://bkper.com/docs/#
 - `billingAdminEmail?`: `string` — The billing admin email for this user's billing account
 - `billingEnabled?`: `boolean` — True if billing is enabled for the user
 - `daysLeftInTrial?`: `number` — How many days left in trial
+- `domain?`: `bkper.Domain`
 - `email?`: `string` — The user email
 - `free?`: `boolean` — True if user is in the free plan
 - `fullName?`: `string` — The user full name

package/lib/docs/sdk/bkper-js.md

@@ -631,7 +631,7 @@ It contains all `Accounts` where `Transactions` are recorded/posted;
 - `getTransaction(id: string)` → `Promise<Transaction | undefined>` — Retrieve a transaction by id.
 - `getVisibility()` / `setVisibility(visibility: Visibility)` → `Visibility` — Gets the visibility of the book.
 - `json()` → `bkper.Book` — Gets an immutable copy of the JSON payload for this resource.
-- `listEvents(afterDate: string | null, beforeDate: string | null, onError: boolean | null, resourceId: string | null, limit: number, cursor?: string)` → `Promise<EventList>` — Lists events in the Book based on the provided parameters.
+- `listEvents(options: ListEventsOptions)` → `Promise<EventList>` — Lists events in the Book based on the provided options.
 - `listFiles(limit?: number, cursor?: string)` → `Promise<FileList>` — Lists files in the Book, for pagination.
 - `listTransactions(query?: string, limit?: number, cursor?: string)` → `Promise<TransactionList>` — Lists transactions in the Book based on the provided query, limit, and cursor, for pagination.
 - `mergeTransactions(transaction1: string | bkper.Transaction | Transaction, transaction2: string | bkper.Transaction | Transaction)` → `Promise<Transaction>` — Merge two `Transactions` into a single new canonical transaction.
@@ -786,6 +786,7 @@ A Collaborator represents a user that has been granted access to a Book with spe
 **Methods:**
 
 - `create(message?: string)` → `Promise<Collaborator>` — Performs create new Collaborator.
+- `getAvatarUrl()` → `string | undefined` — Gets the public avatar url of the Collaborator.
 - `getEmail()` / `setEmail(email: string)` → `string | undefined (set: string)` — Gets the Collaborator email address.
 - `getId()` → `string | undefined` — Gets the Collaborator internal id.
 - `getPermission()` / `setPermission(permission: Permission)` → `Permission | undefined (set: Permission)` — Gets the permission level of the Collaborator.
@@ -902,6 +903,7 @@ A File can be attached to a `Transaction` or used to import data.
 - `getBook()` → `Book` — Gets the Book this File belongs to.
 - `getContent()` / `setContent(content: string)` → `Promise<string | undefined> (set: string)` — Gets the file content Base64 encoded.
 - `getContentType()` / `setContentType(contentType: string)` → `string | undefined (set: string)` — Gets the File content type.
+- `getCreatedAt()` → `Date | undefined` — Gets the date the File was created.
 - `getId()` → `string | undefined` — Gets the File id.
 - `getName()` / `setName(name: string)` → `string | undefined (set: string)` — Gets the File name.
 - `getSize()` → `number | undefined` — Gets the file size in bytes.
@@ -1311,6 +1313,40 @@ Bkper Platform outbound for server-side app routes.
 This function is called when a request fails and needs to be retried.
 It provides the HTTP status code, error message, and the number of retry attempts made so far.
 
+### ListEventsOptions
+
+Options for listing events in a Book.
+
+**Properties:**
+
+- `afterDate?`: `string` — The start date (inclusive) for the events search range, in [RFC3339](https://en.wikipedia.org/wiki/ISO_8601#RFC_3339) format.
+- `beforeDate?`: `string` — The end date (exclusive) for the events search range, in [RFC3339](https://en.wikipedia.org/wiki/ISO_8601#RFC_3339) format.
+- `cursor?`: `string` — The cursor for pagination.
+- `limit`: `number` — The maximum number of events to return.
+- `onError?`: `boolean` — Whether to filter events by error responses.
+- `resourceId?`: `string` — The ID of the event's resource (Transaction, Account, or Group).
+- `type?`: `EventType` — The event type to filter by.
+
+**limit**
+
+Defaults to `50`, maximum is `200`.
+
+**onError**
+
+`true` returns events with at least one error response.
+`false` returns events with no error responses.
+`null` or `undefined` includes events regardless of error responses.
+
+Ignored when `resourceId` is set. When set, `type` is ignored.
+
+**resourceId**
+
+When set, `onError` and `type` are ignored.
+
+**type**
+
+Ignored when `resourceId` or `onError` is set.
+
 ## Enums
 
 ### AccountType

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bkper",
-    "version": "4.18.4",
+    "version": "4.19.0",
     "description": "Command line client for Bkper",
     "bin": {
         "bkper": "./lib/cli.js"
@@ -43,7 +43,7 @@
         "test:integration": "TS_NODE_TRANSPILE_ONLY=true BKPER_API_URL=${BKPER_API_URL:-http://localhost:8081/_ah/api/bkper} TS_NODE_PROJECT=tsconfig.test.json mocha --config .mocharc.integration.json",
         "test:deploy": "TS_NODE_TRANSPILE_ONLY=true BKPER_PLATFORM_URL=http://localhost:8790 BKPER_API_URL=https://api-dev.bkper.app TS_NODE_PROJECT=tsconfig.test.json mocha --config .mocharc.deploy.json",
         "test:all": "bun run test:unit && bun run test:integration",
-        "version": "bun ./scripts/sync-plugin-version.ts",
+        "version": "bun ./scripts/sync-plugin-version.ts && git add .claude-plugin/plugin.json .claude-plugin/marketplace.json .codex-plugin/plugin.json",
         "release:patch": "npm version patch -m \"chore(release): v%s\"",
         "release:minor": "npm version minor -m \"chore(release): v%s\"",
         "release:major": "npm version major -m \"chore(release): v%s\"",
@@ -52,8 +52,8 @@
         "upgrade:api": "bun update @bkper/bkper-api-types --latest && bun update bkper-js --latest"
     },
     "dependencies": {
-        "@earendil-works/pi-coding-agent": "0.80.3",
-        "bkper-js": "^2.37.0",
+        "@earendil-works/pi-coding-agent": "0.80.6",
+        "bkper-js": "^2.40.1",
         "commander": "^13.1.0",
         "dotenv": "^8.2.0",
         "esbuild": "^0.27.2",