@miadi/connector 0.1.20 → 0.1.22

package/dist/runtime-steer.js

@@ -0,0 +1,543 @@
+/**
+ * The connector's half of the terminal-agent steering contract (jgwill/Miadi#930).
+ *
+ * The connector admits a correction and hands it to the bound session's own inbox. It never
+ * watches tools, never waits for idle and never decides when the model reads it: that is the
+ * runtime's. For Claude Code the runtime half is the hook adapter in the kit plugin
+ * miadi-session-observability (hooks/steering_inbox.mjs), which holds the file contract:
+ * <root>/<session_id>/{adapter.json,pending,claimed,expired,withdrawn,rejected,revoked,receipts.jsonl}.
+ *
+ * Other providers have no adapter here, so they answer unsupported with the exact reason. Claude
+ * Code's hook semantics are never assumed of Copilot, Pi or Codex.
+ *
+ * Delivery is read from its own evidence: the connector's write, the runtime hook's receipt and
+ * the transcript record Claude Code itself wrote. A pane echo or a spinner is none of these.
+ */
+import { createHash } from "node:crypto";
+import { appendFileSync, closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { factoryDir } from "./queue-state.js";
+export const STEER_PROTOCOL = 1;
+/** A correction no continuation consumed in a day is stale: the work has moved on. A grant's own expiry comes sooner when it has one. */
+export const ENVELOPE_TTL_MS = 24 * 60 * 60 * 1000;
+export const CLAUDE_ADAPTER = "miadi-session-observability 0.1.34 or later";
+const INBOX_DIRS = ["pending", "claimed", "expired", "withdrawn", "rejected"];
+/** How much transcript one read scans after the steer was queued. */
+const MAX_TRANSCRIPT_SCAN = 32 * 1024 * 1024;
+const MAX_NEXT_ACTIONS = 5;
+export const DELIVERY_STATES = [
+    "authorized",
+    "forwarded_to_runtime",
+    "queued_at_runtime",
+    "delivered_to_agent_context",
+    "acknowledged",
+    "behavior_adjusted",
+    "unsupported",
+    "expired",
+    "blocked",
+    "unknown",
+];
+export function steeringRoot(env = process.env) {
+    return env.MIADI_STEERING_DIR || join(factoryDir(env), "steering");
+}
+export function defaultRuntime(env = process.env) {
+    return { root: steeringRoot(env), claudeDir: env.CLAUDE_CONFIG_DIR || join(env.HOME || homedir(), ".claude") };
+}
+const safe = (id) => id.replace(/[^\w-]/g, "-");
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+const statOrNull = (path) => {
+    try {
+        return lstatSync(path);
+    }
+    catch {
+        return null;
+    }
+};
+const readJson = (path) => {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+};
+/** The token the agent names back in its own text: the same rule as the adapter's ackToken. */
+export const ackToken = (steerId) => `steer ${safe(steerId).replace(/^session_steer_request-/, "").slice(0, 8)}`;
+/** Claude Code's own record of a running session, `<claudeDir>/sessions/<pid>.json`, if its process lives. */
+export function readClaudeSession(deps, sessionId) {
+    const dir = join(deps.claudeDir, "sessions");
+    const alive = deps.isAlive ??
+        ((pid) => {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+    let names;
+    try {
+        names = readdirSync(dir).filter((n) => /^\d+\.json$/.test(n));
+    }
+    catch {
+        return null;
+    }
+    for (const name of names) {
+        const r = readJson(join(dir, name));
+        if (r?.sessionId === sessionId && typeof r.pid === "number" && alive(r.pid))
+            return r;
+    }
+    return null;
+}
+/**
+ * Mission → session → runtime, from what each one signed: the runner's receipt names the session,
+ * Claude Code's registry says it runs and in which pane, and the adapter's file says this session
+ * loaded its hooks. The inbox belongs to this Unix account alone or it is not used.
+ */
+export function resolveRuntime(deps, binding) {
+    const { session_id, pane_id, provider } = binding;
+    if (provider && provider !== "claude") {
+        return { route: "none", code: "unsupported", reason: `No steering adapter is installed for provider "${provider}". Claude Code's hooks are not assumed of it.` };
+    }
+    if (!session_id)
+        return { route: "none", code: "unsupported", reason: "The mission's binding names no session id, so no exact session's inbox can be addressed." };
+    const record = readClaudeSession(deps, session_id);
+    if (!record)
+        return { route: "none", code: "stale_binding", reason: `Claude Code session ${session_id} is not running on this host.` };
+    const seatPane = record.tmux?.match(/%\d+$/)?.[0];
+    if (pane_id && seatPane && seatPane !== pane_id) {
+        return { route: "none", code: "wrong_pane", reason: `Claude Code session ${session_id} is in pane ${seatPane}, not ${pane_id}, the pane its mission is bound to.` };
+    }
+    const dir = join(deps.root, safe(session_id));
+    const st = statOrNull(dir);
+    const adapter = st?.isDirectory() && st.uid === process.getuid?.() && (st.mode & 0o022) === 0 ? readJson(join(dir, "adapter.json")) : null;
+    if (!adapter || adapter.protocol !== STEER_PROTOCOL || adapter.session_id !== session_id) {
+        return {
+            route: "none",
+            code: "unsupported",
+            reason: `Claude Code session ${session_id} has no steering adapter loaded. Hooks load at session start, so a session started before ${CLAUDE_ADAPTER} cannot receive a correction mid-turn.`,
+        };
+    }
+    return { route: "claude_hook_inbox", session_id, seat: record.status ?? "unknown", ...(typeof adapter.transcript_path === "string" ? { transcript_path: adapter.transcript_path } : {}) };
+}
+function findEnvelope(root, sessionId, steer) {
+    const dir = join(root, safe(sessionId));
+    const suffix = `-${safe(steer)}.json`;
+    for (const state of INBOX_DIRS) {
+        let names;
+        try {
+            names = readdirSync(join(dir, state));
+        }
+        catch {
+            continue;
+        }
+        const name = names.find((n) => n.endsWith(suffix));
+        if (name)
+            return { state, file: join(dir, state, name), envelope: readJson(join(dir, state, name)) };
+    }
+    return null;
+}
+/** The steer already on its way with these same words under this grant: one correction, one delivery. */
+export function sameInstructionInFlight(deps, sessionId, grant, instruction) {
+    const dir = join(deps.root, safe(sessionId));
+    const hash = sha256(instruction);
+    for (const state of ["pending", "claimed"]) {
+        let names;
+        try {
+            names = readdirSync(join(dir, state));
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            const e = readJson(join(dir, state, name));
+            if (e?.grant === grant && e.instruction_sha256 === hash)
+                return e.steer;
+        }
+    }
+    return null;
+}
+/**
+ * Put one correction in the session's inbox, durably: fsync, then one rename into pending/, so the
+ * adapter never reads half a file. The steer's id keeps it single across a retry or a connector restart.
+ */
+export function enqueueSteer(deps, args) {
+    const known = findEnvelope(deps.root, args.session_id, args.steer);
+    if (known?.envelope)
+        return { already: true, file: known.file, envelope: known.envelope };
+    const now = args.now ?? new Date();
+    const dir = join(deps.root, safe(args.session_id));
+    const pending = join(dir, "pending");
+    mkdirSync(pending, { recursive: true, mode: 0o700 });
+    const ttl = now.getTime() + ENVELOPE_TTL_MS;
+    const grantEnd = args.grant_expires_at ? Date.parse(args.grant_expires_at) : NaN;
+    const envelope = {
+        protocol: STEER_PROTOCOL,
+        steer: args.steer,
+        grant: args.grant,
+        session_id: args.session_id,
+        instruction: args.instruction,
+        instruction_sha256: sha256(args.instruction),
+        from: args.from,
+        queued_at: now.toISOString(),
+        expires_at: new Date(Number.isNaN(grantEnd) ? ttl : Math.min(ttl, grantEnd)).toISOString(),
+        ...(args.decided ? { decided: true } : {}),
+        ...(args.transcript_path ? { transcript_path: args.transcript_path, transcript_offset: transcriptSize(args.transcript_path) } : {}),
+    };
+    // Ordered by name: never before an envelope already waiting.
+    const last = readdirSync(pending).filter((n) => n.endsWith(".json")).sort().at(-1);
+    const order = Math.max(now.getTime(), last ? Number(last.split("-")[0]) + 1 : 0);
+    const name = `${String(order).padStart(15, "0")}-${safe(args.steer)}.json`;
+    const tmp = join(dir, `.tmp-${safe(args.steer)}`);
+    const fd = openSync(tmp, "w", 0o600);
+    try {
+        writeSync(fd, JSON.stringify(envelope));
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmp, join(pending, name));
+    return { already: false, file: join(pending, name), envelope };
+}
+function transcriptSize(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Revoke a grant or one steer for this session. The marker stops whatever the adapter would consume
+ * next, and what is still pending moves out at once. A rename decides any race with the adapter,
+ * so the answer is exact: revoked here, or already consumed.
+ */
+export function revokeInInbox(deps, sessionId, target, reason) {
+    const dir = join(deps.root, safe(sessionId));
+    const out = { revoked: [], already_consumed: [] };
+    if (!statOrNull(dir))
+        return out;
+    mkdirSync(join(dir, "revoked"), { recursive: true, mode: 0o700 });
+    writeFileSync(join(dir, "revoked", safe(target.steer ?? target.grant)), `${JSON.stringify({ reason, at: new Date().toISOString() })}\n`, { mode: 0o600 });
+    const pending = join(dir, "pending");
+    mkdirSync(join(dir, "withdrawn"), { recursive: true, mode: 0o700 });
+    let names = [];
+    try {
+        names = readdirSync(pending);
+    }
+    catch {
+        // Nothing queued.
+    }
+    for (const name of names) {
+        const e = readJson(join(pending, name));
+        if (!e || e.grant !== target.grant || (target.steer && e.steer !== target.steer))
+            continue;
+        try {
+            renameSync(join(pending, name), join(dir, "withdrawn", name));
+            appendFileSync(join(dir, "receipts.jsonl"), `${JSON.stringify({ at: new Date().toISOString(), source: "connector", steer: e.steer, state: "revoked", reason })}\n`, { mode: 0o600 });
+            out.revoked.push(e.steer);
+        }
+        catch {
+            out.already_consumed.push(e.steer);
+        }
+    }
+    // What the agent's runtime already took cannot be stopped, and the answer says which.
+    let taken = [];
+    try {
+        taken = readdirSync(join(dir, "claimed"));
+    }
+    catch {
+        // Nothing consumed yet.
+    }
+    for (const name of taken) {
+        const e = readJson(join(dir, "claimed", name));
+        if (!e || e.grant !== target.grant || (target.steer && e.steer !== target.steer) || out.already_consumed.includes(e.steer))
+            continue;
+        out.already_consumed.push(e.steer);
+    }
+    return out;
+}
+function readTail(path, offset) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const size = statSync(path).size;
+        const start = Math.max(Math.min(offset, size), size - MAX_TRANSCRIPT_SCAN);
+        const buffer = Buffer.alloc(size - start);
+        readSync(fd, buffer, 0, buffer.length, start);
+        return buffer.toString("utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+const textOf = (content) => {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content.map((b) => (b && typeof b === "object" && b.type === "text" ? String(b.text ?? "") : "")).join("\n");
+};
+/**
+ * What Claude Code itself recorded about this steer. Only an attachment naming the steer's id shows
+ * it entered the model's context, and only the agent's own later text can acknowledge it. Tool
+ * results and the agent's quotes of the id do not count as delivery.
+ */
+export function readTranscriptEvidence(path, offset, steer) {
+    const out = { next_actions: [], actions_seen: 0, raw_inputs: [] };
+    const text = readTail(path, offset);
+    if (text === null)
+        return out;
+    const token = `${ackToken(steer)} received`.toLowerCase();
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        if (!out.delivered && !line.includes(steer))
+            continue;
+        let d;
+        try {
+            d = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!out.delivered) {
+            // Claude Code writes hook_success with the hook's stdout first: that shows the hook exited. These show it entered the context.
+            const admitted = d.type === "attachment" && ["hook_additional_context", "hook_blocking_error", "queued_command"].includes(d.attachment?.type);
+            // A woken model reads it as a meta user message, never a tool result that quotes the id.
+            const wakeMessage = d.type === "user" && d.isMeta === true && textOf(d.message?.content).includes(steer);
+            if (!admitted && !wakeMessage)
+                continue;
+            out.delivered = {
+                at: d.timestamp,
+                attachment: admitted ? d.attachment.type : "meta_user_message",
+                hook_event: admitted ? (d.attachment.hookEvent ?? "Stop") : "Stop",
+                ...(admitted && d.attachment.toolUseID ? { tool_use_id: d.attachment.toolUseID } : {}),
+            };
+            continue;
+        }
+        if (d.type !== "assistant")
+            continue;
+        const content = d.message?.content;
+        const said = textOf(content);
+        if (!out.acknowledged && said.toLowerCase().includes(token))
+            out.acknowledged = { at: d.timestamp, text: said.slice(0, 500) };
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (block?.type !== "tool_use")
+                continue;
+            out.actions_seen++;
+            const input = JSON.stringify(block.input ?? {});
+            if (out.next_actions.length < MAX_NEXT_ACTIONS) {
+                out.next_actions.push({ at: d.timestamp, tool: String(block.name), input: input.slice(0, 200) });
+                out.raw_inputs.push(input);
+            }
+        }
+    }
+    return out;
+}
+/** Whether a prompt typed into the bound pane reached the session: Claude Code's own user or queued-prompt record. A pane echo proves nothing. */
+export function typedLineInTranscript(path, offset, instruction) {
+    const text = readTail(path, offset);
+    if (text === null)
+        return null;
+    const firstLine = instruction.split("\n")[0].slice(0, 80);
+    if (!firstLine.trim())
+        return null;
+    const needle = JSON.stringify(firstLine).slice(1, -1);
+    for (const line of text.split("\n")) {
+        if (!line.includes(needle))
+            continue;
+        try {
+            const d = JSON.parse(line);
+            if (d.type === "attachment" && d.attachment?.type === "queued_command")
+                return { at: d.timestamp, record: "queued_command" };
+            // The person's prompt, never a tool's output that quotes the words.
+            if (d.type === "user" && textOf(d.message?.content).includes(firstLine))
+                return { at: d.timestamp, record: "user" };
+        }
+        catch {
+            // A partial last line: the next read has it whole.
+        }
+    }
+    return null;
+}
+/** Find a session's transcript when its adapter did not name it. */
+export function transcriptPathOf(deps, sessionId) {
+    const adapter = readJson(join(deps.root, safe(sessionId), "adapter.json"));
+    if (typeof adapter?.transcript_path === "string")
+        return adapter.transcript_path;
+    const projects = join(deps.claudeDir, "projects");
+    try {
+        for (const project of readdirSync(projects)) {
+            const file = join(projects, project, `${sessionId}.jsonl`);
+            if (existsSync(file))
+                return file;
+        }
+    }
+    catch {
+        // No projects folder: no transcript to read.
+    }
+    return undefined;
+}
+/**
+ * Where one steer stands, each state with its source and time, for request_session_steer,
+ * mission_status and get_run_result. It only reads, and it can be read at any time: ChatGPT
+ * disconnecting or the connector restarting changes nothing here.
+ */
+export function readSteerDelivery(deps, record, now = new Date()) {
+    const receipt = record.completion_receipt;
+    if (!receipt)
+        return null;
+    const binding = record.body.binding;
+    const route = String(receipt.route ?? (receipt.typed ? "tmux_exact_pane" : "none"));
+    const session_id = binding?.session_id;
+    const receipts = [];
+    const authorizedAt = receipt.decided_at;
+    receipts.push({ state: "authorized", at: authorizedAt, source: "connector", detail: { by: receipt.decided_by, decision: receipt.decision } });
+    const base = { route, ...(session_id ? { session_id } : {}) };
+    if (route === "tmux_exact_pane") {
+        receipts.push({ state: "seat_was_idle", at: authorizedAt, source: "connector", detail: { target: receipt.target } });
+        receipts.push({ state: "forwarded_to_runtime", at: authorizedAt, source: "connector", detail: { target: receipt.target, typed: receipt.typed } });
+        const path = session_id ? transcriptPathOf(deps, session_id) : undefined;
+        const landed = path ? typedLineInTranscript(path, Number(receipt.transcript_offset ?? 0), String(record.body.instruction ?? "")) : null;
+        if (landed) {
+            receipts.push({ state: "delivered_to_agent_context", at: landed.at, source: "claude_transcript", detail: { record: landed.record } });
+            return { ...base, state: "delivered_to_agent_context", receipts, note: "Claude Code recorded the prompt in the session's transcript." };
+        }
+        return { ...base, state: "unknown", receipts, note: "It was typed into the bound pane of an idle seat. No transcript record of it has been read, and a pane echo is not proof the model read it." };
+    }
+    if (route !== "claude_hook_inbox" || !session_id) {
+        const status = String(receipt.steer_status ?? "");
+        const state = status === "unsupported" ? "unsupported" : status === "expired_grant" ? "expired" : "blocked";
+        return { ...base, state, receipts, note: String(receipt.message ?? "Nothing was forwarded.") };
+    }
+    const found = findEnvelope(deps.root, session_id, record.id);
+    const forwardedAt = found?.envelope?.queued_at ?? authorizedAt;
+    receipts.push({ state: "forwarded_to_runtime", at: forwardedAt, source: "connector", detail: { route } });
+    if (!found)
+        return { ...base, state: "unknown", receipts, note: "The session's inbox no longer holds this steer, so where it went cannot be read." };
+    receipts.push({ state: "queued_at_runtime", at: forwardedAt, source: "runtime_inbox", detail: { file: found.file, expires_at: found.envelope?.expires_at } });
+    const hook = hookReceipts(deps.root, session_id, record.id);
+    for (const r of hook) {
+        if (r.state === "emitted") {
+            const { at, state: _state, source: _source, steer: _steer, ...detail } = r;
+            receipts.push({ state: "runtime_hook_emitted", at, source: "runtime_hook", detail });
+        }
+    }
+    const refused = hook.find((r) => r.state === "expired" || r.state === "revoked" || r.state === "blocked");
+    if (found.state === "pending") {
+        const expiresAt = found.envelope?.expires_at;
+        if (expiresAt && Date.parse(expiresAt) <= now.getTime()) {
+            receipts.push({ state: "expired", at: expiresAt, source: "connector_clock" });
+            return { ...base, state: "expired", receipts, note: "It expired in the inbox before any continuation consumed it. It will not reach the model." };
+        }
+        const seat = readClaudeSession(deps, session_id);
+        for (const r of hook.filter((x) => x.state === "woken"))
+            receipts.push({ state: "seat_woken", at: r.at, source: "factory_runner", detail: { pane: r.pane } });
+        if (!seat)
+            return { ...base, state: "queued_at_runtime", continuation: "session_not_running", receipts, note: `It waits in the inbox of a session that is not running. It reaches the model if that session resumes before ${expiresAt}, and otherwise expires.` };
+        if (seat.status === "idle")
+            return { ...base, state: "queued_at_runtime", continuation: "runner_wakes_idle_seat", receipts, note: "The seat went idle before a continuation carried it. The factory runner's next pass, within minutes, prompts the seat, and the correction arrives with that prompt. Nobody has to send it again." };
+        return { ...base, state: "queued_at_runtime", continuation: "next_tool_or_turn_end", receipts, note: "It waits in the session's inbox. The agent's next tool end, or the end of its turn, presents it. This does not yet show the model read it." };
+    }
+    if (found.state === "expired") {
+        receipts.push({ state: "expired", at: refused?.at, source: "runtime_hook", detail: { reason: refused?.reason } });
+        return { ...base, state: "expired", receipts, note: "It expired before a continuation consumed it. It never reached the model." };
+    }
+    if (found.state === "withdrawn" || found.state === "rejected") {
+        receipts.push({ state: "blocked", at: refused?.at, source: refused?.source === "connector" ? "connector" : "runtime_hook", detail: { reason: refused?.reason, moved_to: found.state } });
+        return { ...base, state: "blocked", receipts, note: `It never reached the model: ${refused?.reason ?? found.state}.` };
+    }
+    // Claimed: taken for delivery, exactly once, never again whatever happens next.
+    const path = found.envelope?.transcript_path;
+    const evidence = path ? readTranscriptEvidence(path, found.envelope?.transcript_offset ?? 0, record.id) : null;
+    if (!evidence?.delivered) {
+        const emitted = hook.some((r) => r.state === "emitted");
+        return {
+            ...base,
+            state: "unknown",
+            receipts,
+            note: emitted
+                ? "The runtime hook printed it, and the transcript does not show it entered the model's context yet."
+                : "The hook claimed it and left no receipt, so delivery is ambiguous. It is not sent again.",
+        };
+    }
+    receipts.push({ state: "delivered_to_agent_context", at: evidence.delivered.at, source: "claude_transcript", detail: { attachment: evidence.delivered.attachment, hook_event: evidence.delivered.hook_event, tool_use_id: evidence.delivered.tool_use_id } });
+    let state = "delivered_to_agent_context";
+    if (evidence.acknowledged) {
+        state = "acknowledged";
+        receipts.push({ state: "acknowledged", at: evidence.acknowledged.at, source: "claude_transcript", detail: { text: evidence.acknowledged.text } });
+    }
+    const expect = typeof record.body.expect_next_action === "string" ? record.body.expect_next_action : undefined;
+    let behavior = evidence.actions_seen ? "not_judged" : "not_observed_yet";
+    if (expect && evidence.actions_seen) {
+        const seen = evidence.raw_inputs.findIndex((i) => i.includes(JSON.stringify(expect).slice(1, -1)));
+        behavior = seen >= 0 ? "expected_action_seen" : "expected_action_not_seen";
+        if (seen >= 0) {
+            state = "behavior_adjusted";
+            receipts.push({ state: "behavior_adjusted", at: evidence.next_actions[seen]?.at, source: "claude_transcript", detail: { expected: expect, action: evidence.next_actions[seen] } });
+        }
+    }
+    return {
+        ...base,
+        state,
+        receipts,
+        next_actions: evidence.next_actions,
+        behavior,
+        note: state === "behavior_adjusted"
+            ? "The transcript shows the action this steer named, after it entered the model's context."
+            : "The transcript shows it entered the model's context. Whether the next actions follow it is a person's judgment unless the steer named expect_next_action.",
+    };
+}
+function hookReceipts(root, sessionId, steer) {
+    let text;
+    try {
+        text = readFileSync(join(root, safe(sessionId), "receipts.jsonl"), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const r = JSON.parse(line);
+            if (r.steer === steer)
+                out.push(r);
+        }
+        catch {
+            // A torn line is not a receipt.
+        }
+    }
+    return out;
+}
+/**
+ * What a forwarded steer's ledger record should now say, from its delivery: done once the model has
+ * it, stopped once it never will. Null while it is still on its way, or if it has already settled.
+ */
+export function settlementOf(deps, record, now = new Date()) {
+    if (record.state !== "in_progress" || record.completion_receipt?.forwarded !== true)
+        return null;
+    const delivery = readSteerDelivery(deps, record, now);
+    if (!delivery)
+        return null;
+    const at = delivery.receipts.filter((r) => r.state === delivery.state).at(-1)?.at;
+    if (delivery.state === "delivered_to_agent_context" || delivery.state === "acknowledged" || delivery.state === "behavior_adjusted") {
+        return { state: "completed", outcome: delivery.state, message: delivery.note, ...(at ? { at } : {}) };
+    }
+    if (delivery.state === "expired" || delivery.state === "blocked") {
+        return { state: "blocked", outcome: delivery.state, message: delivery.note, ...(at ? { at } : {}) };
+    }
+    return null;
+}

package/dist/server.d.ts

@@ -1,3 +1,15 @@
+/**
+ * The connector's HTTP surface:
+ *
+ *   /.well-known/oauth-*        OAuth discovery (MCP authorization spec)
+ *   /authorize /token /register /revoke, /authorize/confirm   sign-in
+ *   /mcp                        the MCP endpoint (streamable HTTP, stateless)
+ *   /health                     liveness, no data
+ *
+ * Every MCP request carries the signed-in person, and each tool call runs
+ * as that person (see tools.ts).
+ */
+import type { RuntimeDeps } from "./runtime-steer.js";
 import { MiadiOAuthProvider } from "./oauth.js";
 import type { MiadiPerson } from "./people.js";
 import { Ledger } from "./store.js";
@@ -6,6 +18,7 @@ import type { ConnectorConfig } from "./config.js";
 import type { TmuxLike } from "./steer.js";
 import type { DiscoveryProbe, ProviderId } from "./providers.js";
 import type { JevAdapter } from "./model-preflight.js";
+import type { StandardSource } from "./mission-standard.js";
 export interface ConnectorDeps {
     identify: (token: string) => Promise<MiadiPerson | null>;
     fetchImpl?: typeof fetch;
@@ -19,8 +32,14 @@ export interface ConnectorDeps {
     /** A provider's configured default model and a Jev decider (jgwill/Miadi#913); tests inject fakes. */
     modelOf?: (provider: ProviderId) => string | null;
     jevAdapter?: JevAdapter;
+    /** The environment the draft review reads its keys from (default process.env); tests pass their own (jgwill/Miadi#939). */
+    draftReviewEnv?: NodeJS.ProcessEnv;
+    /** Where the mission standard comes from (default the prompt store, then the built-in copy); tests pass their own. */
+    standardSource?: StandardSource;
     /** Re-peek delay after a steer is typed (default 4000ms; tests pass 0). */
     steerSettleMs?: number;
+    /** Where sessions and their steering inboxes live (jgwill/Miadi#930). */
+    steeringRuntime?: RuntimeDeps;
     /** Person-token attempts allowed per address in 15 minutes on each sign-in form (default 30). */
     tokenAttemptsPerWindow?: number;
     /** Where decision events go (default: one JSON line on stdout, the service journal); tests collect them (jgwill/Miadi#924). */
@@ -31,4 +50,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\nEvery tool is offered on every connection. A client that loads tools on demand shows only those its last tool search matched: a tool you do not see is not missing. Search for it by its exact name, get_capabilities first, before telling the person a tool is absent. The main reads are get_capabilities, get_context, search, fetch, list_records, list_sessions, get_session, review_lookup, read_episode_file and show_decisions.\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 revise it in place with revise_pending_request), or decline.\n- A mission is revised, never re-requested: to change a run or work proposal that still awaits a decision, call revise_pending_request with its id and the version you read (expected_version). It keeps one id, one approval page and one card; get_request_history shows every version. A new request_authorized_run or propose_work is for a new mission only. Requests made earlier as separate versions are joined with supersede_pending_requests, naming their exact ids, only when the person names or confirms them.\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.";
+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\nEvery tool is offered on every connection. A client that loads tools on demand shows only those its last tool search matched: a tool you do not see is not missing. Search for it by its exact name, get_capabilities first, before telling the person a tool is absent. The main reads are get_capabilities, get_context, search, fetch, list_records, list_sessions, get_session, review_lookup, read_episode_file and show_decisions.\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 revise it in place with revise_pending_request), or decline.\n- A new or revised run or work proposal answers with draft_review: the aspects of the mission standard to revise, each with why, the question to settle and who can settle it. Read it before show_decisions. It carries no verdict, it advises and blocks nothing, and next_action says what to do. Answer what your conversation holds, ask the person the rest, then revise. preferences lists the person's standing preferences for you to apply. Fill delivery with the one exact place the result lands, and person_words with the person's own words, verbatim, for anything credited to them.\n- A mission is revised, never re-requested: to change a run or work proposal that still awaits a decision, call revise_pending_request with its id and the version you read (expected_version). It keeps one id, one approval page and one card; get_request_history shows every version. A new request_authorized_run or propose_work is for a new mission only. Requests made earlier as separate versions are joined with supersede_pending_requests, naming their exact ids, only when the person names or confirms them.\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

@@ -1,14 +1,3 @@
-/**
- * The connector's HTTP surface:
- *
- *   /.well-known/oauth-*        OAuth discovery (MCP authorization spec)
- *   /authorize /token /register /revoke, /authorize/confirm   sign-in
- *   /mcp                        the MCP endpoint (streamable HTTP, stateless)
- *   /health                     liveness, no data
- *
- * Every MCP request carries the signed-in person, and each tool call runs
- * as that person (see tools.ts).
- */
 import express from "express";
 import { rateLimit } from "express-rate-limit";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -22,6 +11,7 @@ import { JsonFile, Ledger, ensureStateDir, statePaths } from "./store.js";
 import { registerTools } from "./tools.js";
 import { MiadiClient } from "./miadi.js";
 import { ReviewClient } from "./reviews.js";
+import { draftReviewService } from "./draft-review.js";
 import { VERSION } from "./version.js";
 export function createConnectorApp(config, deps) {
     ensureStateDir(config.stateDir);
@@ -77,8 +67,10 @@ export function createConnectorApp(config, deps) {
     app.post("/authorize/confirm", confirmLimit, express.urlencoded({ extended: false, limit: "16kb" }), (req, res, next) => {
         provider.confirm(req, res).catch(next);
     });
+    const draftReview = draftReviewService({ stateDir: config.stateDir, fetchImpl: deps.fetchImpl, adapter: deps.jevAdapter, env: deps.draftReviewEnv, source: deps.standardSource });
     const approvalDeps = {
         config,
+        draftReview,
         ledger,
         miadi,
         identify: deps.identify,
@@ -87,6 +79,7 @@ export function createConnectorApp(config, deps) {
         tmuxSessions: deps.tmuxSessions,
         tmux: deps.tmux,
         steerSettleMs: deps.steerSettleMs,
+        ...(deps.steeringRuntime ? { steeringRuntime: deps.steeringRuntime } : {}),
         log: deps.log,
     };
     // A run the connector was recording when it last stopped is failed now, so a person may run it again (#924).
@@ -126,7 +119,9 @@ export function createConnectorApp(config, deps) {
             providersProbe: deps.providersProbe,
             modelOf: deps.modelOf,
             jevAdapter: deps.jevAdapter,
+            draftReview,
             steerSettleMs: deps.steerSettleMs,
+            ...(deps.steeringRuntime ? { steeringRuntime: deps.steeringRuntime } : {}),
         };
         const server = new McpServer({ name: "miadi", version: VERSION }, { instructions: INSTRUCTIONS });
         registerTools(server, ctx);
@@ -164,6 +159,7 @@ Every tool is offered on every connection. A client that loads tools on demand s
 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, 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 revise it in place with revise_pending_request), or decline.
+- A new or revised run or work proposal answers with draft_review: the aspects of the mission standard to revise, each with why, the question to settle and who can settle it. Read it before show_decisions. It carries no verdict, it advises and blocks nothing, and next_action says what to do. Answer what your conversation holds, ask the person the rest, then revise. preferences lists the person's standing preferences for you to apply. Fill delivery with the one exact place the result lands, and person_words with the person's own words, verbatim, for anything credited to them.
 - A mission is revised, never re-requested: to change a run or work proposal that still awaits a decision, call revise_pending_request with its id and the version you read (expected_version). It keeps one id, one approval page and one card; get_request_history shows every version. A new request_authorized_run or propose_work is for a new mission only. Requests made earlier as separate versions are joined with supersede_pending_requests, naming their exact ids, only when the person names or confirms them.
 - 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.