@go-labs-sg/bb 2.16.0 → 2.17.0

package/README.md

@@ -183,6 +183,10 @@ external provider.
 
 ### Mutation safety
 
+While an estimate email is `QUEUED`, `PROCESSING`, or awaiting provider
+reconciliation, the API makes that Budget read-only. Budget-changing CLI
+commands return a conflict until delivery becomes `SENT` or `FAILED`.
+
 Every canonical command is classified by effect: `state-change`, `email`, `external-write`, `delete`, and/or `financial-write`. Interactive runs require one exact `CONFIRM`. Non-interactive runs require the corresponding flags (`--allow-state-change`, `--allow-email`, `--allow-external-write`, `--allow-delete`, and `--allow-financial-write`); commands with multiple effects require every matching flag. Agents must still get user confirmation in chat first—the runtime gate is not user authorization.
 
 **Approval email exclusions:** Approval requests create pending database records for every eligible approver, including configured non-recipient admin accounts. Automated approval-request emails skip those accounts.
@@ -191,7 +195,7 @@ Every canonical command is classified by effect: `state-change`, `email`, `exter
 
 **Mutations with `--payload`:** Commands such as `bb budget create`, `bb bill create`, and `bb supplier update` take a single JSON object (`--payload '<json>'`) matching the corresponding tRPC procedure input. Use ISO strings for date/datetime fields; the CLI coerces them where needed. The API still validates the full shape. Plain `description` fields for item create/update are converted to `descriptionRichText`; pass `descriptionRichText` directly when formatted Tiptap JSON is required. For **`bb project update`**, the project window is `dateRange.from` and `dateRange.to` (optional end); there are no separate event-date fields on the project payload. **`bb budget create` / `bb budget update`** do not accept `asanaTaskId`; configure the deal card on the project (`bb project update` / project settings).
 
-**Contact-person estimate email:** `bb budget estimate send --payload '<json>'` calls the same `email.sendEstimateToContactPerson` procedure as the web composer. The payload requires `budgetId`, `estimateId`, optional `estimateDocNumber`, `to`, `cc`, `replyTo`, `subject`, HTML `content`, and HTML `signature`. It sends the raw PDF returned by QuickBooks together with the standard terms and Budget Builder budget attachments, then marks the budget `ESTIMATE_SENT`. The command requires interactive `CONFIRM`; inspect the budget, recipients, and HTML first, and do not retry blindly after an ambiguous delivery failure.
+**Contact-person estimate email:** `bb budget estimate send --payload '<json>'` calls the same `email.sendEstimateToContactPerson` procedure as the web composer. The payload requires `budgetId`, `estimateId`, optional `estimateDocNumber`, `to`, `cc`, `replyTo`, `subject`, HTML `content`, and HTML `signature`. It durably queues worker delivery of the QuickBooks PDF, standard terms, and Budget Builder budget attachments, and returns the outbound-email and operation IDs immediately. Worker retries reuse one provider idempotency key; the budget becomes `ESTIMATE_SENT` only after Resend accepts the email. The command requires interactive `CONFIRM`; inspect the budget, recipients, and HTML first.
 
 **Customer-invoice workflow parity:** `bb customer-invoice list` uses the same global/project list procedure and metrics as the web pages; omit filters for the global list or use `--projectId` for project scope. `bb customer-invoice send` uses the same protected email workflow as the web composer and marks a successful invoice `SENT`. `bb customer-invoice approve` and `bb customer-invoice reject` are Admin-only batch operations: callers select a batch ID, and the API resolves its internal pending Admin approval record. `bb customer-invoice sync` follows QuickBooks' paid state and zero balance, restoring `SENT` or `APPROVED` if that payment is reversed. Invoice approval refuses voided invoices and closes the estimate only when approved invoice coverage totals 100%; deletion, voiding, rejection, expiry, and QBO synchronization use the same estimate-reopening and live-payment guards as the web app.
 
@@ -207,11 +211,14 @@ For agent-driven invoice work, use this read-before-write sequence:
 Project Hub setup and commercial-document reconciliation are durable, asynchronous Budget Builder operations. Read status before requesting either mutation:
 
 ```bash
+bb project hub list --q <project-or-company> --status WON,COMPLETED
 bb project hub status <project-id>
 bb project hub setup <project-id>
 bb project hub sync <project-id>
 ```
 
+`list` is read-only and returns active projects with a Project Hub integration, including setup state and the stored Hub URL when available. It supports project/company search, project-status filters, pagination, and sorting.
+
 `status` reports eligibility, whether setup can be requested, the current setup status, the latest setup error, and the client Hub URL. `setup` uses the same eligibility and accepted-estimate checks as the web button and may create the operational Asana project before provisioning Drive and Project Hub. `sync` requires an existing `READY` native-layout integration and queues a complete reconciliation of accepted estimates, commercial attachments, win proofs, and eligible customer invoices into Asana and Drive.
 
 Both mutation commands write external state asynchronously and therefore require `state-change` and `external-write` confirmation. In non-interactive use, pass both `--allow-state-change` and `--allow-external-write` only after obtaining explicit user approval. A successful `queued` response means the durable operation was accepted. `status` tracks setup readiness; the sync response returns its outbox operation ID, which an Admin can inspect with the integration-operation commands when completion or failure diagnostics are required.
@@ -236,7 +243,7 @@ Project and budget query payloads keep the Asana identities explicit: `asanaTask
 | **Suppliers & items** | `list-suppliers` (defaults to active suppliers, `--perPage 10`, sorted by `createdAt` desc; supports `--name`, `--sortBy` for scalar supplier fields, `--sortDir`, `--createdBy`, `--gstRegistered`, `--status`, `--supplierTags`, `--active false` for archived suppliers), `create-supplier` (`--payload`; when supplier status is `PENDING_APPROVAL`, also runs `supplier.createSupplierApproval` and `email.sendSupplierApprovalRequestEmail`), `update-supplier` (`--payload`; when supplier status is `PENDING_APPROVAL`, also runs `supplier.createSupplierApproval` and `email.sendSupplierApprovalRequestEmail`), `delete-suppliers` (`--ids` CSV; admin; archives/deactivates related items), `reactivate-suppliers` (`--ids` CSV; admin; reactivates related items), `create-certification` / `create-payment-method` / `create-supplier-role` / `create-supplier-tag` (`--name`), `get-supplier-details` (includes `supplierApprovalSummary` for pending approvers, superseded approvers, and the actual responder/respondedAt metadata), `get-supplier-analytics` (admin), `list-items`, `create-item` (`--payload`), `update-item` (`--payload`), `archive-items` (`--ids` CSV, max 100; Budget Builder only; users can archive their own items, leads/admins any item; blocked by Draft/Pending Approval/Approved budgets), `delete-item` (admin; archives in Budget Builder and makes the item inactive in QuickBooks), `get-item`, `list-item-categories`, `create-item-category` / `update-item-category` / `delete-item-categories` (admin; `--ids` CSV for delete) |
 | **Dashboard & users** | `whoami` (current API-key owner identity and role), `list-users`, `create-user` (admin; provisions an API-only service identity with no Google sign-in; `--email`, optional `--name`, optional `--role` defaulting to `USER`), `create-api-key` (`--name`; defaults to the caller; admin-only `--userId` for another user; raw key shown once), `list-api-keys` (defaults to the caller; admin-only `--userId` for another user), `revoke-api-key` (key ID; admin-only `--userId` for another user), `get-user-performance`, `get-dashboard`, `get-monthly-metrics`, `get-system-overview`, `get-estimate-performance`, `get-financial-overview` (performance/dashboard commands are admin-only) |
 | **Errors (admin)** | `get-recent-errors`, `get-error-metrics` |
-| **Automation (admin)** | `list-integration-operations`, `retry-integration-operation` |
+| **Automation (admin)** | `list-integration-operations`, `retry-integration-operation` (Resend resolution requires `--confirmExternalStateReconciled true` plus `--outboundEmailResolution ACCEPTED\|NOT_ACCEPTED_RETRY`; include `--providerMessageId` when accepted) |
 | **Historical / benchmarks** | `get-approved-budgets`, `get-budget-category-benchmarks`, `get-item-pricing-history`, `get-supplier-pricing-history` |
 
 The CLI intentionally wraps low-level upload-request/confirm procedures into file-based commands and omits browser-only helpers such as navigation counts, combobox/facet data, recent-page bookkeeping, and live UI subscriptions. Operational workflows for bills, claims, quotations, customer invoices, project reconciliation/completion, and integration recovery are available directly.

package/command-manifest.json

@@ -4190,6 +4190,76 @@
 		"effects": [],
 		"legacyTarget": "list-projects"
 	},
+	{
+		"path": ["project", "hub", "list"],
+		"legacyAliases": ["list-project-hubs", "list_project_hubs"],
+		"summary": "List project hubs.",
+		"globalOptions": [
+			{
+				"name": "--help",
+				"description": "Show help for this command."
+			},
+			{
+				"name": "--quiet",
+				"description": "Suppress non-error diagnostics."
+			},
+			{
+				"name": "--debug",
+				"description": "Emit sanitized diagnostic traces."
+			},
+			{
+				"name": "--api-url",
+				"description": "Override the Budget Builder API base URL."
+			},
+			{
+				"name": "--allow-state-change",
+				"description": "Allow a Budget Builder state change in non-interactive use."
+			},
+			{
+				"name": "--allow-email",
+				"description": "Allow sending email in non-interactive use."
+			},
+			{
+				"name": "--allow-external-write",
+				"description": "Allow writes to external systems in non-interactive use."
+			},
+			{
+				"name": "--allow-delete",
+				"description": "Allow deleting data in non-interactive use."
+			},
+			{
+				"name": "--allow-financial-write",
+				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--q",
+				"description": "Search project and company names."
+			},
+			{
+				"name": "--status",
+				"description": "Filter by comma-separated project statuses."
+			},
+			{
+				"name": "--page",
+				"description": "Select a results page."
+			},
+			{
+				"name": "--perPage",
+				"description": "Set the results page size."
+			},
+			{
+				"name": "--sortBy",
+				"description": "Sort by startDate, name, companyName, or status."
+			},
+			{
+				"name": "--sortDir",
+				"description": "Sort in asc or desc order."
+			}
+		],
+		"argumentMode": "legacy-passthrough",
+		"effects": [],
+		"legacyTarget": "list-project-hubs"
+	},
 	{
 		"path": ["project", "get"],
 		"legacyAliases": ["get-project", "get_project"],

package/command-reference.md

@@ -736,6 +736,14 @@ Legacy aliases: `list-projects`, `list_projects`.
 
 Effects: none.
 
+## `bb project hub list`
+
+List project hubs.
+
+Legacy aliases: `list-project-hubs`, `list_project_hubs`.
+
+Effects: none.
+
 ## `bb project get`
 
 Get project.

package/dist/commands.js

@@ -1091,7 +1091,7 @@ export async function createEstimate(budgetId, preflight) {
     const result = await api.quickbooks.createEstimate.mutate({ budgetId });
     out(result);
 }
-export const describeEstimateEmailConfirmation = (input) => `to ${input.to}; CC ${input.cc.length > 0 ? input.cc.join(", ") : "none"}; reply-to ${input.replyTo}; subject "${input.subject}"; attach the QBO estimate PDF, terms and conditions, and Budget Builder attachments, then mark the estimate sent`;
+export const describeEstimateEmailConfirmation = (input) => `to ${input.to}; CC ${input.cc.length > 0 ? input.cc.join(", ") : "none"}; reply-to ${input.replyTo}; subject "${input.subject}"; queue durable worker delivery with the QBO estimate PDF, terms and conditions, and Budget Builder attachments; mark the estimate sent after provider acceptance`;
 export const sendEstimateToContactPersonFromPayload = async (raw) => {
     const input = parseSendEstimateToContactPersonPayload(raw);
     await assertSensitiveWorkflowConfirmed({
@@ -1907,6 +1907,14 @@ export async function listProjects(opts) {
     });
     out(result);
 }
+export const listProjectHubs = async (opts) => {
+    const result = await api.project.getAllProjectHubs.query({
+        ...opts,
+        page: opts.page ?? 1,
+        perPage: opts.perPage ?? 20,
+    });
+    out(result);
+};
 export async function getProject(id) {
     const [project, budgetsOverview, billsOverview] = await Promise.all([
         api.project.getProjectDetailsById.query({ id }),
@@ -2015,17 +2023,25 @@ export const listIntegrationOperations = async (input) => {
     const result = await api.integration.listOperations.query(input);
     out(result);
 };
-export const retryIntegrationOperation = async (operationId, confirmExternalStateReconciled) => {
+export const retryIntegrationOperation = async (operationId, confirmExternalStateReconciled, outboundEmailResolution, providerMessageId) => {
     await assertSensitiveWorkflowConfirmed({
-        action: "Retry integration operation",
+        action: outboundEmailResolution === "ACCEPTED"
+            ? "Reconcile integration operation as completed"
+            : "Retry integration operation",
         entity: `operation ${operationId}`,
-        details: confirmExternalStateReconciled
-            ? "after confirming the external state has been reconciled"
-            : undefined,
+        details: outboundEmailResolution === "ACCEPTED"
+            ? `mark provider-accepted email sent with message ID ${providerMessageId ?? "<missing>"}`
+            : outboundEmailResolution === "NOT_ACCEPTED_RETRY"
+                ? "rotate the Resend idempotency key and retry provider delivery"
+                : confirmExternalStateReconciled
+                    ? "after confirming the external state has been reconciled"
+                    : undefined,
     });
     const result = await api.integration.retryOperation.mutate({
         operationId,
         confirmExternalStateReconciled,
+        outboundEmailResolution,
+        providerMessageId,
     });
     out(result);
 };

package/dist/index.js

@@ -5,9 +5,9 @@ import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { BUDGET_BUILDER_API_BASE_URL, configureBudgetBuilderApiBaseUrl, DEFAULT_BUDGET_BUILDER_API_BASE_URL, requireApiKey, } from "./api-client.js";
 import { consumeCliQuietFlags, logCliAction, sanitizeFlagsForTrace, setCliQuiet, shouldLogCliActions, } from "./cli-trace.js";
-import { addBudgetItems, approveBill, approveBudget, approveCustomerInvoice, approveQuotation, approveSupplier, archiveItemsByIds, checkCustomerInvoiceReadiness, checkProjectReconciliation, cleanupStagedBillAttachments, cleanupStagedQuotationAttachments, completeProject, createApiKeyForUser, createBillApproval, createBillFromPayload, createBudgetApproval, createBudgetCategory, createBudgetFromPayload, createCompany, createContactPersonFromPayload, createCustomerInvoice, createEstimate, createInboundSource, createItemCategory, createItemFromPayload, createPlaceholderBillForBudgetItem, createProject, createQuotationFromPayload, createSupplierCertification, createSupplierFromPayload, createSupplierPaymentMethod, createSupplierRoleOption, createSupplierTagOption, createUser, deleteBillById, deleteBudgetById, deleteBudgetCategory, deleteBudgetCommission, deleteBudgetDiscount, deleteCompanyById, deleteCustomerInvoice, deleteItemById, deleteItemCategoriesByIds, deleteProjectById, deleteQuotationById, deleteSuppliersByIds, discardCreatingCustomerInvoice, downloadCustomerInvoicePdf, downloadQuotationPdf, getApprovedBudgets, getBillAttachments, getBillDetails, getBudget, getBudgetCategories, getBudgetCategoryBenchmarks, getBudgetDetails, getBudgetItemsOnly, getBudgetVersions, getCompany, getCustomerInvoice, getCustomerInvoiceEmailContext, getDashboard, getErrorMetrics, getEstimatePerformance, getFinancialOverview, getInboundSource, getInboundSubmission, getItem, getItemPricingHistory, getMonthlyMetrics, getProject, getProjectHubStatus, getQuotationDetails, getRecentErrors, getSupplierAnalytics, getSupplierDetails, getSupplierPricingHistory, getSystemOverview, getUserPerformance, importQuickBooksProjectId, listApiKeysForUser, listApprovals, listBills, listBudgets, listCompanies, listContacts, listCustomerInvoices, listEligibleCustomerInvoiceBudgets, listInboundSources, listInboundSubmissions, listIntegrationOperations, listItemCategories, listItems, listProjects, listQuotations, listSuppliers, listUsers, markBudgetWonWithProof, patchBillInvoiceNumber, patchBillPayment, reactivateSuppliersByIds, reconcileProject, rejectBill, rejectBudget, rejectCustomerInvoice, rejectQuotation, rejectSupplier, removeBudgetItem, renameBudgetVersion, reorderBudgetItemsCli, restoreBudgetVersion, retryIntegrationOperation, revokeApiKeyForUser, saveInboundAutomationConfig, saveInboundMappingVersion, sendCustomerInvoiceToContactPersonFromPayload, sendEstimateToContactPersonFromPayload, setBudgetItemsNotUtilized, setupProjectHub, stageBillAttachmentsFromPaths, submitQuotation, syncCustomerInvoice, syncProjectHubCommercialDocuments, updateBillFromPayload, updateBillPaymentEvidenceFromPayload, updateBillStatus, updateBudgetCategory, updateBudgetCommissionFromPayload, updateBudgetDiscountFromPayload, updateBudgetFromPayload, updateBudgetItem, updateBudgetItemSupplierCli, updateBudgetStatus, updateCompanyFromPayload, updateContactPersonFromPayload, updateInboundProcessing, updateInboundSource, updateItemCategory, updateItemFromPayload, updateProjectFromPayload, updateProjectStatus, updateQuotationFromPayload, updateSupplierFromPayload, uploadBillAttachmentFromPath, uploadBillAttachmentsFromPaths, uploadBillDocumentsFromPaths, uploadBudgetAttachmentFromPath, uploadQuotationAttachmentFromPath, validateBillSelectionFromPayload, voidCustomerInvoice, whoAmI, } from "./commands.js";
+import { addBudgetItems, approveBill, approveBudget, approveCustomerInvoice, approveQuotation, approveSupplier, archiveItemsByIds, checkCustomerInvoiceReadiness, checkProjectReconciliation, cleanupStagedBillAttachments, cleanupStagedQuotationAttachments, completeProject, createApiKeyForUser, createBillApproval, createBillFromPayload, createBudgetApproval, createBudgetCategory, createBudgetFromPayload, createCompany, createContactPersonFromPayload, createCustomerInvoice, createEstimate, createInboundSource, createItemCategory, createItemFromPayload, createPlaceholderBillForBudgetItem, createProject, createQuotationFromPayload, createSupplierCertification, createSupplierFromPayload, createSupplierPaymentMethod, createSupplierRoleOption, createSupplierTagOption, createUser, deleteBillById, deleteBudgetById, deleteBudgetCategory, deleteBudgetCommission, deleteBudgetDiscount, deleteCompanyById, deleteCustomerInvoice, deleteItemById, deleteItemCategoriesByIds, deleteProjectById, deleteQuotationById, deleteSuppliersByIds, discardCreatingCustomerInvoice, downloadCustomerInvoicePdf, downloadQuotationPdf, getApprovedBudgets, getBillAttachments, getBillDetails, getBudget, getBudgetCategories, getBudgetCategoryBenchmarks, getBudgetDetails, getBudgetItemsOnly, getBudgetVersions, getCompany, getCustomerInvoice, getCustomerInvoiceEmailContext, getDashboard, getErrorMetrics, getEstimatePerformance, getFinancialOverview, getInboundSource, getInboundSubmission, getItem, getItemPricingHistory, getMonthlyMetrics, getProject, getProjectHubStatus, getQuotationDetails, getRecentErrors, getSupplierAnalytics, getSupplierDetails, getSupplierPricingHistory, getSystemOverview, getUserPerformance, importQuickBooksProjectId, listApiKeysForUser, listApprovals, listBills, listBudgets, listCompanies, listContacts, listCustomerInvoices, listEligibleCustomerInvoiceBudgets, listInboundSources, listInboundSubmissions, listIntegrationOperations, listItemCategories, listItems, listProjectHubs, listProjects, listQuotations, listSuppliers, listUsers, markBudgetWonWithProof, patchBillInvoiceNumber, patchBillPayment, reactivateSuppliersByIds, reconcileProject, rejectBill, rejectBudget, rejectCustomerInvoice, rejectQuotation, rejectSupplier, removeBudgetItem, renameBudgetVersion, reorderBudgetItemsCli, restoreBudgetVersion, retryIntegrationOperation, revokeApiKeyForUser, saveInboundAutomationConfig, saveInboundMappingVersion, sendCustomerInvoiceToContactPersonFromPayload, sendEstimateToContactPersonFromPayload, setBudgetItemsNotUtilized, setupProjectHub, stageBillAttachmentsFromPaths, submitQuotation, syncCustomerInvoice, syncProjectHubCommercialDocuments, updateBillFromPayload, updateBillPaymentEvidenceFromPayload, updateBillStatus, updateBudgetCategory, updateBudgetCommissionFromPayload, updateBudgetDiscountFromPayload, updateBudgetFromPayload, updateBudgetItem, updateBudgetItemSupplierCli, updateBudgetStatus, updateCompanyFromPayload, updateContactPersonFromPayload, updateInboundProcessing, updateInboundSource, updateItemCategory, updateItemFromPayload, updateProjectFromPayload, updateProjectStatus, updateQuotationFromPayload, updateSupplierFromPayload, uploadBillAttachmentFromPath, uploadBillAttachmentsFromPaths, uploadBillDocumentsFromPaths, uploadBudgetAttachmentFromPath, uploadQuotationAttachmentFromPath, validateBillSelectionFromPayload, voidCustomerInvoice, whoAmI, } from "./commands.js";
 import { getFlag, parseArgs } from "./parse-args.js";
-import { billStatusesForUpdateHelp, budgetStatusesForHelp, isBudgetStatusUpdate, parseApprovalTypeFlag, parseBillStatusForUpdate, parseCommaSeparatedBillStatuses, parseCommaSeparatedBudgetStatuses, parseCommaSeparatedCustomerInvoiceStatuses, parseCommaSeparatedIds, parseCommaSeparatedIntegrationOperationStatuses, parseCommaSeparatedQuotationStatuses, parseCommaSeparatedSupplierStatuses, parseOptionalBillListSortBy, parseOptionalBillListSortDir, parseOptionalDashboardRole, parseOptionalDeals, parseOptionalErrorSeverity, parseOptionalErrorStatus, parseOptionalExtendedProjectStatus, parseOptionalFinancialRole, parseOptionalSupplierAnalyticsTimeFrame, parseOptionalTimeFrame, parseProjectStatusForUpdate, parseUserRole, projectStatusesForHelp, userRolesForHelp, } from "./parse-cli-enums.js";
+import { billStatusesForUpdateHelp, budgetStatusesForHelp, isBudgetStatusUpdate, parseApprovalTypeFlag, parseBillStatusForUpdate, parseCommaSeparatedBillStatuses, parseCommaSeparatedBudgetStatuses, parseCommaSeparatedCustomerInvoiceStatuses, parseCommaSeparatedIds, parseCommaSeparatedIntegrationOperationStatuses, parseCommaSeparatedProjectStatuses, parseCommaSeparatedQuotationStatuses, parseCommaSeparatedSupplierStatuses, parseOptionalBillListSortBy, parseOptionalBillListSortDir, parseOptionalDashboardRole, parseOptionalDeals, parseOptionalErrorSeverity, parseOptionalErrorStatus, parseOptionalExtendedProjectStatus, parseOptionalFinancialRole, parseOptionalProjectHubSortBy, parseOptionalSupplierAnalyticsTimeFrame, parseOptionalTimeFrame, parseProjectStatusForUpdate, parseUserRole, projectStatusesForHelp, userRolesForHelp, } from "./parse-cli-enums.js";
 import { parseJsonFlag, parseOptionalNumber as parseOptNum, } from "./parse-json-flag.js";
 import { createCompletionScript, createHumanHelp, resolveCommand, } from "./registry/index.js";
 import { CliRuntimeError, clearActiveCliSession, confirmCurrentCommand, createProcessRuntime, emitCommandError, emitCommandResult, setActiveCliSession, } from "./runtime/index.js";
@@ -155,6 +155,9 @@ AI agents must inspect the entity first, summarize the exact entity, target
 state, and side effects, then wait for explicit user confirmation before running
 the sensitive command.
 
+Budget mutations return a conflict while an estimate email is queued,
+processing, or awaiting provider reconciliation.
+
 Budgets
   list-budgets              [--projectId] [--name] [--status CSV] [--createdBy] [--dateFrom] [--dateTo] [--sortBy] [--sortDir] [--page] [--perPage] [--summary]
   get-budget <id>            Budget + line items
@@ -268,6 +271,8 @@ Companies & projects
   delete-company <id>
   list-projects              [--companyId] [--name] [--status] [--active true|false] [--page] [--perPage]
     Omit --active to include both active and inactive projects.
+  list-project-hubs          [--q] [--status CSV] [--page] [--perPage] [--sortBy startDate|name|companyName|status] [--sortDir asc|desc]
+    List active projects that have a Project Hub integration.
   get-project <id>
     Budget overview totalRevenue includes Estimate Accepted and Estimate Closed budgets only.
   create-project             --name --companyId --contactPersonId --insideSalesId --businessDevelopmentId --venue --startDate <ISO> [--projectManagerId <userId>] [--asanaTaskId] [--asanaSearch <text>] [--slackChannelId --slackChannelUrl --slackChannelName] [--pax] [--endDate <ISO>] [--description]
@@ -331,7 +336,7 @@ Errors
 
 Automation (admin)
   list-integration-operations [--search] [--destination <provider,...>] [--status <PENDING|PROCESSING|FAILED|COMPLETED,...>] [--page] [--perPage]
-  retry-integration-operation <operationId> [--confirmExternalStateReconciled true|false]
+  retry-integration-operation <operationId> [--confirmExternalStateReconciled true|false] [--outboundEmailResolution ACCEPTED|NOT_ACCEPTED_RETRY] [--providerMessageId <id>]
 
 Historical / benchmarks
   get-approved-budgets       [--projectId] [--limit] [--minRevenue] [--maxRevenue]
@@ -1569,6 +1574,17 @@ export async function runCli(argv = process.argv, runtime = createProcessRuntime
                 });
                 break;
             }
+            case "list-project-hubs": {
+                await listProjectHubs({
+                    q: getFlag(flags, "q"),
+                    statuses: parseCommaSeparatedProjectStatuses(getFlag(flags, "status")),
+                    page: parsePositiveIntFlag(getFlag(flags, "page"), "--page"),
+                    perPage: parsePositiveIntFlag(getFlag(flags, "perPage"), "--perPage"),
+                    sortBy: parseOptionalProjectHubSortBy(getFlag(flags, "sortBy")),
+                    sortDir: parseOptionalBillListSortDir(getFlag(flags, "sortDir")),
+                });
+                break;
+            }
             case "get-project": {
                 const id = positional[0];
                 if (!id)
@@ -2008,8 +2024,14 @@ export async function runCli(argv = process.argv, runtime = createProcessRuntime
                 if (!operationId) {
                     throw new Error("retry-integration-operation requires <operationId>");
                 }
+                const outboundEmailResolution = getFlag(flags, "outboundEmailResolution");
+                if (outboundEmailResolution &&
+                    outboundEmailResolution !== "ACCEPTED" &&
+                    outboundEmailResolution !== "NOT_ACCEPTED_RETRY") {
+                    throw new Error("--outboundEmailResolution must be ACCEPTED or NOT_ACCEPTED_RETRY");
+                }
                 await retryIntegrationOperation(operationId, parseOptionalBoolFlag(flags, "confirmExternalStateReconciled") ??
-                    false);
+                    false, outboundEmailResolution, getFlag(flags, "providerMessageId"));
                 break;
             }
             case "list-inbound-sources": {

package/dist/parse-cli-enums.js

@@ -78,6 +78,36 @@ export function parseOptionalExtendedProjectStatus(raw) {
     }
     return raw;
 }
+export function parseCommaSeparatedProjectStatuses(raw) {
+    if (raw === undefined)
+        return undefined;
+    const statuses = raw
+        .split(",")
+        .map((value) => value.trim().toUpperCase())
+        .filter(Boolean);
+    if (statuses.length === 0)
+        return undefined;
+    for (const status of statuses) {
+        if (!PROJECT_STATUS_VALUES.has(status)) {
+            throw new Error(`Invalid project status "${status}". Use one of: ${[...PROJECT_STATUS_VALUES].join(", ")}.`);
+        }
+    }
+    return statuses;
+}
+const PROJECT_HUB_SORT_FIELDS = new Set([
+    "startDate",
+    "name",
+    "companyName",
+    "status",
+]);
+export function parseOptionalProjectHubSortBy(raw) {
+    if (raw === undefined || raw === "")
+        return undefined;
+    if (!PROJECT_HUB_SORT_FIELDS.has(raw)) {
+        throw new Error(`Invalid --sortBy "${raw}". Use one of: ${[...PROJECT_HUB_SORT_FIELDS].join(", ")}.`);
+    }
+    return raw;
+}
 export function parseOptionalDashboardRole(raw) {
     if (raw === undefined || raw === "")
         return undefined;

package/dist/registry/index.js

@@ -209,11 +209,11 @@ const aliasesFor = (legacyTarget, aliases) => [
         alias.replaceAll("-", "_"),
     ])),
 ];
-const legacyCommand = (legacyTarget, path, aliases = []) => ({
+const legacyCommand = (legacyTarget, path, aliases = [], commandOptions = []) => ({
     path,
     legacyAliases: aliasesFor(legacyTarget, aliases),
     summary: summaryFor(legacyTarget),
-    options: globalCommandOptions,
+    options: [...globalCommandOptions, ...commandOptions],
     effects: effectsFor(legacyTarget),
     legacyTarget,
 });
@@ -367,6 +367,23 @@ const registry = [
     legacyCommand("update-company", ["company", "update"]),
     legacyCommand("delete-company", ["company", "delete"]),
     legacyCommand("list-projects", ["project", "list"]),
+    legacyCommand("list-project-hubs", ["project", "hub", "list"], [], [
+        {
+            name: "--q",
+            description: "Search project and company names.",
+        },
+        {
+            name: "--status",
+            description: "Filter by comma-separated project statuses.",
+        },
+        { name: "--page", description: "Select a results page." },
+        { name: "--perPage", description: "Set the results page size." },
+        {
+            name: "--sortBy",
+            description: "Sort by startDate, name, companyName, or status.",
+        },
+        { name: "--sortDir", description: "Sort in asc or desc order." },
+    ]),
     legacyCommand("get-project", ["project", "get"]),
     legacyCommand("get-project-hub-status", ["project", "hub", "status"]),
     legacyCommand("setup-project-hub", ["project", "hub", "setup"]),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/bb",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "Budget Builder CLI for AI agents — manage budgets, bills, claims, quotations, and customer invoices with explicit workflow previews for sensitive changes.",
   "type": "module",
   "main": "./dist/index.js",

package/role-aware-agent-guide.md

@@ -86,6 +86,7 @@ This table highlights the role-sensitive command groups an agent is most likely
 
 | Commands or action | Required identity condition |
 | --- | --- |
+| `bb project hub list` | Any active authenticated role; the command is read-only and returns only active projects with a Project Hub integration. |
 | `bb auth whoami`; own `bb user api-key create`, `bb user api-key list`, and `bb user api-key revoke` | Any active role; omit `--userId` to act as the current user. |
 | Cross-user API-key commands; `bb user create` | `ADMIN`. |
 | Budget/project mutations, estimates, and budget attachments | `ADMIN`, budget creator, or project assignment as Business Development, Inside Sales, or Project Manager, depending on the endpoint. |