@edda-business/mcp 0.69.2 → 0.71.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edda-business/mcp",
-  "version": "0.69.2",
+  "version": "0.71.0",
   "description": "Edda — the company data layer for AI agents.",
   "license": "Apache-2.0",
   "publishConfig": {

package/src/server.js

@@ -137,10 +137,27 @@ export function createServer() {
       if (want === "documents") docs = docs.filter((d) => d.kind === "declared");
       if (want === "distilled") docs = docs.filter((d) => d.kind === "derived");
       docs = docs.slice(0, perLimit);
-      if (!docs.length) {
+      // Claims are what the company currently BELIEVES, as opposed to what a document says. They
+      // lead the answer: a settled current-state fact beats a page that merely mentions the words,
+      // and each carries its standing so a non-binding figure cannot be read as a commitment.
+      const claims = want === "distilled" ? [] : (r?.claims ?? []);
+
+      if (!docs.length && !claims.length) {
         return text(`Nothing matched "${question}"${want !== "all" ? ` in ${want}` : ""} in the company knowledge.`);
       }
       const lines = [`Company knowledge for "${question}"${want !== "all" ? ` (${want})` : ""}:`, ""];
+      if (claims.length) {
+        lines.push("CURRENT STATE — what this company believes right now:");
+        for (const c of claims) {
+          const mark = c.standing && c.standing !== "committed" && c.standing !== "reported" ? ` (${c.standing})` : "";
+          const infer = c.confidence === "inferred" ? " (inferred)" : "";
+          const label = String(c.predicate ?? "").replace(/[_:]/g, " ");
+          lines.push(`[claim] ${c.subject ? `${c.subject} · ` : ""}${label}${mark}${infer}: ${c.object}`);
+          lines.push(`  as of ${String(c.as_of ?? "").slice(0, 10)} · evidence ${c.source?.kind}:${c.source?.id}`);
+        }
+        lines.push("");
+      }
+      if (docs.length) lines.push("DOCUMENTS:", "");
       for (const d of docs) {
         const declared = d.kind === "declared";
         const tag = declared ? "[company]" : "[company·distilled]";
@@ -258,39 +275,192 @@ export function createServer() {
   // ===========================================================================
   server.tool(
     "submit_company_candidate",
-    "SHARE a file up into the COMPANY knowledge — stage one user-approved item into the company " +
-    "Edda's Inbox. You do NOT pick where it lands: the company routes it into the right folder " +
-    "itself (on the next reconcile). You may optionally `suggest` a destination as a hint. Use " +
-    "this to promote a finished note from your own work into the shared company brain. Only stage " +
-    "what the person has approved sharing — this leaves their private vault. (Their private files " +
-    "stay on their disk; this is the shared company layer.) This stages PAGES (content) only — " +
-    "NEVER folders: if the person asks to create a folder, call `create` instead; folder creation " +
-    "is direct and immediate, it does not go through the Inbox.",
+    "SHARE something up into the COMPANY knowledge — stage one user-approved item into the company " +
+    "Edda's Inbox. Takes EITHER markdown you wrote (`content`) OR a real file (`file_base64`): a " +
+    "proposal, invoice, report, financial model or scan. The server extracts the text from PDF, " +
+    "Word, Excel, images, CSV and plain text, so send the file itself rather than your summary of " +
+    "it — a summary loses the numbers. You do NOT pick where it lands: the company routes it into " +
+    "the right folder on the next reconcile, and you may `suggest` a destination as a hint. " +
+    "Optionally attach `claims` for what this CHANGES about what the company believes — an update " +
+    "to existing truth is not a new document. Only stage what the person has approved sharing: " +
+    "this leaves their private vault. This stages PAGES and FILES, never folders — for a folder " +
+    "call `create`, which is direct and does not go through the Inbox.",
     {
-      name: z.string().describe("File/page name, e.g. 'MCP Overview EFB'. A '.md' suffix is added if missing."),
-      content: z.string().describe("The full markdown content of the item to share."),
+      name: z.string().describe("File/page name, e.g. 'MCP Overview EFB' or 'Q3 invoices.xlsx'. A '.md' suffix is added to markdown items if missing."),
+      content: z.string().optional().describe("The full markdown content, when you are sharing text you wrote. Omit when sending a FILE via file_base64."),
+      file_base64: z.string().optional().describe(
+        "A real FILE, base64-encoded — a proposal, invoice, report, financial model, scan. The server extracts the text: " +
+        "PDF (scans are OCR'd), Word, Excel and legacy .xls (one heading per sheet), images (OCR'd), CSV and plain text. " +
+        "A format with no readable text (.zip, .dwg, an installer) is refused with a reason rather than filed as an empty page. " +
+        "Send the file itself rather than pasting your own summary of it: the extracted text is what makes it searchable, " +
+        "and a summary loses the numbers."
+      ),
+      mime: z.string().optional().describe("The file's MIME type when known, e.g. application/pdf. Helps route the extractor; the filename extension is used as a fallback."),
       suggested: z.string().optional().describe("Optional destination HINT, e.g. 'Projects/Data Centre/Working Documents' or 'General Edda'. The company still resolves/creates and places it — this only nudges."),
       grade: z.enum(["fact", "summary", "full"]).optional().describe("How much of the source this carries: a single fact, a summary, or the full document."),
-      audience: z.enum(["company-wide", "department", "owner", "filing-agent-decides"]).optional().describe("The MOST this may be seen by (an upper bound the company may narrow, never broaden). Default: filing-agent-decides."),
+      audience: z.enum(["company-wide", "department", "owner", "filing-agent-decides"]).optional().describe(
+        "The MOST this may be seen by — an upper bound the company may narrow, never broaden. " +
+        "LEAVE THIS UNSET unless the person asked you to restrict it: the default lets the company decide, which is almost always right for something being shared UP into the shared brain. " +
+        "'owner' means nobody but the submitter can ever see it, including the admin reviewing the Inbox — it does not mean 'be careful', it means the contribution is invisible and has to be promoted by hand. " +
+        "Choose it only when the person explicitly said this must stay private to them."
+      ),
       idempotency_key: z.string().optional().describe("Optional stable key so re-submitting the same approved item files it at most once."),
+      claims: z.array(z.object({
+        predicate: z.string().describe("What is being claimed. Tier 1 (bare): status | next_step | owner | risk | blocker | decision. Tier 2 (root:qualifier): sentiment:<topic> | doc_status:<name> | position:<topic> | availability:<topic>."),
+        object: z.string().describe("The value, in plain words, e.g. 'received — Tom is unhappy with the covenant'."),
+        standing: z.enum(["committed", "reported", "indicative", "contested"]).optional().describe("How FIRM the fact is, independent of who said it. committed = signed/agreed/done · reported = a source states it, unverified · indicative = explicitly non-binding, draft, conditional · contested = disputed. Default reported. Get this right: an indicative figure recorded as fact reads as a commitment."),
+        as_of: z.string().optional().describe("When it became TRUE (YYYY-MM-DD), not when you are writing it down. A late note about an old fact must not overwrite newer knowledge."),
+        subject_kind: z.enum(["project", "person", "company", "page"]).optional().describe("Default project — the project this is filed into."),
+        subject_id: z.string().optional().describe("Only when the subject is NOT the destination project."),
+        confidence: z.enum(["stated", "inferred"]).optional().describe("stated = the source says it outright; inferred = you read it between the lines."),
+      })).optional().describe(
+        "What this material CHANGES about what the company believes — the point of sharing an update rather than a document. " +
+        "'The term sheet arrived and Tom is unhappy with it' is not a document, it is two claims. " +
+        "These are PROPOSALS: they appear in the review gate as a belief diff (what we believed → what you are asserting) " +
+        "and are applied only when a person approves the item. Cite nothing yourself — the filed document becomes the evidence."
+      ),
     },
-    async ({ name, content, suggested, grade, audience, idempotency_key }) => {
+    async ({ name, content, file_base64, mime, suggested, grade, audience, idempotency_key, claims }) => {
       try {
-        const r = await post("/v2/company/river/stage", { name, content, suggested, grade, audience, idempotency_key });
+        if (!content && !file_base64) return text(`Give "${name}" either markdown content or a file (file_base64) to stage.`);
+        const r = await post("/v2/company/river/stage", { name, content, file_base64, mime, suggested, grade, audience, idempotency_key, claims });
         const rc = r?.receipt ?? r;
         if (rc?.idempotent) return text(`Already staged — "${name}" is in the company Inbox (${rc.location}). Nothing duplicated.`);
         if (rc?.rejected === "hash_mismatch") return text(`Couldn't stage "${name}": the content didn't match its declared checksum (it may have changed after approval). Re-capture and try again.`);
         if (rc?.staged === false) return text(`Couldn't stage "${name}": ${rc?.reason ?? "unknown error"}.`);
-        return text(`Staged "${name}" into the company Inbox (${rc?.location ?? "Inbox"}). The company will route it to the right folder on the next reconcile.`);
+        const n = Array.isArray(claims) ? claims.length : 0;
+        // Say what is waiting, including the belief change — the person needs to know a claim is
+        // pending a human decision, not quietly applied.
+        return text(
+          `Staged "${name}" into the company Inbox (${rc?.location ?? "Inbox"}). The company will route it to the right folder on the next reconcile.`
+          + (n ? `\n${n} proposed knowledge update${n === 1 ? "" : "s"} rides with it — shown in the review gate as a belief change and applied only on approval.` : ""),
+        );
       } catch (e) {
         const msg = String(e?.message || e);
-        if (msg.includes("admins_only") || msg.includes("(403)")) return text("You don't have a role that can share into this company wiki (members are read-only).");
+        if (msg.includes("read_only") || msg.includes("admins_only") || msg.includes("(403)")) return text("This seat is read-only on the company Edda, so it can search and read but not contribute. Ask an admin for a write role.");
+        if (msg.includes("no_readable_text")) return text("That file has no text to extract \u2014 it is a binary format. The River reads PDF, Word, Excel, images and scans (OCR\u2019d), CSV and plain text. Filing it as a page would create something that looks like knowledge and answers nothing.");
         if (msg.includes("name_required")) return text("Give the item a name and content to stage.");
         throw e;
       }
     },
   );
 
+  // ===========================================================================
+  // TOOL: submit_company_batch  —  POST /v2/company/river/stage-batch
+  // One periodic ingest run = one submission. A seat's ingest sweeps the last few hours of email,
+  // transcripts, notes and attachments, and produces a handful of documents plus the belief
+  // changes they imply. That is one arrival, not fifteen.
+  // ===========================================================================
+  server.tool(
+    "submit_company_batch",
+    "SHARE SEVERAL things up into the COMPANY knowledge in one call — the batch form of " +
+    "submit_company_candidate, for a periodic ingest run rather than a single share. Use this when " +
+    "a sweep produced multiple documents and belief changes at once: the contracts and invoices " +
+    "that arrived, plus what they change about what the company believes. Everything lands in the " +
+    "company Inbox; you never choose the final destination. A per-item failure does not stop the " +
+    "rest — each item gets its own receipt saying what happened. Up to 100 items. " +
+    "IMPORTANT: attach `claims` to the item they came from rather than writing a separate " +
+    "'here is what changed' document — a belief change carried as structured claims is applied by " +
+    "the reviewer's single approval, whereas one buried in prose has to be read and re-derived by " +
+    "whoever files it.",
+    {
+      items: z.array(z.object({
+        name: z.string().describe("File/page name, e.g. 'Cook Street construction proposal.pdf'."),
+        content: z.string().optional().describe("Markdown content, when sharing text you wrote. Omit when sending a file."),
+        file_base64: z.string().optional().describe("The file itself, base64-encoded — PDF, Word, Excel, image, CSV. Send the file rather than a summary of it."),
+        mime: z.string().optional().describe("MIME type when known."),
+        suggested: z.string().optional().describe("Optional destination HINT. A path you cannot see is dropped, and the item still lands in the Inbox."),
+        grade: z.enum(["fact", "summary", "full"]).optional(),
+        audience: z.enum(["company-wide", "department", "owner", "filing-agent-decides"]).optional().describe("Leave unset unless the person asked to restrict this item. 'owner' makes it invisible to everyone including the reviewer."),
+        idempotency_key: z.string().optional().describe("Stable key so a re-run of the same ingest files each item at most once. Strongly recommended for a periodic sweep."),
+        claims: z.array(z.object({
+          predicate: z.string().describe("status | next_step | owner | risk | blocker | decision, or a qualified root: sentiment:<topic> | doc_status:<name> | position:<topic> | availability:<topic>."),
+          object: z.string().describe("The value in plain words."),
+          standing: z.enum(["committed", "reported", "indicative", "contested"]).optional().describe("How firm the fact is. committed = signed/agreed/done · reported = a source states it · indicative = non-binding, draft, conditional · contested = disputed."),
+          as_of: z.string().optional().describe("When it became TRUE (YYYY-MM-DD), not when you wrote it down."),
+          subject_kind: z.enum(["project", "person", "company", "page"]).optional(),
+          subject_id: z.string().optional(),
+          confidence: z.enum(["stated", "inferred"]).optional(),
+        })).optional().describe("What THIS item changes about what the company believes."),
+      })).max(100).describe("The items from one ingest run."),
+    },
+    async ({ items }) => {
+      try {
+        const r = await post("/v2/company/river/stage-batch", { candidates: items });
+        const staged = r?.staged ?? 0;
+        const failed = r?.failed ?? 0;
+        const lines = [`Staged ${staged} item(s) into the company Inbox${failed ? `, ${failed} rejected` : ""}.`];
+        for (const rec of r?.receipts ?? []) {
+          if (rec.staged === false) lines.push(`  ✗ ${rec.name ?? "(unnamed)"} — ${rec.reason ?? rec.rejected ?? "unknown"}`);
+          else if (rec.suggestion_dropped) lines.push(`  • ${rec.name} — staged; your suggested destination was dropped (not visible to you)`);
+        }
+        lines.push("", "They wait for a person to review and file them. Nothing has been placed in a project yet.");
+        return text(lines.join("\n"));
+      } catch (e) {
+        const msg = String(e?.message || e);
+        if (msg.includes("read_only") || msg.includes("(403)")) return text("This seat is read-only on the company Edda, so it cannot contribute.");
+        if (msg.includes("too_many")) return text("Too many items — send at most 100 per call.");
+        throw e;
+      }
+    },
+  );
+
+  // ===========================================================================
+  // TOOL: submit_belief_update  —  POST /v2/company/river/stage-claims
+  // A correction with no document. The last piece of "updates to existing truth, not necessarily
+  // specific documents": until this existed, an agent holding a pure correction had to invent a
+  // document to carry it.
+  // ===========================================================================
+  server.tool(
+    "submit_belief_update",
+    "CORRECT what the company believes about a project, when NO new document arrived. Use this " +
+    "when something already filed is now out of date: the term sheet you filed last week has been " +
+    "rejected, the deadline moved, the owner changed. It creates NO page — approving it updates " +
+    "the project's current state and nothing else. " +
+    "Use submit_company_candidate instead whenever actual material arrived (a file, a note, a " +
+    "transcript); the claims ride along with it and one approval applies both. " +
+    "NEVER write a document whose only purpose is to describe a change — that is what this tool " +
+    "replaces. " +
+    "`source_refs` is required and must point at evidence ALREADY filed and live in the company " +
+    "brain: a correction has to point at something. If you have nothing to point at, what you are " +
+    "holding is new material — submit it as a document. Like every contribution this waits in the " +
+    "company Inbox for a person to approve.",
+    {
+      folder_id: z.string().describe("The project whose current state changes. Get it from `orientation` or `search`."),
+      claims: z.array(z.object({
+        predicate: z.string().describe("status | next_step | owner | risk | blocker | decision, or a qualified root: sentiment:<topic> | doc_status:<name> | position:<topic> | availability:<topic>."),
+        object: z.string().describe("What is true now, in plain words."),
+        standing: z.enum(["committed", "reported", "indicative", "contested"]).optional().describe("committed = signed/agreed/done · reported = a source states it · indicative = non-binding, draft, conditional · contested = disputed. A weaker claim never retires a firmer one."),
+        as_of: z.string().optional().describe("When it became TRUE (YYYY-MM-DD), not when you learned it."),
+        confidence: z.enum(["stated", "inferred"]).optional(),
+      })).max(25).describe("The beliefs that changed. One per fact — do not pack two facts into one sentence."),
+      source_refs: z.array(z.object({
+        kind: z.enum(["company_file", "river_original", "river_receipt"]),
+        id: z.string(),
+      })).describe("Evidence already live in the brain that this correction rests on."),
+      note: z.string().optional().describe("One line of context for the reviewer, if the claims alone would not explain themselves."),
+      idempotency_key: z.string().optional().describe("Stable key so a re-run of the same ingest proposes this at most once."),
+    },
+    async ({ folder_id, claims, source_refs, note, idempotency_key }) => {
+      try {
+        const r = await post("/v2/company/river/stage-claims", { folder_id, claims, source_refs, note, idempotency_key });
+        const lines = claims.map((c) => `  · ${String(c.predicate).replace(/[_:]/g, " ")}: ${c.object}${c.standing ? ` (${c.standing})` : ""}`);
+        return text(
+          `Belief update waiting in the company Inbox${r?.idempotent ? " (already submitted earlier — not duplicated)" : ""}:\n`
+          + lines.join("\n")
+          + "\n\nA person reviews it. Approving updates the project's current state; no document is created."
+        );
+      } catch (e) {
+        const msg = String(e?.message || e);
+        if (msg.includes("source_refs_required")) return text("A correction has to cite evidence already filed in the brain. If you have none, submit the material as a document with submit_company_candidate instead.");
+        if (msg.includes("bad_source_refs")) return text(`That evidence could not be verified: ${msg}. Cite only documents that are already filed and live.`);
+        if (msg.includes("folder_not_visible")) return text("You do not have access to that project, so you cannot change what the company believes about it.");
+        if (msg.includes("read_only") || msg.includes("(403)")) return text("This seat is read-only on the company Edda, so it cannot contribute.");
+        throw e;
+      }
+    },
+  );
+
   // ===========================================================================
   // TOOL: inbox  —  GET /v2/company/inbox
   // The waiting room the agent-run ingest reads (Decision Log 2026-09-04: the agent is
@@ -298,24 +468,60 @@ export function createServer() {
   // ===========================================================================
   server.tool(
     "inbox",
-    "LIST what is waiting in the company Inbox — each staged item with its id, submitter, the " +
-    "submitter's suggested destination (if any), and a content preview. This is the start of the " +
-    "company ingest: read each item (use `read` for the full text if the preview is not enough), " +
-    "decide where it belongs among the real projects, then file it with " +
-    "reconcile { stagingId, path }. Admin/ambassador only.",
-    {},
-    async () => {
+    "LIST what is waiting in the company Inbox, AND what was decided about the things you sent. " +
+    "Each waiting item comes with its id, submitter, suggested destination and a content preview. " +
+    "This is the start of the company ingest: read each item (use `read` for the full text if the " +
+    "preview is not enough), decide where it belongs among the real projects, then file it with " +
+    "reconcile { stagingId, path }. An ADMIN sees everything waiting; a MEMBER sees only their own " +
+    "submissions. Pass `since` (ISO timestamp) to see only decisions made after your last run — " +
+    "that is the cursor a periodic ingest should keep, so it can tell its user what was filed and " +
+    "what was rejected, and stop re-sending things that were turned down.",
+    {
+      since: z.string().optional().describe("ISO timestamp of your last ingest run. Decisions after it are reported back; omit for the last 7 days."),
+    },
+    async ({ since }) => {
       try {
+        // Two questions in one call, because a periodic ingest asks both every time: what still
+        // needs filing, and what happened to what I already sent. The second half is the only
+        // signal a submitting agent ever gets — without it, it re-sends rejected items forever.
+        const cursor = since || new Date(Date.now() - 7 * 24 * 3600 * 1000).toISOString();
+        const decided = await get(`/v2/company/river/receipts?limit=50&since=${encodeURIComponent(cursor)}`)
+          .then((d) => d?.receipts ?? [])
+          .catch(() => []);
+        const outcomes = decided.length
+          ? "\n\n" + `Decided since ${cursor.slice(0, 16).replace("T", " ")}:\n`
+            + decided.map((d) => {
+                const head = d.status === "rejected" ? `✗ ${d.name} — rejected` : `✓ ${d.name} → ${d.location}`;
+                const why = d.detail ? ` — ${d.detail}` : (d.status === "rejected" ? " (no reason given)" : "");
+                const cl = d.claims_asserted ? ` · updated ${d.claims_asserted} belief(s)` : "";
+                return `  ${head}${why}${cl}`;
+              }).join("\n")
+          : "";
+
         const r = await get("/v2/company/inbox");
         const pending = r?.pending ?? [];
-        if (!pending.length) return text("The company Inbox is empty — nothing waiting.");
-        const lines = pending.map((f) =>
-          `• ${f.name}  (stagingId: ${f.id})\n  staged ${String(f.created_at).slice(0, 10)}` +
-          `${f.suggested ? ` · suggested: ${f.suggested}` : ""}\n  ${String(f.preview || "").replace(/\s+/g, " ").slice(0, 240)}`);
-        return text(`${pending.length} item(s) waiting in the company Inbox:\n\n${lines.join("\n\n")}`);
+        if (!pending.length) return text(`The company Inbox is empty — nothing waiting.${outcomes}`);
+        const lines = pending.map((f) => {
+          // The belief diff, beside the destination. An admin running the ingest is deciding on
+          // BOTH — where the document goes and what it changes about what the company believes —
+          // and the second one is invisible unless it is written down here.
+          const changes = (f.changes ?? []).map((c) => {
+            if (c.invalid) return `    ! ${c.predicate}: ${c.invalid}`;
+            const mark = c.standing && c.standing !== "committed" && c.standing !== "reported" ? ` (${c.standing})` : "";
+            const label = String(c.predicate).replace(/[_:]/g, " ");
+            return c.from
+              ? `    ${label}${mark}: ${c.from}  →  ${c.to}`
+              : `    ${label}${mark}: (new) ${c.to}`;
+          });
+          return `• ${f.name}  (stagingId: ${f.id})\n  staged ${String(f.created_at).slice(0, 10)}`
+            + `${f.suggested ? ` · suggested: ${f.suggested}` : ""}`
+            + `\n  ${String(f.preview || "").replace(/\s+/g, " ").slice(0, 240)}`
+            + (changes.length ? `\n  changes what we believe:\n${changes.join("\n")}` : "");
+        });
+        return text(`${pending.length} item(s) waiting in the company Inbox:\n\n${lines.join("\n\n")}${outcomes}`);
       } catch (e) {
         const msg = String(e?.message || e);
-        if (msg.includes("admins_only") || msg.includes("(403)")) return text("Only an admin or ambassador can read the company Inbox.");
+        if (msg.includes("read_only") || msg.includes("(403)")) return text("This seat is read-only on the company Edda, so it has nothing waiting in the Inbox to show.");
         throw e;
       }
     },