mulmoclaude 0.5.2 → 0.6.0

package/src/plugins/accounting/countries.ts

@@ -0,0 +1,158 @@
+// Country utilities for the accounting plugin.
+//
+// The book's country (ISO 3166-1 alpha-2) identifies the tax
+// jurisdiction the book is kept under. The Accounting role uses it
+// to give country-aware advice — Japanese T-number under
+// インボイス制度, EU VAT ID, UK VAT, GSTIN, ABN, etc.
+//
+// Curated against the supported currency list and the tax-regime
+// guidance in `src/config/roles.ts` (Accounting role prompt).
+// Intl.DisplayNames provides the localized human name at render
+// time, so this stays a flat list of codes.
+
+/** ISO 3166-1 alpha-2 country codes shown in the book country
+ *  dropdown. Curated to cover every jurisdiction the Accounting role
+ *  has explicit tax-registration advice for, plus the major economies
+ *  represented in `SUPPORTED_CURRENCY_CODES`. */
+export const SUPPORTED_COUNTRY_CODES = [
+  "US",
+  "JP",
+  "GB",
+  "CA",
+  "AU",
+  "NZ",
+  "DE",
+  "FR",
+  "IT",
+  "ES",
+  "NL",
+  "BE",
+  "AT",
+  "IE",
+  "PT",
+  "FI",
+  "SE",
+  "DK",
+  "PL",
+  "CH",
+  "NO",
+  "CN",
+  "KR",
+  "TW",
+  "HK",
+  "SG",
+  "IN",
+  "BR",
+  "MX",
+] as const;
+
+export type SupportedCountryCode = (typeof SUPPORTED_COUNTRY_CODES)[number];
+
+/** EU member states as of 2026. Used by the role-prompt advice path
+ *  to recommend a VAT identification number when the book country is
+ *  in the EU. */
+export const EU_COUNTRY_CODES: ReadonlySet<string> = new Set([
+  "AT",
+  "BE",
+  "BG",
+  "CY",
+  "CZ",
+  "DE",
+  "DK",
+  "EE",
+  "ES",
+  "FI",
+  "FR",
+  "GR",
+  "HR",
+  "HU",
+  "IE",
+  "IT",
+  "LT",
+  "LU",
+  "LV",
+  "MT",
+  "NL",
+  "PL",
+  "PT",
+  "RO",
+  "SE",
+  "SI",
+  "SK",
+]);
+
+/** Localized human name for a country code. Falls back to the code
+ *  itself if the runtime can't resolve the name. */
+export function localizedCountryName(code: string, locale: string): string {
+  try {
+    return new Intl.DisplayNames([locale], { type: "region" }).of(code) ?? code;
+  } catch {
+    return code;
+  }
+}
+
+/** Runtime guard for `BookSummary.country`. The type is the union
+ *  `SupportedCountryCode`, but every entry point that takes user /
+ *  LLM input arrives as raw `string` (form submit, JSON-RPC body),
+ *  so the service layer narrows here before persisting. */
+export function isSupportedCountryCode(value: unknown): value is SupportedCountryCode {
+  return typeof value === "string" && (SUPPORTED_COUNTRY_CODES as readonly string[]).includes(value);
+}
+
+/** Country-gated UI features. Each key is a feature name; the value
+ *  is the set of country codes for which the feature is enabled.
+ *  Components ask `countryHasFeature("...", country)` instead of
+ *  hard-coding country lists at the call site.
+ *
+ *  Add a new country-specific feature by adding a new key here and
+ *  reading it via `countryHasFeature`. An unknown / undefined
+ *  country never has any feature — components fall back to neutral
+ *  default UI rather than guessing.
+ *
+ *  Mirrors the "Country-aware tax behaviour" prose in the
+ *  Accounting role prompt (`src/config/roles.ts`). The two MUST
+ *  stay in sync — drift means the LLM and the form give the user
+ *  contradictory advice. The prompt is the source of truth for
+ *  agent behaviour; this table is structured-data sibling for the
+ *  form. */
+export const COUNTRY_FEATURES = {
+  /** Show an amber "missing tax ID" warning + helper text on a
+   *  postable 14xx (input-tax) line whose taxRegistrationId is
+   *  blank. Limited to jurisdictions where the role prompt
+   *  explicitly requires the counterparty registration number
+   *  (JP T-number, EU VAT ID, GB VAT, GSTIN, ABN, NZ GST, CA BN).
+   *  The "other countries" bucket and US (no federal sales-tax
+   *  registration) intentionally stay quiet. 24xx output-tax
+   *  lines don't trigger the warning — see `isTaxAccountCode`. */
+  warnMissingTaxRegistrationId: new Set<SupportedCountryCode>([
+    "JP",
+    "GB",
+    "DE",
+    "FR",
+    "IT",
+    "ES",
+    "NL",
+    "BE",
+    "AT",
+    "IE",
+    "PT",
+    "FI",
+    "SE",
+    "DK",
+    "PL",
+    "IN",
+    "AU",
+    "NZ",
+    "CA",
+  ]),
+} as const;
+
+export type CountryFeature = keyof typeof COUNTRY_FEATURES;
+
+/** Resolve a country-gated feature flag. Returns `false` when the
+ *  country is undefined / unsupported — components default to the
+ *  neutral path (no warning, no extra UI) rather than guessing. */
+export function countryHasFeature(feature: CountryFeature, country: SupportedCountryCode | undefined): boolean {
+  if (!country) return false;
+  return COUNTRY_FEATURES[feature].has(country);
+}

package/src/plugins/accounting/currencies.ts

@@ -0,0 +1,64 @@
+// Currency utilities for the accounting plugin.
+//
+// We expose a curated list of ISO 4217 codes for the New Book
+// dropdown — covering the major reserve currencies plus the most
+// requested Asian / regional ones — plus per-currency formatting
+// helpers built on Intl.NumberFormat.
+//
+// The book's currency is per-book metadata (BookSummary.currency)
+// and only matters once the user has opened the book; cross-book
+// aggregation isn't supported.
+
+/** ISO 4217 codes shown in the New Book dropdown. Curated for
+ *  recognisability — Intl.DisplayNames provides the localised
+ *  human name at render time, so this stays a flat list of codes. */
+export const SUPPORTED_CURRENCY_CODES = ["USD", "EUR", "JPY", "GBP", "CNY", "KRW", "TWD", "HKD", "SGD", "AUD", "CAD", "CHF", "INR", "BRL", "MXN"] as const;
+
+export type SupportedCurrencyCode = (typeof SUPPORTED_CURRENCY_CODES)[number];
+
+const DEFAULT_FALLBACK_DIGITS = 2;
+
+/** Localised human name for a currency code. Falls back to the
+ *  code itself if the runtime can't resolve the name. */
+export function localizedCurrencyName(code: string, locale: string): string {
+  try {
+    return new Intl.DisplayNames([locale], { type: "currency" }).of(code) ?? code;
+  } catch {
+    return code;
+  }
+}
+
+/** Number of fraction digits ISO 4217 specifies for a currency.
+ *  JPY = 0, USD = 2, KWD = 3. Used both for amount formatting and
+ *  for the HTML input step on debit/credit fields. */
+export function fractionDigitsFor(currency: string): number {
+  try {
+    const opts = new Intl.NumberFormat("en", { style: "currency", currency }).resolvedOptions();
+    return opts.maximumFractionDigits ?? DEFAULT_FALLBACK_DIGITS;
+  } catch {
+    return DEFAULT_FALLBACK_DIGITS;
+  }
+}
+
+/** "1" for JPY, "0.01" for USD, "0.001" for KWD. Used as the HTML
+ *  input step on debit/credit fields so a JPY book doesn't let the
+ *  user type cents that would just round-trip back through the
+ *  decimal validator. */
+export function inputStepFor(currency: string): string {
+  const digits = fractionDigitsFor(currency);
+  if (digits === 0) return "1";
+  return (1 / 10 ** digits).toFixed(digits);
+}
+
+/** Locale-aware currency formatter — returns "¥1,130" / "$1,130.00"
+ *  etc. Falls back to fixed-point formatting if the runtime can't
+ *  resolve the currency code; the fallback still respects the
+ *  currency's natural fraction-digit count so JPY shows whole
+ *  numbers even on the slow path. */
+export function formatAmount(value: number, currency: string, locale?: string): string {
+  try {
+    return new Intl.NumberFormat(locale, { style: "currency", currency }).format(value);
+  } catch {
+    return value.toFixed(fractionDigitsFor(currency));
+  }
+}

package/src/plugins/accounting/dates.ts

@@ -0,0 +1,51 @@
+// Local-calendar date helpers for the accounting forms.
+//
+// Why not `new Date().toISOString().slice(0, 10)`? `toISOString` is
+// UTC. In a negative-offset zone (US Pacific, Eastern, …) the UTC
+// date crosses to "tomorrow" several hours before midnight local,
+// so a naively prefilled date input would post entries into the
+// wrong accounting day. Same mistake near month boundaries flips
+// the default Balance Sheet period to the next month.
+//
+// All four helpers below are pure local-calendar formatters built
+// from `getFullYear` / `getMonth` / `getDate`, which the JS engine
+// resolves in the user's local timezone.
+
+function pad2(num: number): string {
+  return String(num).padStart(2, "0");
+}
+
+/** Today as `YYYY-MM-DD` in the user's local timezone. */
+export function localDateString(now: Date = new Date()): string {
+  return `${now.getFullYear()}-${pad2(now.getMonth() + 1)}-${pad2(now.getDate())}`;
+}
+
+/** Current month as `YYYY-MM` in the user's local timezone. */
+export function localMonthString(now: Date = new Date()): string {
+  return `${now.getFullYear()}-${pad2(now.getMonth() + 1)}`;
+}
+
+/** First day of the current calendar year as `YYYY-MM-DD`. */
+export function localStartOfYearString(now: Date = new Date()): string {
+  return `${now.getFullYear()}-01-01`;
+}
+
+/** Previous calendar month as `YYYY-MM` in the user's local timezone. */
+export function previousMonthString(now: Date = new Date()): string {
+  const target = new Date(now.getFullYear(), now.getMonth() - 1, 1);
+  return `${target.getFullYear()}-${pad2(target.getMonth() + 1)}`;
+}
+
+/** Last month of the previous calendar quarter as `YYYY-MM`. Calendar
+ *  quarters: Q1=Jan–Mar, Q2=Apr–Jun, Q3=Jul–Sep, Q4=Oct–Dec. When the
+ *  current month is in Q1, this rolls back to December of last year. */
+export function lastMonthOfPreviousQuarterString(now: Date = new Date()): string {
+  const firstMonthOfCurrentQuarter = Math.floor(now.getMonth() / 3) * 3;
+  const target = new Date(now.getFullYear(), firstMonthOfCurrentQuarter - 1, 1);
+  return `${target.getFullYear()}-${pad2(target.getMonth() + 1)}`;
+}
+
+/** December of the previous calendar year as `YYYY-MM`. */
+export function decemberOfPreviousYearString(now: Date = new Date()): string {
+  return `${now.getFullYear() - 1}-12`;
+}

package/src/plugins/accounting/definition.ts

@@ -0,0 +1,199 @@
+import type { ToolDefinition } from "gui-chat-protocol";
+import { META } from "./meta";
+import { ACCOUNTING_ACTIONS } from "./actions";
+import { SUPPORTED_COUNTRY_CODES } from "./countries";
+import { FISCAL_YEAR_ENDS } from "./fiscalYear";
+import { TIME_SERIES_GRANULARITIES, TIME_SERIES_METRICS } from "./timeSeriesEnums";
+
+// MCP tool definition for the accounting plugin.
+//
+// **Opt-in only.** Not added to any built-in Role's
+// `availablePlugins` (see plans/done/feat-accounting.md hard
+// constraint 1). A user wanting access creates a custom Role and
+// includes `manageAccounting` in its plugin list.
+//
+// The `openBook` action returns an "accounting-app" tool-result
+// envelope that the frontend renderer mounts as the full
+// `<AccountingApp>` View. Every other action returns a compact
+// data payload that renders inline via `Preview.vue`.
+
+const toolDefinition: ToolDefinition = {
+  type: "function",
+  name: META.toolName,
+  prompt:
+    "When the user asks to open / view their books, or to record, look up, or summarise journal entries / balances / opening balances, use manageAccounting. Use action='openBook' (with the target bookId) to switch the canvas to a specific existing book; use the specific action (addEntries / getReport / etc.) for narrowly-scoped operations the user asked about by name. On a fresh workspace call 'createBook' (always pass `country` so tax-registration advice is country-aware) — the accounting view picks up the new book automatically (no follow-up 'openBook' needed for this id). Use 'updateBook' to change a book's name or country (currency cannot be changed). Reach for 'openBook' only when switching to a different existing book. For cross-period charts and dashboards (\"chart my quarterly revenue over the last two years\", \"show net income month-over-month for this fiscal year\", \"plot the cash balance by month\") use action='getTimeSeries' — it returns one chart-ready point per bucket in a single round-trip; do NOT loop over 'getReport' to assemble a series yourself.",
+  description:
+    "Manage a double-entry accounting book stored in the workspace file system. Supports multiple books (entities), opening balances for adoption from existing books, journal entries, voiding (append-only — corrections are reversing pairs), and balance-sheet / profit-loss / ledger reports. Action='openBook' mounts the full accounting UI in the canvas (requires bookId); 'getTimeSeries' returns chart-ready (label, value)[] series for revenue / expense / netIncome / accountBalance over time; specific actions return compact results that render inline.",
+  parameters: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: Object.values(ACCOUNTING_ACTIONS),
+        description:
+          "Operation to perform. 'openBook' mounts the full UI for a specific book; others perform a single read or write. Use 'openBook' when the user wants to browse / interact, and a specific action when the user named the operation.",
+      },
+      bookId: {
+        type: "string",
+        description:
+          "Target book id. Required for every action that reads or writes book data, including 'openBook'; call 'getBooks' first to enumerate available ids. The only actions that do NOT take a bookId are 'getBooks' and 'createBook' (which creates a fresh one).",
+      },
+      // openBook / createBook / updateBook
+      name: { type: "string", description: "For 'createBook' / 'updateBook': human-readable book name." },
+      currency: {
+        type: "string",
+        description: "For 'createBook': ISO 4217 currency code (default USD). Single-currency per book — cannot be changed once set.",
+      },
+      country: {
+        type: "string",
+        // Pinning the enum locks the LLM to the same curated set the
+        // UI dropdown offers and the service-layer guard accepts —
+        // any value outside this list 400s, so emitting a typo or an
+        // unsupported jurisdiction is a wasted tool call. Pass `""`
+        // to 'updateBook' to explicitly clear the country.
+        enum: [...SUPPORTED_COUNTRY_CODES, ""],
+        description:
+          "For 'createBook' / 'updateBook': ISO 3166-1 alpha-2 country code identifying the tax jurisdiction. Drives country-aware advice — e.g. when set to 'JP', strongly suggest the supplier's T-number (適格請求書発行事業者登録番号) on tax-related lines under インボイス制度. Only the codes listed in the enum are accepted; pass an empty string to 'updateBook' to clear the field.",
+      },
+      fiscalYearEnd: {
+        type: "string",
+        enum: [...FISCAL_YEAR_ENDS],
+        description:
+          "For 'createBook' / 'updateBook': which calendar-quarter end is this book's fiscal year end — Q1 = March 31, Q2 = June 30, Q3 = September 30, Q4 = December 31 (calendar year, the default). Drives the date-range shortcuts in the UI ('current quarter', 'current year', etc.). Pure metadata: changing it does not move existing entries.",
+      },
+      initialTab: { type: "string", description: "For 'openBook': initial tab to show (e.g. 'journal', 'opening', 'balanceSheet')." },
+      confirm: { type: "boolean", description: "For 'deleteBook': must be true to actually delete (guard against accidental deletion)." },
+      // accounts
+      account: {
+        type: "object",
+        description: "For 'upsertAccount': the account to insert or update (matched by code).",
+        properties: {
+          code: { type: "string" },
+          name: { type: "string" },
+          type: { type: "string", enum: ["asset", "liability", "equity", "income", "expense"] },
+          note: { type: "string" },
+          active: {
+            type: "boolean",
+            description:
+              "Soft-delete flag. `false` deactivates the account (hides it from entry / ledger dropdowns while keeping it visible in Manage Accounts and historical entries — accounting integrity requires that a code referenced by a journal line never disappears). `true` reactivates a previously-deactivated account. Omit to preserve the existing state — handy when updating name / type / note without touching the active flag.",
+          },
+        },
+        required: ["code", "name", "type"],
+      },
+      // entries (addEntries — batched)
+      entries: {
+        type: "array",
+        description:
+          "For 'addEntries': one or more journal entries to post atomically (all-or-nothing — if any entry fails validation, the whole batch is rejected and nothing is written). Use a single-element array to post one entry. Each entry has its own date, lines, optional memo, and optional replacesEntryId.",
+        items: {
+          type: "object",
+          properties: {
+            date: { type: "string", description: "YYYY-MM-DD booking date." },
+            lines: {
+              type: "array",
+              description: "Journal lines for this entry. Each line sets exactly one of debit or credit (positive amount). Σ debit must equal Σ credit.",
+              items: {
+                type: "object",
+                properties: {
+                  accountCode: { type: "string" },
+                  debit: { type: "number" },
+                  credit: { type: "number" },
+                  memo: { type: "string" },
+                  taxRegistrationId: {
+                    type: "string",
+                    description:
+                      "Optional counterparty tax-authority registration ID for this line (Japan T-number, EU VAT ID, UK VAT registration number, India GSTIN, Australia ABN, etc.). Free-form string, max 32 chars. Required for input-tax-credit eligibility under regimes like Japan's インボイス制度.",
+                  },
+                },
+                required: ["accountCode"],
+              },
+            },
+            memo: { type: "string", description: "Optional entry-level memo." },
+            replacesEntryId: {
+              type: "string",
+              description:
+                "Optional — id of an entry this one replaces (the 'edit' flow). The caller MUST issue a 'voidEntry' for that id immediately before this addEntries call; the void + post pair is not atomic on the server.",
+            },
+          },
+          required: ["date", "lines"],
+        },
+      },
+      // setOpeningBalances — single opening entry (top-level lines / memo)
+      lines: {
+        type: "array",
+        description:
+          "For 'setOpeningBalances': journal lines. Each line sets exactly one of debit or credit (positive amount). Σ debit must equal Σ credit. Only balance-sheet accounts (asset / liability / equity) are accepted.",
+        items: {
+          type: "object",
+          properties: {
+            accountCode: { type: "string" },
+            debit: { type: "number" },
+            credit: { type: "number" },
+            memo: { type: "string" },
+            taxRegistrationId: { type: "string" },
+          },
+          required: ["accountCode"],
+        },
+      },
+      memo: { type: "string", description: "For 'setOpeningBalances': optional entry-level memo." },
+      // void
+      entryId: { type: "string", description: "For 'voidEntry': id of the entry to void. The reverse + marker pair is appended (journal stays append-only)." },
+      reason: { type: "string", description: "For 'voidEntry': human-readable reason." },
+      voidDate: { type: "string", description: "For 'voidEntry': YYYY-MM-DD date for the reverse entry (defaults to today)." },
+      // getJournalEntries / getReport / getTimeSeries ranges
+      from: {
+        type: "string",
+        description:
+          "For 'getJournalEntries': inclusive YYYY-MM-DD lower bound on entry date. For 'getTimeSeries': inclusive YYYY-MM-DD lower bound — the first bucket is the one CONTAINING this date (it can extend earlier).",
+      },
+      to: {
+        type: "string",
+        description:
+          "For 'getJournalEntries': inclusive YYYY-MM-DD upper bound on entry date. For 'getTimeSeries': inclusive YYYY-MM-DD upper bound — the last bucket is the one CONTAINING this date (it can extend later).",
+      },
+      accountCode: {
+        type: "string",
+        description:
+          "For 'getJournalEntries' / 'getReport' (kind=ledger): filter to entries that touch a specific account code. For 'getTimeSeries' with metric='accountBalance': REQUIRED — the account whose closing balance to plot per bucket. Forbidden for the other metrics.",
+      },
+      // getTimeSeries
+      metric: {
+        type: "string",
+        enum: [...TIME_SERIES_METRICS],
+        description:
+          "For 'getTimeSeries': what to plot per bucket. 'revenue' = sum of income-account presentation values within the bucket (positive = money earned). 'expense' = sum of expense accounts within the bucket (positive = money spent). 'netIncome' = revenue − expense (positive = profit). 'accountBalance' = closing balance of `accountCode` at the end of each bucket (cumulative, includes opening balances).",
+      },
+      granularity: {
+        type: "string",
+        enum: [...TIME_SERIES_GRANULARITIES],
+        description:
+          "For 'getTimeSeries': bucket size. 'month' uses calendar months (label format YYYY-MM). 'quarter' and 'year' honour the book's fiscalYearEnd — for a Q4 book they coincide with calendar quarters / years; Q1/Q2/Q3 books shift accordingly. Quarter labels are 'FY{endYear}-Q{1..4}', year labels are 'FY{endYear}'; the FY is named by its END calendar year (e.g. an FY running Apr 2025 – Mar 2026 is FY2026).",
+      },
+      // opening
+      asOfDate: {
+        type: "string",
+        description: "For 'setOpeningBalances': YYYY-MM-DD date the balances are stated as-of. Must be on or before any existing entry.",
+      },
+      // getReport
+      kind: {
+        type: "string",
+        enum: ["balance", "pl", "ledger"],
+        description: "For 'getReport': which report. 'balance' = balance sheet; 'pl' = profit & loss; 'ledger' = per-account running balance.",
+      },
+      period: {
+        type: "object",
+        description: "For 'getReport': either a single closing month or a date range.",
+        properties: {
+          kind: { type: "string", enum: ["month", "range"] },
+          period: { type: "string", description: "For kind='month': YYYY-MM." },
+          from: { type: "string" },
+          to: { type: "string" },
+        },
+        required: ["kind"],
+      },
+    },
+    required: ["action"],
+  },
+};
+
+export default toolDefinition;

package/src/plugins/accounting/fiscalYear.ts

@@ -0,0 +1,136 @@
+// Fiscal-year arithmetic for the accounting plugin.
+//
+// Each book stores a `fiscalYearEnd` token (Q1..Q4) that says which
+// calendar-quarter end is the book's fiscal year end:
+//
+//   Q1 → fiscal year ends March 31     (FY runs Apr 1 → Mar 31)
+//   Q2 → fiscal year ends June 30      (FY runs Jul 1 → Jun 30)
+//   Q3 → fiscal year ends September 30 (FY runs Oct 1 → Sep 30)
+//   Q4 → fiscal year ends December 31  (FY runs Jan 1 → Dec 31; default)
+//
+// "Current quarter" / "current year" everywhere in the UI refer to
+// the *fiscal* quarter / *fiscal* year that contains today, under the
+// active book's `fiscalYearEnd`. For Q4 books fiscal quarters and
+// fiscal years coincide with calendar quarters / calendar years; for
+// the other three a shift applies.
+//
+// All helpers return `YYYY-MM-DD` strings in the user's local
+// timezone — same convention as `dates.ts`.
+
+export const FISCAL_YEAR_ENDS = ["Q1", "Q2", "Q3", "Q4"] as const;
+export type FiscalYearEnd = (typeof FISCAL_YEAR_ENDS)[number];
+
+export const DEFAULT_FISCAL_YEAR_END: FiscalYearEnd = "Q4";
+
+export function isFiscalYearEnd(value: unknown): value is FiscalYearEnd {
+  return typeof value === "string" && (FISCAL_YEAR_ENDS as readonly string[]).includes(value);
+}
+
+/** Books written before the field existed are treated as Q4 in code
+ *  but never auto-rewritten on disk. The settings UI persists through
+ *  the field the next time the user saves anything on the book. */
+export function resolveFiscalYearEnd(value: FiscalYearEnd | undefined): FiscalYearEnd {
+  return value ?? DEFAULT_FISCAL_YEAR_END;
+}
+
+/** Last calendar month (1-12) of the fiscal year for the given Q. */
+export function fiscalYearEndMonth(end: FiscalYearEnd): 3 | 6 | 9 | 12 {
+  if (end === "Q1") return 3;
+  if (end === "Q2") return 6;
+  if (end === "Q3") return 9;
+  return 12;
+}
+
+export interface DateRange {
+  /** Inclusive lower bound (YYYY-MM-DD). Empty string = unbounded. */
+  from: string;
+  /** Inclusive upper bound (YYYY-MM-DD). Empty string = unbounded. */
+  to: string;
+}
+
+function pad2(num: number): string {
+  return String(num).padStart(2, "0");
+}
+
+function lastDayOfMonth(year: number, monthZeroBased: number): number {
+  // Day 0 of next month = last day of this month, all in local time.
+  return new Date(year, monthZeroBased + 1, 0).getDate();
+}
+
+function ymd(year: number, monthOneBased: number, day: number): string {
+  return `${year}-${pad2(monthOneBased)}-${pad2(day)}`;
+}
+
+/** Fiscal quarter index (0..3) of the given local date under `end`,
+ *  where 0 is the first quarter of the fiscal year (right after the
+ *  prior year's close) and 3 is the closing quarter. */
+function fiscalQuarterIndex(end: FiscalYearEnd, today: Date): number {
+  const closingMonth = fiscalYearEndMonth(end); // 1-based
+  const month = today.getMonth() + 1; // 1-based local month
+  // Months past the close of the prior fiscal year, mod 12.
+  const offset = (month - closingMonth - 1 + 12) % 12;
+  return Math.floor(offset / 3);
+}
+
+/** Calendar (year, monthOneBased) of the *first* month of the fiscal
+ *  quarter at index `index` in the fiscal year that *contains*
+ *  `today`. Returned both as the first day of that month and as the
+ *  count of months covered (always 3 — exposed as a constant). */
+function fiscalQuarterStart(end: FiscalYearEnd, today: Date, index: number): { year: number; month: number } {
+  const closingMonth = fiscalYearEndMonth(end);
+  const todayMonth = today.getMonth() + 1;
+  const todayYear = today.getFullYear();
+  // Month after the close of the prior fiscal year — fiscal-year start month.
+  const startMonth = (closingMonth % 12) + 1;
+  // The fiscal year that contains `today` started in the calendar
+  // year ≤ today's year. Specifically: if today's calendar month is
+  // ≥ startMonth (or startMonth is 1, which is the Q4 case), the FY
+  // started this calendar year; otherwise it started last year.
+  const fyStartYear = todayMonth >= startMonth ? todayYear : todayYear - 1;
+  // Month of the requested fiscal quarter's first month, expressed
+  // as a 1-based offset from January of fyStartYear.
+  const flatMonth = startMonth + index * 3; // 1-based, may exceed 12
+  const year = fyStartYear + Math.floor((flatMonth - 1) / 12);
+  const month = ((flatMonth - 1) % 12) + 1;
+  return { year, month };
+}
+
+function quarterRangeAt(end: FiscalYearEnd, today: Date, index: number): DateRange {
+  const start = fiscalQuarterStart(end, today, index);
+  // Quarter spans 3 calendar months starting at `start`.
+  const lastMonthFlat = start.month - 1 + 2; // 0-based offset of the third month
+  const lastMonthYear = start.year + Math.floor(lastMonthFlat / 12);
+  const lastMonth = (lastMonthFlat % 12) + 1; // 1-based
+  const lastDay = lastDayOfMonth(lastMonthYear, lastMonth - 1);
+  return {
+    from: ymd(start.year, start.month, 1),
+    to: ymd(lastMonthYear, lastMonth, lastDay),
+  };
+}
+
+export function currentQuarterRange(end: FiscalYearEnd, today: Date = new Date()): DateRange {
+  return quarterRangeAt(end, today, fiscalQuarterIndex(end, today));
+}
+
+export function previousQuarterRange(end: FiscalYearEnd, today: Date = new Date()): DateRange {
+  const idx = fiscalQuarterIndex(end, today);
+  if (idx > 0) return quarterRangeAt(end, today, idx - 1);
+  // Wrap to Q4 of the prior fiscal year. Step `today` back 3 months
+  // — that lands inside the prior fiscal year regardless of `end`,
+  // and Q4 (closing) is index 3 within whichever FY contains it.
+  const stepped = new Date(today.getFullYear(), today.getMonth() - 3, 1);
+  return quarterRangeAt(end, stepped, 3);
+}
+
+/** Current fiscal year — Q0 start through Q3 close. */
+export function currentFiscalYearRange(end: FiscalYearEnd, today: Date = new Date()): DateRange {
+  const first = quarterRangeAt(end, today, 0);
+  const last = quarterRangeAt(end, today, 3);
+  return { from: first.from, to: last.to };
+}
+
+export function previousFiscalYearRange(end: FiscalYearEnd, today: Date = new Date()): DateRange {
+  // Step a year back so `quarterRangeAt` resolves the prior FY.
+  const stepped = new Date(today.getFullYear() - 1, today.getMonth(), today.getDate());
+  return currentFiscalYearRange(end, stepped);
+}

package/src/plugins/accounting/index.ts

@@ -0,0 +1,49 @@
+import type { PluginRegistration, ToolPlugin } from "../../tools/types";
+import type { ToolResult } from "gui-chat-protocol";
+import View from "./View.vue";
+import Preview from "./Preview.vue";
+import toolDefinition from "./definition";
+import { META } from "./meta";
+import { wrapWithScope } from "../scope";
+import { apiCall } from "../../utils/api";
+import { makeUuid } from "../../utils/id";
+
+// MulmoClaude never invokes `execute()` at runtime (see ToolPlugin
+// contract in src/tools/types.ts) — Claude → MCP → REST goes
+// straight to /api/accounting. The implementation is kept as a
+// one-line passthrough to satisfy the gui-chat-protocol shape.
+export type AccountingActionData = Record<string, unknown>;
+
+const accountingPlugin: ToolPlugin<AccountingActionData> = {
+  toolDefinition,
+
+  async execute(_context, args) {
+    const toolName = toolDefinition.name;
+    const { method, path } = META.apiRoutes.dispatch;
+    const result = await apiCall<ToolResult<AccountingActionData>>(`/api/${META.apiNamespace}${path}`, { method, body: args });
+    if (!result.ok) {
+      return {
+        toolName,
+        uuid: makeUuid(),
+        message: result.error,
+      };
+    }
+    return {
+      ...result.data,
+      toolName,
+      uuid: result.data.uuid ?? makeUuid(),
+    };
+  },
+
+  isEnabled: () => true,
+  generatingMessage: "Working on the books...",
+  viewComponent: wrapWithScope("accounting", View),
+  previewComponent: wrapWithScope("accounting", Preview),
+};
+
+export default accountingPlugin;
+
+export const REGISTRATION: PluginRegistration = {
+  toolName: META.toolName,
+  entry: accountingPlugin,
+};