@kivimedia/kmhub 2.9.1 → 2.11.0

package/tools/fact-review.mjs

@@ -1,125 +1,125 @@
-/**
- * Tool family: fact-review - the owner confirms or rejects business facts from the terminal.
- *
- *   km_list_pending_business_facts -> GET  /knowledge/facts/pending
- *   km_confirm_business_facts      -> POST /knowledge/facts/confirm  (confirmed write)
- *   km_reject_business_facts       -> POST /knowledge/facts/reject   (confirmed write)
- *
- * WHY THIS EXISTS. km_propose_business_fact could only put a fact in the queue, so
- * a conversation where the owner said "confirmed, these three are correct" still
- * ended with "go and click confirm in the web app" (Brant Matthews, 23-Sep-26).
- * Ziv: "you need to be able to confirm for me". The read and propose tools stay in
- * knowledge.mjs, untouched in shape; this is the review half in its own family.
- *
- * 🚨 Both writes are confirmed writes. KM Hub answers 409 with a server-written
- * list of the exact facts; put that to the person, wait for a real yes, then call
- * again with the confirm_token and the SAME fact_ids. Reject is gated too because
- * a rejection cannot be undone.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'fact-review';
-
-export const TOOLS = ['km_list_pending_business_facts', 'km_confirm_business_facts', 'km_reject_business_facts'];
-
-// Same profiles as the knowledge family that proposes and reads these facts.
-export const PROFILES = ['outreach', 'content', 'money'];
-
-function routeMissing(r) {
-  return r.status === 404 || r.status === 405 || r.status === 501;
-}
-
-const NOT_SUPPORTED =
-  'Your KM Hub cannot review business facts from the terminal yet. Nothing is wrong with the workspace and nothing ' +
-  'was changed. The owner can confirm or reject them in the web app at https://hub.kivimedia.co under Settings, ' +
-  'Connect, Business Knowledge.';
-
-const FACT_IDS = z
-  .array(z.string())
-  .min(1)
-  .max(25)
-  .describe('The ids of the facts, from km_list_pending_business_facts. Up to 25 at once.');
-
-const CONFIRM_TOKEN = z
-  .string()
-  .optional()
-  .describe(
-    'Leave this out on the first call. KM Hub answers 409 with the list to put to the person and a token. Only ' +
-      'after they actually say yes, call again with the token and the SAME fact_ids and reason. A yes for one ' +
-      'list never authorises a different one.',
-  );
-
-const REASON = z
-  .string()
-  .optional()
-  .describe('Optional, one line, in the owner\'s words, for example "Brant confirmed on the call". Kept with the decision.');
-
-/** A 404 from a route that does not exist yet, as opposed to a fact that does not exist. */
-function unsupported(r) {
-  if (!routeMissing(r)) return false;
-  const err = r.data && typeof r.data === 'object' ? r.data.error : undefined;
-  return err !== 'not_found' || /Unknown route/i.test(String(r.data?.message || ''));
-}
-
-export function register(server, call, { out, text }) {
-  server.tool(
-    'km_list_pending_business_facts',
-    'The business facts that are waiting for the owner to say yes or no: things somebody proposed with ' +
-      'km_propose_business_fact, or that KM Hub picked up from an uploaded document or the owner\'s emails. Each one ' +
-      'comes with its id, its exact text and where it came from. Call it when km_get_business_facts reports ' +
-      'pending_proposals above zero, when the person asks what is waiting for them, or before confirming anything, so ' +
-      'you have the ids. NONE of these is confirmed: never use one in a draft, a quote or an answer. Read each to the ' +
-      'owner in its exact words and let them decide. Read only.',
-    {},
-    async () => {
-      const r = await call('GET', '/knowledge/facts/pending');
-      if (unsupported(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_confirm_business_facts',
-    'Confirm business facts the owner says are TRUE, the same as the confirm button in KM Hub under Business ' +
-      'Knowledge. Once confirmed, every draft, quote, play and scout relies on the fact, so a wrong one ends up in ' +
-      'real messages to real clients. Use it when the person has read the facts and says they are right. Several ' +
-      'can go in one call, so the person answers once for the whole list. It is recorded as confirmed by the person ' +
-      'this connector belongs to, who has to be an owner or admin of the workspace. ' +
-      'Get the ids from km_list_pending_business_facts, and pass only the ones they actually said yes to. ' +
-      '🚨 A confirmed write. The first call, without confirm_token, returns 409 with `what_would_happen`: the list ' +
-      'of exact facts, written by KM Hub. Show it in those words, wait for a real yes, then call again with the ' +
-      'confirm_token and the SAME fact_ids. Once confirmed, a fact cannot be changed or withdrawn from the terminal, ' +
-      'and confirming a corrected wording later does NOT retire the old one (both would be in use), so confirm only ' +
-      'what the owner has read and said is right.',
-    { fact_ids: FACT_IDS, reason: REASON, confirm_token: CONFIRM_TOKEN },
-    review('/knowledge/facts/confirm'),
-  );
-
-  server.tool(
-    'km_reject_business_facts',
-    'Reject business facts the owner says are WRONG, the same as the reject button in KM Hub under Business ' +
-      'Knowledge, so nothing ever uses them. Only on the owner\'s word about these specific facts, never on your own ' +
-      'judgement that one looks doubtful: if you think one is wrong, say so and let them decide. A rejected fact ' +
-      'cannot be reopened, and the same wording cannot be proposed again; if the owner wants a corrected version, ' +
-      'propose the corrected wording with km_propose_business_fact. ' +
-      '🚨 A confirmed write, because it cannot be undone: the first call returns 409 with the exact facts; show them, ' +
-      'wait for a real yes, then call again with the confirm_token and the SAME fact_ids. Afterwards, say plainly ' +
-      'which facts were rejected.',
-    { fact_ids: FACT_IDS, reason: REASON, confirm_token: CONFIRM_TOKEN },
-    review('/knowledge/facts/reject'),
-  );
-
-  /** Same body on the ask and on the answer, so the confirm token's fingerprint matches. */
-  function review(path) {
-    return async ({ fact_ids, reason, confirm_token }) => {
-      const body = { fact_ids };
-      if (reason !== undefined) body.reason = reason;
-      if (confirm_token) body.confirm_token = String(confirm_token);
-      const r = await call('POST', path, body);
-      if (unsupported(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    };
-  }
-}
+/**
+ * Tool family: fact-review - the owner confirms or rejects business facts from the terminal.
+ *
+ *   km_list_pending_business_facts -> GET  /knowledge/facts/pending
+ *   km_confirm_business_facts      -> POST /knowledge/facts/confirm  (confirmed write)
+ *   km_reject_business_facts       -> POST /knowledge/facts/reject   (confirmed write)
+ *
+ * WHY THIS EXISTS. km_propose_business_fact could only put a fact in the queue, so
+ * a conversation where the owner said "confirmed, these three are correct" still
+ * ended with "go and click confirm in the web app" (Brant Matthews, 23-Sep-26).
+ * Ziv: "you need to be able to confirm for me". The read and propose tools stay in
+ * knowledge.mjs, untouched in shape; this is the review half in its own family.
+ *
+ * 🚨 Both writes are confirmed writes. KM Hub answers 409 with a server-written
+ * list of the exact facts; put that to the person, wait for a real yes, then call
+ * again with the confirm_token and the SAME fact_ids. Reject is gated too because
+ * a rejection cannot be undone.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'fact-review';
+
+export const TOOLS = ['km_list_pending_business_facts', 'km_confirm_business_facts', 'km_reject_business_facts'];
+
+// Same profiles as the knowledge family that proposes and reads these facts.
+export const PROFILES = ['outreach', 'content', 'money'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'Your KM Hub cannot review business facts from the terminal yet. Nothing is wrong with the workspace and nothing ' +
+  'was changed. The owner can confirm or reject them in the web app at https://hub.kivimedia.co under Settings, ' +
+  'Account, Business Knowledge.';
+
+const FACT_IDS = z
+  .array(z.string())
+  .min(1)
+  .max(25)
+  .describe('The ids of the facts, from km_list_pending_business_facts. Up to 25 at once.');
+
+const CONFIRM_TOKEN = z
+  .string()
+  .optional()
+  .describe(
+    'Leave this out on the first call. KM Hub answers 409 with the list to put to the person and a token. Only ' +
+      'after they actually say yes, call again with the token and the SAME fact_ids and reason. A yes for one ' +
+      'list never authorises a different one.',
+  );
+
+const REASON = z
+  .string()
+  .optional()
+  .describe('Optional, one line, in the owner\'s words, for example "Brant confirmed on the call". Kept with the decision.');
+
+/** A 404 from a route that does not exist yet, as opposed to a fact that does not exist. */
+function unsupported(r) {
+  if (!routeMissing(r)) return false;
+  const err = r.data && typeof r.data === 'object' ? r.data.error : undefined;
+  return err !== 'not_found' || /Unknown route/i.test(String(r.data?.message || ''));
+}
+
+export function register(server, call, { out, text }) {
+  server.tool(
+    'km_list_pending_business_facts',
+    'The business facts that are waiting for the owner to say yes or no: things somebody proposed with ' +
+      'km_propose_business_fact, or that KM Hub picked up from an uploaded document or the owner\'s emails. Each one ' +
+      'comes with its id, its exact text and where it came from. Call it when km_get_business_facts reports ' +
+      'pending_proposals above zero, when the person asks what is waiting for them, or before confirming anything, so ' +
+      'you have the ids. NONE of these is confirmed: never use one in a draft, a quote or an answer. Read each to the ' +
+      'owner in its exact words and let them decide. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/knowledge/facts/pending');
+      if (unsupported(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_confirm_business_facts',
+    'Confirm business facts the owner says are TRUE, the same as the confirm button in KM Hub under Business ' +
+      'Knowledge. Once confirmed, every draft, quote, play and scout relies on the fact, so a wrong one ends up in ' +
+      'real messages to real clients. Use it when the person has read the facts and says they are right. Several ' +
+      'can go in one call, so the person answers once for the whole list. It is recorded as confirmed by the person ' +
+      'this connector belongs to, who has to be an owner or admin of the workspace. ' +
+      'Get the ids from km_list_pending_business_facts, and pass only the ones they actually said yes to. ' +
+      '🚨 A confirmed write. The first call, without confirm_token, returns 409 with `what_would_happen`: the list ' +
+      'of exact facts, written by KM Hub. Show it in those words, wait for a real yes, then call again with the ' +
+      'confirm_token and the SAME fact_ids. Once confirmed, a fact cannot be changed or withdrawn from the terminal, ' +
+      'and confirming a corrected wording later does NOT retire the old one (both would be in use), so confirm only ' +
+      'what the owner has read and said is right.',
+    { fact_ids: FACT_IDS, reason: REASON, confirm_token: CONFIRM_TOKEN },
+    review('/knowledge/facts/confirm'),
+  );
+
+  server.tool(
+    'km_reject_business_facts',
+    'Reject business facts the owner says are WRONG, the same as the reject button in KM Hub under Business ' +
+      'Knowledge, so nothing ever uses them. Only on the owner\'s word about these specific facts, never on your own ' +
+      'judgement that one looks doubtful: if you think one is wrong, say so and let them decide. A rejected fact ' +
+      'cannot be reopened, and the same wording cannot be proposed again; if the owner wants a corrected version, ' +
+      'propose the corrected wording with km_propose_business_fact. ' +
+      '🚨 A confirmed write, because it cannot be undone: the first call returns 409 with the exact facts; show them, ' +
+      'wait for a real yes, then call again with the confirm_token and the SAME fact_ids. Afterwards, say plainly ' +
+      'which facts were rejected.',
+    { fact_ids: FACT_IDS, reason: REASON, confirm_token: CONFIRM_TOKEN },
+    review('/knowledge/facts/reject'),
+  );
+
+  /** Same body on the ask and on the answer, so the confirm token's fingerprint matches. */
+  function review(path) {
+    return async ({ fact_ids, reason, confirm_token }) => {
+      const body = { fact_ids };
+      if (reason !== undefined) body.reason = reason;
+      if (confirm_token) body.confirm_token = String(confirm_token);
+      const r = await call('POST', path, body);
+      if (unsupported(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    };
+  }
+}