@miadi/connector 0.1.14 → 0.1.16

package/dist/mission-result.js

@@ -0,0 +1,273 @@
+const REASON_TEXT = {
+    cited_only: "It cites the mission in refs but does not name it in its mission field.",
+    no_binding: "The mission has no bound session to compare the submitting session with.",
+    not_bound_session: "It ends a session this mission is not bound to.",
+    submitter_below_write_tier: "It was submitted below Miadi's write tier; a result is verified only when the write tier or the factory's writer token submits it.",
+};
+const MAX_OUTPUTS = 30;
+/** GitHub calls one answer may make: the anonymous limit is 60 an hour (#922 R9, R19). */
+const MAX_GITHUB_CHECKS = 8;
+const SHA = /^[0-9a-f]{7,40}$/;
+// An owner or repository is one safe path segment: never "." or "..", so a ref cannot reach another API path (#922 R9).
+const SEG = "((?!\\.\\.?(?:/|$))[\\w-][\\w.-]*)";
+const COMMIT_URL = new RegExp(`^https://github\\.com/${SEG}/${SEG}/commit/([0-9a-f]{7,40})/?$`);
+const BLOB_URL = new RegExp(`^https://github\\.com/${SEG}/${SEG}/blob/([^/]+)/(.+)$`);
+const ISSUE_URL = /^https:\/\/github\.com\/([\w.-]+)\/([\w.-]+)\/(?:pull|issues)\/(\d+)\/?$/;
+const ISSUE_REF = /^([\w.-]+)\/([\w.-]+)#(\d+)$/;
+const REVIEW_REF = /^miadi-review:(\/\/)?[0-9a-f-]{36}$/;
+const EPISODE_FILE = /^miadi-chronicle:\/\/\d+\/.+/;
+const RECORD_ID = /^[a-z_]+:[0-9a-f][0-9a-f-]{7,}$/;
+const SESSION_REF = /^session:/;
+const str = (v) => (typeof v === "string" ? v.trim() : "");
+const newestFirst = (a, b) => b.created_at.localeCompare(a.created_at);
+function decisionOf(r) {
+    switch (r.approval_state) {
+        case "approved":
+            return "accepted";
+        case "declined":
+            return "declined";
+        case "revision_requested":
+            return "revision_requested";
+        default:
+            return "pending_approval";
+    }
+}
+/** What one reference is, before anything is read. */
+export function classifyOutput(ref) {
+    let m = COMMIT_URL.exec(ref);
+    if (m)
+        return { ref, type: "commit", repository: `${m[1]}/${m[2]}`, commit: m[3], read: ref };
+    m = BLOB_URL.exec(ref);
+    if (m) {
+        const path = m[4].split("#")[0];
+        if (path.split("/").some((x) => x === "." || x === ".." || x === ""))
+            return { ref, type: "link", read: ref };
+        let gitRef;
+        try {
+            gitRef = decodeURIComponent(m[3]);
+        }
+        catch {
+            return { ref, type: "link", read: ref }; // a malformed escape is a link, never a failed answer (#922 R14)
+        }
+        return { ref, type: "file", repository: `${m[1]}/${m[2]}`, git_ref: gitRef, path, read: ref };
+    }
+    m = ISSUE_URL.exec(ref) ?? ISSUE_REF.exec(ref);
+    if (m)
+        return { ref, type: "issue_or_pr", repository: `${m[1]}/${m[2]}`, read: `mission_status or get_context with ${m[1]}/${m[2]}#${m[3]}` };
+    if (REVIEW_REF.test(ref))
+        return { ref, type: "review", read: "review_lookup" };
+    if (EPISODE_FILE.test(ref))
+        return { ref, type: "episode_file", read: "read_episode_file" };
+    if (RECORD_ID.test(ref))
+        return { ref, type: "record", read: "get_run_result or list_records" };
+    if (/^https?:\/\//.test(ref))
+        return { ref, type: "link", read: ref };
+    return { ref, type: "unrecognized" };
+}
+async function checkOutput(out, ctx) {
+    const checked_at = ctx.now.toISOString();
+    if (out.type === "unrecognized")
+        return { state: "unrecognized", checked_at, note: "Not a reference the connector resolves." };
+    if (out.type === "record") {
+        return ctx.records.some((r) => r.id === out.ref)
+            ? { state: "verified", checked_at }
+            : { state: "not_found", checked_at, note: "The connector ledger holds no record with this id." };
+    }
+    if (out.type !== "commit" && out.type !== "file")
+        return { state: "not_checked", checked_at };
+    if (!ctx.githubGet)
+        return { state: "unverified", access: "github_not_consulted", checked_at };
+    if (ctx.budget.left <= 0)
+        return { state: "not_checked", checked_at, note: `One answer makes at most ${MAX_GITHUB_CHECKS} GitHub calls.` };
+    ctx.budget.left--;
+    const repo = out.repository;
+    if (out.type === "commit") {
+        const res = await ctx.githubGet(`/repos/${repo}/commits/${out.commit}`).catch(() => ({ ok: false, status: 0, access: "unreachable" }));
+        if (!res.ok)
+            return { state: "unverified", access: res.access, checked_at };
+        const sha = str(res.json?.sha);
+        const committed = str(res.json?.commit?.committer?.date) || str(res.json?.commit?.author?.date);
+        if (out.declared_sha && sha && !sha.startsWith(out.declared_sha) && !out.declared_sha.startsWith(sha)) {
+            return { state: "changed_since_submission", sha, checked_at, note: `The agent declared ${out.declared_sha}; the URL resolves to ${sha}.` };
+        }
+        return { state: "verified", ...(sha ? { sha } : {}), ...(committed ? { committed_at: committed } : {}), checked_at };
+    }
+    // A file at a ref.
+    const path = out.path.split("/").map(encodeURIComponent).join("/");
+    const ref = encodeURIComponent(out.git_ref);
+    const res = await ctx.githubGet(`/repos/${repo}/contents/${path}?ref=${ref}`).catch(() => ({ ok: false, status: 0, access: "unreachable" }));
+    if (!res.ok) {
+        return {
+            state: "unverified",
+            access: res.access,
+            checked_at,
+            ...(res.status === 404 ? { note: "A branch name holding a slash cannot be told from the path in a GitHub URL; it is read as its first segment." } : {}),
+        };
+    }
+    const sha = str(res.json?.sha);
+    const size = typeof res.json?.size === "number" ? res.json.size : undefined;
+    const moves = !SHA.test(out.git_ref) || out.git_ref.length < 40;
+    const base = { state: "verified", ...(sha ? { sha } : {}), ...(size !== undefined ? { size } : {}), ...(moves ? { ref_moves: true } : {}), checked_at };
+    if (out.declared_sha && sha && out.declared_sha !== sha) {
+        return { ...base, state: "changed_since_submission", note: `The agent declared blob ${out.declared_sha}; ${out.git_ref} now holds ${sha}.` };
+    }
+    if (moves && !out.declared_sha && ctx.budget.left > 0) {
+        // A branch moves: the file's latest commit says whether it changed after the agent submitted it.
+        ctx.budget.left--;
+        const hist = await ctx.githubGet(`/repos/${repo}/commits?path=${path}&sha=${ref}&per_page=1`).catch(() => ({ ok: false, status: 0, access: "unreachable" }));
+        const last = hist.ok && Array.isArray(hist.json) ? str(hist.json[0]?.commit?.committer?.date) : "";
+        if (last) {
+            base.last_changed_at = last;
+            if (Date.parse(last) > Date.parse(ctx.submittedAt)) {
+                return { ...base, state: "changed_since_submission", note: `The file changed on ${out.git_ref} at ${last}, after the submission at ${ctx.submittedAt}.` };
+            }
+        }
+        else {
+            base.note = "The submission declared no hash and the file's history could not be read; this is the content now.";
+        }
+    }
+    return base;
+}
+/**
+ * The result a mission's agent submitted, checked. `boundSessions` are the Claude
+ * Code session ids the mission is bound to (empty when the viewer may not see them).
+ */
+export async function missionResult(mission, records, boundSessions, deps = {}) {
+    const now = deps.now?.() ?? new Date();
+    const notes = [];
+    const proposals = records.filter((r) => r.kind === "session_completion_proposal" && r.id !== mission.id).sort(newestFirst);
+    const submissions = [];
+    for (const r of proposals) {
+        const b = (r.body ?? {});
+        const names = str(b.mission) === mission.id;
+        const cites = r.refs.includes(mission.id) || r.evidence_refs.includes(mission.id);
+        if (!names && !cites)
+            continue;
+        const sessionId = str(b.session_id).replace(/^session:/, "");
+        let association;
+        let code;
+        if (!names) {
+            association = "cited_only";
+            code = "cited_only";
+        }
+        else if (!boundSessions.size) {
+            association = "unverified_association";
+            code = "no_binding";
+        }
+        else if (!sessionId || !boundSessions.has(sessionId)) {
+            association = "unverified_association";
+            code = "not_bound_session";
+        }
+        else if (!(deps.submittedWithWriteTier ?? submittedWithWriteTier)(r)) {
+            association = "unverified_association";
+            code = "submitter_below_write_tier";
+        }
+        else {
+            association = "verified";
+        }
+        const receipt = (r.completion_receipt ?? {});
+        submissions.push({
+            r,
+            record: r.id,
+            submitted_at: r.created_at,
+            submitted_by: { name: r.actor.name, person_id: r.actor.person_id },
+            association,
+            ...(code ? { association_code: code, association_reason: REASON_TEXT[code] } : {}),
+            ...(sessionId ? { session_id: sessionId } : {}),
+            ...(str(b.ending) ? { ending: str(b.ending) } : {}),
+            decision: decisionOf(r),
+            ...(str(receipt.decided_by?.name) ? { decided_by: str(receipt.decided_by.name) } : {}),
+            ...(str(receipt.decided_at) ? { decided_at: str(receipt.decided_at) } : {}),
+        });
+    }
+    const strip = ({ r: _r, ...s }) => s;
+    const standing = submissions.find((s) => s.association === "verified") ?? submissions.find((s) => s.association === "unverified_association");
+    if (!standing) {
+        if (submissions.length)
+            notes.push(`${submissions.length} record(s) cite this mission without naming it as their mission; none is read as its result.`);
+        return { state: "no_result_submitted", verified: false, submissions: submissions.map(strip), completion: "none", notes };
+    }
+    const verified = standing.association === "verified";
+    if (!verified)
+        notes.push(`The standing submission is an unverified association: ${standing.association_reason} Its decision is not read as the mission's completion.`);
+    const others = submissions.filter((s) => s !== standing && s.association !== "cited_only");
+    if (others.length)
+        notes.push(`${others.length} other submission(s) name this mission; the newest verified one stands, every one is listed in submissions.`);
+    const body = (standing.r.body ?? {});
+    const structured = (body.result && typeof body.result === "object" ? body.result : {});
+    const declared = new Map();
+    for (const o of structured.outputs ?? [])
+        if (str(o?.ref))
+            declared.set(str(o.ref), { label: str(o.label) || undefined, git_sha: str(o.git_sha) || undefined });
+    const refs = [...new Set([...declared.keys(), ...standing.r.evidence_refs])].filter((x) => !SESSION_REF.test(x) && x !== mission.id);
+    if (refs.length > MAX_OUTPUTS)
+        notes.push(`${refs.length} outputs were submitted; the first ${MAX_OUTPUTS} are listed.`);
+    const outputs = [];
+    const budget = { left: MAX_GITHUB_CHECKS };
+    for (const ref of refs.slice(0, MAX_OUTPUTS)) {
+        const d = declared.get(ref);
+        const base = { ...classifyOutput(ref), ...(d?.label ? { label: d.label } : {}), ...(d?.git_sha && SHA.test(d.git_sha) ? { declared_sha: d.git_sha } : {}) };
+        outputs.push({ ...base, check: await checkOutput(base, { records, githubGet: deps.githubGet, submittedAt: standing.submitted_at, now, budget }) });
+    }
+    if (outputs.some((o) => o.check.state === "unverified"))
+        notes.push("Some outputs could not be read by the connector; they are unverified, not missing.");
+    if (outputs.some((o) => o.check.state === "changed_since_submission"))
+        notes.push("Some outputs changed after the agent submitted them; read them at the submitted commit.");
+    const t = structured.tests;
+    const num = (v) => (typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : undefined);
+    const tests = t && typeof t === "object" && (num(t.passed) !== undefined || num(t.failed) !== undefined || str(t.command))
+        ? {
+            state: "agent_claim",
+            ...(str(t.command) ? { command: str(t.command) } : {}),
+            ...(num(t.passed) !== undefined ? { passed: num(t.passed) } : {}),
+            ...(num(t.failed) !== undefined ? { failed: num(t.failed) } : {}),
+            ...(num(t.skipped) !== undefined ? { skipped: num(t.skipped) } : {}),
+            ...(str(t.note) ? { note: str(t.note) } : {}),
+        }
+        : { state: "not_structured", note: "The submission records no structured test receipt; the summary is the agent's own account of its tests." };
+    const blockers = Array.isArray(structured.blockers) ? structured.blockers.map(str).filter(Boolean) : [];
+    return {
+        state: "submitted",
+        verified,
+        current: {
+            ...strip(standing),
+            summary: str(structured.summary) || str(body.reason),
+            summary_claim: "agent_claim",
+            outputs,
+            tests,
+            blockers,
+            ...(standing.decision === "pending_approval" && deps.approvalUrl ? { approval_url: deps.approvalUrl(standing.record) } : {}),
+        },
+        submissions: submissions.map(strip),
+        completion: verified ? standing.decision : "none",
+        notes,
+    };
+}
+/** Endings made before 0.1.16 carry no recorded tier; from this time on every ending carries one (#922 R18). */
+export const TIER_RECORDED_SINCE = "2026-11-05T00:00:00.000Z";
+/**
+ * Whether a submission was made with Miadi's write tier. The factory's writer token is write tier
+ * by construction. Since 0.1.16 the connector records the submitter's tier on every ending. An
+ * ending without it is trusted only when it is older than TIER_RECORDED_SINCE: nobody can add a
+ * tier to it now, and a newer one without a tier was not written by this connector.
+ */
+export function submittedWithWriteTier(r) {
+    if (r.actor.person_id === "system:writer")
+        return true;
+    const body = (r.body ?? {});
+    if (!("submitted_with_tier" in body))
+        return r.created_at < TIER_RECORDED_SINCE;
+    return body.submitted_with_tier === "write";
+}
+/** The result as a viewer below the write tier reads it: no session ids, which are operator data. */
+export function redactResult(result) {
+    const clean = (x) => {
+        const { session_id: _s, ...rest } = x;
+        return rest;
+    };
+    return {
+        ...result,
+        ...(result.current ? { current: clean(result.current) } : {}),
+        submissions: result.submissions.map(clean),
+    };
+}

package/dist/mission-status.d.ts

@@ -21,15 +21,50 @@
  */
 import type { ConnectorRecord } from "./records.js";
 import type { RequestProjection } from "./request-state.js";
+import type { FactoryReceipt } from "./factory-receipt.js";
+import { type GithubGet, type MissionResult } from "./mission-result.js";
 export interface MissionSession {
-    /** How this session is bound to the mission: signed_ref (a session: ref on the record), brief_target (the delivered brief's `to`), named (the requested name). */
-    association: "signed_ref" | "brief_target" | "named";
+    /**
+     * How this session is bound to the mission: factory_receipt (the factory runner's delivery
+     * receipt names the record, the tmux session, the pane and the Claude Code session id that
+     * took the brief), signed_ref (a session: ref on the record), brief_target (the delivered
+     * brief's `to`), named (the requested name).
+     */
+    association: "factory_receipt" | "signed_ref" | "brief_target" | "named";
     session: string;
     live: "running" | "absent" | "unknown";
+    /** Busy or idle is the seat's turn state, never completion. */
     activity?: "busy" | "idle" | "unknown";
+    /** miadi_registry: Miadi's session registry; pane_peek: a read-only capture of the bound pane. */
+    activity_source?: "miadi_registry" | "pane_peek";
+    /** When the registry last saw that activity. */
+    activity_at?: string;
+    /** The Claude Code session id (factory_receipt). */
+    session_id?: string;
+    /** The tmux pane id the brief was typed into (factory_receipt). */
+    pane_id?: string;
+    delivered_at?: string;
+    /**
+     * verified: the factory receipt and Miadi's session registry agree on the session id, tmux session
+     * and pane. receipt_only: only the receipt says so (the registry is unavailable or shows no live
+     * seat). unverified_association: the registry places that session elsewhere.
+     */
+    binding?: "verified" | "receipt_only" | "unverified_association";
+    binding_reason?: string;
+    /** The fields the receipt and the registry were compared on; a field one side lacks is not compared. */
+    binding_compared?: string[];
     /** Present when Miadi's session view was joined (write tier). */
     miadi?: unknown;
 }
+/** The provider the mission asked for, the one resolved on the host, and the one that ran. */
+export interface MissionProvider {
+    requested: string | null;
+    resolved: string | null;
+    actual: string | null;
+    actual_source?: "factory_receipt" | "miadi_registry";
+    /** False when the agent that ran is not the one requested or resolved; nothing was re-run because of it. */
+    match: boolean | "unknown";
+}
 /** What the connector could establish about a GitHub reference. `unverified` is never `not_found`: without access the connector cannot tell. */
 export interface IssueLookup {
     state: string;
@@ -87,26 +122,32 @@ export interface MissionStageTruth {
      */
     released: "verified" | "receipt_recorded" | "stale" | "live_mismatch" | "claimed_unverified" | "no_evidence";
     release_evidence?: ReleaseEvidence;
+    /** The agent submitted a result naming this mission (a completion proposal). Its own claim; see result. */
+    result_submitted: boolean;
+    /** The standing submission names the mission, ends a bound session and was made with the write tier. */
+    result_verified: boolean;
+    /** The person's decision on the standing submission's ending; none without one. Accepted is not closed unless the ending exits. */
+    completion: MissionResult["completion"];
     /** True only with an approved ending (exit or complete_then_exit) naming this mission in its `mission` field, for one of its sessions. A completed request is not a closure. */
     closed: boolean;
     closure_evidence?: ClosureEvidence;
 }
-export type MissionResolution = "exact" | "declared_primary" | "inferred_primary" | "ambiguous_mission" | "related_only";
+export type MissionResolution = "exact" | "declared_primary" | "factory_bound" | "inferred_primary" | "ambiguous_mission" | "related_only";
 export interface MissionCandidate {
     id: string;
     kind: string;
     created_at: string;
-    /** primary: the reference is this record's primary issue. related: an issue it cites and does not implement. cited: a session it cites. */
-    relation: "primary" | "related" | "cited";
-    /** declared: body.primary_issue. first_issue_ref: inferred from the first issue in refs. cited_ref: the reference is in its refs. */
-    provenance: "declared" | "first_issue_ref" | "cited_ref";
+    /** primary: the reference is this record's primary issue. related: an issue it cites and does not implement. cited: a session it cites. bound: the session the factory delivered it to. */
+    relation: "primary" | "related" | "cited" | "bound";
+    /** declared: body.primary_issue. first_issue_ref: inferred from the first issue in refs. cited_ref: the reference is in its refs. factory_receipt: the factory delivered it to that session. */
+    provenance: "declared" | "first_issue_ref" | "cited_ref" | "factory_receipt";
     primary_issue?: string;
 }
 export interface MissionIdentity {
     resolution: MissionResolution;
     /** A declared primary that another request also holds by inference: reported, not authorizing. */
     contested?: boolean;
-    /** True only for exact and an uncontested declared_primary: a steer, release or closure may name this mission. */
+    /** True only for exact, factory_bound and an uncontested declared_primary: a steer, release or closure may name this mission. */
     authorizes_actions: boolean;
     primary_issue?: {
         ref: string;
@@ -133,6 +174,7 @@ export interface MissionStatus {
         state: string;
     };
     sessions?: MissionSession[];
+    provider?: MissionProvider;
     issues?: {
         ref: string;
         relation: "primary" | "related";
@@ -147,6 +189,21 @@ export interface MissionStatus {
         max_attempts?: number;
     };
     stage_truth?: MissionStageTruth;
+    /**
+     * The furthest stage with evidence, read first: awaiting_decision, recording, sent_back, declined,
+     * approved, queued, delivered, running, result_submitted_unverified, result_submitted_awaiting_completion_approval,
+     * result_submitted_completion_declined, result_submitted_revision_requested, completion_accepted,
+     * merged, released, closed. stage_truth holds each stage on its own.
+     */
+    mission_stage?: string;
+    /** Decisions only a person takes that this mission waits on, each with where it is taken. */
+    pending_human_gates?: {
+        gate: "run_approval" | "completion_approval" | "unverified_completion_approval" | "steer_approval";
+        record: string;
+        approval_url?: string;
+    }[];
+    /** What the agent returned: summary, outputs with their checks, tests, blockers and the completion decision (jgwill/Miadi#921). */
+    result?: MissionResult;
     next_authorized_action?: string;
     notes: string[];
 }
@@ -157,8 +214,27 @@ export interface MissionStatusDeps {
     projectOf: (record: ConnectorRecord) => RequestProjection | null;
     /** Live tmux session names, when the host can list them (write tier only). */
     tmuxSessions?: () => string[];
-    /** Read-only peek: is the named session's first pane mid-turn? (write tier only.) */
-    paneBusy?: (session: string) => "busy" | "idle" | "unknown";
+    /** Read-only peek: is the named session's pane mid-turn? The pane id when the binding names one, else the first pane. (write tier only.) */
+    paneBusy?: (session: string, paneId?: string) => "busy" | "idle" | "unknown";
+    /** Whether the tmux session still holds the pane id (write tier only); undefined when it cannot be listed. */
+    panePresent?: (session: string, paneId: string) => boolean | undefined;
+    /** The factory runner's delivery receipts for one record, newest first (write tier only). */
+    factoryReceiptsOf?: (recordId: string) => FactoryReceipt[];
+    /** The records the factory delivered to one Claude Code session id (write tier only). */
+    recordsBoundTo?: (sessionId: string) => string[];
+    /** GitHub reads for a result's outputs, as the connector can make them. */
+    githubGet?: GithubGet;
+    /**
+     * The Claude Code session ids the factory delivered a record to, for every tier: what a result
+     * and a closure are checked against never depends on who is reading (#922 R5). Never shown.
+     */
+    boundSessionIdsOf?: (recordId: string) => string[];
+    /** The unredacted ledger, for checking results and closures; what is shown still comes from `records`. */
+    trustedRecords?: ConnectorRecord[];
+    /** The viewer holds the write tier: session ids in the result and the closure are shown. Default true. */
+    operator?: boolean;
+    /** The approval page of a record. */
+    approvalUrl?: (id: string) => string;
     /** Miadi's session view by session:<uuid> (write tier only). */
     sessionOf?: (id: string) => Promise<unknown>;
     issueOf?: (owner: string, repo: string, n: string) => Promise<IssueLookup>;
@@ -181,7 +257,7 @@ export interface ResolvedSubject {
     contested?: boolean;
     candidates: MissionCandidate[];
 }
-/** Whether a resolved reference may be acted on: an exact id, or a declared primary nobody else holds. */
+/** Whether a resolved reference may be acted on: an exact id, the one record the factory delivered to a session, or a declared primary nobody else holds. */
 export declare function authorizesActions(found: Pick<ResolvedSubject, "resolution" | "contested">): boolean;
 /**
  * The record a mission reference resolves to, how it was found, and every other
@@ -189,5 +265,9 @@ export declare function authorizesActions(found: Pick<ResolvedSubject, "resoluti
  * Expects the folded ledger (`current()`), so a superseding record never stands
  * as a mission of its own.
  */
-export declare function resolveMissionSubject(ref: string, records: ConnectorRecord[]): ResolvedSubject | null;
+export declare function resolveMissionSubject(ref: string, records: ConnectorRecord[], opts?: {
+    recordsBoundTo?: (sessionId: string) => string[];
+}): ResolvedSubject | null;
 export declare function missionStatus(ref: string, records: ConnectorRecord[], deps: MissionStatusDeps): Promise<MissionStatus>;
+/** The furthest stage the evidence reaches. Each stage keeps its own truth in stage_truth. */
+export declare function missionStage(standing: RequestProjection | null, t: MissionStageTruth): string;