@miadi/connector 0.1.20 → 0.1.22

package/dist/tools.js

@@ -23,7 +23,9 @@ import { discoverProviders, jevConfigOf, resolveProvider, routerPreflight, PROVI
 import { authorizesActions, missionStatus, primaryIssueOf, resolveMissionSubject } from "./mission-status.js";
 import { authorizationReceipt, authorizeProvider, CHOICE_PROVIDERS, isPersonId, needsPersonChoice, providerPolicyOf } from "./provider-policy.js";
 import { candidatesFor, CRITICALITIES, jevAdapter, modelPreflight, PREFLIGHT_CONTRACT, PREFLIGHT_VERSION, TASK_TYPES, } from "./model-preflight.js";
-import { checkGrant, isBusy, steerAttempts, steeringGrantOf, steerSession } from "./steer.js";
+import { ShelfRefusal, listShelfArtefacts, readShelfArtefact } from "./research-shelf.js";
+import { CLAUDE_ADAPTER, DELIVERY_STATES, readSteerDelivery, revokeInInbox, settlementOf } from "./runtime-steer.js";
+import { checkGrant, isBusy, steerAttempts, steeringGrantOf, steeringRevoked, steerSession } from "./steer.js";
 import { factoryLedgerPath, readFactoryReceipts, receiptsForRecord, recordsForSession } from "./factory-receipt.js";
 import { missionResult, redactResult } from "./mission-result.js";
 import { factoryDir as defaultFactoryDir } from "./queue-state.js";
@@ -35,6 +37,18 @@ import { canReadReading, readingOwner } from "./reading/privacy.js";
 import { artefactVisibility, readArtefactWeave, saveResearchArtefact } from "@miadi/inquiry-weave";
 import { ResearchUploads, UploadRefusal } from "./uploads.js";
 import { DEFAULT_PAGE_BYTES, FOUNDATIONS_PERMISSION, FileRefusal, MAX_TEXT_BYTES, MIN_PAGE_BYTES, TEXT_TYPES, checkRelativePath, episodeNumberOf, extensionOf, fileRef, holdsFoundationRead, isFoundationDoc, pageOf, parseFileRef, } from "./episode-files.js";
+/** Which standard judges a mission now, and whether Jev takes part; no key value is read into it. */
+async function standardStatus(service) {
+    const standard = await service.standard();
+    return {
+        name: standard.name,
+        version: standard.version,
+        source: standard.source,
+        ...(standard.note ? { note: standard.note } : {}),
+        aspects: standard.aspects.map((a) => ({ code: a.code, name: a.name, requires: a.requires, settled_by: a.settled_by })),
+        jev: service.jevConfigured ? "configured" : "unconfigured",
+    };
+}
 class ToolRefusal extends Error {
     code;
     detail;
@@ -99,6 +113,8 @@ const primaryIssue = z
     .regex(/^[\w.-]+\/[\w.-]+#\d+$/)
     .optional()
     .describe("owner/repo#n: the one issue this mission implements. Other refs stay related. Without it, mission_status can only infer the mission from the first issue in refs (jgwill/Miadi#913).");
+const deliveryField = z.string().min(1).max(500).optional().describe("The one exact place the result lands: a path, a branch, a pull request, an issue, a review or an episode. Not a kind of place or a choice among places (jgwill/Miadi#939).");
+const personWordsField = z.string().min(1).max(4000).optional().describe("The person's own words, verbatim from your conversation, for any rule, correction or decision the mission credits to them. The person reads them on the card and the worker reads them in the brief.");
 /** Refs with the declared primary issue first, never duplicated. */
 function withPrimary(refs, primary) {
     return primary ? [primary, ...refs.filter((r) => r !== primary)] : refs;
@@ -150,6 +166,27 @@ export function githubGetter(fetchImpl = fetch, token = process.env.GITHUB_TOKEN
     };
 }
 /** Whether the steering transport works now: registered is not operational (jgwill/Miadi#909). */
+/**
+ * The provider interface as a client reads it (jgwill/Miadi#930). A correction goes to the session's
+ * own runtime, and busy is normal. Only the adapter named here exists. No other provider is assumed
+ * to behave like Claude Code.
+ */
+/** A steer being sent now, by its record: a retry arriving during it waits for this answer and sends nothing (jgwill/Miadi#930). */
+const steersInFlight = new Map();
+export const STEERING_CONTRACT = {
+    busy_is_normal: true,
+    connector: "Admits the steer, resolves mission → session → runtime, hands it to that session's inbox and reports what the runtime accepted. It does not watch tools or wait for idle.",
+    runtime: "The agent's own lifecycle presents it to its model at the next supported continuation in the same turn.",
+    delivery_states: DELIVERY_STATES,
+    provider_adapters: {
+        claude: { route: "claude_hook_inbox", continuation: "PostToolUse, PostToolUseFailure, then Stop if no tool follows", needs: `${CLAUDE_ADAPTER}, loaded when the session started` },
+        codex: { route: "unsupported" },
+        copilot: { route: "unsupported" },
+        pi: { route: "unsupported" },
+        gemini: { route: "unsupported" },
+    },
+    idle_seat: "An idle seat has no continuation coming, so its steer is typed into its bound pane once the prompt reads empty.",
+};
 export function steeringTransport(tmux) {
     if (!tmux)
         return { tool: "registered", transport: "unavailable", reason: "The connector host was started without a steering surface." };
@@ -232,8 +269,44 @@ export function registerTools(server, ctx) {
             ...fields,
         });
     };
+    /** A person's standing preferences are read by that person and by the write tier. */
+    const reviewShownTo = (review, r, reader) => review ? (reader.api_tier === "write" || r.actor.person_id === reader.id ? review : { ...review, preferences: [] }) : null;
+    /** The report for a mission's current version; a failure here never refuses the request (jgwill/Miadi#939). */
+    const draftReviewOf = async (r) => ctx.draftReview ? ctx.draftReview.review(all().find((x) => x.id === r.id) ?? r, all()) : { state: "unavailable", message: "This connector runs no draft review." };
+    /**
+     * A forwarded steer's record moves when the runtime's evidence moves: done once the model has it,
+     * stopped once it never will. The ledger then agrees with its delivery on every surface that reads it
+     * (jgwill/Miadi#930). This only reads the inbox and the transcript, and appends when something changed.
+     */
+    const settleSteers = () => {
+        if (!ctx.steeringRuntime)
+            return;
+        for (const r of current(ledger.all())) {
+            if (r.kind !== "session_steer_request")
+                continue;
+            const settled = settlementOf(ctx.steeringRuntime, r);
+            if (!settled)
+                continue;
+            ledger.append({
+                id: newRecordId(r.kind),
+                kind: r.kind,
+                created_at: new Date().toISOString(),
+                actor: r.actor,
+                refs: r.refs,
+                evidence_refs: r.evidence_refs,
+                supersedes: r.id,
+                ...(r.approval_state ? { approval_state: r.approval_state } : {}),
+                state: settled.state,
+                completion_receipt: { ...r.completion_receipt, outcome: settled.outcome, delivery_state: settled.outcome, settled_at: new Date().toISOString(), ...(settled.at ? { delivered_at: settled.at } : {}), message: settled.message },
+                body: r.body,
+            });
+        }
+    };
     /** Every record, folded; for logic. What a tool returns goes through `shown`. */
-    const all = () => current(ledger.all());
+    const all = () => {
+        settleSteers();
+        return current(ledger.all());
+    };
     const records = () => {
         const raw = all();
         // Completion results can contain exact drafts too. Hide their parent mission as
@@ -316,8 +389,9 @@ export function registerTools(server, ctx) {
                 ledger: "connector ledger (append-only, /srv/miadi/connector)",
             },
             tools: TOOL_STATUS,
+            mission_standard: ctx.draftReview ? await standardStatus(ctx.draftReview) : { state: "unavailable" },
             // Registered is not operational: whether a steer can reach a pane on this host now (jgwill/Miadi#909).
-            steering: steeringTransport(ctx.tmux),
+            steering: { ...steeringTransport(ctx.tmux), runtime_route: ctx.steeringRuntime ? "configured" : "not_configured", contract: STEERING_CONTRACT },
             foundation_read: {
                 permission: FOUNDATIONS_PERMISSION,
                 held: foundations,
@@ -769,8 +843,11 @@ export function registerTools(server, ctx) {
             ...(versionOf(r) > 1 ? { history: "Earlier versions: get_request_history." } : {}),
             approval_url: r.approval_state === "awaiting_approval" ? approvalUrl(r.id) : undefined,
             queue: r.kind === "run_request" || r.kind === "work_proposal" ? readQueueState(r, ctx.factoryDir) : undefined,
+            // Where a steer stands, joined to its id: operator detail, as mission_status has it (jgwill/Miadi#930).
+            ...(r.kind === "session_steer_request" && ctx.steeringRuntime && person.api_tier === "write" ? { delivery: readSteerDelivery(ctx.steeringRuntime, all().find((x) => x.id === r.id) ?? r) ?? undefined } : {}),
             // Where the request stands, in the words every surface uses (jgwill/Miadi#889).
             projection: requestProjection(r, { reviewBase: ctx.approval?.config.reviewUrl, factoryDir: ctx.factoryDir }),
+            ...(r.kind === "run_request" || r.kind === "work_proposal" ? { draft_review: reviewShownTo(ctx.draftReview?.stored(r), r, person) } : {}),
             ...(r.approval_state === "revision_requested"
                 ? { revision: { instructions: r.completion_receipt?.instructions, next: `Revise it in place: revise_pending_request with request_id ${r.id} and expected_version ${versionOf(r)}.` } }
                 : {}),
@@ -794,6 +871,14 @@ export function registerTools(server, ctx) {
         return withProviderAuthorization(await missionStatus(ref.trim(), records(), {
             projectOf: (r) => requestProjection(r, { reviewBase: ctx.approval?.config.reviewUrl, factoryDir: ctx.factoryDir }),
             queueOf: (r) => (r.kind === "run_request" || r.kind === "work_proposal" ? readQueueState(r, ctx.factoryDir) : undefined),
+            ...(writeTier && ctx.steeringRuntime
+                ? {
+                    steerDeliveryOf: (r) => {
+                        const stored = all().find((x) => x.id === r.id) ?? r;
+                        return readSteerDelivery(ctx.steeringRuntime, stored);
+                    },
+                }
+                : {}),
             // Without a lister the host cannot say which sessions live: unknown, never "absent" (jgwill/Miadi#909).
             tmuxSessions: writeTier ? (ctx.tmuxSessions ?? (ctx.tmux?.listSessions ? () => ctx.tmux.listSessions() : undefined)) : undefined,
             paneBusy: writeTier && ctx.tmux
@@ -1226,6 +1311,8 @@ export function registerTools(server, ctx) {
             refs,
             primary_issue: primaryIssue,
             repo: z.string().max(120).optional(),
+            delivery: deliveryField,
+            person_words: personWordsField,
             ...base,
         },
         annotations: WRITE,
@@ -1240,9 +1327,16 @@ export function registerTools(server, ctx) {
             idempotency_key: a.idempotency_key,
             state: "pending",
             approval_state: "awaiting_approval",
-            body: { title: a.title, desired_outcome: a.desired_outcome, repo: a.repo, ...(a.primary_issue ? { primary_issue: a.primary_issue } : {}) },
+            body: {
+                title: a.title,
+                desired_outcome: a.desired_outcome,
+                repo: a.repo,
+                ...(a.primary_issue ? { primary_issue: a.primary_issue } : {}),
+                ...(a.delivery ? { delivery: a.delivery } : {}),
+                ...(a.person_words ? { person_words: a.person_words } : {}),
+            },
         });
-        return { ...r, approval_url: approvalUrl(r.id) };
+        return { ...r, approval_url: approvalUrl(r.id), draft_review: await draftReviewOf(r) };
     }));
     server.registerTool("prepare_calendar_event", {
         title: "Draft a calendar event",
@@ -1409,10 +1503,12 @@ export function registerTools(server, ctx) {
         title: "Request a bounded agent run",
         description: "Ask for an agent session to do one bounded task. The request waits for a person with Miadi's write tier to approve it on the returned approval_url; once approved, a brief is queued for the factory intake, which opens or reaches the session within minutes. Read it back with get_run_result. This is for a new mission only: to change a request that still awaits a decision, call revise_pending_request with its id, so the person keeps one card to decide.",
         inputSchema: {
-            task: z.string().min(1).max(12000).describe("What the session does and what it returns."),
+            task: z.string().min(1).max(12000).describe("What the session does and what it returns. State the result that will exist rather than the mechanism, unless the person asked for the mechanism."),
             circle,
             refs,
             primary_issue: primaryIssue,
+            delivery: deliveryField,
+            person_words: personWordsField,
             session: z.string().regex(/^[A-Za-z0-9._-]{3,80}$/).optional().describe("An existing tmux session to hand it to, or a name for a new one."),
             cwd: z.string().max(300).optional().describe("Working folder for a new session (default: the factory runner's defaultCwd on the host)."),
             provider: z
@@ -1455,12 +1551,15 @@ export function registerTools(server, ctx) {
                 provider: a.provider,
                 resolved_provider: resolution.provider.id,
                 ...(a.primary_issue ? { primary_issue: a.primary_issue } : {}),
+                ...(a.delivery ? { delivery: a.delivery } : {}),
+                ...(a.person_words ? { person_words: a.person_words } : {}),
                 ...(a.steering ? { steering: a.steering } : {}),
             },
         });
         const authorization = providerAuthorizationOf(all().find((x) => x.id === r.id) ?? r);
         return {
             ...r,
+            draft_review: await draftReviewOf(r),
             provider: {
                 requested: a.provider ?? null,
                 resolved: resolution.provider.id,
@@ -1506,6 +1605,8 @@ export function registerTools(server, ctx) {
                 circle: circle.optional(),
                 refs: z.array(z.string()).max(50).optional().describe("The whole new list of refs, replacing the old one."),
                 primary_issue: primaryIssue,
+                delivery: deliveryField,
+                person_words: personWordsField,
                 session: z.string().regex(/^[A-Za-z0-9._-]{3,80}$/).optional(),
                 cwd: z.string().max(300).optional(),
                 provider: z.enum(["codex", "pi", "copilot", "claude"]).optional().describe("Verified installed on the connector host again, as request_authorized_run does."),
@@ -1554,6 +1655,9 @@ export function registerTools(server, ctx) {
         }
         if (c.primary_issue !== undefined)
             body.primary_issue = c.primary_issue;
+        for (const k of ["delivery", "person_words"])
+            if (c[k] !== undefined)
+                body[k] = c[k];
         const nextRefs = withPrimary(c.refs ?? live?.refs ?? [], c.primary_issue ?? body.primary_issue);
         let record;
         try {
@@ -1578,6 +1682,7 @@ export function registerTools(server, ctx) {
         const revisedAuthorization = providerAuthorizationOf(all().find((x) => x.id === (record.supersedes ?? record.id)));
         return {
             ...revisionOut(record.supersedes ? { ...record, id: record.supersedes } : record),
+            draft_review: await draftReviewOf(all().find((x) => x.id === (record.supersedes ?? record.id)) ?? record),
             revised: record.revision,
             ...(provider ? { provider } : {}),
             ...(revisedAuthorization ? { provider_authorization: authorizationOut(revisedAuthorization) } : {}),
@@ -1656,10 +1761,11 @@ export function registerTools(server, ctx) {
     }));
     server.registerTool("request_session_steer", {
         title: "Send one authorized follow-up to a running agent",
-        description: "Steer one existing live agent session within an approved run's steering grant (jgwill/Miadi#893): the exact instruction is typed into the mission's bound pane — never whichever pane is active — after a peek, and a re-peek verifies the agent accepted it. When the approved run carries no steering grant covering this, the steer waits for one explicit scoped human decision on the returned approval_url. Every attempt leaves a durable artifact with its hash and both captures.",
+        description: "Send one correction to a running agent within an approved run's steering grant (jgwill/Miadi#893, #930). Busy is normal: send it while the agent works, once, and do not watch its tools, wait for idle or retry. The connector hands it to the bound session's own inbox, and the agent's runtime presents it to its model at its next continuation in the same turn. The answer's delivery says which state it reached, each with its source and time: forwarded_to_runtime and queued_at_runtime do not show the model read it; delivered_to_agent_context, acknowledged and behavior_adjusted are read from the session's transcript. A provider with no adapter, or a session started before the adapter, answers unsupported with the reason and uses no attempt. An idle seat has no continuation coming, so its steer is typed into the mission's bound pane, never whichever pane is active. When the run's grant does not cover this, the steer waits for one explicit scoped human decision on the returned approval_url. Read it later with get_run_result on the steer's id or with mission_status.",
         inputSchema: {
             run_request: z.string().min(1).describe("The approved run_request or work_proposal whose steering grant covers this steer."),
-            instruction: z.string().min(1).max(4000).describe("The exact instruction typed into the session. It is material within the approved mission's scope, not new authority."),
+            instruction: z.string().min(1).max(4000).describe("The exact instruction for the agent. It is material within the approved mission's scope, not new authority."),
+            expect_next_action: z.string().min(1).max(200).optional().describe("Words to look for in the agent's next tool inputs. When they appear after delivery, the state becomes behavior_adjusted; without this, whether the next actions follow the correction is a person's judgment."),
             session: z.string().regex(/^[A-Za-z0-9._-]{3,80}$/).optional().describe("The session to steer; must be the one the grant binds."),
             pane: z.string().regex(/^\d+\.\d+$/).optional().describe("The pane (window.pane); default the grant's pane, else the session's first pane. The active pane is never used."),
             refs,
@@ -1683,15 +1789,36 @@ export function registerTools(server, ctx) {
         }
         const grant = steeringGrantOf(grantRecord);
         const priorAttempts = steerAttempts(all(), grantRecord.id);
-        const covered = checkGrant(grant, priorAttempts) === "ok";
+        const deliveryOf = (rec) => (ctx.steeringRuntime ? readSteerDelivery(ctx.steeringRuntime, rec) ?? undefined : undefined);
+        const wasSent = (rec) => {
+            const receipt = rec.completion_receipt;
+            return receipt?.typed === true || receipt?.forwarded === true;
+        };
+        const attemptsNow = (counted) => ({ used: steerAttempts(all(), grantRecord.id), ...(grant?.max_attempts !== undefined ? { max: grant.max_attempts } : {}), counted });
+        // The same key after a client's retry or a dropped connection gets the first answer, whatever the grant says by now.
+        if (a.idempotency_key) {
+            const sameKey = all().find((x) => x.kind === "session_steer_request" && x.idempotency_key === a.idempotency_key && x.actor.person_id === person.id && x.refs.includes(grantRecord.id));
+            if (sameKey && wasSent(sameKey))
+                return { ...sameKey, delivery: deliveryOf(sameKey), attempts: attemptsNow(false) };
+            if (sameKey && steersInFlight.has(sameKey.id)) {
+                await steersInFlight.get(sameKey.id);
+                const settled = all().find((x) => x.id === sameKey.id) ?? sameKey;
+                return { ...settled, delivery: deliveryOf(settled), attempts: attemptsNow(false) };
+            }
+        }
+        const revoked = steeringRevoked(all(), grantRecord.id);
+        const covered = checkGrant(grant, priorAttempts, new Date(), revoked) === "ok";
         // The pane the factory delivered this mission to: the steer goes there and nowhere else (jgwill/Miadi#909).
         const bound = receiptsForRecord(receipts(), grantRecord.id)[0];
-        const binding = bound ? { session: bound.tmux_session, ...(bound.pane_id ? { pane_id: bound.pane_id } : {}) } : undefined;
+        const binding = bound
+            ? { session: bound.tmux_session, ...(bound.pane_id ? { pane_id: bound.pane_id } : {}), ...(bound.session_id ? { session_id: bound.session_id } : {}), ...(bound.provider ? { provider: bound.provider } : {}) }
+            : undefined;
         const body = {
             instruction: a.instruction,
             session: a.session ?? bound?.tmux_session ?? grantRecord.body.session,
             pane: a.pane ?? grant?.pane,
-            ...(binding ? { binding: { ...binding, by: "factory_receipt", delivered_at: bound.at, ...(bound.session_id ? { session_id: bound.session_id } : {}) } } : {}),
+            ...(a.expect_next_action ? { expect_next_action: a.expect_next_action } : {}),
+            ...(binding ? { binding: { ...binding, by: "factory_receipt", delivered_at: bound.at } } : {}),
         };
         const fields = {
             circle: grantRecord.circle,
@@ -1709,42 +1836,113 @@ export function registerTools(server, ctx) {
                 ...r,
                 approval_url: approvalUrl(r.id),
                 state: "awaiting_approval",
-                reason: !grant ? "no_grant" : checkGrant(grant, priorAttempts),
+                reason: !grant ? "no_grant" : checkGrant(grant, priorAttempts, new Date(), revoked),
                 message: "The approved run's steering grant does not cover this steer; a person's decision is requested, once, for exactly this instruction.",
             };
         }
         const r = append("session_steer_request", person, auth, { ...fields, approval_state: "not_required" });
-        const result = await steerSession({ tmux: ctx.tmux, stateDir: config.stateDir, ...(ctx.steerSettleMs !== undefined ? { settleMs: ctx.steerSettleMs } : {}) }, { record: r, grantRecord, priorAttempts, ...(binding ? { binding } : {}) });
-        // A typed steer is never "failed": failed is re-runnable, and that would type it twice (#922 R8).
-        const delivered = result.typed;
-        ledger.append({
-            id: newRecordId(r.kind),
-            kind: r.kind,
-            created_at: new Date().toISOString(),
-            actor: r.actor,
-            refs: r.refs,
-            evidence_refs: [],
-            supersedes: r.id,
-            approval_state: "not_required",
-            state: delivered ? "completed" : "blocked",
-            completion_receipt: {
-                decision: "covered_by_grant",
-                decided_by: { person_id: person.id, name: person.name },
-                decided_at: new Date().toISOString(),
-                outcome: delivered ? result.status : "failed",
-                steer_status: result.status,
-                typed: result.typed,
-                message: result.message,
-                ...(result.target ? { target: result.target } : {}),
-                ...(result.artifact ? { artifact: result.artifact } : {}),
-            },
-            body: r.body,
+        const sameWords = all().find((x) => x.kind === "session_steer_request" && x.id !== r.id && x.refs.includes(grantRecord.id) && x.body.instruction === a.instruction && wasSent(x));
+        let finishSend = () => { };
+        steersInFlight.set(r.id, new Promise((resolve) => (finishSend = resolve)));
+        try {
+            const result = await steerSession({ tmux: ctx.tmux, stateDir: config.stateDir, ...(ctx.steeringRuntime ? { runtime: ctx.steeringRuntime } : {}), ...(ctx.steerSettleMs !== undefined ? { settleMs: ctx.steerSettleMs } : {}) }, { record: r, grantRecord, priorAttempts, ...(binding ? { binding } : {}), ...(sameWords ? { sameInstructionSent: sameWords.id } : {}) });
+            // A typed or forwarded steer is never "failed": failed is re-runnable, and that would send it twice (#922 R8).
+            const delivered = result.typed || result.forwarded === true;
+            ledger.append({
+                id: newRecordId(r.kind),
+                kind: r.kind,
+                created_at: new Date().toISOString(),
+                actor: r.actor,
+                refs: r.refs,
+                evidence_refs: [],
+                supersedes: r.id,
+                approval_state: "not_required",
+                // Forwarded is under way: the runtime has not presented it yet, and delivery reads where it stands.
+                state: result.forwarded ? "in_progress" : delivered ? "completed" : "blocked",
+                completion_receipt: {
+                    decision: "covered_by_grant",
+                    decided_by: { person_id: person.id, name: person.name },
+                    decided_at: new Date().toISOString(),
+                    outcome: delivered ? result.status : "failed",
+                    steer_status: result.status,
+                    typed: result.typed,
+                    ...(result.forwarded ? { forwarded: true } : {}),
+                    ...(result.route ? { route: result.route } : {}),
+                    ...(result.transcript_offset !== undefined ? { transcript_offset: result.transcript_offset } : {}),
+                    message: result.message,
+                    ...(result.target ? { target: result.target } : {}),
+                    ...(result.artifact ? { artifact: result.artifact } : {}),
+                },
+                body: r.body,
+            });
+            const stored = all().find((x) => x.id === r.id) ?? r;
+            return {
+                ...(records().find((x) => x.id === r.id) ?? r),
+                delivery: deliveryOf(stored),
+                attempts: attemptsNow(delivered),
+            };
+        }
+        finally {
+            finishSend();
+            steersInFlight.delete(r.id);
+        }
+    }));
+    server.registerTool("revoke_session_steering", {
+        title: "Stop a run's steering, or one steer still waiting",
+        description: "A person stops a correction before its agent reads it (jgwill/Miadi#930). Name the run to stop all further steers under its grant and everything still waiting in its session's inbox, or add steer to stop only that one. The agent's runtime checks again when it would consume it. The answer says exactly what was revoked and what the agent already consumed: a correction already read cannot be taken back.",
+        inputSchema: {
+            run_request: z.string().min(1).describe("The run_request or work_proposal the steering belongs to."),
+            steer: z.string().min(1).optional().describe("One session_steer_request to stop; without it, the run's whole steering grant is revoked."),
+            reason: z.string().min(1).max(1000),
+            refs,
+            ...base,
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = who(extra);
+        requireContribute(auth);
+        requireTier(person, "write");
+        const grantRecord = all().find((r) => r.id === a.run_request);
+        if (!grantRecord || (grantRecord.kind !== "run_request" && grantRecord.kind !== "work_proposal")) {
+            throw new ToolRefusal("invalid_ref", "Give the id of the run_request or work_proposal whose steering this stops.");
+        }
+        if (a.steer) {
+            const steer = all().find((r) => r.id === a.steer);
+            if (!steer || steer.kind !== "session_steer_request" || !steer.refs.includes(grantRecord.id))
+                throw new ToolRefusal("invalid_ref", `${a.steer} is not a steer of ${grantRecord.id}.`);
+        }
+        const r = append("steering_revocation", person, auth, {
+            circle: grantRecord.circle,
+            refs: [grantRecord.id, ...(a.steer ? [a.steer] : []), ...a.refs],
+            intention: a.intention,
+            role: a.role,
+            idempotency_key: a.idempotency_key,
+            body: { reason: a.reason, ...(a.steer ? { steer: a.steer } : {}) },
         });
-        const after = steerAttempts(all(), grantRecord.id);
-        return {
-            ...(records().find((x) => x.id === r.id) ?? r),
-            attempts: { used: after, ...(grant?.max_attempts !== undefined ? { max: grant.max_attempts } : {}), counted: result.typed },
-        };
+        // A steer still waiting for a person's decision is closed too, so approving it later cannot run it.
+        if (a.steer) {
+            const waiting = all().find((x) => x.id === a.steer);
+            if (waiting?.approval_state === "awaiting_approval") {
+                ledger.append({
+                    id: newRecordId(waiting.kind),
+                    kind: waiting.kind,
+                    created_at: new Date().toISOString(),
+                    actor: waiting.actor,
+                    refs: waiting.refs,
+                    evidence_refs: [],
+                    supersedes: waiting.id,
+                    approval_state: "declined",
+                    state: "withdrawn",
+                    completion_receipt: { decision: "revoked", decided_by: { person_id: person.id, name: person.name }, decided_at: new Date().toISOString(), outcome: "revoked", steer_status: "blocked", typed: false, message: a.reason },
+                    body: waiting.body,
+                });
+            }
+        }
+        const sessions = [...new Set(receiptsForRecord(receipts(), grantRecord.id).map((x) => x.session_id).filter((x) => Boolean(x)))];
+        const inboxes = ctx.steeringRuntime
+            ? sessions.map((session_id) => ({ session_id, ...revokeInInbox(ctx.steeringRuntime, session_id, { grant: grantRecord.id, ...(a.steer ? { steer: a.steer } : {}) }, a.reason) }))
+            : [];
+        return { ...r, inboxes, note: a.steer ? "This steer was stopped where it had not been consumed." : "No further steer runs under this grant without a person's decision on that exact steer." };
     }));
     server.registerTool("request_review_operation", {
         title: "Request a review operation",
@@ -1917,6 +2115,78 @@ export function registerTools(server, ctx) {
             research_url: `${config.miadiPublicUrl}/research`,
         };
     }));
+    server.registerTool("list_research_artifacts", {
+        title: "List what is on the inquiry shelf",
+        description: "Reports and folders on Miadi's private inquiry shelf, as you may read them: each one's title, opening, words, sections, sources, files, date, owner, visibility, issue, episodes and, for a saved report, its sha256. All of it is computed from the files, never summarised. scope mine lists what you own; scope all, for Miadi's write tier, lists every folder. Search with query, narrow with kind, order with sort, and page with offset and next_offset. Read one with read_research_artifact. Read only: nothing is changed.",
+        inputSchema: {
+            scope: z.enum(["mine", "all"]).default("mine"),
+            query: z.string().max(200).optional().describe("Words to find in a title, an opening, a heading or a folder's name."),
+            kind: z.enum(["report", "folder", "notes"]).optional().describe("report: saved through a door. folder: holds a document. notes: agent instructions or unreadable files only."),
+            sort: z.enum(["newest", "oldest", "longest", "title"]).default("newest"),
+            limit: z.number().int().min(1).max(200).default(50),
+            offset: z.number().int().min(0).default(0).describe("0, or next_offset from the previous page."),
+        },
+        annotations: READ,
+    }, wrap(async (a, extra) => {
+        const { person } = who(extra);
+        if (!config.inquiryRoot)
+            throw new ToolRefusal("unavailable", "This connector host has no inquiry shelf configured.");
+        try {
+            const { scope, query, kind, sort, limit, offset } = a;
+            return await listShelfArtefacts(config.inquiryRoot, person, {
+                ...(scope ? { scope } : {}),
+                ...(query ? { query } : {}),
+                ...(kind ? { kind } : {}),
+                ...(sort ? { sort } : {}),
+                ...(limit !== undefined ? { limit } : {}),
+                ...(offset !== undefined ? { offset } : {}),
+            });
+        }
+        catch (error) {
+            if (error instanceof ShelfRefusal)
+                throw new ToolRefusal(error.code, error.message);
+            throw error;
+        }
+    }));
+    server.registerTool("read_research_artifact", {
+        title: "Read a document on the inquiry shelf",
+        description: "Read back what is on Miadi's private inquiry shelf, as you: a folder's owner, visibility, its issue, its episodes, the commit that holds it, whether anything on disk differs from that commit, and every file with its bytes and sha256. With the folder's report, or the file you name, you also get its text, in pages when long: pass page.next back; joined, the pages hash to sha256. integrity says whether a saved report's bytes are still the bytes saved. Only the folder's owner or a person with Miadi's write tier can read it. Text files only; hidden files and links are never served. Read only: nothing is changed.",
+        inputSchema: {
+            artefact: z.string().min(1).max(300).describe("The shelf folder's name, inquiry-artefact:<name> or the research_artifact record id save_research returned."),
+            file: z.string().min(1).max(500).optional().describe("A path in the folder, as files lists it. Default: its saved report, if it has one."),
+            offset: z.number().int().min(0).optional().describe("0, or page.next.offset from the previous page."),
+            revision: z.string().regex(/^[0-9a-f]{64}$/).optional().describe("page.next.revision from the previous page: refuses with changed if the file moved since."),
+            max_bytes: z.number().int().min(MIN_PAGE_BYTES).max(MAX_TEXT_BYTES).optional().describe(`Page size in bytes (default ${DEFAULT_PAGE_BYTES}).`),
+        },
+        annotations: READ,
+    }, wrap(async (a, extra) => {
+        const { person } = who(extra);
+        if (!config.inquiryRoot)
+            throw new ToolRefusal("unavailable", "This connector host has no inquiry shelf configured.");
+        const ref = a.artefact.trim();
+        let name = ref.replace(/^inquiry-artefact:/, "");
+        if (ref.startsWith("research_artifact:")) {
+            const held = all().find((r) => r.id === ref && r.kind === "research_artifact");
+            const artefact = held?.body?.artefact;
+            if (typeof artefact !== "string")
+                throw new ToolRefusal("not_found", `No research_artifact ${ref}.`);
+            name = artefact;
+        }
+        try {
+            const { file, offset, revision, max_bytes: maxBytes } = a;
+            return await readShelfArtefact(config.inquiryRoot, name, person, {
+                ...(file !== undefined ? { file } : {}),
+                ...(offset !== undefined ? { offset } : {}),
+                ...(revision !== undefined ? { revision } : {}),
+                ...(maxBytes !== undefined ? { maxBytes } : {}),
+            });
+        }
+        catch (error) {
+            if (error instanceof ShelfRefusal)
+                throw new ToolRefusal(error.code, error.message);
+            throw error;
+        }
+    }));
     server.registerTool("request_inquiry_episode", {
         title: "Request that an inquiry be woven into an episode, or start one",
         description: "Ask that a folder on the inquiry shelf (from save_research) be woven into a Chronicle episode, or that a new episode be started from it. Weaving copies the folder into the episode, so the approval page shows its visibility. Waits for a person's approval; on approval it runs once through Miadi's episode doors.",
@@ -2022,6 +2292,13 @@ export function registerTools(server, ctx) {
                 intention: r.intention,
                 consequence: consequenceOf(r, providerAuthorizationOf(r)),
                 detail: detailOf(r),
+                ...(r.kind === "run_request" || r.kind === "work_proposal"
+                    ? {
+                        delivery: r.body.delivery,
+                        person_words: r.body.person_words,
+                        draft_review: ctx.draftReview?.stored(r) ?? null,
+                    }
+                    : {}),
                 ...(r.kind === "run_request" ? { provider_authorization: authorizationOut(providerAuthorizationOf(r)) } : {}),
                 approval_url: approvalUrl(r.id),
                 projection: requestProjection(r, { reviewBase: ctx.approval?.config.reviewUrl, factoryDir: ctx.factoryDir }),
@@ -2227,20 +2504,23 @@ export const TOOL_STATUS = {
     register_source_intent: "live, contribute",
     record_handoff: "live, contribute",
     update_handoff: "live, contribute",
-    propose_work: "live, contribute, needs_approval (approving starts the work as a factory run)",
+    propose_work: "live, contribute, needs_approval (approving starts the work as a factory run; answers with draft_review)",
     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; may name a verified provider and a bounded steering grant)",
-    revise_pending_request: "live, contribute (a waiting or sent-back run or proposal gets its next version; same id, same card)",
+    request_authorized_run: "live, contribute, needs_approval (queues a factory brief once approved; may name a verified provider and a bounded steering grant; answers with draft_review)",
+    revise_pending_request: "live, contribute (a waiting or sent-back run or proposal gets its next version; same id, same card; answers with draft_review)",
     get_request_history: "live (every version of a request, oldest first; whoever asked, or the write tier)",
     supersede_pending_requests: "live, contribute (retires named earlier requests still waiting and joins them as earlier versions of the one that stands)",
-    request_session_steer: "live, contribute, write tier (runs inside an approved run's steering grant, else one scoped human decision; get_capabilities.steering says whether the transport works now)",
+    request_session_steer: "live, contribute, write tier (one correction to a working agent, forwarded to its runtime; runs inside an approved run's steering grant, else one scoped human decision; get_capabilities.steering says whether the transport works now and which providers have an adapter)",
+    revoke_session_steering: "live, contribute, write tier (stops a run's steering, or one steer not yet consumed)",
     request_review_operation: "live, contribute, needs_approval",
     request_screenwalk_reading: "live, contribute, needs_approval (host provider adapter required; stops at editorial decision)",
     request_reading_import: "live, contribute, needs_approval (exact public import; atomic service contract required)",
     request_deep_diver: "live, contribute, needs_approval",
     link_review_to_episode: "live, contribute, needs_approval",
     save_research: "live, contribute (the whole report, in parts when long; saved on the inquiry shelf with its issue, pushed; private by default)",
+    list_research_artifacts: "live (the shelf as you may read it: yours, or every folder for the write tier; searched, sorted, paged)",
+    read_research_artifact: "live (a shelf folder's manifest and its text files, paged, with sha256 and the commit that holds them; its owner or Miadi's write tier)",
     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/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.20";
+export declare const VERSION = "0.1.22";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.1.20";
+export const VERSION = "0.1.22";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/connector",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "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",
@@ -16,6 +16,18 @@
       "types": "./dist/records.d.ts",
       "import": "./dist/records.js"
     },
+    "./research-digest": {
+      "types": "./dist/research-digest.d.ts",
+      "import": "./dist/research-digest.js"
+    },
+    "./runtime-steer": {
+      "types": "./dist/runtime-steer.d.ts",
+      "import": "./dist/runtime-steer.js"
+    },
+    "./research-shelf": {
+      "types": "./dist/research-shelf.d.ts",
+      "import": "./dist/research-shelf.js"
+    },
     "./package.json": "./package.json"
   },
   "bin": {
@@ -26,7 +38,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@miadi/inquiry-weave": "0.18.8",
+    "@miadi/inquiry-weave": "0.18.10",
     "@miadi/node-service-kit": "0.1.2",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "express": "^5.2.1",