@miadi/connector 0.1.11 → 0.1.12

package/README.md

@@ -27,6 +27,7 @@ Call `get_capabilities` first. It names the signed-in person, their Miadi API ti
 
 - **Reads** need Miadi's read tier and stay within it. A person Miadi gives no API tier reaches only `get_capabilities`. Sessions need the write tier, because a session's name and pane are operator data. For the same reason, below the write tier a record someone else made shows no session, working folder or seat, and no long bodies.
 - **Episode files.** `get_evidence` lists an episode's files; each text file Miadi can preview carries a `read_ref` (`miadi-chronicle://<n>/<path>`). `read_episode_file` (or `fetch` with that ref) returns the file's whole UTF-8 text, read as the person through Miadi's file door, so Miadi's audience and room rules apply. The answer names the episode, the path, the content type, the byte count and the sha256, and `verified` says whether the text received hashes to what Miadi read. Only md, txt, yaml, yml and json files up to 512 KiB are read. A traversal, absolute, hidden or encoded path is refused before any URL is built. A longer text comes in pages cut on character boundaries: pass `page.next` back, and the joined pages hash to `sha256`. Other kinds answer `unsupported`, a file over the limit `too_large`, a missing one `not_found`, a ceremony note below the write gate `forbidden`.
+- **One narrow grant.** A person with no Miadi API tier who holds `chronicle_foundations_read` (ticked by an admin under /admin → People → Additional permissions; admins hold it through their role) reaches `read_episode_file` for foundation documents only: `foundations/<topic>/*.md`, read through Miadi's `GET /api/chronicle/episodes/<ref>/foundations/<topic>/<file>.md`, which checks the permission on every read. Naming the episode alone lists them. Every other file and every other tool stays refused, and the permission gives no API tier. Unticking it refuses the next read. `get_capabilities` reports it under `foundation_read`, from Miadi's answer at that moment.
 - **Contributions** need Miadi's read tier and the `miadi:contribute` scope, chosen at sign-in. A record is moved on (`update_handoff`) only by its author or the write tier, and a request's receipt comes only from its decision. They append a record to the ledger and change nothing else, except `save_research`: it saves a report on the inquiry shelf as a new folder (the Markdown exactly as given, owner and visibility recorded, private by default), opens the folder's inquiry issue, and commits and pushes the folder in the shelf's repository. A long report is sent in parts (`part`, `parts`, `upload_id`) and saved when the last part arrives; the answer returns its bytes, sha256 and first and last lines.
 - **Requests** append a record that waits for a decision. The answer gives an `approval_url`; Miadi's `/research` page offers the same decisions to a signed-in person with the write tier, and `show_decisions` shows them as cards inside the conversation (below). The person approves, approves with changes (their instructions are carried into what runs), sends it back for revision with instructions (`revision_requested`, nothing runs, `get_run_result` returns the instructions), or declines. Only the approval door runs a request, once, as that person; a second decision on the same request, at the same time or later, is refused:
   - a run becomes a brief in the factory queue, which the intake delivers to a session;

package/dist/episode-files.d.ts

@@ -1,5 +1,14 @@
 /** The extensions Miadi's vessel reads as text (@medicine-wheel/episode-vessel TEXT_EXTENSIONS). */
 export declare const TEXT_TYPES: Record<string, string>;
+/**
+ * The one Miadi permission that reads foundation documents without an API
+ * tier (jgwill/Miadi#905). Miadi checks it on every read at
+ * GET /api/chronicle/episodes/<ref>/foundations/<topic>/<file>.md.
+ */
+export declare const FOUNDATIONS_PERMISSION = "chronicle_foundations_read";
+/** `foundations/<topic>/…/<file>.md`: what that permission reads, and nothing else. */
+export declare function isFoundationDoc(segments: string[]): boolean;
+export declare function holdsFoundationRead(permissions: readonly string[] | undefined): boolean;
 /** The vessel's own limit for reading text whole (MAX_TEXT_BYTES). */
 export declare const MAX_TEXT_BYTES: number;
 export declare const DEFAULT_PAGE_BYTES = 100000;

package/dist/episode-files.js

@@ -21,6 +21,19 @@ export const TEXT_TYPES = {
     ".yml": "application/yaml; charset=utf-8",
     ".json": "application/json; charset=utf-8",
 };
+/**
+ * The one Miadi permission that reads foundation documents without an API
+ * tier (jgwill/Miadi#905). Miadi checks it on every read at
+ * GET /api/chronicle/episodes/<ref>/foundations/<topic>/<file>.md.
+ */
+export const FOUNDATIONS_PERMISSION = "chronicle_foundations_read";
+/** `foundations/<topic>/…/<file>.md`: what that permission reads, and nothing else. */
+export function isFoundationDoc(segments) {
+    return segments.length >= 3 && segments[0] === "foundations" && extensionOf(segments.join("/")) === ".md";
+}
+export function holdsFoundationRead(permissions) {
+    return Boolean(permissions?.includes("*") || permissions?.includes(FOUNDATIONS_PERMISSION));
+}
 /** The vessel's own limit for reading text whole (MAX_TEXT_BYTES). */
 export const MAX_TEXT_BYTES = 512 * 1024;
 export const DEFAULT_PAGE_BYTES = 100_000;

package/dist/tools.js

@@ -24,7 +24,7 @@ import { checkGrant, isBusy, steerAttempts, steeringGrantOf, steerSession } from
 import { join } from "node:path";
 import { artefactVisibility, readArtefactWeave, saveResearchArtefact } from "@miadi/inquiry-weave";
 import { ResearchUploads, UploadRefusal } from "./uploads.js";
-import { DEFAULT_PAGE_BYTES, FileRefusal, MAX_TEXT_BYTES, MIN_PAGE_BYTES, TEXT_TYPES, checkRelativePath, episodeNumberOf, extensionOf, fileRef, pageOf, parseFileRef, } from "./episode-files.js";
+import { DEFAULT_PAGE_BYTES, FOUNDATIONS_PERMISSION, FileRefusal, MAX_TEXT_BYTES, MIN_PAGE_BYTES, TEXT_TYPES, checkRelativePath, episodeNumberOf, extensionOf, fileRef, holdsFoundationRead, isFoundationDoc, pageOf, parseFileRef, } from "./episode-files.js";
 class ToolRefusal extends Error {
     code;
     detail;
@@ -161,7 +161,14 @@ export function registerTools(server, ctx) {
         annotations: READ,
     }, wrap(async (_args, extra) => {
         const { person, auth } = who(extra, "none");
-        const miadiUp = await miadi.get(person.token, "/api/identity/me").then(() => "reachable", (e) => (e instanceof MiadiError && e.status === 0 ? "unavailable" : "reachable"));
+        let fresh;
+        const miadiUp = await miadi.get(person.token, "/api/identity/me").then((me) => {
+            if (Array.isArray(me?.permissions))
+                fresh = me.permissions.map(String);
+            return "reachable";
+        }, (e) => (e instanceof MiadiError && e.status === 0 ? "unavailable" : "reachable"));
+        // Miadi's answer now, not the sign-in's last one (cached up to five minutes).
+        const foundations = holdsFoundationRead(fresh ?? person.permissions);
         return {
             service: "@miadi/connector",
             version: VERSION,
@@ -175,6 +182,15 @@ export function registerTools(server, ctx) {
                 ledger: "connector ledger (append-only, /srv/miadi/connector)",
             },
             tools: TOOL_STATUS,
+            foundation_read: {
+                permission: FOUNDATIONS_PERMISSION,
+                held: foundations,
+                reads: foundations
+                    ? "read_episode_file reads foundations/<topic>/*.md in episodes you can see; Miadi checks the permission on every read."
+                    : person.api_tier
+                        ? "Not held. read_episode_file reads an episode's text files through your Miadi read tier."
+                        : "Not held: nothing to read. An admin gives it under /admin → People → Additional permissions.",
+            },
             domains: DOMAINS,
             circles: CIRCLES.map((c) => ({ id: c.id, glyph: c.glyph, name: c.name })),
             not_built: [
@@ -341,6 +357,26 @@ export function registerTools(server, ctx) {
      * door; Miadi applies their audience, the room rule and the vessel's path
      * guard, and the path is checked here before a URL is built (jgwill/Miadi#815).
      */
+    /** A number, epNNN or a folder name; `..` would be folded by the URL parser into another route. */
+    const checkedEpisodeRef = (episode) => {
+        const ref = episodeRef(episode);
+        if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(decodeURIComponent(ref))) {
+            throw new FileRefusal("invalid_path", "Name the episode as miadi-chronicle://<n>, its number or its folder.");
+        }
+        return ref;
+    };
+    /** An episode's foundation documents, by path and size: what read_episode_file reads with the permission alone. */
+    const foundationListing = async (person, episode) => {
+        const listing = await miadi.get(person.token, `/api/chronicle/episodes/${checkedEpisodeRef(episode)}/files`);
+        const folder = listing?.episode?.path;
+        const number = listing?.episode?.number ?? (folder ? episodeNumberOf(folder) : null);
+        const docs = (Array.isArray(listing?.files) ? listing.files : []).filter((f) => f?.previewable && isFoundationDoc(String(f.relativePath).split("/")));
+        return {
+            episode: { ref: number === null ? `chronicle:${folder}` : `miadi-chronicle://${number}`, number, folder },
+            foundations: docs.map((f) => ({ path: f.relativePath, bytes: f.size, modified_at: f.modifiedAt, read_ref: fileRef(number ?? folder, f.relativePath) })),
+            count: docs.length,
+        };
+    };
     const readEpisodeFile = async (person, a) => {
         const path = a.path.trim();
         const segments = checkRelativePath(path);
@@ -349,12 +385,18 @@ export function registerTools(server, ctx) {
         if (!contentType) {
             throw new FileRefusal("unsupported", `${path} is not read as text here: only ${Object.keys(TEXT_TYPES).join(", ")} files are. Miadi serves documents (html, pdf, csv, svg) as downloads and images and media by their own routes; get_evidence lists them.`);
         }
-        const ref = episodeRef(a.episode);
-        // A number, epNNN or a folder name; `..` would be folded by the URL parser into another route.
-        if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(decodeURIComponent(ref))) {
-            throw new FileRefusal("invalid_path", "Name the episode as miadi-chronicle://<n>, its number or its folder.");
+        const ref = checkedEpisodeRef(a.episode);
+        // Without a tier, a foundation document is all this tool reads, through
+        // Miadi's foundation door, which decides on every call whether the person
+        // holds the permission: a grant or a revocation counts from the next call,
+        // whatever the sign-in cached. A tier holder reads the room as before.
+        const foundation = person.api_tier === null && isFoundationDoc(segments);
+        if (!foundation && person.api_tier === null) {
+            throw new ToolRefusal("forbidden", `Without Miadi's read tier, this tool reads only foundation documents (foundations/<topic>/<file>.md), with the ${FOUNDATIONS_PERMISSION} permission.`);
         }
-        const url = `/api/chronicle/episodes/${ref}/files/${segments.map(encodeURIComponent).join("/")}`;
+        const url = foundation
+            ? `/api/chronicle/episodes/${ref}/foundations/${segments.slice(1).map(encodeURIComponent).join("/")}`
+            : `/api/chronicle/episodes/${ref}/files/${segments.map(encodeURIComponent).join("/")}`;
         let text;
         try {
             text = await miadi.get(person.token, url);
@@ -368,7 +410,12 @@ export function registerTools(server, ctx) {
                 throw new ToolRefusal("unavailable", "Miadi could not be reached.", detail);
             if (body.error === "not_in_the_room")
                 throw new ToolRefusal("forbidden", body.message ?? "This file is not part of the episode room.", detail);
-            if (error.status === 401 || error.status === 403)
+            if (error.status === 401)
+                throw new ToolRefusal("unauthenticated", "Miadi does not recognise this sign-in's token.", detail);
+            if (error.status === 403 && foundation) {
+                throw new ToolRefusal("forbidden", `Reading foundation documents needs the ${FOUNDATIONS_PERMISSION} permission; an admin gives it under /admin → People → Additional permissions.`, detail);
+            }
+            if (error.status === 403)
                 throw new ToolRefusal("forbidden", body.message ?? "Miadi does not let this person read that file.", detail);
             if (error.status === 404)
                 throw new ToolRefusal("not_found", body.message ?? `No file ${path} in ${decodeURIComponent(ref)}.`, detail);
@@ -408,7 +455,7 @@ export function registerTools(server, ctx) {
     };
     server.registerTool("read_episode_file", {
         title: "Read one file an episode holds",
-        description: "The full UTF-8 text of one text file (md, txt, yaml, yml, json) in a Chronicle episode, read as you through Miadi, with its content type, byte count and sha256. Name the episode and the path get_evidence lists (or pass its read_ref as episode alone). A file longer than max_bytes comes in pages: pass page.next back to read the next one; joined, the pages hash to sha256. Read only: nothing is changed.",
+        description: "The full UTF-8 text of one text file (md, txt, yaml, yml, json) in a Chronicle episode, read as you through Miadi, with its content type, byte count and sha256. Name the episode and the path get_evidence lists (or pass its read_ref as episode alone); name the episode alone to list its foundation documents. With Miadi's read tier it reads the episode's text files; with the chronicle_foundations_read permission alone, foundations/<topic>/*.md only. A file longer than max_bytes comes in pages: pass page.next back to read the next one; joined, the pages hash to sha256. Read only: nothing is changed.",
         inputSchema: {
             episode: z.string().min(1).describe("miadi-chronicle://<n>, an episode number or its folder; or a read_ref (miadi-chronicle://<n>/<path>) with path left out."),
             path: z.string().optional().describe("The file's path inside the episode, as get_evidence lists it, e.g. foundations/broker-adapters/README.md."),
@@ -418,13 +465,22 @@ export function registerTools(server, ctx) {
         },
         annotations: READ,
     }, wrap(async (a, extra) => {
-        const { person } = who(extra);
+        // No API tier needed: the permission alone admits foundation documents (jgwill/Miadi#905).
+        const { person } = who(extra, "none");
         let episode = a.episode;
         let path = a.path;
         if (!path) {
             const parsed = parseFileRef(a.episode);
-            if (!parsed)
-                throw new FileRefusal("invalid_path", "Name the file: give path, or pass a read_ref (miadi-chronicle://<n>/<path>) as episode.");
+            if (!parsed) {
+                // Miadi's answer now: the sign-in's copy may be five minutes old, and a
+                // person just given the permission would be refused the listing.
+                const now = person.api_tier === null ? await miadi.get(person.token, "/api/identity/me").catch(() => null) : null;
+                const permissions = Array.isArray(now?.permissions) ? now.permissions.map(String) : person.permissions;
+                if (person.api_tier === null && !holdsFoundationRead(permissions)) {
+                    throw new ToolRefusal("forbidden", `Listing an episode's foundation documents needs Miadi's read tier or the ${FOUNDATIONS_PERMISSION} permission.`);
+                }
+                return foundationListing(person, a.episode);
+            }
             ({ episode, path } = parsed);
         }
         return readEpisodeFile(person, { ...a, episode, path });
@@ -1548,7 +1604,7 @@ export const TOOL_STATUS = {
     list_sessions: "live, Miadi write tier",
     get_session: "live, Miadi write tier",
     get_evidence: "live",
-    read_episode_file: "live (text files an episode holds: md, txt, yaml, yml, json, up to 512 KiB, paged; read as you, nothing changed)",
+    read_episode_file: "live (Miadi read tier: an episode's text files; chronicle_foundations_read alone: foundations/<topic>/*.md; up to 512 KiB, paged; read as you, nothing changed)",
     get_evaluations: "live (tracing records and recorded assessments; no provider scores)",
     get_narrative_beats: "live (NCP project beats and candidate beats)",
     review_lookup: "live (video search needs the review token on the connector host)",

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.11";
+export declare const VERSION = "0.1.12";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.1.11";
+export const VERSION = "0.1.12";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/connector",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "The Miadi connector: one remote MCP service through which a person signed in with their Miadi person token, from ChatGPT or any MCP client, reads sessions, reviews, episodes and circles and records observations, inquiries, handoffs and proposals with their name on each record.",
   "license": "MIT",
   "author": "Miadi",