@miadi/connector 0.1.10 → 0.1.12

package/README.md

@@ -20,12 +20,14 @@ Call `get_capabilities` first. It names the signed-in person, their Miadi API ti
 
 | kind | tools |
 |---|---|
-| reads | `get_capabilities` `get_context` `list_circles` `get_circle` `list_sessions` `get_session` `get_evidence` `get_evaluations` `get_narrative_beats` `review_lookup` `review_versions` `handoff_status` `list_records` `get_run_result` `mission_status` `provider_capabilities` `search` `fetch` |
+| reads | `get_capabilities` `get_context` `list_circles` `get_circle` `list_sessions` `get_session` `get_evidence` `read_episode_file` `get_evaluations` `get_narrative_beats` `review_lookup` `review_versions` `handoff_status` `list_records` `get_run_result` `mission_status` `provider_capabilities` `search` `fetch` |
 | contributions | `append_observation` `open_inquiry` `link_records` `propose_narrative_beat` `record_evaluation` `register_source_intent` `record_handoff` `update_handoff` `prepare_calendar_event` `save_research` |
 | requests (approved by a person) | `propose_work` `propose_session_completion` `request_authorized_run` `request_session_steer` `request_review_operation` `request_deep_diver` `link_review_to_episode` `request_inquiry_episode` |
 | decisions in the conversation | `show_decisions` (cards), `decide_request` (called by the card only) |
 
 - **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

@@ -0,0 +1,71 @@
+/** 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;
+/** A page must hold the longest UTF-8 character. */
+export declare const MIN_PAGE_BYTES = 4;
+export declare class FileRefusal extends Error {
+    readonly code: "invalid_path" | "invalid_offset" | "unsupported" | "changed";
+    constructor(code: "invalid_path" | "invalid_offset" | "unsupported" | "changed", message: string);
+}
+/** The same rule as the vessel's assertRelativeFile, applied before any URL exists. */
+export declare function checkRelativePath(value: string): string[];
+export declare function extensionOf(path: string): string;
+/** `miadi-chronicle://548/foundations/x/README.md` → its episode and path; null for any other id. */
+export declare function parseFileRef(id: string): {
+    episode: string;
+    path: string;
+} | null;
+export declare function fileRef(episodeNumber: number | string, path: string): string;
+/** The episode number a folder carries (`2026-09-27-episode-548-…` → 548). */
+export declare function episodeNumberOf(folder: string): number | null;
+export interface MiadiText {
+    episode: string;
+    file: string;
+    content: string;
+    size: number;
+    revision?: {
+        sha256?: string;
+        bytes?: number;
+        modifiedAt?: string;
+    };
+}
+/**
+ * One page of a file Miadi returned whole. `offset` must be 0 or a
+ * `next.offset` this function gave, so a page never starts inside a character;
+ * `revision`, when given, must still be the file's sha256, so pages of two
+ * versions are never joined.
+ */
+export declare function pageOf(text: MiadiText, opts?: {
+    offset?: number;
+    maxBytes?: number;
+    revision?: string;
+}): {
+    page: {
+        offset: number;
+        end: number;
+        bytes: number;
+        sha256: string;
+        complete: boolean;
+        next: {
+            offset: number;
+            revision: string;
+        } | null;
+    };
+    text: string;
+    modified_at?: string | undefined;
+    verification?: string | undefined;
+    bytes: number;
+    sha256: string;
+    verified: boolean;
+};

package/dist/episode-files.js

@@ -0,0 +1,128 @@
+/**
+ * Reading one text file an episode holds, through Miadi's file door
+ * (`GET /api/chronicle/episodes/<ref>/files/<path>`, jgwill/Miadi#653), as the
+ * signed-in person. Miadi decides what that person may read: the episode's
+ * audience, the room rule (ceremony notes and captures), the vessel's path
+ * guard and its 512 KiB text limit. The connector adds two things Miadi cannot
+ * see from its side of the URL:
+ *
+ * - the path is checked before a URL is built, because a URL parser folds
+ *   `a/../../people` into another route before Miadi ever reads it;
+ * - the text is paged by UTF-8 bytes on character boundaries, each page
+ *   carrying the whole file's sha256, so a reader can join the pages and prove
+ *   they hold the file exactly (jgwill/Miadi#815).
+ */
+import { createHash } from "node:crypto";
+/** The extensions Miadi's vessel reads as text (@medicine-wheel/episode-vessel TEXT_EXTENSIONS). */
+export const TEXT_TYPES = {
+    ".md": "text/markdown; charset=utf-8",
+    ".txt": "text/plain; charset=utf-8",
+    ".yaml": "application/yaml; charset=utf-8",
+    ".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;
+/** A page must hold the longest UTF-8 character. */
+export const MIN_PAGE_BYTES = 4;
+export class FileRefusal extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** The same rule as the vessel's assertRelativeFile, applied before any URL exists. */
+export function checkRelativePath(value) {
+    if (!value || value.includes("\\") || value.includes("\0") || value.startsWith("/") || /^[a-z]+:/i.test(value)) {
+        throw new FileRefusal("invalid_path", "Name a file by its path inside the episode, as get_evidence lists it (e.g. foundations/<topic>/README.md).");
+    }
+    const segments = value.split("/");
+    if (segments.some((s) => !s || s === "." || s === ".." || s.startsWith(".") || /%2e|%2f|%5c|%00/i.test(s))) {
+        throw new FileRefusal("invalid_path", "The path has an empty, '.', '..', hidden or encoded segment; episode files are read by their listed path only.");
+    }
+    return segments;
+}
+export function extensionOf(path) {
+    const name = path.slice(path.lastIndexOf("/") + 1);
+    const dot = name.lastIndexOf(".");
+    return dot > 0 ? name.slice(dot).toLowerCase() : "";
+}
+/** `miadi-chronicle://548/foundations/x/README.md` → its episode and path; null for any other id. */
+export function parseFileRef(id) {
+    const m = /^miadi-chronicle:(?:\/\/)?([^/\s]+)\/(.+)$/.exec(id.trim());
+    return m ? { episode: m[1], path: m[2] } : null;
+}
+export function fileRef(episodeNumber, path) {
+    return `miadi-chronicle://${episodeNumber}/${path}`;
+}
+/** The episode number a folder carries (`2026-09-27-episode-548-…` → 548). */
+export function episodeNumberOf(folder) {
+    const m = /(?:^|-)episode-0*(\d+)(?:-|$)/.exec(folder);
+    return m ? Number.parseInt(m[1], 10) : null;
+}
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/**
+ * One page of a file Miadi returned whole. `offset` must be 0 or a
+ * `next.offset` this function gave, so a page never starts inside a character;
+ * `revision`, when given, must still be the file's sha256, so pages of two
+ * versions are never joined.
+ */
+export function pageOf(text, opts = {}) {
+    const bytes = Buffer.from(text.content, "utf8");
+    const total = bytes.byteLength;
+    const whole = sha256(bytes);
+    if (opts.revision && opts.revision !== whole) {
+        throw new FileRefusal("changed", `The file changed since that page was read (it was ${opts.revision}, it is ${whole} now). Read it again from offset 0.`);
+    }
+    const offset = opts.offset ?? 0;
+    const maxBytes = Math.max(MIN_PAGE_BYTES, opts.maxBytes ?? DEFAULT_PAGE_BYTES);
+    if (!Number.isInteger(offset) || offset < 0 || offset > total || (offset < total && (bytes[offset] & 0xc0) === 0x80)) {
+        throw new FileRefusal("invalid_offset", `offset must be 0 or a next.offset this tool returned (the file has ${total} bytes).`);
+    }
+    let end = Math.min(total, offset + maxBytes);
+    while (end < total && (bytes[end] & 0xc0) === 0x80)
+        end--;
+    const page = bytes.subarray(offset, end);
+    const complete = end === total;
+    // Miadi computed its sha256 over the text it decoded; the bytes on disk are
+    // `size`. Both agree only when the file is valid UTF-8 and was read whole.
+    const miadiSha = text.revision?.sha256;
+    const verified = miadiSha === whole && total === text.size;
+    return {
+        bytes: total,
+        sha256: whole,
+        verified,
+        ...(verified
+            ? {}
+            : {
+                verification: miadiSha !== whole
+                    ? `Miadi named sha256 ${miadiSha ?? "none"}; the text received hashes to ${whole}.`
+                    : `The file is ${text.size} bytes on disk and ${total} bytes as UTF-8 text: it is not valid UTF-8, and the text holds replacement characters.`,
+            }),
+        ...(text.revision?.modifiedAt ? { modified_at: text.revision.modifiedAt } : {}),
+        page: {
+            offset,
+            end,
+            bytes: page.byteLength,
+            sha256: sha256(page),
+            complete,
+            next: complete ? null : { offset: end, revision: whole },
+        },
+        text: page.toString("utf8"),
+    };
+}

package/dist/tools.js

@@ -24,6 +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, 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;
@@ -63,6 +64,8 @@ function wrap(fn) {
                 return fail({ error: error.code, message: error.message, ...(error.detail ? { detail: error.detail } : {}) });
             if (error instanceof UploadRefusal)
                 return fail({ error: "invalid_upload", message: error.message });
+            if (error instanceof FileRefusal)
+                return fail({ error: error.code, message: error.message });
             if (error instanceof MiadiError) {
                 const unavailable = error.status === 0;
                 return fail({
@@ -158,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,
@@ -172,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: [
@@ -327,12 +346,145 @@ export function registerTools(server, ctx) {
         ]);
         return {
             episode: decodeURIComponent(ref),
-            files,
+            files: withReadRefs(files),
             screenwalks,
             reviews: epReviews,
             connector_records: touching(`miadi-chronicle://${decodeURIComponent(ref)}`),
         };
     }));
+    /**
+     * One text file of one episode, read as the person through Miadi's file
+     * 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);
+        const extension = extensionOf(path);
+        const contentType = TEXT_TYPES[extension];
+        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 = 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 = 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);
+        }
+        catch (error) {
+            if (!(error instanceof MiadiError))
+                throw error;
+            const body = (error.body ?? {});
+            const detail = { episode: decodeURIComponent(ref), path, miadi: { status: error.status, ...body } };
+            if (error.status === 0)
+                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)
+                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);
+            if (body.error === "TOO_LARGE")
+                throw new ToolRefusal("too_large", `${path} is larger than the ${MAX_TEXT_BYTES / 1024} KiB Miadi reads as text whole; nothing of it is returned.`, detail);
+            if (error.status === 415)
+                throw new ToolRefusal("unsupported", body.message ?? `${path} is not text Miadi reads.`, detail);
+            if (error.status === 400)
+                throw new ToolRefusal("invalid_path", body.message ?? `${path} is not a readable path in the episode.`, detail);
+            throw error;
+        }
+        if (typeof text?.content !== "string")
+            throw new ToolRefusal("unsupported", `Miadi did not return ${path} as text.`);
+        const number = episodeNumberOf(text.episode);
+        const episodeAddress = number === null ? `chronicle:${text.episode}` : `miadi-chronicle://${number}`;
+        return {
+            ref: fileRef(number ?? text.episode, text.file ?? path),
+            episode: { ref: episodeAddress, number, folder: text.episode },
+            path: text.file ?? path,
+            content_type: contentType,
+            ...pageOf(text, { offset: a.offset, maxBytes: a.max_bytes, revision: a.revision }),
+        };
+    };
+    /** Each text file Miadi lists as previewable carries the ref read_episode_file and fetch take. */
+    const withReadRefs = (listing) => {
+        const folder = listing?.episode?.path;
+        if (!folder || !Array.isArray(listing?.files))
+            return listing;
+        const number = listing.episode.number ?? episodeNumberOf(folder);
+        return {
+            ...listing,
+            files: listing.files.map((f) => f?.kind === "text" && f.previewable && TEXT_TYPES[extensionOf(String(f.relativePath))]
+                ? { ...f, read_ref: fileRef(number ?? folder, f.relativePath) }
+                : f),
+            connector_read: "A file with read_ref is read whole, in pages if long, by read_episode_file or fetch. Files without one are listed only.",
+        };
+    };
+    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); 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."),
+            offset: z.number().int().min(0).optional().describe("0, or page.next.offset from the previous page."),
+            revision: z.string().regex(/^[0-9a-f]{64}$/).optional().describe("page.next.revision from the previous page: refuses with changed if the file moved since."),
+            max_bytes: z.number().int().min(MIN_PAGE_BYTES).max(MAX_TEXT_BYTES).optional().describe(`Page size in bytes (default ${DEFAULT_PAGE_BYTES}).`),
+        },
+        annotations: READ,
+    }, wrap(async (a, 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) {
+                // 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 });
+    }));
     server.registerTool("get_evaluations", {
         title: "Evaluations: provider traces and recorded assessments",
         description: "The tracing records (LLMOps provider traces and prompts) an episode holds, and the assessments people recorded with record_evaluation, operational and creator-experience kept apart.",
@@ -563,11 +715,29 @@ export function registerTools(server, ctx) {
     }));
     server.registerTool("fetch", {
         title: "Fetch one item found by search",
-        description: "The full text of an item returned by search: a review (miadi-review:<uuid>) or a connector record id.",
+        description: "The full text of an item returned by search: a review (miadi-review:<uuid>) or a connector record id; or of an episode file by the read_ref get_evidence lists (miadi-chronicle://<n>/<path>), its first page when long.",
         inputSchema: { id: z.string().min(1) },
         annotations: READ,
     }, wrap(async ({ id }, extra) => {
-        who(extra);
+        const { person } = who(extra);
+        const file = parseFileRef(id);
+        if (file) {
+            const read = await readEpisodeFile(person, file);
+            return {
+                id: read.ref,
+                title: `${read.path} (${read.episode.ref})`,
+                text: read.text,
+                url: `${config.miadiPublicUrl}/chronicle/${encodeURIComponent(read.episode.folder)}`,
+                metadata: {
+                    content_type: read.content_type,
+                    bytes: read.bytes,
+                    sha256: read.sha256,
+                    verified: read.verified,
+                    complete: read.page.complete,
+                    ...(read.page.next ? { next: { tool: "read_episode_file", episode: read.ref, ...read.page.next } } : {}),
+                },
+            };
+        }
         const reviewId = reviewIdOf(id);
         if (reviewId) {
             const r = await reviews.get(reviewId);
@@ -1434,6 +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 (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.10";
+export declare const VERSION = "0.1.12";

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/connector",
-  "version": "0.1.10",
+  "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",
@@ -26,7 +26,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@miadi/inquiry-weave": "0.18.5",
+    "@miadi/inquiry-weave": "0.18.8",
     "@miadi/node-service-kit": "0.1.2",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "express": "^5.2.1",