@miadi/connector 0.1.2 → 0.1.4

package/README.md

@@ -25,9 +25,10 @@ Call `get_capabilities` first. It names the signed-in person, their Miadi API ti
 | 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, 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:
+- **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. A long report is sent in parts (`part`, `parts`, `upload_id`) and saved when the last part arrives; the answer returns its bytes, sha256 and first and last lines.
+- **Requests** append a record that waits for a decision. The answer gives an `approval_url`; Miadi's `/research` page offers the same decisions to a signed-in person with the write tier. The person approves, approves with changes (their instructions are carried into what runs), sends it back for revision with instructions (`revision_requested`, nothing runs, `get_run_result` returns the instructions), or declines. Only the approval door runs a request, once, as that person:
   - a run becomes a brief in the factory queue, which the intake delivers to a session;
+  - a work proposal starts its work the same way, as a brief written from the proposal;
   - a review operation calls the review service;
   - Deep Diver marks the review version ready;
   - an episode link goes through Miadi's episode door;

package/dist/approve.d.ts

@@ -25,6 +25,13 @@ export interface ApprovalDeps {
     factoryDir?: string;
     tmuxSessions?: () => string[];
 }
+/**
+ * What a person may decide on a request. Approving with changes runs it with the
+ * approver's instructions carried into what runs; a revision sends it back to
+ * whoever asked, with instructions, and runs nothing.
+ */
+export declare const DECISIONS: readonly ["approve", "approve_with_changes", "request_revision", "decline"];
+export type Decision = (typeof DECISIONS)[number];
 export declare function factoryDir(env?: NodeJS.ProcessEnv): string;
 export declare function runBriefFile(record: {
     id: string;
@@ -39,9 +46,11 @@ export declare function readQueueState(record: ConnectorRecord, dir?: string): {
     file: string;
     note: string;
 };
-export declare function runBrief(record: ConnectorRecord, approver: MiadiPerson, sessions: string[]): {
+/** The task a work proposal asks for, written from the proposal's own fields. */
+export declare function proposalTask(record: ConnectorRecord): string;
+export declare function runBrief(record: ConnectorRecord, approver: MiadiPerson, sessions: string[], instructions?: string): {
     to: string;
     brief: string;
 };
-export declare function executeApproved(record: ConnectorRecord, approver: MiadiPerson, deps: ApprovalDeps): Promise<Record<string, unknown>>;
+export declare function executeApproved(record: ConnectorRecord, approver: MiadiPerson, deps: ApprovalDeps, instructions?: string): Promise<Record<string, unknown>>;
 export declare function registerApprovalRoutes(app: Express, deps: ApprovalDeps): void;

package/dist/approve.js

@@ -26,6 +26,12 @@ const APPROVABLE = new Set([
     "session_completion_proposal",
     "inquiry_episode_request",
 ]);
+/**
+ * What a person may decide on a request. Approving with changes runs it with the
+ * approver's instructions carried into what runs; a revision sends it back to
+ * whoever asked, with instructions, and runs nothing.
+ */
+export const DECISIONS = ["approve", "approve_with_changes", "request_revision", "decline"];
 export function factoryDir(env = process.env) {
     return env.MIADI_FACTORY_DIR || join(homedir(), ".miadi", "factory");
 }
@@ -63,8 +69,19 @@ function yymmdd(d = new Date()) {
 function attr(v) {
     return v.replace(/["<>\n]/g, " ");
 }
-export function runBrief(record, approver, sessions) {
-    const body = record.body;
+/** The task a work proposal asks for, written from the proposal's own fields. */
+export function proposalTask(record) {
+    const b = record.body;
+    const lines = ["Carry out this approved work proposal, within its own scope and constraints.", ""];
+    for (const [k, v] of Object.entries(b)) {
+        if (v === undefined || v === null || v === "")
+            continue;
+        lines.push(`${k.replace(/_/g, " ")}: ${typeof v === "string" ? v : JSON.stringify(v)}`);
+    }
+    return lines.join("\n");
+}
+export function runBrief(record, approver, sessions, instructions) {
+    const body = (record.kind === "work_proposal" ? { task: proposalTask(record) } : record.body);
     const short = record.id.split(":")[1]?.slice(0, 8) ?? "run";
     const to = body.session && sessions.includes(body.session) ? body.session : `new:${body.session ?? `connector-${yymmdd()}-${short}`}`;
     const cwd = body.cwd || "/a/src/Miadi-18";
@@ -86,6 +103,16 @@ export function runBrief(record, approver, sessions) {
         // The intake reads one <input> block per file: a closing tag inside the task would end it early.
         body.task.replace(/<\/?(input|task)\b/gi, (m) => m.replace("<", "‹")),
         "</task>",
+        ...(instructions
+            ? [
+                "",
+                `${approver.name} approved it with these instructions. Where they differ from the task, they win:`,
+                "",
+                "<instructions>",
+                instructions.replace(/<\/?(input|task|instructions)\b/gi, (m) => m.replace("<", "‹")),
+                "</instructions>",
+            ]
+            : []),
         "",
         "When it is done, reply with what was achieved, the evidence (commits, paths, URLs), what is still open, and whether this session should end. Then record the receipt through the connector's update_handoff if a handoff names this record, and end the session per its lifecycle.",
         "",
@@ -98,7 +125,7 @@ function plainName(name) {
     const n = name.replace(/[^\w .'-]/g, "").trim().slice(0, 40);
     return /^[^\W_]/.test(n) ? n : "Miadi connector";
 }
-export async function executeApproved(record, approver, deps) {
+export async function executeApproved(record, approver, deps, instructions) {
     const f = deps.fetchImpl ?? fetch;
     const b = record.body;
     const reviewCall = async (method, path, payload) => {
@@ -120,15 +147,17 @@ export async function executeApproved(record, approver, deps) {
         }
         return { status: res.status, ok: res.ok, response: parsed };
     };
+    const queueBrief = () => {
+        const queue = join(deps.factoryDir ?? factoryDir(), "queue");
+        mkdirSync(queue, { recursive: true });
+        const { to, brief } = runBrief(record, approver, (deps.tmuxSessions ?? liveTmux)(), instructions);
+        const file = runBriefFile(record);
+        writeFileSync(join(queue, file), brief, { flag: "wx", mode: 0o640 });
+        return { outcome: "queued", to, file, note: "The factory intake delivers queued briefs every 5 minutes." };
+    };
     switch (record.kind) {
-        case "run_request": {
-            const queue = join(deps.factoryDir ?? factoryDir(), "queue");
-            mkdirSync(queue, { recursive: true });
-            const { to, brief } = runBrief(record, approver, (deps.tmuxSessions ?? liveTmux)());
-            const file = runBriefFile(record);
-            writeFileSync(join(queue, file), brief, { flag: "wx", mode: 0o640 });
-            return { outcome: "queued", to, file, note: "The factory intake delivers queued briefs every 5 minutes." };
-        }
+        case "run_request":
+            return queueBrief();
         case "review_operation_request": {
             const url = b.video_id ? `https://youtu.be/${b.video_id}` : undefined;
             const r = b.operation === "create"
@@ -181,7 +210,8 @@ export async function executeApproved(record, approver, deps) {
             }
         }
         case "work_proposal":
-            return { outcome: "approved", note: "The proposal is approved; a run starts only through request_authorized_run." };
+            // Approving a proposal starts its work: a factory brief written from the proposal and the approver's instructions.
+            return queueBrief();
         case "session_completion_proposal":
             return {
                 outcome: "decided",
@@ -233,7 +263,7 @@ ${r.refs.length ? `<dt>References</dt><dd>${r.refs.map(escapeHtml).join("<br>")}
 }
 export function registerApprovalRoutes(app, deps) {
     const find = (id) => current(deps.ledger.all()).find((r) => r.id === id);
-    const form = express.urlencoded({ extended: false, limit: "16kb" });
+    const form = express.urlencoded({ extended: false, limit: "128kb" });
     app.get("/approve/:id", (req, res) => {
         const r = find(String(req.params.id));
         if (!r || !APPROVABLE.has(r.kind)) {
@@ -262,12 +292,24 @@ export function registerApprovalRoutes(app, deps) {
             res.status(403).type("html").send(approvePage(r, `Approving needs Miadi's write tier; ${person.name} has ${person.api_tier ?? "no API tier"}.`));
             return;
         }
-        const decision = body.decision === "approve" ? "approved" : "declined";
-        let receipt = { decided_by: { person_id: person.id, name: person.name }, decided_at: new Date().toISOString(), note: body.note || undefined };
-        let state = decision === "approved" ? "completed" : "withdrawn";
+        const choice = DECISIONS.includes(String(body.decision)) ? body.decision : "decline";
+        const instructions = String(body.instructions ?? "").trim().slice(0, 20000) || undefined;
+        if ((choice === "approve_with_changes" || choice === "request_revision") && !instructions) {
+            res.status(400).type("html").send(approvePage(r, choice === "request_revision" ? "Say what to revise." : "Write the changes to apply."));
+            return;
+        }
+        const decision = choice === "approve" || choice === "approve_with_changes" ? "approved" : choice === "request_revision" ? "revision_requested" : "declined";
+        let receipt = {
+            decided_by: { person_id: person.id, name: person.name },
+            decided_at: new Date().toISOString(),
+            decision: choice,
+            ...(instructions ? { instructions } : {}),
+            note: body.note || undefined,
+        };
+        let state = decision === "approved" ? "completed" : decision === "revision_requested" ? "pending" : "withdrawn";
         if (decision === "approved") {
             try {
-                const outcome = await executeApproved(r, person, deps);
+                const outcome = await executeApproved(r, person, deps, instructions);
                 receipt = { ...receipt, ...outcome };
                 if (outcome.outcome === "failed")
                     state = "blocked";
@@ -283,16 +325,17 @@ export function registerApprovalRoutes(app, deps) {
             id: newRecordId(r.kind),
             kind: r.kind,
             created_at: new Date().toISOString(),
-            actor: { person_id: person.id, name: person.name, client_id: "approval-page" },
+            actor: { person_id: person.id, name: person.name, client_id: String(body.via ?? "approval-page").slice(0, 60) },
             refs: r.refs,
             evidence_refs: [],
             supersedes: r.id,
             approval_state: decision,
             state,
+            ...(decision === "revision_requested" ? { next_action: `Revise and submit a new request that cites ${r.id} in refs.` } : {}),
             completion_receipt: receipt,
-            body: { decision },
+            body: { decision: choice, ...(instructions ? { instructions } : {}) },
         });
-        res.type("html").send(page("Recorded", `<h1>${decision === "approved" ? "Approved" : "Declined"}</h1>${summary(find(r.id))}<pre>${escapeHtml(JSON.stringify(receipt, null, 2))}</pre>`));
+        res.type("html").send(page("Recorded", `<h1>${decision === "approved" ? "Approved" : decision === "revision_requested" ? "Sent back for revision" : "Declined"}</h1>${summary(find(r.id))}<pre>${escapeHtml(JSON.stringify(receipt, null, 2))}</pre>`));
     });
     // A record's own page, for citations in ChatGPT: any person Miadi recognises may read it.
     app.get("/records/:id", (req, res) => {
@@ -328,10 +371,12 @@ ${r.approval_state === "awaiting_approval"
         ? `<form method="post">
 <label for="t">Your Miadi person token (write tier)</label>
 <input id="t" name="person_token" type="password" autocomplete="off" required>
-<label for="n">Note (optional)</label>
-<textarea id="n" name="note" rows="2"></textarea>
+<label for="i">Instructions (needed to approve with changes or to send back)</label>
+<textarea id="i" name="instructions" rows="4"></textarea>
 <div class="row">
 <button class="primary" type="submit" name="decision" value="approve">Approve and run</button>
+<button type="submit" name="decision" value="approve_with_changes">Approve with my changes</button>
+<button type="submit" name="decision" value="request_revision">Send back for revision</button>
 <button type="submit" name="decision" value="decline">Decline</button>
 </div></form>`
         : ""}`);

package/dist/records.d.ts

@@ -40,8 +40,12 @@ export type RecordKind = (typeof RECORD_KINDS)[number];
 /** #816 handoff states. */
 export declare const HANDOFF_STATES: readonly ["pending", "blocked", "ready", "in_progress", "completed", "withdrawn"];
 export type HandoffState = (typeof HANDOFF_STATES)[number];
-/** Approval of a request that a person must grant before anything runs. */
-export declare const APPROVAL_STATES: readonly ["awaiting_approval", "approved", "declined", "not_required"];
+/**
+ * Approval of a request that a person must grant before anything runs.
+ * `revision_requested`: sent back to whoever asked, with the approver's
+ * instructions in the receipt; nothing of it ran.
+ */
+export declare const APPROVAL_STATES: readonly ["awaiting_approval", "approved", "declined", "revision_requested", "not_required"];
 export type ApprovalState = (typeof APPROVAL_STATES)[number];
 export interface Actor {
     person_id: string;

package/dist/records.js

@@ -63,8 +63,12 @@ export const RECORD_KINDS = [
 ];
 /** #816 handoff states. */
 export const HANDOFF_STATES = ["pending", "blocked", "ready", "in_progress", "completed", "withdrawn"];
-/** Approval of a request that a person must grant before anything runs. */
-export const APPROVAL_STATES = ["awaiting_approval", "approved", "declined", "not_required"];
+/**
+ * Approval of a request that a person must grant before anything runs.
+ * `revision_requested`: sent back to whoever asked, with the approver's
+ * instructions in the receipt; nothing of it ran.
+ */
+export const APPROVAL_STATES = ["awaiting_approval", "approved", "declined", "revision_requested", "not_required"];
 export function newRecordId(kind) {
     return `${kind}:${randomUUID()}`;
 }

package/dist/server.d.ts

@@ -15,4 +15,4 @@ export declare function createConnectorApp(config: ConnectorConfig, deps: Connec
     provider: MiadiOAuthProvider;
     ledger: Ledger<ConnectorRecord>;
 };
-export declare const INSTRUCTIONS = "Miadi is a relational software factory: agent sessions, Miadi reviews of screenwalks, Chronicle episodes, talking circles and the five accountable circles (Story, Stewardship, Engineering, Evaluation, Continuity) across three domains (Creative, Ceremonial, Engineering).\n\nStart with get_capabilities: it says who you are signed in as, which tools are live, and which return not_implemented.\n\nRules every tool keeps:\n- Every record names the person who made it, with a claim category: observed, hypothesis, desired_future, fiction or verified_implementation. Keep fiction and desired futures apart from what was observed.\n- Requests (runs, review operations, Deep Diver, review-to-episode links, session completion, calendar events) are recorded as awaiting_approval. Nothing runs, publishes or closes until a person approves it in Miadi.\n- An unknown id is answered as not found, never invented. A missing backing service is answered as unavailable.\n- Use the miadi-review:<uuid>, miadi-chronicle://<n>, owner/repo#n and session:<uuid> reference forms.";
+export declare const INSTRUCTIONS = "Miadi is a relational software factory: agent sessions, Miadi reviews of screenwalks, Chronicle episodes, talking circles and the five accountable circles (Story, Stewardship, Engineering, Evaluation, Continuity) across three domains (Creative, Ceremonial, Engineering).\n\nStart with get_capabilities: it says who you are signed in as, which tools are live, and which return not_implemented.\n\nRules every tool keeps:\n- Every record names the person who made it, with a claim category: observed, hypothesis, desired_future, fiction or verified_implementation. Keep fiction and desired futures apart from what was observed.\n- Requests (runs, work proposals, review operations, Deep Diver, review-to-episode links, inquiry-to-episode weaves, session completion) are recorded as awaiting_approval. Nothing runs, publishes or closes until a person decides in Miadi. The person may approve, approve with changes (their instructions are carried into what runs), send it back for revision with instructions (approval_state revision_requested; read the instructions with get_run_result and submit a revised request citing the old id in refs), or decline.\n- A research report (a Deep Research report) is delivered with save_research exactly as written, never summarised or shortened, with its sources; a long report goes in parts. Check the bytes and first and last lines the answer returns against what you sent.\n- An unknown id is answered as not found, never invented. A missing backing service is answered as unavailable.\n- Use the miadi-review:<uuid>, miadi-chronicle://<n>, owner/repo#n and session:<uuid> reference forms.";

package/dist/server.js

@@ -116,6 +116,7 @@ Start with get_capabilities: it says who you are signed in as, which tools are l
 
 Rules every tool keeps:
 - Every record names the person who made it, with a claim category: observed, hypothesis, desired_future, fiction or verified_implementation. Keep fiction and desired futures apart from what was observed.
-- Requests (runs, review operations, Deep Diver, review-to-episode links, session completion, calendar events) are recorded as awaiting_approval. Nothing runs, publishes or closes until a person approves it in Miadi.
+- Requests (runs, work proposals, review operations, Deep Diver, review-to-episode links, inquiry-to-episode weaves, session completion) are recorded as awaiting_approval. Nothing runs, publishes or closes until a person decides in Miadi. The person may approve, approve with changes (their instructions are carried into what runs), send it back for revision with instructions (approval_state revision_requested; read the instructions with get_run_result and submit a revised request citing the old id in refs), or decline.
+- A research report (a Deep Research report) is delivered with save_research exactly as written, never summarised or shortened, with its sources; a long report goes in parts. Check the bytes and first and last lines the answer returns against what you sent.
 - An unknown id is answered as not found, never invented. A missing backing service is answered as unavailable.
 - Use the miadi-review:<uuid>, miadi-chronicle://<n>, owner/repo#n and session:<uuid> reference forms.`;

package/dist/tools.js

@@ -19,6 +19,7 @@ import { VERSION } from "./version.js";
 import { readQueueState } from "./approve.js";
 import { join } from "node:path";
 import { artefactVisibility, readArtefactWeave, saveResearchArtefact } from "@miadi/inquiry-weave";
+import { ResearchUploads, UploadRefusal } from "./uploads.js";
 class ToolRefusal extends Error {
     code;
     detail;
@@ -56,6 +57,8 @@ function wrap(fn) {
         catch (error) {
             if (error instanceof ToolRefusal)
                 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 MiadiError) {
                 const unavailable = error.status === 0;
                 return fail({
@@ -102,6 +105,7 @@ export function registerTools(server, ctx) {
         });
     };
     const records = () => current(ledger.all());
+    const uploads = new ResearchUploads(join(config.stateDir, "uploads"));
     const touching = (ref) => records().filter((r) => r.refs.includes(ref) || r.evidence_refs.includes(ref) || r.id === ref);
     // ── reads ──────────────────────────────────────────────────────────────
     server.registerTool("get_capabilities", {
@@ -404,7 +408,7 @@ export function registerTools(server, ctx) {
     }));
     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.",
+        description: "A request's decision (approved, approved with changes, sent back for revision, declined), the approver's instructions, 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) => {
@@ -415,7 +419,10 @@ export function registerTools(server, ctx) {
         return {
             record: r,
             approval_url: r.approval_state === "awaiting_approval" ? approvalUrl(r.id) : undefined,
-            queue: r.kind === "run_request" ? readQueueState(r, ctx.factoryDir) : undefined,
+            queue: r.kind === "run_request" || r.kind === "work_proposal" ? readQueueState(r, ctx.factoryDir) : undefined,
+            ...(r.approval_state === "revision_requested"
+                ? { revision: { instructions: r.completion_receipt?.instructions, next: `Submit a revised request that cites ${r.id} in refs.` } }
+                : {}),
         };
     }));
     // search / fetch: the pair ChatGPT uses for connectors in search and deep research.
@@ -674,7 +681,7 @@ export function registerTools(server, ctx) {
     }));
     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.",
+        description: "Propose a bounded piece of work: what should exist when it is done, the circle accountable, the sources. Nothing starts until a person decides. Approving it starts the work as a factory run, with any changes the person writes; the person may instead send it back for revision with instructions (approval_state revision_requested, instructions in completion_receipt): then submit a revised proposal citing the old id in refs.",
         inputSchema: {
             title: z.string().min(1).max(200),
             desired_outcome: z.string().min(1).max(6000),
@@ -877,10 +884,13 @@ export function registerTools(server, ctx) {
     // ── 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.",
+        description: "Deliver a finished research report (a Deep Research report) to Miadi in your name, exactly as written: never summarised, shortened or rewritten, with its sources and citations. It is saved byte-for-byte in a new folder on Miadi's inquiry shelf, gets its inquiry issue, and is committed and pushed. A report longer than about 60,000 characters is sent in parts: call with part 1 and parts N, then with the upload_id returned and parts 2..N, each part the next slice of the text cut at a line end; the report is saved when the last part arrives. The answer gives bytes, sha256 and the report's first and last lines so you can confirm all of it arrived. Private to you unless shared with a circle; never published from 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."),
+            markdown: z.string().min(1).max(1_000_000).describe("The whole report, or this part of it, exactly as written."),
+            part: z.number().int().min(1).max(200).optional().describe("Which part this is, from 1, when the report is sent in parts."),
+            parts: z.number().int().min(1).max(200).optional().describe("How many parts the report is sent in."),
+            upload_id: z.string().max(80).optional().describe("Returned by part 1; give it with every later part."),
             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."),
@@ -894,20 +904,32 @@ export function registerTools(server, ctx) {
             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.");
+        let markdown = a.markdown;
+        let meta = { title: a.title, refs: a.refs, visibility: a.visibility, circle: a.circle };
+        const parts = a.parts ?? 1;
+        if (parts > 1 || a.upload_id) {
+            const got = uploads.receive(person.id, { upload_id: a.upload_id, part: a.part ?? 1, parts, text: a.markdown, meta });
+            if (!got.complete) {
+                return { upload_id: got.upload_id, received: got.received, missing: got.missing, bytes_so_far: got.bytes, next: `Send part ${got.missing[0]} of ${got.parts} with upload_id ${got.upload_id}.` };
+            }
+            markdown = got.text;
+            meta = got.meta;
+        }
         const saved = await saveResearchArtefact({
             inquiryRoot: config.inquiryRoot,
             repo: config.inquiryRepo,
-            title: a.title,
-            markdown: a.markdown,
+            title: meta.title,
+            markdown,
             owner: { person_id: person.id, name: person.name },
-            visibility: a.visibility,
-            circle: a.circle,
+            visibility: meta.visibility,
+            circle: meta.circle,
             via: "miadi-connector",
-            refs: a.refs,
+            refs: meta.refs,
         });
+        const lines = markdown.split("\n").filter((l) => l.trim());
         const r = append("research_artifact", person, auth, {
-            circle: a.circle ?? "stewardship",
-            refs: [`inquiry-artefact:${saved.artefact}`, ...(saved.issue ? [saved.issue] : []), ...a.refs],
+            circle: meta.circle ?? "stewardship",
+            refs: [`inquiry-artefact:${saved.artefact}`, ...(saved.issue ? [saved.issue] : []), ...meta.refs],
             intention: a.intention,
             role: a.role,
             idempotency_key: a.idempotency_key ?? `research:${saved.sha256}`,
@@ -915,18 +937,23 @@ export function registerTools(server, ctx) {
             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,
+                title: meta.title,
                 artefact: saved.artefact,
                 issue: saved.issue,
                 issue_url: saved.issue_url,
                 sha256: saved.sha256,
                 bytes: saved.bytes,
                 visibility: saved.visibility,
-                circle: a.circle,
+                circle: meta.circle,
                 shelf: { state: saved.shelf.state, observed: saved.shelf.observed },
             },
         });
-        return { ...r, saved: saved.status, research_url: `${config.miadiPublicUrl}/research` };
+        return {
+            ...r,
+            saved: saved.status,
+            received: { bytes: saved.bytes, sha256: saved.sha256, parts, first_line: lines[0]?.slice(0, 200), last_line: lines.at(-1)?.slice(0, 200) },
+            research_url: `${config.miadiPublicUrl}/research`,
+        };
     }));
     server.registerTool("request_inquiry_episode", {
         title: "Request that an inquiry be woven into an episode, or start one",
@@ -1046,13 +1073,13 @@ export const TOOL_STATUS = {
     register_source_intent: "live, contribute",
     record_handoff: "live, contribute",
     update_handoff: "live, contribute",
-    propose_work: "live, contribute, needs_approval",
+    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_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)",
+    save_research: "live, contribute (the whole report, in parts when long; saved on the inquiry shelf with its issue, pushed; private by default)",
     request_inquiry_episode: "live, contribute, needs_approval (weaves a shelf folder into an episode or starts one)",
 };

package/dist/uploads.d.ts

@@ -0,0 +1,27 @@
+export declare const MAX_UPLOAD_CHARS = 5000000;
+export declare class UploadRefusal extends Error {
+}
+export declare class ResearchUploads {
+    private readonly dir;
+    constructor(dir: string);
+    private path;
+    receive(personId: string, input: {
+        upload_id?: string;
+        part: number;
+        parts: number;
+        text: string;
+        meta: Record<string, unknown>;
+    }): {
+        upload_id: string;
+        parts: number;
+        received: number[];
+        missing: number[];
+        bytes: number;
+        complete: false;
+    } | {
+        complete: true;
+        upload_id: string;
+        text: string;
+        meta: Record<string, unknown>;
+    };
+}

package/dist/uploads.js

@@ -0,0 +1,54 @@
+/**
+ * A research report sent in parts (save_research with part/parts): each part is
+ * kept under <state>/uploads/<id>.json until the last arrives, then the parts are
+ * joined in order, exactly, and the upload is removed. One person's upload is
+ * never readable by another.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+export const MAX_UPLOAD_CHARS = 5_000_000;
+export class UploadRefusal extends Error {
+}
+export class ResearchUploads {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    path(id) {
+        if (!/^upload-[0-9a-f-]{36}$/.test(id))
+            throw new UploadRefusal(`Unknown upload_id ${id}.`);
+        return join(this.dir, `${id}.json`);
+    }
+    receive(personId, input) {
+        mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+        let up;
+        if (input.upload_id) {
+            const p = this.path(input.upload_id);
+            if (!existsSync(p))
+                throw new UploadRefusal(`Unknown upload_id ${input.upload_id}: start again with part 1.`);
+            up = JSON.parse(readFileSync(p, "utf8"));
+            if (up.person_id !== personId)
+                throw new UploadRefusal(`Unknown upload_id ${input.upload_id}.`);
+        }
+        else {
+            if (input.part !== 1)
+                throw new UploadRefusal("Start with part 1; it returns the upload_id the later parts carry.");
+            up = { id: `upload-${randomUUID()}`, person_id: personId, parts: input.parts, received: {}, meta: input.meta, created_at: new Date().toISOString() };
+        }
+        if (input.part > up.parts)
+            throw new UploadRefusal(`This upload has ${up.parts} parts; part ${input.part} does not exist.`);
+        up.received[String(input.part)] = input.text;
+        const total = Object.values(up.received).reduce((n, t) => n + t.length, 0);
+        if (total > MAX_UPLOAD_CHARS)
+            throw new UploadRefusal(`The report passes ${MAX_UPLOAD_CHARS} characters.`);
+        const missing = Array.from({ length: up.parts }, (_, i) => i + 1).filter((n) => !(String(n) in up.received));
+        if (missing.length) {
+            writeFileSync(this.path(up.id), JSON.stringify(up), { mode: 0o600 });
+            return { upload_id: up.id, parts: up.parts, received: Object.keys(up.received).map(Number).sort((a, b) => a - b), missing, bytes: total, complete: false };
+        }
+        const text = Array.from({ length: up.parts }, (_, i) => up.received[String(i + 1)]).join("");
+        rmSync(this.path(up.id), { force: true });
+        return { complete: true, upload_id: up.id, text, meta: up.meta };
+    }
+}

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/connector",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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",
@@ -12,6 +12,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./records": {
+      "types": "./dist/records.d.ts",
+      "import": "./dist/records.js"
+    },
     "./package.json": "./package.json"
   },
   "bin": {