@kivimedia/kmhub 2.9.0 → 2.10.0

package/tools/briefing.mjs

@@ -1,91 +1,91 @@
-/**
- * Tool family: briefing - the morning handoff. One tool, one call, the whole day.
- *
- * WHY A WHOLE FAMILY FOR ONE TOOL
- * Every other family is a door onto one part of the workspace. This one is the
- * front door. A Terminal Mode session starts cold every single time: the model
- * knows the workspace exists and knows nothing about what is happening in it. The
- * old opening move was km_waiting, which hands back six counts, and then four or
- * five list calls to turn those counts back into things a person can act on. That
- * is five round trips before anyone has said a useful sentence, and a guess in the
- * middle of it about which of the six numbers actually mattered.
- *
- * km_briefing is that whole opening move as one call, with the guess replaced by a
- * ranking done on the server where the data already is. It comes back as ONE
- * ordered list, most-worth-doing first, every entry carrying the reason it is
- * there, plus the diary, plus the raw gate counts, plus one suggested play when
- * the shape of the day genuinely calls for one.
- *
- * WHAT IT DOES NOT DO
- * It reads. It cannot send, approve, complete, schedule or spend, and the play it
- * suggests is never one that can spend the client's money. Everything it surfaces
- * still ends where it ended before: a draft in the Approval Queue, a decision in
- * front of a human.
- *
- * The route behind it is GET /briefing. That route owns the ranking rule and the
- * suggestion rule, so this file passes two optional parameters through and
- * reshapes nothing.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'briefing';
-
-export const TOOLS = ['km_briefing'];
-
-// Every profile. A session that can read invoices but cannot ask what needs doing
-// today is a session that starts every conversation from nothing. This is the one
-// tool whose absence is felt in every other family's work.
-export const PROFILES = ['*'];
-
-/** The API has not shipped this route yet (404 / 405 / 501 all mean the same here). */
-function routeMissing(r) {
-  return r.status === 404 || r.status === 405 || r.status === 501;
-}
-
-/**
- * If the workspace is on an older kmhub-api, say so in one sentence and name the
- * fallback. This is the first tool of the session, so an unexplained JSON 404 here
- * would set the tone for everything after it.
- */
-const NOT_SUPPORTED =
-  'This KM Hub is on an older version of the API that does not have the morning briefing yet. Nothing is broken and no data is missing. Fall back to km_waiting for the gate counts, then km_list_outreach_drafts, km_list_outreach_replies, km_list_tasks with overdue true, km_list_invoices with overdue true, and km_my_schedule for the diary. Say plainly that you are stitching it together by hand rather than pretending you have the ranked version.';
-
-/**
- * @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 shared response helpers from ../tools.mjs
- */
-export function register(server, call, { out, text, qs }) {
-  server.tool(
-    'km_briefing',
-    'THE FIRST TOOL TO REACH FOR on any open question about the day. If the user says any of "what needs me today", "what have I got on", "morning", "catch me up", "where are we", "what should I do first", "anything urgent", "what did I miss", or opens a session without a specific task, call this before anything else and answer from what it returns. ' +
-      'It REPLACES the old opening sequence entirely: km_waiting plus km_list_outreach_drafts plus km_list_outreach_replies plus km_list_tasks plus km_list_invoices plus km_my_schedule, all in one call. Do not run those first and do not run them afterwards to double check. Go to a list tool only when the user asks for more of one specific thing than the briefing carried, for example the full text of a draft (km_read_outreach_draft) or every invoice rather than only the late ones (km_list_invoices). ' +
-      'What comes back, in one response: a headline sentence you can read straight out loud; `items`, ONE list ranked in the order a person should actually deal with them, each with a plain reason it is there; `calendar`, today and the next few days including any date that is only pencilled in and has nothing signed behind it; `waiting`, the same raw gate counts km_waiting would have given you; and `suggested_play` when the shape of the day genuinely calls for one. ' +
-      'The ranking is not a list of lists. A new enquiry nobody has answered and a reply nobody has handled sit near the top because they are the things that stop being worth anything if you leave them, and money that is already late and worth real amounts outranks something merely unread. A gig today is near the top too, but as a fact to absorb rather than a decision to make. Trust the order: work down it, and do not silently re-sort it into your own idea of importance. Each item carries `score` so you can see why it sits where it does, and `next_tool` naming the read tool that opens it. ' +
-      'Read the `notes` array and the `complete` flag before you summarise. When a part of the workspace could not be read, the briefing says which part rather than quietly showing an empty list, and you must pass that on rather than telling somebody they have a clear day when you do not know that. ' +
-      'This tool only reads. It never sends, approves, completes, schedules or spends anything, and a play it suggests is never one that can spend money.',
-    {
-      days: z
-        .number()
-        .int()
-        .min(1)
-        .max(14)
-        .optional()
-        .describe('How far ahead the calendar part looks, in days including today. Default 3. Raise it when the user asks about the week or the fortnight ahead.'),
-      limit: z
-        .number()
-        .int()
-        .min(1)
-        .max(60)
-        .optional()
-        .describe('How many ranked items to return, most important first. Default 25, which is already more than a person will do in a morning. `counts.truncated` tells you when there were more.'),
-    },
-    async ({ days, limit }) => {
-      const r = await call('GET', `/briefing${qs({ days, limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-}
+/**
+ * Tool family: briefing - the morning handoff. One tool, one call, the whole day.
+ *
+ * WHY A WHOLE FAMILY FOR ONE TOOL
+ * Every other family is a door onto one part of the workspace. This one is the
+ * front door. A Terminal Mode session starts cold every single time: the model
+ * knows the workspace exists and knows nothing about what is happening in it. The
+ * old opening move was km_waiting, which hands back six counts, and then four or
+ * five list calls to turn those counts back into things a person can act on. That
+ * is five round trips before anyone has said a useful sentence, and a guess in the
+ * middle of it about which of the six numbers actually mattered.
+ *
+ * km_briefing is that whole opening move as one call, with the guess replaced by a
+ * ranking done on the server where the data already is. It comes back as ONE
+ * ordered list, most-worth-doing first, every entry carrying the reason it is
+ * there, plus the diary, plus the raw gate counts, plus one suggested play when
+ * the shape of the day genuinely calls for one.
+ *
+ * WHAT IT DOES NOT DO
+ * It reads. It cannot send, approve, complete, schedule or spend, and the play it
+ * suggests is never one that can spend the client's money. Everything it surfaces
+ * still ends where it ended before: a draft in the Approval Queue, a decision in
+ * front of a human.
+ *
+ * The route behind it is GET /briefing. That route owns the ranking rule and the
+ * suggestion rule, so this file passes two optional parameters through and
+ * reshapes nothing.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'briefing';
+
+export const TOOLS = ['km_briefing'];
+
+// Every profile. A session that can read invoices but cannot ask what needs doing
+// today is a session that starts every conversation from nothing. This is the one
+// tool whose absence is felt in every other family's work.
+export const PROFILES = ['*'];
+
+/** The API has not shipped this route yet (404 / 405 / 501 all mean the same here). */
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+/**
+ * If the workspace is on an older kmhub-api, say so in one sentence and name the
+ * fallback. This is the first tool of the session, so an unexplained JSON 404 here
+ * would set the tone for everything after it.
+ */
+const NOT_SUPPORTED =
+  'This KM Hub is on an older version of the API that does not have the morning briefing yet. Nothing is broken and no data is missing. Fall back to km_waiting for the gate counts, then km_list_outreach_drafts, km_list_outreach_replies, km_list_tasks with overdue true, km_list_invoices with overdue true, and km_my_schedule for the diary. Say plainly that you are stitching it together by hand rather than pretending you have the ranked version.';
+
+/**
+ * @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 shared response helpers from ../tools.mjs
+ */
+export function register(server, call, { out, text, qs }) {
+  server.tool(
+    'km_briefing',
+    'THE FIRST TOOL TO REACH FOR on any open question about the day. If the user says any of "what needs me today", "what have I got on", "morning", "catch me up", "where are we", "what should I do first", "anything urgent", "what did I miss", or opens a session without a specific task, call this before anything else and answer from what it returns. ' +
+      'It REPLACES the old opening sequence entirely: km_waiting plus km_list_outreach_drafts plus km_list_outreach_replies plus km_list_tasks plus km_list_invoices plus km_my_schedule, all in one call. Do not run those first and do not run them afterwards to double check. Go to a list tool only when the user asks for more of one specific thing than the briefing carried, for example the full text of a draft (km_read_outreach_draft) or every invoice rather than only the late ones (km_list_invoices). ' +
+      'What comes back, in one response: a headline sentence you can read straight out loud; `items`, ONE list ranked in the order a person should actually deal with them, each with a plain reason it is there; `calendar`, today and the next few days including any date that is only pencilled in and has nothing signed behind it; `waiting`, the same raw gate counts km_waiting would have given you; and `suggested_play` when the shape of the day genuinely calls for one. ' +
+      'The ranking is not a list of lists. A new enquiry nobody has answered and a reply nobody has handled sit near the top because they are the things that stop being worth anything if you leave them, and money that is already late and worth real amounts outranks something merely unread. A gig today is near the top too, but as a fact to absorb rather than a decision to make. Trust the order: work down it, and do not silently re-sort it into your own idea of importance. Each item carries `score` so you can see why it sits where it does, and `next_tool` naming the read tool that opens it. ' +
+      'Read the `notes` array and the `complete` flag before you summarise. When a part of the workspace could not be read, the briefing says which part rather than quietly showing an empty list, and you must pass that on rather than telling somebody they have a clear day when you do not know that. ' +
+      'This tool only reads. It never sends, approves, completes, schedules or spends anything, and a play it suggests is never one that can spend money.',
+    {
+      days: z
+        .number()
+        .int()
+        .min(1)
+        .max(14)
+        .optional()
+        .describe('How far ahead the calendar part looks, in days including today. Default 3. Raise it when the user asks about the week or the fortnight ahead.'),
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(60)
+        .optional()
+        .describe('How many ranked items to return, most important first. Default 25, which is already more than a person will do in a morning. `counts.truncated` tells you when there were more.'),
+    },
+    async ({ days, limit }) => {
+      const r = await call('GET', `/briefing${qs({ days, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}

package/tools/calendar.mjs

@@ -1,170 +1,170 @@
-/**
- * Tool family: calendar - the diary. What is on, what is free, and what one gig is.
- *
- * core.mjs already lists bookings and calendar events. This family is for the
- * questions a performer asks in a car park at 5pm, where the answer has to
- * arrive in one tool call and be readable out loud:
- *
- *   km_my_schedule        what have I got this week
- *   km_check_availability am I free on that date, and at that hour
- *   km_get_booking        tell me everything about this gig
- *   km_update_booking     fix the details of a gig that is already agreed
- *   km_blocked_dates      which days are already spoken for
- *
- * The availability answer is computed by the same database functions that drive
- * the public booking widget and the lead gate, never re-derived on the way past,
- * because a second opinion about a free Saturday is how a real person ends up
- * double booked. When those functions decline to answer, the tool says it cannot
- * tell rather than guessing "free".
- *
- * km_update_booking is deliberately the narrowest write in the whole server. It
- * cannot move a date or a time, cannot touch money, and cannot cancel or
- * complete anything, because those commit the business to something a person
- * should be the one to commit to. It can confirm, and the description says in
- * plain words what confirming does to the calendar.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'calendar';
-
-export const TOOLS = [
-  'km_my_schedule',
-  'km_check_availability',
-  'km_get_booking',
-  'km_update_booking',
-  'km_blocked_dates',
-];
-
-// The diary is the context every other family reasons against: a money question
-// and a follow-up question both start with what is already on the books. It
-// carries five tools, so the cost of joining every profile is small.
-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_my_schedule',
-    'What is on in KM Hub, day by day, in one call. Reach for this when the question is specifically '
-      + 'about the DIARY: a named week, a named day, or the next gig. "What have I got this week", '
-      + '"am I busy Saturday", "when is my next gig". Do NOT answer the broad question about the day from '
-      + 'here: if the person says "what needs me today", "catch me up", "what should I do first", or just '
-      + 'opens a session with nothing specific, km_briefing is the tool. It carries this diary AND the '
-      + 'enquiries, replies, tasks and money that are waiting, ranked against each other, none of which '
-      + 'this tool can see. Running both means paying for the same diary twice. It returns a plain-English '
-      + 'headline, one readable line per day, and the detail behind each line: the gigs with their times, '
-      + 'client, venue, guest count and fee, anything else in the diary, days blocked off, and dates that '
-      + 'are only pencilled in by a live lead. Days are counted in the workspace timezone, so "today" means '
-      + 'today where the performer is. Defaults to the next 7 days starting today. Read only: it never '
-      + 'changes anything. Use km_check_availability instead when the question is whether a specific date '
-      + 'is free rather than what is already booked.',
-    {
-      from: z.string().optional().describe('First day, YYYY-MM-DD. Defaults to today in the workspace timezone.'),
-      days: z.number().int().min(1).max(31).optional().describe('How many days to cover, 1 to 31. Default 7.'),
-    },
-    async ({ from, days }) => out(await call('GET', `/schedule${qs({ from, days })}`)),
-  );
-
-  server.tool(
-    'km_check_availability',
-    'Is a date free for a booking. Ask this before telling anyone a date might work. The verdict comes '
-      + 'from the same availability check that the public booking page and the lead forms use, so it '
-      + 'already counts confirmed bookings, days blocked off by hand, weekends the workspace does not work, '
-      + 'and dates a live lead has pencilled in. Give start_time (and optionally end_time or '
-      + 'duration_minutes, plus setup, packdown and travel padding) and it answers for that time window '
-      + 'instead of the whole day, so two non-overlapping gigs on one day both read as possible. Alongside '
-      + 'each verdict it lists what is actually in the diary that day, so a "taken" comes with the gig that '
-      + 'is taking it. If the workspace has switched its availability check off, the tool reports that it '
-      + 'cannot give a verdict and shows the diary instead: it will never call a day free when it does not '
-      + 'know. Read only, and it never reserves or holds anything.',
-    {
-      from: z.string().optional().describe('First date to check, YYYY-MM-DD. Defaults to today in the workspace timezone.'),
-      to: z.string().optional().describe('Last date to check, YYYY-MM-DD. Defaults to the same day as from. Up to 92 days for a whole-day check, 14 days when a start_time is given.'),
-      start_time: z.string().optional().describe('Start of the slot, HH:MM in 24 hour time. Supply it to check a time window rather than the whole day.'),
-      end_time: z.string().optional().describe('End of the slot, HH:MM in 24 hour time. Only meaningful with start_time; without it the workspace default duration is used.'),
-      duration_minutes: z.number().int().min(1).max(1440).optional().describe('How long the gig runs, when end_time is unknown.'),
-      buffer_before_minutes: z.number().int().min(0).max(1440).optional().describe('Setup time needed before the slot.'),
-      buffer_after_minutes: z.number().int().min(0).max(1440).optional().describe('Packdown time needed after the slot.'),
-      travel_minutes: z.number().int().min(0).max(1440).optional().describe('Travel time each way, added to both ends of the window.'),
-    },
-    async (args) => out(await call('GET', `/availability${qs(args)}`)),
-  );
-
-  server.tool(
-    'km_get_booking',
-    'Everything about one booking in KM Hub: the date, the start, end and setup times, the client with '
-      + 'their phone and email, the venue with its address and on-site contact, the event type and guest '
-      + 'count, the fee with deposit and outstanding balance, the client notes, internal notes and special '
-      + 'requirements, the pipeline deal it belongs to, and any diary entries attached to it. This is the '
-      + 'tool for "what is this gig", "where am I playing on Saturday", "who is the contact for the Kaplan '
-      + 'wedding" and "what do I need to bring". Needs the booking id, which km_my_schedule and '
-      + 'km_list_bookings both return. Read only.',
-    {
-      booking_id: z.string().describe('UUID of the booking (from km_my_schedule or km_list_bookings).'),
-    },
-    async ({ booking_id }) => out(await call('GET', `/bookings/${encodeURIComponent(String(booking_id || '').trim())}`)),
-  );
-
-  server.tool(
-    'km_update_booking',
-    'Correct the working details of a gig that is already agreed: its title, event type, guest count, '
-      + 'setup time, venue, client notes, internal notes, special requirements, and its status. '
-      + 'CONFIRMING IS CONSEQUENTIAL: setting status to confirmed marks that whole date as taken across '
-      + 'KM Hub, so the public booking page, the lead forms and every availability check start turning '
-      + 'other people away from it. Moving the status back to pending releases the date and offers it '
-      + 'again. Only make that call when the performer has actually said the gig is on or off. '
-      + 'WHAT THIS TOOL WILL NOT DO, by design, so do not try: it cannot move a booking to another date, '
-      + 'cannot change the start or end time, cannot change the fee, deposit or balance, cannot mark money '
-      + 'as paid, cannot mark a gig completed, and cannot cancel one. Those bind the business or free a '
-      + 'date for someone else, so a person does them in KM Hub. It also refuses to touch a gig that is '
-      + 'already completed or cancelled, and any booking owned by the meeting scheduler. Every change is '
-      + 'written to the AI activity log so the owner can see it; booking edits are not auto-undoable, so '
-      + 'get it right rather than counting on undo.',
-    {
-      booking_id: z.string().describe('UUID of the booking (from km_my_schedule or km_list_bookings).'),
-      title: z.string().optional().describe('What the gig is called on the calendar.'),
-      event_type: z.string().optional().describe('e.g. wedding, corporate, birthday. The value "meeting" is reserved by the scheduler and is refused.'),
-      guest_count: z.number().int().min(0).nullable().optional().describe('How many people are expected. Send null to clear it.'),
-      setup_start_time: z.string().nullable().optional().describe('Load-in time, HH:MM in 24 hour time. This is the performer\'s own logistics, not the event start. Send null to clear it.'),
-      venue_id: z.string().optional().describe('UUID of a venue already in this workspace.'),
-      client_notes: z.string().optional().describe('Notes the client would be shown.'),
-      internal_notes: z.string().optional().describe('Notes only the team sees.'),
-      special_requirements: z.string().optional().describe('Anything the gig needs: access, power, dress code, dietary.'),
-      status: z
-        .enum(['pending', 'confirmed', 'in_progress'])
-        .optional()
-        .describe('confirmed marks the date taken everywhere; pending releases it; in_progress means the gig is under way. Cancelled and completed are not available here.'),
-      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 ({ booking_id, ...changes }) =>
-      out(await call('PATCH', `/bookings/${encodeURIComponent(String(booking_id || '').trim())}`, changes)),
-  );
-
-  server.tool(
-    'km_blocked_dates',
-    'The days that are already spoken for in KM Hub without being a gig: dates blocked off by hand with '
-      + 'their reason (holiday, family, studio time), and active holds, including dates a live lead has '
-      + 'pencilled in and that will expire on their own if the lead goes cold. Use it to answer "what am I '
-      + 'blocked out for", "why does that weekend show as unavailable", or before suggesting dates to '
-      + 'someone. Defaults to the next 90 days. Read only: blocking or unblocking a date decides whether '
-      + 'real work can be booked, so a person does that in KM Hub.',
-    {
-      from: z.string().optional().describe('First date, YYYY-MM-DD. Defaults to today in the workspace timezone.'),
-      to: z.string().optional().describe('Last date, YYYY-MM-DD. Defaults to 90 days out. At most a year at a time.'),
-    },
-    async ({ from, to }) => out(await call('GET', `/blocked-dates${qs({ from, to })}`)),
-  );
-}
+/**
+ * Tool family: calendar - the diary. What is on, what is free, and what one gig is.
+ *
+ * core.mjs already lists bookings and calendar events. This family is for the
+ * questions a performer asks in a car park at 5pm, where the answer has to
+ * arrive in one tool call and be readable out loud:
+ *
+ *   km_my_schedule        what have I got this week
+ *   km_check_availability am I free on that date, and at that hour
+ *   km_get_booking        tell me everything about this gig
+ *   km_update_booking     fix the details of a gig that is already agreed
+ *   km_blocked_dates      which days are already spoken for
+ *
+ * The availability answer is computed by the same database functions that drive
+ * the public booking widget and the lead gate, never re-derived on the way past,
+ * because a second opinion about a free Saturday is how a real person ends up
+ * double booked. When those functions decline to answer, the tool says it cannot
+ * tell rather than guessing "free".
+ *
+ * km_update_booking is deliberately the narrowest write in the whole server. It
+ * cannot move a date or a time, cannot touch money, and cannot cancel or
+ * complete anything, because those commit the business to something a person
+ * should be the one to commit to. It can confirm, and the description says in
+ * plain words what confirming does to the calendar.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'calendar';
+
+export const TOOLS = [
+  'km_my_schedule',
+  'km_check_availability',
+  'km_get_booking',
+  'km_update_booking',
+  'km_blocked_dates',
+];
+
+// The diary is the context every other family reasons against: a money question
+// and a follow-up question both start with what is already on the books. It
+// carries five tools, so the cost of joining every profile is small.
+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_my_schedule',
+    'What is on in KM Hub, day by day, in one call. Reach for this when the question is specifically '
+      + 'about the DIARY: a named week, a named day, or the next gig. "What have I got this week", '
+      + '"am I busy Saturday", "when is my next gig". Do NOT answer the broad question about the day from '
+      + 'here: if the person says "what needs me today", "catch me up", "what should I do first", or just '
+      + 'opens a session with nothing specific, km_briefing is the tool. It carries this diary AND the '
+      + 'enquiries, replies, tasks and money that are waiting, ranked against each other, none of which '
+      + 'this tool can see. Running both means paying for the same diary twice. It returns a plain-English '
+      + 'headline, one readable line per day, and the detail behind each line: the gigs with their times, '
+      + 'client, venue, guest count and fee, anything else in the diary, days blocked off, and dates that '
+      + 'are only pencilled in by a live lead. Days are counted in the workspace timezone, so "today" means '
+      + 'today where the performer is. Defaults to the next 7 days starting today. Read only: it never '
+      + 'changes anything. Use km_check_availability instead when the question is whether a specific date '
+      + 'is free rather than what is already booked.',
+    {
+      from: z.string().optional().describe('First day, YYYY-MM-DD. Defaults to today in the workspace timezone.'),
+      days: z.number().int().min(1).max(31).optional().describe('How many days to cover, 1 to 31. Default 7.'),
+    },
+    async ({ from, days }) => out(await call('GET', `/schedule${qs({ from, days })}`)),
+  );
+
+  server.tool(
+    'km_check_availability',
+    'Is a date free for a booking. Ask this before telling anyone a date might work. The verdict comes '
+      + 'from the same availability check that the public booking page and the lead forms use, so it '
+      + 'already counts confirmed bookings, days blocked off by hand, weekends the workspace does not work, '
+      + 'and dates a live lead has pencilled in. Give start_time (and optionally end_time or '
+      + 'duration_minutes, plus setup, packdown and travel padding) and it answers for that time window '
+      + 'instead of the whole day, so two non-overlapping gigs on one day both read as possible. Alongside '
+      + 'each verdict it lists what is actually in the diary that day, so a "taken" comes with the gig that '
+      + 'is taking it. If the workspace has switched its availability check off, the tool reports that it '
+      + 'cannot give a verdict and shows the diary instead: it will never call a day free when it does not '
+      + 'know. Read only, and it never reserves or holds anything.',
+    {
+      from: z.string().optional().describe('First date to check, YYYY-MM-DD. Defaults to today in the workspace timezone.'),
+      to: z.string().optional().describe('Last date to check, YYYY-MM-DD. Defaults to the same day as from. Up to 92 days for a whole-day check, 14 days when a start_time is given.'),
+      start_time: z.string().optional().describe('Start of the slot, HH:MM in 24 hour time. Supply it to check a time window rather than the whole day.'),
+      end_time: z.string().optional().describe('End of the slot, HH:MM in 24 hour time. Only meaningful with start_time; without it the workspace default duration is used.'),
+      duration_minutes: z.number().int().min(1).max(1440).optional().describe('How long the gig runs, when end_time is unknown.'),
+      buffer_before_minutes: z.number().int().min(0).max(1440).optional().describe('Setup time needed before the slot.'),
+      buffer_after_minutes: z.number().int().min(0).max(1440).optional().describe('Packdown time needed after the slot.'),
+      travel_minutes: z.number().int().min(0).max(1440).optional().describe('Travel time each way, added to both ends of the window.'),
+    },
+    async (args) => out(await call('GET', `/availability${qs(args)}`)),
+  );
+
+  server.tool(
+    'km_get_booking',
+    'Everything about one booking in KM Hub: the date, the start, end and setup times, the client with '
+      + 'their phone and email, the venue with its address and on-site contact, the event type and guest '
+      + 'count, the fee with deposit and outstanding balance, the client notes, internal notes and special '
+      + 'requirements, the pipeline deal it belongs to, and any diary entries attached to it. This is the '
+      + 'tool for "what is this gig", "where am I playing on Saturday", "who is the contact for the Kaplan '
+      + 'wedding" and "what do I need to bring". Needs the booking id, which km_my_schedule and '
+      + 'km_list_bookings both return. Read only.',
+    {
+      booking_id: z.string().describe('UUID of the booking (from km_my_schedule or km_list_bookings).'),
+    },
+    async ({ booking_id }) => out(await call('GET', `/bookings/${encodeURIComponent(String(booking_id || '').trim())}`)),
+  );
+
+  server.tool(
+    'km_update_booking',
+    'Correct the working details of a gig that is already agreed: its title, event type, guest count, '
+      + 'setup time, venue, client notes, internal notes, special requirements, and its status. '
+      + 'CONFIRMING IS CONSEQUENTIAL: setting status to confirmed marks that whole date as taken across '
+      + 'KM Hub, so the public booking page, the lead forms and every availability check start turning '
+      + 'other people away from it. Moving the status back to pending releases the date and offers it '
+      + 'again. Only make that call when the performer has actually said the gig is on or off. '
+      + 'WHAT THIS TOOL WILL NOT DO, by design, so do not try: it cannot move a booking to another date, '
+      + 'cannot change the start or end time, cannot change the fee, deposit or balance, cannot mark money '
+      + 'as paid, cannot mark a gig completed, and cannot cancel one. Those bind the business or free a '
+      + 'date for someone else, so a person does them in KM Hub. It also refuses to touch a gig that is '
+      + 'already completed or cancelled, and any booking owned by the meeting scheduler. Every change is '
+      + 'written to the AI activity log so the owner can see it; booking edits are not auto-undoable, so '
+      + 'get it right rather than counting on undo.',
+    {
+      booking_id: z.string().describe('UUID of the booking (from km_my_schedule or km_list_bookings).'),
+      title: z.string().optional().describe('What the gig is called on the calendar.'),
+      event_type: z.string().optional().describe('e.g. wedding, corporate, birthday. The value "meeting" is reserved by the scheduler and is refused.'),
+      guest_count: z.number().int().min(0).nullable().optional().describe('How many people are expected. Send null to clear it.'),
+      setup_start_time: z.string().nullable().optional().describe('Load-in time, HH:MM in 24 hour time. This is the performer\'s own logistics, not the event start. Send null to clear it.'),
+      venue_id: z.string().optional().describe('UUID of a venue already in this workspace.'),
+      client_notes: z.string().optional().describe('Notes the client would be shown.'),
+      internal_notes: z.string().optional().describe('Notes only the team sees.'),
+      special_requirements: z.string().optional().describe('Anything the gig needs: access, power, dress code, dietary.'),
+      status: z
+        .enum(['pending', 'confirmed', 'in_progress'])
+        .optional()
+        .describe('confirmed marks the date taken everywhere; pending releases it; in_progress means the gig is under way. Cancelled and completed are not available here.'),
+      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 ({ booking_id, ...changes }) =>
+      out(await call('PATCH', `/bookings/${encodeURIComponent(String(booking_id || '').trim())}`, changes)),
+  );
+
+  server.tool(
+    'km_blocked_dates',
+    'The days that are already spoken for in KM Hub without being a gig: dates blocked off by hand with '
+      + 'their reason (holiday, family, studio time), and active holds, including dates a live lead has '
+      + 'pencilled in and that will expire on their own if the lead goes cold. Use it to answer "what am I '
+      + 'blocked out for", "why does that weekend show as unavailable", or before suggesting dates to '
+      + 'someone. Defaults to the next 90 days. Read only: blocking or unblocking a date decides whether '
+      + 'real work can be booked, so a person does that in KM Hub.',
+    {
+      from: z.string().optional().describe('First date, YYYY-MM-DD. Defaults to today in the workspace timezone.'),
+      to: z.string().optional().describe('Last date, YYYY-MM-DD. Defaults to 90 days out. At most a year at a time.'),
+    },
+    async ({ from, to }) => out(await call('GET', `/blocked-dates${qs({ from, to })}`)),
+  );
+}