@frihet/mcp-server 1.16.5 → 1.17.0

package/dist/tools/shared.js

@@ -9,6 +9,7 @@
 import { z } from "zod/v4";
 import { log, logToolCall } from "../logger.js";
 import { recordToolCall } from "../metrics.js";
+import { sanitizeServerRemediation } from "../redaction.js";
 /* ------------------------------------------------------------------ */
 /*  Safety annotations for MCP tool registrations                      */
 /* ------------------------------------------------------------------ */
@@ -43,47 +44,73 @@ export const ERROR_CONTENT_ANNOTATIONS = {
 /*  Response size guard                                                */
 /* ------------------------------------------------------------------ */
 const MAX_RESPONSE_CHARS = 80_000; // ~20,000 tokens safety margin
-export function truncateResponse(text) {
+export function truncateResponse(text, truncatedNotice = '\n\n[Response truncated. Use pagination (limit/offset) to retrieve smaller result sets.]') {
     if (text.length <= MAX_RESPONSE_CHARS)
         return text;
-    return text.slice(0, MAX_RESPONSE_CHARS) +
-        '\n\n[Response truncated. Use pagination (limit/offset) to retrieve smaller result sets.]';
+    return text.slice(0, MAX_RESPONSE_CHARS) + truncatedNotice;
 }
 function isFrihetApiError(error) {
     return (typeof error === "object" &&
         error !== null &&
         "statusCode" in error &&
         "errorCode" in error &&
-        typeof error.statusCode === "number");
+        typeof error.statusCode === "number" &&
+        typeof error.errorCode === "string" &&
+        typeof error.message === "string");
 }
+const FORBIDDEN_FRIENDLY_MESSAGE = "Access denied. Reconnect Frihet or use configured credentials with permission for this action. / Acceso denegado. Vuelve a conectar Frihet o usa credenciales con permiso para esta accion.";
 /**
  * Maps an error to a user-friendly MCP tool response with error annotations.
  * Emits structured log entries for all errors.
  */
 export function handleToolError(error, toolName) {
     if (isFrihetApiError(error)) {
+        const loggedMessage = error.statusCode === 403 ? "Forbidden" : error.message;
+        const loggedCode = error.statusCode === 403 ? "forbidden" : error.errorCode;
         log({
             level: "error",
-            message: `API error: ${error.statusCode} ${error.errorCode}: ${error.message}`,
+            message: `API error: ${error.statusCode} ${loggedCode}: ${loggedMessage}`,
             tool: toolName,
             operation: "tool_error",
             error: {
-                message: error.message,
-                code: error.errorCode,
+                message: loggedMessage,
+                code: loggedCode,
                 statusCode: error.statusCode,
             },
         });
         const messages = {
             400: "Bad request. Check your input parameters. / Solicitud incorrecta. Revisa los parametros.",
-            401: "Authentication failed. Check your API key. / Autenticacion fallida. Revisa tu API key.",
-            403: "Access denied. Your API key does not have permission for this action. / Acceso denegado.",
+            401: "Authentication failed. Reconnect Frihet or check the configured credentials. / Autenticacion fallida. Vuelve a conectar Frihet o revisa las credenciales configuradas.",
+            403: FORBIDDEN_FRIENDLY_MESSAGE,
             404: "Resource not found. / Recurso no encontrado.",
             405: "Method not allowed. / Metodo no permitido.",
             413: "Request body too large (max 1MB). / Cuerpo de la solicitud demasiado grande (max 1MB).",
             429: "Rate limit exceeded. Try again later. / Limite de peticiones excedido. Intenta mas tarde.",
             500: "Internal server error. Try again later. / Error interno del servidor.",
+            503: "Frihet could not confirm the request outcome because the network connection failed.",
         };
-        const friendlyMessage = messages[error.statusCode] ?? `API error ${error.statusCode}. Contact support if this persists.`;
+        const transportOutcomeUnknown = error.errorCode === "request_timeout" || error.errorCode === "network_error";
+        const operationOutcomeUnknown = transportOutcomeUnknown
+            || error.errorCode === "response_timeout"
+            || error.errorCode === "invalid_response_after_success"
+            || (error.statusCode >= 500 && error.statusCode <= 599)
+            || (error.statusCode === 409
+                && error.errorCode.toUpperCase() === "IDEMPOTENCY_REQUEST_IN_PROGRESS");
+        let friendlyMessage;
+        if (error.statusCode === 413 && error.errorCode === "payload_too_large") {
+            friendlyMessage = `Document response too large: ${error.message} / Respuesta de documento demasiado grande.`;
+        }
+        else if (error.statusCode === 403) {
+            const guidance = sanitizeServerRemediation(error.detail, error.errorCode)
+                ?? sanitizeServerRemediation(error.message, error.errorCode);
+            friendlyMessage = guidance
+                ? `${FORBIDDEN_FRIENDLY_MESSAGE} Server guidance: ${guidance}`
+                : FORBIDDEN_FRIENDLY_MESSAGE;
+        }
+        else {
+            friendlyMessage = messages[error.statusCode]
+                ?? `API error ${error.statusCode}. Contact support if this persists.`;
+        }
         return {
             content: [
                 {
@@ -93,6 +120,16 @@ export function handleToolError(error, toolName) {
                 },
             ],
             isError: true,
+            ...(operationOutcomeUnknown
+                ? {
+                    _meta: {
+                        "io.frihet/operationOutcomeUnknown": true,
+                        ...(transportOutcomeUnknown
+                            ? { "io.frihet/transportOutcomeUnknown": true }
+                            : {}),
+                    },
+                }
+                : {}),
         };
     }
     const errMsg = error instanceof Error ? error.stack ?? error.message : String(error);
@@ -132,6 +169,15 @@ export function formatPaginatedResponse(resourceName, response) {
     }
     return truncateResponse(lines.join("\n"));
 }
+/** Format an exhaustive list whose backend exposes no pagination controls. */
+export function formatUnpaginatedListResponse(resourceName, response) {
+    const lines = [`Found ${response.total} ${resourceName}:`, ""];
+    for (const item of response.data) {
+        lines.push(JSON.stringify(item, null, 2));
+        lines.push("---");
+    }
+    return truncateResponse(lines.join("\n"), "\n\n[Response truncated.]");
+}
 /**
  * Formats a single record for display.
  */
@@ -157,11 +203,22 @@ export function mutateContent(text) {
     return { type: "text", text, annotations: MUTATE_CONTENT_ANNOTATIONS };
 }
 /* ------------------------------------------------------------------ */
-/*  Contextual enrichment — _suggestions and _warnings                 */
+/*  Contextual enrichment — text appended to `content`, not structuredContent */
 /* ------------------------------------------------------------------ */
 /**
- * Adds contextual suggestions and warnings to tool responses.
- * Helps AI agents know what to do next without guessing.
+ * Returns agent-facing suggestions and warnings for a tool call, formatted
+ * as plain text to be APPENDED to the human-readable `content` block.
+ *
+ * Why text, not structured fields: `structuredContent` is the strict
+ * outputSchema contract. Spreading `{ _suggestions, _warnings }` into
+ * structuredContent would make them undeclared enrichment (Inspector /
+ * conformance failures, drift in the OpenAI reviewed surface's frozen
+ * snapshot). The hints are agent-facing and deterministic from the
+ * emitted data, so they belong in the text the model reads, not in the
+ * JSON the schema validates. Pinned by
+ * src/__tests__/paginated-strict-output.test.ts (ERP #1580): the strict
+ * contract test asserts structuredContent never carries the old
+ * `_suggestions` / `_warnings` keys.
  */
 export function enrichResponse(resource, operation, data) {
     const suggestions = [];
@@ -237,10 +294,20 @@ export function enrichResponse(resource, operation, data) {
     if (operation === "delete") {
         warnings.push("This action cannot be undone / Esta accion no se puede deshacer");
     }
-    return {
-        ...(suggestions.length > 0 ? { _suggestions: suggestions } : {}),
-        ...(warnings.length > 0 ? { _warnings: warnings } : {}),
-    };
+    if (suggestions.length === 0 && warnings.length === 0)
+        return "";
+    const lines = [];
+    if (warnings.length > 0) {
+        lines.push("Warnings:");
+        for (const w of warnings)
+            lines.push(`  - ${w}`);
+    }
+    if (suggestions.length > 0) {
+        lines.push("Suggested next steps:");
+        for (const s of suggestions)
+            lines.push(`  - ${s}`);
+    }
+    return "\n" + lines.join("\n");
 }
 /* ------------------------------------------------------------------ */
 /*  Output schemas (MCP spec 2025-11-25: outputSchema + structuredContent) */
@@ -268,6 +335,15 @@ export function paginatedOutput(itemSchema, opts = {}) {
     // so they keep the item schema's own required contract (an `{}` row there is
     // an API regression the schema must catch, not tolerate).
     const rowSchema = opts.projectable ? itemSchema.partial() : itemSchema;
+    // Canonical envelope contract: the emitted `structuredContent` of every
+    // paginated tool is exactly this object. The MCP SDK validates the runtime
+    // value against this schema on every call; anything not declared here is
+    // an Inspector/conformance failure. Pinned by
+    // src/__tests__/paginated-strict-output.test.ts (ERP #1580). The
+    // OpenAI reviewed surface's frozen snapshot (`openai-review-descriptor`)
+    // is a byte contract on this shape, so adding a field here would drift
+    // the snapshot — the right place for agent-facing hints is the `content`
+    // text block, not `structuredContent` (see enrichResponse).
     return z.object({
         data: z.array(rowSchema),
         total: z.number(),
@@ -281,6 +357,32 @@ export const deleteResultOutput = z.object({
     success: z.boolean(),
     id: z.string(),
 });
+/**
+ * Schema for deletes of FISCAL DOCUMENTS (invoices, quotes) — the only two
+ * resources where "delete" is not always a delete.
+ *
+ * The backend refuses to destroy a non-draft invoice/quote (VeriFactu hash
+ * chain) and soft-CANCELS it instead, distinguishing the outcomes on the wire:
+ * 204 = row destroyed, 200 + body = document kept with status=cancelled
+ * (erp-main publicApi.ts `deleteResource`). `outcome` is what lets an agent
+ * tell the user which one actually happened (GAP-12).
+ *
+ * Deliberately NOT folded into {@link deleteResultOutput}: that one is shared by
+ * nine non-fiscal delete tools whose backend has no cancel branch, and widening
+ * it would drift their published output schema for no behavioural reason.
+ */
+export const documentDeleteResultOutput = z.object({
+    success: z.boolean(),
+    id: z.string(),
+    /** "deleted" = row destroyed (204). "cancelled" = document kept, status=cancelled (200). */
+    outcome: z.enum(["deleted", "cancelled"]).optional(),
+    /** Document status after a soft cancel (always "cancelled" when present). */
+    status: z.string().optional(),
+    /** Status the document held before it was cancelled (e.g. "sent", "paid"). */
+    previousStatus: z.string().optional(),
+    /** Backend path that performed the soft cancellation, when reported. */
+    cancelledVia: z.string().optional(),
+});
 /**
  * Permissive structured-output schema for tools whose API returns an open
  * `Record<string, unknown>` (summaries, single-object actions, VIES/portal
@@ -296,9 +398,12 @@ export function openObjectOutput(description) {
 }
 /* --- Per-resource item schemas ------------------------------------ */
 const lineItemSchema = z.object({
+    id: z.string().optional(),
     description: z.string(),
     quantity: z.number(),
     unitPrice: z.number(),
+    taxRate: z.number().optional(),
+    discount: z.number().optional(),
 });
 export const invoiceItemOutput = z.object({
     id: z.string(),
@@ -306,6 +411,7 @@ export const invoiceItemOutput = z.object({
     // draft — verified live. Kept documented but non-required so get/create/update
     // of a draft or a client-less invoice validates. `id` stays required: every
     // single-object read/create/update returns the doc id.
+    clientId: z.string().optional(),
     clientName: z.string().nullable().optional(),
     items: z.array(lineItemSchema).optional(),
     issueDate: z.string().optional(),
@@ -313,6 +419,7 @@ export const invoiceItemOutput = z.object({
     status: z.string().optional(),
     notes: z.string().optional(),
     taxRate: z.number().optional(),
+    discountRate: z.number().optional(),
     total: z.number().optional(),
     createdAt: z.string().optional(),
     updatedAt: z.string().optional(),
@@ -323,8 +430,10 @@ export const expenseItemOutput = z.object({
     amount: z.number(),
     category: z.string().optional(),
     date: z.string().optional(),
+    vendorId: z.string().optional(),
     vendor: z.string().optional(),
     taxDeductible: z.boolean().optional(),
+    paidDate: z.string().optional(),
     createdAt: z.string().optional(),
     updatedAt: z.string().optional(),
 }).passthrough();
@@ -340,6 +449,7 @@ export const clientItemOutput = z.object({
     name: z.string(),
     email: z.string().optional(),
     phone: z.string().optional(),
+    stage: z.string().optional(),
     taxId: z.string().optional(),
     address: addressOutputSchema,
     createdAt: z.string().optional(),
@@ -351,18 +461,24 @@ export const productItemOutput = z.object({
     unitPrice: z.number(),
     description: z.string().optional(),
     taxRate: z.number().optional(),
+    isActive: z.boolean().optional(),
     createdAt: z.string().optional(),
     updatedAt: z.string().optional(),
 }).passthrough();
 export const quoteItemOutput = z.object({
     id: z.string(),
     // Same draft/client-less tolerance as invoices (shared form engine).
+    clientId: z.string().optional(),
     clientName: z.string().nullable().optional(),
     items: z.array(lineItemSchema).optional(),
+    issueDate: z.string().optional(),
+    dueDate: z.string().optional(),
     validUntil: z.string().optional(),
     notes: z.string().optional(),
     status: z.string().optional(),
     total: z.number().optional(),
+    taxRate: z.number().optional(),
+    discountRate: z.number().optional(),
     createdAt: z.string().optional(),
     updatedAt: z.string().optional(),
 }).passthrough();
@@ -378,13 +494,31 @@ export const vendorItemOutput = z.object({
 }).passthrough();
 export const webhookItemOutput = z.object({
     id: z.string(),
+    userId: z.string().optional(),
+    name: z.string(),
     url: z.string(),
     events: z.array(z.string()),
-    active: z.boolean().optional(),
-    secret: z.string().optional(),
+    status: z.enum(["active", "inactive", "paused"]),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    hasSecret: z.boolean(),
+    pausedReason: z.string().optional(),
+    lastTriggeredAt: z.string().optional(),
     createdAt: z.string().optional(),
     updatedAt: z.string().optional(),
-}).passthrough();
+    _demo: z.literal(true).optional(),
+    _demoNotice: z.string().optional(),
+}).strict();
+/** Create alone may echo the caller-supplied signing secret once. */
+export const webhookCreateOutput = webhookItemOutput.extend({
+    secret: z.string().optional(),
+}).strict();
+/** `/webhooks` has no backend pagination contract. */
+export const webhookListOutput = z.object({
+    data: z.array(webhookItemOutput),
+    total: z.number(),
+    _demo: z.literal(true).optional(),
+    _demoNotice: z.string().optional(),
+}).strict();
 /* --- CRM subcollection item schemas -------------------------------- */
 export const contactItemOutput = z.object({
     id: z.string(),
@@ -401,10 +535,14 @@ export const activityItemOutput = z.object({
     type: z.string(),
     title: z.string(),
     description: z.string().optional(),
-    date: z.string().optional(),
+    metadata: z.record(z.string(), z.string()).optional(),
+    timestamp: z.string(),
+    createdBy: z.enum(["system", "user"]).optional(),
     createdAt: z.string().optional(),
     updatedAt: z.string().optional(),
-}).passthrough();
+    _demo: z.literal(true).optional(),
+    _demoNotice: z.string().optional(),
+}).strict();
 export const noteItemOutput = z.object({
     id: z.string(),
     content: z.string(),
@@ -543,6 +681,7 @@ export const actionResultOutput = z.object({
     success: z.boolean().optional(),
     id: z.string().optional(),
     message: z.string().optional(),
+    messageId: z.string().optional(),
     // Anti-envelope tripwire: with everything optional + passthrough, a raw
     // {data, meta} API envelope would otherwise VALIDATE — silently re-hiding the
     // exact bug this PR fixes if a client method ever regresses to raw request().
@@ -568,6 +707,9 @@ export const creditNoteResultOutput = z.object({
         originalInvoiceId: z.string().optional(),
         reason: z.string().optional(),
         fullCredit: z.boolean().optional(),
+        status: z.string().optional(),
+        rectificationMethod: z.string().optional(),
+        totalCredited: z.number().optional(),
     }).passthrough().optional(),
     // Anti-envelope tripwire — see actionResultOutput.
     data: z.never().optional(),
@@ -729,11 +871,32 @@ export const recurringInvoiceItemOutput = z.object({
     createdAt: z.string().optional(),
     updatedAt: z.string().optional(),
 }).passthrough();
-/** Schema for PDF results */
+/**
+ * Schema for the MIME-discriminated `get_invoice_einvoice` artifact.
+ *
+ * Stored UBL/Facturae artifacts return strict UTF-8 `xml`; Factur-X artifacts
+ * return PDF bytes as `base64`. Identity, MIME and byte size are always present.
+ */
+export const einvoiceResultOutput = z.object({
+    id: z.string(),
+    contentType: z.string(),
+    sizeBytes: z.number().int().nonnegative(),
+    xml: z.string().optional(),
+    base64: z.string().optional(),
+    filename: z.string().optional(),
+}).passthrough().refine((value) => (typeof value.xml === "string") !== (typeof value.base64 === "string"), { message: "Exactly one of xml or base64 is required" });
+/**
+ * Schema for `get_invoice_pdf` results (#1393 — content-type-aware).
+ *
+ * The backend serves raw `application/pdf` bytes. MCP `structuredContent` is
+ * JSON-only, so callers receive bounded base64 plus request identity and size.
+ */
 export const pdfResultOutput = z.object({
     id: z.string(),
-    url: z.string().optional(),
-    contentType: z.string().optional(),
+    contentType: z.string(),
+    sizeBytes: z.number().int().nonnegative(),
+    base64: z.string(),
+    filename: z.string().optional(),
 }).passthrough();
 /* --- Time summary schema --------------------------------------------------- */
 const timeSummaryGroupItemSchema = z.object({
@@ -756,14 +919,15 @@ export const timeSummaryOutput = z.object({
 /* --- Team member item schema ----------------------------------------------- */
 export const teamMemberItemOutput = z.object({
     id: z.string(),
-    name: z.string().optional(),
-    email: z.string(),
-    role: z.enum(["owner", "admin", "member", "viewer"]).optional(),
+    name: z.string().nullable().optional(),
+    email: z.string().nullable().optional(),
+    role: z.enum(["owner", "admin", "editor", "accountant", "viewer"]).optional(),
     status: z.enum(["active", "pending"]).optional(),
-    invitedAt: z.string().optional(),
-    joinedAt: z.string().optional(),
-    createdAt: z.string().optional(),
-    updatedAt: z.string().optional(),
+    invitedAt: z.string().nullable().optional(),
+    joinedAt: z.string().nullable().optional(),
+    createdAt: z.string().nullable().optional(),
+    updatedAt: z.string().nullable().optional(),
+    expiresAt: z.string().nullable().optional(),
 }).passthrough();
 /* --- Gestoria item schemas ------------------------------------------------- */
 /**
@@ -885,19 +1049,40 @@ export const attendanceEntryItemOutput = z.object({
     createdAt: z.string().optional(),
     updatedAt: z.string().optional(),
 }).passthrough();
-/** Overtime aggregated report. */
+/** Exact ERP DTO for `GET /v1/time-entries/overtime`. */
 export const overtimeReportOutput = z.object({
-    period: z.string(),
-    totalRegularHours: z.number().optional(),
-    totalOvertimeHours: z.number().optional(),
-    estimatedCostEur: z.number().optional(),
-    byEmployee: z.array(z.object({
-        employeeId: z.string(),
-        employeeName: z.string().optional(),
-        regularHours: z.number().optional(),
-        overtimeHours: z.number().optional(),
-    }).passthrough()).optional(),
-    generatedAt: z.string().optional(),
+    period: z.string().regex(/^\d{4}(-(0[1-9]|1[0-2]))?$/),
+    employeeId: z.string().nullable(),
+    recordCount: z.number().int().nonnegative(),
+    dailyOvertime: z.array(z.object({
+        date: z.string(),
+        minutes: z.number().nonnegative(),
+        exceedsDaily: z.boolean(),
+    })),
+    weeklyOvertime: z.array(z.object({
+        weekStart: z.string(),
+        totalMinutes: z.number().nonnegative(),
+        overtimeMinutes: z.number().nonnegative(),
+    })),
+    monthlyTotal: z.object({
+        workedMinutes: z.number().nonnegative(),
+        overtimeMinutes: z.number().nonnegative(),
+        regularMinutes: z.number().nonnegative(),
+    }),
+    annualOvertimeHours: z.number().nonnegative(),
+    alerts: z.array(z.object({
+        type: z.enum(["daily_exceeded", "weekly_exceeded", "annual_approaching", "annual_exceeded", "missing_break"]),
+        severity: z.enum(["warning", "critical"]),
+        message: z.string(),
+        date: z.string(),
+    })),
+    data: z.never().optional(),
+    meta: z.never().optional(),
+    totalRegularHours: z.never().optional(),
+    totalOvertimeHours: z.never().optional(),
+    estimatedCostEur: z.never().optional(),
+    byEmployee: z.never().optional(),
+    generatedAt: z.never().optional(),
 }).passthrough();
 /** Anomaly detection record — backend `/v1/anomalies`. */
 export const anomalyItemOutput = z.object({
@@ -922,28 +1107,60 @@ export const webhookTestResultOutput = z.object({
     attemptedAt: z.string().optional(),
     error: z.string().optional(),
 }).passthrough();
-/** Payroll export result — backend `/v1/payroll/prep/export`. */
+/** Exact normalized dataset DTO from `GET /v1/payroll/prep/export`. */
 export const payrollExportOutput = z.object({
-    format: z.enum(["a3", "contasol", "sage", "holded", "siltra"]),
-    month: z.string(),
-    fileUrl: z.string().optional(),
-    filename: z.string().optional(),
-    rowCount: z.number().int().optional(),
-    generatedAt: z.string().optional(),
+    month: z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/),
+    format: z.enum(["a3", "contasol", "sage", "siltra"]),
+    employees: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        nss: z.string(),
+        irpfPct: z.number(),
+        salaryGrossAnnual: z.number(),
+        convenioColectivo: z.string().nullable(),
+        categoriaProfesional: z.string().nullable(),
+        prorrateoPagasExtras: z.boolean().nullable(),
+        formaPago: z.enum(["transferencia", "efectivo", "cheque"]),
+        iban: z.string().nullable(),
+    })),
+    summary: z.object({
+        exportedCount: z.number().int().nonnegative(),
+        skippedNotReady: z.number().int().nonnegative(),
+        totalGrossAnnual: z.number(),
+    }),
+    data: z.never().optional(),
+    meta: z.never().optional(),
+    fileUrl: z.never().optional(),
+    filename: z.never().optional(),
+    rowCount: z.never().optional(),
+    generatedAt: z.never().optional(),
 }).passthrough();
-/** Payroll checklist — backend `/v1/payroll/prep/employees`. */
+/** Exact readiness DTO from `GET /v1/payroll/prep/employees`. */
 export const payrollChecklistOutput = z.object({
-    month: z.string(),
-    totalEmployees: z.number().int().optional(),
-    readyEmployees: z.number().int().optional(),
-    missingEmployees: z.number().int().optional(),
+    month: z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/),
     employees: z.array(z.object({
-        employeeId: z.string(),
-        employeeName: z.string().optional(),
-        status: z.enum(["ready", "missing_data", "blocked"]).optional(),
-        missingFields: z.array(z.string()).optional(),
-    }).passthrough()).optional(),
-    generatedAt: z.string().optional(),
+        id: z.string(),
+        name: z.string(),
+        status: z.enum(["active", "onLeave"]),
+        hasPayrollProfile: z.boolean(),
+        ready: z.boolean(),
+        missingFields: z.array(z.enum(["nss", "irpfPct", "salaryGrossAnnual", "formaPago", "iban"])),
+        reviewedForMonth: z.string().nullable(),
+        reviewedThisMonth: z.boolean(),
+        reviewedAt: z.string().nullable(),
+    })),
+    summary: z.object({
+        total: z.number().int().nonnegative(),
+        ready: z.number().int().nonnegative(),
+        notReady: z.number().int().nonnegative(),
+        reviewedThisMonth: z.number().int().nonnegative(),
+    }),
+    data: z.never().optional(),
+    meta: z.never().optional(),
+    totalEmployees: z.never().optional(),
+    readyEmployees: z.never().optional(),
+    missingEmployees: z.never().optional(),
+    generatedAt: z.never().optional(),
 }).passthrough();
 /** Onboarding workspace state — backend `/v1/onboarding/status`. */
 export const onboardingStatusOutput = z.object({
@@ -961,23 +1178,82 @@ export const onboardingPersonaResultOutput = z.object({
     persona: z.enum(["autonomo", "empresa", "agencia", "gestoria"]),
     updatedAt: z.string().optional(),
 }).passthrough();
-/** Permissions matrix — backend `/v1/permissions/matrix`. */
+const rbacRoleOutput = z.enum(["owner", "admin", "manager", "sales", "accountant", "employee", "viewer"]);
+const rbacResourceOutput = z.enum([
+    "workspace", "invoices", "quotes", "expenses", "clients", "products", "accounting",
+    "people", "payroll", "integrations", "banking", "settings", "audit_log", "billing",
+]);
+const rbacActionOutput = z.enum(["read", "create", "update", "delete", "bulk_delete", "export"]);
+const rbacActionsOutput = z.array(rbacActionOutput);
+// Matrix rows intentionally omit denied resources. Keep every known resource
+// explicit and optional so sparse backend rows validate consistently.
+const rbacResourceGrantsOutput = z.object({
+    workspace: rbacActionsOutput.optional(),
+    invoices: rbacActionsOutput.optional(),
+    quotes: rbacActionsOutput.optional(),
+    expenses: rbacActionsOutput.optional(),
+    clients: rbacActionsOutput.optional(),
+    products: rbacActionsOutput.optional(),
+    accounting: rbacActionsOutput.optional(),
+    people: rbacActionsOutput.optional(),
+    payroll: rbacActionsOutput.optional(),
+    integrations: rbacActionsOutput.optional(),
+    banking: rbacActionsOutput.optional(),
+    settings: rbacActionsOutput.optional(),
+    audit_log: rbacActionsOutput.optional(),
+    billing: rbacActionsOutput.optional(),
+}).strict();
+const rbacMatrixOutput = z.object({
+    owner: rbacResourceGrantsOutput,
+    admin: rbacResourceGrantsOutput,
+    manager: rbacResourceGrantsOutput,
+    sales: rbacResourceGrantsOutput,
+    accountant: rbacResourceGrantsOutput,
+    employee: rbacResourceGrantsOutput,
+    viewer: rbacResourceGrantsOutput,
+}).strict();
+/**
+ * Documented RBAC-model snapshot — backend `/v1/permissions/matrix`.
+ * This is not an exhaustive report of runtime authorization or Firestore rules.
+ */
 export const permissionsMatrixOutput = z.object({
-    roles: z.array(z.object({
-        role: z.string(),
-        permissions: z.array(z.string()),
-    }).passthrough()).optional(),
-    resources: z.array(z.string()).optional(),
-    generatedAt: z.string().optional(),
+    roles: z.array(rbacRoleOutput).describe("Role names represented by this documented RBAC model"),
+    resources: z.array(rbacResourceOutput).describe("Resource names represented by this documented RBAC model"),
+    actions: z.array(rbacActionOutput).describe("Action names represented by this documented RBAC model"),
+    legacyAliases: z.record(z.string(), rbacRoleOutput).describe("Legacy role name to canonical RBAC-model role"),
+    matrix: rbacMatrixOutput
+        .describe("Documented role/resource/action grants; not a runtime authorization guarantee"),
+    source: z.string().describe("Backend explanation of the model's source and limitations"),
 }).passthrough();
-/** Caller's own permissions — backend `/v1/permissions/me`. */
+/**
+ * Caller's RBAC-model row and API-key scope state — backend `/v1/permissions/me`.
+ * Known denials are intentionally non-exhaustive; a backend 403 is authoritative.
+ */
 export const permissionsMeOutput = z.object({
-    userId: z.string().optional(),
-    role: z.string().optional(),
-    permissions: z.array(z.string()).optional(),
-    workspaceId: z.string().optional(),
+    role: rbacRoleOutput.describe("Backwards-compatible RBAC-model role"),
+    isOwner: z.boolean().describe("Backwards-compatible RBAC-model owner flag"),
+    resources: rbacResourceGrantsOutput.describe("Backwards-compatible RBAC-model resource grants"),
+    scopes: z.array(z.string()).describe("Backwards-compatible RBAC capabilities; not API-key scopes"),
+    legacyFieldSemantics: z.object({
+        resources: z.literal("rbacResources"),
+        scopes: z.literal("rbacCapabilities"),
+    }).describe("Explicit meaning of the backwards-compatible resources/scopes fields"),
+    rbac: z.object({
+        role: rbacRoleOutput,
+        isOwner: z.boolean(),
+        resources: rbacResourceGrantsOutput,
+        capabilities: z.array(z.string()),
+    }).describe("Documented RBAC-model view; not an exhaustive authorization prediction"),
+    apiKeyScopes: z.array(z.string()).describe("Actual scopes stored for this API key"),
+    apiKeyUnrestricted: z.boolean().describe("Whether empty/absent stored scopes use unrestricted-key semantics"),
+    denied: z.object({
+        einvoice: z.boolean(),
+    }).describe("Known API-key-scope denials only"),
+    deniedSemantics: z.string().describe("Backend limitation statement for denied"),
+    notIncluded: z.array(z.enum(["featureFlags", "deployedEndpoints"]))
+        .describe("Authorization surfaces this endpoint cannot truthfully report"),
 }).passthrough();
-/** Accounting period state — backend `/v1/periods/*`. */
+/** Legacy demo/write result retained for period_close and period_reopen only. */
 export const periodStatusOutput = z.object({
     id: z.string(),
     type: z.enum(["monthly", "quarterly"]).optional(),
@@ -991,6 +1267,35 @@ export const periodStatusOutput = z.object({
     createdAt: z.string().optional(),
     updatedAt: z.string().optional(),
 }).passthrough();
+/** Exact ERP DTO for `GET /v1/periods/current` and `GET /v1/periods/YYYY`. */
+export const currentPeriodOutput = z.object({
+    fiscalYear: z.string().regex(/^\d{4}$/),
+    fiscalYearStart: z.string().regex(/^\d{2}-\d{2}$/),
+    status: z.enum(["open", "closed"]),
+    dateRange: z.object({
+        from: z.string(),
+        to: z.string(),
+    }),
+    closing: z.object({
+        status: z.string(),
+        closedAt: z.string().nullable(),
+        netIncome: z.number().nullable(),
+        totalIncome: z.number().nullable(),
+        totalExpenses: z.number().nullable(),
+        journalEntries: z.number().nullable(),
+    }).nullable(),
+    data: z.never().optional(),
+    meta: z.never().optional(),
+    id: z.never().optional(),
+    type: z.never().optional(),
+    startDate: z.never().optional(),
+    endDate: z.never().optional(),
+    closedAt: z.never().optional(),
+    closedBy: z.never().optional(),
+    reopenedAt: z.never().optional(),
+    reopenReason: z.never().optional(),
+    generatedAt: z.never().optional(),
+}).passthrough();
 /**
  * Wraps a tool handler to automatically log execution time, success/failure,
  * and record metrics. Catches errors and routes them through handleToolError.
@@ -1014,7 +1319,12 @@ export async function withToolLogging(toolName, fn) {
     }
     catch (error) {
         const durationMs = Math.round(Date.now() - startTime);
-        logToolCall(toolName, startTime, false, error instanceof Error ? error : new Error(String(error)));
+        const errorForLog = isFrihetApiError(error) && error.statusCode === 403
+            ? Object.assign(new Error("Forbidden"), { statusCode: 403, errorCode: "forbidden" })
+            : error instanceof Error
+                ? error
+                : new Error(String(error));
+        logToolCall(toolName, startTime, false, errorForLog);
         recordToolCall(toolName, durationMs, false);
         return handleToolError(error, toolName);
     }