@miadi/connector 0.1.0 → 0.1.2

package/README.md

@@ -21,16 +21,17 @@ Call `get_capabilities` first. It names the signed-in person, their Miadi API ti
 | kind | tools |
 |---|---|
 | reads | `get_capabilities` `get_context` `list_circles` `get_circle` `list_sessions` `get_session` `get_evidence` `get_evaluations` `get_narrative_beats` `review_lookup` `review_versions` `handoff_status` `list_records` `get_run_result` `search` `fetch` |
-| contributions | `append_observation` `open_inquiry` `link_records` `propose_narrative_beat` `record_evaluation` `register_source_intent` `record_handoff` `update_handoff` `prepare_calendar_event` |
-| requests (approved by a person) | `propose_work` `propose_session_completion` `request_authorized_run` `request_review_operation` `request_deep_diver` `link_review_to_episode` |
+| contributions | `append_observation` `open_inquiry` `link_records` `propose_narrative_beat` `record_evaluation` `register_source_intent` `record_handoff` `update_handoff` `prepare_calendar_event` `save_research` |
+| requests (approved by a person) | `propose_work` `propose_session_completion` `request_authorized_run` `request_review_operation` `request_deep_diver` `link_review_to_episode` `request_inquiry_episode` |
 
 - **Reads** stay within the person's Miadi tier. Sessions need the write tier, because a session's name and pane are operator data.
-- **Contributions** need the `miadi:contribute` scope, chosen at sign-in. They append a record to the ledger and change nothing else.
+- **Contributions** need the `miadi:contribute` scope, chosen at sign-in. They append a record to the ledger and change nothing else, except `save_research`: it saves a report on the inquiry shelf as a new folder (the Markdown exactly as given, owner and visibility recorded, private by default), opens the folder's inquiry issue, and commits and pushes the folder in the shelf's repository.
 - **Requests** append a record that waits for approval. The answer gives an `approval_url`. A person with Miadi's write tier opens it in a browser, signs in, and approves or declines. Only that page runs the request, once, as that person:
   - a run becomes a brief in the factory queue, which the intake delivers to a session;
   - a review operation calls the review service;
   - Deep Diver marks the review version ready;
   - an episode link goes through Miadi's episode door;
+  - an inquiry is woven into an episode through its inquiry door, or a new episode is minted with it;
   - a session ending is recorded, and no pane is closed.
 
 The model that asked cannot approve its own request.
@@ -53,6 +54,8 @@ MIADI_CONNECTOR_PUBLIC_URL=https://mcp.sanctuaireagentique.com node packages/con
 | `MIADI_REVIEW_BASE_URL` | `https://miadi-review-service.vercel.app` | the review service |
 | `MIADI_REVIEW_TOKEN` | read from `~/.env` | review search and approved review operations |
 | `MIADI_FACTORY_DIR` | `~/.miadi/factory` | the queue approved runs are written to |
+| `MIADI_INQUIRY_DIR` | `/a/src/IAIP/prototypes/artefacts` | the inquiry shelf `save_research` writes to, inside a git checkout it pushes |
+| `MIADI_INQUIRY_GITHUB_REPO` | `miadisabelle/Etuaptmumk-RSM` | where a saved report's inquiry issue is opened, with the host's `gh` login |
 
 On gaia it runs as the user service `miadi-connector.service`, and the Cloudflare tunnel `gaia` routes `mcp.sanctuaireagentique.com` to it.
 

package/dist/approve.d.ts

@@ -1,7 +1,7 @@
 /**
  * The approval door. A request made through the connector (a run, a review
- * operation, Deep Diver, a review-to-episode link, a work proposal, a session
- * ending) waits here until a person with Miadi's write tier opens
+ * operation, Deep Diver, a review-to-episode link, an inquiry-to-episode weave,
+ * a work proposal, a session ending) waits here until a person with Miadi's write tier opens
  * /approve/<record id>, signs in with their Miadi person token and approves or
  * declines it. The model that asked cannot approve: the page is a browser form
  * outside the MCP channel.

package/dist/approve.js

@@ -1,7 +1,7 @@
 /**
  * The approval door. A request made through the connector (a run, a review
- * operation, Deep Diver, a review-to-episode link, a work proposal, a session
- * ending) waits here until a person with Miadi's write tier opens
+ * operation, Deep Diver, a review-to-episode link, an inquiry-to-episode weave,
+ * a work proposal, a session ending) waits here until a person with Miadi's write tier opens
  * /approve/<record id>, signs in with their Miadi person token and approves or
  * declines it. The model that asked cannot approve: the page is a browser form
  * outside the MCP channel.
@@ -24,6 +24,7 @@ const APPROVABLE = new Set([
     "review_episode_link_request",
     "work_proposal",
     "session_completion_proposal",
+    "inquiry_episode_request",
 ]);
 export function factoryDir(env = process.env) {
     return env.MIADI_FACTORY_DIR || join(homedir(), ".miadi", "factory");
@@ -158,6 +159,27 @@ export async function executeApproved(record, approver, deps) {
                 throw e;
             }
         }
+        case "inquiry_episode_request": {
+            // A new episode is minted with the inquiry woven in one call; an existing one goes through its inquiry door.
+            const inquiry = { artefact: b.artefact, ...(b.issue ? { issue: b.issue } : {}) };
+            try {
+                if (b.new_episode) {
+                    const res = await deps.miadi.request(approver.token, "POST", "/api/chronicle/episodes", {
+                        title: b.new_episode.title,
+                        ...(b.new_episode.goal ? { goal: b.new_episode.goal } : {}),
+                        inquiry,
+                    });
+                    return { outcome: "minted_and_woven", response: res };
+                }
+                const res = await deps.miadi.request(approver.token, "POST", `/api/chronicle/episodes/${encodeURIComponent(b.episode)}/inquiry`, inquiry);
+                return { outcome: "woven", response: res };
+            }
+            catch (e) {
+                if (e instanceof MiadiError)
+                    return { outcome: "failed", status: e.status, response: e.body };
+                throw e;
+            }
+        }
         case "work_proposal":
             return { outcome: "approved", note: "The proposal is approved; a run starts only through request_authorized_run." };
         case "session_completion_proposal":

package/dist/config.d.ts

@@ -10,5 +10,9 @@ export interface ConnectorConfig {
     reviewUrl: string;
     reviewToken?: string;
     stateDir: string;
+    /** The inquiry shelf research reports are saved on (MIADI_INQUIRY_DIR). */
+    inquiryRoot?: string;
+    /** owner/repo a saved report's inquiry issue is opened in (MIADI_INQUIRY_GITHUB_REPO). */
+    inquiryRepo?: string;
 }
 export declare function configFromEnv(env?: NodeJS.ProcessEnv): ConnectorConfig;

package/dist/config.js

@@ -1,6 +1,8 @@
+import { resolveEnv } from "@miadi/inquiry-weave";
 import { reviewToken } from "./reviews.js";
 export function configFromEnv(env = process.env) {
     const port = Number(env.MIADI_CONNECTOR_PORT || 3337);
+    const shelf = resolveEnv({}, env);
     return {
         publicUrl: (env.MIADI_CONNECTOR_PUBLIC_URL || `http://127.0.0.1:${port}`).replace(/\/$/, ""),
         host: env.MIADI_CONNECTOR_HOST || "127.0.0.1",
@@ -10,5 +12,7 @@ export function configFromEnv(env = process.env) {
         reviewUrl: (env.MIADI_REVIEW_BASE_URL || "https://miadi-review-service.vercel.app").replace(/\/$/, ""),
         reviewToken: reviewToken(env),
         stateDir: env.MIADI_CONNECTOR_STATE_DIR || "/srv/miadi/connector",
+        inquiryRoot: shelf.inquiryRoot,
+        inquiryRepo: shelf.repo,
     };
 }

package/dist/oauth.d.ts

@@ -60,9 +60,21 @@ export declare const emptyOAuthState: () => OAuthState;
 export declare class MiadiOAuthProvider implements OAuthServerProvider {
     private readonly state;
     private readonly identify;
+    /**
+     * The issuer as the metadata states it. It goes back on every authorization
+     * response as `iss` (RFC 9207), which ChatGPT requires to use its stable
+     * callback URL.
+     */
+    private readonly issuer?;
     private readonly confirmPath;
     private readonly direct;
-    constructor(state: JsonFile<OAuthState>, identify: Identify, confirmPath?: string);
+    constructor(state: JsonFile<OAuthState>, identify: Identify, 
+    /**
+     * The issuer as the metadata states it. It goes back on every authorization
+     * response as `iss` (RFC 9207), which ChatGPT requires to use its stable
+     * callback URL.
+     */
+    issuer?: string | undefined, confirmPath?: string);
     get clientsStore(): OAuthRegisteredClientsStore;
     authorize(client: OAuthClientInformationFull, params: AuthorizationParams, res: Response): Promise<void>;
     /** POST from the sign-in page: the person's token, or a refusal. */

package/dist/oauth.js

@@ -14,11 +14,19 @@ const now = () => Math.floor(Date.now() / 1000);
 export class MiadiOAuthProvider {
     state;
     identify;
+    issuer;
     confirmPath;
     direct = new Map();
-    constructor(state, identify, confirmPath = "/authorize/confirm") {
+    constructor(state, identify, 
+    /**
+     * The issuer as the metadata states it. It goes back on every authorization
+     * response as `iss` (RFC 9207), which ChatGPT requires to use its stable
+     * callback URL.
+     */
+    issuer, confirmPath = "/authorize/confirm") {
         this.state = state;
         this.identify = identify;
+        this.issuer = issuer;
         this.confirmPath = confirmPath;
     }
     get clientsStore() {
@@ -68,6 +76,8 @@ export class MiadiOAuthProvider {
         const redirect = new URL(pending.params.redirectUri);
         if (pending.params.state)
             redirect.searchParams.set("state", pending.params.state);
+        if (this.issuer)
+            redirect.searchParams.set("iss", this.issuer);
         if (body.decision === "deny") {
             this.state.update((st) => delete st.pending[body.request_id]);
             redirect.searchParams.set("error", "access_denied");

package/dist/records.d.ts

@@ -35,7 +35,7 @@ export declare const DOMAINS: readonly ["creative", "ceremonial", "engineering"]
 /** #815 "claim category": what kind of statement a record makes. */
 export declare const CLAIM_CATEGORIES: readonly ["observed", "hypothesis", "desired_future", "fiction", "verified_implementation"];
 export type ClaimCategory = (typeof CLAIM_CATEGORIES)[number];
-export declare const RECORD_KINDS: readonly ["observation", "inquiry", "link", "work_proposal", "run_request", "handoff", "source_intent", "review_operation_request", "deep_diver_request", "review_episode_link_request", "calendar_event_draft", "session_completion_proposal"];
+export declare const RECORD_KINDS: readonly ["observation", "inquiry", "link", "work_proposal", "run_request", "handoff", "source_intent", "review_operation_request", "deep_diver_request", "review_episode_link_request", "calendar_event_draft", "session_completion_proposal", "research_artifact", "inquiry_episode_request"];
 export type RecordKind = (typeof RECORD_KINDS)[number];
 /** #816 handoff states. */
 export declare const HANDOFF_STATES: readonly ["pending", "blocked", "ready", "in_progress", "completed", "withdrawn"];

package/dist/records.js

@@ -58,6 +58,8 @@ export const RECORD_KINDS = [
     "review_episode_link_request",
     "calendar_event_draft",
     "session_completion_proposal",
+    "research_artifact",
+    "inquiry_episode_request",
 ];
 /** #816 handoff states. */
 export const HANDOFF_STATES = ["pending", "blocked", "ready", "in_progress", "completed", "withdrawn"];

package/dist/server.js

@@ -12,7 +12,7 @@
 import express from "express";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { mcpAuthRouter, getOAuthProtectedResourceMetadataUrl } from "@modelcontextprotocol/sdk/server/auth/router.js";
+import { mcpAuthRouter, createOAuthMetadata, getOAuthProtectedResourceMetadataUrl } from "@modelcontextprotocol/sdk/server/auth/router.js";
 import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
 import { MiadiOAuthProvider, SCOPES, emptyOAuthState } from "./oauth.js";
 import { registerApprovalRoutes } from "./approve.js";
@@ -26,7 +26,9 @@ export function createConnectorApp(config, deps) {
     const paths = statePaths(config.stateDir);
     const oauthState = new JsonFile(paths.oauth, emptyOAuthState);
     const ledger = new Ledger(paths.ledger);
-    const provider = new MiadiOAuthProvider(oauthState, deps.identify);
+    // The issuer string exactly as the metadata states it (URL.href, so with its trailing slash).
+    const issuer = new URL(config.publicUrl).href;
+    const provider = new MiadiOAuthProvider(oauthState, deps.identify, issuer);
     const miadi = new MiadiClient(config.miadiUrl, deps.fetchImpl);
     const reviews = new ReviewClient(config.reviewUrl, config.reviewToken, deps.fetchImpl);
     const publicUrl = new URL(config.publicUrl);
@@ -38,6 +40,21 @@ export function createConnectorApp(config, deps) {
     app.get("/health", (_req, res) => {
         res.json({ ok: true, service: "@miadi/connector", version: VERSION });
     });
+    // The SDK's metadata, plus RFC 9207: authorization responses carry `iss`.
+    // Served before the SDK router so this document is the one clients read.
+    const asMetadata = {
+        ...createOAuthMetadata({
+            provider,
+            issuerUrl: publicUrl,
+            baseUrl: publicUrl,
+            scopesSupported: SCOPES,
+            serviceDocumentationUrl: new URL("https://github.com/jgwill/Miadi/tree/main/packages/connector"),
+        }),
+        authorization_response_iss_parameter_supported: true,
+    };
+    app.get("/.well-known/oauth-authorization-server", (_req, res) => {
+        res.set("cache-control", "no-store").json(asMetadata);
+    });
     app.use(mcpAuthRouter({
         provider,
         issuerUrl: publicUrl,

package/dist/tools.js

@@ -17,6 +17,8 @@ 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";
+import { join } from "node:path";
+import { artefactVisibility, readArtefactWeave, saveResearchArtefact } from "@miadi/inquiry-weave";
 class ToolRefusal extends Error {
     code;
     detail;
@@ -872,6 +874,106 @@ export function registerTools(server, ctx) {
         });
         return { ...r, approval_url: approvalUrl(r.id) };
     }));
+    // ── research on the inquiry shelf (jgwill/Miadi#879) ───────────────────
+    server.registerTool("save_research", {
+        title: "Save a research report on the inquiry shelf",
+        description: "Save a finished research report (for example a Deep Research export) in your name: a new folder on Miadi's inquiry shelf holding the Markdown exactly as given, its inquiry issue, and the folder committed and pushed in the shelf's repository. Private to you unless shared with a circle; publishing goes through the public-inquiry route, never here. The same report saved again returns the folder already saved. Weave it into an episode afterwards with request_inquiry_episode.",
+        inputSchema: {
+            title: z.string().min(1).max(200),
+            markdown: z.string().min(1).max(1_000_000).describe("The whole report, as Markdown. Saved byte-for-byte."),
+            refs: refs.describe("Records and sources the report answers: a connector inquiry id, a DOI or URL, owner/repo#n."),
+            visibility: z.enum(["private", "circle"]).default("private"),
+            circle: circle.optional().describe("The circle it is shared with, when visibility is circle."),
+            ...base,
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = personOf(extra);
+        requireContribute(auth);
+        if (!config.inquiryRoot || !config.inquiryRepo)
+            throw new ToolRefusal("unavailable", "This connector host has no inquiry shelf configured.");
+        if (a.visibility === "circle" && !a.circle)
+            throw new ToolRefusal("invalid_input", "Name the circle the report is shared with.");
+        const saved = await saveResearchArtefact({
+            inquiryRoot: config.inquiryRoot,
+            repo: config.inquiryRepo,
+            title: a.title,
+            markdown: a.markdown,
+            owner: { person_id: person.id, name: person.name },
+            visibility: a.visibility,
+            circle: a.circle,
+            via: "miadi-connector",
+            refs: a.refs,
+        });
+        const r = append("research_artifact", person, auth, {
+            circle: a.circle ?? "stewardship",
+            refs: [`inquiry-artefact:${saved.artefact}`, ...(saved.issue ? [saved.issue] : []), ...a.refs],
+            intention: a.intention,
+            role: a.role,
+            idempotency_key: a.idempotency_key ?? `research:${saved.sha256}`,
+            claim_category: "observed",
+            state: saved.shelf.state === "landed" ? "completed" : "blocked",
+            next_action: "request_inquiry_episode to weave it into an episode or start one",
+            body: {
+                title: a.title,
+                artefact: saved.artefact,
+                issue: saved.issue,
+                issue_url: saved.issue_url,
+                sha256: saved.sha256,
+                bytes: saved.bytes,
+                visibility: saved.visibility,
+                circle: a.circle,
+                shelf: { state: saved.shelf.state, observed: saved.shelf.observed },
+            },
+        });
+        return { ...r, saved: saved.status, research_url: `${config.miadiPublicUrl}/research` };
+    }));
+    server.registerTool("request_inquiry_episode", {
+        title: "Request that an inquiry be woven into an episode, or start one",
+        description: "Ask that a folder on the inquiry shelf (from save_research) be woven into a Chronicle episode, or that a new episode be started from it. Weaving copies the folder into the episode, so the approval page shows its visibility. Waits for a person's approval; on approval it runs once through Miadi's episode doors.",
+        inputSchema: {
+            artefact: z.string().min(1).max(300).describe("The shelf folder name save_research returned."),
+            episode: z.string().min(1).optional().describe("An existing episode: miadi-chronicle://<n>, a number or a folder."),
+            new_episode_title: z.string().min(1).max(200).optional().describe("Start a new episode with this title instead."),
+            goal: z.string().max(2000).optional().describe("The new episode's goal."),
+            ...base,
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = personOf(extra);
+        requireContribute(auth);
+        if (Boolean(a.episode) === Boolean(a.new_episode_title)) {
+            throw new ToolRefusal("invalid_input", "Name either an existing episode or a new episode title, not both.");
+        }
+        if (!config.inquiryRoot)
+            throw new ToolRefusal("unavailable", "This connector host has no inquiry shelf configured.");
+        const name = String(a.artefact).trim();
+        if (!/^[\w.-]+$/.test(name))
+            throw new ToolRefusal("invalid_ref", "Give the bare shelf folder name.");
+        const weave = await readArtefactWeave(join(config.inquiryRoot, name)).catch(() => undefined);
+        if (!weave)
+            throw new ToolRefusal("not_found", `No folder ${name} on the inquiry shelf.`);
+        if (weave.owner && weave.owner.person_id !== person.id && person.api_tier !== "write") {
+            throw new ToolRefusal("forbidden", "That folder belongs to another person.");
+        }
+        const episode = a.episode ? String(a.episode).replace(/^miadi-chronicle:(\/\/)?/, "").trim() : undefined;
+        const r = append("inquiry_episode_request", person, auth, {
+            circle: "continuity",
+            refs: [`inquiry-artefact:${name}`, ...(weave.issue ? [weave.issue] : []), ...(episode ? [`miadi-chronicle://${episode}`] : [])],
+            intention: a.intention,
+            role: a.role,
+            idempotency_key: a.idempotency_key ?? `${name}:${episode ?? `new:${a.new_episode_title}`}`,
+            approval_state: "awaiting_approval",
+            body: {
+                artefact: name,
+                issue: weave.issue,
+                visibility: artefactVisibility(weave),
+                owner: weave.owner?.name ?? weave.owner?.person_id ?? "no owner recorded",
+                ...(episode ? { episode } : { new_episode: { title: a.new_episode_title, ...(a.goal ? { goal: a.goal } : {}) } }),
+            },
+        });
+        return { ...r, approval_url: approvalUrl(r.id) };
+    }));
 }
 function asState(e) {
     if (e instanceof MiadiError)
@@ -951,4 +1053,6 @@ export const TOOL_STATUS = {
     request_review_operation: "live, contribute, needs_approval",
     request_deep_diver: "live, contribute, needs_approval",
     link_review_to_episode: "live, contribute, needs_approval",
+    save_research: "live, contribute (saves on the inquiry shelf, opens its issue, pushes; private by default)",
+    request_inquiry_episode: "live, contribute, needs_approval (weaves a shelf folder into an episode or starts one)",
 };

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.1.2";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.1.0";
+export const VERSION = "0.1.2";

package/package.json

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