@kivimedia/kmhub 2.9.1 → 2.11.0

package/tools/outreach.mjs

@@ -1,238 +1,238 @@
-/**
- * Tool family: outreach - the approval queue, the campaigns, the replies and the
- * email log.
- *
- * The safety line runs straight through this file and never moves: KM Hub writes
- * every outgoing message as a DRAFT, and a person approves it in KM Hub or the
- * Booth before anything leaves the building. So there is no approve tool here, no
- * send tool, no schedule tool and no delete tool, and every description says so
- * out loud, because the model will be asked to send and needs to know the answer
- * before it starts looking for a way.
- *
- * What IS here is the work a person actually wants help with: reading the
- * backlog, rewriting a message that is not right yet, seeing how a campaign is
- * doing, stopping one that should stop, triaging replies, and checking whether
- * anything landed.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'outreach';
-
-export const TOOLS = [
-  'km_list_outreach_drafts',
-  'km_read_outreach_draft',
-  'km_edit_outreach_draft',
-  'km_list_outreach_campaigns',
-  'km_outreach_campaign_stats',
-  'km_pause_outreach_campaign',
-  'km_resume_outreach_campaign',
-  'km_list_outreach_replies',
-  'km_outreach_email_log',
-  'km_outreach_email_stats',
-];
-
-// The cold outreach machine. tools.mjs already maps this family into the
-// 'outreach' profile; declaring it here keeps the file true on its own.
-export const PROFILES = ['outreach'];
-
-const DRAFT_STATUS = ['draft', 'approved', 'scheduled', 'sent', 'cancelled', 'all'];
-const CHANNEL = ['email', 'linkedin', 'ig', 'sms_whatsapp'];
-const CAMPAIGN_STATUS = ['draft', 'running', 'paused', 'completed', 'archived'];
-const REPLY_CLASS = [
-  'interested', 'not_interested', 'objection', 'ooo',
-  'wrong_person', 'unsubscribe', 'question', 'auto_reply', 'neutral',
-];
-
-/**
- * @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, qs: Function }} helpers shared response helpers from ../tools.mjs
- */
-export function register(server, call, { out, qs }) {
-  server.tool(
-    'km_list_outreach_drafts',
-    'Show the outreach messages waiting for approval: the emails and DMs that have been written for the user but have not gone anywhere yet. ' +
-      'Reach for it when the question is specifically about THIS queue: how many messages are pending, what is in the queue, or when they want to work through it one message at a time. ' +
-      'Do not answer the broad "what is waiting on me" from here. This is one channel of one kind of work, and km_briefing already carries the top of this queue ranked against the replies, tasks, invoices, enquiries and gigs that this tool cannot see, so a session that answers the whole day from this list reports a quarter of it as if it were all of it. ' +
-      'Each one comes back with the opening lines, who it is for, which campaign it belongs to and whether anyone has already edited it; ' +
-      'read one in full with km_read_outreach_draft. A backlog of a few hundred is normal, so this pages: the answer carries the exact ' +
-      'total and tells you whether there is more, so never report a count from the rows you can see. ' +
-      'This only reads. It cannot approve or send anything - a person does that in KM Hub.',
-    {
-      status: z.enum(DRAFT_STATUS).optional().describe('Default draft, which is the queue actually waiting on a human. Use all for the whole history.'),
-      channel: z.enum(CHANNEL).optional().describe('Narrow to one channel.'),
-      campaign_id: z.string().optional().describe('UUID of a campaign (see km_list_outreach_campaigns).'),
-      contact_id: z.string().optional().describe('UUID of a contact (see km_find_contact).'),
-      deal_id: z.string().optional().describe('UUID of a deal (see km_list_deals).'),
-      limit: z.number().int().min(1).max(100).optional().describe('Default 20.'),
-      offset: z.number().int().min(0).optional().describe('Skip this many before reading, for paging through a long backlog.'),
-    },
-    async ({ status, channel, campaign_id, contact_id, deal_id, limit, offset }) =>
-      out(await call('GET', `/outreach-drafts${qs({ status, channel, campaign_id, contact_id, deal_id, limit, offset })}`)),
-  );
-
-  server.tool(
-    'km_read_outreach_draft',
-    'Read one waiting outreach message in full: the whole body, the subject, who it is addressed to, which campaign and which step of the ' +
-      'sequence it belongs to, and where it stands. Reach for it before you quote a message back to the user, judge it, or rewrite it, so you ' +
-      'are working from the real wording rather than the preview. It also reports whether the message can still be rewritten from here, ' +
-      'so you know before you try. Read only: it never approves and never sends.',
-    {
-      id: z.string().describe('UUID of the draft (see km_list_outreach_drafts).'),
-    },
-    async ({ id }) => out(await call('GET', `/outreach-drafts/${encodeURIComponent(String(id))}`)),
-  );
-
-  server.tool(
-    'km_edit_outreach_draft',
-    'Rewrite a message that is still waiting for approval. This is how "make it shorter", "lead with the fire" or "drop the exclamation marks" ' +
-      'actually lands: the wording in the Approval Queue is replaced with yours, so the user opens KM Hub and reads the better version. ' +
-      'Send the FULL replacement text, never a description of the change, never a diff, never only the paragraph you touched. ' +
-      'Read the message first with km_read_outreach_draft so you are rewriting what is really there. ' +
-      'It refuses, and says why, once a person has approved, scheduled, sent or cancelled the message: wording someone signed off on is the ' +
-      'wording that goes out. ' +
-      'A message carrying PHOTOS rewrites normally: the rich version is rebuilt around your new words and the photos stay exactly where they ' +
-      'are, so there is no need to finish the wording before adding images. ' +
-      'The one thing it will not rewrite is a draft built from a saved TEMPLATE, where the markup is hand built around this copy and the plain ' +
-      'text is only half of what the recipient sees; the subject can still be changed there. ' +
-      'Editing does NOT approve and does NOT send. The message stays in the queue and a person still approves it. ' +
-      'The wording you replaced is kept in the AI activity log so nothing is lost, but there is no one-click undo for an edit: ' +
-      'putting the old words back means editing again, so do not promise the user a revert button.',
-    {
-      id: z.string().describe('UUID of the draft (see km_list_outreach_drafts).'),
-      body: z.string().optional().describe('The complete new message text, replacing what is there now.'),
-      subject: z.string().optional().describe('The complete new subject line (email). Leave it out to keep the current one.'),
-    },
-    async ({ id, body, subject }) => {
-      const payload = {};
-      if (body !== undefined) payload.body = body;
-      if (subject !== undefined) payload.subject = subject;
-      return out(await call('POST', `/outreach-drafts/${encodeURIComponent(String(id))}/edit`, payload));
-    },
-  );
-
-  server.tool(
-    'km_list_outreach_campaigns',
-    'List the cold outreach campaigns in this workspace: the name of each one, whether it is running, paused, finished, archived or still ' +
-      'being built, how many prospects are on it and when it last sent. Reach for it when the user asks what campaigns are live, which one is ' +
-      'paused, or as the step before pausing or resuming one so you are certain you have the right campaign and can name it back to them. ' +
-      'Read only.',
-    {
-      status: z.enum(CAMPAIGN_STATUS).optional().describe('Narrow to one status.'),
-      limit: z.number().int().min(1).max(100).optional().describe('Default 25.'),
-    },
-    async ({ status, limit }) => out(await call('GET', `/outreach-campaigns${qs({ status, limit })}`)),
-  );
-
-  server.tool(
-    'km_outreach_campaign_stats',
-    'How one campaign is actually doing. Returns the campaign settings plus a headcount of its prospects by state (still pending, queued, ' +
-      'sent to, replied, stopped, completed, suppressed), how many people opened or clicked, how many bounced, and how many of its messages ' +
-      'are still sitting in the approval queue. Reach for it when the user asks how a campaign is going, whether it is worth continuing, or ' +
-      'why nothing seems to be going out - a big awaiting_approval number usually IS the answer to that last one. ' +
-      'The opened and clicked numbers count PEOPLE, not events: 40 opened means 40 different prospects opened at least once. Read only.',
-    {
-      campaign_id: z.string().describe('UUID of the campaign (see km_list_outreach_campaigns).'),
-    },
-    async ({ campaign_id }) => out(await call('GET', `/outreach-campaigns/${encodeURIComponent(String(campaign_id))}/stats`)),
-  );
-
-  server.tool(
-    'km_pause_outreach_campaign',
-    'Pause a running campaign. Nothing more goes out on it until someone resumes, and every prospect keeps their place in the sequence, so ' +
-      'this is fully reversible and nothing is lost. ' +
-      'Pausing a live campaign stops mail reaching real people, so CONFIRM FIRST: name the campaign back to the user and get a yes before ' +
-      'you call this. Use km_list_outreach_campaigns to get the id and the exact name. ' +
-      'It will not pause anything that is not currently running, and it will say so plainly rather than guess. It does not delete, archive ' +
-      'or unenroll anybody.',
-    {
-      campaign_id: z.string().describe('UUID of the campaign (see km_list_outreach_campaigns).'),
-      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 ({ campaign_id, confirm_token }) =>
-      out(await call('POST', `/outreach-campaigns/${encodeURIComponent(String(campaign_id))}/pause`, { confirm_token })),
-  );
-
-  server.tool(
-    'km_resume_outreach_campaign',
-    'Un-pause a campaign that someone paused. It picks up exactly where it stopped. ' +
-      'Resuming starts messages flowing toward real people again, so CONFIRM FIRST: name the campaign back to the user and get a yes. ' +
-      'This only un-pauses a PAUSED campaign. It will not start a campaign for the first time and will not reopen a completed or archived ' +
-      'one; those are decisions a person makes in KM Hub. Every message on the campaign still waits for a human approval before it sends.',
-    {
-      campaign_id: z.string().describe('UUID of the campaign (see km_list_outreach_campaigns).'),
-      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 ({ campaign_id, confirm_token }) =>
-      out(await call('POST', `/outreach-campaigns/${encodeURIComponent(String(campaign_id))}/resume`, { confirm_token })),
-  );
-
-  server.tool(
-    'km_list_outreach_replies',
-    'The replies that have come back from outreach, newest first, each with what it appears to be: interested, a question, an objection, not ' +
-      'interested, an out of office, the wrong person, or an unsubscribe. Reach for it when the user asks who replied, wants to work through ' +
-      'the responses, or asks whether anyone bit. Filter by classification to pull out the warm ones, or handled=false to see only what ' +
-      'nobody has dealt with yet. Long quoted email threads come back trimmed to a readable preview. ' +
-      'Read only: it cannot answer anybody. To reply, write the answer with km_create_outreach_draft and a person approves it in KM Hub.',
-    {
-      classification: z.enum(REPLY_CLASS).optional().describe('Narrow to one kind of reply. interested is the one worth surfacing first.'),
-      handled: z.boolean().optional().describe('false shows only replies nobody has dealt with yet.'),
-      contact_id: z.string().optional().describe('UUID of a contact (see km_find_contact).'),
-      deal_id: z.string().optional().describe('UUID of a deal (see km_list_deals).'),
-      from: z.string().optional().describe('Earliest received date, YYYY-MM-DD.'),
-      to: z.string().optional().describe('Latest received date, YYYY-MM-DD.'),
-      limit: z.number().int().min(1).max(100).optional().describe('Default 25.'),
-    },
-    async ({ classification, handled, contact_id, deal_id, from, to, limit }) =>
-      out(await call('GET', `/outreach-replies${qs({ classification, handled, contact_id, deal_id, from, to, limit })}`)),
-  );
-
-  server.tool(
-    'km_outreach_email_log',
-    'What actually went out by email and what happened to it: who it went to, the subject, when it sent, whether it was delivered, when it ' +
-      'was first opened and how many times, whether any links were clicked, and whether it bounced. Reach for it when the user asks "did that ' +
-      'reach her", "has anyone opened it", "what have we sent this person" (pass contact_id) or wants the recent sending history. ' +
-      'Defaults to messages that have already sent; pass status=all to include the ones still waiting or cancelled. ' +
-      'It returns the envelope and the engagement, not the message text - use km_read_outreach_draft for the wording. Read only.',
-    {
-      contact_id: z.string().optional().describe('UUID of a contact (see km_find_contact), for one person history.'),
-      campaign_id: z.string().optional().describe('UUID of a campaign (see km_list_outreach_campaigns).'),
-      status: z.enum(DRAFT_STATUS).optional().describe('Default sent, which is the log of what really went out.'),
-      from: z.string().optional().describe('Earliest date, YYYY-MM-DD.'),
-      to: z.string().optional().describe('Latest date, YYYY-MM-DD.'),
-      limit: z.number().int().min(1).max(100).optional().describe('Default 25.'),
-    },
-    async ({ contact_id, campaign_id, status, from, to, limit }) =>
-      out(await call('GET', `/outreach-emails${qs({ contact_id, campaign_id, status, from, to, limit })}`)),
-  );
-
-  server.tool(
-    'km_outreach_email_stats',
-    'The day by day shape of email sending across the whole workspace: sent, delivered, opened, clicked, replied, bounced and complained, one ' +
-      'row per day plus the totals for the window. Reach for it when the user asks how sending has been going lately, whether volume is up or ' +
-      'down, or whether bounces have spiked, which is the early warning that a sending domain is getting into trouble. ' +
-      'For one specific message or one person, use km_outreach_email_log instead. Read only.',
-    {
-      days: z.number().int().min(1).max(90).optional().describe('How many days back. Default 30.'),
-    },
-    async ({ days }) => out(await call('GET', `/outreach-emails/daily${qs({ days })}`)),
-  );
-}
+/**
+ * Tool family: outreach - the approval queue, the campaigns, the replies and the
+ * email log.
+ *
+ * The safety line runs straight through this file and never moves: KM Hub writes
+ * every outgoing message as a DRAFT, and a person approves it in KM Hub or the
+ * Booth before anything leaves the building. So there is no approve tool here, no
+ * send tool, no schedule tool and no delete tool, and every description says so
+ * out loud, because the model will be asked to send and needs to know the answer
+ * before it starts looking for a way.
+ *
+ * What IS here is the work a person actually wants help with: reading the
+ * backlog, rewriting a message that is not right yet, seeing how a campaign is
+ * doing, stopping one that should stop, triaging replies, and checking whether
+ * anything landed.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'outreach';
+
+export const TOOLS = [
+  'km_list_outreach_drafts',
+  'km_read_outreach_draft',
+  'km_edit_outreach_draft',
+  'km_list_outreach_campaigns',
+  'km_outreach_campaign_stats',
+  'km_pause_outreach_campaign',
+  'km_resume_outreach_campaign',
+  'km_list_outreach_replies',
+  'km_outreach_email_log',
+  'km_outreach_email_stats',
+];
+
+// The cold outreach machine. tools.mjs already maps this family into the
+// 'outreach' profile; declaring it here keeps the file true on its own.
+export const PROFILES = ['outreach'];
+
+const DRAFT_STATUS = ['draft', 'approved', 'scheduled', 'sent', 'cancelled', 'all'];
+const CHANNEL = ['email', 'linkedin', 'ig', 'sms_whatsapp'];
+const CAMPAIGN_STATUS = ['draft', 'running', 'paused', 'completed', 'archived'];
+const REPLY_CLASS = [
+  'interested', 'not_interested', 'objection', 'ooo',
+  'wrong_person', 'unsubscribe', 'question', 'auto_reply', 'neutral',
+];
+
+/**
+ * @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, qs: Function }} helpers shared response helpers from ../tools.mjs
+ */
+export function register(server, call, { out, qs }) {
+  server.tool(
+    'km_list_outreach_drafts',
+    'Show the outreach messages waiting for approval: the emails and DMs that have been written for the user but have not gone anywhere yet. ' +
+      'Reach for it when the question is specifically about THIS queue: how many messages are pending, what is in the queue, or when they want to work through it one message at a time. ' +
+      'Do not answer the broad "what is waiting on me" from here. This is one channel of one kind of work, and km_briefing already carries the top of this queue ranked against the replies, tasks, invoices, enquiries and gigs that this tool cannot see, so a session that answers the whole day from this list reports a quarter of it as if it were all of it. ' +
+      'Each one comes back with the opening lines, who it is for, which campaign it belongs to and whether anyone has already edited it; ' +
+      'read one in full with km_read_outreach_draft. A backlog of a few hundred is normal, so this pages: the answer carries the exact ' +
+      'total and tells you whether there is more, so never report a count from the rows you can see. ' +
+      'This only reads. It cannot approve or send anything - a person does that in KM Hub.',
+    {
+      status: z.enum(DRAFT_STATUS).optional().describe('Default draft, which is the queue actually waiting on a human. Use all for the whole history.'),
+      channel: z.enum(CHANNEL).optional().describe('Narrow to one channel.'),
+      campaign_id: z.string().optional().describe('UUID of a campaign (see km_list_outreach_campaigns).'),
+      contact_id: z.string().optional().describe('UUID of a contact (see km_find_contact).'),
+      deal_id: z.string().optional().describe('UUID of a deal (see km_list_deals).'),
+      limit: z.number().int().min(1).max(100).optional().describe('Default 20.'),
+      offset: z.number().int().min(0).optional().describe('Skip this many before reading, for paging through a long backlog.'),
+    },
+    async ({ status, channel, campaign_id, contact_id, deal_id, limit, offset }) =>
+      out(await call('GET', `/outreach-drafts${qs({ status, channel, campaign_id, contact_id, deal_id, limit, offset })}`)),
+  );
+
+  server.tool(
+    'km_read_outreach_draft',
+    'Read one waiting outreach message in full: the whole body, the subject, who it is addressed to, which campaign and which step of the ' +
+      'sequence it belongs to, and where it stands. Reach for it before you quote a message back to the user, judge it, or rewrite it, so you ' +
+      'are working from the real wording rather than the preview. It also reports whether the message can still be rewritten from here, ' +
+      'so you know before you try. Read only: it never approves and never sends.',
+    {
+      id: z.string().describe('UUID of the draft (see km_list_outreach_drafts).'),
+    },
+    async ({ id }) => out(await call('GET', `/outreach-drafts/${encodeURIComponent(String(id))}`)),
+  );
+
+  server.tool(
+    'km_edit_outreach_draft',
+    'Rewrite a message that is still waiting for approval. This is how "make it shorter", "lead with the fire" or "drop the exclamation marks" ' +
+      'actually lands: the wording in the Approval Queue is replaced with yours, so the user opens KM Hub and reads the better version. ' +
+      'Send the FULL replacement text, never a description of the change, never a diff, never only the paragraph you touched. ' +
+      'Read the message first with km_read_outreach_draft so you are rewriting what is really there. ' +
+      'It refuses, and says why, once a person has approved, scheduled, sent or cancelled the message: wording someone signed off on is the ' +
+      'wording that goes out. ' +
+      'A message carrying PHOTOS rewrites normally: the rich version is rebuilt around your new words and the photos stay exactly where they ' +
+      'are, so there is no need to finish the wording before adding images. ' +
+      'The one thing it will not rewrite is a draft built from a saved TEMPLATE, where the markup is hand built around this copy and the plain ' +
+      'text is only half of what the recipient sees; the subject can still be changed there. ' +
+      'Editing does NOT approve and does NOT send. The message stays in the queue and a person still approves it. ' +
+      'The wording you replaced is kept in the AI activity log so nothing is lost, but there is no one-click undo for an edit: ' +
+      'putting the old words back means editing again, so do not promise the user a revert button.',
+    {
+      id: z.string().describe('UUID of the draft (see km_list_outreach_drafts).'),
+      body: z.string().optional().describe('The complete new message text, replacing what is there now.'),
+      subject: z.string().optional().describe('The complete new subject line (email). Leave it out to keep the current one.'),
+    },
+    async ({ id, body, subject }) => {
+      const payload = {};
+      if (body !== undefined) payload.body = body;
+      if (subject !== undefined) payload.subject = subject;
+      return out(await call('POST', `/outreach-drafts/${encodeURIComponent(String(id))}/edit`, payload));
+    },
+  );
+
+  server.tool(
+    'km_list_outreach_campaigns',
+    'List the cold outreach campaigns in this workspace: the name of each one, whether it is running, paused, finished, archived or still ' +
+      'being built, how many prospects are on it and when it last sent. Reach for it when the user asks what campaigns are live, which one is ' +
+      'paused, or as the step before pausing or resuming one so you are certain you have the right campaign and can name it back to them. ' +
+      'Read only.',
+    {
+      status: z.enum(CAMPAIGN_STATUS).optional().describe('Narrow to one status.'),
+      limit: z.number().int().min(1).max(100).optional().describe('Default 25.'),
+    },
+    async ({ status, limit }) => out(await call('GET', `/outreach-campaigns${qs({ status, limit })}`)),
+  );
+
+  server.tool(
+    'km_outreach_campaign_stats',
+    'How one campaign is actually doing. Returns the campaign settings plus a headcount of its prospects by state (still pending, queued, ' +
+      'sent to, replied, stopped, completed, suppressed), how many people opened or clicked, how many bounced, and how many of its messages ' +
+      'are still sitting in the approval queue. Reach for it when the user asks how a campaign is going, whether it is worth continuing, or ' +
+      'why nothing seems to be going out - a big awaiting_approval number usually IS the answer to that last one. ' +
+      'The opened and clicked numbers count PEOPLE, not events: 40 opened means 40 different prospects opened at least once. Read only.',
+    {
+      campaign_id: z.string().describe('UUID of the campaign (see km_list_outreach_campaigns).'),
+    },
+    async ({ campaign_id }) => out(await call('GET', `/outreach-campaigns/${encodeURIComponent(String(campaign_id))}/stats`)),
+  );
+
+  server.tool(
+    'km_pause_outreach_campaign',
+    'Pause a running campaign. Nothing more goes out on it until someone resumes, and every prospect keeps their place in the sequence, so ' +
+      'this is fully reversible and nothing is lost. ' +
+      'Pausing a live campaign stops mail reaching real people, so CONFIRM FIRST: name the campaign back to the user and get a yes before ' +
+      'you call this. Use km_list_outreach_campaigns to get the id and the exact name. ' +
+      'It will not pause anything that is not currently running, and it will say so plainly rather than guess. It does not delete, archive ' +
+      'or unenroll anybody.',
+    {
+      campaign_id: z.string().describe('UUID of the campaign (see km_list_outreach_campaigns).'),
+      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 ({ campaign_id, confirm_token }) =>
+      out(await call('POST', `/outreach-campaigns/${encodeURIComponent(String(campaign_id))}/pause`, { confirm_token })),
+  );
+
+  server.tool(
+    'km_resume_outreach_campaign',
+    'Un-pause a campaign that someone paused. It picks up exactly where it stopped. ' +
+      'Resuming starts messages flowing toward real people again, so CONFIRM FIRST: name the campaign back to the user and get a yes. ' +
+      'This only un-pauses a PAUSED campaign. It will not start a campaign for the first time and will not reopen a completed or archived ' +
+      'one; those are decisions a person makes in KM Hub. Every message on the campaign still waits for a human approval before it sends.',
+    {
+      campaign_id: z.string().describe('UUID of the campaign (see km_list_outreach_campaigns).'),
+      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 ({ campaign_id, confirm_token }) =>
+      out(await call('POST', `/outreach-campaigns/${encodeURIComponent(String(campaign_id))}/resume`, { confirm_token })),
+  );
+
+  server.tool(
+    'km_list_outreach_replies',
+    'The replies that have come back from outreach, newest first, each with what it appears to be: interested, a question, an objection, not ' +
+      'interested, an out of office, the wrong person, or an unsubscribe. Reach for it when the user asks who replied, wants to work through ' +
+      'the responses, or asks whether anyone bit. Filter by classification to pull out the warm ones, or handled=false to see only what ' +
+      'nobody has dealt with yet. Long quoted email threads come back trimmed to a readable preview. ' +
+      'Read only: it cannot answer anybody. To reply, write the answer with km_create_outreach_draft and a person approves it in KM Hub.',
+    {
+      classification: z.enum(REPLY_CLASS).optional().describe('Narrow to one kind of reply. interested is the one worth surfacing first.'),
+      handled: z.boolean().optional().describe('false shows only replies nobody has dealt with yet.'),
+      contact_id: z.string().optional().describe('UUID of a contact (see km_find_contact).'),
+      deal_id: z.string().optional().describe('UUID of a deal (see km_list_deals).'),
+      from: z.string().optional().describe('Earliest received date, YYYY-MM-DD.'),
+      to: z.string().optional().describe('Latest received date, YYYY-MM-DD.'),
+      limit: z.number().int().min(1).max(100).optional().describe('Default 25.'),
+    },
+    async ({ classification, handled, contact_id, deal_id, from, to, limit }) =>
+      out(await call('GET', `/outreach-replies${qs({ classification, handled, contact_id, deal_id, from, to, limit })}`)),
+  );
+
+  server.tool(
+    'km_outreach_email_log',
+    'What actually went out by email and what happened to it: who it went to, the subject, when it sent, whether it was delivered, when it ' +
+      'was first opened and how many times, whether any links were clicked, and whether it bounced. Reach for it when the user asks "did that ' +
+      'reach her", "has anyone opened it", "what have we sent this person" (pass contact_id) or wants the recent sending history. ' +
+      'Defaults to messages that have already sent; pass status=all to include the ones still waiting or cancelled. ' +
+      'It returns the envelope and the engagement, not the message text - use km_read_outreach_draft for the wording. Read only.',
+    {
+      contact_id: z.string().optional().describe('UUID of a contact (see km_find_contact), for one person history.'),
+      campaign_id: z.string().optional().describe('UUID of a campaign (see km_list_outreach_campaigns).'),
+      status: z.enum(DRAFT_STATUS).optional().describe('Default sent, which is the log of what really went out.'),
+      from: z.string().optional().describe('Earliest date, YYYY-MM-DD.'),
+      to: z.string().optional().describe('Latest date, YYYY-MM-DD.'),
+      limit: z.number().int().min(1).max(100).optional().describe('Default 25.'),
+    },
+    async ({ contact_id, campaign_id, status, from, to, limit }) =>
+      out(await call('GET', `/outreach-emails${qs({ contact_id, campaign_id, status, from, to, limit })}`)),
+  );
+
+  server.tool(
+    'km_outreach_email_stats',
+    'The day by day shape of email sending across the whole workspace: sent, delivered, opened, clicked, replied, bounced and complained, one ' +
+      'row per day plus the totals for the window. Reach for it when the user asks how sending has been going lately, whether volume is up or ' +
+      'down, or whether bounces have spiked, which is the early warning that a sending domain is getting into trouble. ' +
+      'For one specific message or one person, use km_outreach_email_log instead. Read only.',
+    {
+      days: z.number().int().min(1).max(90).optional().describe('How many days back. Default 30.'),
+    },
+    async ({ days }) => out(await call('GET', `/outreach-emails/daily${qs({ days })}`)),
+  );
+}