@miadi/connector 0.1.11 → 0.1.13

package/dist/tools.js

@@ -18,13 +18,14 @@ import { CIRCLES, CIRCLE_IDS, CLAIM_CATEGORIES, DOMAINS, HANDOFF_STATES, current
 import { VERSION } from "./version.js";
 import { AlreadyDecided, DECISIONS, KIND_LABELS, consequenceOf, decide, isApprovable, readQueueState, requestProjection } from "./approve.js";
 import { DECISIONS_CARD_HTML, DECISIONS_CARD_URI, DECISION_TOKENS_META } from "./decisions.js";
-import { discoverProviders, resolveProvider, routerPreflight, PROVIDERS } from "./providers.js";
-import { missionStatus } from "./mission-status.js";
+import { discoverProviders, jevConfigOf, resolveProvider, routerPreflight, PROVIDERS } from "./providers.js";
+import { authorizesActions, missionStatus, primaryIssueOf, resolveMissionSubject } from "./mission-status.js";
+import { candidatesFor, CRITICALITIES, jevAdapter, modelPreflight, PREFLIGHT_CONTRACT, PREFLIGHT_VERSION, TASK_TYPES, } from "./model-preflight.js";
 import { checkGrant, isBusy, steerAttempts, steeringGrantOf, steerSession } from "./steer.js";
 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;
@@ -84,6 +85,29 @@ const WRITE = { readOnlyHint: false, destructiveHint: false, openWorldHint: fals
 const refs = z.array(z.string()).max(50).default([]).describe("References: miadi-review:<uuid>, miadi-chronicle://<n>, owner/repo#n, session:<uuid>, a record id, or a URL.");
 const circle = z.enum(CIRCLE_IDS);
 const claim = z.enum(CLAIM_CATEGORIES).describe("observed, hypothesis, desired_future, fiction or verified_implementation.");
+const primaryIssue = z
+    .string()
+    .regex(/^[\w.-]+\/[\w.-]+#\d+$/)
+    .optional()
+    .describe("owner/repo#n: the one issue this mission implements. Other refs stay related. Without it, mission_status can only infer the mission from the first issue in refs (jgwill/Miadi#913).");
+/** Refs with the declared primary issue first, never duplicated. */
+function withPrimary(refs, primary) {
+    return primary ? [primary, ...refs.filter((r) => r !== primary)] : refs;
+}
+/**
+ * Why GitHub did not answer a reference (jgwill/Miadi#913 B). A 404 without a
+ * token is a private repository as often as a missing issue, so nothing here is
+ * ever reported as not found.
+ */
+export function githubAccess(status, hasToken) {
+    if (status === 404)
+        return hasToken ? "not_visible_to_token" : "no_github_token";
+    if (status === 401)
+        return "token_rejected";
+    if (status === 403 || status === 429)
+        return "forbidden_or_rate_limited";
+    return `github_${status}`;
+}
 function episodeRef(input) {
     // miadi-chronicle://316, miadi-chronicle:316, chronicle:<folder>, a folder, or a number
     return encodeURIComponent(input.replace(/^miadi-chronicle:(\/\/)?/, "").replace(/^chronicle:/, "").trim());
@@ -161,7 +185,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 +206,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: [
@@ -211,7 +251,7 @@ export function registerTools(server, ctx) {
                 signal: AbortSignal.timeout(15_000),
             });
             if (!res.ok)
-                return { ref: r, kind: "github_issue", state: res.status === 404 ? "not_found_or_private" : `github_${res.status}`, cited_by: cited };
+                return { ref: r, kind: "github_issue", state: "unverified", access: githubAccess(res.status, Boolean(process.env.GITHUB_TOKEN)), cited_by: cited };
             const i = await res.json();
             return {
                 ref: r,
@@ -341,6 +381,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 +409,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 +434,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 +479,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 +489,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 });
@@ -569,7 +649,7 @@ export function registerTools(server, ctx) {
     }));
     server.registerTool("mission_status", {
         title: "Where a mission stands",
-        description: "One mission, joined and verified: its source request and decision, the sessions bound to it (live or not), its issues and PRs, what is approved, queued, delivered, running, merged, released or closed — each by its evidence, never inferred from an idle pane — and the next authorized action. Operator details need Miadi's write tier. jgwill/Miadi#893.",
+        description: "One mission, joined and verified: its source request and decision, the sessions bound to it (live or not), its issues and PRs, what is approved, queued, delivered, running, merged, released or closed — each by its evidence, never inferred from an idle pane — and the next authorized action. An issue or session resolves only through the request that holds it as primary; several are ambiguous_mission, citations alone are related_only, and an inference authorizes nothing (identity.authorizes_actions). Released needs a release receipt with artifact, target, production check and a fresh time; closed needs an approved session ending that cites the mission. Operator details need Miadi's write tier. jgwill/Miadi#893, #913.",
         inputSchema: {
             ref: z
                 .string()
@@ -611,10 +691,11 @@ export function registerTools(server, ctx) {
                 }
                 const res = await f(`https://api.github.com/repos/${owner}/${repo}/issues/${n}`, { headers, signal: AbortSignal.timeout(15_000) });
                 if (!res.ok)
-                    return { state: res.status === 404 ? "not_found_or_private" : `github_${res.status}` };
+                    return { state: "unverified", access: githubAccess(res.status, Boolean(process.env.GITHUB_TOKEN)) };
                 const i = await res.json();
                 return { state: i.state, title: i.title };
             },
+            liveVersionOf: (pkg) => (pkg === "@miadi/connector" ? VERSION : undefined),
         });
     }));
     server.registerTool("provider_capabilities", {
@@ -633,6 +714,63 @@ export function registerTools(server, ctx) {
             note: "A provider name in a task's text selects nothing; request_authorized_run's provider field is verified against this list, and an unavailable provider leaves the mission unstarted.",
         };
     }));
+    server.registerTool("mission_model_preflight", {
+        title: "Which provider and model fits a mission, and how that is known",
+        description: "A typed, versioned, read-only preflight for one mission (jgwill/Miadi#913): the candidate providers with their concrete model when the host shows one, sign-in evidence (config directory only), quota unknown, policy eligibility (the approved provider is kept; Claude Code only when named), a review floor, and a recommendation or an abstention with its reasons. It says where the choice came from: static_fallback, jev or a synthetic fixture. Jev is asked only with consult_jev and a Jev key in the connector's environment; that call is charged, and it carries no task text, mission id or repository name. A reported launch on another provider than the approved one fails closed as provider_mismatch. It authorizes nothing. Needs Miadi's write tier.",
+        inputSchema: {
+            ref: z.string().min(1).describe("The mission: run_request:<id> or work_proposal:<id> (an issue or session ref resolves only through its primary relation)."),
+            task_type: z.enum(TASK_TYPES),
+            criticality: z.enum(CRITICALITIES).default("normal"),
+            consult_jev: z.boolean().default(false).describe("Ask Jev to choose among the eligible options. Charged by Jev; off by default."),
+            launch: z
+                .object({
+                provider: z.enum(["codex", "pi", "copilot", "claude"]),
+                model: z.string().max(120).optional(),
+                evidence: z.string().min(1).max(500).describe("What shows it: a process line, a pane header."),
+            })
+                .optional()
+                .describe("What actually launched, as observed. A provider other than the approved one fails closed."),
+        },
+        annotations: READ,
+    }, wrap(async (a, extra) => {
+        const { person } = who(extra);
+        requireTier(person, "write");
+        const found = resolveMissionSubject(String(a.ref).trim(), records());
+        if (!found?.record) {
+            return {
+                contract: PREFLIGHT_CONTRACT,
+                version: PREFLIGHT_VERSION,
+                state: "mission_unresolved",
+                ref: a.ref,
+                identity: found ? { resolution: found.resolution, candidates: found.candidates } : { resolution: "not_found", candidates: [] },
+                note: "Name one mission by its record id; no model is chosen for an unidentified mission.",
+            };
+        }
+        const record = found.record;
+        const body = record.body;
+        const provider = (typeof body.resolved_provider === "string" ? body.resolved_provider : typeof body.provider === "string" ? body.provider : null);
+        const basis = record.approval_state === "approved" ? "approved" : "requested";
+        const candidates = candidatesFor(discoverProviders(ctx.providersProbe), provider, ctx.modelOf, basis);
+        const jevConfig = jevConfigOf(process.env);
+        const jev = a.consult_jev ? (ctx.jevAdapter ?? (jevConfig ? jevAdapter(jevConfig, ctx.approval?.fetchImpl ?? fetch) : undefined)) : undefined;
+        const configured = Boolean(jevConfig);
+        const primary = primaryIssueOf(record);
+        return modelPreflight({
+            mission: {
+                id: record.id,
+                resolution: found.resolution,
+                authorizes_actions: authorizesActions(found),
+                ...(primary ? { primary_issue: primary.ref } : {}),
+            },
+            approved_provider: provider,
+            provider_basis: basis,
+            task: a.task_type,
+            criticality: a.criticality,
+            candidates,
+            ...(a.launch ? { launch: a.launch } : {}),
+            ...(jev ? { adapter: jev } : { routerWhenAbsent: configured ? "not_requested" : "router_unconfigured" }),
+        });
+    }));
     // search / fetch: the pair ChatGPT uses for connectors in search and deep research.
     server.registerTool("search", {
         title: "Search Miadi",
@@ -919,6 +1057,7 @@ export function registerTools(server, ctx) {
             desired_outcome: z.string().min(1).max(6000),
             circle,
             refs,
+            primary_issue: primaryIssue,
             repo: z.string().max(120).optional(),
             ...base,
         },
@@ -928,13 +1067,13 @@ export function registerTools(server, ctx) {
         requireContribute(auth);
         const r = append("work_proposal", person, auth, {
             circle: a.circle,
-            refs: a.refs,
+            refs: withPrimary(a.refs, a.primary_issue),
             intention: a.intention,
             role: a.role,
             idempotency_key: a.idempotency_key,
             state: "pending",
             approval_state: "awaiting_approval",
-            body: { title: a.title, desired_outcome: a.desired_outcome, repo: a.repo },
+            body: { title: a.title, desired_outcome: a.desired_outcome, repo: a.repo, ...(a.primary_issue ? { primary_issue: a.primary_issue } : {}) },
         });
         return { ...r, approval_url: approvalUrl(r.id) };
     }));
@@ -971,6 +1110,11 @@ export function registerTools(server, ctx) {
             session_id: z.string().min(8),
             ending: z.enum(["exit", "complete_then_exit", "record_only"]),
             reason: z.string().min(1).max(4000),
+            mission: z
+                .string()
+                .regex(/^(run_request|work_proposal):[\w-]+$/)
+                .optional()
+                .describe("The mission this ending closes, by record id. Only an approved exit or complete_then_exit that names the mission here closes it in mission_status (jgwill/Miadi#913)."),
             evidence_refs: refs,
         },
         annotations: WRITE,
@@ -980,11 +1124,11 @@ export function registerTools(server, ctx) {
         const id = a.session_id.replace(/^session:/, "");
         const r = append("session_completion_proposal", person, auth, {
             circle: "continuity",
-            refs: [`session:${id}`],
+            refs: a.mission ? [`session:${id}`, a.mission] : [`session:${id}`],
             evidence_refs: a.evidence_refs,
             approval_state: "awaiting_approval",
-            idempotency_key: `${id}:${a.ending}`,
-            body: { session_id: id, ending: a.ending, reason: a.reason },
+            idempotency_key: a.mission ? `${id}:${a.ending}:${a.mission}` : `${id}:${a.ending}`,
+            body: { session_id: id, ending: a.ending, reason: a.reason, ...(a.mission ? { mission: a.mission } : {}) },
         });
         return { ...r, approval_url: approvalUrl(r.id) };
     }));
@@ -996,6 +1140,7 @@ export function registerTools(server, ctx) {
             task: z.string().min(1).max(12000).describe("What the session does and what it returns."),
             circle,
             refs,
+            primary_issue: primaryIssue,
             session: z.string().regex(/^[A-Za-z0-9._-]{3,80}$/).optional().describe("An existing tmux session to hand it to, or a name for a new one."),
             cwd: z.string().max(300).optional().describe("Working folder for a new session (default the Miadi checkout)."),
             provider: z
@@ -1025,7 +1170,7 @@ export function registerTools(server, ctx) {
         }
         const r = append("run_request", person, auth, {
             circle: a.circle,
-            refs: a.refs,
+            refs: withPrimary(a.refs, a.primary_issue),
             intention: a.intention,
             role: a.role,
             idempotency_key: a.idempotency_key,
@@ -1037,6 +1182,7 @@ export function registerTools(server, ctx) {
                 cwd: a.cwd,
                 provider: a.provider,
                 resolved_provider: resolution.provider.id,
+                ...(a.primary_issue ? { primary_issue: a.primary_issue } : {}),
                 ...(a.steering ? { steering: a.steering } : {}),
             },
         });
@@ -1548,7 +1694,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)",
@@ -1557,6 +1703,7 @@ export const TOOL_STATUS = {
     list_records: "live",
     get_run_result: "live",
     mission_status: "live (operator details need the Miadi write tier)",
+    mission_model_preflight: "live, Miadi write tier (static policy; Jev only with consult_jev and a Jev key on the host, otherwise router_unconfigured)",
     provider_capabilities: "live, Miadi write tier",
     search: "live",
     fetch: "live",

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

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