@miadi/connector 0.1.9 → 0.1.11

package/dist/tools.js

@@ -18,9 +18,13 @@ 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 { 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";
 class ToolRefusal extends Error {
     code;
     detail;
@@ -60,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({
@@ -324,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.",
@@ -468,6 +567,72 @@ 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.",
+        inputSchema: {
+            ref: z
+                .string()
+                .min(1)
+                .describe("run_request:<id>, work_proposal:<id>, another record id, session:<uuid>, or owner/repo#n the mission cites."),
+        },
+        annotations: READ,
+    }, wrap(async ({ ref }, extra) => {
+        const { person } = who(extra);
+        const writeTier = person.api_tier === "write";
+        return missionStatus(ref.trim(), records(), {
+            projectOf: (r) => requestProjection(r, { reviewBase: ctx.approval?.config.reviewUrl, factoryDir: ctx.factoryDir }),
+            queueOf: (r) => (r.kind === "run_request" || r.kind === "work_proposal" ? readQueueState(r, ctx.factoryDir) : undefined),
+            tmuxSessions: writeTier ? (ctx.tmuxSessions ?? (() => [])) : undefined,
+            paneBusy: writeTier && ctx.tmux
+                ? (session) => {
+                    try {
+                        const pane = ctx.tmux.listPanes(session)[0];
+                        if (!pane)
+                            return "unknown";
+                        return isBusy(ctx.tmux.capture(`${session}:${pane.window}.${pane.pane}`)) ? "busy" : "idle";
+                    }
+                    catch {
+                        return "unknown";
+                    }
+                }
+                : undefined,
+            sessionOf: writeTier ? (id) => miadi.get(person.token, `/api/session/${encodeURIComponent(id)}`) : undefined,
+            issueOf: async (owner, repo, n) => {
+                const f = ctx.approval?.fetchImpl ?? fetch;
+                const headers = {
+                    accept: "application/vnd.github+json",
+                    ...(process.env.GITHUB_TOKEN ? { authorization: "Bearer " + process.env.GITHUB_TOKEN } : {}),
+                };
+                const pr = await f(`https://api.github.com/repos/${owner}/${repo}/pulls/${n}`, { headers, signal: AbortSignal.timeout(15_000) });
+                if (pr.ok) {
+                    const p = await pr.json();
+                    return { state: p.state, title: p.title, merged: Boolean(p.merged_at) };
+                }
+                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}` };
+                const i = await res.json();
+                return { state: i.state, title: i.title };
+            },
+        });
+    }));
+    server.registerTool("provider_capabilities", {
+        title: "Which agent providers this host can launch",
+        description: "The provider reality of the connector host (jgwill/Miadi#893): which agent CLIs are installed, their versions, whether sign-in evidence exists, the preference order (Codex, Pi, Copilot; Claude Code only on explicit request), and the read-only Jev routing preflight. No token is read or shown. Needs Miadi's write tier: this is host truth.",
+        inputSchema: {},
+        annotations: READ,
+    }, wrap(async (_args, extra) => {
+        const { person } = who(extra);
+        requireTier(person, "write");
+        return {
+            preference_order: PROVIDERS.map((p) => p.id),
+            explicit_only: PROVIDERS.filter((p) => !p.selectable_by_default).map((p) => p.id),
+            providers: discoverProviders(ctx.providersProbe),
+            router: await routerPreflight(process.env, ctx.approval?.fetchImpl ?? fetch),
+            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.",
+        };
+    }));
     // search / fetch: the pair ChatGPT uses for connectors in search and deep research.
     server.registerTool("search", {
         title: "Search Miadi",
@@ -494,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);
@@ -815,12 +998,31 @@ export function registerTools(server, ctx) {
             refs,
             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
+                .enum(["codex", "pi", "copilot", "claude"])
+                .optional()
+                .describe("The provider the run should launch with, verified installed on the connector host. Claude Code runs only when named explicitly. Unknown or unavailable leaves the mission unstarted."),
+            steering: z
+                .object({
+                max_attempts: z.number().int().min(1).max(20).describe("How many authorized follow-up steers this approval covers."),
+                expires_at: z.string().optional().describe("ISO time after which no steer runs under this grant."),
+                pane: z.string().regex(/^\d+\.\d+$/).optional().describe("The pane the seat lives in (window.pane); default the session's first pane."),
+            })
+                .optional()
+                .describe("The steering grant the approver covers with this run: bounded follow-ups to the same session through request_session_steer."),
             ...base,
         },
         annotations: WRITE,
     }, wrap(async (a, extra) => {
         const { person, auth } = who(extra);
         requireContribute(auth);
+        const found = discoverProviders(ctx.providersProbe);
+        const resolution = resolveProvider(a.provider, found);
+        if (resolution.state === "provider_unknown")
+            throw new ToolRefusal("invalid_request", resolution.message, { available: resolution.available });
+        if (resolution.state !== "ok") {
+            return { state: resolution.state, message: resolution.message, available: resolution.available, note: "Nothing was recorded or queued; the mission is unstarted." };
+        }
         const r = append("run_request", person, auth, {
             circle: a.circle,
             refs: a.refs,
@@ -829,9 +1031,100 @@ export function registerTools(server, ctx) {
             idempotency_key: a.idempotency_key,
             approval_state: "awaiting_approval",
             state: "pending",
-            body: { task: a.task, session: a.session, cwd: a.cwd },
+            body: {
+                task: a.task,
+                session: a.session,
+                cwd: a.cwd,
+                provider: a.provider,
+                resolved_provider: resolution.provider.id,
+                ...(a.steering ? { steering: a.steering } : {}),
+            },
         });
-        return { ...r, approval_url: approvalUrl(r.id) };
+        return {
+            ...r,
+            provider: { requested: a.provider ?? null, resolved: resolution.provider.id, explicit: resolution.explicit, version: resolution.provider.version },
+            approval_url: approvalUrl(r.id),
+        };
+    }));
+    server.registerTool("request_session_steer", {
+        title: "Send one authorized follow-up to a running agent",
+        description: "Steer one existing live agent session within an approved run's steering grant (jgwill/Miadi#893): the exact instruction is typed into the mission's bound pane — never whichever pane is active — after a peek, and a re-peek verifies the agent accepted it. When the approved run carries no steering grant covering this, the steer waits for one explicit scoped human decision on the returned approval_url. Every attempt leaves a durable artifact with its hash and both captures.",
+        inputSchema: {
+            run_request: z.string().min(1).describe("The approved run_request or work_proposal whose steering grant covers this steer."),
+            instruction: z.string().min(1).max(4000).describe("The exact instruction typed into the session. It is material within the approved mission's scope, not new authority."),
+            session: z.string().regex(/^[A-Za-z0-9._-]{3,80}$/).optional().describe("The session to steer; must be the one the grant binds."),
+            pane: z.string().regex(/^\d+\.\d+$/).optional().describe("The pane (window.pane); default the grant's pane, else the session's first pane. The active pane is never used."),
+            refs,
+            ...base,
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = who(extra);
+        requireContribute(auth);
+        requireTier(person, "write");
+        if (!ctx.tmux)
+            throw new ToolRefusal("unavailable", "The connector host has no steering surface; the steer is unstarted.");
+        const grantRecord = all().find((r) => r.id === a.run_request);
+        if (!grantRecord || (grantRecord.kind !== "run_request" && grantRecord.kind !== "work_proposal")) {
+            throw new ToolRefusal("invalid_ref", "Give the id of the approved run_request or work_proposal this steer belongs to.");
+        }
+        if (grantRecord.approval_state !== "approved") {
+            throw new ToolRefusal("not_approved", `${grantRecord.id} is ${grantRecord.approval_state ?? "not approved"}; a steer needs an approved run's grant or its own human decision.`);
+        }
+        const grant = steeringGrantOf(grantRecord);
+        const priorAttempts = steerAttempts(all(), grantRecord.id);
+        const covered = checkGrant(grant, priorAttempts) === "ok";
+        const body = {
+            instruction: a.instruction,
+            session: a.session ?? grantRecord.body.session,
+            pane: a.pane ?? grant?.pane,
+        };
+        const fields = {
+            circle: grantRecord.circle,
+            refs: [grantRecord.id, ...a.refs],
+            intention: a.intention,
+            role: a.role,
+            idempotency_key: a.idempotency_key,
+            body,
+        };
+        if (!covered) {
+            // One explicit scoped human decision (jgwill/Miadi#893): the record waits
+            // on the approval page; approving it runs exactly this instruction once.
+            const r = append("session_steer_request", person, auth, { ...fields, approval_state: "awaiting_approval", state: "pending" });
+            return {
+                ...r,
+                approval_url: approvalUrl(r.id),
+                state: "awaiting_approval",
+                reason: !grant ? "no_grant" : checkGrant(grant, priorAttempts),
+                message: "The approved run's steering grant does not cover this steer; a person's decision is requested, once, for exactly this instruction.",
+            };
+        }
+        const r = append("session_steer_request", person, auth, { ...fields, approval_state: "not_required" });
+        const result = await steerSession({ tmux: ctx.tmux, stateDir: config.stateDir, ...(ctx.steerSettleMs !== undefined ? { settleMs: ctx.steerSettleMs } : {}) }, { record: r, grantRecord, priorAttempts });
+        const delivered = result.status === "accepted" || result.status === "submitted";
+        ledger.append({
+            id: newRecordId(r.kind),
+            kind: r.kind,
+            created_at: new Date().toISOString(),
+            actor: r.actor,
+            refs: r.refs,
+            evidence_refs: [],
+            supersedes: r.id,
+            approval_state: "not_required",
+            state: delivered ? "completed" : "blocked",
+            completion_receipt: {
+                decision: "covered_by_grant",
+                decided_by: { person_id: person.id, name: person.name },
+                decided_at: new Date().toISOString(),
+                outcome: delivered ? result.status : "failed",
+                steer_status: result.status,
+                message: result.message,
+                ...(result.target ? { target: result.target } : {}),
+                ...(result.artifact ? { artifact: result.artifact } : {}),
+            },
+            body: r.body,
+        });
+        return records().find((x) => x.id === r.id) ?? r;
     }));
     server.registerTool("request_review_operation", {
         title: "Request a review operation",
@@ -1255,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)",
@@ -1262,6 +1556,8 @@ export const TOOL_STATUS = {
     handoff_status: "live",
     list_records: "live",
     get_run_result: "live",
+    mission_status: "live (operator details need the Miadi write tier)",
+    provider_capabilities: "live, Miadi write tier",
     search: "live",
     fetch: "live",
     append_observation: "live, contribute",
@@ -1275,7 +1571,8 @@ export const TOOL_STATUS = {
     propose_work: "live, contribute, needs_approval (approving starts the work as a factory run)",
     prepare_calendar_event: "live, contribute (draft and .ics only)",
     propose_session_completion: "live, contribute, needs_approval (decision recorded, nothing closed)",
-    request_authorized_run: "live, contribute, needs_approval (queues a factory brief once approved)",
+    request_authorized_run: "live, contribute, needs_approval (queues a factory brief once approved; may name a verified provider and a bounded steering grant)",
+    request_session_steer: "live, contribute, write tier (runs inside an approved run's steering grant, else one scoped human decision)",
     request_review_operation: "live, contribute, needs_approval",
     request_deep_diver: "live, contribute, needs_approval",
     link_review_to_episode: "live, contribute, needs_approval",

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

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