@miadi/connector 0.1.3 → 0.1.5

package/README.md

@@ -23,11 +23,13 @@ Call `get_capabilities` first. It names the signed-in person, their Miadi API ti
 | 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` `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` |
+| decisions in the conversation | `show_decisions` (cards), `decide_request` (called by the card only) |
 
 - **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, and `show_decisions` shows them as cards inside the conversation (below). 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;
@@ -36,6 +38,17 @@ Call `get_capabilities` first. It names the signed-in person, their Miadi API ti
 
 The model that asked cannot approve its own request.
 
+### Deciding inside the conversation
+
+In a client that renders MCP Apps (ChatGPT among them), `show_decisions` draws one card per request awaiting a decision: what is asked, by whom, and what approving does. The person decides on the card with their own click: Approve, Approve with my changes, Send back for revision, or Decline. The card then shows the receipt.
+
+The model that asked cannot decide for the person:
+- `decide_request` is declared for the card only (`_meta.ui.visibility: ["app"]`), so the host does not offer it to the model.
+- It requires a decision token that travels only in the `_meta` of the `show_decisions` result. Hosts deliver that metadata to the card and keep it from the model. The token is bound to one request, one person and one OAuth client, and expires after 30 minutes. A decided request no longer awaits a decision, so a token works once.
+- The sign-in must carry `miadi:approve`. A person grants it by ticking "Let me approve requests on cards inside this client" on the sign-in page, and only a person with Miadi's write tier receives it. A person token used directly as Bearer never carries it.
+
+Without that sign-in, or for a person without the write tier, the cards link to each request's approval page instead.
+
 Every record has a claim category: `observed`, `hypothesis`, `desired_future`, `fiction` or `verified_implementation`. Witnessed fact, envisioned features and fiction stay apart.
 
 ## Run it

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,29 @@ 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>>;
+/**
+ * Record a person's decision on a request and, when approved, run it once as
+ * them. The approval page and the in-chat approval card both decide here; the
+ * caller has already checked who the person is, their write tier, and that the
+ * request still awaits approval.
+ */
+export declare function decide(r: ConnectorRecord, person: MiadiPerson, choice: Decision, deps: ApprovalDeps, opts: {
+    instructions?: string;
+    note?: string;
+    via: string;
+}): Promise<{
+    decision: NonNullable<ConnectorRecord["approval_state"]>;
+    state: ConnectorRecord["state"];
+    receipt: Record<string, unknown>;
+}>;
+export declare function isApprovable(r: ConnectorRecord | undefined): r is ConnectorRecord;
+/** What approving a request does, in one sentence, for the card a person decides on. */
+export declare function consequenceOf(r: ConnectorRecord): string;
 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",
@@ -231,9 +261,82 @@ ${r.refs.length ? `<dt>References</dt><dd>${r.refs.map(escapeHtml).join("<br>")}
 </dl>
 <pre>${escapeHtml(JSON.stringify(shown, null, 2))}</pre>`;
 }
+/**
+ * Record a person's decision on a request and, when approved, run it once as
+ * them. The approval page and the in-chat approval card both decide here; the
+ * caller has already checked who the person is, their write tier, and that the
+ * request still awaits approval.
+ */
+export async function decide(r, person, choice, deps, opts) {
+    const { instructions } = opts;
+    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,
+        via: opts.via,
+        ...(instructions ? { instructions } : {}),
+        note: opts.note,
+    };
+    let state = decision === "approved" ? "completed" : decision === "revision_requested" ? "pending" : "withdrawn";
+    if (decision === "approved") {
+        try {
+            const outcome = await executeApproved(r, person, deps, instructions);
+            receipt = { ...receipt, ...outcome };
+            if (outcome.outcome === "failed")
+                state = "blocked";
+            if (outcome.outcome === "queued")
+                state = "in_progress";
+        }
+        catch (error) {
+            receipt = { ...receipt, outcome: "failed", message: error instanceof Error ? error.message : String(error) };
+            state = "blocked";
+        }
+    }
+    deps.ledger.append({
+        id: newRecordId(r.kind),
+        kind: r.kind,
+        created_at: new Date().toISOString(),
+        actor: { person_id: person.id, name: person.name, client_id: opts.via },
+        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: choice, ...(instructions ? { instructions } : {}) },
+    });
+    return { decision, state, receipt };
+}
+export function isApprovable(r) {
+    return Boolean(r && APPROVABLE.has(r.kind));
+}
+/** What approving a request does, in one sentence, for the card a person decides on. */
+export function consequenceOf(r) {
+    const b = r.body;
+    switch (r.kind) {
+        case "run_request":
+            return "Approving queues a brief for the factory intake, which opens or reaches an agent session within minutes.";
+        case "work_proposal":
+            return "Approving starts the work: a brief written from the proposal and your instructions is queued for an agent session.";
+        case "review_operation_request":
+            return `Approving calls the review service once: ${String(b.operation ?? "operation").replace(/_/g, " ")}.`;
+        case "deep_diver_request":
+            return `Approving marks review version ${b.version ?? "?"} ready for Deep Diver, which queues its pass.`;
+        case "review_episode_link_request":
+            return `Approving has episode ${b.episode ?? "?"} hold the review through the episode door.`;
+        case "inquiry_episode_request":
+            return b.new_episode ? "Approving mints a new episode with the inquiry woven in." : `Approving weaves the inquiry into episode ${b.episode ?? "?"}.`;
+        case "session_completion_proposal":
+            return `Approving records the ending (${b.ending ?? "?"}) for the session. No pane is closed.`;
+        default:
+            return "Approving runs the request once, as you.";
+    }
+}
 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,37 +365,18 @@ 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";
-        if (decision === "approved") {
-            try {
-                const outcome = await executeApproved(r, person, deps);
-                receipt = { ...receipt, ...outcome };
-                if (outcome.outcome === "failed")
-                    state = "blocked";
-                if (outcome.outcome === "queued")
-                    state = "in_progress";
-            }
-            catch (error) {
-                receipt = { ...receipt, outcome: "failed", message: error instanceof Error ? error.message : String(error) };
-                state = "blocked";
-            }
+        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;
         }
-        deps.ledger.append({
-            id: newRecordId(r.kind),
-            kind: r.kind,
-            created_at: new Date().toISOString(),
-            actor: { person_id: person.id, name: person.name, client_id: "approval-page" },
-            refs: r.refs,
-            evidence_refs: [],
-            supersedes: r.id,
-            approval_state: decision,
-            state,
-            completion_receipt: receipt,
-            body: { decision },
+        const { decision, receipt } = await decide(r, person, choice, deps, {
+            instructions,
+            note: body.note || undefined,
+            via: String(body.via ?? "approval-page").slice(0, 60),
         });
-        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 +412,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/decisions.d.ts

@@ -0,0 +1,18 @@
+export declare const DECISIONS_CARD_URI = "ui://miadi/decisions-v1.html";
+export declare const DECISION_TOKEN_TTL: number;
+/** Where the tokens travel in a result's `_meta`, keyed by record id. */
+export declare const DECISION_TOKENS_META = "miadi/decisionTokens";
+export declare class DecisionTokens {
+    private readonly secret;
+    constructor(stateDir: string);
+    private sign;
+    issue(recordId: string, personId: string, clientId: string, now?: number): string;
+    verify(token: string, recordId: string, personId: string, clientId: string, now?: number): "ok" | "expired" | "invalid";
+}
+/**
+ * The card. Self-contained: no network, no external script. It reads the
+ * request list from the tool output and the tokens from the tool's metadata,
+ * and calls `decide_request` through the host. In a host without that bridge it
+ * shows each request's approval page instead.
+ */
+export declare const DECISIONS_CARD_HTML = "<!doctype html>\n<html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">\n<style>\n:root{color-scheme:light dark;--fg:#1d1b18;--muted:#5b5650;--line:#d9d4cc;--accent:#7a4a00;--ok:#1d6b3a;--err:#b00020;--chip:#f1ede6}\n@media (prefers-color-scheme:dark){:root{--fg:#ece8e1;--muted:#b3ada4;--line:#3a3631;--accent:#ffd700;--ok:#7fd49b;--err:#ff8a80;--chip:#24211d}}\n*{box-sizing:border-box}\nbody{margin:0;color:var(--fg);font:15px/1.45 system-ui,sans-serif;background:transparent}\nmain{padding:12px;display:grid;gap:12px}\n.empty,.note{color:var(--muted)}\narticle{border:1px solid var(--line);border-radius:10px;padding:12px}\nh2{font-size:15px;margin:0 0 4px}\n.kind{display:inline-block;font-size:12px;padding:1px 8px;border-radius:999px;background:var(--chip);color:var(--muted);margin-bottom:6px}\n.meta{font-size:13px;color:var(--muted);margin:0 0 6px}\n.does{margin:6px 0;font-weight:600}\ndetails{margin:6px 0}\nsummary{cursor:pointer;color:var(--muted);font-size:13px}\npre{white-space:pre-wrap;overflow-wrap:anywhere;font-size:12px;margin:6px 0 0;max-height:240px;overflow:auto}\ntextarea{width:100%;min-height:64px;padding:8px;border:1px solid var(--line);border-radius:8px;background:transparent;color:var(--fg);font:inherit;margin-top:8px}\n.row{display:flex;flex-wrap:wrap;gap:8px;margin-top:8px}\nbutton{padding:8px 12px;border-radius:8px;border:1px solid var(--line);background:transparent;color:var(--fg);font:inherit;cursor:pointer;min-height:40px}\nbutton.primary{border-color:var(--accent);outline:1px solid var(--accent)}\nbutton:focus-visible,a:focus-visible,textarea:focus-visible{outline:2px solid var(--accent);outline-offset:2px}\nbutton[disabled]{opacity:.55;cursor:default}\na{color:inherit}\n.done{color:var(--ok);font-weight:600}\n.fail{color:var(--err);font-weight:600}\n</style></head><body><main id=\"root\" aria-live=\"polite\"><p class=\"note\">Loading requests\u2026</p></main>\n<script>\n(function(){\n  var root=document.getElementById(\"root\");\n  var decided={};\n  function el(tag,attrs,text){var e=document.createElement(tag);if(attrs)for(var k in attrs){if(k===\"class\")e.className=attrs[k];else e.setAttribute(k,attrs[k]);}if(text!=null)e.textContent=text;return e;}\n  function host(){return window.openai||null;}\n  function data(){var h=host();return h&&h.toolOutput?h.toolOutput:null;}\n  function tokens(){var h=host();var m=h&&h.toolResponseMetadata;return (m&&m[\"miadi/decisionTokens\"])||{};}\n  function render(){\n    var d=data();root.textContent=\"\";\n    if(!d){root.appendChild(el(\"p\",{class:\"note\"},\"Waiting for the request list.\"));return;}\n    var list=d.decisions||[];\n    if(!list.length){root.appendChild(el(\"p\",{class:\"empty\"},d.message||\"No request is waiting for a decision.\"));return;}\n    if(!d.can_decide_here&&d.reason){root.appendChild(el(\"p\",{class:\"note\"},d.reason));}\n    var t=tokens();\n    list.forEach(function(r){root.appendChild(card(r,t[r.id]));});\n  }\n  function card(r,token){\n    var a=el(\"article\",{\"aria-label\":r.title});\n    a.appendChild(el(\"span\",{class:\"kind\"},r.kind_label||r.kind));\n    a.appendChild(el(\"h2\",null,r.title));\n    a.appendChild(el(\"p\",{class:\"meta\"},\"Asked by \"+r.by+(r.via?\" through \"+r.via:\"\")+\" \u00B7 \"+new Date(r.created_at).toLocaleString()+(r.circle?\" \u00B7 \"+r.circle+\" circle\":\"\")));\n    a.appendChild(el(\"p\",{class:\"does\"},r.consequence));\n    if(r.intention)a.appendChild(el(\"p\",null,r.intention));\n    var det=el(\"details\");det.appendChild(el(\"summary\",null,\"What exactly is asked\"));det.appendChild(el(\"pre\",null,r.detail||\"\"));a.appendChild(det);\n    var status=el(\"p\",{role:\"status\"});\n    if(decided[r.id]){status.className=decided[r.id].ok?\"done\":\"fail\";status.textContent=decided[r.id].text;a.appendChild(status);return a;}\n    if(!token||!host()||!host().callTool){\n      var p=el(\"p\",{class:\"note\"});p.appendChild(document.createTextNode(\"Decide on its approval page: \"));\n      var link=el(\"a\",{href:r.approval_url,target:\"_blank\",rel:\"noopener\"},\"open the approval page\");p.appendChild(link);a.appendChild(p);return a;\n    }\n    var ta=el(\"textarea\",{\"aria-label\":\"Instructions or changes (needed to approve with changes or send back)\",placeholder:\"Instructions or changes (needed to approve with changes or send back)\"});\n    a.appendChild(ta);\n    var row=el(\"div\",{class:\"row\"});\n    var buttons=[[\"approve\",\"Approve\",\"primary\"],[\"approve_with_changes\",\"Approve with my changes\",\"\"],[\"request_revision\",\"Send back for revision\",\"\"],[\"decline\",\"Decline\",\"\"]];\n    var btns=[];\n    buttons.forEach(function(b){var x=el(\"button\",{type:\"button\",class:b[2]},b[1]);x.addEventListener(\"click\",function(){go(b[0]);});btns.push(x);row.appendChild(x);});\n    a.appendChild(row);a.appendChild(status);\n    function go(choice){\n      var text=ta.value.trim();\n      if((choice===\"approve_with_changes\"||choice===\"request_revision\")&&!text){status.className=\"fail\";status.textContent=choice===\"request_revision\"?\"Say what to revise.\":\"Write the changes to apply.\";ta.focus();return;}\n      btns.forEach(function(x){x.disabled=true;});status.className=\"note\";status.textContent=\"Recording your decision\u2026\";\n      host().callTool(\"decide_request\",{record_id:r.id,decision:choice,instructions:text||undefined,decision_token:token}).then(function(res){\n        var out=(res&&(res.structuredContent||res.structured_content))||null;\n        if(!out&&res&&res.content&&res.content[0]&&res.content[0].text){try{out=JSON.parse(res.content[0].text);}catch(e){out={message:res.content[0].text};}}\n        var ok=out&&!out.error;\n        decided[r.id]={ok:ok,text:ok?(out.summary||\"Recorded.\"):((out&&out.message)||\"Not recorded.\")};render();\n      },function(err){btns.forEach(function(x){x.disabled=false;});status.className=\"fail\";status.textContent=\"Not recorded: \"+(err&&err.message?err.message:String(err));});\n    }\n    return a;\n  }\n  window.addEventListener(\"openai:set_globals\",render);\n  render();\n})();\n</script></body></html>";

package/dist/decisions.js

@@ -0,0 +1,139 @@
+/**
+ * In-chat approval: a request is decided on a card rendered inside the client
+ * (ChatGPT and other MCP Apps hosts), by the person's own click.
+ *
+ * Two locks keep the model that asked from approving:
+ * - `decide_request` is declared for the card only (`_meta.ui.visibility: ["app"]`),
+ *   so the host does not offer it to the model;
+ * - it requires a decision token that travels only in the `_meta` of the
+ *   `show_decisions` result, which hosts deliver to the card and keep from the
+ *   model. The token is bound to one request, one person and one OAuth client,
+ *   and expires. A request decided once is no longer awaiting approval, so a
+ *   token cannot be used twice.
+ *
+ * The sign-in must also carry `miadi:approve`, which a person grants by ticking
+ * it, and Miadi must give them the write tier.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { newSecret } from "./store.js";
+export const DECISIONS_CARD_URI = "ui://miadi/decisions-v1.html";
+export const DECISION_TOKEN_TTL = 30 * 60;
+/** Where the tokens travel in a result's `_meta`, keyed by record id. */
+export const DECISION_TOKENS_META = "miadi/decisionTokens";
+export class DecisionTokens {
+    secret;
+    constructor(stateDir) {
+        const file = join(stateDir, "decision-secret");
+        if (!existsSync(file))
+            writeFileSync(file, newSecret(32), { mode: 0o600, flag: "wx" });
+        this.secret = readFileSync(file, "utf8").trim();
+    }
+    sign(recordId, personId, clientId, exp) {
+        return createHmac("sha256", this.secret).update(`${recordId}\n${personId}\n${clientId}\n${exp}`).digest("base64url");
+    }
+    issue(recordId, personId, clientId, now = Math.floor(Date.now() / 1000)) {
+        const exp = now + DECISION_TOKEN_TTL;
+        return `${exp}.${this.sign(recordId, personId, clientId, exp)}`;
+    }
+    verify(token, recordId, personId, clientId, now = Math.floor(Date.now() / 1000)) {
+        const [expRaw, mac] = String(token ?? "").split(".");
+        const exp = Number(expRaw);
+        if (!Number.isInteger(exp) || !mac)
+            return "invalid";
+        const expected = Buffer.from(this.sign(recordId, personId, clientId, exp));
+        const given = Buffer.from(mac);
+        if (expected.length !== given.length || !timingSafeEqual(expected, given))
+            return "invalid";
+        return exp < now ? "expired" : "ok";
+    }
+}
+/**
+ * The card. Self-contained: no network, no external script. It reads the
+ * request list from the tool output and the tokens from the tool's metadata,
+ * and calls `decide_request` through the host. In a host without that bridge it
+ * shows each request's approval page instead.
+ */
+export const DECISIONS_CARD_HTML = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<style>
+:root{color-scheme:light dark;--fg:#1d1b18;--muted:#5b5650;--line:#d9d4cc;--accent:#7a4a00;--ok:#1d6b3a;--err:#b00020;--chip:#f1ede6}
+@media (prefers-color-scheme:dark){:root{--fg:#ece8e1;--muted:#b3ada4;--line:#3a3631;--accent:#ffd700;--ok:#7fd49b;--err:#ff8a80;--chip:#24211d}}
+*{box-sizing:border-box}
+body{margin:0;color:var(--fg);font:15px/1.45 system-ui,sans-serif;background:transparent}
+main{padding:12px;display:grid;gap:12px}
+.empty,.note{color:var(--muted)}
+article{border:1px solid var(--line);border-radius:10px;padding:12px}
+h2{font-size:15px;margin:0 0 4px}
+.kind{display:inline-block;font-size:12px;padding:1px 8px;border-radius:999px;background:var(--chip);color:var(--muted);margin-bottom:6px}
+.meta{font-size:13px;color:var(--muted);margin:0 0 6px}
+.does{margin:6px 0;font-weight:600}
+details{margin:6px 0}
+summary{cursor:pointer;color:var(--muted);font-size:13px}
+pre{white-space:pre-wrap;overflow-wrap:anywhere;font-size:12px;margin:6px 0 0;max-height:240px;overflow:auto}
+textarea{width:100%;min-height:64px;padding:8px;border:1px solid var(--line);border-radius:8px;background:transparent;color:var(--fg);font:inherit;margin-top:8px}
+.row{display:flex;flex-wrap:wrap;gap:8px;margin-top:8px}
+button{padding:8px 12px;border-radius:8px;border:1px solid var(--line);background:transparent;color:var(--fg);font:inherit;cursor:pointer;min-height:40px}
+button.primary{border-color:var(--accent);outline:1px solid var(--accent)}
+button:focus-visible,a:focus-visible,textarea:focus-visible{outline:2px solid var(--accent);outline-offset:2px}
+button[disabled]{opacity:.55;cursor:default}
+a{color:inherit}
+.done{color:var(--ok);font-weight:600}
+.fail{color:var(--err);font-weight:600}
+</style></head><body><main id="root" aria-live="polite"><p class="note">Loading requests…</p></main>
+<script>
+(function(){
+  var root=document.getElementById("root");
+  var decided={};
+  function el(tag,attrs,text){var e=document.createElement(tag);if(attrs)for(var k in attrs){if(k==="class")e.className=attrs[k];else e.setAttribute(k,attrs[k]);}if(text!=null)e.textContent=text;return e;}
+  function host(){return window.openai||null;}
+  function data(){var h=host();return h&&h.toolOutput?h.toolOutput:null;}
+  function tokens(){var h=host();var m=h&&h.toolResponseMetadata;return (m&&m["${DECISION_TOKENS_META}"])||{};}
+  function render(){
+    var d=data();root.textContent="";
+    if(!d){root.appendChild(el("p",{class:"note"},"Waiting for the request list."));return;}
+    var list=d.decisions||[];
+    if(!list.length){root.appendChild(el("p",{class:"empty"},d.message||"No request is waiting for a decision."));return;}
+    if(!d.can_decide_here&&d.reason){root.appendChild(el("p",{class:"note"},d.reason));}
+    var t=tokens();
+    list.forEach(function(r){root.appendChild(card(r,t[r.id]));});
+  }
+  function card(r,token){
+    var a=el("article",{"aria-label":r.title});
+    a.appendChild(el("span",{class:"kind"},r.kind_label||r.kind));
+    a.appendChild(el("h2",null,r.title));
+    a.appendChild(el("p",{class:"meta"},"Asked by "+r.by+(r.via?" through "+r.via:"")+" · "+new Date(r.created_at).toLocaleString()+(r.circle?" · "+r.circle+" circle":"")));
+    a.appendChild(el("p",{class:"does"},r.consequence));
+    if(r.intention)a.appendChild(el("p",null,r.intention));
+    var det=el("details");det.appendChild(el("summary",null,"What exactly is asked"));det.appendChild(el("pre",null,r.detail||""));a.appendChild(det);
+    var status=el("p",{role:"status"});
+    if(decided[r.id]){status.className=decided[r.id].ok?"done":"fail";status.textContent=decided[r.id].text;a.appendChild(status);return a;}
+    if(!token||!host()||!host().callTool){
+      var p=el("p",{class:"note"});p.appendChild(document.createTextNode("Decide on its approval page: "));
+      var link=el("a",{href:r.approval_url,target:"_blank",rel:"noopener"},"open the approval page");p.appendChild(link);a.appendChild(p);return a;
+    }
+    var ta=el("textarea",{"aria-label":"Instructions or changes (needed to approve with changes or send back)",placeholder:"Instructions or changes (needed to approve with changes or send back)"});
+    a.appendChild(ta);
+    var row=el("div",{class:"row"});
+    var buttons=[["approve","Approve","primary"],["approve_with_changes","Approve with my changes",""],["request_revision","Send back for revision",""],["decline","Decline",""]];
+    var btns=[];
+    buttons.forEach(function(b){var x=el("button",{type:"button",class:b[2]},b[1]);x.addEventListener("click",function(){go(b[0]);});btns.push(x);row.appendChild(x);});
+    a.appendChild(row);a.appendChild(status);
+    function go(choice){
+      var text=ta.value.trim();
+      if((choice==="approve_with_changes"||choice==="request_revision")&&!text){status.className="fail";status.textContent=choice==="request_revision"?"Say what to revise.":"Write the changes to apply.";ta.focus();return;}
+      btns.forEach(function(x){x.disabled=true;});status.className="note";status.textContent="Recording your decision…";
+      host().callTool("decide_request",{record_id:r.id,decision:choice,instructions:text||undefined,decision_token:token}).then(function(res){
+        var out=(res&&(res.structuredContent||res.structured_content))||null;
+        if(!out&&res&&res.content&&res.content[0]&&res.content[0].text){try{out=JSON.parse(res.content[0].text);}catch(e){out={message:res.content[0].text};}}
+        var ok=out&&!out.error;
+        decided[r.id]={ok:ok,text:ok?(out.summary||"Recorded."):((out&&out.message)||"Not recorded.")};render();
+      },function(err){btns.forEach(function(x){x.disabled=false;});status.className="fail";status.textContent="Not recorded: "+(err&&err.message?err.message:String(err));});
+    }
+    return a;
+  }
+  window.addEventListener("openai:set_globals",render);
+  render();
+})();
+</script></body></html>`;

package/dist/oauth.d.ts

@@ -16,6 +16,12 @@ import type { OAuthClientInformationFull, OAuthTokens, OAuthTokenRevocationReque
 import { JsonFile } from "./store.js";
 export declare const SCOPE_READ = "miadi:read";
 export declare const SCOPE_CONTRIBUTE = "miadi:contribute";
+/**
+ * Decide requests on in-chat approval cards. Granted only when the person ticks
+ * it at sign-in and Miadi gives them the write tier; never to a person token
+ * used directly as Bearer.
+ */
+export declare const SCOPE_APPROVE = "miadi:approve";
 export declare const SCOPES: string[];
 /** Who a Miadi person token belongs to, as Miadi itself answers. */
 export interface Person {
@@ -23,6 +29,8 @@ export interface Person {
     name: string;
     /** The Miadi person token, so calls to Miadi are made as this person. */
     token: string;
+    /** Miadi's API tier for this person, when the identify function knows it. */
+    api_tier?: string | null;
 }
 export type Identify = (token: string) => Promise<Person | null>;
 interface Pending {

package/dist/oauth.js

@@ -3,7 +3,15 @@ import { escapeHtml } from "@miadi/node-service-kit/format";
 import { digest, newSecret } from "./store.js";
 export const SCOPE_READ = "miadi:read";
 export const SCOPE_CONTRIBUTE = "miadi:contribute";
-export const SCOPES = [SCOPE_READ, SCOPE_CONTRIBUTE];
+/**
+ * Decide requests on in-chat approval cards. Granted only when the person ticks
+ * it at sign-in and Miadi gives them the write tier; never to a person token
+ * used directly as Bearer.
+ */
+export const SCOPE_APPROVE = "miadi:approve";
+export const SCOPES = [SCOPE_READ, SCOPE_CONTRIBUTE, SCOPE_APPROVE];
+/** What a person token used directly as Bearer carries: no in-chat approval. */
+const DIRECT_SCOPES = [SCOPE_READ, SCOPE_CONTRIBUTE];
 export const emptyOAuthState = () => ({ clients: {}, pending: {}, codes: {}, tokens: {} });
 const ACCESS_TTL = 8 * 3600;
 const REFRESH_TTL = 90 * 24 * 3600;
@@ -98,9 +106,14 @@ export class MiadiOAuthProvider {
             }));
             return;
         }
-        let scopes = wanted(pending.params.scopes);
+        let scopes = wanted(pending.params.scopes).filter((x) => x !== SCOPE_APPROVE);
         if (body.contribute !== "on")
             scopes = scopes.filter((x) => x !== SCOPE_CONTRIBUTE);
+        // In-chat approval is opt-in, whatever the client asked for, and only for Miadi's write tier.
+        if (body.approve === "on" && person.api_tier === "write")
+            scopes.push(SCOPE_APPROVE);
+        if (!scopes.includes(SCOPE_READ))
+            scopes.unshift(SCOPE_READ);
         const code = newSecret(24);
         this.state.update((st) => {
             delete st.pending[body.request_id];
@@ -158,14 +171,14 @@ export class MiadiOAuthProvider {
         // A Miadi person token used directly (terminal clients).
         const cached = this.direct.get(digest(token));
         if (cached && cached.until > now()) {
-            return info(token, "direct", SCOPES, cached.until, cached.person);
+            return info(token, "direct", DIRECT_SCOPES, cached.until, cached.person);
         }
         const person = await this.identify(token);
         if (!person)
             throw new InvalidTokenError("Unknown token");
         const until = now() + DIRECT_TTL;
         this.direct.set(digest(token), { person, until });
-        return info(token, "direct", SCOPES, until, person);
+        return info(token, "direct", DIRECT_SCOPES, until, person);
     }
     async revokeToken(_client, request) {
         this.state.update((s) => {
@@ -250,6 +263,8 @@ ${o.error ? `<p class="err" role="alert">${escapeHtml(o.error)}</p>` : ""}
 <label for="person_token">Your Miadi person token</label>
 <input id="person_token" name="person_token" type="password" autocomplete="off" required>
 ${contribute ? '<label><input type="checkbox" name="contribute" checked> Allow contributions in my name</label>' : ""}
+<label><input type="checkbox" name="approve"> Let me approve requests on cards inside this client</label>
+<p>Only for people with Miadi's write tier. Each approval is your own click on a card; the assistant cannot approve for you.</p>
 <div class="row">
 <button class="primary" type="submit" name="decision" value="allow">Sign in</button>
 <button type="submit" name="decision" value="deny" formnovalidate>Refuse</button>

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. After making a request, call show_decisions: it shows the request as a card in the conversation, where the person decides with their own click (or follows its approval page). Never claim a decision the card has not reported. 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

@@ -16,6 +16,7 @@ import { mcpAuthRouter, createOAuthMetadata, getOAuthProtectedResourceMetadataUr
 import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
 import { MiadiOAuthProvider, SCOPES, emptyOAuthState } from "./oauth.js";
 import { registerApprovalRoutes } from "./approve.js";
+import { DecisionTokens } from "./decisions.js";
 import { JsonFile, Ledger, ensureStateDir, statePaths } from "./store.js";
 import { registerTools } from "./tools.js";
 import { MiadiClient } from "./miadi.js";
@@ -67,7 +68,7 @@ export function createConnectorApp(config, deps) {
     app.post("/authorize/confirm", express.urlencoded({ extended: false, limit: "16kb" }), (req, res, next) => {
         provider.confirm(req, res).catch(next);
     });
-    registerApprovalRoutes(app, {
+    const approvalDeps = {
         config,
         ledger,
         miadi,
@@ -75,14 +76,16 @@ export function createConnectorApp(config, deps) {
         fetchImpl: deps.fetchImpl,
         factoryDir: deps.factoryDir,
         tmuxSessions: deps.tmuxSessions,
-    });
+    };
+    registerApprovalRoutes(app, approvalDeps);
+    const decisionTokens = new DecisionTokens(config.stateDir);
     const auth = requireBearerAuth({
         verifier: provider,
         requiredScopes: ["miadi:read"],
         resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(mcpUrl),
     });
     const handle = async (req, res) => {
-        const ctx = { config, miadi, reviews, ledger, oauthState, factoryDir: deps.factoryDir };
+        const ctx = { config, miadi, reviews, ledger, oauthState, factoryDir: deps.factoryDir, approval: approvalDeps, decisionTokens };
         const server = new McpServer({ name: "miadi", version: VERSION }, { instructions: INSTRUCTIONS });
         registerTools(server, ctx);
         const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
@@ -116,6 +119,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. After making a request, call show_decisions: it shows the request as a card in the conversation, where the person decides with their own click (or follows its approval page). Never claim a decision the card has not reported. 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.d.ts

@@ -5,6 +5,8 @@ import type { ReviewClient } from "./reviews.js";
 import type { JsonFile, Ledger } from "./store.js";
 import type { OAuthState } from "./oauth.js";
 import { type ConnectorRecord } from "./records.js";
+import { type ApprovalDeps } from "./approve.js";
+import { type DecisionTokens } from "./decisions.js";
 export interface ToolContext {
     config: ConnectorConfig;
     miadi: MiadiClient;
@@ -13,6 +15,9 @@ export interface ToolContext {
     oauthState: JsonFile<OAuthState>;
     /** The factory directory holding queue/ (default ~/.miadi/factory). */
     factoryDir?: string;
+    /** What the in-chat approval card needs to run a decided request. */
+    approval?: ApprovalDeps;
+    decisionTokens?: DecisionTokens;
 }
 export declare function registerTools(server: McpServer, ctx: ToolContext): void;
 /** What get_capabilities reports for each tool. */

package/dist/tools.js

@@ -13,12 +13,14 @@
 import { z } from "zod";
 import { MiadiError } from "./miadi.js";
 import { reviewIdOf, videoIdOf } from "./reviews.js";
-import { SCOPE_CONTRIBUTE } from "./oauth.js";
+import { SCOPE_APPROVE, 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 { DECISIONS, consequenceOf, decide, isApprovable, readQueueState } from "./approve.js";
+import { DECISIONS_CARD_HTML, DECISIONS_CARD_URI, DECISION_TOKENS_META } from "./decisions.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 +58,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 +106,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 +409,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 +420,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 +682,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 +885,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 +905,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 +938,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",
@@ -974,6 +1002,146 @@ export function registerTools(server, ctx) {
         });
         return { ...r, approval_url: approvalUrl(r.id) };
     }));
+    // ── decisions inside the conversation ─────────────────────────────────
+    const KIND_LABEL = {
+        run_request: "Agent run",
+        work_proposal: "Work proposal",
+        review_operation_request: "Review operation",
+        deep_diver_request: "Deep Diver",
+        review_episode_link_request: "Review into an episode",
+        inquiry_episode_request: "Inquiry into an episode",
+        session_completion_proposal: "Session ending",
+    };
+    const titleOf = (r) => {
+        const b = r.body;
+        const t = b.title ?? b.task ?? b.desired_outcome ?? b.reason ?? b.operation ?? b.artefact ?? r.intention ?? r.kind;
+        const line = String(t).split("\n")[0].trim();
+        return line.length > 120 ? `${line.slice(0, 117)}…` : line;
+    };
+    const detailOf = (r) => {
+        const shown = { ...r.body };
+        for (const k of ["markdown", "transcript"])
+            if (typeof shown[k] === "string")
+                shown[k] = `${shown[k].length} chars`;
+        return JSON.stringify({ ...shown, refs: r.refs.length ? r.refs : undefined }, null, 2);
+    };
+    server.registerResource("miadi-decisions-card", DECISIONS_CARD_URI, { title: "Miadi decisions", description: "Requests awaiting a person's decision, decided by the person's own click.", mimeType: "text/html;profile=mcp-app" }, async () => ({
+        contents: [
+            {
+                uri: DECISIONS_CARD_URI,
+                mimeType: "text/html;profile=mcp-app",
+                text: DECISIONS_CARD_HTML,
+                _meta: { ui: { prefersBorder: true, csp: { connectDomains: [], resourceDomains: [] } }, "openai/widgetDescription": "Cards for the requests awaiting the person's decision." },
+            },
+        ],
+    }));
+    server.registerTool("show_decisions", {
+        title: "Show the requests awaiting a decision",
+        description: "Show the requests that await a person's decision (runs, work proposals, review operations, Deep Diver, episode links, session endings) as cards in the conversation. The person approves, approves with changes, sends back or declines each one with their own click; you cannot decide for them. Call it after making a request, or when the person asks what waits for them. Optionally pass record_id to show one request.",
+        inputSchema: { record_id: z.string().optional() },
+        annotations: READ,
+        _meta: { ui: { resourceUri: DECISIONS_CARD_URI }, "openai/outputTemplate": DECISIONS_CARD_URI, "openai/toolInvocation/invoking": "Gathering requests", "openai/toolInvocation/invoked": "Requests shown" },
+    }, async ({ record_id }, extra) => {
+        try {
+            const { person, auth } = personOf(extra);
+            const writer = person.api_tier === "write";
+            const waiting = records()
+                .filter((r) => r.approval_state === "awaiting_approval" && isApprovable(r))
+                .filter((r) => writer || r.actor.person_id === person.id)
+                .filter((r) => !record_id || r.id === record_id)
+                .slice(-20)
+                .reverse();
+            const canDecide = writer && auth.scopes.includes(SCOPE_APPROVE) && Boolean(ctx.decisionTokens);
+            const reason = canDecide
+                ? undefined
+                : !writer
+                    ? `Deciding needs Miadi's write tier; ${person.name} has ${person.api_tier ?? "no API tier"}. The requests are listed with their approval pages.`
+                    : "This sign-in does not allow approving inside this client. Reconnect and tick \"Let me approve requests on cards inside this client\", or use each request's approval page.";
+            const decisions = waiting.map((r) => ({
+                id: r.id,
+                kind: r.kind,
+                kind_label: KIND_LABEL[r.kind] ?? r.kind,
+                title: titleOf(r),
+                by: r.actor.name,
+                via: r.actor.client_name,
+                created_at: r.created_at,
+                circle: r.circle,
+                intention: r.intention,
+                consequence: consequenceOf(r),
+                detail: detailOf(r),
+                approval_url: approvalUrl(r.id),
+            }));
+            const tokens = canDecide ? Object.fromEntries(waiting.map((r) => [r.id, ctx.decisionTokens.issue(r.id, person.id, auth.clientId)])) : {};
+            const structured = {
+                decisions,
+                count: decisions.length,
+                can_decide_here: canDecide,
+                ...(reason ? { reason } : {}),
+                ...(decisions.length ? {} : { message: record_id ? "That request is not awaiting a decision." : "No request is waiting for a decision." }),
+            };
+            const text = decisions.length
+                ? `${decisions.length} request(s) await a decision and are shown as cards. ${canDecide ? "The person decides each one on its card; do not decide or claim a decision for them." : reason}`
+                : structured.message;
+            return { structuredContent: structured, content: [{ type: "text", text }], _meta: { [DECISION_TOKENS_META]: tokens } };
+        }
+        catch (error) {
+            if (error instanceof ToolRefusal)
+                return fail({ error: error.code, message: error.message });
+            return fail({ error: "failed", message: error instanceof Error ? error.message : String(error) });
+        }
+    });
+    server.registerTool("decide_request", {
+        title: "Record the person's decision from a card",
+        description: "Called by the decisions card when the person clicks Approve, Approve with my changes, Send back or Decline. Requires the card's decision token, which the assistant does not receive.",
+        inputSchema: {
+            record_id: z.string().min(1),
+            decision: z.enum(DECISIONS),
+            instructions: z.string().max(20000).optional(),
+            decision_token: z.string().min(10).max(200),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+        _meta: { ui: { resourceUri: DECISIONS_CARD_URI, visibility: ["app"] }, "openai/widgetAccessible": true },
+    }, async (a, extra) => {
+        try {
+            const { person, auth } = personOf(extra);
+            if (!auth.scopes.includes(SCOPE_APPROVE))
+                throw new ToolRefusal("insufficient_scope", "This sign-in does not allow approving inside this client.");
+            requireTier(person, "write");
+            if (!ctx.decisionTokens || !ctx.approval)
+                throw new ToolRefusal("unavailable", "In-chat decisions are not configured on this connector.");
+            const r = records().find((x) => x.id === a.record_id);
+            if (!isApprovable(r))
+                throw new ToolRefusal("not_found", "No request with that id.");
+            const check = ctx.decisionTokens.verify(a.decision_token, r.id, person.id, auth.clientId);
+            if (check !== "ok")
+                throw new ToolRefusal(check === "expired" ? "token_expired" : "invalid_token", check === "expired" ? "This card is too old; show the requests again." : "This decision did not come from the person's card.");
+            if (r.approval_state !== "awaiting_approval")
+                throw new ToolRefusal("already_decided", `This request is already ${r.approval_state}.`);
+            const instructions = a.instructions?.trim() || undefined;
+            if ((a.decision === "approve_with_changes" || a.decision === "request_revision") && !instructions) {
+                throw new ToolRefusal("instructions_required", a.decision === "request_revision" ? "Say what to revise." : "Write the changes to apply.");
+            }
+            const client = ctx.oauthState.read().clients[auth.clientId];
+            const { decision, state, receipt } = await decide(r, person, a.decision, ctx.approval, {
+                instructions,
+                via: `card:${String(client?.client_name ?? auth.clientId).slice(0, 50)}`,
+            });
+            const summary = decision === "approved"
+                ? `Approved by ${person.name}. ${receipt.outcome === "failed" ? "Running it failed; see the receipt." : `Outcome: ${String(receipt.outcome ?? "recorded").replace(/_/g, " ")}.`}`
+                : decision === "revision_requested"
+                    ? `Sent back for revision by ${person.name}.`
+                    : `Declined by ${person.name}.`;
+            const out = { record_id: r.id, decision, state, summary, receipt };
+            return { structuredContent: out, content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
+        }
+        catch (error) {
+            if (error instanceof ToolRefusal) {
+                const out = { error: error.code, message: error.message };
+                return { isError: true, structuredContent: out, content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
+            }
+            return fail({ error: "failed", message: error instanceof Error ? error.message : String(error) });
+        }
+    });
 }
 function asState(e) {
     if (e instanceof MiadiError)
@@ -1046,13 +1214,15 @@ 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)",
+    show_decisions: "live (cards in the conversation; deciding on them needs the write tier and the miadi:approve sign-in)",
+    decide_request: "card only: the person's click on a decisions card; not offered to the assistant",
 };

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.3";
+export declare const VERSION = "0.1.5";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.1.3";
+export const VERSION = "0.1.5";

package/package.json

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