@kivimedia/kmhub 2.9.1 → 2.11.0

package/tools/crm.mjs

@@ -1,209 +1,209 @@
-/**
- * Tool family: crm - opening a record, changing it, and keeping the follow-ups.
- *
- * core gives you the lists: clients, deals, bookings. This family gives you the
- * one record behind a list row, the small edits that keep a CRM honest, the deal
- * board move, and tasks (which core cannot see at all).
- *
- * One tool per route in supabase/functions/kmhub-api/routes/crm.ts. Nothing here
- * deletes anything, and nothing here sends anything to a client of the workspace.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'crm';
-
-export const TOOLS = [
-  'km_find_contact',
-  'km_get_client',
-  'km_update_client',
-  'km_get_deal',
-  'km_move_deal_stage',
-  'km_set_deal_status',
-  'km_list_tasks',
-  'km_create_task',
-  'km_complete_task',
-  'km_log_touch',
-];
-
-/**
- * Every profile. core already puts km_list_clients and km_list_deals in front of
- * every caller, so a profile that can list records but cannot open one of them is
- * a broken profile, whatever else it was narrowed to.
- */
-export const PROFILES = ['*'];
-
-/**
- * @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_find_contact',
-    'THE way to turn a name a person says out loud into a record you can act on. Search contacts by first name, last name, company, or part of an email, or filter by a tag. Reach for this the moment someone says "the ABRA Auto Body draft" or "that magician from the fair" or "the motorsport people" - you cannot act on a name until you have the record. Do NOT reach for km_list_clients to find a named person: that one returns only the most recently added contacts, so anyone added a while ago will not be in it and you will wrongly conclude they do not exist. If this comes back empty, the contact genuinely is not in the workspace under that spelling: say so and offer to create them, rather than guessing. Read only.',
-    {
-      q: z.string().optional().describe('A name, company, or part of an email. Partial and case-insensitive, so "abra" finds "ABRA Auto Body & Glass".'),
-      tag: z.string().optional().describe('Filter by an exact tag, which is how a group like a market segment was labelled. Combine with q to search inside a group.'),
-      limit: z.number().int().min(1).max(100).optional().describe('Default 25.'),
-    },
-    async ({ q, tag, limit }) => out(await call('GET', `/clients/search${qs({ q, tag, limit })}`)),
-  );
-
-  server.tool(
-    'km_get_client',
-    'Open ONE client or lead and see everything you would want in front of you before you contact them: their details, the deals they are in, their bookings, anything still open on your side, and the last few conversations anyone recorded. Reach for this whenever you are about to write to someone, quote someone, or answer "what is going on with X", so you are working from their real history rather than from memory. Get the id from km_find_contact. If the record was merged into another contact the answer says so, and the surviving contact is the one to use. Read only: it changes nothing.',
-    {
-      client_id: z.string().describe('The client UUID, from km_find_contact.'),
-    },
-    async ({ client_id }) => out(await call('GET', `/clients/${encodeURIComponent(String(client_id ?? '').trim())}`)),
-  );
-
-  server.tool(
-    'km_update_client',
-    'Correct or fill in the details on an existing client: a new phone number, a spelling, a company name, an address, a note to self. Use it when the person tells you something has changed, or when you spot something wrong while looking at their record. Send only the fields you actually want to change; everything you leave out stays exactly as it is, and passing null to a field clears it. It will NOT touch anything the workspace works out for itself, like their lifetime value, their booking count or their billing links, and it cannot move a client to another workspace. There is no way to delete a client from here. The change is recorded in the AI activity log so the owner can see what you did, but unlike a newly created record it cannot be auto-undone, so read the current details back with km_get_client first if you are not certain.',
-    {
-      client_id: z.string().describe('The client UUID, from km_find_contact or km_get_client.'),
-      first_name: z.string().optional().describe('Cannot be emptied - every contact needs at least a first name.'),
-      last_name: z.string().nullable().optional(),
-      company_name: z.string().nullable().optional(),
-      email: z.string().nullable().optional(),
-      phone: z.string().nullable().optional(),
-      job_title: z.string().nullable().optional(),
-      website: z.string().nullable().optional(),
-      linkedin_url: z.string().nullable().optional(),
-      address_line_1: z.string().nullable().optional(),
-      city: z.string().nullable().optional(),
-      state: z.string().nullable().optional(),
-      postal_code: z.string().nullable().optional(),
-      country_code: z.string().nullable().optional(),
-      type: z.string().nullable().optional().describe('What kind of contact this is, e.g. individual or company.'),
-      notes: z.string().nullable().optional().describe('Free notes on the contact. This REPLACES the existing notes, so read them first if you mean to add to them.'),
-      // tags deliberately absent: a tag can arm an automation that emails or texts
-      // the client, so it stays a human action in KM Hub. See routes/crm.ts.
-    },
-    async ({ client_id, ...fields }) =>
-      out(await call('PATCH', `/clients/${encodeURIComponent(String(client_id ?? '').trim())}`, fields)),
-  );
-
-  server.tool(
-    'km_get_deal',
-    'Open ONE deal from the sales board and see where it stands: the money, the event, who the contact is, every stage it has moved through and when, and the exact list of stages it is allowed to move to next. Reach for this before moving a deal, before quoting on it, or when someone asks what is happening with a particular job. The available_stages in the answer are that board\'s real columns, which may be customised for this workspace, so use them rather than guessing stage names. Read only: it changes nothing.',
-    {
-      deal_id: z.string().describe('The deal UUID, from km_list_deals.'),
-    },
-    async ({ deal_id }) => out(await call('GET', `/deals/${encodeURIComponent(String(deal_id ?? '').trim())}`)),
-  );
-
-  server.tool(
-    'km_move_deal_stage',
-    'Move a deal to a different column on the sales board, for example from Qualifying to Quoting when a price has gone out. The deal\'s open / won / lost standing follows the stage automatically, so the board and the reporting can never disagree. The move is reversible: you can move it back the same way, and every move is kept on the deal\'s own history. IMPORTANT: moving a deal into a stage that marks it WON or LOST is not routine bookkeeping, it changes what this workspace believes about its own money and its own pipeline. Confirm with the person first, in plain words, before you make that particular move, and never infer it from an ambiguous message. Call km_get_deal first to see the stages this board actually has.',
-    {
-      deal_id: z.string().describe('The deal UUID, from km_list_deals or km_get_deal.'),
-      stage: z
-        .string()
-        .describe('The stage slug to move into. Use one of the available_stages from km_get_deal. On a standard board those are inbound, qualifying, quoting, proposal_sent, booked, in_progress, completed, lost, abandoned.'),
-      reason: z
-        .string()
-        .optional()
-        .describe('A short plain-language reason, kept on the deal history so the owner can see why it moved.'),
-    },
-    async ({ deal_id, stage, reason }) =>
-      out(await call('PATCH', `/deals/${encodeURIComponent(String(deal_id ?? '').trim())}/stage`, { stage, reason })),
-  );
-
-  server.tool(
-    'km_set_deal_status',
-    'Set whether a deal counts as open, won, lost or abandoned WITHOUT moving it to another column. Use this in the narrow case where the deal is already sitting in the right place on the board but the answer has finally come back, for example a proposal that was declined. In every other case prefer km_move_deal_stage, which keeps the board and the standing in step for you. Marking a deal won or lost changes what this workspace believes about its own money, so confirm with the person first and never infer it. Nothing here is auto-undoable, though the change is kept on the deal history and in the AI activity log.',
-    {
-      deal_id: z.string().describe('The deal UUID, from km_list_deals or km_get_deal.'),
-      status: z
-        .enum(['open', 'won', 'lost', 'abandoned'])
-        .describe('open = still live, won = the work is theirs, lost = they said no, abandoned = it went quiet and is not coming back.'),
-      lost_reason: z.string().optional().describe('Why it was lost, in the person\'s own words. Only kept for lost or abandoned.'),
-      reason: z.string().optional().describe('A short note kept on the deal history explaining the change.'),
-      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 ({ deal_id, status, lost_reason, reason, confirm_token }) =>
-      out(await call('PATCH', `/deals/${encodeURIComponent(String(deal_id ?? '').trim())}/status`, { status, lost_reason, reason, confirm_token })),
-  );
-
-  server.tool(
-    'km_list_tasks',
-    'List the jobs on the workspace to-do list. Use it to answer "what do I owe anyone", "what is late", or "what is outstanding on the Henderson wedding". Set overdue to true for the things that were due and are still not done, which is usually what someone actually means when they ask what is late. You can also narrow to one client or one booking. By default it shows the soonest due dates first, and tasks with no date at the end. Read only: it changes nothing.',
-    {
-      limit: z.number().int().min(1).max(100).optional().describe('How many to return. Default 25.'),
-      overdue: z.boolean().optional().describe('True = only work that is past its due date and still not done.'),
-      status: z
-        .enum(['pending', 'in_progress', 'completed', 'cancelled'])
-        .optional()
-        .describe('Narrow to one state. With overdue this must be pending or in_progress, because finished work cannot be late.'),
-      client_id: z.string().optional().describe('Only tasks tied to this client (UUID).'),
-      booking_id: z.string().optional().describe('Only tasks tied to this booking (UUID).'),
-    },
-    async ({ limit, overdue, status, client_id, booking_id }) =>
-      out(
-        await call(
-          'GET',
-          `/tasks${qs({
-            limit: limit ?? 25,
-            overdue: overdue ? 'true' : '',
-            status,
-            client_id,
-            booking_id,
-          })}`,
-        ),
-      ),
-  );
-
-  server.tool(
-    'km_create_task',
-    'Add a job to the workspace to-do list, optionally tied to a client or a booking, so a follow-up someone mentioned in passing does not get lost. Good for "chase the deposit on Friday", "send the Hendersons their timeline", "call the venue back". A new task always starts as not done and is never assigned to a particular person, because who does the work is the owner\'s call and not yours. A bare date like 2026-09-14 means the END of that day, so a task due today does not read as late until tomorrow. Creating a task is fully undoable from the AI activity log.',
-    {
-      name: z.string().describe('What the task is, in one line. This is what the owner will read on their list.'),
-      description: z.string().optional().describe('Any detail that will not fit in the name. Up to 20,000 characters, and a longer one is refused with its length rather than stored short.'),
-      due_date: z.string().optional().describe('YYYY-MM-DD, or a full ISO timestamp when the time of day matters.'),
-      client_id: z.string().optional().describe('Tie it to a client (UUID), so it shows on their record.'),
-      booking_id: z.string().optional().describe('Tie it to a booking (UUID), so it shows against that job.'),
-    },
-    async (args) => out(await call('POST', '/tasks', args)),
-  );
-
-  server.tool(
-    'km_complete_task',
-    'Tick a task off the list once the person tells you it is done. Get the id from km_list_tasks. If it was already ticked off, this says so and changes nothing, so it is safe to call twice. It does not delete the task: completed work stays on the record where it can be seen. There is no way to delete a task from here, and no way to un-complete one, so only call it when you have been told the work is actually finished.',
-    {
-      task_id: z.string().describe('The task UUID, from km_list_tasks.'),
-    },
-    async ({ task_id }) =>
-      out(await call('POST', `/tasks/${encodeURIComponent(String(task_id ?? '').trim())}/complete`)),
-  );
-
-  server.tool(
-    'km_log_touch',
-    'Write down something that ALREADY happened with a client, so it lands on their timeline in date order next to everything else: a phone call, running into them at a venue, a DM, a card in the post. This is the place for anything that happened off the rails, which the workspace cannot see by itself. Use it whenever the person tells you about a conversation, and quote them rather than summarising, because the detail is the whole point. This tool NEVER contacts anybody: it is a private note in the workspace, not a message, and there is no path from here to one. If you only know the deal, pass deal_id and the note goes on that deal\'s contact; the answer tells you which contact it landed on. Use occurred_at when the conversation happened on a different day from the one you are typing on.',
-    {
-      note: z.string().describe('What happened, in the person\'s own words. Free text, and the more specific the better.'),
-      client_id: z.string().optional().describe('The client UUID this happened with. Give this or deal_id.'),
-      deal_id: z.string().optional().describe('A deal UUID, when you only know the job. The note goes on that deal\'s contact.'),
-      channel: z
-        .enum(['call', 'email', 'text', 'in_person', 'social', 'mail', 'other'])
-        .optional()
-        .describe('How it happened. Default other.'),
-      occurred_at: z
-        .string()
-        .optional()
-        .describe('When it actually happened, YYYY-MM-DD or a full ISO timestamp. Default now. Use it when logging a conversation from a previous day.'),
-    },
-    async (args) => out(await call('POST', '/touches', args)),
-  );
-}
+/**
+ * Tool family: crm - opening a record, changing it, and keeping the follow-ups.
+ *
+ * core gives you the lists: clients, deals, bookings. This family gives you the
+ * one record behind a list row, the small edits that keep a CRM honest, the deal
+ * board move, and tasks (which core cannot see at all).
+ *
+ * One tool per route in supabase/functions/kmhub-api/routes/crm.ts. Nothing here
+ * deletes anything, and nothing here sends anything to a client of the workspace.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'crm';
+
+export const TOOLS = [
+  'km_find_contact',
+  'km_get_client',
+  'km_update_client',
+  'km_get_deal',
+  'km_move_deal_stage',
+  'km_set_deal_status',
+  'km_list_tasks',
+  'km_create_task',
+  'km_complete_task',
+  'km_log_touch',
+];
+
+/**
+ * Every profile. core already puts km_list_clients and km_list_deals in front of
+ * every caller, so a profile that can list records but cannot open one of them is
+ * a broken profile, whatever else it was narrowed to.
+ */
+export const PROFILES = ['*'];
+
+/**
+ * @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_find_contact',
+    'THE way to turn a name a person says out loud into a record you can act on. Search contacts by first name, last name, company, or part of an email, or filter by a tag. Reach for this the moment someone says "the ABRA Auto Body draft" or "that magician from the fair" or "the motorsport people" - you cannot act on a name until you have the record. Do NOT reach for km_list_clients to find a named person: that one returns only the most recently added contacts, so anyone added a while ago will not be in it and you will wrongly conclude they do not exist. If this comes back empty, the contact genuinely is not in the workspace under that spelling: say so and offer to create them, rather than guessing. Read only.',
+    {
+      q: z.string().optional().describe('A name, company, or part of an email. Partial and case-insensitive, so "abra" finds "ABRA Auto Body & Glass".'),
+      tag: z.string().optional().describe('Filter by an exact tag, which is how a group like a market segment was labelled. Combine with q to search inside a group.'),
+      limit: z.number().int().min(1).max(100).optional().describe('Default 25.'),
+    },
+    async ({ q, tag, limit }) => out(await call('GET', `/clients/search${qs({ q, tag, limit })}`)),
+  );
+
+  server.tool(
+    'km_get_client',
+    'Open ONE client or lead and see everything you would want in front of you before you contact them: their details, the deals they are in, their bookings, anything still open on your side, and the last few conversations anyone recorded. Reach for this whenever you are about to write to someone, quote someone, or answer "what is going on with X", so you are working from their real history rather than from memory. Get the id from km_find_contact. If the record was merged into another contact the answer says so, and the surviving contact is the one to use. Read only: it changes nothing.',
+    {
+      client_id: z.string().describe('The client UUID, from km_find_contact.'),
+    },
+    async ({ client_id }) => out(await call('GET', `/clients/${encodeURIComponent(String(client_id ?? '').trim())}`)),
+  );
+
+  server.tool(
+    'km_update_client',
+    'Correct or fill in the details on an existing client: a new phone number, a spelling, a company name, an address, a note to self. Use it when the person tells you something has changed, or when you spot something wrong while looking at their record. Send only the fields you actually want to change; everything you leave out stays exactly as it is, and passing null to a field clears it. It will NOT touch anything the workspace works out for itself, like their lifetime value, their booking count or their billing links, and it cannot move a client to another workspace. There is no way to delete a client from here. The change is recorded in the AI activity log so the owner can see what you did, but unlike a newly created record it cannot be auto-undone, so read the current details back with km_get_client first if you are not certain.',
+    {
+      client_id: z.string().describe('The client UUID, from km_find_contact or km_get_client.'),
+      first_name: z.string().optional().describe('Cannot be emptied - every contact needs at least a first name.'),
+      last_name: z.string().nullable().optional(),
+      company_name: z.string().nullable().optional(),
+      email: z.string().nullable().optional(),
+      phone: z.string().nullable().optional(),
+      job_title: z.string().nullable().optional(),
+      website: z.string().nullable().optional(),
+      linkedin_url: z.string().nullable().optional(),
+      address_line_1: z.string().nullable().optional(),
+      city: z.string().nullable().optional(),
+      state: z.string().nullable().optional(),
+      postal_code: z.string().nullable().optional(),
+      country_code: z.string().nullable().optional(),
+      type: z.string().nullable().optional().describe('What kind of contact this is, e.g. individual or company.'),
+      notes: z.string().nullable().optional().describe('Free notes on the contact. This REPLACES the existing notes, so read them first if you mean to add to them.'),
+      // tags deliberately absent: a tag can arm an automation that emails or texts
+      // the client, so it stays a human action in KM Hub. See routes/crm.ts.
+    },
+    async ({ client_id, ...fields }) =>
+      out(await call('PATCH', `/clients/${encodeURIComponent(String(client_id ?? '').trim())}`, fields)),
+  );
+
+  server.tool(
+    'km_get_deal',
+    'Open ONE deal from the sales board and see where it stands: the money, the event, who the contact is, every stage it has moved through and when, and the exact list of stages it is allowed to move to next. Reach for this before moving a deal, before quoting on it, or when someone asks what is happening with a particular job. The available_stages in the answer are that board\'s real columns, which may be customised for this workspace, so use them rather than guessing stage names. Read only: it changes nothing.',
+    {
+      deal_id: z.string().describe('The deal UUID, from km_list_deals.'),
+    },
+    async ({ deal_id }) => out(await call('GET', `/deals/${encodeURIComponent(String(deal_id ?? '').trim())}`)),
+  );
+
+  server.tool(
+    'km_move_deal_stage',
+    'Move a deal to a different column on the sales board, for example from Qualifying to Quoting when a price has gone out. The deal\'s open / won / lost standing follows the stage automatically, so the board and the reporting can never disagree. The move is reversible: you can move it back the same way, and every move is kept on the deal\'s own history. IMPORTANT: moving a deal into a stage that marks it WON or LOST is not routine bookkeeping, it changes what this workspace believes about its own money and its own pipeline. Confirm with the person first, in plain words, before you make that particular move, and never infer it from an ambiguous message. Call km_get_deal first to see the stages this board actually has.',
+    {
+      deal_id: z.string().describe('The deal UUID, from km_list_deals or km_get_deal.'),
+      stage: z
+        .string()
+        .describe('The stage slug to move into. Use one of the available_stages from km_get_deal. On a standard board those are inbound, qualifying, quoting, proposal_sent, booked, in_progress, completed, lost, abandoned.'),
+      reason: z
+        .string()
+        .optional()
+        .describe('A short plain-language reason, kept on the deal history so the owner can see why it moved.'),
+    },
+    async ({ deal_id, stage, reason }) =>
+      out(await call('PATCH', `/deals/${encodeURIComponent(String(deal_id ?? '').trim())}/stage`, { stage, reason })),
+  );
+
+  server.tool(
+    'km_set_deal_status',
+    'Set whether a deal counts as open, won, lost or abandoned WITHOUT moving it to another column. Use this in the narrow case where the deal is already sitting in the right place on the board but the answer has finally come back, for example a proposal that was declined. In every other case prefer km_move_deal_stage, which keeps the board and the standing in step for you. Marking a deal won or lost changes what this workspace believes about its own money, so confirm with the person first and never infer it. Nothing here is auto-undoable, though the change is kept on the deal history and in the AI activity log.',
+    {
+      deal_id: z.string().describe('The deal UUID, from km_list_deals or km_get_deal.'),
+      status: z
+        .enum(['open', 'won', 'lost', 'abandoned'])
+        .describe('open = still live, won = the work is theirs, lost = they said no, abandoned = it went quiet and is not coming back.'),
+      lost_reason: z.string().optional().describe('Why it was lost, in the person\'s own words. Only kept for lost or abandoned.'),
+      reason: z.string().optional().describe('A short note kept on the deal history explaining the change.'),
+      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 ({ deal_id, status, lost_reason, reason, confirm_token }) =>
+      out(await call('PATCH', `/deals/${encodeURIComponent(String(deal_id ?? '').trim())}/status`, { status, lost_reason, reason, confirm_token })),
+  );
+
+  server.tool(
+    'km_list_tasks',
+    'List the jobs on the workspace to-do list. Use it to answer "what do I owe anyone", "what is late", or "what is outstanding on the Henderson wedding". Set overdue to true for the things that were due and are still not done, which is usually what someone actually means when they ask what is late. You can also narrow to one client or one booking. By default it shows the soonest due dates first, and tasks with no date at the end. Read only: it changes nothing.',
+    {
+      limit: z.number().int().min(1).max(100).optional().describe('How many to return. Default 25.'),
+      overdue: z.boolean().optional().describe('True = only work that is past its due date and still not done.'),
+      status: z
+        .enum(['pending', 'in_progress', 'completed', 'cancelled'])
+        .optional()
+        .describe('Narrow to one state. With overdue this must be pending or in_progress, because finished work cannot be late.'),
+      client_id: z.string().optional().describe('Only tasks tied to this client (UUID).'),
+      booking_id: z.string().optional().describe('Only tasks tied to this booking (UUID).'),
+    },
+    async ({ limit, overdue, status, client_id, booking_id }) =>
+      out(
+        await call(
+          'GET',
+          `/tasks${qs({
+            limit: limit ?? 25,
+            overdue: overdue ? 'true' : '',
+            status,
+            client_id,
+            booking_id,
+          })}`,
+        ),
+      ),
+  );
+
+  server.tool(
+    'km_create_task',
+    'Add a job to the workspace to-do list, optionally tied to a client or a booking, so a follow-up someone mentioned in passing does not get lost. Good for "chase the deposit on Friday", "send the Hendersons their timeline", "call the venue back". A new task always starts as not done and is never assigned to a particular person, because who does the work is the owner\'s call and not yours. A bare date like 2026-09-14 means the END of that day, so a task due today does not read as late until tomorrow. Creating a task is fully undoable from the AI activity log.',
+    {
+      name: z.string().describe('What the task is, in one line. This is what the owner will read on their list.'),
+      description: z.string().optional().describe('Any detail that will not fit in the name. Up to 20,000 characters, and a longer one is refused with its length rather than stored short.'),
+      due_date: z.string().optional().describe('YYYY-MM-DD, or a full ISO timestamp when the time of day matters.'),
+      client_id: z.string().optional().describe('Tie it to a client (UUID), so it shows on their record.'),
+      booking_id: z.string().optional().describe('Tie it to a booking (UUID), so it shows against that job.'),
+    },
+    async (args) => out(await call('POST', '/tasks', args)),
+  );
+
+  server.tool(
+    'km_complete_task',
+    'Tick a task off the list once the person tells you it is done. Get the id from km_list_tasks. If it was already ticked off, this says so and changes nothing, so it is safe to call twice. It does not delete the task: completed work stays on the record where it can be seen. There is no way to delete a task from here, and no way to un-complete one, so only call it when you have been told the work is actually finished.',
+    {
+      task_id: z.string().describe('The task UUID, from km_list_tasks.'),
+    },
+    async ({ task_id }) =>
+      out(await call('POST', `/tasks/${encodeURIComponent(String(task_id ?? '').trim())}/complete`)),
+  );
+
+  server.tool(
+    'km_log_touch',
+    'Write down something that ALREADY happened with a client, so it lands on their timeline in date order next to everything else: a phone call, running into them at a venue, a DM, a card in the post. This is the place for anything that happened off the rails, which the workspace cannot see by itself. Use it whenever the person tells you about a conversation, and quote them rather than summarising, because the detail is the whole point. This tool NEVER contacts anybody: it is a private note in the workspace, not a message, and there is no path from here to one. If you only know the deal, pass deal_id and the note goes on that deal\'s contact; the answer tells you which contact it landed on. Use occurred_at when the conversation happened on a different day from the one you are typing on.',
+    {
+      note: z.string().describe('What happened, in the person\'s own words. Free text, and the more specific the better.'),
+      client_id: z.string().optional().describe('The client UUID this happened with. Give this or deal_id.'),
+      deal_id: z.string().optional().describe('A deal UUID, when you only know the job. The note goes on that deal\'s contact.'),
+      channel: z
+        .enum(['call', 'email', 'text', 'in_person', 'social', 'mail', 'other'])
+        .optional()
+        .describe('How it happened. Default other.'),
+      occurred_at: z
+        .string()
+        .optional()
+        .describe('When it actually happened, YYYY-MM-DD or a full ISO timestamp. Default now. Use it when logging a conversation from a previous day.'),
+    },
+    async (args) => out(await call('POST', '/touches', args)),
+  );
+}