thehood 0.1.0-preview.0

package/dist/runtime/revisionPacket.js

@@ -0,0 +1,144 @@
+import { writeRunArtifact } from "./artifacts.js";
+import { newId, nowIso } from "./ids.js";
+const maxTextLength = 500;
+const maxCriteria = 8;
+const isJsonObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const stringField = (value) => typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+const truncateText = (value) => value.length <= maxTextLength ? value : `${value.slice(0, maxTextLength - 3)}...`;
+const stringArrayField = (value) => Array.isArray(value)
+    ? value.filter((item) => typeof item === "string" && item.trim().length > 0)
+    : [];
+const unique = (values) => {
+    const seen = new Set();
+    const output = [];
+    for (const value of values.map((item) => truncateText(item.trim())).filter(Boolean)) {
+        if (seen.has(value)) {
+            continue;
+        }
+        seen.add(value);
+        output.push(value);
+    }
+    return output.slice(0, maxCriteria);
+};
+const fallbackCriteria = (sourceRole) => [
+    `Address the ${sourceRole} revision finding without expanding the requested scope.`,
+    "Preserve runtime approval, protected-path, and verifier separation invariants.",
+    "Leave evidence that lets QA and verifier re-check the repair."
+];
+const qaDecision = (response) => {
+    const payload = isJsonObject(response.data.qaResult) ? response.data.qaResult : undefined;
+    const verdict = stringField(payload?.verdict);
+    if (verdict !== "needs_revision") {
+        return {
+            shouldRevise: false,
+            acceptanceCriteria: []
+        };
+    }
+    const summary = stringField(payload?.summary) ?? response.summary;
+    const criteria = unique([
+        ...stringArrayField(payload?.risks),
+        ...stringArrayField(payload?.missedCases),
+        ...stringArrayField(payload?.suggestedCommands).map((command) => `Consider runtime validation: ${command}`)
+    ]);
+    return {
+        shouldRevise: true,
+        sourceRole: "qa",
+        reasonCode: "qa_needs_revision",
+        reason: summary,
+        repairObjective: `Repair the issue found by QA tester evidence: ${summary}`,
+        acceptanceCriteria: criteria.length > 0 ? criteria : fallbackCriteria("qa")
+    };
+};
+const verifierDecision = (response) => {
+    const payload = isJsonObject(response.data.verificationResult) ? response.data.verificationResult : undefined;
+    const verdict = stringField(payload?.verdict);
+    if (verdict !== "revise") {
+        return {
+            shouldRevise: false,
+            acceptanceCriteria: []
+        };
+    }
+    const summary = stringField(payload?.summary) ?? response.summary;
+    const criteria = unique([
+        ...stringArrayField(payload?.failedCriteria),
+        ...stringArrayField(payload?.risks)
+    ]);
+    return {
+        shouldRevise: true,
+        sourceRole: "verifier",
+        reasonCode: "verifier_revise",
+        reason: summary,
+        repairObjective: `Repair the verifier revision finding: ${summary}`,
+        acceptanceCriteria: criteria.length > 0 ? criteria : fallbackCriteria("verifier")
+    };
+};
+const criticDecision = (response) => {
+    const payload = isJsonObject(response.data.critiqueResult) ? response.data.critiqueResult : undefined;
+    const verdict = stringField(payload?.verdict);
+    const blockingConcerns = stringArrayField(payload?.blockingConcerns);
+    if (verdict !== "needs_revision") {
+        return {
+            shouldRevise: false,
+            acceptanceCriteria: []
+        };
+    }
+    const reason = blockingConcerns[0] ?? response.summary;
+    const criteria = unique([
+        ...blockingConcerns,
+        ...stringArrayField(payload?.nonBlockingConcerns)
+    ]);
+    return {
+        shouldRevise: true,
+        sourceRole: "critic",
+        reasonCode: blockingConcerns.length > 0 ? "critic_blocking_concerns" : "critic_needs_revision",
+        reason,
+        repairObjective: `Repair the critic finding: ${reason}`,
+        acceptanceCriteria: criteria.length > 0 ? criteria : fallbackCriteria("critic")
+    };
+};
+export const decideRevisionPacket = (sourceRole, response) => {
+    switch (sourceRole) {
+        case "qa":
+            return qaDecision(response);
+        case "verifier":
+            return verifierDecision(response);
+        case "critic":
+            return criticDecision(response);
+    }
+};
+export const buildRevisionPacket = (run, input) => {
+    const { decision } = input;
+    if (!decision.shouldRevise || !decision.sourceRole || !decision.reasonCode || !decision.reason || !decision.repairObjective) {
+        throw new Error("Cannot build a revision packet without a complete revision decision.");
+    }
+    return {
+        schemaVersion: 1,
+        kind: "revision_packet",
+        runId: run.runId,
+        createdAt: nowIso(),
+        sourceRole: decision.sourceRole,
+        reasonCode: decision.reasonCode,
+        reason: truncateText(decision.reason),
+        repairObjective: truncateText(decision.repairObjective),
+        acceptanceCriteria: unique(decision.acceptanceCriteria),
+        evidenceRefs: unique(input.evidenceRefs),
+        ...(input.sourceResponseRef ? { sourceResponseRef: input.sourceResponseRef } : {}),
+        ...(input.criticTriggerRef ? { criticTriggerRef: input.criticTriggerRef } : {})
+    };
+};
+export const writeRevisionPacketArtifact = async (run, input) => {
+    const packet = buildRevisionPacket(run, input);
+    const artifact = await writeRunArtifact({
+        repoPath: run.repoPath,
+        runId: run.runId,
+        kind: "revision_packet",
+        name: `revision-${newId("revision")}.json`,
+        content: `${JSON.stringify(packet, null, 2)}\n`,
+        summary: `Revision packet from ${packet.sourceRole}: ${packet.reasonCode}`
+    });
+    return {
+        artifact,
+        packet
+    };
+};
+//# sourceMappingURL=revisionPacket.js.map

package/dist/runtime/revisionPacket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revisionPacket.js","sourceRoot":"","sources":["../../src/runtime/revisionPacket.ts"],"names":[],"mappings":"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"}

package/dist/runtime/revisionTrail.d.ts

@@ -0,0 +1,2 @@
+import type { RevisionTrail, RunRecord } from "./types.js";
+export declare const deriveRevisionTrail: (run: RunRecord) => RevisionTrail;

package/dist/runtime/revisionTrail.js

@@ -0,0 +1,162 @@
+import { nowIso } from "./ids.js";
+const reviewRoles = new Set(["qa", "verifier"]);
+const stringField = (value) => typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+const stringArrayField = (value) => Array.isArray(value)
+    ? value.filter((item) => typeof item === "string" && item.trim().length > 0)
+    : [];
+const roleField = (value) => {
+    const role = stringField(value);
+    return role === "qa" || role === "verifier" || role === "critic" ? role : undefined;
+};
+const uniqueStrings = (values) => [...new Set(values.filter((value) => value.trim().length > 0))];
+const sourceKey = (source) => [source.kind, source.runId, source.id ?? "", source.ref ?? "", source.eventType ?? ""].join(":");
+const uniqueSources = (values) => {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        const key = sourceKey(value);
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(value);
+        }
+    }
+    return result;
+};
+const eventIndex = (run, event) => event ? run.events.findIndex((candidate) => candidate.id === event.id) : -1;
+const packetArtifactRef = (event) => event.type === "revision_packet_written" ? stringField(event.data?.artifactRef) : undefined;
+const eventAfter = (run, startIndex, predicate) => run.events.find((event, index) => index > startIndex && predicate(event));
+const eventsAfter = (run, startIndex, predicate) => run.events.filter((event, index) => index > startIndex && predicate(event));
+const handoffAfter = (run, after, artifactRef) => run.handoffs.find((handoff) => handoff.createdAt >= after.createdAt &&
+    handoff.kind === "agent_handoff" &&
+    handoff.toRole === "implementer" &&
+    handoff.artifactRefs?.includes(artifactRef) === true);
+const responseArtifactRef = (event) => stringField(event?.data?.artifactRef);
+const validationArtifactRefs = (events) => uniqueStrings(events.map((event) => stringField(event.data?.artifactRef)).filter((ref) => Boolean(ref)));
+const trailStatus = (input) => {
+    if (input.nextPacket) {
+        return "superseded";
+    }
+    if (input.completion || input.reviewResponses.some((event) => event.data?.role === "verifier")) {
+        return "reviewed";
+    }
+    if (input.validationEvents.length > 0 || input.reviewResponses.length > 0) {
+        return "awaiting_review";
+    }
+    if (input.repairResponse) {
+        return "repair_reported";
+    }
+    if (input.delegation && input.run.state === "implementing") {
+        return "repairing";
+    }
+    if (input.delegation) {
+        return "delegated";
+    }
+    return "packet_written";
+};
+const sourceRefs = (run, events, artifactRefs) => uniqueSources([
+    ...events.map((event) => ({
+        kind: "run_event",
+        runId: run.runId,
+        id: event.id,
+        eventType: event.type
+    })),
+    ...artifactRefs.map((ref) => ({
+        kind: "run_artifact",
+        runId: run.runId,
+        ref
+    }))
+]);
+const itemForPacket = (run, packetEvent, nextPacket) => {
+    const artifactRef = packetArtifactRef(packetEvent);
+    if (!artifactRef) {
+        return undefined;
+    }
+    const packetIndex = eventIndex(run, packetEvent);
+    const delegation = eventAfter(run, packetIndex, (event) => event.type === "revision_delegated" && event.data?.artifactRef === artifactRef);
+    const delegationIndex = eventIndex(run, delegation);
+    const repairResponse = eventAfter(run, delegationIndex >= 0 ? delegationIndex : packetIndex, (event) => event.type === "agent_response" && event.data?.role === "implementer");
+    const repairIndex = eventIndex(run, repairResponse);
+    const evidenceStart = repairIndex >= 0 ? repairIndex : delegationIndex >= 0 ? delegationIndex : packetIndex;
+    const validationEvents = eventsAfter(run, evidenceStart, (event) => event.type === "validation_evidence_captured");
+    const reviewResponses = eventsAfter(run, evidenceStart, (event) => event.type === "agent_response" && reviewRoles.has(event.data?.role));
+    const completion = eventAfter(run, evidenceStart, (event) => event.type === "run_completed");
+    const handoff = delegation ? handoffAfter(run, delegation, artifactRef) : undefined;
+    const sourceRole = roleField(packetEvent.data?.sourceRole);
+    const reasonCode = stringField(packetEvent.data?.reasonCode);
+    const repairObjective = stringField(delegation?.data?.repairObjective);
+    const evidenceRefs = stringArrayField(packetEvent.data?.evidenceRefs);
+    const sourceResponseRef = stringField(packetEvent.data?.sourceResponseRef);
+    const criticTriggerRef = stringField(packetEvent.data?.criticTriggerRef);
+    const repairResponseRef = responseArtifactRef(repairResponse);
+    const reviewResponseRefs = uniqueStrings(reviewResponses.map(responseArtifactRef).filter((ref) => Boolean(ref)));
+    const validationRefs = validationArtifactRefs(validationEvents);
+    const artifactRefs = uniqueStrings([
+        artifactRef,
+        ...evidenceRefs,
+        ...(sourceResponseRef ? [sourceResponseRef] : []),
+        ...(criticTriggerRef ? [criticTriggerRef] : []),
+        ...(repairResponseRef ? [repairResponseRef] : []),
+        ...validationRefs,
+        ...reviewResponseRefs
+    ]);
+    const eventRefs = uniqueStrings([
+        packetEvent.id,
+        ...(delegation ? [delegation.id] : []),
+        ...(repairResponse ? [repairResponse.id] : []),
+        ...validationEvents.map((event) => event.id),
+        ...reviewResponses.map((event) => event.id),
+        ...(completion ? [completion.id] : [])
+    ]);
+    const status = trailStatus({
+        nextPacket,
+        delegation,
+        repairResponse,
+        validationEvents,
+        reviewResponses,
+        completion,
+        run
+    });
+    const active = !nextPacket && !["reviewed", "superseded"].includes(status);
+    return {
+        id: `revision-trail-${packetEvent.id}`,
+        status,
+        active,
+        packetArtifactRef: artifactRef,
+        ...(sourceRole ? { sourceRole } : {}),
+        ...(reasonCode ? { reasonCode } : {}),
+        ...(repairObjective ? { repairObjective } : {}),
+        ...(sourceResponseRef ? { sourceResponseRef } : {}),
+        ...(criticTriggerRef ? { criticTriggerRef } : {}),
+        ...(repairResponseRef ? { repairResponseRef } : {}),
+        ...(completion ? { completedEventRef: completion.id } : {}),
+        evidenceRefs,
+        validationArtifactRefs: validationRefs,
+        reviewResponseRefs,
+        artifactRefs,
+        eventRefs,
+        handoffRefs: handoff ? [handoff.id] : [],
+        sourceRefs: sourceRefs(run, [
+            packetEvent,
+            ...[delegation, repairResponse, completion].filter((event) => Boolean(event)),
+            ...validationEvents,
+            ...reviewResponses
+        ], artifactRefs)
+    };
+};
+export const deriveRevisionTrail = (run) => {
+    const packetEvents = run.events.filter((event) => packetArtifactRef(event));
+    const items = packetEvents
+        .map((event, index) => itemForPacket(run, event, packetEvents[index + 1]))
+        .filter((item) => Boolean(item));
+    const latest = items.at(-1);
+    return {
+        schemaVersion: 1,
+        kind: "revision_trail",
+        runId: run.runId,
+        generatedAt: nowIso(),
+        phase: run.state,
+        items,
+        ...(latest ? { latest } : {})
+    };
+};
+//# sourceMappingURL=revisionTrail.js.map

package/dist/runtime/revisionTrail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revisionTrail.js","sourceRoot":"","sources":["../../src/runtime/revisionTrail.ts"],"names":[],"mappings":"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"}

package/dist/runtime/role-assignment.d.ts

@@ -0,0 +1,4 @@
+import { type RoleAssignment, type RuntimeRole } from "./types.js";
+export declare const parseRole: (value: string) => RuntimeRole;
+export declare const parseRoleAssignment: (value: string) => RoleAssignment;
+export declare const formatRoleAssignment: (assignment: RoleAssignment) => string;

package/dist/runtime/role-assignment.js

@@ -0,0 +1,21 @@
+import { InputError } from "./errors.js";
+import { runtimeRoles } from "./types.js";
+const roleSet = new Set(runtimeRoles);
+export const parseRole = (value) => {
+    if (roleSet.has(value)) {
+        return value;
+    }
+    throw new InputError(`Unknown role "${value}". Expected one of: ${runtimeRoles.join(", ")}.`);
+};
+export const parseRoleAssignment = (value) => {
+    const separatorIndex = value.indexOf(":");
+    if (separatorIndex <= 0 || separatorIndex === value.length - 1) {
+        throw new InputError(`Role assignment "${value}" must use provider:model format.`);
+    }
+    return {
+        provider: value.slice(0, separatorIndex),
+        model: value.slice(separatorIndex + 1)
+    };
+};
+export const formatRoleAssignment = (assignment) => `${assignment.provider}:${assignment.model}`;
+//# sourceMappingURL=role-assignment.js.map

package/dist/runtime/role-assignment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-assignment.js","sourceRoot":"","sources":["../../src/runtime/role-assignment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAyC,MAAM,YAAY,CAAC;AAEjF,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,YAAY,CAAC,CAAC;AAE9C,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAa,EAAe,EAAE;IACtD,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,KAAoB,CAAC;IAC9B,CAAC;IAED,MAAM,IAAI,UAAU,CAClB,iBAAiB,KAAK,uBAAuB,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACxE,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,KAAa,EAAkB,EAAE;IACnE,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAE1C,IAAI,cAAc,IAAI,CAAC,IAAI,cAAc,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/D,MAAM,IAAI,UAAU,CAAC,oBAAoB,KAAK,mCAAmC,CAAC,CAAC;IACrF,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC;QACxC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,cAAc,GAAG,CAAC,CAAC;KACvC,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,UAA0B,EAAU,EAAE,CACzE,GAAG,UAAU,CAAC,QAAQ,IAAI,UAAU,CAAC,KAAK,EAAE,CAAC"}

package/dist/runtime/roleRoster.d.ts

@@ -0,0 +1,28 @@
+import { type RoleAssignment, type RuntimeRole, type TheHoodConfig } from "./types.js";
+import type { RuntimeHealthReport } from "./doctor.js";
+export type RoleRosterState = "ready" | "needs_attention" | "unassigned";
+export type RoleRosterAssignmentSource = "product_default" | "repo_config" | "unassigned";
+export interface RoleRosterItem {
+    role: RuntimeRole;
+    laneLabel: string;
+    responsibility: string;
+    authority: string;
+    assignment?: RoleAssignment;
+    assignmentLabel: string;
+    defaultAssignmentLabel?: string;
+    assignmentSource: RoleRosterAssignmentSource;
+    state: RoleRosterState;
+    issues: string[];
+    readOnly: boolean;
+    permissions: {
+        read: boolean;
+        edit: boolean;
+        shell: boolean;
+        network: boolean;
+    };
+    providerEnabled?: boolean;
+    providerImplemented?: boolean;
+    modelConfigured?: boolean;
+    commandFound?: boolean;
+}
+export declare const buildRoleRoster: (config: TheHoodConfig, health?: RuntimeHealthReport) => RoleRosterItem[];

package/dist/runtime/roleRoster.js

@@ -0,0 +1,96 @@
+import { defaultRoles } from "./defaults.js";
+import { defaultRolePermissions } from "./permissions.js";
+import { formatRoleAssignment } from "./role-assignment.js";
+import { runtimeRoles } from "./types.js";
+const roleMetadata = {
+    orchestrator: {
+        laneLabel: "Agent 1 / Orchestrator",
+        responsibility: "Plans, delegates, compares evidence, and decides the next loop step.",
+        authority: "Strategy owner; no direct edit or final acceptance authority."
+    },
+    planner: {
+        laneLabel: "Agent 1A / Planner",
+        responsibility: "Creates implementation plans, risks, and acceptance criteria.",
+        authority: "Read-only planning lane; advisory until runtime evidence exists."
+    },
+    researcher: {
+        laneLabel: "Agent 1B / Researcher",
+        responsibility: "Inspects repo, docs, logs, and bounded external references.",
+        authority: "Read-only evidence lane; cannot change run state by itself."
+    },
+    implementer: {
+        laneLabel: "Agent 2 / Implementer",
+        responsibility: "Makes scoped code changes in an isolated worker path when possible.",
+        authority: "Edit-capable worker; cannot apply its own patch or self-verify."
+    },
+    qa: {
+        laneLabel: "Agent 3 / QA Tester",
+        responsibility: "Finds missed cases and recommends deterministic validation.",
+        authority: "Read-only advisory QA; cannot satisfy runtime validation gates."
+    },
+    verifier: {
+        laneLabel: "Agent 4 / Verifier",
+        responsibility: "Reviews runtime evidence against acceptance criteria.",
+        authority: "Required independent review lane; cannot edit."
+    },
+    critic: {
+        laneLabel: "Agent 5 / Critic",
+        responsibility: "Challenges risks, missing cases, and design assumptions.",
+        authority: "Read-only advisory review; cannot approve completion."
+    },
+    integrator: {
+        laneLabel: "Runtime / Integrator",
+        responsibility: "Applies approved patches and captures integration evidence.",
+        authority: "Deterministic runtime lane; not a general model agent."
+    },
+    citation: {
+        laneLabel: "Agent 6 / Citation",
+        responsibility: "Checks evidence, attribution, and provenance.",
+        authority: "Read-only citation lane; cannot satisfy verifier gates."
+    }
+};
+const sameAssignment = (left, right) => Boolean(left && right && left.provider === right.provider && left.model === right.model);
+const roleHealthByRole = (health) => new Map((health?.roles ?? []).map((roleHealth) => [roleHealth.role, roleHealth]));
+const assignmentSource = (role, assignment) => {
+    if (!assignment) {
+        return "unassigned";
+    }
+    return sameAssignment(assignment, defaultRoles[role]) ? "product_default" : "repo_config";
+};
+const roleState = (assignment, issues) => {
+    if (!assignment) {
+        return "unassigned";
+    }
+    return issues.length > 0 ? "needs_attention" : "ready";
+};
+export const buildRoleRoster = (config, health) => {
+    const healthByRole = roleHealthByRole(health);
+    return runtimeRoles.map((role) => {
+        const assignment = config.roles[role];
+        const defaultAssignment = defaultRoles[role];
+        const roleHealth = healthByRole.get(role);
+        const issues = roleHealth?.issues ?? [];
+        const permissions = defaultRolePermissions[role];
+        return {
+            role,
+            ...roleMetadata[role],
+            ...(assignment ? { assignment } : {}),
+            assignmentLabel: assignment ? formatRoleAssignment(assignment) : "unassigned",
+            ...(defaultAssignment ? { defaultAssignmentLabel: formatRoleAssignment(defaultAssignment) } : {}),
+            assignmentSource: assignmentSource(role, assignment),
+            state: roleState(assignment, issues),
+            issues,
+            readOnly: !permissions.edit,
+            permissions: { ...permissions },
+            ...(roleHealth
+                ? {
+                    providerEnabled: roleHealth.providerEnabled,
+                    providerImplemented: roleHealth.providerImplemented,
+                    modelConfigured: roleHealth.modelConfigured,
+                    ...(roleHealth.commandFound === undefined ? {} : { commandFound: roleHealth.commandFound })
+                }
+                : {})
+        };
+    });
+};
+//# sourceMappingURL=roleRoster.js.map

package/dist/runtime/roleRoster.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roleRoster.js","sourceRoot":"","sources":["../../src/runtime/roleRoster.ts"],"names":[],"mappings":"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"}

package/dist/runtime/runInsights.d.ts

@@ -0,0 +1,121 @@
+import { agentMarkdownField } from "../providers/markdownPayload.js";
+import { type RunHandoffSummary } from "./handoffs.js";
+import type { AgentResponse } from "../providers/types.js";
+import type { AutopilotApproval } from "./approvalInbox.js";
+import type { CrewLaneTrail, JsonObject, LoopResponsibilitySchedule, OperatorNextAction, ReviewLane, RevisionTrail, RunArtifact, RunRecord } from "./types.js";
+export interface RunArtifactSummary {
+    kind: RunArtifact["kind"];
+    ref: string;
+    summary: string;
+}
+export interface LatestAgentResponseInsight {
+    artifact: RunArtifactSummary;
+    status: AgentResponse["status"];
+    summary: string;
+    data: JsonObject;
+    primaryOutputKey?: string;
+    primaryOutput?: JsonObject;
+    markdown?: LatestAgentResponseMarkdownInsight;
+    decision?: JsonObject;
+}
+export interface LatestAgentResponseMarkdownInsight {
+    field: typeof agentMarkdownField;
+    preview: string;
+    truncated: boolean;
+    charLength: number;
+}
+export interface FinalReportInsight {
+    artifact: RunArtifactSummary;
+    completedBy?: JsonObject;
+    stopReason?: string;
+}
+export interface CriticTriggerInsight {
+    artifact: RunArtifactSummary;
+    reasonCode?: string;
+    reason?: string;
+    sourceRoles: string[];
+    evidenceRefs: string[];
+    criticResponseRef?: string;
+}
+export interface RevisionPacketInsight {
+    artifact: RunArtifactSummary;
+    sourceRole?: string;
+    reasonCode?: string;
+    reason?: string;
+    repairObjective?: string;
+    acceptanceCriteria: string[];
+    evidenceRefs: string[];
+    sourceResponseRef?: string;
+    criticTriggerRef?: string;
+}
+export interface ReviewRoutingInsight {
+    artifact: RunArtifactSummary;
+    riskTier?: string;
+    action?: string;
+    required?: JsonObject;
+    reasons: string[];
+    signals?: JsonObject;
+}
+export interface ProviderExecutionInsight {
+    artifact: RunArtifactSummary;
+    role?: string;
+    provider?: string;
+    model?: string;
+    command?: string;
+    args: string[];
+    commandMode?: string;
+    workspaceMode?: string;
+    sandbox?: string;
+    permissionMode?: string;
+    exitCode?: number;
+    timedOut?: boolean;
+    durationMs?: number;
+    stdoutRef?: string;
+    stderrRef?: string;
+    responseParsed?: boolean;
+    responseStatus?: string;
+}
+export interface FanoutInsight {
+    artifact: RunArtifactSummary;
+    status?: string;
+    requestedItems?: number;
+    executedItems?: number;
+    maxItems?: number;
+    sidecarOnly: boolean;
+    canSatisfyRequiredGates: boolean;
+    items: FanoutItemInsight[];
+}
+export interface FanoutItemInsight {
+    index: number;
+    role?: string;
+    summonKind?: string;
+    status?: string;
+    responseArtifactRef?: string;
+    directiveArtifactRef?: string;
+}
+export interface RunInsights {
+    latestAgentResponse?: LatestAgentResponseInsight;
+    finalReport?: FinalReportInsight;
+    latestCriticTrigger?: CriticTriggerInsight;
+    latestRevisionPacket?: RevisionPacketInsight;
+    latestReviewRouting?: ReviewRoutingInsight;
+    latestProviderExecution?: ProviderExecutionInsight;
+    recentProviderExecutions: ProviderExecutionInsight[];
+    latestFanout?: FanoutInsight;
+    latestProgressPacket?: RunArtifactSummary;
+    latestReconciliation?: RunArtifactSummary;
+    latestRepoContext?: RunArtifactSummary;
+    latestRemoteRepoContext?: RunArtifactSummary;
+    latestTransferManifest?: RunArtifactSummary;
+    canonicalMemory?: JsonObject;
+    crewLanes: CrewLaneTrail;
+    revisionTrail: RevisionTrail;
+    loopResponsibilities: LoopResponsibilitySchedule;
+    reviewLanes: ReviewLane[];
+    operatorNextActions: OperatorNextAction[];
+    latestHandoff?: RunHandoffSummary;
+    handoffTimeline: RunHandoffSummary[];
+    recentAutopilotApprovals: AutopilotApproval[];
+    issues: string[];
+}
+export declare const getRunInsights: (run: RunRecord) => Promise<RunInsights>;