@kivimedia/kmhub 2.9.0 → 2.10.0

package/tools/dubsado.mjs

@@ -1,137 +1,137 @@
-/**
- * Tool family: dubsado - the Dubsado lead reply loop.
- *
- * For workspaces whose Dubsado account is wired through the Kivi dubsado-bridge
- * (today: Dazzling Balloons). The bridge polls Dubsado every 5 minutes, LeadIQ
- * stores each lead and writes an AI reply draft, and the send goes back out
- * through Dubsado itself so the reply sits in the real project email thread and
- * comes from the business's own sender.
- *
- * The terminal is the editor: there is no regenerate machinery here. Read the
- * draft, rework the wording with the person in chat, send the final text.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-export const FAMILY = 'dubsado';
-
-export const TOOLS = [
-  'km_dubsado_status',
-  'km_dubsado_leads',
-  'km_dubsado_lead',
-  'km_dubsado_send_reply',
-  'km_dubsado_sync',
-];
-
-export const PROFILES = ['*'];
-
-function routeMissing(r) {
-  return r.status === 404 || r.status === 405 || r.status === 501;
-}
-
-const NOT_SUPPORTED =
-  'This workspace does not have the Dubsado connection yet. That is not a fault: every other tool works as ' +
-  'normal. Connecting a Dubsado account is done by the Kivi Media team.';
-
-export function register(server, call, { out, text, qs, z }) {
-  server.tool(
-    'km_dubsado_status',
-    'Health check for the Dubsado connection: whether the bridge that syncs leads from Dubsado is alive, when ' +
-      'the last sync happened, and the newest lead it has. Call it first in a session about Dubsado leads, and ' +
-      'whenever a lead the person expects to see is missing. If bridge.alive is false, say plainly that syncing ' +
-      'and sending are down until the Kivi Media team revives the session, and do not attempt a send.',
-    {},
-    async () => {
-      const r = await call('GET', '/dubsado/status');
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_dubsado_leads',
-    'The Dubsado leads in this workspace, newest first, each with its reply_state: no_draft_yet, ' +
-      'draft_ready_for_review (the AI already wrote a reply nobody approved), approved_awaiting_send, or ' +
-      'reply_sent. Use it to answer "any new inquiries?", to find a lead by name, or to sweep for ' +
-      'draft_ready_for_review leads that deserve attention. New inquiries land here up to ~5 minutes after ' +
-      'they hit Dubsado. This lists; read one lead in full with km_dubsado_lead before judging any draft.',
-    {
-      q: z.string().optional().describe('Search by client name, email, or event type.'),
-      status: z.string().optional().describe('Filter by pipeline stage, e.g. inquiry, qualified, proposal_sent, booked.'),
-      limit: z.number().int().min(1).max(100).optional().describe('How many leads, default 20.'),
-    },
-    async ({ q, status, limit }) => {
-      const r = await call('GET', `/dubsado/leads${qs({ q, status, limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_dubsado_lead',
-    'One Dubsado lead in full: contact details, event info, the form answers they submitted, the whole email ' +
-      'thread so far, and every AI reply draft with its state. Accepts the lead_id from km_dubsado_leads (or a ' +
-      '24 character Dubsado job id). Read this BEFORE proposing any reply: the thread and form answers are the ' +
-      'context that makes a reply sound informed instead of canned. Show the newest unsent draft to the person, ' +
-      'take their edits in chat, and only then reach for km_dubsado_send_reply.',
-    {
-      lead_id: z.string().describe('Lead UUID from km_dubsado_leads, or the Dubsado job id.'),
-    },
-    async ({ lead_id }) => {
-      const r = await call('GET', `/dubsado/leads/${encodeURIComponent(String(lead_id || '').trim())}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_dubsado_send_reply',
-    'Send a reply email to a Dubsado lead, through Dubsado, from the business\'s own sender. It lands in the ' +
-      'lead\'s real Dubsado project thread and cannot be unsent, so the person must have seen and approved the ' +
-      'exact final wording first. Pass draft_id for an existing AI draft, with subject and body carrying the ' +
-      'final wording after any edits; or pass just subject + body for a reply written here in the terminal. ' +
-      'The recipient is always the lead\'s own email on file and cannot be changed here. Plain text is fine: ' +
-      'blank lines become paragraphs. The send is refused for leads whose follow-ups were halted and for leads ' +
-      'in a terminal stage like booked or lost. ' +
-      'On success, tell the person it went out, to whom, and with what subject.',
-    {
-      lead_id: z.string().describe('Lead UUID from km_dubsado_leads, or the Dubsado job id.'),
-      draft_id: z.string().optional().describe('UUID of the AI draft being approved (from km_dubsado_lead).'),
-      subject: z.string().optional().describe('Final subject line. Overrides the draft subject when draft_id is given.'),
-      body: z.string().optional().describe('Final reply text. Overrides the draft text when draft_id is given.'),
-      confirm_token: z
-        .string()
-        .optional()
-        .describe(
-          'Leave this out on the first call. This action needs an explicit yes from the person you are working ' +
-            'with: KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show ' +
-            'them that description in those words, wait for a real answer, and only then call again with the ' +
-            'token and the SAME arguments. A yes for one action never authorises a different one.',
-        ),
-    },
-    async ({ lead_id, ...rest }) => {
-      const r = await call(
-        'POST',
-        `/dubsado/leads/${encodeURIComponent(String(lead_id || '').trim())}/send`,
-        rest,
-      );
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_dubsado_sync',
-    'Ask the bridge to re-pull recent leads from Dubsado now instead of waiting for the next 5 minute poll. ' +
-      'Use it when a lead the person can see in Dubsado has not appeared in km_dubsado_leads. Re-pulled leads ' +
-      'land within about 5 minutes of this call, so check the list again after that, not immediately. ' +
-      'days_back widens how far back the re-pull looks.',
-    {
-      days_back: z.number().int().min(1).max(90).optional().describe('Re-pull leads updated in the last N days.'),
-    },
-    async ({ days_back }) => {
-      const r = await call('POST', '/dubsado/sync', days_back ? { days_back } : {});
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-}
+/**
+ * Tool family: dubsado - the Dubsado lead reply loop.
+ *
+ * For workspaces whose Dubsado account is wired through the Kivi dubsado-bridge
+ * (today: Dazzling Balloons). The bridge polls Dubsado every 5 minutes, LeadIQ
+ * stores each lead and writes an AI reply draft, and the send goes back out
+ * through Dubsado itself so the reply sits in the real project email thread and
+ * comes from the business's own sender.
+ *
+ * The terminal is the editor: there is no regenerate machinery here. Read the
+ * draft, rework the wording with the person in chat, send the final text.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+export const FAMILY = 'dubsado';
+
+export const TOOLS = [
+  'km_dubsado_status',
+  'km_dubsado_leads',
+  'km_dubsado_lead',
+  'km_dubsado_send_reply',
+  'km_dubsado_sync',
+];
+
+export const PROFILES = ['*'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'This workspace does not have the Dubsado connection yet. That is not a fault: every other tool works as ' +
+  'normal. Connecting a Dubsado account is done by the Kivi Media team.';
+
+export function register(server, call, { out, text, qs, z }) {
+  server.tool(
+    'km_dubsado_status',
+    'Health check for the Dubsado connection: whether the bridge that syncs leads from Dubsado is alive, when ' +
+      'the last sync happened, and the newest lead it has. Call it first in a session about Dubsado leads, and ' +
+      'whenever a lead the person expects to see is missing. If bridge.alive is false, say plainly that syncing ' +
+      'and sending are down until the Kivi Media team revives the session, and do not attempt a send.',
+    {},
+    async () => {
+      const r = await call('GET', '/dubsado/status');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_dubsado_leads',
+    'The Dubsado leads in this workspace, newest first, each with its reply_state: no_draft_yet, ' +
+      'draft_ready_for_review (the AI already wrote a reply nobody approved), approved_awaiting_send, or ' +
+      'reply_sent. Use it to answer "any new inquiries?", to find a lead by name, or to sweep for ' +
+      'draft_ready_for_review leads that deserve attention. New inquiries land here up to ~5 minutes after ' +
+      'they hit Dubsado. This lists; read one lead in full with km_dubsado_lead before judging any draft.',
+    {
+      q: z.string().optional().describe('Search by client name, email, or event type.'),
+      status: z.string().optional().describe('Filter by pipeline stage, e.g. inquiry, qualified, proposal_sent, booked.'),
+      limit: z.number().int().min(1).max(100).optional().describe('How many leads, default 20.'),
+    },
+    async ({ q, status, limit }) => {
+      const r = await call('GET', `/dubsado/leads${qs({ q, status, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_dubsado_lead',
+    'One Dubsado lead in full: contact details, event info, the form answers they submitted, the whole email ' +
+      'thread so far, and every AI reply draft with its state. Accepts the lead_id from km_dubsado_leads (or a ' +
+      '24 character Dubsado job id). Read this BEFORE proposing any reply: the thread and form answers are the ' +
+      'context that makes a reply sound informed instead of canned. Show the newest unsent draft to the person, ' +
+      'take their edits in chat, and only then reach for km_dubsado_send_reply.',
+    {
+      lead_id: z.string().describe('Lead UUID from km_dubsado_leads, or the Dubsado job id.'),
+    },
+    async ({ lead_id }) => {
+      const r = await call('GET', `/dubsado/leads/${encodeURIComponent(String(lead_id || '').trim())}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_dubsado_send_reply',
+    'Send a reply email to a Dubsado lead, through Dubsado, from the business\'s own sender. It lands in the ' +
+      'lead\'s real Dubsado project thread and cannot be unsent, so the person must have seen and approved the ' +
+      'exact final wording first. Pass draft_id for an existing AI draft, with subject and body carrying the ' +
+      'final wording after any edits; or pass just subject + body for a reply written here in the terminal. ' +
+      'The recipient is always the lead\'s own email on file and cannot be changed here. Plain text is fine: ' +
+      'blank lines become paragraphs. The send is refused for leads whose follow-ups were halted and for leads ' +
+      'in a terminal stage like booked or lost. ' +
+      'On success, tell the person it went out, to whom, and with what subject.',
+    {
+      lead_id: z.string().describe('Lead UUID from km_dubsado_leads, or the Dubsado job id.'),
+      draft_id: z.string().optional().describe('UUID of the AI draft being approved (from km_dubsado_lead).'),
+      subject: z.string().optional().describe('Final subject line. Overrides the draft subject when draft_id is given.'),
+      body: z.string().optional().describe('Final reply text. Overrides the draft text when draft_id is given.'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Leave this out on the first call. This action needs an explicit yes from the person you are working ' +
+            'with: KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show ' +
+            'them that description in those words, wait for a real answer, and only then call again with the ' +
+            'token and the SAME arguments. A yes for one action never authorises a different one.',
+        ),
+    },
+    async ({ lead_id, ...rest }) => {
+      const r = await call(
+        'POST',
+        `/dubsado/leads/${encodeURIComponent(String(lead_id || '').trim())}/send`,
+        rest,
+      );
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_dubsado_sync',
+    'Ask the bridge to re-pull recent leads from Dubsado now instead of waiting for the next 5 minute poll. ' +
+      'Use it when a lead the person can see in Dubsado has not appeared in km_dubsado_leads. Re-pulled leads ' +
+      'land within about 5 minutes of this call, so check the list again after that, not immediately. ' +
+      'days_back widens how far back the re-pull looks.',
+    {
+      days_back: z.number().int().min(1).max(90).optional().describe('Re-pull leads updated in the last N days.'),
+    },
+    async ({ days_back }) => {
+      const r = await call('POST', '/dubsado/sync', days_back ? { days_back } : {});
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}

package/tools/exports.mjs

@@ -1,128 +1,128 @@
-/**
- * Tool family: exports - getting your own data back out, from a terminal.
- *
- * This family exists because of one email. A customer with three workspaces asked
- * for "a full export of all my data, including the most recent", said the system
- * was hard to navigate, and said he could not work out how to see his invoices.
- * Everything he asked for was already in KM Hub and already exportable, and there
- * was still no way to answer him without telling him to go and click through a
- * screen he had just told us he could not find. A person asking for their own
- * records should never be handed a navigation problem.
- *
- * Four tools:
- *   km_export_data        one dataset, csv or xlsx
- *   km_export_everything  the whole workspace, one ZIP of readable CSVs
- *   km_export_status      how far an export got, and its link once ready
- *   km_list_exports       what has been exported lately
- *
- * These do not build files. They queue the same job the Export Data screen
- * queues, and the same worker builds it, so an export started here and an export
- * started in the browser are byte-for-byte the same file.
- *
- * 🚨 A DOWNLOAD LINK IS A CREDENTIAL. The signed URL needs no login and lives for
- * seven days. Hand it to the person who asked, use it to fetch the file, and do
- * not write it into a document, a commit, a ticket or a chat log that outlives
- * the download.
- *
- * No PROFILES export on purpose. Exporting is not the job of the narrow money,
- * outreach or content profiles, and a family that pins itself into every profile
- * makes the profiles meaningless. It ships in `full`, which is the default.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'exports';
-
-export const TOOLS = [
-  'km_export_data',
-  'km_export_everything',
-  'km_export_status',
-  'km_list_exports',
-];
-
-const LINK_WARNING =
-  'The download link that comes back is a signed URL: anyone holding it can fetch the file without signing in, and it expires after seven days. Give it to the person who asked for it and do not paste it anywhere it will be stored.';
-
-const NOT_INSTANT =
-  'The file is built in the background. This returns an export id straight away; call km_export_status with that id until it says ready, which is usually a few seconds and can be a couple of minutes for a large workspace.';
-
-/**
- * @param {{ tool: Function }} server guarded registrar (see ./README.md)
- * @param {(method: string, path: string, body?: any) => Promise<{ok:boolean,status:number,data:any}>} call
- * @param {{ out: Function, text: Function, qs: Function }} helpers
- */
-export function register(server, call, { out, qs }) {
-  server.tool(
-    'km_export_data',
-    'Export one set of records from this workspace to a spreadsheet file: invoices, bookings, clients, payments, quotes, leads, expenses, gigs, venues, vendors, equipment, team members, or the outreach tables. ' +
-      'Reach for this whenever someone asks to be sent, given, or shown their data outside KM Hub: "send me my invoices", "export the client list", "I need last year in a spreadsheet", "can I get all of this out", "my accountant wants the payments". ' +
-      'It exports every column of the chosen dataset. Narrow it by date with date_from and date_to when the person named a period, and leave both off when they asked for everything. ' +
-      'If they want the whole workspace rather than one dataset, use km_export_everything instead. ' +
-      NOT_INSTANT + ' ' + LINK_WARNING,
-    {
-      dataset: z
-        .string()
-        .describe(
-          'What to export. One of: invoices, bookings, clients, payments, quotes, inquiries, expenses, gigs, venues, vendors, equipment_items, kmhub_export_team_members, outreach_campaigns, outreach_campaign_prospect_status, outreach_replies, outreach_drafts, booking_drafts. Everyday words are understood too: events, jobs and projects mean bookings, contacts and customers mean clients, bills means invoices, leads and enquiries mean inquiries, equipment, team and crew are understood.',
-        ),
-      format: z
-        .enum(['csv', 'xlsx'])
-        .optional()
-        .describe('csv (the default, opens anywhere) or xlsx for Excel.'),
-      date_from: z.string().optional().describe('Only records from this date onward, as YYYY-MM-DD. Leave off for everything.'),
-      date_to: z.string().optional().describe('Only records before this date, as YYYY-MM-DD. Leave off for everything.'),
-      date_field: z
-        .string()
-        .optional()
-        .describe('Which date the range applies to. Defaults to created_at. For bookings, event_date is usually what a person means by "last year".'),
-      label: z.string().optional().describe('A name for this export, shown in the export history. Say what it is, for instance "2025 invoices for the accountant".'),
-    },
-    async ({ dataset, format, date_from, date_to, date_field, label }) =>
-      out(await call('POST', '/exports', { dataset, format, date_from, date_to, date_field, label })),
-  );
-
-  server.tool(
-    'km_export_everything',
-    'Export the ENTIRE workspace as one ZIP file: every booking, lead, deal, client, quote, invoice, payment, venue, vendor, expense, gig, team member, email history, outreach record and Booking Brain artifact, each as its own readable CSV inside the archive. ' +
-      'This is the one to reach for when someone asks for "all my data", "a full export", "everything you have on us", or is leaving and wants their records. ' +
-      'Prefer km_export_data when they named one thing: a person who asked for their invoices does not want a forty-file archive to dig through. ' +
-      'This is a confirmed action. The first call comes back with a sentence describing exactly what will be packaged and a confirm_token. Put that sentence to the person, wait for an explicit yes, then call again with the same inputs plus that token. Never send the token without asking. ' +
-      NOT_INSTANT + ' ' + LINK_WARNING,
-    {
-      label: z.string().optional().describe('A name for this export, shown in the export history.'),
-      confirm_token: z
-        .string()
-        .min(1)
-        .max(4096)
-        .optional()
-        .describe('Only ever the exact token returned in the 409 response, and only after the person has said yes to the sentence that came with it.'),
-    },
-    async ({ label, confirm_token }) =>
-      out(await call('POST', '/exports/everything', { label, ...(confirm_token ? { confirm_token } : {}) })),
-  );
-
-  server.tool(
-    'km_export_status',
-    'Check one export: whether it is still building, what it is doing right now, how many rows it has read, and once it is ready the file size, the row count and the download link. ' +
-      'Call this after km_export_data or km_export_everything, using the export_id they returned. If it is still building, say what it is doing rather than just "working on it", and check again in a few seconds. ' +
-      'A failed export comes back with the reason in error_message, which is usually a date range that matched too many rows. ' +
-      LINK_WARNING,
-    {
-      export_id: z.string().describe('The export_id returned when the export was started.'),
-    },
-    async ({ export_id }) => out(await call('GET', `/exports/${encodeURIComponent(export_id)}`)),
-  );
-
-  server.tool(
-    'km_list_exports',
-    'List the exports built from this workspace recently: what was exported, when, in what format, how big it was and whether it is still available. ' +
-      'Useful when someone asks "did I already pull that", "what did we send the accountant", or when an earlier export id has been lost. ' +
-      'Download links are deliberately not included here. Ask for one export by id with km_export_status to get its link. ' +
-      'This tool only reads. It cannot start or delete an export.',
-    {
-      limit: z.number().int().min(1).max(100).optional().describe('How many to list. Defaults to 20.'),
-    },
-    async ({ limit }) => out(await call('GET', `/exports${qs({ limit })}`)),
-  );
-}
+/**
+ * Tool family: exports - getting your own data back out, from a terminal.
+ *
+ * This family exists because of one email. A customer with three workspaces asked
+ * for "a full export of all my data, including the most recent", said the system
+ * was hard to navigate, and said he could not work out how to see his invoices.
+ * Everything he asked for was already in KM Hub and already exportable, and there
+ * was still no way to answer him without telling him to go and click through a
+ * screen he had just told us he could not find. A person asking for their own
+ * records should never be handed a navigation problem.
+ *
+ * Four tools:
+ *   km_export_data        one dataset, csv or xlsx
+ *   km_export_everything  the whole workspace, one ZIP of readable CSVs
+ *   km_export_status      how far an export got, and its link once ready
+ *   km_list_exports       what has been exported lately
+ *
+ * These do not build files. They queue the same job the Export Data screen
+ * queues, and the same worker builds it, so an export started here and an export
+ * started in the browser are byte-for-byte the same file.
+ *
+ * 🚨 A DOWNLOAD LINK IS A CREDENTIAL. The signed URL needs no login and lives for
+ * seven days. Hand it to the person who asked, use it to fetch the file, and do
+ * not write it into a document, a commit, a ticket or a chat log that outlives
+ * the download.
+ *
+ * No PROFILES export on purpose. Exporting is not the job of the narrow money,
+ * outreach or content profiles, and a family that pins itself into every profile
+ * makes the profiles meaningless. It ships in `full`, which is the default.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'exports';
+
+export const TOOLS = [
+  'km_export_data',
+  'km_export_everything',
+  'km_export_status',
+  'km_list_exports',
+];
+
+const LINK_WARNING =
+  'The download link that comes back is a signed URL: anyone holding it can fetch the file without signing in, and it expires after seven days. Give it to the person who asked for it and do not paste it anywhere it will be stored.';
+
+const NOT_INSTANT =
+  'The file is built in the background. This returns an export id straight away; call km_export_status with that id until it says ready, which is usually a few seconds and can be a couple of minutes for a large workspace.';
+
+/**
+ * @param {{ tool: Function }} server guarded registrar (see ./README.md)
+ * @param {(method: string, path: string, body?: any) => Promise<{ok:boolean,status:number,data:any}>} call
+ * @param {{ out: Function, text: Function, qs: Function }} helpers
+ */
+export function register(server, call, { out, qs }) {
+  server.tool(
+    'km_export_data',
+    'Export one set of records from this workspace to a spreadsheet file: invoices, bookings, clients, payments, quotes, leads, expenses, gigs, venues, vendors, equipment, team members, or the outreach tables. ' +
+      'Reach for this whenever someone asks to be sent, given, or shown their data outside KM Hub: "send me my invoices", "export the client list", "I need last year in a spreadsheet", "can I get all of this out", "my accountant wants the payments". ' +
+      'It exports every column of the chosen dataset. Narrow it by date with date_from and date_to when the person named a period, and leave both off when they asked for everything. ' +
+      'If they want the whole workspace rather than one dataset, use km_export_everything instead. ' +
+      NOT_INSTANT + ' ' + LINK_WARNING,
+    {
+      dataset: z
+        .string()
+        .describe(
+          'What to export. One of: invoices, bookings, clients, payments, quotes, inquiries, expenses, gigs, venues, vendors, equipment_items, kmhub_export_team_members, outreach_campaigns, outreach_campaign_prospect_status, outreach_replies, outreach_drafts, booking_drafts. Everyday words are understood too: events, jobs and projects mean bookings, contacts and customers mean clients, bills means invoices, leads and enquiries mean inquiries, equipment, team and crew are understood.',
+        ),
+      format: z
+        .enum(['csv', 'xlsx'])
+        .optional()
+        .describe('csv (the default, opens anywhere) or xlsx for Excel.'),
+      date_from: z.string().optional().describe('Only records from this date onward, as YYYY-MM-DD. Leave off for everything.'),
+      date_to: z.string().optional().describe('Only records before this date, as YYYY-MM-DD. Leave off for everything.'),
+      date_field: z
+        .string()
+        .optional()
+        .describe('Which date the range applies to. Defaults to created_at. For bookings, event_date is usually what a person means by "last year".'),
+      label: z.string().optional().describe('A name for this export, shown in the export history. Say what it is, for instance "2025 invoices for the accountant".'),
+    },
+    async ({ dataset, format, date_from, date_to, date_field, label }) =>
+      out(await call('POST', '/exports', { dataset, format, date_from, date_to, date_field, label })),
+  );
+
+  server.tool(
+    'km_export_everything',
+    'Export the ENTIRE workspace as one ZIP file: every booking, lead, deal, client, quote, invoice, payment, venue, vendor, expense, gig, team member, email history, outreach record and Booking Brain artifact, each as its own readable CSV inside the archive. ' +
+      'This is the one to reach for when someone asks for "all my data", "a full export", "everything you have on us", or is leaving and wants their records. ' +
+      'Prefer km_export_data when they named one thing: a person who asked for their invoices does not want a forty-file archive to dig through. ' +
+      'This is a confirmed action. The first call comes back with a sentence describing exactly what will be packaged and a confirm_token. Put that sentence to the person, wait for an explicit yes, then call again with the same inputs plus that token. Never send the token without asking. ' +
+      NOT_INSTANT + ' ' + LINK_WARNING,
+    {
+      label: z.string().optional().describe('A name for this export, shown in the export history.'),
+      confirm_token: z
+        .string()
+        .min(1)
+        .max(4096)
+        .optional()
+        .describe('Only ever the exact token returned in the 409 response, and only after the person has said yes to the sentence that came with it.'),
+    },
+    async ({ label, confirm_token }) =>
+      out(await call('POST', '/exports/everything', { label, ...(confirm_token ? { confirm_token } : {}) })),
+  );
+
+  server.tool(
+    'km_export_status',
+    'Check one export: whether it is still building, what it is doing right now, how many rows it has read, and once it is ready the file size, the row count and the download link. ' +
+      'Call this after km_export_data or km_export_everything, using the export_id they returned. If it is still building, say what it is doing rather than just "working on it", and check again in a few seconds. ' +
+      'A failed export comes back with the reason in error_message, which is usually a date range that matched too many rows. ' +
+      LINK_WARNING,
+    {
+      export_id: z.string().describe('The export_id returned when the export was started.'),
+    },
+    async ({ export_id }) => out(await call('GET', `/exports/${encodeURIComponent(export_id)}`)),
+  );
+
+  server.tool(
+    'km_list_exports',
+    'List the exports built from this workspace recently: what was exported, when, in what format, how big it was and whether it is still available. ' +
+      'Useful when someone asks "did I already pull that", "what did we send the accountant", or when an earlier export id has been lost. ' +
+      'Download links are deliberately not included here. Ask for one export by id with km_export_status to get its link. ' +
+      'This tool only reads. It cannot start or delete an export.',
+    {
+      limit: z.number().int().min(1).max(100).optional().describe('How many to list. Defaults to 20.'),
+    },
+    async ({ limit }) => out(await call('GET', `/exports${qs({ limit })}`)),
+  );
+}