@miadi/connector 0.0.0-stage → 0.1.1

package/dist/tools.js

@@ -0,0 +1,954 @@
+/**
+ * The connector's tools: the verbs of jgwill/Miadi#815 ("Connector v2") and
+ * #816 (Review Bridge), each a thin adapter over a Miadi route, the review
+ * service, or the connector's own ledger.
+ *
+ * Three kinds:
+ * - reads (readOnlyHint), for any signed-in person, within their Miadi tier;
+ * - contributions, which append a record in the person's name (scope
+ *   miadi:contribute) and change nothing else;
+ * - requests, which append a record awaiting approval and return the page
+ *   where a person with Miadi's write tier approves it. Only that page runs it.
+ */
+import { z } from "zod";
+import { MiadiError } from "./miadi.js";
+import { reviewIdOf, videoIdOf } from "./reviews.js";
+import { SCOPE_CONTRIBUTE } from "./oauth.js";
+import { CIRCLES, CIRCLE_IDS, CLAIM_CATEGORIES, DOMAINS, HANDOFF_STATES, current, newRecordId, } from "./records.js";
+import { VERSION } from "./version.js";
+import { readQueueState } from "./approve.js";
+class ToolRefusal extends Error {
+    code;
+    detail;
+    constructor(code, message, detail) {
+        super(message);
+        this.code = code;
+        this.detail = detail;
+    }
+}
+function personOf(extra) {
+    const auth = extra.authInfo;
+    const person = auth?.extra?.person;
+    if (!auth || !person)
+        throw new ToolRefusal("unauthenticated", "No signed-in person on this request.");
+    return { person, auth };
+}
+function requireContribute(auth) {
+    if (!auth.scopes.includes(SCOPE_CONTRIBUTE)) {
+        throw new ToolRefusal("insufficient_scope", "This sign-in did not allow contributions. Sign in again and allow contributions in your name.");
+    }
+}
+function requireTier(person, tier) {
+    const ok = person.api_tier === "write" || (tier === "read" && person.api_tier === "read");
+    if (!ok) {
+        throw new ToolRefusal("forbidden", `Miadi gives the ${person.role ?? "current"} role ${person.api_tier ? `the ${person.api_tier} tier` : "no API tier"}; this tool needs the ${tier} tier.`);
+    }
+}
+const ok = (value) => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
+const fail = (value) => ({ isError: true, content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
+function wrap(fn) {
+    return async (args, extra) => {
+        try {
+            return ok(await fn(args, extra));
+        }
+        catch (error) {
+            if (error instanceof ToolRefusal)
+                return fail({ error: error.code, message: error.message, ...(error.detail ? { detail: error.detail } : {}) });
+            if (error instanceof MiadiError) {
+                const unavailable = error.status === 0;
+                return fail({
+                    error: unavailable ? "unavailable" : error.status === 404 ? "not_found" : "miadi_error",
+                    status: error.status,
+                    path: error.path,
+                    body: error.body,
+                });
+            }
+            return fail({ error: "failed", message: error instanceof Error ? error.message : String(error) });
+        }
+    };
+}
+const READ = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };
+const WRITE = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
+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.");
+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());
+}
+export function registerTools(server, ctx) {
+    const { config, miadi, reviews, ledger } = ctx;
+    const actorOf = (person, auth) => {
+        const client = ctx.oauthState.read().clients[auth.clientId];
+        return { person_id: person.id, name: person.name, client_id: auth.clientId, ...(client?.client_name ? { client_name: client.client_name } : {}) };
+    };
+    const approvalUrl = (id) => `${config.publicUrl}/approve/${encodeURIComponent(id)}`;
+    const append = (kind, person, auth, fields) => {
+        if (fields.idempotency_key) {
+            const prior = ledger.all().find((r) => r.kind === kind && r.idempotency_key === fields.idempotency_key && r.actor.person_id === person.id);
+            if (prior)
+                return prior;
+        }
+        return ledger.append({
+            id: newRecordId(kind),
+            kind,
+            created_at: new Date().toISOString(),
+            actor: actorOf(person, auth),
+            refs: [],
+            evidence_refs: [],
+            ...fields,
+        });
+    };
+    const records = () => current(ledger.all());
+    const touching = (ref) => records().filter((r) => r.refs.includes(ref) || r.evidence_refs.includes(ref) || r.id === ref);
+    // ── reads ──────────────────────────────────────────────────────────────
+    server.registerTool("get_capabilities", {
+        title: "What this connector can do for you",
+        description: "The capability handshake: who you are signed in as, your Miadi tier and scopes, every tool with its status (live, needs_approval, write_tier), the services reached and the five circles. Call this first.",
+        inputSchema: {},
+        annotations: READ,
+    }, wrap(async (_args, extra) => {
+        const { person, auth } = personOf(extra);
+        const miadiUp = await miadi.get(person.token, "/api/identity/me").then(() => "reachable", (e) => (e instanceof MiadiError && e.status === 0 ? "unavailable" : "reachable"));
+        return {
+            service: "@miadi/connector",
+            version: VERSION,
+            contract: "jgwill/Miadi#815 Connector v2, jgwill/Miadi#816 Review Bridge",
+            signed_in_as: { person_id: person.id, name: person.name, role: person.role ?? null, miadi_api_tier: person.api_tier, via: auth.clientId },
+            scopes: auth.scopes,
+            can_contribute: auth.scopes.includes(SCOPE_CONTRIBUTE),
+            services: {
+                miadi: { url: config.miadiPublicUrl, state: miadiUp },
+                review_service: { url: config.reviewUrl, search: reviews.canSearch ? "enabled" : "disabled: no token on the connector host" },
+                ledger: "connector ledger (append-only, /srv/miadi/connector)",
+            },
+            tools: TOOL_STATUS,
+            domains: DOMAINS,
+            circles: CIRCLES.map((c) => ({ id: c.id, glyph: c.glyph, name: c.name })),
+            not_built: [
+                "Calendar events are drafts with an .ics text; nothing is put on a calendar.",
+                "A decided session ending is recorded, never executed: no pane is closed through the connector.",
+                "Narrative clustering (#314) has no code; beats come from NCP projects and candidate beats recorded here.",
+                "Langfuse scores are not read; evaluations are the tracing records of an episode and the assessments recorded here.",
+            ],
+        };
+    }));
+    server.registerTool("get_context", {
+        title: "Resolve a reference",
+        description: "Resolve one reference to what it points at: miadi-review:<uuid> (with the episodes that hold it), miadi-chronicle://<n> or chronicle:<folder>, miadi-ceremony:, miadi-circle:, miadi-foundation:, miadi-tracing:, session:<uuid>, owner/repo#n (GitHub issue), a YouTube URL or video id, or a connector record id. Also lists connector records that cite it.",
+        inputSchema: { ref: z.string().min(1) },
+        annotations: READ,
+    }, wrap(async ({ ref }, extra) => {
+        const { person } = personOf(extra);
+        const r = ref.trim();
+        const cited = touching(r);
+        if (/^session:/.test(r)) {
+            requireTier(person, "write");
+            const id = r.replace(/^session:/, "");
+            return { ref: r, kind: "session", session: await miadi.get(person.token, `/api/session/${encodeURIComponent(id)}`), cited_by: cited };
+        }
+        if (/^[a-z_]+:[0-9a-f-]{36}$/.test(r) && r.split(":")[0] !== "miadi-review" && r.split(":")[0] !== "review" && r.split(":")[0] !== "session") {
+            const rec = records().find((x) => x.id === r);
+            if (rec)
+                return { ref: r, kind: "connector_record", record: rec, cited_by: cited.filter((x) => x.id !== r) };
+        }
+        const issue = r.match(/^([\w.-]+)\/([\w.-]+)#(\d+)$/);
+        if (issue) {
+            const res = await fetch(`https://api.github.com/repos/${issue[1]}/${issue[2]}/issues/${issue[3]}`, {
+                headers: { accept: "application/vnd.github+json", ...(process.env.GITHUB_TOKEN ? { authorization: `Bearer ${process.env.GITHUB_TOKEN}` } : {}) },
+            });
+            if (!res.ok)
+                return { ref: r, kind: "github_issue", state: res.status === 404 ? "not_found_or_private" : `github_${res.status}`, cited_by: cited };
+            const i = await res.json();
+            return {
+                ref: r,
+                kind: i.pull_request ? "github_pull_request" : "github_issue",
+                title: i.title,
+                state: i.state,
+                url: i.html_url,
+                labels: (i.labels ?? []).map((l) => l.name),
+                updated_at: i.updated_at,
+                body: String(i.body ?? "").slice(0, 6000),
+                cited_by: cited,
+            };
+        }
+        const video = videoIdOf(r);
+        if (video && !reviewIdOf(r)) {
+            return { ref: r, kind: "video", video_id: video, reviews: await lookupByVideo(video), cited_by: cited };
+        }
+        const reviewId = reviewIdOf(r);
+        const uri = reviewId ? `miadi-review:${reviewId}` : r.replace(/^chronicle:/, "miadi-chronicle:");
+        const resolved = await miadi.get(person.token, `/api/chronicle/resolve?uri=${encodeURIComponent(uri)}`);
+        return { ref: r, kind: "miadi_reference", resolved, cited_by: cited };
+    }));
+    async function lookupByVideo(videoId) {
+        if (!reviews.canSearch)
+            return { state: "search_unavailable", message: "The connector host has no review service token; give the review id instead." };
+        const found = (await reviews.search(videoId, 10)).filter((x) => x.video_id === videoId);
+        return found.map((x) => reviews.summary(x));
+    }
+    server.registerTool("list_circles", {
+        title: "The five circles, and the talking circles you belong to",
+        description: "The five accountable circles (Story, Stewardship, Engineering, Evaluation, Continuity) with what each is accountable for and how many handoffs each holds open, and the Miadi talking circles your person token reaches.",
+        inputSchema: {},
+        annotations: READ,
+    }, wrap(async (_args, extra) => {
+        const { person } = personOf(extra);
+        const open = records().filter((r) => r.kind === "handoff" && r.state !== "completed" && r.state !== "withdrawn");
+        const talking = await miadi.get(person.token, "/api/circles").then((b) => (b.circles ?? []).map((c) => ({ id: c.id, name: c.name, intention: c.intention, member: c.member ?? undefined })), (e) => ({ state: e instanceof MiadiError ? `miadi_${e.status}` : "unavailable" }));
+        return {
+            accountability_circles: CIRCLES.map((c) => ({ ...c, open_handoffs: open.filter((r) => r.to_circle === c.id || r.circle === c.id).length })),
+            note: "The legacy teams T1–T7 (miadi-orchestration-kit teams/teams.json) are migration evidence; no team is mapped to a circle until that mapping is decided.",
+            talking_circles: talking,
+        };
+    }));
+    server.registerTool("get_circle", {
+        title: "One circle",
+        description: "One of the five circles by id (story, stewardship, engineering, evaluation, continuity) with its open handoffs, proposals and requests, or a Miadi talking circle by its id with its members and ceremonies.",
+        inputSchema: { circle_id: z.string().min(1) },
+        annotations: READ,
+    }, wrap(async ({ circle_id }, extra) => {
+        const { person } = personOf(extra);
+        const five = CIRCLES.find((c) => c.id === circle_id.toLowerCase());
+        if (five) {
+            const mine = records().filter((r) => r.circle === five.id || r.to_circle === five.id || r.from_circle === five.id);
+            return {
+                circle: five,
+                handoffs: mine.filter((r) => r.kind === "handoff"),
+                proposals: mine.filter((r) => r.kind === "work_proposal" || r.kind === "run_request"),
+                observations: mine.filter((r) => r.kind === "observation" || r.kind === "inquiry").slice(-25),
+            };
+        }
+        return { talking_circle: await miadi.get(person.token, `/api/circles/${encodeURIComponent(circle_id.replace(/^miadi-circle:/, ""))}`) };
+    }));
+    server.registerTool("list_sessions", {
+        title: "Agent sessions",
+        description: "Agent sessions as Miadi joins them (binding line, live registry, witness inventory): intention, team, accountable circle, episode, review refs, and work_status, runtime_status and closure_status kept apart. Newest first. Needs Miadi's write tier: session names and panes are operator data.",
+        inputSchema: {
+            episode: z.string().optional().describe("An episode folder, to list the sessions that worked in it."),
+            live_only: z.boolean().optional(),
+            team: z.string().optional().describe("Legacy team id, e.g. T3."),
+            status: z.string().optional().describe("A work_status (complete, in_progress, held…) or a runtime_status (running, ended, not_running)."),
+            q: z.string().optional().describe("Text in the name, intention, repo or review refs."),
+            limit: z.number().int().min(1).max(200).optional(),
+        },
+        annotations: READ,
+    }, wrap(async (args, extra) => {
+        const { person } = personOf(extra);
+        requireTier(person, "write");
+        const qs = new URLSearchParams();
+        if (args.episode)
+            qs.set("episode", args.episode);
+        if (args.live_only)
+            qs.set("live", "1");
+        if (args.team)
+            qs.set("team", args.team);
+        if (args.status)
+            qs.set("status", args.status);
+        if (args.q)
+            qs.set("q", args.q);
+        qs.set("limit", String(args.limit ?? 30));
+        return miadi.get(person.token, `/api/session?${qs}`);
+    }));
+    server.registerTool("get_session", {
+        title: "One agent session",
+        description: "One session by id: what it was asked to do, what its record says it completed, what it holds, its ending (proposed or decided), the live pane state, and the connector records that cite it (handoffs, completion proposals).",
+        inputSchema: { session_id: z.string().min(8) },
+        annotations: READ,
+    }, wrap(async ({ session_id }, extra) => {
+        const { person } = personOf(extra);
+        requireTier(person, "write");
+        const id = session_id.replace(/^session:/, "");
+        const session = await miadi.get(person.token, `/api/session/${encodeURIComponent(id)}`);
+        return { ...session, connector_records: touching(`session:${id}`) };
+    }));
+    server.registerTool("get_evidence", {
+        title: "What an episode holds as evidence",
+        description: "For one Chronicle episode: its files by name, its screenwalks, the reviews it holds with their versions, and the connector records that cite it. Captures other than screenwalks are not listed by Miadi yet.",
+        inputSchema: { episode: z.string().min(1).describe("miadi-chronicle://<n>, an episode number or its folder.") },
+        annotations: READ,
+    }, wrap(async ({ episode }, extra) => {
+        const { person } = personOf(extra);
+        const ref = episodeRef(episode);
+        const [files, screenwalks, epReviews] = await Promise.all([
+            miadi.get(person.token, `/api/chronicle/episodes/${ref}/files`).catch(asState),
+            miadi.get(person.token, `/api/chronicle/episodes/${ref}/screenwalks`).catch(asState),
+            miadi.get(person.token, `/api/chronicle/episodes/${ref}/reviews`).catch(asState),
+        ]);
+        return {
+            episode: decodeURIComponent(ref),
+            files,
+            screenwalks,
+            reviews: epReviews,
+            connector_records: touching(`miadi-chronicle://${decodeURIComponent(ref)}`),
+        };
+    }));
+    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.",
+        inputSchema: { episode: z.string().optional(), subject_ref: z.string().optional() },
+        annotations: READ,
+    }, wrap(async ({ episode, subject_ref }, extra) => {
+        const { person } = personOf(extra);
+        const evals = records().filter((r) => r.kind === "observation" && typeof r.body?.assessment === "string");
+        const scoped = subject_ref ? evals.filter((r) => r.refs.includes(subject_ref)) : evals;
+        return {
+            tracing: episode ? await miadi.get(person.token, `/api/chronicle/episodes/${episodeRef(episode)}/tracing`).catch(asState) : "give an episode to read its tracing records",
+            operational: scoped.filter((r) => r.body.assessment === "operational"),
+            creator_experience: scoped.filter((r) => r.body.assessment === "creator_experience"),
+        };
+    }));
+    server.registerTool("get_narrative_beats", {
+        title: "Narrative beats",
+        description: "Story beats of an NCP story project in Miadi's studio (e.g. chimera), and the candidate narrative beats people recorded with propose_narrative_beat, each with its claim category so a witnessed moment and an imagined one stay apart.",
+        inputSchema: { project: z.string().optional().describe("NCP studio project id, e.g. chimera."), episode: z.string().optional() },
+        annotations: READ,
+    }, wrap(async ({ project, episode }, extra) => {
+        const { person } = personOf(extra);
+        let ncp = "give a project id to read its story beats";
+        if (project) {
+            ncp = await miadi.get(person.token, `/api/ncp/projects/${encodeURIComponent(project)}`).then((b) => ({ project: project, beats: collectBeats(b?.project), validation: b?.validation ?? null }), asState);
+        }
+        const candidates = records().filter((r) => r.body?.narrative_beat === true && (!episode || r.refs.some((x) => x.includes(String(episode)))));
+        return { ncp, candidate_beats: candidates };
+    }));
+    server.registerTool("review_lookup", {
+        title: "Find a Miadi review",
+        description: "Find the review of a video before anything is created: by review id, review URL, YouTube URL or video id, or keywords. Returns review id, latest version, video, Deep Diver readiness and the episodes that hold it. Never creates a review.",
+        inputSchema: { query: z.string().min(1) },
+        annotations: READ,
+    }, wrap(async ({ query }, extra) => {
+        const { person } = personOf(extra);
+        const id = reviewIdOf(query);
+        if (id) {
+            const r = await reviews.get(id);
+            if (!r)
+                return { query, state: "not_found", review_id: id };
+            const holders = await miadi.get(person.token, `/api/chronicle/resolve?uri=${encodeURIComponent(`miadi-review:${id}`)}`).then((b) => b?.holders ?? b?.resolution?.holders ?? null, () => null);
+            return { query, state: "found", review: reviews.summary(r), holders, cited_by: touching(`miadi-review:${id}`) };
+        }
+        const video = videoIdOf(query);
+        if (video) {
+            const found = await lookupByVideo(video);
+            const intents = records().filter((r) => r.kind === "source_intent" && r.body.video_id === video);
+            return { query, video_id: video, state: Array.isArray(found) && found.length ? "found" : "no_review", reviews: found, source_intents: intents };
+        }
+        if (!reviews.canSearch)
+            return { query, state: "search_unavailable" };
+        return { query, state: "searched", reviews: (await reviews.search(query, 10)).map((x) => reviews.summary(x)) };
+    }));
+    server.registerTool("review_versions", {
+        title: "A review's versions",
+        description: "Every version of a review (immutable history: number, model, date), and the text of one version (latest by default) with its aspects and results.",
+        inputSchema: { review_id: z.string().min(8), version: z.number().int().min(1).optional() },
+        annotations: READ,
+    }, wrap(async ({ review_id, version }) => {
+        const id = reviewIdOf(review_id);
+        if (!id)
+            throw new ToolRefusal("invalid_ref", "Give a review UUID, miadi-review:<uuid> or the review's URL.");
+        const r = await reviews.get(id, version);
+        if (!r)
+            return { state: "not_found", review_id: id };
+        return {
+            review: reviews.summary(r),
+            versions: r.versions ?? [],
+            selected: r.version
+                ? { version: r.version.version, model: r.version.model, created_at: r.version.created_at, markdown: r.version.markdown, data: r.version.data }
+                : null,
+            raw_url: `${config.reviewUrl}/review/${id}/raw${version ? `?v=${version}` : ""}`,
+        };
+    }));
+    server.registerTool("handoff_status", {
+        title: "Handoffs between circles",
+        description: "Handoffs and their state (pending, blocked, ready, in_progress, completed, withdrawn), responsible circle, next action, receipts and human gates. Filter by a reference, a circle or a state.",
+        inputSchema: { ref: z.string().optional(), circle: circle.optional(), state: z.enum(HANDOFF_STATES).optional() },
+        annotations: READ,
+    }, wrap(async ({ ref, circle: c, state }, extra) => {
+        personOf(extra);
+        let list = records().filter((r) => r.kind === "handoff" || r.kind === "source_intent");
+        if (ref)
+            list = list.filter((r) => r.id === ref || r.refs.includes(ref) || r.evidence_refs.includes(ref));
+        if (c)
+            list = list.filter((r) => r.to_circle === c || r.circle === c);
+        if (state)
+            list = list.filter((r) => r.state === state);
+        const gates = records().filter((r) => r.approval_state === "awaiting_approval");
+        return { handoffs: list, awaiting_approval: gates.map((r) => ({ id: r.id, kind: r.kind, created_at: r.created_at, by: r.actor.name, approval_url: approvalUrl(r.id) })) };
+    }));
+    server.registerTool("list_records", {
+        title: "Records contributed through the connector",
+        description: "The ledger, newest first: observations, inquiries, links, beats, evaluations, handoffs, proposals and requests, each with who made it and its claim category.",
+        inputSchema: {
+            kind: z.string().optional(),
+            circle: circle.optional(),
+            ref: z.string().optional(),
+            person_id: z.string().optional(),
+            limit: z.number().int().min(1).max(200).optional(),
+        },
+        annotations: READ,
+    }, wrap(async (a, extra) => {
+        personOf(extra);
+        let list = records();
+        if (a.kind)
+            list = list.filter((r) => r.kind === a.kind);
+        if (a.circle)
+            list = list.filter((r) => r.circle === a.circle || r.to_circle === a.circle);
+        if (a.ref)
+            list = list.filter((r) => r.refs.includes(a.ref) || r.evidence_refs.includes(a.ref));
+        if (a.person_id)
+            list = list.filter((r) => r.actor.person_id === a.person_id);
+        const out = list.reverse().slice(0, a.limit ?? 50);
+        return { records: out, count: out.length, total: list.length };
+    }));
+    server.registerTool("get_run_result", {
+        title: "Where a requested run stands",
+        description: "A run request's approval, the brief queued for the factory intake once approved, whether the intake delivered it, and its receipt.",
+        inputSchema: { record_id: z.string().min(1) },
+        annotations: READ,
+    }, wrap(async ({ record_id }, extra) => {
+        personOf(extra);
+        const r = records().find((x) => x.id === record_id);
+        if (!r)
+            return { state: "not_found", record_id };
+        return {
+            record: r,
+            approval_url: r.approval_state === "awaiting_approval" ? approvalUrl(r.id) : undefined,
+            queue: r.kind === "run_request" ? readQueueState(r, ctx.factoryDir) : undefined,
+        };
+    }));
+    // search / fetch: the pair ChatGPT uses for connectors in search and deep research.
+    server.registerTool("search", {
+        title: "Search Miadi",
+        description: "Search reviews (title, channel, video, text) and the connector's records. Returns ids to pass to fetch.",
+        inputSchema: { query: z.string().min(1) },
+        annotations: READ,
+    }, wrap(async ({ query }, extra) => {
+        personOf(extra);
+        const needle = query.toLowerCase();
+        const results = [];
+        if (reviews.canSearch) {
+            for (const r of await reviews.search(query, 10).catch(() => [])) {
+                results.push({ id: `miadi-review:${r.id}`, title: r.title ?? r.id, url: `${config.reviewUrl}/review/${r.id}` });
+            }
+        }
+        for (const r of records().reverse()) {
+            if (results.length >= 25)
+                break;
+            if (JSON.stringify(r.body).toLowerCase().includes(needle) || (r.intention ?? "").toLowerCase().includes(needle)) {
+                results.push({ id: r.id, title: `${r.kind} by ${r.actor.name}: ${String(r.body.title ?? r.body.text ?? r.intention ?? "").slice(0, 80)}`, url: `${config.publicUrl}/records/${encodeURIComponent(r.id)}` });
+            }
+        }
+        return { results };
+    }));
+    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.",
+        inputSchema: { id: z.string().min(1) },
+        annotations: READ,
+    }, wrap(async ({ id }, extra) => {
+        personOf(extra);
+        const reviewId = reviewIdOf(id);
+        if (reviewId) {
+            const r = await reviews.get(reviewId);
+            if (!r)
+                return { id, state: "not_found" };
+            return { id, title: r.title, text: r.version?.markdown ?? "", url: `${config.reviewUrl}/review/${reviewId}`, metadata: { latest_version: r.latest_version, video_id: r.video_id } };
+        }
+        const rec = records().find((x) => x.id === id);
+        if (!rec)
+            return { id, state: "not_found" };
+        return { id, title: `${rec.kind} by ${rec.actor.name}`, text: JSON.stringify(rec, null, 2), url: `${config.publicUrl}/records/${encodeURIComponent(rec.id)}`, metadata: { kind: rec.kind } };
+    }));
+    // ── contributions ──────────────────────────────────────────────────────
+    const base = {
+        intention: z.string().max(2000).optional().describe("Why this is recorded: the human intention it serves."),
+        role: z.string().max(80).optional().describe("The role you act in: author, steward, agent, reviewer…"),
+        idempotency_key: z.string().max(200).optional().describe("Repeat the same key to get the first record back instead of a duplicate."),
+    };
+    server.registerTool("append_observation", {
+        title: "Record an observation",
+        description: "Record what was observed (or hypothesised, desired, imagined) about a source, in your name, with its claim category and the circle it concerns. Fiction and desired futures stay labelled as such.",
+        inputSchema: {
+            text: z.string().min(1).max(20000),
+            claim_category: claim,
+            refs,
+            evidence_refs: refs,
+            circle: circle.optional(),
+            domain: z.enum(DOMAINS).optional(),
+            consent_boundary: z.string().max(1000).optional().describe("Who may see or use this, when it matters."),
+            ...base,
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = personOf(extra);
+        requireContribute(auth);
+        return append("observation", person, auth, {
+            claim_category: a.claim_category,
+            circle: a.circle,
+            domain: a.domain,
+            consent_boundary: a.consent_boundary,
+            refs: a.refs,
+            evidence_refs: a.evidence_refs,
+            intention: a.intention,
+            role: a.role,
+            idempotency_key: a.idempotency_key,
+            body: { text: a.text },
+        });
+    }));
+    server.registerTool("open_inquiry", {
+        title: "Open an inquiry",
+        description: "Record an open question for a circle to carry, with the sources it rests on. It stays open until a later record answers it.",
+        inputSchema: { question: z.string().min(1).max(5000), refs, circle: circle.optional(), episode: z.string().optional(), ...base },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = personOf(extra);
+        requireContribute(auth);
+        return append("inquiry", person, auth, {
+            circle: a.circle,
+            refs: a.episode ? [...a.refs, `miadi-chronicle://${String(a.episode).replace(/^miadi-chronicle:(\/\/)?/, "")}`] : a.refs,
+            intention: a.intention,
+            role: a.role,
+            idempotency_key: a.idempotency_key,
+            state: "pending",
+            body: { question: a.question },
+        });
+    }));
+    server.registerTool("link_records", {
+        title: "Relate two references",
+        description: "Record a relation between two references (a review and an episode, a session and an issue, a beat and a source), with the relation's name and why.",
+        inputSchema: { from: z.string().min(1), to: z.string().min(1), relation: z.string().min(1).max(80), note: z.string().max(2000).optional(), ...base },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = personOf(extra);
+        requireContribute(auth);
+        return append("link", person, auth, {
+            refs: [a.from, a.to],
+            intention: a.intention,
+            role: a.role,
+            idempotency_key: a.idempotency_key,
+            body: { from: a.from, to: a.to, relation: a.relation, note: a.note },
+        });
+    }));
+    server.registerTool("propose_narrative_beat", {
+        title: "Propose a candidate narrative beat",
+        description: "A candidate beat for the author to consider: a witnessed moment (observed) or an imagined one (desired_future, fiction), with the source it comes from. The author chooses whether it enters a chapter or song.",
+        inputSchema: {
+            title: z.string().min(1).max(200),
+            text: z.string().min(1).max(10000),
+            claim_category: z.enum(["observed", "desired_future", "fiction"]),
+            source_refs: refs,
+            episode: z.string().optional(),
+            ...base,
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = personOf(extra);
+        requireContribute(auth);
+        return append("observation", person, auth, {
+            circle: "story",
+            claim_category: a.claim_category,
+            refs: a.episode ? [...a.source_refs, `miadi-chronicle://${String(a.episode).replace(/^miadi-chronicle:(\/\/)?/, "")}`] : a.source_refs,
+            evidence_refs: a.source_refs,
+            intention: a.intention,
+            role: a.role,
+            idempotency_key: a.idempotency_key,
+            state: "pending",
+            body: { narrative_beat: true, title: a.title, text: a.text, author_choice: "pending" },
+        });
+    }));
+    server.registerTool("record_evaluation", {
+        title: "Record an assessment",
+        description: "An assessment of a subject (a review version, a session, a contribution): operational (did it work, with measured evidence) or creator_experience (did it help the author create, understand, relate, continue). The two are never merged.",
+        inputSchema: {
+            subject_ref: z.string().min(1),
+            assessment: z.enum(["operational", "creator_experience"]),
+            verdict: z.string().min(1).max(200),
+            notes: z.string().max(10000).optional(),
+            evidence_refs: refs,
+            ...base,
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = personOf(extra);
+        requireContribute(auth);
+        return append("observation", person, auth, {
+            circle: "evaluation",
+            claim_category: a.assessment === "operational" && a.evidence_refs.length ? "verified_implementation" : "observed",
+            refs: [a.subject_ref],
+            evidence_refs: a.evidence_refs,
+            intention: a.intention,
+            role: a.role,
+            idempotency_key: a.idempotency_key,
+            body: { assessment: a.assessment, verdict: a.verdict, notes: a.notes },
+        });
+    }));
+    server.registerTool("register_source_intent", {
+        title: "Register a pending source",
+        description: "Register a screenwalk or video as a pending source with its intention and readiness, without generating any review. One per video and purpose: registering again returns the first.",
+        inputSchema: {
+            video: z.string().min(1).describe("YouTube URL or video id."),
+            intention: z.string().min(1).max(4000),
+            readiness: z.enum(["uploading", "released_for_review", "withheld"]),
+            purpose: z.string().max(120).default("screenwalk_review"),
+            refs,
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = personOf(extra);
+        requireContribute(auth);
+        const video = videoIdOf(a.video);
+        if (!video)
+            throw new ToolRefusal("invalid_ref", "Give a YouTube URL or an 11-character video id.");
+        return append("source_intent", person, auth, {
+            circle: "continuity",
+            refs: [...a.refs, `https://youtu.be/${video}`],
+            intention: a.intention,
+            idempotency_key: `${video}:${a.purpose}`,
+            state: a.readiness === "released_for_review" ? "ready" : a.readiness === "withheld" ? "blocked" : "pending",
+            body: { video_id: video, supplied: a.video, readiness: a.readiness, purpose: a.purpose },
+        });
+    }));
+    server.registerTool("record_handoff", {
+        title: "Hand work to a circle",
+        description: "Record a durable handoff: which circle hands what to which circle, the contribution wanted, the evidence, and the next action. One accountable circle per handoff; no terminal is opened by it.",
+        inputSchema: {
+            source_ref: z.string().min(1),
+            from_circle: circle,
+            to_circle: circle,
+            desired_contribution: z.string().min(1).max(4000),
+            next_action: z.string().min(1).max(1000),
+            evidence_refs: refs,
+            refs,
+            state: z.enum(HANDOFF_STATES).default("pending"),
+            ...base,
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = personOf(extra);
+        requireContribute(auth);
+        return append("handoff", person, auth, {
+            from_circle: a.from_circle,
+            to_circle: a.to_circle,
+            circle: a.to_circle,
+            refs: [a.source_ref, ...a.refs],
+            evidence_refs: a.evidence_refs,
+            intention: a.intention,
+            role: a.role,
+            idempotency_key: a.idempotency_key,
+            state: a.state,
+            next_action: a.next_action,
+            body: { desired_contribution: a.desired_contribution },
+        });
+    }));
+    server.registerTool("update_handoff", {
+        title: "Move a handoff or inquiry on",
+        description: "Change the state of a handoff, inquiry, source intent or beat (accepted → in_progress → completed, or blocked, withdrawn), with a note and, on completion, the receipt: what was delivered and where.",
+        inputSchema: {
+            record_id: z.string().min(1),
+            state: z.enum(HANDOFF_STATES),
+            note: z.string().max(4000).optional(),
+            next_action: z.string().max(1000).optional(),
+            completion_receipt: z.record(z.string(), z.unknown()).optional(),
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = personOf(extra);
+        requireContribute(auth);
+        const target = records().find((r) => r.id === a.record_id);
+        if (!target)
+            return { state: "not_found", record_id: a.record_id };
+        if (!["handoff", "inquiry", "source_intent", "observation", "work_proposal"].includes(target.kind)) {
+            throw new ToolRefusal("not_updatable", `A ${target.kind} changes through its approval, not here.`);
+        }
+        append(target.kind, person, auth, {
+            supersedes: target.id,
+            refs: target.refs,
+            state: a.state,
+            next_action: a.next_action,
+            completion_receipt: a.completion_receipt,
+            body: { update: true, note: a.note },
+        });
+        return records().find((r) => r.id === target.id);
+    }));
+    server.registerTool("propose_work", {
+        title: "Propose work to a circle",
+        description: "Propose a bounded piece of work: what should exist when it is done, the circle accountable, the sources. A proposal; nothing starts. A person approves it before it becomes a run.",
+        inputSchema: {
+            title: z.string().min(1).max(200),
+            desired_outcome: z.string().min(1).max(6000),
+            circle,
+            refs,
+            repo: z.string().max(120).optional(),
+            ...base,
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = personOf(extra);
+        requireContribute(auth);
+        const r = append("work_proposal", person, auth, {
+            circle: a.circle,
+            refs: a.refs,
+            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 },
+        });
+        return { ...r, approval_url: approvalUrl(r.id) };
+    }));
+    server.registerTool("prepare_calendar_event", {
+        title: "Draft a calendar event",
+        description: "Draft a meeting (title, time, attendees, agenda) and return it with an .ics text. Nothing is put on anyone's calendar: a person adds it.",
+        inputSchema: {
+            title: z.string().min(1).max(200),
+            start: z.string().describe("ISO 8601 date-time with offset."),
+            end: z.string().optional(),
+            attendees: z.array(z.string()).max(30).default([]),
+            agenda: z.string().max(6000).optional(),
+            refs,
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = personOf(extra);
+        requireContribute(auth);
+        const start = new Date(a.start);
+        if (Number.isNaN(start.getTime()))
+            throw new ToolRefusal("invalid_time", "start must be an ISO 8601 date-time.");
+        const end = a.end ? new Date(a.end) : new Date(start.getTime() + 3600_000);
+        const r = append("calendar_event_draft", person, auth, {
+            refs: a.refs,
+            approval_state: "not_required",
+            body: { title: a.title, start: start.toISOString(), end: end.toISOString(), attendees: a.attendees, agenda: a.agenda },
+        });
+        return { ...r, ics: ics(r.id, a.title, start, end, a.agenda ?? "", a.attendees) };
+    }));
+    server.registerTool("propose_session_completion", {
+        title: "Propose how a session ends",
+        description: "Propose an ending for an agent session (exit, complete_then_exit, record_only) with the reason and evidence. A person decides it on the approval page; the decision is recorded, and no pane is closed by the connector.",
+        inputSchema: {
+            session_id: z.string().min(8),
+            ending: z.enum(["exit", "complete_then_exit", "record_only"]),
+            reason: z.string().min(1).max(4000),
+            evidence_refs: refs,
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = personOf(extra);
+        requireContribute(auth);
+        const id = a.session_id.replace(/^session:/, "");
+        const r = append("session_completion_proposal", person, auth, {
+            circle: "continuity",
+            refs: [`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 },
+        });
+        return { ...r, approval_url: approvalUrl(r.id) };
+    }));
+    // ── requests: recorded, approved by a person on the approval page, then run ──
+    server.registerTool("request_authorized_run", {
+        title: "Request a bounded agent run",
+        description: "Ask for an agent session to do one bounded task. The request waits for a person with Miadi's write tier to approve it on the returned approval_url; once approved, a brief is queued for the factory intake, which opens or reaches the session within minutes. Read it back with get_run_result.",
+        inputSchema: {
+            task: z.string().min(1).max(12000).describe("What the session does and what it returns."),
+            circle,
+            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)."),
+            ...base,
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = personOf(extra);
+        requireContribute(auth);
+        const r = append("run_request", person, auth, {
+            circle: a.circle,
+            refs: a.refs,
+            intention: a.intention,
+            role: a.role,
+            idempotency_key: a.idempotency_key,
+            approval_state: "awaiting_approval",
+            state: "pending",
+            body: { task: a.task, session: a.session, cwd: a.cwd },
+        });
+        return { ...r, approval_url: approvalUrl(r.id) };
+    }));
+    server.registerTool("request_review_operation", {
+        title: "Request a review operation",
+        description: "Ask for one review-service operation: create (a review from a YouTube URL), import_markdown (a hand-written version), new_version (regenerate), store_transcript. It waits for a person's approval; check review_lookup first so nothing is duplicated.",
+        inputSchema: {
+            operation: z.enum(["create", "import_markdown", "new_version", "store_transcript"]),
+            review_id: z.string().optional(),
+            video: z.string().optional().describe("YouTube URL, for create and import_markdown."),
+            markdown: z.string().max(400000).optional(),
+            transcript: z.string().max(800000).optional(),
+            refs,
+            ...base,
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = personOf(extra);
+        requireContribute(auth);
+        const reviewId = a.review_id ? reviewIdOf(a.review_id) : null;
+        const video = a.video ? videoIdOf(a.video) : null;
+        if ((a.operation === "new_version" || a.operation === "store_transcript") && !reviewId)
+            throw new ToolRefusal("invalid_request", `${a.operation} needs review_id.`);
+        if ((a.operation === "create" || a.operation === "import_markdown") && !video)
+            throw new ToolRefusal("invalid_request", `${a.operation} needs a YouTube video.`);
+        if (a.operation === "import_markdown" && !a.markdown)
+            throw new ToolRefusal("invalid_request", "import_markdown needs markdown.");
+        if (a.operation === "store_transcript" && !a.transcript)
+            throw new ToolRefusal("invalid_request", "store_transcript needs transcript.");
+        if (a.operation === "create" && video && reviews.canSearch) {
+            const existing = await lookupByVideo(video);
+            if (Array.isArray(existing) && existing.length) {
+                return { state: "review_exists", message: "A review of this video exists; use new_version or import_markdown on it.", reviews: existing };
+            }
+        }
+        const r = append("review_operation_request", person, auth, {
+            circle: "continuity",
+            refs: [...a.refs, ...(reviewId ? [`miadi-review:${reviewId}`] : []), ...(video ? [`https://youtu.be/${video}`] : [])],
+            intention: a.intention,
+            role: a.role,
+            idempotency_key: a.idempotency_key,
+            approval_state: "awaiting_approval",
+            body: { operation: a.operation, review_id: reviewId, video_id: video, markdown: a.markdown, transcript: a.transcript },
+        });
+        return { ...r, body: { ...r.body, markdown: a.markdown ? `${a.markdown.length} chars` : undefined, transcript: a.transcript ? `${a.transcript.length} chars` : undefined }, approval_url: approvalUrl(r.id) };
+    }));
+    server.registerTool("request_deep_diver", {
+        title: "Request Deep Diver for a review version",
+        description: "Ask that one accepted review version be marked ready for Deep Diver. It waits for a person's approval; then the review service records it and its signed webhook queues /deepdive for the Deep Diver owner.",
+        inputSchema: { review_id: z.string().min(8), version: z.number().int().min(1), episode: z.string().optional(), ...base },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = personOf(extra);
+        requireContribute(auth);
+        const id = reviewIdOf(a.review_id);
+        if (!id)
+            throw new ToolRefusal("invalid_ref", "Give a review UUID.");
+        const r0 = await reviews.get(id, a.version);
+        if (!r0)
+            return { state: "not_found", review_id: id, version: a.version };
+        const r = append("deep_diver_request", person, auth, {
+            circle: "continuity",
+            refs: [`miadi-review:${id}`, ...(a.episode ? [`miadi-chronicle://${String(a.episode).replace(/^miadi-chronicle:(\/\/)?/, "")}`] : [])],
+            intention: a.intention,
+            role: a.role,
+            idempotency_key: a.idempotency_key ?? `${id}:v${a.version}`,
+            approval_state: "awaiting_approval",
+            body: { review_id: id, version: a.version, episode: a.episode },
+        });
+        return { ...r, approval_url: approvalUrl(r.id) };
+    }));
+    server.registerTool("link_review_to_episode", {
+        title: "Request that an episode hold a review",
+        description: "Ask that a Chronicle episode hold a review version, through Miadi's episode door (which also relates them on the wheel). An unknown episode stays unassigned: name it. Waits for a person's approval.",
+        inputSchema: {
+            review_id: z.string().min(8),
+            version: z.number().int().min(1),
+            episode: z.string().min(1),
+            relation: z.string().max(80).optional(),
+            ...base,
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = personOf(extra);
+        requireContribute(auth);
+        const id = reviewIdOf(a.review_id);
+        if (!id)
+            throw new ToolRefusal("invalid_ref", "Give a review UUID.");
+        const episode = String(a.episode).replace(/^miadi-chronicle:(\/\/)?/, "");
+        const r = append("review_episode_link_request", person, auth, {
+            circle: "continuity",
+            refs: [`miadi-review:${id}`, `miadi-chronicle://${episode}`],
+            intention: a.intention,
+            role: a.role,
+            idempotency_key: a.idempotency_key ?? `${id}:v${a.version}:${episode}`,
+            approval_state: "awaiting_approval",
+            body: { review_id: id, version: a.version, episode, relation: a.relation },
+        });
+        return { ...r, approval_url: approvalUrl(r.id) };
+    }));
+}
+function asState(e) {
+    if (e instanceof MiadiError)
+        return { state: e.status === 0 ? "unavailable" : e.status === 404 ? "not_found" : `miadi_${e.status}`, body: e.body };
+    return { state: "failed", message: e instanceof Error ? e.message : String(e) };
+}
+function collectBeats(project) {
+    if (!project || typeof project !== "object")
+        return [];
+    const out = [];
+    const walk = (v, depth) => {
+        if (!v || typeof v !== "object" || depth > 8)
+            return;
+        for (const [k, val] of Object.entries(v)) {
+            if (/^story_?beats$/i.test(k) && Array.isArray(val))
+                out.push(...val);
+            else
+                walk(val, depth + 1);
+        }
+    };
+    walk(project, 0);
+    return out;
+}
+function icsDate(d) {
+    return d.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
+}
+function icsText(s) {
+    return s.replace(/\\/g, "\\\\").replace(/;/g, "\\;").replace(/,/g, "\\,").replace(/\r?\n/g, "\\n");
+}
+function ics(uid, title, start, end, agenda, attendees) {
+    return [
+        "BEGIN:VCALENDAR",
+        "VERSION:2.0",
+        "PRODID:-//Miadi//connector//EN",
+        "BEGIN:VEVENT",
+        `UID:${uid.replace(/[^\w-]/g, "")}@miadi`,
+        `DTSTAMP:${icsDate(new Date())}`,
+        `DTSTART:${icsDate(start)}`,
+        `DTEND:${icsDate(end)}`,
+        `SUMMARY:${icsText(title)}`,
+        ...(agenda ? [`DESCRIPTION:${icsText(agenda)}`] : []),
+        ...attendees.filter((x) => x.includes("@")).map((x) => `ATTENDEE:mailto:${x}`),
+        "END:VEVENT",
+        "END:VCALENDAR",
+    ].join("\r\n");
+}
+/** What get_capabilities reports for each tool. */
+export const TOOL_STATUS = {
+    get_capabilities: "live",
+    get_context: "live",
+    list_circles: "live",
+    get_circle: "live",
+    list_sessions: "live, Miadi write tier",
+    get_session: "live, Miadi write tier",
+    get_evidence: "live",
+    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)",
+    review_versions: "live",
+    handoff_status: "live",
+    list_records: "live",
+    get_run_result: "live",
+    search: "live",
+    fetch: "live",
+    append_observation: "live, contribute",
+    open_inquiry: "live, contribute",
+    link_records: "live, contribute",
+    propose_narrative_beat: "live, contribute",
+    record_evaluation: "live, contribute",
+    register_source_intent: "live, contribute",
+    record_handoff: "live, contribute",
+    update_handoff: "live, contribute",
+    propose_work: "live, contribute, needs_approval",
+    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_review_operation: "live, contribute, needs_approval",
+    request_deep_diver: "live, contribute, needs_approval",
+    link_review_to_episode: "live, contribute, needs_approval",
+};