@miadi/connector 0.1.10 → 0.1.11

package/README.md

@@ -20,12 +20,13 @@ 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`.
 - **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,62 @@
+/** The extensions Miadi's vessel reads as text (@medicine-wheel/episode-vessel TEXT_EXTENSIONS). */
+export declare const TEXT_TYPES: Record<string, string>;
+/** 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,115 @@
+/**
+ * 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 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, FileRefusal, MAX_TEXT_BYTES, MIN_PAGE_BYTES, TEXT_TYPES, checkRelativePath, episodeNumberOf, extensionOf, fileRef, 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({
@@ -327,12 +330,105 @@ 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).
+     */
+    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 = 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 url = `/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 || 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). 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) => {
+        const { person } = who(extra);
+        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.");
+            ({ 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 +659,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 +1548,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)",
     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.11";

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/connector",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "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",