@frihet/mcp-server 1.16.6 → 2.0.0

package/dist/tools/shared.js

@@ -4,11 +4,14 @@
  * This module is used by both the local (stdio) and remote (Cloudflare Workers)
  * MCP servers. It must NOT import concrete classes from either client — error
  * detection uses duck-typing (checking for `statusCode`/`errorCode` properties)
- * so it works regardless of which FrihetApiError class threw the error.
+ * so it works regardless of which FrihetApiError class threw the error. The
+ * client-owned predicate separately verifies local validation provenance.
  */
 import { z } from "zod/v4";
 import { log, logToolCall } from "../logger.js";
 import { recordToolCall } from "../metrics.js";
+import { sanitizeServerRemediation } from "../redaction.js";
+import { isLocalInputValidationError } from "../client.js";
 /* ------------------------------------------------------------------ */
 /*  Safety annotations for MCP tool registrations                      */
 /* ------------------------------------------------------------------ */
@@ -19,15 +22,16 @@ export const DELETE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: true,
 /* ------------------------------------------------------------------ */
 /*  Content annotations for tool responses                             */
 /* ------------------------------------------------------------------ */
-/** List operations: useful to both user and assistant for navigation, medium priority. */
+// MCP permits fractional priorities, but some clients (including Codex CLI
+// 0.153.4) fail to decode them. Omit this optional hint on read responses while
+// retaining their audience. See https://github.com/openai/codex/issues/38979.
+/** List operations: useful to both user and assistant for navigation. */
 export const LIST_CONTENT_ANNOTATIONS = {
     audience: ["user", "assistant"],
-    priority: 0.5,
 };
-/** Get/read operations: useful to both, higher priority as specifically requested data. */
+/** Get/read operations: useful to both user and assistant. */
 export const GET_CONTENT_ANNOTATIONS = {
     audience: ["user", "assistant"],
-    priority: 0.7,
 };
 /** Mutating operations (create/update/delete): primarily for the user, highest priority. */
 export const MUTATE_CONTENT_ANNOTATIONS = {
@@ -43,47 +47,100 @@ 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");
 }
+/** Error class names safe to echo from the unexpected-error path. */
+const UNEXPECTED_ERROR_CLASSES = new Set([
+    "FrihetApiError",
+    "TypeError",
+    "SyntaxError",
+    "RangeError",
+    "AbortError",
+    "ZodError",
+]);
+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) {
+    // NOTE: FrihetApiError carries the backend `requestId`, but it is NOT echoed
+    // here: `requestId` is in SENSITIVE_FIELD_NAMES (src/redaction.ts), whose
+    // values must not leave the process. Surfacing it needs an explicit policy
+    // change, not a side effect of error formatting.
     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");
+        // Fixed booleans only: private output profiles must preserve definitive
+        // API denial semantics without forwarding provider text, codes or IDs.
+        const definitiveDenial = !operationOutcomeUnknown
+            && (error.statusCode === 404 || error.statusCode === 403);
+        const localValidationRejected = !operationOutcomeUnknown && error.statusCode === 400
+            && isLocalInputValidationError(error);
+        const requestRejected = !operationOutcomeUnknown && error.statusCode === 400
+            && !localValidationRejected;
+        let friendlyMessage;
+        if (operationOutcomeUnknown) {
+            friendlyMessage = "Frihet could not confirm whether this request completed. Read the current record before deciding whether to retry. / Frihet no pudo confirmar si la solicitud se completó. Consulta el estado actual antes de decidir si reintentar.";
+        }
+        else if (localValidationRejected) {
+            friendlyMessage = "Input validation failed before sending the request. No action was performed. Correct the ID and input parameters before retrying. / La validación falló antes de enviar la solicitud. No se realizó ninguna acción. Corrige el ID y los parámetros antes de reintentar.";
+        }
+        else 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 +150,30 @@ export function handleToolError(error, toolName) {
                 },
             ],
             isError: true,
+            ...(error.statusCode === 401 || operationOutcomeUnknown || definitiveDenial || localValidationRejected || requestRejected
+                ? {
+                    _meta: {
+                        ...(definitiveDenial
+                            ? { [error.statusCode === 404 ? "io.frihet/resourceNotFound" : "io.frihet/accessDenied"]: true }
+                            : {}),
+                        ...(error.statusCode === 401
+                            ? { "io.frihet/authenticationRequired": true }
+                            : {}),
+                        ...(localValidationRejected
+                            ? { "io.frihet/localValidationRejected": true }
+                            : {}),
+                        ...(requestRejected
+                            ? { "io.frihet/requestRejected": true }
+                            : {}),
+                        ...(operationOutcomeUnknown
+                            ? { "io.frihet/operationOutcomeUnknown": true }
+                            : {}),
+                        ...(transportOutcomeUnknown
+                            ? { "io.frihet/transportOutcomeUnknown": true }
+                            : {}),
+                    },
+                }
+                : {}),
         };
     }
     const errMsg = error instanceof Error ? error.stack ?? error.message : String(error);
@@ -106,8 +187,19 @@ export function handleToolError(error, toolName) {
             code: error instanceof Error ? error.name : "unknown",
         },
     });
+    // Class name only, from a fixed allowlist — never the message, stack, or an
+    // arbitrary `name` (a thrown object can set `name` to any identifier-shaped
+    // value, including a secret).
+    const errorClass = error instanceof Error && UNEXPECTED_ERROR_CLASSES.has(error.name)
+        ? error.name
+        : "UnknownError";
     return {
-        content: [{ type: "text", text: "Error: An unexpected error occurred. Contact support if this persists.", annotations: ERROR_CONTENT_ANNOTATIONS }],
+        content: [{
+                type: "text",
+                text: `Error: An unexpected error occurred (${errorClass}). Contact support if this persists.`,
+                annotations: ERROR_CONTENT_ANNOTATIONS,
+            }],
+        structuredContent: { error: "unexpected_error", errorClass },
         isError: true,
     };
 }
@@ -123,15 +215,32 @@ export function formatPaginatedResponse(resourceName, response) {
         lines.push(JSON.stringify(item, null, 2));
         lines.push("---");
     }
-    if (response.total > response.offset + response.data.length) {
+    const hasMoreByTotal = response.total > response.offset + response.data.length;
+    const isTruncatedScanWindow = Boolean(response.nextCursor && response.data.length < response.limit);
+    if (isTruncatedScanWindow && response.nextCursor) {
+        lines.push(`More results available beyond the current scan window. Continue with after='${response.nextCursor}' to fetch the next page.`);
+    }
+    else if (hasMoreByTotal) {
         const nextOffset = response.offset + response.data.length;
         lines.push(`More results available. Use offset=${nextOffset} to see the next page.`);
         if (response.nextCursor) {
             lines.push(`Cursor pagination: use after='${response.nextCursor}' for efficient cursor-based pagination.`);
         }
     }
+    else if (response.nextCursor) {
+        lines.push(`Cursor pagination: use after='${response.nextCursor}' for efficient cursor-based pagination.`);
+    }
     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 +266,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 +357,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 +398,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 +420,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 +461,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 +474,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 +482,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 +493,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 +512,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 +524,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 +557,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 +598,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(),
@@ -507,7 +708,9 @@ export const posTerminalItemOutput = z.object({
     label: z.string().optional(),
     deviceType: z.string().optional(),
     locationId: z.string().optional(),
-    status: z.enum(["online", "offline", "unknown"]).optional(),
+    // Raw stored value: Frihet-ERP apps/erp/modules/pos/schema/collections.ts
+    // (posTerminals.status), returned verbatim by publicApi/families/pos.ts.
+    status: z.enum(["active", "paused", "retired"]).optional(),
     stripeReaderId: z.string().optional(),
     createdAt: z.string().optional(),
     updatedAt: z.string().optional(),
@@ -543,6 +746,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 +772,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 +936,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 +984,18 @@ 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(),
-    status: z.enum(["active", "pending"]).optional(),
-    invitedAt: z.string().optional(),
-    joinedAt: z.string().optional(),
-    createdAt: z.string().optional(),
-    updatedAt: z.string().optional(),
+    name: z.string().nullable().optional(),
+    email: z.string().nullable().optional(),
+    // Frihet-ERP functions/src/publicApi.ts team listing: invitation rows whose
+    // stored role is not assignable are rendered with `role: null` and
+    // `status: 'invalid'`; past-expiry invitations surface as `expired`.
+    role: z.enum(["owner", "admin", "editor", "accountant", "viewer"]).nullable().optional(),
+    status: z.enum(["active", "pending", "expired", "invalid"]).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 ------------------------------------------------- */
 /**
@@ -855,7 +1087,13 @@ export const gestoriaAgingConsolidatedOutput = z.object({
     }).passthrough()),
     generatedAt: z.string().optional(),
 }).passthrough();
-/* --- D4-B: HR / Webhook test / Payroll / Onboarding / Permissions / Period close --- */
+/* --- D4-B: HR / Webhook test / Payroll / Permissions / Period close ---
+ * Onboarding (onboarding_status, onboarding_persona_set) was withdrawn via
+ * issue #124 because Frihet-ERP has no /v1/onboarding/* family. The schemas
+ * lived here previously; the registration in register-all.ts and the file
+ * src/tools/onboarding.ts are also gone. If a future Frihet-ERP release
+ * ships the family, restore src/tools/onboarding.ts, re-add the export
+ * symbols here, and re-import them in register-all.ts. */
 /** Leave/PTO request — backend `/v1/leaves`. */
 export const leaveRequestItemOutput = z.object({
     id: z.string(),
@@ -885,19 +1123,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,62 +1181,137 @@ 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(),
-}).passthrough();
-/** Onboarding workspace state — backend `/v1/onboarding/status`. */
-export const onboardingStatusOutput = z.object({
-    workspaceId: z.string().optional(),
-    persona: z.enum(["autonomo", "empresa", "agencia", "gestoria"]).optional(),
-    completedSteps: z.array(z.string()).optional(),
-    pendingSteps: z.array(z.string()).optional(),
-    percentComplete: z.number().min(0).max(100).optional(),
-    startedAt: z.string().optional(),
-    completedAt: z.string().optional(),
-}).passthrough();
-/** Onboarding persona update result. */
-export const onboardingPersonaResultOutput = z.object({
-    workspaceId: z.string().optional(),
-    persona: z.enum(["autonomo", "empresa", "agencia", "gestoria"]),
-    updatedAt: 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();
-/** 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 +1325,43 @@ 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();
+/** Mark a local confirmation refusal without parsing or exposing provider text. */
+export function confirmationRequiredError(message) {
+    return {
+        content: [{ type: "text", text: message, annotations: ERROR_CONTENT_ANNOTATIONS }],
+        isError: true,
+        _meta: { "io.frihet/confirmationRequired": true },
+    };
+}
 /**
  * Wraps a tool handler to automatically log execution time, success/failure,
  * and record metrics. Catches errors and routes them through handleToolError.
@@ -1014,7 +1385,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);
     }