@kivimedia/kmhub 2.9.0 → 2.10.0

package/tools/plays.mjs

@@ -1,244 +1,244 @@
-/**
- * Tool family: plays - the operating intelligence, leased one step at a time.
- *
- * Every other family is a door onto the workspace data. This one is the reason a
- * client would rather have KM Hub in their terminal than a generic assistant with
- * a CRM connector: the plays are the proven ways this kind of business actually
- * gets booked, and they are worth more than any single record they touch.
- *
- * Which is why none of them live on the client's machine. The protection model,
- * stated plainly so nobody has to reverse engineer it from the code:
- *
- *   - The client's disk holds three things: a URL, an API key, and a rules file
- *     of pure orientation. No play, no runbook, no criterion, ever.
- *   - km_play_catalog returns METADATA ONLY: slug, label, and the plain reason a
- *     human would care. Never the task, never the criterion, never an internal.
- *   - km_play_run leases ONE bounded step per call. The text arrives in the
- *     conversation, is used, and is never written to a file by us.
- *   - Quotas are what stop somebody enumerating the catalog by running everything
- *     once: a cap per hour, a cap per day, and a cap on how many DIFFERENT plays
- *     in a rolling day. Repeating a play already seen in that window is free of
- *     the variety cap, so normal work never hits it and harvesting does.
- *   - Each issued step carries an HMAC watermark. Be honest about what that is:
- *     it is forensic attribution, NOT DRM. The task is plaintext in the client's
- *     own transcript and a determined person can strip the marker. It tells us
- *     WHERE a leaked task came from. It does not stop the leak.
- *   - The real kill switch is Phase 1 and it already works: cancel the
- *     subscription and the entitlement gate answers 402 on every route here, so
- *     no catalog, no runs, no rules refresh, from the next call onwards.
- *
- * Nothing in this family sends anything to anybody. A play that produces a
- * message still ends at km_create_outreach_draft and the Approval Queue.
- *
- * The routes behind it are GET /plays, POST /plays/run and POST /plays/verify.
- * They own the truth about the body shape, so the two POST handlers pass their
- * arguments straight through rather than reshaping them here.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'plays';
-
-export const TOOLS = ['km_play_catalog', 'km_play_run', 'km_play_verify'];
-
-// Every profile. A session that can read the calendar but cannot reach the plays
-// is a crippled session: the plays are what make the rest of the tools add up to
-// a way of working rather than a pile of endpoints.
-export const PROFILES = ['*'];
-
-/** The API has not shipped these routes yet (404 / 405 / 501 all mean the same here). */
-function routeMissing(r) {
-  return r.status === 404 || r.status === 405 || r.status === 501;
-}
-
-const NOT_SUPPORTED =
-  'This KM Hub does not have the plays switched on yet. Nothing is broken and nothing is lost: the workspace is fine and every other tool works as normal. Carry on with the tools you have, and say plainly that the plays are not available on this account rather than inventing a method and calling it one.';
-
-/** Round a retry delay into something a person says out loud. Empty when unknown. */
-function inAbout(seconds) {
-  const s = Number(seconds);
-  if (!Number.isFinite(s) || s <= 0) return '';
-  if (s < 90) return `about ${Math.max(1, Math.round(s))} seconds`;
-  const minutes = Math.round(s / 60);
-  if (minutes < 90) return `about ${minutes} minute${minutes === 1 ? '' : 's'}`;
-  const hours = Math.round(s / 3600);
-  return `about ${hours} hour${hours === 1 ? '' : 's'}`;
-}
-
-/**
- * Turn a 429 into a sentence a working performer understands.
- *
- * The shared out() helper already does this for a 402, and a refusal is the one
- * moment where a raw status code is least use to anybody. Two different things
- * answer 429 on this API and they need different words:
- *
- *   - `rate_limited` from the API front door: too many calls per minute. A pause
- *     fixes it.
- *   - anything else: the play allowance itself. Not a fault, not a charge, and
- *     not something a retry loop will get around.
- *
- * Returns null when the response is not a 429, so callers can carry on normally.
- */
-function quotaRefusal(r) {
-  if (!r || r.status !== 429) return null;
-  const body = r.data && typeof r.data === 'object' ? r.data : {};
-  const code = String(body.error || body.reason || body.code || '').toLowerCase();
-  const said = typeof body.message === 'string' && body.message.trim() ? body.message.trim() : '';
-  const wait = inAbout(body.retry_after ?? body.retryAfter ?? body.retry_after_seconds);
-  const lines = [];
-
-  if (code.includes('rate_limit')) {
-    lines.push('I am calling KM Hub faster than it allows, so it asked me to slow down. Nothing failed and nothing changed.');
-    lines.push(wait ? `It clears in ${wait}.` : 'It clears on its own in well under a minute.');
-    if (said) lines.push(said);
-    lines.push('Wait it out and try the same call once more. Do not split the work into more calls, which makes it worse.');
-    return { content: [{ type: 'text', text: lines.join('\n\n') }], isError: true };
-  }
-
-  const variety = code.includes('distinct') || code.includes('variety') || code.includes('skill_limit');
-  if (variety) {
-    lines.push(
-      'That is a play this workspace has not opened today, and it has already opened as many different ones as a day allows. Nothing is wrong, nothing was charged, and nothing in the workspace has changed.',
-    );
-    lines.push(
-      'A play already run today can still be run again as much as it is needed, so if one of those covers what is being asked, use it instead. Otherwise this one is worth doing tomorrow.',
-    );
-  } else {
-    lines.push(
-      'This workspace has run as many plays as its allowance covers for now. Nothing is wrong, nothing was charged, and nothing in the workspace has changed.',
-    );
-    lines.push('The allowance is there so the plays get used on real work rather than pulled through in bulk.');
-  }
-  if (said) lines.push(said);
-  lines.push(wait ? `It frees up again in ${wait}.` : 'It frees up again on its own.');
-  lines.push(
-    'Tell the person that plainly and get on with the work by hand: the clients, the calendar, the drafts and everything else are untouched and still work. Do not retry this in a loop.',
-  );
-  return { content: [{ type: 'text', text: lines.join('\n\n') }], isError: true };
-}
-
-/**
- * @param {{ tool: Function }} server guarded registrar (see ./README.md)
- * @param {(method: string, path: string, body?: any) => Promise<{ok:boolean,status:number,data:any}>} call
- * @param {{ out: Function, text: Function, qs: Function }} helpers
- */
-export function register(server, call, { out, text }) {
-  server.tool(
-    'km_play_catalog',
-    [
-      'The plays: the proven ways a business like this one actually gets booked, kept current by KM Hub and written by people who book work for a living rather than assembled from general marketing advice.',
-      'LOOK HERE FIRST whenever the ask is open ended. "What should I do today", "how do I get more corporate work", "nobody is replying to me", "help me with the fair market", "next month looks empty", "how do I get repeat bookings out of this client": there is very often a play for exactly that, and it will be sharper than anything improvised from what you already know about marketing. This is also where brand and pricing work lives, so check here before answering that the workspace has no luxury, brand, positioning or pricing capability: "am I priced too low", "does my website undersell me", "should I run a discount", "should I add this new service", "what do I say on the call about price", "do you have the luxury tools". The luxury family is in this catalog, not in the tool list.',
-      'Free, fast, sends nothing and changes nothing. What comes back is a short list, and each entry is a slug to run it by, its name, and the plain reason a working performer would care about it.',
-      'What it deliberately does NOT contain is the method. The steps are not in here and cannot be worked out from the name, so never describe how a play works or promise what it will produce from the catalog alone. The method arrives one step at a time from km_play_run, and only while the subscription is live.',
-      'Reading the catalog is not doing the work, and reciting the whole list at somebody is not an answer. Name the one or two that actually fit what they said, in their words, and offer to run one.',
-    ].join(' '),
-    {},
-    async () => {
-      const r = await call('GET', '/plays');
-      if (routeMissing(r)) return text(NOT_SUPPORTED);
-      const refused = quotaRefusal(r);
-      if (refused) return refused;
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_play_run',
-    [
-      'Run a play: start one, or come back for its next step.',
-      'This is a lease, one step at a time. KM Hub hands back a SINGLE bounded piece of work, aimed at this workspace and this situation, that you can actually finish with the km_* tools already in front of you. Do that step. Tell the person what happened in your own words. Then call this again with the same run_id to get the next one. Keep going until the play says it is finished, then call km_play_verify.',
-      'The step text is working material on loan for this run, not a document to hand over. Do not paste it back to the person verbatim, do not save it into a file, a note, a scratch document or a memory, and do not quote it at length in your reply. They asked for the outcome, not the recipe, and the recipe is the part KM Hub is paid for. Each issued step carries a marker identifying the workspace it was leased to.',
-      'Run the play that fits what was actually asked. There is an allowance on how many plays get pulled in a day and on how many DIFFERENT ones, so do not open plays speculatively, do not work down the catalog to see what each one says, and do not start a second play while the first is unfinished. A play already opened today can be run again as often as it is useful.',
-      'It sends nothing to anybody. A play that produces a message still ends at km_create_outreach_draft, in the Approval Queue, for a human to read and release. If a step asks for something you do not have, say so and ask, rather than filling the gap with a plausible guess.',
-    ].join(' '),
-    {
-      slug: z
-        .string()
-        .describe('Which play to run, exactly as km_play_catalog gave it, for example quiet-week-rescue. Never invent a slug or guess one from a name.'),
-      run_id: z
-        .string()
-        .optional()
-        .describe('Leave this out for the first step. To continue a play you already started, pass back the run id from the previous step and you get the next one.'),
-      context: z
-        .string()
-        .optional()
-        .describe('What the person actually asked for, in their own words, plus anything about right now that the step should take into account. It lets KM Hub aim the step at the real situation instead of the general case.'),
-      step_result: z
-        .string()
-        .optional()
-        .describe('Only when continuing a run: what happened on the step you just finished, in a sentence or two, including anything that did not work. The next step is built on it, so an honest account beats a tidy one.'),
-    },
-    async (args) => {
-      // Slugs are lowercase kebab everywhere in this codebase, and a model that
-      // has read the catalog once and is typing from memory will occasionally
-      // capitalise one. Fixing that here costs nothing and saves a 404.
-      const slug = String(args?.slug || '').trim().toLowerCase();
-      if (!slug) {
-        return text(
-          'I need to know which play to run. km_play_catalog lists the ones this workspace has, with the slug for each.',
-        );
-      }
-      // The route requires an idempotency_key (8-128 of [A-Za-z0-9._:-]) so a
-      // retry cannot double-spend a quota slot. It is minted here, never asked
-      // of the model: a caller-chosen key is a footgun, and a model has no
-      // basis to invent a stable one. Continuing a run reuses a key derived
-      // from the run id so a retried continuation replays instead of counting
-      // twice; a fresh run gets a random one.
-      const runId = String(args?.run_id || '').trim();
-      const idempotency_key = runId
-        ? `run-${runId.replace(/[^A-Za-z0-9._:-]/g, '')}`.slice(0, 128)
-        : crypto.randomUUID().replace(/-/g, '');
-      const r = await call('POST', '/plays/run', { ...args, slug, idempotency_key });
-      if (routeMissing(r)) return text(NOT_SUPPORTED);
-      const refused = quotaRefusal(r);
-      if (refused) return refused;
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_play_verify',
-    [
-      'Check whether the play actually worked. Every play has a criterion: the observable thing that should be true now if it did its job. That is a different question from whether you got through the steps, and it is the one that matters.',
-      'Call it when a play reaches its end, or whenever someone asks whether the thing you ran last week did anything. KM Hub gives you the criterion, you check it against what you can genuinely see through the km_* tools, and you report what you found.',
-      'Being honest here is the whole point of the tool. "I ran it, and I cannot confirm yet that it worked" is a real answer, a useful one, and far better than a confident yes that falls apart a week later. Say which part you could confirm, which part you could not, and what would settle it.',
-      'Do not call a play successful because the steps are done. Do not verify a play you did not run. This changes nothing in the workspace, sends nothing to anybody, and cannot make a play have worked.',
-    ].join(' '),
-    {
-      run_id: z
-        .string()
-        .optional()
-        .describe('The run being checked, as returned by km_play_run. Give this whenever you have it: it is what ties the criterion to the work that was actually done.'),
-      slug: z
-        .string()
-        .optional()
-        .describe('The play being checked, as km_play_catalog gave it. Pass it alongside run_id for context. On its own it is not enough: the check is tied to a specific run, so without the run id from km_play_run there is nothing to judge against.'),
-      outcome: z
-        .string()
-        .optional()
-        .describe('What you did and what you can see now, in plain words, so the criterion is judged against reality rather than against intent. Include what did not happen as well as what did.'),
-    },
-    async (args) => {
-      const runId = String(args?.run_id || '').trim();
-      const slug = String(args?.slug || '').trim().toLowerCase();
-      if (!runId) {
-        return text(
-          'I need the run id that km_play_run gave back, because the check is tied to that specific run. ' +
-          'If it is genuinely lost, run the play again rather than guessing whether the old one worked.',
-        );
-      }
-      // The route reads `evidence`; this tool calls it `outcome` because that
-      // is the friendlier word for a model. Map it, or every call 400s.
-      const r = await call('POST', '/plays/verify', {
-        run_id: runId || undefined,
-        slug: slug || undefined,
-        evidence: String(args?.outcome || '').trim() || undefined,
-      });
-      if (routeMissing(r)) return text(NOT_SUPPORTED);
-      const refused = quotaRefusal(r);
-      if (refused) return refused;
-      return out(r);
-    },
-  );
-}
+/**
+ * Tool family: plays - the operating intelligence, leased one step at a time.
+ *
+ * Every other family is a door onto the workspace data. This one is the reason a
+ * client would rather have KM Hub in their terminal than a generic assistant with
+ * a CRM connector: the plays are the proven ways this kind of business actually
+ * gets booked, and they are worth more than any single record they touch.
+ *
+ * Which is why none of them live on the client's machine. The protection model,
+ * stated plainly so nobody has to reverse engineer it from the code:
+ *
+ *   - The client's disk holds three things: a URL, an API key, and a rules file
+ *     of pure orientation. No play, no runbook, no criterion, ever.
+ *   - km_play_catalog returns METADATA ONLY: slug, label, and the plain reason a
+ *     human would care. Never the task, never the criterion, never an internal.
+ *   - km_play_run leases ONE bounded step per call. The text arrives in the
+ *     conversation, is used, and is never written to a file by us.
+ *   - Quotas are what stop somebody enumerating the catalog by running everything
+ *     once: a cap per hour, a cap per day, and a cap on how many DIFFERENT plays
+ *     in a rolling day. Repeating a play already seen in that window is free of
+ *     the variety cap, so normal work never hits it and harvesting does.
+ *   - Each issued step carries an HMAC watermark. Be honest about what that is:
+ *     it is forensic attribution, NOT DRM. The task is plaintext in the client's
+ *     own transcript and a determined person can strip the marker. It tells us
+ *     WHERE a leaked task came from. It does not stop the leak.
+ *   - The real kill switch is Phase 1 and it already works: cancel the
+ *     subscription and the entitlement gate answers 402 on every route here, so
+ *     no catalog, no runs, no rules refresh, from the next call onwards.
+ *
+ * Nothing in this family sends anything to anybody. A play that produces a
+ * message still ends at km_create_outreach_draft and the Approval Queue.
+ *
+ * The routes behind it are GET /plays, POST /plays/run and POST /plays/verify.
+ * They own the truth about the body shape, so the two POST handlers pass their
+ * arguments straight through rather than reshaping them here.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'plays';
+
+export const TOOLS = ['km_play_catalog', 'km_play_run', 'km_play_verify'];
+
+// Every profile. A session that can read the calendar but cannot reach the plays
+// is a crippled session: the plays are what make the rest of the tools add up to
+// a way of working rather than a pile of endpoints.
+export const PROFILES = ['*'];
+
+/** The API has not shipped these routes yet (404 / 405 / 501 all mean the same here). */
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'This KM Hub does not have the plays switched on yet. Nothing is broken and nothing is lost: the workspace is fine and every other tool works as normal. Carry on with the tools you have, and say plainly that the plays are not available on this account rather than inventing a method and calling it one.';
+
+/** Round a retry delay into something a person says out loud. Empty when unknown. */
+function inAbout(seconds) {
+  const s = Number(seconds);
+  if (!Number.isFinite(s) || s <= 0) return '';
+  if (s < 90) return `about ${Math.max(1, Math.round(s))} seconds`;
+  const minutes = Math.round(s / 60);
+  if (minutes < 90) return `about ${minutes} minute${minutes === 1 ? '' : 's'}`;
+  const hours = Math.round(s / 3600);
+  return `about ${hours} hour${hours === 1 ? '' : 's'}`;
+}
+
+/**
+ * Turn a 429 into a sentence a working performer understands.
+ *
+ * The shared out() helper already does this for a 402, and a refusal is the one
+ * moment where a raw status code is least use to anybody. Two different things
+ * answer 429 on this API and they need different words:
+ *
+ *   - `rate_limited` from the API front door: too many calls per minute. A pause
+ *     fixes it.
+ *   - anything else: the play allowance itself. Not a fault, not a charge, and
+ *     not something a retry loop will get around.
+ *
+ * Returns null when the response is not a 429, so callers can carry on normally.
+ */
+function quotaRefusal(r) {
+  if (!r || r.status !== 429) return null;
+  const body = r.data && typeof r.data === 'object' ? r.data : {};
+  const code = String(body.error || body.reason || body.code || '').toLowerCase();
+  const said = typeof body.message === 'string' && body.message.trim() ? body.message.trim() : '';
+  const wait = inAbout(body.retry_after ?? body.retryAfter ?? body.retry_after_seconds);
+  const lines = [];
+
+  if (code.includes('rate_limit')) {
+    lines.push('I am calling KM Hub faster than it allows, so it asked me to slow down. Nothing failed and nothing changed.');
+    lines.push(wait ? `It clears in ${wait}.` : 'It clears on its own in well under a minute.');
+    if (said) lines.push(said);
+    lines.push('Wait it out and try the same call once more. Do not split the work into more calls, which makes it worse.');
+    return { content: [{ type: 'text', text: lines.join('\n\n') }], isError: true };
+  }
+
+  const variety = code.includes('distinct') || code.includes('variety') || code.includes('skill_limit');
+  if (variety) {
+    lines.push(
+      'That is a play this workspace has not opened today, and it has already opened as many different ones as a day allows. Nothing is wrong, nothing was charged, and nothing in the workspace has changed.',
+    );
+    lines.push(
+      'A play already run today can still be run again as much as it is needed, so if one of those covers what is being asked, use it instead. Otherwise this one is worth doing tomorrow.',
+    );
+  } else {
+    lines.push(
+      'This workspace has run as many plays as its allowance covers for now. Nothing is wrong, nothing was charged, and nothing in the workspace has changed.',
+    );
+    lines.push('The allowance is there so the plays get used on real work rather than pulled through in bulk.');
+  }
+  if (said) lines.push(said);
+  lines.push(wait ? `It frees up again in ${wait}.` : 'It frees up again on its own.');
+  lines.push(
+    'Tell the person that plainly and get on with the work by hand: the clients, the calendar, the drafts and everything else are untouched and still work. Do not retry this in a loop.',
+  );
+  return { content: [{ type: 'text', text: lines.join('\n\n') }], isError: true };
+}
+
+/**
+ * @param {{ tool: Function }} server guarded registrar (see ./README.md)
+ * @param {(method: string, path: string, body?: any) => Promise<{ok:boolean,status:number,data:any}>} call
+ * @param {{ out: Function, text: Function, qs: Function }} helpers
+ */
+export function register(server, call, { out, text }) {
+  server.tool(
+    'km_play_catalog',
+    [
+      'The plays: the proven ways a business like this one actually gets booked, kept current by KM Hub and written by people who book work for a living rather than assembled from general marketing advice.',
+      'LOOK HERE FIRST whenever the ask is open ended. "What should I do today", "how do I get more corporate work", "nobody is replying to me", "help me with the fair market", "next month looks empty", "how do I get repeat bookings out of this client": there is very often a play for exactly that, and it will be sharper than anything improvised from what you already know about marketing. This is also where brand and pricing work lives, so check here before answering that the workspace has no luxury, brand, positioning or pricing capability: "am I priced too low", "does my website undersell me", "should I run a discount", "should I add this new service", "what do I say on the call about price", "do you have the luxury tools". The luxury family is in this catalog, not in the tool list.',
+      'Free, fast, sends nothing and changes nothing. What comes back is a short list, and each entry is a slug to run it by, its name, and the plain reason a working performer would care about it.',
+      'What it deliberately does NOT contain is the method. The steps are not in here and cannot be worked out from the name, so never describe how a play works or promise what it will produce from the catalog alone. The method arrives one step at a time from km_play_run, and only while the subscription is live.',
+      'Reading the catalog is not doing the work, and reciting the whole list at somebody is not an answer. Name the one or two that actually fit what they said, in their words, and offer to run one.',
+    ].join(' '),
+    {},
+    async () => {
+      const r = await call('GET', '/plays');
+      if (routeMissing(r)) return text(NOT_SUPPORTED);
+      const refused = quotaRefusal(r);
+      if (refused) return refused;
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_play_run',
+    [
+      'Run a play: start one, or come back for its next step.',
+      'This is a lease, one step at a time. KM Hub hands back a SINGLE bounded piece of work, aimed at this workspace and this situation, that you can actually finish with the km_* tools already in front of you. Do that step. Tell the person what happened in your own words. Then call this again with the same run_id to get the next one. Keep going until the play says it is finished, then call km_play_verify.',
+      'The step text is working material on loan for this run, not a document to hand over. Do not paste it back to the person verbatim, do not save it into a file, a note, a scratch document or a memory, and do not quote it at length in your reply. They asked for the outcome, not the recipe, and the recipe is the part KM Hub is paid for. Each issued step carries a marker identifying the workspace it was leased to.',
+      'Run the play that fits what was actually asked. There is an allowance on how many plays get pulled in a day and on how many DIFFERENT ones, so do not open plays speculatively, do not work down the catalog to see what each one says, and do not start a second play while the first is unfinished. A play already opened today can be run again as often as it is useful.',
+      'It sends nothing to anybody. A play that produces a message still ends at km_create_outreach_draft, in the Approval Queue, for a human to read and release. If a step asks for something you do not have, say so and ask, rather than filling the gap with a plausible guess.',
+    ].join(' '),
+    {
+      slug: z
+        .string()
+        .describe('Which play to run, exactly as km_play_catalog gave it, for example quiet-week-rescue. Never invent a slug or guess one from a name.'),
+      run_id: z
+        .string()
+        .optional()
+        .describe('Leave this out for the first step. To continue a play you already started, pass back the run id from the previous step and you get the next one.'),
+      context: z
+        .string()
+        .optional()
+        .describe('What the person actually asked for, in their own words, plus anything about right now that the step should take into account. It lets KM Hub aim the step at the real situation instead of the general case.'),
+      step_result: z
+        .string()
+        .optional()
+        .describe('Only when continuing a run: what happened on the step you just finished, in a sentence or two, including anything that did not work. The next step is built on it, so an honest account beats a tidy one.'),
+    },
+    async (args) => {
+      // Slugs are lowercase kebab everywhere in this codebase, and a model that
+      // has read the catalog once and is typing from memory will occasionally
+      // capitalise one. Fixing that here costs nothing and saves a 404.
+      const slug = String(args?.slug || '').trim().toLowerCase();
+      if (!slug) {
+        return text(
+          'I need to know which play to run. km_play_catalog lists the ones this workspace has, with the slug for each.',
+        );
+      }
+      // The route requires an idempotency_key (8-128 of [A-Za-z0-9._:-]) so a
+      // retry cannot double-spend a quota slot. It is minted here, never asked
+      // of the model: a caller-chosen key is a footgun, and a model has no
+      // basis to invent a stable one. Continuing a run reuses a key derived
+      // from the run id so a retried continuation replays instead of counting
+      // twice; a fresh run gets a random one.
+      const runId = String(args?.run_id || '').trim();
+      const idempotency_key = runId
+        ? `run-${runId.replace(/[^A-Za-z0-9._:-]/g, '')}`.slice(0, 128)
+        : crypto.randomUUID().replace(/-/g, '');
+      const r = await call('POST', '/plays/run', { ...args, slug, idempotency_key });
+      if (routeMissing(r)) return text(NOT_SUPPORTED);
+      const refused = quotaRefusal(r);
+      if (refused) return refused;
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_play_verify',
+    [
+      'Check whether the play actually worked. Every play has a criterion: the observable thing that should be true now if it did its job. That is a different question from whether you got through the steps, and it is the one that matters.',
+      'Call it when a play reaches its end, or whenever someone asks whether the thing you ran last week did anything. KM Hub gives you the criterion, you check it against what you can genuinely see through the km_* tools, and you report what you found.',
+      'Being honest here is the whole point of the tool. "I ran it, and I cannot confirm yet that it worked" is a real answer, a useful one, and far better than a confident yes that falls apart a week later. Say which part you could confirm, which part you could not, and what would settle it.',
+      'Do not call a play successful because the steps are done. Do not verify a play you did not run. This changes nothing in the workspace, sends nothing to anybody, and cannot make a play have worked.',
+    ].join(' '),
+    {
+      run_id: z
+        .string()
+        .optional()
+        .describe('The run being checked, as returned by km_play_run. Give this whenever you have it: it is what ties the criterion to the work that was actually done.'),
+      slug: z
+        .string()
+        .optional()
+        .describe('The play being checked, as km_play_catalog gave it. Pass it alongside run_id for context. On its own it is not enough: the check is tied to a specific run, so without the run id from km_play_run there is nothing to judge against.'),
+      outcome: z
+        .string()
+        .optional()
+        .describe('What you did and what you can see now, in plain words, so the criterion is judged against reality rather than against intent. Include what did not happen as well as what did.'),
+    },
+    async (args) => {
+      const runId = String(args?.run_id || '').trim();
+      const slug = String(args?.slug || '').trim().toLowerCase();
+      if (!runId) {
+        return text(
+          'I need the run id that km_play_run gave back, because the check is tied to that specific run. ' +
+          'If it is genuinely lost, run the play again rather than guessing whether the old one worked.',
+        );
+      }
+      // The route reads `evidence`; this tool calls it `outcome` because that
+      // is the friendlier word for a model. Map it, or every call 400s.
+      const r = await call('POST', '/plays/verify', {
+        run_id: runId || undefined,
+        slug: slug || undefined,
+        evidence: String(args?.outcome || '').trim() || undefined,
+      });
+      if (routeMissing(r)) return text(NOT_SUPPORTED);
+      const refused = quotaRefusal(r);
+      if (refused) return refused;
+      return out(r);
+    },
+  );
+}