@miadi/connector 0.1.15 → 0.1.17

package/dist/tools.js

@@ -23,6 +23,9 @@ import { discoverProviders, jevConfigOf, resolveProvider, routerPreflight, PROVI
 import { authorizesActions, missionStatus, primaryIssueOf, resolveMissionSubject } from "./mission-status.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 { factoryLedgerPath, readFactoryReceipts, receiptsForRecord, recordsForSession } from "./factory-receipt.js";
+import { missionResult, redactResult } from "./mission-result.js";
+import { factoryDir as defaultFactoryDir } from "./queue-state.js";
 import { join } from "node:path";
 import { artefactVisibility, readArtefactWeave, saveResearchArtefact } from "@miadi/inquiry-weave";
 import { ResearchUploads, UploadRefusal } from "./uploads.js";
@@ -109,6 +112,46 @@ export function githubAccess(status, hasToken) {
         return "forbidden_or_rate_limited";
     return `github_${status}`;
 }
+/** GitHub answers kept briefly, so one status read does not spend the unauthenticated rate limit twice. */
+const githubCache = new Map();
+const GITHUB_CACHE_MS = 5 * 60_000;
+/** A GitHub REST read as the connector can make it: GITHUB_TOKEN when the host has one, else anonymous. */
+export function githubGetter(fetchImpl = fetch, token = process.env.GITHUB_TOKEN) {
+    return async (path) => {
+        // Keyed by whether a token was sent: an anonymous 404 is not a token's answer (#922 R9).
+        const key = `${token ? "token" : "anonymous"}:${path}`;
+        const hit = githubCache.get(key);
+        if (hit && Date.now() - hit.at < GITHUB_CACHE_MS)
+            return hit.answer;
+        const headers = { accept: "application/vnd.github+json", ...(token ? { authorization: "Bearer " + token } : {}) };
+        let answer;
+        try {
+            const res = await fetchImpl(`https://api.github.com${path}`, { headers, signal: AbortSignal.timeout(15_000) });
+            answer = res.ok ? { ok: true, json: await res.json() } : { ok: false, status: res.status, access: githubAccess(res.status, Boolean(token)) };
+        }
+        catch {
+            answer = { ok: false, status: 0, access: "unreachable" };
+        }
+        // Rate limits and outages are not kept: the next read asks again.
+        if (answer.ok || answer.status === 404) {
+            if (githubCache.size >= 500)
+                for (const [k, v] of githubCache)
+                    if (Date.now() - v.at >= GITHUB_CACHE_MS)
+                        githubCache.delete(k);
+            if (githubCache.size < 1000)
+                githubCache.set(key, { at: Date.now(), answer });
+        }
+        return answer;
+    };
+}
+/** Whether the steering transport works now: registered is not operational (jgwill/Miadi#909). */
+export function steeringTransport(tmux) {
+    if (!tmux)
+        return { tool: "registered", transport: "unavailable", reason: "The connector host was started without a steering surface." };
+    if (tmux.available && !tmux.available())
+        return { tool: "registered", transport: "unavailable", reason: "The host's tmux server does not answer." };
+    return { tool: "registered", transport: "operational" };
+}
 function episodeRef(input) {
     // miadi-chronicle://316, miadi-chronicle:316, chronicle:<folder>, a folder, or a number
     return encodeURIComponent(input.replace(/^miadi-chronicle:(\/\/)?/, "").replace(/^chronicle:/, "").trim());
@@ -137,15 +180,19 @@ export function registerTools(server, ctx) {
         if (!viewer || viewer.api_tier === "write" || r.actor.person_id === viewer.id)
             return r;
         const body = { ...r.body };
-        for (const k of ["session", "cwd", "session_id"])
+        // A steer's binding, pane, target and artifact path name the seat as the session does (#922 R2).
+        for (const k of ["session", "cwd", "session_id", "binding", "pane"])
             delete body[k];
         for (const k of ["markdown", "transcript"])
             if (typeof body[k] === "string")
                 body[k] = `${body[k].length} chars`;
         const receipt = r.completion_receipt ? { ...r.completion_receipt } : undefined;
         if (receipt)
-            for (const k of ["to", "file", "session_id"])
+            for (const k of ["to", "file", "session_id", "target", "artifact"])
                 delete receipt[k];
+        // A steer's message names its target pane.
+        if (receipt && r.kind === "session_steer_request")
+            delete receipt.message;
         return { ...r, body, ...(receipt ? { completion_receipt: receipt } : {}) };
     };
     const actorOf = (person, auth) => {
@@ -178,6 +225,9 @@ export function registerTools(server, ctx) {
     const records = () => all().map(redact);
     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);
+    /** The factory runner's delivery receipts, read fresh: operator data, for the write tier only. */
+    const receipts = () => readFactoryReceipts(factoryLedgerPath(ctx.factoryDir ?? defaultFactoryDir()));
+    const github = githubGetter(ctx.approval?.fetchImpl ?? fetch);
     // ── reads ──────────────────────────────────────────────────────────────
     server.registerTool("get_capabilities", {
         title: "What this connector can do for you",
@@ -207,6 +257,8 @@ export function registerTools(server, ctx) {
                 ledger: "connector ledger (append-only, /srv/miadi/connector)",
             },
             tools: TOOL_STATUS,
+            // Registered is not operational: whether a steer can reach a pane on this host now (jgwill/Miadi#909).
+            steering: steeringTransport(ctx.tmux),
             foundation_read: {
                 permission: FOUNDATIONS_PERMISSION,
                 held: foundations,
@@ -354,7 +406,13 @@ export function registerTools(server, ctx) {
         requireTier(person, "write");
         const id = session_id.replace(/^session:/, "");
         const session = await miadi.get(person.token, `/api/session/${encodeURIComponent(id)}`);
-        return { ...session, connector_records: touching(`session:${id}`) };
+        // The missions the factory delivered to this session, by the runner's receipt (jgwill/Miadi#909).
+        const all = receipts();
+        const missions = recordsForSession(all, id).map((record) => {
+            const rc = all.filter((x) => x.record === record && x.session_id === id).sort((a, b) => b.at.localeCompare(a.at))[0];
+            return { record, binding: "factory_receipt", delivered_at: rc?.at, tmux_session: rc?.tmux_session, pane_id: rc?.pane_id, read: `mission_status with ${record}` };
+        });
+        return { ...session, missions, connector_records: touching(`session:${id}`) };
     }));
     server.registerTool("get_evidence", {
         title: "What an episode holds as evidence",
@@ -629,14 +687,23 @@ export function registerTools(server, ctx) {
     }));
     server.registerTool("get_run_result", {
         title: "Where a requested run stands",
-        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.",
+        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, its receipt, and for a run or work proposal the result its agent submitted (summary, outputs with their checks, tests, blockers, the pending or decided completion). mission_status joins the live session and every stage.",
         inputSchema: { record_id: z.string().min(1) },
         annotations: READ,
     }, wrap(async ({ record_id }, extra) => {
-        who(extra);
+        const { person } = who(extra);
         const r = records().find((x) => x.id === record_id);
         if (!r)
             return { state: "not_found", record_id };
+        const isMission = r.kind === "run_request" || r.kind === "work_proposal";
+        // The sessions a result must come from: the runner's receipts, for every tier, else the record's session refs (#922 R5).
+        const bound = new Set(receiptsForRecord(receipts(), r.id).flatMap((x) => (x.session_id ? [x.session_id] : [])));
+        if (!bound.size)
+            for (const ref of r.refs)
+                if (/^session:[0-9a-f-]{36}$/.test(ref))
+                    bound.add(ref.slice(8));
+        const checked = isMission ? await missionResult(r, all(), bound, { githubGet: github, approvalUrl }) : undefined;
+        const result = checked && person.api_tier !== "write" ? redactResult(checked) : checked;
         return {
             record: r,
             version: versionOf(r),
@@ -648,11 +715,13 @@ export function registerTools(server, ctx) {
             ...(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)}.` } }
                 : {}),
+            // What the agent returned (jgwill/Miadi#921). The projection above is the request; this is its result.
+            ...(result ? { result, mission_status: `mission_status with ${r.id} joins the live session, the stages and the human gates.` } : {}),
         };
     }));
     server.registerTool("mission_status", {
         title: "Where a mission stands",
-        description: "One mission, joined and verified: its source request and decision, the sessions bound to it (live or not), its issues and PRs, what is approved, queued, delivered, running, merged, released or closed — each by its evidence, never inferred from an idle pane — and the next authorized action. An issue or session resolves only through the request that holds it as primary; several are ambiguous_mission, citations alone are related_only, and an inference authorizes nothing (identity.authorizes_actions). Released needs a release receipt with artifact, target, production check and a fresh time; closed needs an approved session ending that cites the mission. Operator details need Miadi's write tier. jgwill/Miadi#893, #913.",
+        description: "One mission, joined and verified: its source request and decision, the sessions bound to it (live or not), its issues and PRs, what is approved, queued, delivered, running, merged, released or closed — each by its evidence, never inferred from an idle pane — and the next authorized action. An issue or session resolves only through the request that holds it as primary; several are ambiguous_mission, citations alone are related_only, and an inference authorizes nothing (identity.authorizes_actions). Released needs a release receipt with artifact, target, production check and a fresh time; closed needs an approved session ending that cites the mission. A session the factory delivered a mission to resolves through the runner's receipt (factory_bound), cross-checked with Miadi's session registry (binding verified, receipt_only or unverified_association). result returns what the agent submitted through propose_session_completion naming the mission: summary, outputs with their checks, tests, blockers and the completion decision; mission_stage and pending_human_gates say where it stands and what waits on a person. Operator details need Miadi's write tier. jgwill/Miadi#893, #913, #909, #921.",
         inputSchema: {
             ref: z
                 .string()
@@ -666,11 +735,13 @@ export function registerTools(server, ctx) {
         return 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),
-            tmuxSessions: writeTier ? (ctx.tmuxSessions ?? (() => [])) : undefined,
+            // 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
-                ? (session) => {
+                ? (session, paneId) => {
                     try {
-                        const pane = ctx.tmux.listPanes(session)[0];
+                        const panes = ctx.tmux.listPanes(session);
+                        const pane = paneId ? panes.find((p) => p.id === paneId) : panes[0];
                         if (!pane)
                             return "unknown";
                         return isBusy(ctx.tmux.capture(`${session}:${pane.window}.${pane.pane}`)) ? "busy" : "idle";
@@ -680,6 +751,24 @@ export function registerTools(server, ctx) {
                     }
                 }
                 : undefined,
+            panePresent: writeTier && ctx.tmux
+                ? (session, paneId) => {
+                    try {
+                        return ctx.tmux.listPanes(session).some((p) => p.id === paneId);
+                    }
+                    catch {
+                        return undefined;
+                    }
+                }
+                : undefined,
+            factoryReceiptsOf: writeTier ? (id) => receiptsForRecord(receipts(), id) : undefined,
+            recordsBoundTo: writeTier ? (sessionId) => recordsForSession(receipts(), sessionId) : undefined,
+            // What a result and a closure are checked against does not depend on who reads (#922 R5); only what is shown does.
+            boundSessionIdsOf: (id) => receiptsForRecord(receipts(), id).flatMap((x) => (x.session_id ? [x.session_id] : [])),
+            trustedRecords: all(),
+            operator: writeTier,
+            githubGet: github,
+            approvalUrl,
             sessionOf: writeTier ? (id) => miadi.get(person.token, `/api/session/${encodeURIComponent(id)}`) : undefined,
             issueOf: async (owner, repo, n) => {
                 const f = ctx.approval?.fetchImpl ?? fetch;
@@ -1119,21 +1208,77 @@ export function registerTools(server, ctx) {
                 .optional()
                 .describe("The mission this ending closes, by record id. Only an approved exit or complete_then_exit that names the mission here closes it in mission_status (jgwill/Miadi#913)."),
             evidence_refs: refs,
+            result: z
+                .object({
+                summary: z.string().max(4000).optional().describe("What was achieved, in the agent's words. Default: the reason."),
+                outputs: z
+                    .array(z.object({
+                    ref: z.string().min(1).max(500).describe("A commit or file URL on GitHub, owner/repo#n, miadi-review:<uuid>, miadi-chronicle://<n>/<path>, a record id or a URL."),
+                    label: z.string().max(200).optional(),
+                    git_sha: z.string().regex(/^[0-9a-f]{7,40}$/).optional().describe("The commit sha, or the file's git blob sha, as submitted: a later change shows as changed_since_submission."),
+                }))
+                    .max(30)
+                    .optional(),
+                tests: z
+                    .object({
+                    command: z.string().max(300).optional(),
+                    passed: z.number().int().min(0).optional(),
+                    failed: z.number().int().min(0).optional(),
+                    skipped: z.number().int().min(0).optional(),
+                    note: z.string().max(1000).optional(),
+                })
+                    .optional(),
+                blockers: z.array(z.string().min(1).max(500)).max(20).optional(),
+            })
+                .optional()
+                .describe("The mission's result as its agent returns it (jgwill/Miadi#921): mission_status and get_run_result read it back by the mission id. It is the agent's claim; outputs are checked when read."),
         },
         annotations: WRITE,
     }, wrap(async (a, extra) => {
         const { person, auth } = who(extra);
         requireContribute(auth);
         const id = a.session_id.replace(/^session:/, "");
+        const startedAt = new Date().toISOString();
         const r = append("session_completion_proposal", person, auth, {
             circle: "continuity",
             refs: a.mission ? [`session:${id}`, a.mission] : [`session:${id}`],
             evidence_refs: a.evidence_refs,
             approval_state: "awaiting_approval",
             idempotency_key: a.mission ? `${id}:${a.ending}:${a.mission}` : `${id}:${a.ending}`,
-            body: { session_id: id, ending: a.ending, reason: a.reason, ...(a.mission ? { mission: a.mission } : {}) },
+            body: {
+                session_id: id,
+                ending: a.ending,
+                reason: a.reason,
+                ...(a.mission ? { mission: a.mission } : {}),
+                ...(a.result ? { result: a.result } : {}),
+                // Set by the connector, never by the caller: a result is verified only when the write tier submits it (#922 R3).
+                submitted_with_tier: person.api_tier ?? null,
+            },
         });
-        return { ...r, approval_url: approvalUrl(r.id) };
+        // The same session, ending and mission already awaiting a decision: it is handed back unchanged.
+        const replayed = r.created_at < startedAt;
+        const prior = r.body;
+        const dropped = replayed
+            ? [
+                ...(prior.reason !== a.reason ? ["reason"] : []),
+                ...(JSON.stringify(prior.result ?? null) !== JSON.stringify(a.result ?? null) ? ["result"] : []),
+                ...(JSON.stringify(r.evidence_refs) !== JSON.stringify(a.evidence_refs ?? []) ? ["evidence_refs"] : []),
+            ]
+            : [];
+        return {
+            ...r,
+            approval_url: approvalUrl(r.id),
+            ...(replayed
+                ? {
+                    replayed: true,
+                    ...(dropped.length ? { not_recorded: dropped } : {}),
+                    note: dropped.length
+                        ? `An ending for this session, ending and mission already awaits a decision; it stands as first submitted, and this call's ${dropped.join(", ")} were not recorded. Ask the person to decline it, then submit again.`
+                        : "An ending for this session, ending and mission already awaits a decision; it is returned unchanged and nothing new was recorded.",
+                }
+                : {}),
+            ...(a.mission ? { read_back: `mission_status with ${a.mission}` } : {}),
+        };
     }));
     // ── requests: recorded, approved by a person on the approval page, then run ──
     server.registerTool("request_authorized_run", {
@@ -1383,8 +1528,10 @@ export function registerTools(server, ctx) {
         const { person, auth } = who(extra);
         requireContribute(auth);
         requireTier(person, "write");
-        if (!ctx.tmux)
-            throw new ToolRefusal("unavailable", "The connector host has no steering surface; the steer is unstarted.");
+        // No transport, no record: a steer that cannot reach a pane uses none of the grant (jgwill/Miadi#909).
+        const transport = steeringTransport(ctx.tmux);
+        if (transport.transport !== "operational")
+            throw new ToolRefusal("unavailable", `${transport.reason} The steer is unstarted; no attempt was used.`);
         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 approved run_request or work_proposal this steer belongs to.");
@@ -1395,10 +1542,14 @@ export function registerTools(server, ctx) {
         const grant = steeringGrantOf(grantRecord);
         const priorAttempts = steerAttempts(all(), grantRecord.id);
         const covered = checkGrant(grant, priorAttempts) === "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 body = {
             instruction: a.instruction,
-            session: a.session ?? grantRecord.body.session,
+            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 } : {}) } } : {}),
         };
         const fields = {
             circle: grantRecord.circle,
@@ -1421,8 +1572,9 @@ export function registerTools(server, ctx) {
             };
         }
         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 });
-        const delivered = result.status === "accepted" || result.status === "submitted";
+        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,
@@ -1439,13 +1591,18 @@ export function registerTools(server, ctx) {
                 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,
         });
-        return records().find((x) => x.id === r.id) ?? r;
+        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 },
+        };
     }));
     server.registerTool("request_review_operation", {
         title: "Request a review operation",
@@ -1885,7 +2042,7 @@ export const TOOL_STATUS = {
     handoff_status: "live",
     list_records: "live",
     get_run_result: "live",
-    mission_status: "live (operator details need the Miadi write tier)",
+    mission_status: "live (operator details need the Miadi write tier; returns the agent's submitted result)",
     mission_model_preflight: "live, Miadi write tier (static policy; Jev only with consult_jev and a Jev key on the host, otherwise router_unconfigured)",
     provider_capabilities: "live, Miadi write tier",
     search: "live",
@@ -1905,7 +2062,7 @@ export const TOOL_STATUS = {
     revise_pending_request: "live, contribute (a waiting or sent-back run or proposal gets its next version; same id, same card)",
     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)",
+    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_review_operation: "live, contribute, needs_approval",
     request_deep_diver: "live, contribute, needs_approval",
     link_review_to_episode: "live, contribute, needs_approval",

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.15";
+export declare const VERSION = "0.1.17";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.1.15";
+export const VERSION = "0.1.17";

package/package.json

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